如何设计一个稳定的 API 限流与计费系统:让准入判断和账单共用同一份用量事件
限流负责实时准入,计费负责周期结算,两者若各自计数就会产生“放行未计费”或“计费未放行”的差异。较稳妥的做法是:准入用快速计数器做近似判断,计费以不可变的用量事件为唯一事实来源,中间通过预留、结算、释放和对账衔接。
- 限流和计费必须能对得上:准入可以近似,账单必须可重放。
- 用量事件要带幂等键和价格版本,否则重复写入与历史改价都会污染账单。
- 先预留、再按实际结算、失败释放,并给预留设超时,防止额度泄漏。
- 存储不可用时是放行还是拒绝,应在上线前明确决定,而不是故障时临时选。
限流和计费常被当成两个模块分别实现,稳定性的问题往往就出在这个缝里:限流器放行了请求,计费侧却没收到对应的用量;或者账单扣了费,日志里找不到放行记录。本文的结论是——准入判断可以近似,账单必须可对账,中间用一份带幂等键的用量事件把两侧连起来。
需要先说明材料边界:本次没有可用的外部正文或厂商文档,下面给的是通用设计推理与示意代码,不含实测数据和具体平台的实现细节。API.PLUS 自身的限流响应头、计量单位和计费口径,需以其文档为准,本文不代为断言。
先分清两种“计数”#
限流是毫秒级决策:这一次请求放不放行。计费是周期结算:这个账期用了多少、该收多少。它们的约束正好相反。
- 限流计数要求低延迟,可以用本地内存、近似算法、短窗口过期,允许在扩容或重启时短暂不准。
- 计费用量要求可重放、可审计,必须落到持久存储,且能被重复计算而不产生偏差。
如果让计费直接读限流计数器,上述“允许不准”的特性就会变成账单误差。合理的分工是:限流器做前置闸门,计费侧消费独立的用量事件。
限流层:先把语义定清楚#
选算法之前,有几个问题必须先回答,否则实现完还会返工:
- 限的是什么——请求数、并发连接数,还是计量单位(token、字符、调用点数)?按单位限流时,限流器需要先知道本次消耗,这会影响架构。
- 窗口语义——固定窗口、滑动窗口,还是令牌桶?令牌桶(Token Bucket)用桶容量表达允许的突发量、用填充速率表达长期平均速率,实现简单,是常见默认选项。
- 限流键——API key、账号、IP,还是“账号 + 端点”组合?建议做分层:账号级总量、端点级细粒度、再加一层全局保护阈值,防止单点异常拖垮整体。
- 超限响应——返回 429,并在
Retry-After中给出建议等待时间,比只返回错误码更利于客户端退避。
固定窗口实现最省事,但在窗口边界前后连续放行,瞬时可能接近配额的两倍。是否可接受,取决于下游能否承受这个尖峰。
计费层:用量事件是唯一事实来源#
一条可用的用量事件,至少应包含:
| 字段 | 作用 |
|---|---|
| 事件 ID / 幂等键 | 重复写入时只计一次,抵御重试与消息重投 |
| 账号与 API key 标识 | 归属与权限追溯,不存明文密钥 |
| 端点与计量单位、数量 | 决定单价与计费维度 |
| 服务端时间戳 | 不信任客户端时间,避免时钟偏移导致跨账期 |
| 价格版本 | 记录事件发生时的价目版本,改价不回溯污染历史 |
| 请求 ID | 把账单条目与日志、限流记录串起来 |
写入方式建议采用不可变追加日志 + 定期聚合:原始事件只追加不修改,聚合结果可随时由原始事件重算。这样对账差异才有办法定位到具体事件,而不是面对一个无法解释的总额。
预留、结算与对账#
按用量计费时,请求开始前并不知道最终消耗。常见做法是先按上限预留,成功后按实际结算,失败则释放:
# 伪代码,未执行;仅示意顺序,不代表任何具体实现
def handle(request):
key = request.api_key
cost = estimate_max_cost(request) # 预留上限
if not reserve(key, cost, ttl=30s): # 预留失败即限流
return 429, {"Retry-After": "1"}
try:
result = call_upstream(request)
usage = measure(result) # 实际用量
commit(key, reserve_id, usage) # 按实际结算,退回差额
return result
except UpstreamError:
release(key, reserve_id) # 失败释放,不计费
raise
这里有两个容易忽略的点:预留必须带超时(示例中的 ttl),否则进程崩溃会让额度永久挂起;结算与预留要能通过同一个 reserve_id 关联,才能查出“预留了但从未结算”的泄漏。
对账是最后一道防线:按日比较聚合用量与账单金额,差异超过阈值就告警,并允许抽样回溯到事件级别。指标上建议至少观察限流命中率、预留泄漏数、事件写入延迟和对账差异额。
边界条件与验证方法#
- 重试放大:客户端重试若不带幂等键,一次失败可能产生多条计费事件。
- 缓存命中是否计费:必须在文档里写清楚,否则会变成争议点。
- 存储不可用时的取舍:限流存储故障时是“放行并记录”还是“拒绝”,两种选择对应不同的业务风险,应在上线前决定并写进运行手册,而不是故障现场临时拍板。
- 多渠道余额一致:控制台、代理商、预付额度若各自维护余额,容易出现同一账号多处可透支。
验收不一定要压测,但至少要注入三类异常:重复投递同一事件 ID、乱序到达、以及人为制造时钟偏移,确认账单结果与预期一致。这些属于验证建议,本文未提供执行记录与结果数据。
落地顺序#
如果只能分阶段做,建议顺序是:先定义计量单位与限流键(决定契约),再实现用量事件与幂等(决定账单可信度),然后接上预留与结算,最后补对账与告警。反过来先做限流算法调优,往往会在计费口径变化时全部推翻。
需要提醒的是,上述为通用设计推理。实际接入时,端点是否按单位计量、超限返回的具体字段、以及历史用量可否重算,都需以平台文档和自身账务规则核实后再定。