API 限流与计费的一致性设计:单位、窗口与幂等
稳定的限流与计费系统,关键在于让同一笔用量在准入、记账、出账三个环节使用同一套口径。文章按计量单位与时间窗口、准入的近似程度、幂等事件记账、差异归因四部分给出设计边界,并说明哪些选择取决于业务而无法通用回答。
限流与计费系统的稳定性,通常不在于算法有多精巧,而在于同一笔用量在准入、记账、出账三个环节被算成了不同的数。可行的做法是先固定计量口径,再让每个环节只回答自己的问题。本文是通用设计建议,不包含对 API.PLUS 具体接口、配额或价格的实测或核验;这些信息本次材料未提供,接入前应以官方文档为准(待核实)。
一、先把计量口径固定下来#
口径不清,后面所有对账都会变成争论。至少要明确四件事:
| 维度 | 常见选择 | 影响 |
|---|---|---|
| 计量主体 | 按 API key、账号或项目 | 限流按 key、计费按账号是最易出差异的组合,需显式写入文档 |
| 计量单位 | 请求数、token、字节或时长 | 按请求计最简单,但单请求成本差异大时计费会失真 |
| 时间窗口 | 固定窗口、滑动窗口、令牌桶 | 固定窗口实现简单,但窗口边界可能出现短时双倍突发 |
| 计费时机 | 进入时预扣、返回后结算、异步批量入账 | 三种选择对“失败请求是否计费”的答案不同 |
这四项不需要选“最好”的,但必须在一个地方写死,并让准入与出账引用同一份定义。
二、准入判断可以近似,但要说明近似到什么程度#
限流的作用是保护上游,不是账本。把准入做成“近似正确且可解释”,通常比追求精确更稳:本地缓存配合周期性同步,能扛住计数服务抖动,代价是短时超卖;集中计数更准,但计数服务会进入请求关键路径。
选择依据是超卖的后果。超卖只影响体验,可接受近似;超卖直接变成计费金额,就应使用集中计数,并为计数服务准备降级策略。降级是放行还是拒绝,两者都能成立,但必须提前选定、写入文档并配告警,不能等故障时临时决定。
三、记账:把每次消耗落成幂等事件#
建议以不可变事件作为事实来源,聚合数据只作派生结果,可随时重算。事件字段至少包含请求 ID、计量主体、计量单位、数量、发生时间(UTC)、窗口标识和结果状态。
重试是重复计费的主要来源。客户端重试、网关重试和异步投递重试会叠在一起,因此写事件必须带幂等键;同一请求重复提交时,只应产生一条有效计量记录。这一步比限流算法更值得投入。
四、对账:差异要能归因,而不只是能发现#
常见差异有三类:漏记,来自超时、进程崩溃或投递失败;重复,来自重试或双写;归属错,来自时区、窗口边界和跨天补录。对账的最小闭环是“原始事件总量 → 聚合用量 → 出账金额”逐层比对,且每一层都能回溯到请求 ID。只比总额、无法下钻到单条请求的对账,发现问题也难定位。
五、最小事件结构示例(未执行)#
以下仅为字段形态演示,占位值非真实数据,代码未运行。
{
"request_id": "req_demo_0001",
"subject": "account_demo",
"api_key_id": "key_demo",
"unit": "request",
"quantity": 1,
"occurred_at": "2026-11-17T00:00:00Z",
"window_id": "2026-11-17T00",
"status": "ok",
"idempotency_key": "idem_demo_0001"
}
六、上线前应能回答的问题#
- 计数服务不可用时,准入是放行还是拒绝,由谁收到告警?
- 客户端用同一幂等键重试,是否会扣两次?
- 跨窗口边界的请求计入哪个窗口,文档里是否写明?
- 失败请求是否计费,准入与出账的答案是否一致?
- 出账前是否需要复核差异率,超过多少暂停出账?
这些问题没有通用答案,取决于业务对超卖和收入的容忍度。但每一项都应有明确选择并写进接口文档;未核实的具体配额与价格,不应靠推测进入系统设计。