# 同步任务跑得太快，第一周 API 密钥就可能遭停用

> FDE 常站在限流的两端：几十行 Python，既能在收到 429 时退避，也能给自己的 API 设上限。

原文: https://fdetimes.net/zh/guides/api-rate-limiting-429-retry-after-token-bucket/

这个同步任务要处理 3,000 条记录，跑得很快。正因为快，客户的 ERP 系统整夜报错；第二天早上，客户的 IT 团队发来邮件：API 密钥已暂停，任务修好之前不会恢复。这是一个假设的驻场第一周，但对前线部署工程师（FDE）来说，真碰上一点也不难。

FDE 通常夹在两个系统之间：一边调用客户自有的 API，一边对外暴露自己的 API，供客户系统调用。前一个方向上，你得做个守规矩的客户端；后一个方向上，你得设好自己的限额，免得一个出故障的客户端就把服务拖垮。

本指南覆盖这两个方向。先写一个能识别 429 信号并主动减速的客户端，再写一个挡在自己 API 前面的简单限流器。代码是示意级的 Python，为便于阅读做了精简，只用标准库。你需要 Python 3、一个终端，以及一个可供测试的真实或模拟 API。

## 限流到底在保护什么？

MDN 对限流的定义是：控制一段时间内执行的操作数量，主要目的是防止系统过载、变慢。服务器可以限制某个客户端在一定时间内能发来的请求数，既为保证性能，也为缓解 DoS 等攻击。

限额通常按客户端 IP 计算。如果请求经过认证或带有 cookie，也可能按用户或按应用计算。放到客户现场，这意味着共用一个 API 密钥的所有任务也共用同一份配额，你的同步任务可能正在挤占另一个内部应用的额度。

先做一道简单的算术。假设客户的 API 每秒允许 10 个请求，你要同步 3,000 条记录，每条一个请求。最短耗时就是 300 秒，也就是 5 分钟。任何想在 5 分钟内跑完的尝试，换来的只有报错。

## 第 1 步：正确读取 429 和 Retry-After 信号

HTTP 429 Too Many Requests 表示客户端在一定时间内发送的请求过多。这个限额可能针对整台服务器，也可能针对单个资源。服务器可以附带 Retry-After 头，告诉客户端要等多久再重试。

陷阱在于，Retry-After 有两种形式：一种是 HTTP 日期，另一种是表示等待秒数的非负整数。只处理其中一种的代码，一遇到用另一种形式的服务器就会出错。

```python
from email.utils import parsedate_to_datetime
from datetime import datetime, timezone

def retry_after_seconds(value):
    if value is None:
        return None
    value = value.strip()
    if value.isdigit():               # 秒数形式
        return int(value)
    try:                              # HTTP 日期形式
        when = parsedate_to_datetime(value)
        delta = (when - datetime.now(timezone.utc)).total_seconds()
        return max(0, delta)
    except (TypeError, ValueError):
        return None
```

**检查：**`retry_after_seconds("120")` 必须返回 120。传入几分钟后的 HTTP 日期，结果必须是正的秒数。传入乱码字符串，函数必须返回 `None`，而不是抛出异常。

## 第 2 步：服务器没说等多久时，带抖动重试

并不是每台服务器都会发 Retry-After。没有它时，常见做法是指数退避：每次重试的等待时间是上一次的两倍。AWS Architecture Blog 的一篇文章显示，在他们的模拟中，不加抖动的普通退避效果最差，因为同一时刻失败的大量客户端也会在同一时刻重试。

```python
import random, time

def backoff_delay(attempt, base=1, cap=60):
    return random.uniform(0, min(cap, base * 2 ** attempt))

def call_with_retry(send, max_attempts=5):
    for attempt in range(max_attempts):
        status, headers = send()      # send() 是你自己的占位函数
        if status != 429:
            return status
        wait = retry_after_seconds(headers.get("Retry-After"))
        time.sleep(wait if wait is not None else backoff_delay(attempt))
    raise RuntimeError("重试次数已用完")
```

**检查：**让一个假的 `send()` 先返回三次 429，再返回 200，把每次等待时间打印出来。这些时间应该是随机的、总体呈增长趋势，而不是每次运行都一模一样的 1、2、4。

## 第 3 步：别等到 429 才减速

重试是安全网，不是策略。好的客户端从一开始就给自己节流。MDN 区分了两个概念：节流（throttling）仍然允许操作执行，但只能以固定的最高速率执行；防抖（debouncing）则把间隔很近的多次调用合并为一次，等调用完全停下来才执行。

同步任务需要的是节流。防抖适合客户端搜索框这类场景。

Tyk 比较了几种常见算法：固定窗口简单，但容易受突发流量冲击；滑动日志精确，但耗内存；令牌桶能灵活应对突发。令牌桶就像一只桶：令牌以固定速率放入，每个请求取走一个，桶满时新令牌直接丢弃。

```python
class TokenBucket:
    def __init__(self, rate, capacity):
        self.rate, self.capacity = rate, capacity
        self.tokens = capacity
        self.last = time.monotonic()

    def take(self):
        now = time.monotonic()
        self.tokens = min(self.capacity,
                          self.tokens + (now - self.last) * self.rate)
        self.last = now
        if self.tokens >= 1:
            self.tokens -= 1
            return True
        return False

bucket = TokenBucket(rate=8, capacity=8)   # 比每秒 10 次的上限低 20%，留出余量
def throttled_send(send):
    while not bucket.take():
        time.sleep(0.05)
    return call_with_retry(send)
```

