Python requests 超时与重试设置方法

Python requests库默认既不设超时也不自动重试，若不手动配置，请求可能无限挂起或失败后直接放弃，严重损害程序稳定性；本文详解如何通过元组形式的timeout参数精准分离连接与读取超时，并借助urllib3的Retry策略为Session注入智能重试机制——仅对5xx、429等临时性错误生效，支持指数退避、方法白名单和状态码定制，再结合实际场景给出connect/read超时推荐值、重试次数与退避因子的最佳搭配，同时提醒SSL握手、代理、重定向等易被忽略的边界问题，助你构建真正健壮、可控、生产就绪的HTTP客户端。

Python requests 库默认不启用自动重试，超时也需手动设置；不配置的话，请求可能无限等待或失败后不重试，影响程序健壮性。

超时设置：分连接与读取两阶段

requests 的 timeout 参数接受数字或元组。单个数字表示连接+读取总超时；更推荐用元组 (connect_timeout, read_timeout) 分开控制：

• connect_timeout：建立 TCP 连接的最长时间，网络不通、DNS 失败时触发
• read_timeout：成功连接后，等待服务器响应首字节的最长时间（不是整个响应体）

例如：requests.get(url, timeout=(3, 10)) 表示最多等 3 秒连上，连上后再等最多 10 秒收第一个字节。若响应体大且流式下载，还需配合 stream=True 和分块读取，避免卡在 read 阶段。

重试机制：用 urllib3 的 Retry 类

requests 底层基于 urllib3，可通过 HTTPAdapter 注入自定义重试策略。关键点：

• 重试只对特定状态码（如 5xx、429）和网络错误生效，不会重试 4xx（如 404、400）
• 可指定最大重试次数、退避因子（指数退避）、重试的 HTTP 方法
• 需为 session 或单个 request 显式挂载 adapter

示例代码：

from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retry_strategy = Retry(
    total=3,
    status_forcelist=[429, 500, 502, 503, 504],
    method_whitelist=["HEAD", "GET", "OPTIONS", "POST"],
    backoff_factor=1
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session = requests.Session()
session.mount("http://", adapter)
session.mount("https://", adapter)

response = session.get("https://api.example.com/data")

组合超时与重试的最佳实践

两者应协同使用，避免重试浪费时间或陷入长等待：

• connect timeout 设为 3–5 秒，防止 DNS 慢或目标不可达时卡住
• read timeout 根据接口预期响应时间设定，一般 5–30 秒；流式接口可设更低，靠循环读取控制
• 重试次数建议 2–3 次，配合 backoff_factor=1（即第 1 次重试前等 1 秒，第 2 次等 2 秒，第 3 次等 4 秒）
• 对 POST/PUT 等非幂等请求，谨慎开启重试，或改用带业务幂等性的方案

注意边界情况

有些问题无法靠超时和重试解决：

• SSL 握手超时：属于 connect 阶段，但有时会表现异常，可加 verify=False（仅测试）或更新 CA 证书
• 代理超时：若走代理，超时可能由代理服务控制，需同步配置代理端
• 重定向循环：默认最多重定向 30 次，可通过 allow_redirects=True 和 max_redirects 调整，但不属 Retry 控制范围

本篇关于《Python requests 超时与重试设置方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！