以下三家公司与全部数字均为教学假设,用于演示商业化计算,不代表任何真实企业。
计量管道一定会重复
分布式系统里,「恰好一次」是一个昂贵的承诺。消息队列、HTTP 回调、批处理任务,默认语义都是「至少一次」:发送方没有收到确认就会重发,接收方可能已经处理过,也可能没有。
计量管道继承了这条默认语义。生产端把一条对话事件发出去,网络超时,客户端重试;队列的消费者处理到一半崩溃,消息重新入队;夜里补跑的批任务因为上游数据延迟,把同一个时间窗又算了一遍。三种情况都会让同一条事实到达两次以上。
这不是工程团队的疏忽,而是系统设计的前提。计量系统不能假设「不会重复」,只能假设「一定会重复」,然后用幂等把重复挡在账外。
幂等不是「把重复删掉」这么简单。删除会丢失「曾经重复过」这个信息,而重复率本身是判断管道健康度的指标。正确的做法是:重复到达时识别它、记录它、不重复计费。
重复的三种来源
把来源分开,才能分别处理。
生产端重试。 业务服务调用计量接口失败后重试。这类重复的特征是 eventId 相同、内容相同、到达时间接近。处理方式最简单:以 eventId 为键做唯一约束。
队列重投。 消费者处理超时或崩溃,消息被重新投递。这类重复的 eventId 也相同,但可能已经被部分处理,比如写入了事件表却没有更新聚合表。处理方式是让「写事件」和「更新聚合」在同一个事务里,或者让聚合可以从事件表重算。
批任务重跑。 运营手动重跑某天的汇总,或者调度系统补跑失败分区。这类重复没有相同的 eventId,因为它是重新生成的聚合结果。处理方式不是去重,而是让聚合具备幂等性:按 (tenantId, date) 覆盖写,而不是追加写。
三种来源对应三种键:事件级用 eventId,聚合级用 (tenantId, date, unit),账单级用 (tenantId, period)。用错层级,去重就会失效。比如用 eventId 去重聚合结果,重跑时新生成的 eventId 不同,重复照样进账。
幂等键怎么构造
幂等键的作用是回答「这两条记录是不是同一件事」。构造方式决定了它能挡住哪些重复。
| 键的构造 | 能挡住的重复 | 挡不住的重复 | 适用层 |
|---|---|---|---|
eventId | 生产端重试、队列重投 | 批任务重跑 | 事件 |
tenantId + eventId | 跨租户 ID 碰撞 | 同一租户内的重跑 | 事件 |
tenantId + 业务自然键 + 时间窗 | 无稳定 ID 的补录 | 同一窗口内的合法多次 | 聚合 |
tenantId + 账期 | 重复出账 | 账期内的部分更正 | 账单 |
eventId 必须由生产端生成,并且在重试时保持不变。如果每次重试都生成新 ID,后面所有去重都无从谈起。
tenantId + eventId 比单用 eventId 更稳。事件 ID 可能由不同服务生成,命名空间不隔离时会有碰撞;加上租户维度,碰撞概率降到可以忽略。
自然键方案适合没有稳定 ID 的场景。比如 ClausePilot 的案件事件,可以用 tenantId + caseId + reviewRound 作为键。但自然键有一个陷阱:如果业务上允许同一案件同一轮次合法地产生多条事件,自然键就会误杀。用之前必须确认「这个组合在业务上唯一」。
账单层的键最简单,也最重要。tenantId + period 唯一,意味着一个客户一个账期只能有一张账单。重复出账是财务事故里最难解释的一类,因为客户会收到两张金额相同、编号不同的发票。
去重放在哪一层
去重可以放在入口、聚合、开票三个位置,每个位置解决不同的问题。
入口去重拦截重复投递。事件写入前检查键是否存在,存在就返回 duplicate,不写库。优点是成本最低,缺点是只能挡住「键相同」的重复,挡不住批任务重跑。
聚合去重保证同一时间窗只算一次。日聚合表用 (tenantId, date, unit) 做主键,重跑时覆盖写。优点是能挡住重跑,缺点是如果原始事件本身重复,聚合会把重复一起算进去。所以聚合去重不能替代入口去重。
开票去重是最后一道闸。出账前检查该账期是否已有账单,有则拒绝或进入人工复核。它不解决计量问题,只防止财务重复出账。
三层都要有,但职责不能混。最常见的错误是把三层合成一层:只在开票时查重,结果账单金额是对的,但用量页面和成本报表已经被重复数据污染;或者只在入口查重,批任务重跑后账单翻倍。
重试不是重复
这是计量设计里最容易混淆的一对概念。
重试是业务行为:一次推理失败,系统再调用一次,期望得到结果。重复投递是传输行为:同一条已经产生的事实,被送了两次。前者应该产生新的成本,后者不应该产生新的成本,也不应该产生新的收入。
LumenDesk 的重试率是 8%,Verba 是 3%,ClausePilot 是 11%。把它们折进有效成本:
LumenDesk:15,000 ÷ (1 − 0.08) = 16,304 micro-USD
Verba:4,200 ÷ (1 − 0.03) = 4,330 micro-USD
ClausePilot:65 ÷ (1 − 0.11) = 73.03 美元
这三个数应该进入成本模型,但不应该进入客户账单。客户不为供应商的重试付费,除非合同明确写了「按调用次数计费」。LumenDesk 和 Verba 都按成功单位计费,ClausePilot 按案件计费,重试成本由供应商吸收。
重复的代价随计费单位放大。LumenDesk 一条对话事件对应 0.015 美元成本,一百条重复是 1.50 美元;Verba 一分钟对应 0.008 美元收入与 0.0042 美元成本,一百条重复是 0.80 美元收入、0.42 美元成本;ClausePilot 一件案件对应 180 美元收入与 65 美元成本,一百条重复就是 18,000 美元收入和 6,500 美元成本。同样是「一百条」,在按案件计费的生意里足以变成一次账单争议。
所以事件里必须能区分「这是一次新尝试」和「这是同一条事实的第二次投递」。前者生成新的 eventId,billableQuantity 可以为 0、costQuantity 为 1;后者复用原 eventId,整条事件被拒绝。
如果两者用同一个字段表达,系统就只剩一个选择:要么把重试算进账单,要么把重试成本丢掉。两种都会让毛利失真,前者得罪客户,后者欺骗自己。
补录:晚到事件的窗口
事件不会都在计费时点准时到达。生产端可能离线缓存了几个小时,队列可能积压,跨区域传输可能延迟。补录机制就是给这些晚到事件一个合法的入口。
补录的第一个参数是窗口长度。窗口太短,晚到事件被拒绝,收入漏记;窗口太长,账期已经关掉,补录只能走人工调账。窗口应该覆盖「处理时长 + 传输重试」的 P99,而不是拍一个整数。
第二个参数是截止后的处理方式。超过窗口的事件不能直接丢,通常有三种选择:
- 拒绝并记录,进入人工队列,由运营判断是否补账。
- 接受但标记
late,计入下一个账期,并在报表里单列。 - 接受并回溯修正当前账期,重算聚合并生成调整单。
三种方式对应三种业务约束。LumenDesk 按月结算,月末关账后回溯修正的成本很高,适合第二种;ClausePilot 的客单价高,3,230 件里漏一件就是 180 美元收入,适合第三种,但必须配套调整单和审计记录。
补录还要防止「补录风暴」。如果某个上游系统停机一天,恢复后会把积压的几十万条事件一次性推过来,聚合任务可能被打爆。生产端应该做限速和分批,消费端应该能按时间窗分批重算,而不是要求一次事务处理完。
更正:只追加,不覆盖
发现一条事件记错了,最直觉的做法是改掉它。这个做法在计量系统里是禁止的。
原因不是技术洁癖,而是可解释性。客户下个月问「为什么上个月账单变了」,如果原始记录被覆盖,系统无法回答「原来是多少、为什么改、谁改的」。审计时同样无法证明数据的完整性。
正确做法是补偿式更正:原始事件保持不动,新增一条金额为负或正的调整事件,引用原事件 ID,写明原因。账务上的净额等于原始值加调整值。
补偿式更正有三个好处。第一,任何时点的余额都可以通过重放事件得到,不需要备份历史版本。第二,更正本身是一条审计记录,谁在什么时候因为什么改了账,一目了然。第三,错误可以被统计,团队能看出哪类事件最容易错,从源头修。
代价是查询变复杂。账单不能只读一张表,要把原始事件和调整事件一起聚合。这个代价是值得的,因为计量系统的第一属性是可解释,第二才是查询快。
代码:幂等摄入与补偿更正
下面的代码实现三个动作:用幂等键摄入事件、把晚到事件标记为 late、用新增条目表达更正。账本是一个 Map,键是幂等键,重复到达直接返回 duplicate,不覆盖原条目。
// file: src/ops/06-2-idempotency.ts
// tier: L1
// verify: node --test test/ops/06-2-idempotency.test.ts
// 幂等摄入:重复投递只落一笔,晚到事件进入补录,更正一律新增条目。
import { type Cents } from "../core/money.ts";
import { type Bps, FULL } from "../core/rate.ts";
export type LedgerEvent = {
eventId: string; tenantId: string; billableQuantity: number;
costMicros: number; occurredAt: string;
};
export type LedgerEntry = LedgerEvent & {
key: string; receivedAt: string; status: "accepted" | "late";
};
export type Ledger = { entries: Map<string, LedgerEntry> };
export type IngestStatus = "accepted" | "late" | "duplicate";
export const BACKFILL_CUTOFF_HOURS = 72;
export function createLedger(): Ledger {
return { entries: new Map() };
}
/** 幂等键由租户与事件 ID 组成,与到达次数和时间无关。 */
export function idempotencyKey(event: LedgerEvent): string {
return `${event.tenantId}:${event.eventId}`;
}
/** 首次到达落账;重复键直接返回 duplicate,不覆盖已有条目。 */
export function ingest(ledger: Ledger, event: LedgerEvent, receivedAt: string): IngestStatus {
const key = idempotencyKey(event);
if (ledger.entries.has(key)) return "duplicate";
const lagHours = (Date.parse(receivedAt) - Date.parse(event.occurredAt)) / 3_600_000;
const status = lagHours > BACKFILL_CUTOFF_HOURS ? "late" : "accepted";
ledger.entries.set(key, { ...event, key, receivedAt, status });
return status;
}
/** 补录一条更正:在原条目之外新增,保留原始事实。 */
export function correct(
ledger: Ledger, targetKey: string, deltaQuantity: number,
deltaCostMicros: number, receivedAt: string,
): LedgerEntry {
const target = ledger.entries.get(targetKey);
if (!target) throw new Error("目标条目不存在");
const entry: LedgerEntry = {
...target,
key: `${targetKey}:adjust:${ledger.entries.size}`,
billableQuantity: deltaQuantity,
costMicros: deltaCostMicros,
receivedAt,
status: "late",
};
ledger.entries.set(entry.key, entry);
return entry;
}
/** 有效单位成本 = 名义单位成本 ÷ (1 − 重试率)。 */
export function effectiveCostMicros(unitCostMicros: number, retryBps: Bps): number {
if (retryBps >= FULL) throw new Error("重试率必须低于 100%");
return Math.round((unitCostMicros * FULL) / (FULL - retryBps));
}
export function totals(ledger: Ledger): { billable: number; costMicros: number } {
let billable = 0;
let costMicros = 0;
for (const entry of ledger.entries.values()) {
billable += entry.billableQuantity;
costMicros += entry.costMicros;
}
return { billable, costMicros };
}
/** 被拦下的重复事件本会产生的成本,单位美分。 */
export function dedupeSavingsCents(duplicateCount: number, costMicros: number): Cents {
return Math.round((duplicateCount * costMicros) / 10_000);
}
ingest 先查键,再判断延迟小时数。超过 72 小时的事件仍然落账,但状态是 late,方便后续单独统计和决定是否进入下一个账期。
correct 不修改原条目,而是复制原事件的维度,写入新的数量和成本增量,键加上 :adjust: 后缀。这样 totals 自然把调整算进去,原始事实仍然可查。
effectiveCostMicros 把重试率折进单位成本,dedupeSavingsCents 把拦下的重复换算成金额。后者是给运营看的:一天拦下多少重复、值多少钱,比「去重成功率 99.9%」更有说服力。
对账:三张表要能对上
幂等做得好不好,最终要靠对账验证。至少要有三张表:
- 接收表:所有到达的事件,包括重复和被拒绝的,用于计算重复率。
- 账本表:去重后实际计费的事件,用于生成账单。
- 聚合表:按租户、账期、单位汇总的结果,用于报表和毛利分析。
三张表的数量关系应该稳定:
接收量 = 账本量 + 重复量 + 拒绝量
账本聚合 = 账本明细之和
账单金额 = 账本聚合 × 价格表
第一条不平,说明有事件在入口丢失或状态未记录;第二条不平,说明聚合逻辑有 bug;第三条不平,说明价格版本或额度规则不一致。三条都平,才能关账。
对账频率建议按天,而不是按月。月末才发现重复,已经错过了修正窗口;按天对账,问题能在 24 小时内定位到具体批次。
幂等系统的验收
验收幂等不能只看代码,要真的制造重复。
重投测试。 把同一批一百条事件投递两次,账本数量不变。LumenDesk 一百条对话是 100 × 0.015 = 1.50 美元成本,重复后如果变成 3.00 美元,说明入口去重失效。
重跑测试。 把某天的聚合任务跑两次,聚合结果不变。这一条挡住的是批任务重跑,入口去重管不到。
乱序测试。 把事件按时间倒序投递,最终聚合结果与正序一致。计量事实不应该依赖到达顺序。
更正测试。 对一条已计费事件做负向调整,总额下降、原始记录仍在、审计链完整。
四条测试都能通过,才算具备「至少一次投递、恰好一次计费」的能力。
小结
- 计量管道的默认语义是至少一次,重复不是 bug,而是必须被设计接住的前提。
- 重复来自生产端重试、队列重投、批任务重跑,三者要分别用事件键、聚合键、账单键处理。
- 幂等键必须由生产端生成并在重试中保持不变,
tenantId + eventId比单用事件 ID 更稳。 - 去重分入口、聚合、开票三层,任何一层都不能替代另外两层。
- 重试产生新成本但不是新计费:8% 让 LumenDesk 有效单次成本升到 16,304 micro-USD,11% 让 ClausePilot 升到 73.03 美元。
- 补录窗口覆盖处理与传输的 P99,超窗事件要么进人工队列,要么标记 late 进下一账期。
- 更正只追加不覆盖,原始事实、调整条目与原因共同构成可解释的账。
- 用接收表、账本表、聚合表三方对账,按天而不是按月发现重复与缺口。
阅读导航:上一节:6.1 计量事件的设计 · 下一节:6.3 用量数据的审计轨迹 。
常见错误与边界
- 假设上游只会投递一次,入口不做唯一约束,重复直接进账,月末靠人工冲销。
- 每次重试都生成新的
eventId,幂等键失效,去重逻辑看起来存在但从不生效。 - 把重试当成重复直接丢弃,成本凭空消失,毛利被高估。
- 只在开票层查重,账单金额对了,但用量页面、成本报表和毛利分析已经被污染。
- 补录窗口拍成固定七天,既挡不住真正的晚到,又让关账后的调整无路可走。
- 发现记错就改原记录,审计时无法回答「原来是多少、谁改的、为什么改」。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。