设成 8 而不是 10，是给共用这个密钥的其他应用留出空间。这是谨慎的选择，不是标准数值。**检查：**通过 `throttled_send` 发送 80 个请求，总耗时应在 9 秒左右，而不是接近零。

## 第 4 步：API 归你所有了，限流放在哪？

以每分钟 100 个请求的固定窗口为例。某个客户端在前一分钟的最后一秒发出 100 个请求，又在下一分钟的第一秒发出 100 个。两个窗口都没超限，后端却在大约 2 秒内承受了 200 个请求。换成容量较小的令牌桶，这种突发就过不去。

这只桶应该放在 API 网关里。IBM 把 API 网关描述为客户端访问众多后端服务的统一入口。限流是网关的职责，而不是负载均衡器的职责，因为正是在网关这一层，你可以防止任何单个客户端或 IP 压垮服务。

按 Tyk 的建议把限额放在这里，就能按 API 密钥、IP 或用户一致地执行策略。

在网关上，要把第 3 步用到的两种功能分开。限流为请求设定上限，拒绝超出的部分；节流则在流量激增时放慢、延迟请求或让请求排队。同样一只令牌桶，客户端用 `sleep` 排队，服务端则立即拒绝。

## 第 5 步：返回客户端能据此行动的 429

Tyk 指出，返回 429 是标准做法，同时还应附带 Retry-After、X-RateLimit-Limit 和 X-RateLimit-Remaining 等响应头。你的响应，正是第 1 步那个客户端需要读取的信号。下面的代码片段模拟了这段逻辑，每个 API 密钥一只桶。

```python
buckets = {}
LIMIT = 10

def check(api_key):
    b = buckets.setdefault(api_key, TokenBucket(rate=LIMIT, capacity=LIMIT))
    allowed = b.take()
    headers = {"X-RateLimit-Limit": str(LIMIT),
               "X-RateLimit-Remaining": str(int(b.tokens))}
    if not allowed:
        headers["Retry-After"] = "1"
        return 429, headers
    return 200, headers
```

这只是进程内的示意。在真实部署中，应按照客户现有网关产品的文档在网关上配置这条策略，而不是自己写。**检查：**连续调用 `check("key-a")` 15 次，应能看到大约 5 次 429，而 `check("key-b")` 仍然返回 200。

## 让集成密钥遭封的几个错误

一个常见错误是收到 429 立刻重试。这个状态码本来就是在说客户端请求太多，马上重试只会给已经过载的系统继续加压。第二个错误是只解析 Retry-After 的数字形式，结果任务第一次遇到日期形式，就在凌晨 2 点崩溃。

第三个错误更难发现：并行跑多个 worker，每个 worker 各有一只每秒 8 个请求的桶。五个 worker 加起来就是每秒 40 个请求，是上限的四倍。共用同一个密钥的所有 worker，必须共用同一只桶。

**要点:** 重试只能救火。真正保护客户系统的，是从第一个请求起就把速率控制在上限以下。

## 到了客户现场，先问三个问题

第一次和客户 IT 团队开会时，写代码之前先问三个问题：上限是多少；按密钥、IP 还是用户计算；还有哪些应用共用这个密钥。答案决定了你的 `rate` 参数。

有了这些，就能像上文算出 5 分钟那样，算出每个任务的最短耗时，并提前告知客户。

如果你瞄准的岗位描述里提到与客户系统集成，面试时就带上这个例子：配额算术、所有 worker 共用的桶，以及你如何读取 Retry-After。

客户很少记得你的任务跑得有多快。他们记得的是，整个项目期间，他们的系统从没因为你报过一次警。

**本周动手试试:**

- 在你的项目里找出调用外部 API 的代码，检查它是否读取 Retry-After。如果没有，加上本指南中的 retry_after_seconds 函数，并为两种取值形式编写单元测试。
- 用 rate=5、capacity=10 运行 TokenBucket，连续发出 30 个请求，数一数有多少被拒绝，亲眼看看突发流量是怎么处理的。
- 在简历上写一行，说明你如何让一个集成任务保持在 API 配额之内，附上具体数字：速率、记录数，以及修复前后的 429 次数。

## 信源

- [Rate limit - Glossary | MDN](https://developer.mozilla.org/en-US/docs/Glossary/Rate_limit)

- [Throttle - Glossary | MDN](https://developer.mozilla.org/en-US/docs/Glossary/Throttle)

- [Debounce - Glossary | MDN](https://developer.mozilla.org/en-US/docs/Glossary/Debounce)

- [429 Too Many Requests - HTTP | MDN](https://developer.mozilla.org/docs/Web/HTTP/Reference/Status/429)

- [Retry-After header - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After)

- [API rate limiting explained: From basics to best practices (Tyk)](https://tyk.io/learning-center/api-rate-limiting/)

- [What is an API gateway? (IBM)](https://www.ibm.com/blog/api-gateway/)

- [API gateway vs. Load balancer: Do you need one or both?](https://roadmap.sh/network-engineer/api-gateway-vs-load-balancer)

- [Exponential Backoff And Jitter (AWS Architecture Blog)](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
