如何设计一个稳定的 API 限流与计费系统:拆分三种限、选好失败方向
稳定的限流与计费系统先把速率、并发、配额三种限制拆开,再分别决定计数放在本地还是集中存储,并把故障时的失败方向写成显式策略。计费侧的关键约束是计量单位固定、换算只在一处实现、舍入规则写入契约;迟到与乱序事件的处理口径需要单独定义。本文只讨论设计取舍,不涉及具体产品配额数值。
稳定的限流与计费系统,关键不在“算得准”,而在于当存储、网络和时钟都可能出错时,系统仍能给出可解释的行为。实现路径可以归纳为三步:先把三种不同的“限”拆开,再分别决定计数放在哪里,最后把故障时的失败方向写成显式策略。本文只讨论通用设计取舍;API.PLUS 的具体配额数值、计费口径与结算周期不在本次材料范围内,待核实。
一、把三种“限”拆开#
三者常被塞进同一个计数器,结果是在长请求和批量请求上互相干扰。
| 类型 | 限制对象 | 典型失效方式 |
|---|---|---|
| 速率限流 | 单位时间内的请求数 | 固定窗口在边界处允许双倍突刺 |
| 并发上限 | 同时处理中的请求数 | 长请求占满并发槽位,短请求排队 |
| 配额、预算 | 一个周期内可消耗的计量单位 | 周期重置的时区与边界不明确 |
拆分之后,每类限制都有独立的键(租户、接口、模型)、独立的窗口和独立的错误语义,排查时才能定位是哪一层拦下的。
二、计数放在哪里#
- 纯本地内存:延迟最低,但多实例之间不共享,集群总量约等于单实例额度乘以实例数,扩缩容时额度会漂移。
- 纯集中存储:总量准确,但每次请求都多一次网络往返,热点租户会把集中存储打成瓶颈。
- 本地预扣加集中校准:本地先扣一小份额度,按阈值或时间向集中端批量申领。代价是瞬时可能超发一个批次,因此必须把“可接受的超发量”当作设计参数写下来。
第三种是常见折中,但它不是性能承诺。是否值得,取决于能否容忍批次级超发,以及集中端故障时的降级行为。
三、窗口与算法的取舍#
固定窗口实现简单,缺点是边界突刺;滑动窗口和令牌桶更平滑,代价是状态更多、冷启动和时钟漂移需要额外处理。选择依据是“业务能否接受突发”和“允许多大误差”,而不是哪个算法更新。窗口按事件时间还是按到达时间切分,也必须先定义,否则乱序事件会落到错误的周期里。
四、计费侧的三个硬约束#
- 计量单位固定:请求数、字节、token、秒,选定后不要在链路中途换算。
- 换算只在一处实现:从原始计量到计价单位的转换集中在一个模块,避免网关和账单各算一遍。
- 舍入规则写进契约:向上取整还是按比例,调用方需要能预期结果。
迟到事件的处理口径同样要先定义:是补记到原周期,还是计入到达周期。两种做法都合理,但不能由实现随手决定。
五、失败方向必须先写下来#
限流器不可用时,放行会造成超发,拒绝会造成误伤,这没有两全的答案。可操作的原则是:预付费场景倾向拒绝,后付费场景倾向放行并记录超发量,同时把这一选择写进对外文档。计费写入失败时,先把事件落到本地持久队列再重放,而重放需要幂等键,否则会重复计费。
// 未执行的示例:仅示意“本地预扣 + 集中校准”的结构,非可运行代码
async function acquire(tenantId, cost) {
if (!localBucket.tryTake(tenantId, cost)) {
return { ok: false, retryAfterMs: localBucket.retryAfter(tenantId) };
}
if (localBucket.shouldSync(tenantId)) { // 按阈值或时间触发
const lease = await quotaService.reserve(tenantId, BATCH_SIZE); // 占位常量
localBucket.refill(tenantId, lease.granted);
}
return { ok: true };
}
六、响应契约要能指导重试#
被限流时返回 429 并提供 Retry-After;若暴露剩余额度,字段含义要稳定。调用方最需要知道的是“等多久再试”,而不是一句“超限”。
七、上线前能验证的几件事#
- 多实例扩容后,集群总吞吐是否仍落在预期区间。
- 集中存储不可用时,系统进入的是放行还是拒绝,日志能否区分。
- 同一事件重复投递,账单是否只增加一次。
- 跨周期边界的一批请求,分别落在哪个窗口。
这些检查不依赖具体实现,但都需要在真实部署形态下跑,单机单测无法覆盖。