限流拒了、账单却记了:API 限流与计费的一致性设计与边界
限流决定请求能否进来,计费记录实际消耗,两者应共享同一请求标识与同一份用量事实,而不是让账单读取限流器的近似计数。文章给出计量口径先行、用量事件去重入账、失败模式提前选边、窗口与时钟边界、三方对账的设计顺序,并说明具体阈值与容量需按自身流量验证。
限流决定一个请求能不能进来,计费记录它实际消耗了什么。这两件事可以各自出错,但不该互相污染。稳定的做法是让它们共享同一个请求标识和同一份用量事实,而不是让账单去读限流器里的计数器。下文给出可落地的判断顺序。需要说明的是,本次没有可核验的实现记录或压测材料,具体阈值、容量与算法在真实流量下的表现不在本文结论范围内,需自行验证。
先定计费口径,再谈限流算法#
限流算法(令牌桶、漏桶、滑动窗口、固定窗口)解决的是速率控制,但计费口径决定限流维度该按什么来。口径至少要在 API 契约里写清四件事:
- 计量单位:请求次数、输入与输出 token、字节数,还是占用时长。
- 计量时点:进入即计、成功才计,还是超时也算。
- 失败归属:4xx、5xx、客户端断开分别怎么记。
- 重试归属:同一逻辑请求的多次重试记一次还是多次。
如果按 token 计费却按请求数限流,成本与准入就会脱节。建议让限流维度与计费维度至少保持可换算关系,否则两个系统会长期给出互相矛盾的解释。
一次请求只产生一条可核对的用量记录#
网关生成 request_id,或直接采用客户端的幂等键,让它贯穿准入判定、用量事件、账本写入三段。用量事件按“至少一次”投递,账本按去重键写入,重复写入不累加。状态机可以设为 accepted → measured → billed,允许重试,但状态只能前进。
这里有个容易忽略的区分:限流器里的计数通常是近似的(本地缓存、分片、预借额度),账本里的数字必须是可以逐条追溯的事实。把近似值当账单来源,等于把限流器的实现细节写进了收费依据。
失败模式要提前选边#
| 场景 | 可选策略 | 代价 |
|---|---|---|
| 限流器不可用 | fail-open 放过 / fail-closed 拒绝 / 本地兜底配额 | 前两者分别在超额与可用性上让步,需按接口重要性分别选择 |
| 计量管道积压 | 先持久化事件,账单侧延迟结算 | 需要设定最长补账窗口,并对外说明账单可能延后 |
| 限流与账本不一致 | 以账本为准做补偿 | 补偿逻辑本身需要幂等 |
我倾向于:涉及扣费的写接口用 fail-closed 或本地兜底配额,只读查询用 fail-open。这只是建议,取舍取决于业务对超额成本与拒绝服务的容忍度。
窗口、时钟与结算边界#
- 以服务端时间为准,客户端时间只作参考;跨窗口的请求归属要写死按开始时间还是结束时间。
- 限流周期与结算周期不必相同,但换算关系要显式定义。
- 时钟漂移要在边界附近留容忍,否则容易出现双计或漏计。
- 限流拒绝建议返回 429,并附带重试等待时间与
request_id,便于用户举证与排查。
对账是设计的一部分,不是运维补丁#
至少保留三个可交叉核对的来源:网关访问日志、计量账本、对外账单。按 request_id 抽样比对,把差异分成缺失、重复、金额不符三类,每类指定处理方与时限。与之配套的观测项包括拒绝率、按原因码的分布、用量事件端到端延迟、对账差异率。
一个未执行的示例#
以下为示意顺序的伪代码,未实际执行,不代表可运行实现:
def handle(req):
rid = req.headers.get("Idempotency-Key") or new_id()
decision = limiter.check(api_key=req.api_key, cost=estimate(req))
if not decision.allowed:
return response(429, retry_after=decision.retry_after, request_id=rid)
resp = upstream(req)
usage = measure(req, resp, request_id=rid)
ledger.append_once(usage) # 以 rid 去重,重复写入不累加
return resp
要点是 estimate 与 measure 的口径必须一致;两者不一致时,限流与计费会系统性偏离,而且偏离方向稳定,很难靠调阈值掩盖。
哪些还需要你自己验证#
限流算法在自身流量分布下的表现、各接口的阈值、单机与集群的容量余量、补账窗口该设多长,都需要可复现的压测与线上观测才能定,本文不给出数字。如果准备对外称“实测”,至少应记录环境、数据集、并发模型与统计口径,否则只能算示例。