技术文章

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

如何设计一个稳定的 API 限流与计费系统:拆分三种限、选好失败方向

一句话回答

稳定的限流与计费系统先把速率、并发、配额三种限制拆开,再分别决定计数放在本地还是集中存储,并把故障时的失败方向写成显式策略。计费侧的关键约束是计量单位固定、换算只在一处实现、舍入规则写入契约;迟到与乱序事件的处理口径需要单独定义。本文只讨论设计取舍,不涉及具体产品配额数值。

稳定的限流与计费系统,关键不在“算得准”,而在于当存储、网络和时钟都可能出错时,系统仍能给出可解释的行为。实现路径可以归纳为三步:先把三种不同的“限”拆开,再分别决定计数放在哪里,最后把故障时的失败方向写成显式策略。本文只讨论通用设计取舍;API.PLUS 的具体配额数值、计费口径与结算周期不在本次材料范围内,待核实。

一、把三种“限”拆开#

三者常被塞进同一个计数器,结果是在长请求和批量请求上互相干扰。

类型限制对象典型失效方式
速率限流单位时间内的请求数固定窗口在边界处允许双倍突刺
并发上限同时处理中的请求数长请求占满并发槽位,短请求排队
配额、预算一个周期内可消耗的计量单位周期重置的时区与边界不明确

拆分之后,每类限制都有独立的键(租户、接口、模型)、独立的窗口和独立的错误语义,排查时才能定位是哪一层拦下的。

二、计数放在哪里#

  • 纯本地内存:延迟最低,但多实例之间不共享,集群总量约等于单实例额度乘以实例数,扩缩容时额度会漂移。
  • 纯集中存储:总量准确,但每次请求都多一次网络往返,热点租户会把集中存储打成瓶颈。
  • 本地预扣加集中校准:本地先扣一小份额度,按阈值或时间向集中端批量申领。代价是瞬时可能超发一个批次,因此必须把“可接受的超发量”当作设计参数写下来。

第三种是常见折中,但它不是性能承诺。是否值得,取决于能否容忍批次级超发,以及集中端故障时的降级行为。

三、窗口与算法的取舍#

固定窗口实现简单,缺点是边界突刺;滑动窗口和令牌桶更平滑,代价是状态更多、冷启动和时钟漂移需要额外处理。选择依据是“业务能否接受突发”和“允许多大误差”,而不是哪个算法更新。窗口按事件时间还是按到达时间切分,也必须先定义,否则乱序事件会落到错误的周期里。

四、计费侧的三个硬约束#

  1. 计量单位固定:请求数、字节、token、秒,选定后不要在链路中途换算。
  2. 换算只在一处实现:从原始计量到计价单位的转换集中在一个模块,避免网关和账单各算一遍。
  3. 舍入规则写进契约:向上取整还是按比例,调用方需要能预期结果。

迟到事件的处理口径同样要先定义:是补记到原周期,还是计入到达周期。两种做法都合理,但不能由实现随手决定。

五、失败方向必须先写下来#

限流器不可用时,放行会造成超发,拒绝会造成误伤,这没有两全的答案。可操作的原则是:预付费场景倾向拒绝,后付费场景倾向放行并记录超发量,同时把这一选择写进对外文档。计费写入失败时,先把事件落到本地持久队列再重放,而重放需要幂等键,否则会重复计费。

// 未执行的示例:仅示意“本地预扣 + 集中校准”的结构,非可运行代码
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;若暴露剩余额度,字段含义要稳定。调用方最需要知道的是“等多久再试”,而不是一句“超限”。

七、上线前能验证的几件事#

  • 多实例扩容后,集群总吞吐是否仍落在预期区间。
  • 集中存储不可用时,系统进入的是放行还是拒绝,日志能否区分。
  • 同一事件重复投递,账单是否只增加一次。
  • 跨周期边界的一批请求,分别落在哪个窗口。

这些检查不依赖具体实现,但都需要在真实部署形态下跑,单机单测无法覆盖。

作者:沐小悠

本文约 5 分钟读完 · 关键词:API 限流、计费系统、令牌桶、滑动窗口、并发限流

更多文章 GET 示例接口

「」标签下的其他文章