技术文章

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

如何设计一个稳定的 API 限流与计费系统:让准入判断和账单共用同一份用量事件

一句话回答

限流负责实时准入,计费负责周期结算,两者若各自计数就会产生“放行未计费”或“计费未放行”的差异。较稳妥的做法是:准入用快速计数器做近似判断,计费以不可变的用量事件为唯一事实来源,中间通过预留、结算、释放和对账衔接。

核心要点 TL;DR
  • 限流和计费必须能对得上:准入可以近似,账单必须可重放。
  • 用量事件要带幂等键和价格版本,否则重复写入与历史改价都会污染账单。
  • 先预留、再按实际结算、失败释放,并给预留设超时,防止额度泄漏。
  • 存储不可用时是放行还是拒绝,应在上线前明确决定,而不是故障时临时选。

限流和计费常被当成两个模块分别实现,稳定性的问题往往就出在这个缝里:限流器放行了请求,计费侧却没收到对应的用量;或者账单扣了费,日志里找不到放行记录。本文的结论是——准入判断可以近似,账单必须可对账,中间用一份带幂等键的用量事件把两侧连起来。

需要先说明材料边界:本次没有可用的外部正文或厂商文档,下面给的是通用设计推理与示意代码,不含实测数据和具体平台的实现细节。API.PLUS 自身的限流响应头、计量单位和计费口径,需以其文档为准,本文不代为断言。

先分清两种“计数”#

限流是毫秒级决策:这一次请求放不放行。计费是周期结算:这个账期用了多少、该收多少。它们的约束正好相反。

  • 限流计数要求低延迟,可以用本地内存、近似算法、短窗口过期,允许在扩容或重启时短暂不准。
  • 计费用量要求可重放、可审计,必须落到持久存储,且能被重复计算而不产生偏差。

如果让计费直接读限流计数器,上述“允许不准”的特性就会变成账单误差。合理的分工是:限流器做前置闸门,计费侧消费独立的用量事件。

限流层:先把语义定清楚#

选算法之前,有几个问题必须先回答,否则实现完还会返工:

  1. 限的是什么——请求数、并发连接数,还是计量单位(token、字符、调用点数)?按单位限流时,限流器需要先知道本次消耗,这会影响架构。
  2. 窗口语义——固定窗口、滑动窗口,还是令牌桶?令牌桶(Token Bucket)用桶容量表达允许的突发量、用填充速率表达长期平均速率,实现简单,是常见默认选项。
  3. 限流键——API key、账号、IP,还是“账号 + 端点”组合?建议做分层:账号级总量、端点级细粒度、再加一层全局保护阈值,防止单点异常拖垮整体。
  4. 超限响应——返回 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、乱序到达、以及人为制造时钟偏移,确认账单结果与预期一致。这些属于验证建议,本文未提供执行记录与结果数据。

落地顺序#

如果只能分阶段做,建议顺序是:先定义计量单位与限流键(决定契约),再实现用量事件与幂等(决定账单可信度),然后接上预留与结算,最后补对账与告警。反过来先做限流算法调优,往往会在计费口径变化时全部推翻。

需要提醒的是,上述为通用设计推理。实际接入时,端点是否按单位计量、超限返回的具体字段、以及历史用量可否重算,都需以平台文档和自身账务规则核实后再定。

常见问题(FAQ)

限流算法选令牌桶还是滑动窗口?
取决于你要不要允许突发。令牌桶用桶容量表达突发上限、用填充速率表达长期速率,实现成本低;滑动窗口日志更精确但存储开销大。固定窗口在窗口边界可能出现接近两倍的瞬时放行,需要评估是否能接受。
为什么计费不能直接复用限流计数器?
限流计数器为了低延迟通常是近似的、按短窗口过期甚至本地聚合的,重启或扩容就可能丢数;账单需要可重放、可审计。两者目标不同,应当分开实现、定期对账,而不是共用一份可变计数。

作者:沐小悠

本文约 6 分钟读完 · 关键词:API 限流设计、API 计费系统、令牌桶、用量事件、幂等

更多文章 GET 示例接口

「」标签下的其他文章