如何设计稳定的 API 限流与计费系统:预留、用量事件与对账
限流与计费应共享同一条可重放的用量事件,但限流路径不能依赖计费路径的可用性。文章给出数据契约、分层限流与失败模式选择、异步计费与幂等去重、四条不变式,以及需要自行实测的边界条件。
- 限流做预留、计费做结算,两者用同一个请求标识串起来,才能事后对账。
- 集中计数器不可用时,放行还是拒绝要按路由显式选择,而不是让超时默认决定。
- 计价规则版本随用量事件写入,事后调价只影响新事件,不改历史记录。
限流回答的是“这次请求现在能不能进”,计费回答的是“已经用掉多少、该算多少”。两者经常被塞进同一个中间件,但它们的可用性要求和失败代价并不相同:限流失败会立刻表现为拒绝服务或超额放量,计费失败则可以延迟处理,但不能丢失数据。面向 API.PLUS 这类 API 平台的场景,更稳的结构是让两者共享同一条可重放的“用量事件”,同时保证限流路径不依赖计费路径是否在线。下文所述均为工程建议与示意,具体平台能力以官方文档为准,本文未做联网核验。
先定一条数据契约#
限流和计费要能对上账,前提是双方说的是同一件事。建议把每次请求压缩成一条用量事件,至少包含:请求标识(request_id)、主体标识(API 密钥或账号)、路由、计量单位与数量、计价规则版本号、发生时间。限流侧在请求进入时做“预留”,计费侧在请求结束后做“结算”,两侧都携带同一个请求标识。没有这个共同键,事后只能靠时间窗和总量去猜,误差无法收敛。
限流:分层,并把失败模式写成显式配置#
- 边缘层按来源做粗粒度突发抑制,成本低,但看不到业务主体。
- 服务层按主体、路由、计量单位做细粒度配额,是真正决定“谁用了多少”的地方。
- 上游配额如果调用了第三方模型或服务,还需要一层代理侧配额,避免把上游的限流错误直接暴露给调用方。
比算法选型(令牌桶、滑动窗口、漏桶)更重要的是失败模式:集中计数器超时或不可用时,是放行(可用性优先)还是拒绝(成本优先)。这个选择应当按路由配置,并且可观测——如果默认行为是“超时即放行”,那么一次计数器故障就会变成一次账单异常。推断:多数事故不是限流算法写错,而是降级路径没有被当成一等公民设计。
计费:异步结算,幂等去重#
计费不适合放在请求的关键路径上同步完成。更常见的做法是先落用量事件,再由聚合任务按窗口出账:允许延迟,不允许丢。两条规则需要写进代码而不是文档里:
- 同一 request_id 的用量事件幂等写入,重试不重复计量。
- 迟到事件按事件自身的时间戳归入对应窗口,而不是按处理时间。
调价、退款、纠错应产生反向事件或新版本事件,而不是修改历史记录——否则对账时无法解释差额从哪来。
四条不变式#
| 不变式 | 违反后的表现 |
|---|---|
| 每次成功预留最终要么结算、要么释放 | 配额泄漏,主体被永久降速 |
| 同一 request_id 只计量一次 | 重试导致多计费 |
| 计价规则版本随事件写入 | 历史账单无法复现 |
| 限流判定使用单调时间源 | 时钟回拨造成窗口错乱 |
一个未执行的调用顺序示例#
下面的伪代码只示意预留与结算的先后关系,未实际执行,参数均为占位值。
# 未执行示例:仅示意顺序,不代表任何库的真实接口
reservation = limiter.reserve(key="YOUR_KEY:chat", units=1, ttl_ms=5000)
if not reservation.ok:
return 429
try:
result = handle(request)
billing.emit(request_id=request.id, units=result.units, rule_version="demo-v0")
finally:
# 无论成功失败都必须释放或结算,否则配额泄漏
reservation.settle(units_used=result.units if result else 0)
需要自己测的边界#
以下项目没有通用答案,需要用自己的流量数据验证,本文不提供实测结论:集中计数器的读写延迟与超时阈值、预留 TTL 与最长请求时长的关系、多计量单位(请求数、token 数、字节数)如何共存于同一配额、以及迟到事件的容忍窗口。建议先在一个低风险路由上并行跑“影子对账”,比较限流侧记录的用量与计费侧出账的用量,差额稳定后再扩大范围。