同步任务跑得太快,第一周 API 密钥就可能遭停用
FDE 常站在限流的两端:几十行 Python,既能在收到 429 时退避,也能给自己的 API 设上限。
要点速览
- 调用客户的 API 时,先给自己节流,别撞上限;如果仍然收到 429,就按 Retry-After 等待。
- 在 AWS 的模拟中,不加抖动的重试表现最差,所以一定要加入随机间隔。
- API 归你所有时,在网关按 API 密钥限流,并返回 429 和能告诉客户端该怎么做的响应头。
这个同步任务要处理 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 日期,另一种是表示等待秒数的非负整数。只处理其中一种的代码,一遇到用另一种形式的服务器就会出错。
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 的一篇文章显示,在他们的模拟中,不加抖动的普通退避效果最差,因为同一时刻失败的大量客户端也会在同一时刻重试。
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 比较了几种常见算法:固定窗口简单,但容易受突发流量冲击;滑动日志精确,但耗内存;令牌桶能灵活应对突发。令牌桶就像一只桶:令牌以固定速率放入,每个请求取走一个,桶满时新令牌直接丢弃。
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 密钥一只桶。
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。
客户很少记得你的任务跑得有多快。他们记得的是,整个项目期间,他们的系统从没因为你报过一次警。
这篇文章对你有帮助吗?
感谢你的反馈!
9 个信源
- Rate limit - Glossary | MDN · 2025-07-11
- Throttle - Glossary | MDN · 2025-07-11
- Debounce - Glossary | MDN · 2025-07-11
- 429 Too Many Requests - HTTP | MDN · 2026-06-22
- Retry-After header - HTTP | MDN · 2025-11-21
- API rate limiting explained: From basics to best practices (Tyk) · 2023-02-03
- What is an API gateway? (IBM) · 2024-08-15
- API gateway vs. Load balancer: Do you need one or both?
- Exponential Backoff And Jitter (AWS Architecture Blog) · 2015-03-04