技术文章

外部链接将在新标签页打开。

怎么设计一个稳定的 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 的具体限流策略与计费规则,请查阅其官方文档,待核实后再写入客户端契约。

作者:沐小悠

本文约 5 分钟读完 · 关键词:API 限流、API 计费、令牌桶、配额、幂等

更多文章 GET 示例接口

「」标签下的其他文章