跳至内容

速率限制处理:构建能在 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  # 防御性返回,理论不可达

两个值得为之付出的实现细节:

  1. 优先遵从 Retry-After。 服务端发此头就是在告诉你精确的等待时长;自己计算延迟纯属在错误的时刻瞎猜。Speakeasy 的文章里写得很直接:“忽略这个头部意味着你在应当精确的地方却在猜测。”
  2. 抖动用乘数而非加性常数。 当基础延迟已经 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 廉价得多,还能把上游预算留给真正的需求。
  • 多个服务共享同一上游时引入内部代理。 它集中速率统计,使公平调度成为可能,避免每个服务都误以为独占完整配额。

参考资料