先说结论: requests 默认不重试。要重试,给 HTTPAdapter 传一个 urllib3 的 Retry 对象,挂到 Session 上。有五件事最容易配错或误解:
backoff_factor × 2^(n-1) 增长。backoff_factor=0.5 时,各次重试前的等待依次是 0、1、2、4 秒,上限默认 120 秒;status_forcelist 的状态码才会重试;allowed_methods 的默认值里没有 POST 和 PATCH,因为它们不是幂等的;Retry-After 默认会被遵守:413、429、503 带了这个头时,按它说的时间等;RetryError,连接类的失败抛 ConnectionError;设 raise_on_status=False 则返回最后一次的响应。下面在本地用一个按路径模拟各种失败的服务端,把这几点逐个跑一遍。环境:Python 3.12、requests 2.34.2、urllib3 2.8.0。
服务端打印每个请求到达的相对时间,这样可以直接从日志里算出每次重试之间等了多久。
# flaky.py
import time
from collections import Counter
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
T0 = time.monotonic()
hits = Counter()
class H(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"
def reply(self, code, extra=None):
body = f"{code}\n".encode()
self.send_response(code)
for k, v in (extra or {}).items():
self.send_header(k, v)
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def handle_any(self):
if self.command == "POST":
self.rfile.read(int(self.headers.get("Content-Length", 0)))
hits[self.path] += 1
n = hits[self.path]
print(f"[server] {time.monotonic() - T0:6.2f}s {self.command} {self.path} 第{n}次", flush=True)
if self.path == "/flaky": # 前 3 次 503,第 4 次成功
self.reply(503 if n <= 3 else 200)
elif self.path == "/always503":
self.reply(503)
elif self.path == "/retry-after": # 第 1 次 503,并要求 2 秒后再来
self.reply(503, {"Retry-After": "2"}) if n == 1 else self.reply(200)
elif self.path == "/post-flaky": # 第 1 次 503,之后成功
self.reply(503 if n == 1 else 200)
elif self.path == "/notfound":
self.reply(404)
do_GET = do_POST = handle_any
def log_message(self, *a): pass
ThreadingHTTPServer(("127.0.0.1", 18103), H).serve_forever()import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry
retry = Retry(
total=4, # 最多重试 4 次(不含第一次请求)
backoff_factor=0.5, # 退避:0、1、2、4 秒
status_forcelist=[500, 502, 503, 504], # 这些状态码也重试
allowed_methods=Retry.DEFAULT_ALLOWED_METHODS, # 默认值,写出来是为了醒目:不含 POST
)
s = requests.Session()
adapter = HTTPAdapter(max_retries=retry)
s.mount("http://", adapter)
s.mount("https://", adapter)s.mount 按网址前缀匹配,http 和 https 两个前缀要分别挂,只挂一个的话另一类请求不会重试。
GET /flaky: HTTP 200,3.0s
[server] 1.07s GET /flaky 第1次
[server] 1.07s GET /flaky 第2次
[server] 2.09s GET /flaky 第3次
[server] 4.09s GET /flaky 第4次第 1 次 503 后立刻重试,间隔 0;第 2 次 503 后等了 1 秒;第 3 次后等了 2 秒;第 4 次成功。调用方只看到一个 200,总耗时 3 秒。
退避时间的计算在 urllib3 的 Retry.get_backoff_time() 里:只统计最近一段连续的失败次数 n,n 小于等于 1 时返回 0,否则返回 backoff_factor * 2 ** (n - 1),再和 backoff_max(默认 120 秒)取较小值。如果你看的是旧资料,会发现公式描述不完全一样,以自己安装版本的源码为准。
多个客户端同时失败、又按同样的节奏重试,会在同一时刻一起打到服务端上。urllib3 2.x 提供了 backoff_jitter 参数,在退避时间上加一个随机量,把重试打散:
Retry(total=4, backoff_factor=0.5, backoff_jitter=0.3, status_forcelist=[502, 503, 504])GET /always503: RetryError: HTTPConnectionPool(host='127.0.0.1', port=18103): Max retries exceeded with url: /always503 (Caused by ResponseError('too many 503 error responses')),7.0s
[server] 4.18s GET /always503 第1次
[server] 4.18s GET /always503 第2次
[server] 5.19s GET /always503 第3次
[server] 7.20s GET /always503 第4次
[server] 11.20s GET /always503 第5次1 次请求 + 4 次重试,共 5 次,等待 0 + 1 + 2 + 4 = 7 秒,最后抛出 requests.exceptions.RetryError。注意这不是 HTTPError,原来写的 except requests.HTTPError 接不住它。
如果你希望重试用完后拿到最后一次的响应自己处理,而不是异常:
Retry(total=4, backoff_factor=0.5, status_forcelist=[503], raise_on_status=False)GET /always503 raise_on_status=False: 503 7.0s同样等了 7 秒,返回的是一个普通的 503 响应,可以照常读取状态码和响应体。
GET /retry-after: HTTP 200,2.0s
[server] 11.29s GET /retry-after 第1次
[server] 13.30s GET /retry-after 第2次按退避公式,第一次重试本应立即发生,实际却等了 2 秒,因为响应里带了 Retry-After: 2。respect_retry_after_header 默认为 True,作用于 RETRY_AFTER_STATUS_CODES,即 413、429、503 三个状态码。
这一点要特别注意:如果服务端回了 Retry-After: 3600,客户端就会真的等一个小时。 线程被占住,调用方以为程序卡死了。对外部接口,可以考虑:
respect_retry_after_header=False,完全由自己的退避控制;还要注意 backoff_max 只限制退避时间,不限制 Retry-After 给出的等待时间。
POST /post-flaky: HTTP 503,0.0s
[server] 13.39s POST /post-flaky 第1次服务端只收到 1 次请求,客户端直接拿到了 503。默认的 allowed_methods 是:
frozenset(["HEAD", "GET", "PUT", "DELETE", "OPTIONS", "TRACE"])POST 和 PATCH 不在里面。原因很简单:服务端回 503 时,你无法确定它是「没处理」还是「处理到一半出错」。对下单、扣款、发消息这类操作,自动重发可能造成重复执行。
确实要让 POST 也重试,可以把 allowed_methods 设为 None(表示所有方法都重试)或者显式加上 POST:
POST allowed_methods=None: 200 0.0s
[server] 1.07s POST /post-flaky 第1次
[server] 1.07s POST /post-flaky 第2次这样做的前提是接口本身是幂等的,最好由服务端支持幂等键:客户端为每个业务操作生成一个唯一 ID 放在请求头里,服务端发现同一个 ID 已经处理过,就直接返回上次的结果。
GET /notfound: HTTP 404,0.0s
GET 没监听的端口: ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=18105): Max retries exceeded with url: / (Caused by NewConnectionError("HTTPConnection(host='127.0.0.1', port=18105): Failed to establish a new connection: [Errno 61] Connection refused")),7.0s404 不在 status_forcelist 里,直接返回,不重试。这是对的,404 重试多少次都是 404。同理,400、401、403 也不应该放进去。
连接被拒绝时,这次真的重试了 4 次,同样按 0、1、2、4 秒退避,7 秒后抛出 ConnectionError。连接类错误受 connect 参数和 total 共同限制,total 用完就停。如果你想区分「连不上」和「服务端报错」的重试次数,可以分别设置:
Retry(total=None, connect=3, read=1, status=4, backoff_factor=0.5,
status_forcelist=[502, 503, 504])read 控制的是「请求已经发出、读取响应时出错」的重试。对非幂等请求,这种情况下服务端很可能已经处理过了,read 设小一点或设为 0 更安全。
import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry
def make_session():
retry = Retry(
total=4,
connect=3,
read=1,
status=3,
backoff_factor=0.5,
backoff_jitter=0.3,
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=Retry.DEFAULT_ALLOWED_METHODS,
respect_retry_after_header=True,
raise_on_status=False,
)
adapter = HTTPAdapter(max_retries=retry)
s = requests.Session()
s.mount("http://", adapter)
s.mount("https://", adapter)
return s
session = make_session()
resp = session.get("https://example.com/api", timeout=(3.05, 10))再强调一次:重试不能代替超时。 每次尝试都要有自己的 timeout,否则一次卡住的读取就会让后面的重试永远没有机会执行。
参数 | 默认值 | 作用 |
|---|---|---|
total | 10(requests 默认不重试,是因为它传的是 0) | 所有重试次数的总上限 |
connect / read / status | None(只受 total 限制) | 分别限制各类错误的重试次数 |
backoff_factor | 0 | 退避基数,0 表示不等待 |
backoff_max | 120 | 单次退避上限(秒) |
backoff_jitter | 0.0 | 随机附加的等待时间上限 |
status_forcelist | None | 哪些状态码要重试 |
allowed_methods | 不含 POST、PATCH | 哪些方法可以重试 |
respect_retry_after_header | True | 是否遵守 413/429/503 的 Retry-After |
raise_on_status | True | 用完后抛 RetryError 还是返回最后的响应 |
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。