技术文章

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

设计稳定的 API 限流与计费系统:让放行与记账共用一份计量事实

一句话回答

限流与计费要稳定,关键不是挑一个最精确的算法,而是让放行判断和计费记账基于同一份可核验的计量事件。本文从计量单位定义、限流算法取舍、分布式原子性、预扣与结算、对账与失败语义几个方面给出通用设计思路,并标明示例代码未执行、具体平台参数待核实。

结论:限流与计费要稳定,关键不在于算法多精妙,而在于“放行判断”和“计费记账”是否基于同一份可核验的计量事实。两套逻辑各算各的,典型后果是限流已经放行、账本没有记录,或者账本已扣费、请求却被拒。本文没有可核验的外部素材,以下为通用的工程设计说明;涉及具体平台的限流维度、计费口径与配额数值,均需以该平台官方文档为准(待核实)。

一、先定义计量事件,再选算法#

计费单位和限流单位可以不同:限流常按“请求数/秒”,计费常按“调用次数、token 数、字节数或时长”。但两者应当由同一个事件产生,否则对账时无法解释差异。建议每条计量事件至少包含:

  • 租户与凭据标识(哪个账号、哪个密钥);
  • 服务端生成的请求 ID 与幂等键(用于重试去重);
  • 计量单位与数量(本次消耗多少);
  • 服务端时间戳,而不是客户端上报时间;
  • 处理结果(成功、失败、部分成功),以及是否计入计费。

“失败是否计费”必须在契约里写清楚,否则同一份流水会被两种口径统计出两个数字。

二、限流算法是取舍,不是最优解#

方案是否允许突发主要代价
固定窗口计数窗口边界处会放行约两倍流量实现最简单,需接受边界突刺
滑动窗口(日志)较平滑存储与计算成本随窗口内请求数增长
滑动窗口(计数近似)较平滑结果有误差,需接受近似
令牌桶 / 漏桶令牌桶可控突发,漏桶趋于匀速需维护桶状态,参数需要压测调

多维限流(按密钥、按 IP、按接口、按租户总额度)应取各维度判断的“最小值”:任一维度不足即拒绝。单机限流只能保护单实例,全局配额必须放到共享存储上判断。

三、分布式限流:原子性与热点#

“先读剩余量、再写扣减”如果拆成两次调用,并发下会超卖。把检查与扣减放进同一次原子操作,通常是中心存储加脚本。代价是每个请求多一次网络往返,并且配额键会成为热点。分片或本地预取能降低延迟,但会牺牲一定精确度,需要在设计文档里写明可接受的误差。

-- 未执行示例:演示“检查并扣减”需在同一原子操作内完成
-- 环境:Redis + Lua;仅为思路演示,参数与键名均为占位
local key  = KEYS[1]        -- 占位:limit:{tenant}:{window}
local cost = tonumber(ARGV[1])
local limit = tonumber(ARGV[2])
local ttl  = tonumber(ARGV[3])

local used = tonumber(redis.call('GET', key) or '0')
if used + cost > limit then
  return 0                  -- 拒绝
end
redis.call('INCRBY', key, cost)
if used == 0 then
  redis.call('EXPIRE', key, ttl)
end
return 1                    -- 放行

该示例是固定窗口计数,仍存在边界突刺;窗口起点的对齐、过期时间的设置都需要额外处理。示例未经实际执行,不能直接作为生产配置。

四、计费走“预扣—结算—对账”#

  1. 预扣:请求开始时按预估上限原子扣减配额,失败即返回限流错误。
  2. 结算:处理完成后按实际用量写计量事件;实际值与预扣值不一致时做差额补偿。
  3. 释放:处理超时或进程崩溃时,预扣记录应能通过 TTL 或补偿任务回收,否则配额会被永久占住。
  4. 对账:按周期把事件流水汇总,与账本余额比对,差异超过阈值告警,而不是静默修正。

重试是计费系统最常见的双扣来源,所以幂等键必须由客户端或网关稳定生成,并在结算侧做去重。

五、失败语义与可观测性#

限流和额度耗尽不是一回事:前者可稍后重试,后者往往需要充值或提升配额。建议用不同状态码或错误码区分,并在 429 响应中给出 Retry-After,同时以响应头暴露剩余额度,便于客户端自适应退避。至少要监控:限流命中率、计量事件写入失败率、预扣与结算的差额分布、对账差异。这些指标比单次请求的延迟更能反映系统是否稳定。

六、边界与待核实#

本文不涉及任何具体平台的限额数值、计费单位或票据规则,这些信息本次材料未提供,需查阅对应官方文档确认。文中的脚本与流程属于设计示意,未经执行验证;上线前应在测试环境用并发与故障注入验证原子性、超时回收和对账准确性。

作者:沐小悠

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

更多文章 GET 示例接口

「」标签下的其他文章