速率限制处理:构建能在 429 中存活的 HTTP 客户端
速率限制处理:构建能在 429 中存活的 HTTP 客户端
背景与动机
任何成熟的上游 API 都会施加速率限制。你迟早会收到一个 HTTP 429 Too Many Requests 响应(由 RFC 6585 定义),而你在那之后的处理方式决定了你的代码是脆弱脚本还是稳健服务。最朴素的直觉 —— 立即重试,失败就更密集地重试 —— 恰恰是把一次短暂限流延长为多分钟停机的元凶。AWS Builders’ Library 关于重试与退避的文章(Brooker, AWS Builder Center)对这条原则有一句精炼总结:“重试是自私的。” 每次重试都在消耗服务端的资源,只为提高单个客户端的成功率。少量精准的重试能吸收瞬态故障;成千上万次协同重试只会放大故障。
因此一套深思熟虑的速率限制处理策略有两个动机。其一,保护上游:避免成为触发"惊群效应"的那个客户端 —— 大量调用方退避到同一钟表时刻后再次撞击同一限制。其二,保护自身:把一个可预测的错误清晰地冒泡给应用层,而不是默默烧光令牌配额、挂起连接或让延迟漂移。本文给出一条分层路径 —— 退避 → 令牌桶 → 代理 —— 你可以随流量增长逐层叠加。
前置条件
动手实现之前,请先对齐几个基础约定:
- 一个可用的 HTTP 客户端。示例使用 Python +
httpx,但模式可直接迁移到 Go、Rust、TypeScript 等任意语言。 - 具备读取并遵从
Retry-After响应头的能力 —— 这是行为规范的服务端返回的最常被忽视的信号(Retry-After: 30表示秒,Retry-After: Thu, 01 Jan 2026 00:00:00 GMT表示 HTTP 日期)。 - 一处重试日志出口。没有带时间戳的
attempt、delay、jitter记录,调试限流行为几乎等同于盲调。 - 对哪些 HTTP 状态可重试有清晰认知。429 与 503 是限流/瞬态信号。除此之外的 4xx(401、403、404、422)几乎从不应该重试 —— 重试它们只是在徒耗请求配额。
来源:Speakeasy《Rate Limiting Best Practices in REST API Design》强调,服务端返回 429 并附带
Retry-After头才是正确做法,因为它*“明确告诉客户端应当退避一段时间”,并“避免让客户端猜测何时该再次尝试”*。
步骤一:准备工作
先把几个常量固化下来,它们会出现在设计的每一层:
# rate_limit_config.py
from dataclasses import dataclass
@dataclass(frozen=True)
class ClientPolicy:
max_retries: int # 5 — 含首次在内最多尝试次数
base_delay: float # 1.0 秒,首次退避基线
max_delay: float # 60.0 秒,上限(封顶指数退避)
jitter_fraction: float # 0.5 — 抖动覆盖计算延迟的 50%~100%
retry_statuses: tuple # (429, 503) — 仅对这两个状态重试
DEFAULT = ClientPolicy(
max_retries=5,
base_delay=1.0,
max_delay=60.0,
jitter_fraction=0.5,
retry_statuses=(429, 503),
)max_delay 上限即 AWS Builders’ Library 所称的封顶指数退避:指数函数增长过快,若无封顶,单是第 8 次重试就要等四分钟。封顶必须与 max_retries 配对使用,否则客户端永远不放弃,会把上游故障隐藏在无限重试背后,让调用方迟迟拿不到错误。
步骤二:核心实现
第一层 —— 带抖动的指数退避
每位资深工程师都应当烂熟于心的基础。伪数学表达为 wait = min(base * 2**attempt, max_delay) * (1 - random()*jitter_fraction)。抖动项绝非可选:没有它,所有在同一时刻触发限流的客户端都会在同一时刻重试 —— 这就是惊群效应。
# backoff_client.py
import asyncio
import email.utils
import random
from datetime import datetime, timezone
import httpx
from rate_limit_config import ClientPolicy, DEFAULT
def parse_retry_after(value: str | None, now: datetime) -> float:
"""Retry-After 可能是秒数,也可能是 HTTP 日期。"""
if not value:
return float("nan")
if value.strip().isdigit():
return float(value)
try:
dt = email.utils.parsedate_to_datetime(value)
return max(0.0, (dt - now).total_seconds())
except (TypeError, ValueError):
return float("nan")
async def request_with_backoff(
client: httpx.AsyncClient,
method: str,
url: str,
*,
policy: ClientPolicy = DEFAULT,
**kwargs,
) -> httpx.Response:
"""对可重试状态执行带指数退避的 HTTP 请求。"""
for attempt in range(policy.max_retries + 1):
response = await client.request(method, url, **kwargs)
if response.status_code not in policy.retry_statuses:
return response # 成功或非可重试错误
if attempt == policy.max_retries:
response.raise_for_status() # 最后一次尝试 — 抛出 429/503
# 优先采用服务端提示;否则退回计算的指数延迟
server_hint = parse_retry_after(
response.headers.get("Retry-After"),
datetime.now(timezone.utc),
)
base = server_hint if not (server_hint != server_hint) else \
min(policy.base_delay * (2 ** attempt), policy.max_delay)
jitter = base * (1 - random.random() * policy.jitter_fraction)
print(f"重试 {attempt + 1}/{policy.max_retries},等待 {jitter:.2f}s")
await asyncio.sleep(jitter)
return response # 防御性返回,理论不可达两个值得为之付出的实现细节:
- 优先遵从
Retry-After。 服务端发此头就是在告诉你精确的等待时长;自己计算延迟纯属在错误的时刻瞎猜。Speakeasy 的文章里写得很直接:“忽略这个头部意味着你在应当精确的地方却在猜测。” - 抖动用乘数而非加性常数。 当基础延迟已经 32 秒时,±200 毫秒的常数抖动毫无意义。让抖动随延迟按比例缩放(
0.5~1.0 × base)能在整条退避曲线上保持有效散布 —— 这与 Exponential Backoff and Jitter 一文的建议一致。
第二层 —— 客户端令牌桶
仅靠退避会任由客户端一路把请求砸到上游直到收到 429。客户端侧的令牌桶让你在请求离开进程之前就先进行自我节流 —— 这比网络往返更廉价,也为真正的需求让出上游预算。令牌桶按配置速率补充令牌,耗尽时阻塞或拒绝请求。
# token_bucket.py
import asyncio
import time
from dataclasses import dataclass, field
@dataclass
class TokenBucket:
capacity: int # 例如 100 — 突发上限
refill_per_sec: float # 例如 10.0 — 稳态速率
_tokens: float = field(init=False)
_last_refill: float = field(init=False)
_lock: asyncio.Lock = field(default_factory=asyncio.Lock, init=False)
def __post_init__(self) -> None:
self._tokens = float(self.capacity)
self._last_refill = time.monotonic()
def _refill(self) -> None:
now = time.monotonic()
self._tokens = min(
self.capacity,
self._tokens + (now - self._last_refill) * self.refill_per_sec,
)
self._last_refill = now
async def acquire(self, timeout: float = 30.0) -> bool:
deadline = time.monotonic() + timeout
while True:
async with self._lock:
self._refill()
if self._tokens >= 1:
self._tokens -= 1
return True
if time.monotonic() >= deadline:
return False
await asyncio.sleep(0.05)把两层组合使用:请求前先从桶里取走令牌,服务端仍回 429 时再触发退避。两层解决的是不同的失效模式 —— 桶主动平滑突发流量,退避响应服务端进行二次否决。
第三层 —— 内部速率限制代理
当多个服务调用同一个上游 API 时,每个服务独立的重试逻辑必然导致协同失效:每个服务都以为拥有完整速率配额,并最终同步重试、同步触发新一轮 429。Stanislav Lazarenko 的客户端 429 处理文章描述得很直白 —— 当服务们*“同时撞墙、同时退避、几乎同时重试,循环不止”*,正解是在各服务与外部 API 之间放一个内部代理服务。这个代理持有全局速率消耗视图,令牌耗尽时排队请求,并按公平策略在调用者之间调度。每个下游服务仍需保留"客户端侧感知"层,以在代理自身不可用时仍有退避兜底 —— 你不是在两层之间二选一,而是叠加。
步骤三:验证与调优
在真正用得上这些观测与护栏之前,先把它们建好。
- 每次重试都要打日志,包含
attempt、计算的delay、服务端返回的Retry-After与响应状态。没有这些数据,你无法判断退避究竟在工作,还是上游在默默对每次请求限流。 - 上指标计数器
rate_limit_retries_total{status="<429|503>"}。计数平稳上升说明客户端在自适应;发布后陡然飙升通常是配置收紧了限额。 - 按调用方 deadline 反推
max_retries。base=1, max=60时,5 次尝试最坏耗时1+2+4+8+16 ≈ 31s;若调用方超时只有 10s,你的客户端会被中途杀掉 —— 设max_retries=3并接受更高的失败率。 - 设置显式请求超时。 AWS Builders’ Library 的文章反复强调:每一次远程调用都应有连接、请求、DNS/TLS 握手全覆盖的超时。一条挂起的连接在功能上等同于 429,只是检测成本更高。
- 在开启重试前先验证幂等性。 退避只在幂等端点上安全。对于非幂等写入(支付、资源创建),要么使用幂等键,要么把重试上移到能识别重复的更高层。
- 对代理做混沌演练。 第三层若是单点故障,必须能够故障切换。向代理路径注入 200 ms 延迟,确认第一层仍能绕开它。
最佳实践小结
- 只要服务端给了
Retry-After就要遵从。 这是其精确提示;忽略它意味着在最不该猜测的时刻去猜测。 - 抖动不是可选项。 没有抖动,退避后的客户端会让重试同步,再度触发限流。抖动要随延迟按比例缩放,不要用加性常数。
- 同时给延迟与重试次数封顶。 封顶指数退避若不配套重试上限,就退化为近乎无限的等待;重试无封顶则向上游施加指数级的负载放大。
- 在请求发出之前就加一层客户端令牌桶。 主动自我节流比被动 429 廉价得多,还能把上游预算留给真正的需求。
- 多个服务共享同一上游时引入内部代理。 它集中速率统计,使公平调度成为可能,避免每个服务都误以为独占完整配额。
参考资料
- Timeouts, retries, and backoff with jitter — AWS Builder Center (Marc Brooker)
- Handling HTTP 429 (Too Many Requests) on the client side — Stanislav Lazarenko
- Rate Limiting Best Practices in REST API Design — Speakeasy
- How to Handle API Rate Limiting and Implement Exponential Backoff in GCP — OneUptime
- RFC 6585 — Additional HTTP Status Codes (§4: 429 Too Many Requests)
- Exponential Backoff and Jitter — AWS Architecture Blog