怎么设计一个稳定的 API 限流与计费系统:先定口径,再谈算法
稳定的限流与计费系统首先要统一计量单位和拒绝语义,再把限流与计费分开处理:前端做快速拒绝,后端用不可变的用量事件账本异步结算。实现时需要注意窗口边界、多租户键、计数器故障时的放行或拒绝策略,以及客户端约定的错误码。具体产品的配额阈值、计费单价和现行策略需以官方文档核实,本文不假设。
本文回答一个工程问题:怎样让 API 的限流与计费在一起工作时仍然稳定。核心答案可以先说清楚:稳定性主要来自“口径统一”和“故障时有明确取舍”,而不是来自更复杂的算法。本次没有提供可核验的发布方文档,以下是一般性工程说明,不针对任何具体产品的现行配额、价格或实现。API.PLUS 的实际计量单位、限流阈值与结算口径,需以其官方文档为准,本文不作假设。
第一步:先定计量单位与拒绝语义#
限流和计费如果使用不同口径,系统迟早会对不上账。建议先写清楚三件事:
- 计量单位:按请求数、按输入与输出 token、按字节,还是按“调用次数 + 计算量”的复合单位。单位不同,限流键和账本字段也不同。
- 时间窗口:按秒、分钟还是月。窗口边界由服务端时间决定,不能使用客户端时间。
- 拒绝语义:区分“速率超限”和“配额耗尽”。前者可重试,后者通常要等配额重置或升级。两者混用一个错误码,客户端就无法正确退避。
这部分属于设计建议。推断是:如果错误码含糊,客户端往往会盲目重试,反而放大流量。
限流放在哪一层#
常见做法是两层:进程内用令牌桶或漏桶做快速预检,集中存储做全局配额扣减。令牌桶允许一定突发,漏桶更平滑;固定窗口实现简单,但窗口交界处可能出现流量尖峰;滑动窗口更平滑,代价是状态更多。选择哪种,取决于业务能接受突发,还是更怕尖峰。
集中计数器可用 Redis 一类存储,但要注意原子性与热点键。限流键建议至少包含租户、端点和计量维度,避免单一热键成为瓶颈。
计数器不可用时怎么办
这是稳定性设计中最容易被忽略的一环。集中存储故障时只有两种选择:放行(fail-open)或拒绝(fail-closed)。建议按端点分级:读类、低价值接口可以短时放行并记录事件,写类或高成本接口倾向拒绝。这个取舍没有通用答案,需要结合滥用风险和收入风险确定。
计费与限流解耦:用量事件 + 不可变账本#
不要在请求路径上同步写账单。更稳的结构是:请求完成时写一条用量事件,包含事件 ID、幂等键、账户、计量单位、数量、服务端时间戳;异步聚合后生成账本条目。账本只追加、不修改,纠错用冲正条目。这样重试和重复投递不会重复计费。
# 未执行的示例,仅示意结构,非可运行代码
event = {
"event_id": "evt_placeholder_0001",
"idempotency_key": "req_placeholder_0001",
"account": "acct_demo",
"meter": "requests",
"quantity": 1,
"ts": "server_time",
}
# 1) 以 event_id 去重写入
# 2) 异步聚合到账本
# 3) 与上游账单定期对账,差异生成冲正条目
对账是计费系统的一部分,不是附加功能。至少要能回答:某账户某窗口的用量事件总数、聚合结果、对外账单三者是否一致。
面向客户端的契约#
- 超限返回 429,并视情况给出
Retry-After;配额耗尽使用独立错误码。 - 错误体里写清
rate_limited或quota_exceeded,便于客户端分支处理。 - 如需返回剩余配额,先评估是否会泄露其他租户信息;通常只返回当前调用方的值。
可观测性与边界#
建议至少记录:被限流请求数、限流键分布、用量事件积压量、聚合延迟、对账差异数。指标要能按租户和时间窗口切片,否则出问题时无法定位是单租户热点还是全局容量不足。
最后强调边界:本文不提供任何性能数字或实测结论;上述结构是否适用于具体业务,取决于流量规模、一致性要求和故障预算,需通过压测与故障演练验证。API.PLUS 的具体限流策略与计费规则,请查阅其官方文档,待核实后再写入客户端契约。