技术文章

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

设计稳定的 API 限流与计费系统:先把“判定”和“记账”拆开

一句话回答

限流负责快速决定放不放行,计费负责准确记录用了多少,两者共用量用事实但不能共用一个计数器。文章给出速率、配额、账单三类数量的区分,限流的拒绝语义,计费的“预留—提交—回滚”顺序,以及用事件日志对账计数器的做法,并列出重试、窗口边界、失败是否计费等需要先写进契约的边界条件。

一个稳定的 API 限流与计费系统,关键不在选哪个算法,而在于把两件事拆成两条路径:一是“这次请求放不放行”,二是“这次调用用了多少、该记多少”。前者要快,可以近似;后者要准,必须能对账。把两者塞进同一个计数器的设计,通常会在并发、重试和窗口边界上同时失真。

本文讨论通用的设计取舍,不假设 API.PLUS 的具体限额、计费单位与价格;这些需要以其控制台和文档为准,本次材料未提供,待核实。

先区分三类“数量”#

“限流”和“配额”经常被当成同一个开关,但它们的时间尺度不同,存储与精度要求也不同。

  • 速率:单位时间内的请求数或并发数,秒级到分钟级,允许近似,允许少量抖动。
  • 周期配额:日额度、月额度,需要确定性,耗尽后行为必须可预期。
  • 账单:金额或计量单位,需要可追溯、可重算、可申诉。

三者共用一份“用量事实”,但不应该共用同一个可变的计数器:前两者为了低延迟可以走内存或共享缓存,账单必须落到可持久、可重放的记录上。

限流层:先定拒绝的语义#

常见算法的取舍是公开的工程常识,这里只列判断依据:固定窗口实现最简单,但在窗口交界处可能出现约两倍于阈值的瞬时放行;滑动窗口更精确,代价是每个维度都要保存窗口内的事件或分片计数;令牌桶允许突发,适合交互式调用;漏桶输出平滑,适合保护下游。

比算法更影响稳定性的是层级与拒绝方式:

  • 多级限流:全局 → 租户 → 密钥 → 端点,任一级超限即拒绝,避免单租户打满全局容量。
  • 拒绝要快且可解析:返回 429 并给出 Retry-After,让客户端知道等多久,而不是盲目重试。
  • 限流本身不能成为故障点:限流组件不可用时,需要预先决定是放行还是拒绝,这个决定要写进设计而不是临时拍板。

计费层:预留、提交、回滚#

“先调用、后记账”在并发下会透支额度,因为调用完成前没有任何东西阻止同一租户继续提交请求。更稳的顺序是:先按估算量预留,执行后按实际用量提交,失败则释放。

  • 幂等键:客户端传入 Idempotency-Key,服务端保存“键 → 结果”,重试命中同一条记录时不重复扣减。
  • 失败口径:被限流拒绝、上游报错、客户端超时三种情况是否计费,必须在对外契约里写清楚,不能留给实现细节。
  • 计量单位:按请求数、按返回字节、按输入输出分别计量的模型各自成立,但单位要能被使用者自行验证,否则对账会变成争议。

顺序示意(未执行示例)

下面的代码是伪代码,用于说明调用顺序,未在任何环境运行,也不代表任何产品的实际实现。其中 example.com 仅为占位域名。

def handle(request):
    key = request.headers.get("Idempotency-Key") or new_id()
    if seen(key):                       # 幂等:重试不重复计费
        return cached(key)

    if not limiter.allow(tenant=request.tenant, cost=estimate(request)):
        return json(429, {"error": "rate_limited", "retry_after": 1})

    hold = ledger.reserve(key, tenant=request.tenant, amount=estimate(request))
    try:
        result = upstream.call(request)          # 上游地址为占位,未实际调用
        ledger.commit(hold, actual=actual_usage(result))
    except UpstreamError:
        ledger.release(hold)                     # 是否计费须以契约规定为准
        raise

用事件日志对账计数器#

计数器负责实时拒绝,事件日志负责事后解释。两者都要有,并且要定期比对:按天聚合日志,与计数器快照做差,差异超过阈值就告警。只保留计数器意味着出了问题无法重算;只保留日志意味着每次限流判定都要扫历史,延迟不可接受。

窗口切分建议统一使用服务端时间,并明确窗口是左闭右开还是右闭左开;跨节点计数如果依赖共享存储,需要先确认该存储的一致性模型是否满足“不超发”的要求,这一点在选型时经常被忽略。

上线前值得逐条确认的边界#

  1. 同一租户的并发请求在预留阶段是否正确串行化,还是会出现两个请求各自看到“余额充足”。
  2. 配额恰好耗尽时的行为是否确定:拒绝、降级还是排队,不能随负载变化。
  3. 限流阈值与计费单位变更时,历史账单如何解释,是否需要版本号。
  4. 重试、批量请求、流式响应这三种形态分别算一次还是多次。

这些问题大多不是算法问题,而是契约问题。先写清楚“超了会怎样、失败怎么算、重试算几次”,再选实现,稳定性主要来自这里。

作者:沐小悠

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

更多文章 GET 示例接口

「」标签下的其他文章