API 限流与计费的稳定性设计：失败路径、事件账本与窗口边界

稳定的限流与计费系统，难点不在算法，而在失败路径：限流判断出错，最多是多放过几个请求；计费记录出错，就可能丢账、重复计费或无法对账。设计上应把两者拆成独立路径，各自声明失败时怎么办。以下是通用设计建议，未在真实系统上验证；API.PLUS 的具体配额、计费单位与是否提供用量查询接口，本次材料未涉及，接入前应以其文档为准。

先算清两条路径的失败代价#

限流路径追求低延迟、可容忍近似，目标是不让后端被打穿；计费路径追求不丢不重、可容忍延迟，目标是账目能对上。两者可以共用一次准入检查，但写入动作和失败处理必须分开，不能写在同一段事务里。

限流：先分层，再决定放行还是拒绝#

建议三层而不是一层：接入层做粗粒度上限（如连接数、单来源速率），应用层按调用主体（API key、账号）分配额度，后端按昂贵资源（并发数、下游配额）做最后保护。任一层失效，其余层仍能兜住。

集中计数与本地计数是典型取舍：集中式（如 Redis 类存储）一致性好，但引入网络依赖和单点；本地令牌桶延迟低，但在多实例部署下实际总量会被放大到“实例数 × 桶速率”。常见折中是本地快速拒绝、集中式周期同步，接受短暂超发——关键是把超发上限写进设计文档并给出估算方式，而不是等线上发现。

降级策略必须按接口显式声明：限流依赖不可用时，fail-open 放行以保可用性、牺牲后端，fail-closed 拒绝以保后端、牺牲可用性。读接口通常倾向放行，高成本写接口通常倾向拒绝。建议同时留一个可运行时切换的开关，避免变更依赖发版。

计费：写事件，不写结论#

不要在请求路径上直接累加“已用额度”。先追加一条不可变的用量事件（调用主体、时间、接口、计量单位、数量、幂等键），再异步聚合出余额与账单。就地累加一旦失败就无法重放；事件流可以重放、可以审计，也能在计费规则调整后按新规则重算指定区间——是否允许重算历史，要事先明确，否则对账双方口径永远对不上。

“至少一次投递 + 幂等键去重”比“保证恰好一次”更可实现。幂等键可由请求 ID 派生，或由（账号、接口、时间窗）组合生成；去重窗口长度与存储成本需要按实际量级估算，此处不给具体数值。

时钟与窗口边界#

固定窗口与滑动窗口的拒绝曲线不同，选哪种要写清楚。跨实例比较时间需统一时间源，并留意时钟偏移。窗口边界是最容易产生客诉的地方：配额何时重置、按哪个时区、跨越边界的请求算进哪一边，都应落到文档，而不是只存在于代码里。

可观测性的最小集#

至少要能回答三个问题：某账号某时间段被拒了多少次、被哪个维度拒的、某笔用量事件为什么没进账单。对应三类数据：按维度打标的拒绝计数、限流依赖的延迟与错误率、事件队列的积压量与最老未处理事件的年龄。

示意代码：顺序比语法重要#

# 示意伪代码，未执行；仅表达顺序：先准入，再落事件，余额判断允许滞后
def handle(request):
    key = request.api_key
    # 1) 准入：按接口声明的失败策略降级
    if not limiter.allow(key, cost=request.cost,
                         fail_open=request.endpoint.fail_open):
        return 429
    # 2) 追加不可变用量事件，幂等键由服务端派生
    usage.append({
        "idempotency_key": request.id or derive_key(request),
        "api_key": key,
        "endpoint": request.endpoint.name,
        "units": request.cost,
        "at": now_utc(),
    })
    # 3) 余额判断读聚合结果，允许滞后；超额由事后对账兜底
    return dispatch(request)

这段代码没有处理“余额不足”的准入，因为余额来自异步聚合，本身就有滞后。如果想在前置阶段拦截超额，需要额外的预扣或缓存余额，代价是要处理预扣回滚——是否值得，取决于超支风险的量级。

上线前的核对项#

• 每个接口的 fail-open / fail-closed 已声明，并说明理由
• 多实例下超发上限的估算方式与可接受范围已写明
• 幂等键生成规则与去重窗口已文档化
• 窗口类型、重置时刻、时区已写清
• 计费规则变更时是否重算历史，已有明确结论
• 能从任一账号回溯到用量事件与账单行

这六项都能答上来，系统在依赖抖动时至少是“可解释地出错”，而不是静默丢账。