限流与计费解耦：API 稳定性设计中的计量、预扣与对账

稳定的 API 限流与计费系统，靠的是三条可验证的性质：每条计量事件都能追溯到具体请求；限额判断与扣费记录不共用一个失败点；账目差异能被主动发现，而不是等用户投诉。令牌桶、漏桶、滑动窗口这些算法只决定突发流量怎么削减，决定不了账对不对得上。本文只给设计要点，不含实测数据；具体参数需按实际流量形态评估。

把“当下”和“历史”拆成两条路径#

限流回答的是“这一秒这个请求能不能过”，计费回答的是“这个周期用了多少”。前者的目标是低延迟，允许短暂不精确；后者要求可重放、可审计。如果两者写在同一段同步逻辑里，计费存储一抖动，接口就会超时——这是限流与计费耦合最常见的故障形态。

计量事件先定字段，再谈存储#

每次请求产生一条计量事件，至少包含：请求 ID、租户 ID、接口标识、计量单位（次数、字节、token 等）、数量、发生时间、口径版本。其中口径版本容易被忽略：一旦单位或换算规则变更，旧事件不能被新规则重算，只能按记录时的版本结算，否则历史账目会随代码发布而漂移。

预扣与结算分离#

高并发下“先查余额再扣减”存在竞态。常见做法是预扣（reserve）→ 执行 → 确认（commit）或释放（release）。预扣用带条件的原子操作，超时未确认的预扣由清理任务回收。注意预扣额度是上限，不是实际扣费；最终账以计量事件为准。

# 未执行示例：仅示意预扣-确认流程，不能直接用于生产
def handle(tenant, endpoint, units):
    key = "quota:" + tenant + ":" + current_period()
    if not reserve(key, units, ttl=60):
        return 429
    try:
        resp = call_upstream(endpoint)
        commit(key, units, event_id=new_event_id())
        return resp
    except Exception:
        release(key, units)
        raise

该片段未在任何环境运行；reserve 的原子性完全取决于所选的限流存储，换存储需要重新验证语义。

限流器与计费写入不可用时的降级#

• 限流存储超时：降级到本地令牌桶，按单实例份额放行。宁可短暂超发，也不整体拒绝服务。
• 计费写入失败：先落本地缓冲或日志，异步补写；补写仍失败的进入待对账表，不丢弃。
• 降级状态要暴露成指标。否则超发可能持续数小时而无人察觉。

对账是系统的一部分，不是运维补充#

按周期比对三个数：网关侧计量条数、计费侧入账条数、计费侧出账金额。差异按原因归类——重复提交、补写丢失、口径不一致——并设阈值告警。没有对账，前面所有设计都无法被证明有效。

边界说明#

算法选型取决于峰值、突发比例与存储成本，需要按实际流量压测后再定，本文不给推荐参数。API.PLUS 各接口的具体限额、配额与计价规则以平台公布信息为准；本次材料未提供，相关细节待核实。