API 限流与计费怎么不冲突:用量事件、幂等写入与对账边界
限流与计费应共用同一份用量事件定义,但执行路径分离:限流可容忍近似,账单必须能重放;用服务端生成的 event_id 保证幂等,用 policy_version 保留规则可追溯性,延迟与差异率则必须通过自测确认。
- 限流和账单分叉多源于口径不同(失败请求、重试、窗口边界、事后折扣),而不是计算精度不够。
- 共享的应是事件定义与幂等身份,而不是同一个计数器;限流可走缓存,账单需回放事件日志。
- 稳定性结论要靠自测:准入延迟、幂等性、窗口漂移与对账差异率都不能由设计推导得出。
要让限流与计费稳定,关键不在把两个数字算得更精确,而在于让它们来自同一份用量记录:准入判断读它,账单从它聚合。两份独立计数一旦分叉,就会出现“被限流却计费”“计费了但查不到请求”这类争议,而仅靠日志往往难以还原。以下是设计层面的建议与边界清单;本文未做大规模压测,也不涉及任何具体服务商的实现细节,涉及数值的结论一律待核实。
两套计数为什么会分叉#
常见做法是网关用本地内存或缓存做令牌桶(token bucket:按固定速率补充令牌,每次请求消耗一个),计费侧另写一条异步日志。两条路径输入看似相同,实际差异不少:
- 口径不同:限流通常把“到达”算作消耗,账单常只结算成功请求。
- 重试与超时:客户端重试会重复到达,服务端超时则可能已经占用了上游资源。
- 窗口与时钟:多实例各用本地时间切分窗口,边界处容易多算或少算。
- 事后调整:账单还要叠加阶梯价格与折扣,回溯修改后再也回不到限流时的原始数。
这些属于结构问题:同一个事实存在两个版本,而不是精度不足。
把用量事件定义成共同底稿#
建议在请求处理早期生成一条用量事件,限流与计费都引用它。字段可按业务取舍,但下列几类通常缺一不可:
| 字段 | 作用 | 注意点 |
|---|---|---|
event_id | 幂等键,防止重复入账 | 由服务端生成,不采信客户端传入值 |
key | 归属维度(账号、密钥、接口) | 同一维度要能同时支撑限流与结算 |
occurred_at | 发生时间 | 用服务端时间,并注明时区 |
units | 计费单位:次数、token 数等 | 单位在接口契约里固定,不做隐式换算 |
outcome | 成功 / 失败 / 被拒绝 | 明确哪些状态计入账单 |
policy_version | 当时生效的限流与价格版本 | 规则调整后仍能按原版本解释历史事件 |
policy_version 最容易被忽略:没有它,规则一改,对账就失去解释依据。
准入与计费的分工#
- 鉴权后确定
key与配额维度。 - 按
key估算本次消耗,做准入判断;放行与拒绝都要落事件,不能只记录放行。 - 放行后执行请求,用实际消耗回填事件(流式响应往往结束时才知道真实用量)。
- 计费侧只消费已定稿的事件,按
policy_version聚合,不与限流路径共享内存状态。 - 对账任务定期比对事件与账单条数,差异进入人工队列,而不是自动抹平。
这里的取舍是:限流可以容忍近似,多放一个请求影响有限;账单不能,必须能重放。因此限流可以走缓存计数以压低延迟,账单必须回到事件日志。两者共享的是事件定义与幂等身份,而不是同一个计数器。相比让账单去读限流器的剩余配额,这种“共享定义、分离执行”更容易解释偏差来源。
未执行的示例:写入顺序与幂等#
下面是伪代码,仅示意调用顺序与字段关系,未执行,不含真实端点、密钥或性能数据。
# 未执行的示例
event = {
"event_id": new_uuid(), # 服务端生成,作为幂等键
"key": auth.key_id, # 限流与计费的公共维度
"occurred_at": server_clock(), # 服务端时间
"units_estimated": estimate(req),
"units_actual": None, # 请求结束后回填
"outcome": "pending",
"policy_version": load_policy().version,
}
admit = limiter.try_acquire(event["key"], event["units_estimated"])
event["outcome"] = "admitted" if admit else "rejected"
store.append(event) # 以 event_id 去重写入
if admit:
run_request()
event["units_actual"] = measure()
store.finalize(event["event_id"])
需要实测才能下的结论#
以上是结构建议,不能当作性能结论直接引用。以下几项必须在自己环境中压测核对,本文不给出数字:
- 准入判断在目标 QPS 下的尾延迟与缓存命中率。
- 事件写入在重试、乱序、重复投递下幂等性是否真的成立。
- 窗口边界与时钟漂移带来的超额比例。
- 对账差异率,以及差异集中在哪些
outcome或policy_version上。
在拿到这些数据之前,稳妥的说法是:限流与计费共用一份用量事件,是让偏差可解释、可回溯的前提;偏差多大、能否接受,取决于实际流量与业务口径。对任何对外提供接口的服务(包括 API.PLUS 这类接口平台)而言,这条前提成立与否,都应先用自己环境里的记录来验证,而不是靠设计文档推断。