Spring Boot on Renxin's Blog

第三话｜跨行清算对账：跟你跑通一个对账流水线，亲手拆解分布式一致性的工程骨架

Sun, 15 Feb 2026 00:00:00 +0000

A 从工行转 10,000 元给 B 的建行账户。工行 App 显示扣款成功，建行的到账短信也到了，两边客户看到的都是「成功」。

第二天日终对账跑完，报表上多出一行差异：建行侧这笔交易有两条分录（账本上的记账记录），B 的账户多出一万块。钱只转了一次。那条多出来的分录是哪来的？谁负责把它消掉？能自动消掉吗？

这三个问题，对账系统都得回答。而回答之前，得先知道这笔转账在哪几个地方各记了什么——它不是一个系统写一行数据，是三个互不信任的系统各写各的账。

GYD 这个系列讲分布式系统里各种解决方案的实现方式。上一篇讲了消息队列的可靠投递——一条消息从发出到被处理，中间可能死在三段里。当消息可靠地到达了，新的问题浮现：两边的账还是可能对不上，你怎么发现、怎么分级处理、怎么修正？

对账这件事，本质上不是在检查「账有没有记错」——它是在问一个更根本的问题：在没有全局一致性的分布式环境里，你用什么手段去证明系统的状态是对的？

建一个最小可行的对账流水线：两个银行服务、各自的借贷账本、一个模拟结算服务、一个日终对账 Job。跑起来，亲手看到对账怎么发现差异、怎么分级决策、怎么追加式更正。不追求完整银行核心系统——那太大了——而是聚焦对账最核心的口径、匹配和分级处理。

一、一笔跨行转账，动了三个账本

回到那笔 10,000 元。表面上看，就是工行的一个账户余额减了，建行的一个账户余额加了。但这个简化版本漏掉了最关键的一环：银行间的结算。

先说清一件容易被跳过的事：工行不会用运钞车把一万块现金送到建行。银行之间的「钱」，是它们在央行开的账户里的数字。每家商业银行都在央行有一个结算账户——好比公司里每个部门都在财务总部存了一笔备用金，跨部门的结算由总部在这个池子里挪数字。

所以一笔跨行转账，实际有三个记账主体，各自维护一个独立数据库，互相看不到对方的账：

记账主体	账本上记的是什么	谁维护
工行核心系统	A 的客户存款 + 工行存放央行的钱	工行
央行支付系统	工行结算账户 + 建行结算账户	央行
建行核心系统	建行存放央行的钱 + B 的客户存款	建行

三幕记账

时间线上分三幕，每一幕各写一组分录。分录（journal entry）就是账本上的一行记账记录，它的约束第二节细讲。

第一幕：A 点转账，工行记账。 工行校验 A 余额充足，在自己的账本上写入两条：A 的客户存款减少一万，工行存放央行的钱减少一万。此时钱还没易手，只是工行单方面记下了「我要付一万出去」。

第二幕：工行把支付指令发给央行，央行记账。 央行检查工行结算账户余额够不够，够则同时改两户：工行的结算账户减一万，建行的结算账户加一万。这一步完成，银行间资金交割就「最终」了——在央行的制度里这叫结算最终性，记入央行账户后不可撤销。

第三幕：央行通知建行，建行记账。 建行收到入账通知，确认 B 账户状态正常，在自己的账本上写入两条：建行存放央行的钱增加一万，B 的客户存款增加一万。之后建行回执、工行给 A 弹「转账成功」——那是通知，不是记账。

%%{init: {'theme':'neutral'}}%%
sequenceDiagram
 autonumber
 participant A as A（工行客户）
 participant ICBC as 工行核心系统
 participant PBC as 央行支付系统
 participant CCB as 建行核心系统
 participant B as B（建行客户）

 A->>ICBC: 发起转账 10,000 元
 ICBC->>ICBC: 记账：客户存款-A 减 / 存放央行 减
 ICBC->>PBC: 支付指令
 PBC->>PBC: 记账：结算存款-工行 减 / 结算存款-建行 加
 Note over PBC: 资金真正易手，结算最终性成立
 PBC->>CCB: 入账通知
 CCB->>CCB: 记账：存放央行 加 / 客户存款-B 加
 CCB-->>B: 到账短信
 ICBC-->>A: 转账成功

三幕走完，四个账户余额发生了变化：A 的存款 −1 万、工行在央行的结算户 −1 万、建行在央行的结算户 +1 万、B 的存款 +1 万。钱没有消失也没有多出，只是欠条链条换了人。

同一个结算账户，在两个账本里性质相反

这里有一处最容易绕晕，说透了后面全通：工行在央行的那个结算账户，在工行账本上是资产，在央行账本上是负债。

就像你的工资卡余额——对你自己记「别人欠我一万」，对银行记「我欠客户一万」。同一笔债，两边各记各的，谁也没错。所以第二幕里，央行记的是「结算存款—工行」减少，因为那是央行欠工行的钱变少了；而第一幕里，工行记的是「存放央行款项」减少，因为那是工行存在别人那里的钱变少了。两笔指的是同一件事，但记在两个不同的数据库里，用两个方向相反的科目名。

对账要跨的就是这种缝：三本账各记各的，同一个事实在不同账本里长得完全不一样。

为什么裁判只能是央行

既然工行和建行各记各的账，为什么不能两边互相对一下就完事？

假设只让两家互对：工行说「我转了」，建行说「我没收到」，信谁？两家都是这笔交易的利益相关方，漏记、错记的一方有动机把责任推给对方。更糟的情况是两边都记错了——比如入账通知丢失导致两边都没入账，互对反而「对平了」，两家错得整整齐齐，谁也不知道出了问题。

央行不一样：它在这笔交易里没有利益瓜葛，而且是资金真正动过的那个地方。第一幕和第三幕都只是各家自己账本上的数字变化，第二幕才是钱真的易手。既然「钱到底转没转成」这个动作只发生在央行账上，这个问题的裁判也只能是央行账。

这就是「两方互对只能发现不一致，三方核对才能判定哪边不一致」的由来：工行建行互对，发现差一万，吵不清谁错；拿出央行记录一看「总部说转了一万」，立刻知道是哪家的小账本没记上。

这条判断抽掉金融外壳也成立——谁是那个动作真正发生的地方，谁的数据就是事实；两边平票时，找一个改它记录对自己没好处的第三方。 支付公司和微信对账以商户平台账单为准，电商和物流对账以仓储出库记录为准，都是同一个道理。

三幕链条会断在哪里

三幕跨越三个数据库、靠异步消息传递，没有任何全局事务能保证三步原子完成。断点至少有三个：

断在哪	后果	对账看到的现象
第一幕成功、指令没发出去	工行扣了 A 的钱，央行和建行都没动静	付款行有分录、结算侧无记录
第二幕成功、入账通知丢了	钱已到建行在央行的户头，但 B 没到账	结算已确认、收款行漏记
通知重复投递、消费端没做好幂等	B 到账两万	同一笔交易在收款行有重复分录

开篇那个场景就是第三种。记住这三种断裂方式，第四节的差异分类表就不是凭空冒出来的分类，而是这三个断点的直接映射。

demo 的架构

三幕在 demo 里的落点：

%%{init: {'theme':'neutral'}}%%
flowchart LR
 ICBC["工行服务
客户存款账本"]
 CCB["建行服务
客户存款账本"]
 SETTLE["模拟结算服务
清算结果记录"]
 MQ["RabbitMQ
清算通道"]
 RECON["对账 Job
日终逐笔匹配"]
 
 SETTLE -->|"分别投递"| MQ
 MQ -->|"消费记账"| ICBC
 MQ -->|"消费记账"| CCB
 RECON -->|"REST 拉取当日数据"| ICBC
 RECON -->|"REST 拉取当日数据"| CCB
 SETTLE -.->|"对账 Job 同进程
直接读本地库"| RECON

模拟结算服务充当那个「央行的角色」，产生每笔转账的清算结果。RabbitMQ 只是传递这些指令的通道——它不代替结算服务的权威性。对账 Job 从两家银行各拉一份数据，再加上自己进程内的结算记录，凑齐三方才能进入真正的匹配逻辑。

有一处和真实世界的差异要说清楚：现实中是「工行主动向央行发指令，央行结算后通知建行」，方向和顺序都固定；demo 里是结算服务生成结果后通过 RabbitMQ 分别投递给两家银行记账，两家都是被动消费。方向不同，但「三方各记各账、靠同一个交易流水号关联」的骨架一致。

二、单方账本的约束：借贷记账法的边界

在讲跨行对账之前，先要弄清楚一件事：一家银行自己的账本，凭什么说自己是「自洽」的？

答案是一套五百多年前发明的记账规则：借贷记账法（Double-Entry Bookkeeping）。

先把三个词落地

上一节说「工行写入两条」，那两条长什么样？要看懂它，得先落地三个词。

科目：账本上的分类抽屉。银行账本上不写「张三」「李四」，而写「客户存款」「存放央行款项」这样的类别，每一类是一个科目，下面再挂具体账户。第一节里工行记的那两条，科目分别是「客户存款」和「存放央行款项」。

资产和负债：「存放央行款项」是资产——钱存在别人那里，是别人欠银行的。「客户存款」是负债——客户存进来的钱是银行欠客户的，客户随时可以取走。你存 1 万，是银行欠你 1 万，这笔钱在银行账上从来不是「银行的钱」。

借和贷：跟借钱、贷款没有任何关系。它们是会计里的两个方向符号，相当于左和右，五百年前意大利商人记账时定下的习惯，沿用至今。方向怎么定，规则只有两条：

	增加记	减少记
资产	借	贷
负债	贷	借

有了这两条，第一幕那两条分录就能自己读通了：客户存款是负债，减少记借；存放央行是资产，减少记贷。第三幕反过来：存放央行是资产，增加记借；客户存款是负债，增加记贷。

借贷记账法做了什么

每笔账务交易，必须至少产生两条分录——一条记借方（Debit），一条记贷方（Credit），这两条的总金额相等、方向相反。

转账那笔 10,000 元，在工行侧产生的分录是：

方向	科目	金额
借	客户存款（负债减少）	¥10,000
贷	存放央行款项（资产减少）	¥10,000

两条分录的金额相等，借贷平衡。把工行所有账务分录的借方加总、贷方加总，两者必须相等——这就是「试算平衡」。

为什么钱必须记成对？因为钱不会凭空出现——它一定是「从某处来、到某处去」。只记「A 少了一万」而不记「这一万去了哪」，账本就没交代这笔钱的去向。借贷成对，等于强制每一笔都写清来源和去向。

这个约束的价值在于：任何一笔账务操作，要么借方和贷方一起写入（交易提交），要么一起不写（交易回滚）。 数据库的原子提交保证了这一点。所以「借记了一笔但忘了记对应的贷方」在正常运行的系统中不会发生——要么都记，要么都不记。

在 demo 里，这个约束落在 LedgerService.postEntries 上——它接收一组分录，校验借贷平衡后在同一事务写入：

// bank/LedgerService.java（节选）
@Transactional
public void postEntries(List<JournalEntry> entries) {
 // 校验借贷平衡：借方合计必须等于贷方合计
 long debitSum = entries.stream()
 .filter(e -> e.getDirection() == Direction.DEBIT)
 .mapToLong(JournalEntry::getAmountCents)
 .sum();
 long creditSum = entries.stream()
 .filter(e -> e.getDirection() == Direction.CREDIT)
 .mapToLong(JournalEntry::getAmountCents)
 .sum();

 if (debitSum != creditSum) {
 throw new UnbalancedException(debitSum, creditSum);
 }

 // 借贷平衡 + 原子提交：所有分录在同一事务中写入
 repo.saveAll(entries);
}

注意两处和直觉不同的地方：

金额用的是 long（最小货币单位「分」），不是 BigDecimal 也不是浮点。这不是「贬低 DECIMAL」——DECIMAL 本身是精确的定点数，银行系统里也广泛使用。demo 选 long 分是因为它足够表达整数金额、且避免了跨语言序列化时定点数精度不一致的坑。这是工程取舍，不是「浮点不安全所以只能选 long」。
借贷平衡的校验在应用层完成，PostgreSQL 的普通 CHECK 约束无法跨行校验「借方合计 == 贷方合计」——CHECK 只能约束单行的取值范围。这是数据库约束的边界，需要应用层补上。

借贷平衡 + 原子提交，保证了单方账本不会出现「凭空多了一笔钱或凭空少了一笔钱」。但它的保护范围到此为止。

借贷平衡不能发现的问题

试算平衡验证的是账务的内部自洽性，不是业务正确性。以下四类错误，账都是平的——借贷合计仍然相等：

整笔漏记：转账根本没入账。借方和贷方都没有，当然平衡。
整笔重复入账：同一笔转账被记了两次。第一次的借贷平衡，第二次的借贷也平衡，两次合起来仍然平衡。
记错科目：本该借记客户存款，却借记了另一个负债科目。借贷合计对得上，但客户的实际余额不对。
两侧金额同时记错：本来该记 10,000 元，两侧都记成了 1,000 元。借贷平衡，金额错误。

这四类正好覆盖第一节那三个断点：指令没发出去是整笔漏记，通知重复投递是整笔重复入账。它们全是异步链条的正常故障模式，而在单方账本上全都是「平的」——这就是为什么必须有跨方核对。

试算平衡就像一道数学题的自检验算——能证明「我的计算过程没有低级算术错误」，但不能证明「我的算式列对了」。要证明「列对了」，需要和外部数据进行比对。这就是对账要解决的。

%%{init: {'theme':'neutral'}}%%
flowchart TB
 subgraph PASS["「平了」但有问题"]
 direction LR
 P1["整笔漏记"]
 P2["整笔重复"]
 P3["记错科目"]
 P4["金额同时记错"]
 end
 subgraph FAIL["「不平」才是报警"]
 direction LR
 F1["单侧多记"]
 F2["金额单侧偏差"]
 end
 CHECK["借贷平衡校验"] --> PASS
 CHECK --> FAIL

这张图的核心信息是：不要以为账平了就万事大吉。平了只说明单方账簿没有算术错误。对账就是去验证「平了的那几行，是不是真的对应了一笔正确的交易」。

三、实时处理与周期核对可以并存

在讲对账逻辑之前，需要先澄清一个容易混淆的话题：什么时候对账？ 很多人把「清算的实时性」和「对账的时效」混为一谈。

先用一个生活类比把三个词分开。你和同事这个月互相请客：算清楚「他欠我 80 块」是清算，他真的微信转你 80 是结算，月底翻聊天记录和账单确认「确实是 80，不是 180，也没重复算」是对账。

维度	在做什么	时效
清算（Clearing）	计算各方的应收应付义务	HVPS（大额支付系统）逐笔实时，BEPS（小额支付系统）批量轧差
结算（Settlement）	通过资金账户完成义务清偿	大额实时，小额定时净额
对账（Reconciliation）	核对各方记录是否一致	可以是日终批次、小时批次或准实时

清算和结算发生在交易当时（第一节的第二幕），对账发生在事后。这个时间差就是对账存在的全部理由——当时没人能保证三本账都写对了，只能事后摊开来核。

大额支付系统（HVPS）逐笔实时全额清算，每笔大额转账完成时就已经决定了各家银行的应收应付义务，银行间的结算也是实时的。小额支付系统（BEPS）用批量轧差——工行今天欠建行 80、建行欠工行 50，不必转两次，轧一下只转净差额 30；把一段时间里所有小额交易的借方和贷方分别汇总，只结算这个净额。

但不管清算和结算是实时的还是批量的，对账这件事都不一定跟它们同步。对账的时效是一个独立的工程选择，取决于你愿意在多大延迟内发现差异、差异出现时系统里堆积了多少未核对数据。

网联清算平台的做法很有代表性：它的交易是实时转接的，但对账按小时切分成多个批次，每个批次独立处理。好处是把一天的量打散到 24 小时里分别核对，避免了日终集中处理的性能洪峰，也让差异能在小时内被发现、而不是等到第二天。

我们这个 demo 选择日终批次。 不是因为「银行都是这样做的」，而是因为日终批次是理解对账口径最清晰的模型：定义一个业务日的截止点，拉取那一天的完整数据，逐笔匹配，对所有差异做出分类和处理。至于这个「日」是 24 小时、1 小时还是一刻钟，口径不变，只改调度频率。

四、简化对账流水线的实现

好了，原理讲完，开始跑代码。整个 demo 的结构如下：

服务清单

服务	职责	对应第一节哪个角色	端口
`gyd-c03-settlement`	模拟结算服务：生成每笔转账的清算结果记录	央行（第二幕的记账者 + 权威记录源）	18080
`gyd-c03-bank`（bank-a profile）	付款行（工行）：维护客户存款账本，消费清算指令记账	工行（第一幕）	18081
`gyd-c03-bank`（bank-b profile）	收款行（建行）：维护客户存款账本，消费清算指令记账	建行（第三幕）	18082
`ReconJob`（结算服务内的组件）	对账任务：定时拉取三方数据，逐笔匹配，分级处理差异	事后核对，不属于三幕	随结算服务同进程（Spring Scheduler）

三个业务服务各自有独立的 PostgreSQL 数据库，中间通过 RabbitMQ 传递清算指令。对账 Job 随结算服务一起运行——它直接读本进程内的结算记录表（权威数据源），银行侧的分录则通过 REST API 拉取。

数据库表设计

每家银行的账本结构相同：

-- 账务分录表（append-only，已入账的行永不修改）
CREATE TABLE journal_entry (
 id BIGSERIAL PRIMARY KEY,
 entry_id VARCHAR(64) NOT NULL UNIQUE, -- 业务流水号
 trade_id VARCHAR(64) NOT NULL, -- 清算指令 ID（关联结算记录）
 account_id VARCHAR(32) NOT NULL,
 direction VARCHAR(6) NOT NULL CHECK (direction IN ('DEBIT', 'CREDIT')),
 amount_cents BIGINT NOT NULL, -- 金额，最小货币单位（分）
 trade_time TIMESTAMPTZ NOT NULL, -- 业务发生时间
 booked_at TIMESTAMPTZ NOT NULL, -- 记账时间（应用层 Instant.now() 写入）
 reversal_of VARCHAR(64) -- 若为冲正分录，指向被它抵销的那条原始分录（第六节细讲）
);

CREATE INDEX idx_entry_trade ON journal_entry(trade_id);
CREATE INDEX idx_entry_booked ON journal_entry(booked_at);

模拟结算服务的数据库：

-- 清算结果表
CREATE TABLE settlement_record (
 id BIGSERIAL PRIMARY KEY,
 trade_id VARCHAR(64) NOT NULL UNIQUE, -- 清算指令 ID
 from_bank VARCHAR(16) NOT NULL,
 to_bank VARCHAR(16) NOT NULL,
 amount_cents BIGINT NOT NULL,
 settled_at TIMESTAMPTZ NOT NULL, -- 结算完成时间
 status VARCHAR(16) NOT NULL -- 结算状态，SETTLED = 已结算（应用层默认）
);

几个关键设计决策：

金额用 BIGINT 存分（最小货币单位），不是浮点。浮点确实不能用于金额——多笔累加后的舍入误差会制造假差异。但 DECIMAL 本身是精确的定点数，银行系统里也广泛使用，这里选 BIGINT 分而不是 DECIMAL，是为了让跨语言（Java ↔ SQL ↔ JSON）序列化时金额精度完全一致，减少一个出错面。这是取舍，不是说 DECIMAL 不能用。
entry_id 是业务身份。这是对账匹配的核心——同一个 trade_id 在付款行和收款行各自产生分录，各自的 entry_id 不同，但都关联到同一个 trade_id。对账靠 trade_id 匹配。
reversal_of 链。冲正分录指向被冲正的原始 entry_id，形成完整的更正链路。对账的闭环验收靠这个字段追溯。

对账 Job 的核心逻辑

对账 Job 定时执行（demo 里用 fixedDelay，方便跑起来立刻看到结果），拉取当日的完整数据：

// settlement/recon/ReconJob.java（节选，完整代码见仓库）
@Scheduled(fixedDelayString = "${gyd.c03.recon.schedule-ms:60000}",
 initialDelayString = "${gyd.c03.recon.initial-delay-ms:30000}")
public void run() {
 LocalDate today = LocalDate.now();
 Instant start = today.atStartOfDay(ZoneOffset.UTC).toInstant();
 Instant end = today.plusDays(1).atStartOfDay(ZoneOffset.UTC).toInstant();

 // 1. 拉取三方数据（银行通过 REST，结算记录直接查本地库）
 List<SettlementRecord> settlements = settlementRepo.findSettledBetween(start, end);
 List<JournalEntry> bankAEntries = fetchBankEntries(bankAUrl, start, end);
 List<JournalEntry> bankBEntries = fetchBankEntries(bankBUrl, start, end);

 // 2. 以 trade_id 为键建立三方索引
 Map<String, List<JournalEntry>> aByTrade = groupByTrade(bankAEntries);
 Map<String, List<JournalEntry>> bByTrade = groupByTrade(bankBEntries);
 Map<String, SettlementRecord> settlementMap = settlements.stream()
 .collect(Collectors.toMap(SettlementRecord::getTradeId, s -> s));

 Set<String> allTradeIds = new HashSet<>(settlementMap.keySet());
 allTradeIds.addAll(aByTrade.keySet());
 allTradeIds.addAll(bByTrade.keySet());

 // 3. 逐笔匹配：结算侧无记录单独判，其余交给 checkBank 按科目核对
 List<ReconDiff> diffs = new ArrayList<>();
 for (String tradeId : allTradeIds) {
 SettlementRecord settlement = settlementMap.get(tradeId);
 List<JournalEntry> aEntries = aByTrade.getOrDefault(tradeId, List.of());
 List<JournalEntry> bEntries = bByTrade.getOrDefault(tradeId, List.of());

 if (settlement == null) {
 // 银行有分录、结算侧查不到已结算记录 → 待查，不自动修正
 if (!aEntries.isEmpty()) {
 diffs.add(new ReconDiff(tradeId, ReconDiffType.NO_SETTLEMENT,
 Bank.ICBC.code(), entryIds(aEntries), -1, 0));
 }
 if (!bEntries.isEmpty()) {
 diffs.add(new ReconDiff(tradeId, ReconDiffType.NO_SETTLEMENT,
 Bank.CCB.code(), entryIds(bEntries), -1, 0));
 }
 continue;
 }

 checkBank(aEntries, settlement, Bank.ICBC, tradeId, diffs);
 checkBank(bEntries, settlement, Bank.CCB, tradeId, diffs);
 }

 // 4. 分级处理差异（processDiff 按类型决策）
 for (ReconDiff diff : diffs) {
 processDiff(diff, settlementMap);
 }

 // 5. 闭环验收
 verifyClosedLoop(diffs, settlementMap, start, end);
}

checkBank 里的匹配规则：

结算侧有没有记录，在主循环里单独判，不在 checkBank 里：findSettledBetween 已经过滤掉非 SETTLED 的记录，所以「银行有分录、结算侧查不到」直接标 NO_SETTLEMENT（待查）。checkBank 只负责单侧的逐科目核对。
本行的角色从结算记录的 fromBank / toBank 推导，不写死「工行一定是借方」——反向交易（建行付给工行）时，两个科目的方向会整体反过来。
按科目逐个核对，不是只看一个方向：本行这笔交易应该在「客户存款」和「存放央行款项」上各有一条净分录，预期方向由 account.directionFor(movement) 推导。
金额以结算记录为准（权威数据源）。某科目上没有分录 → MISSING；多于一条净分录 → DUPLICATE；方向与预期不符 → DIRECTION_MISMATCH；金额不符 → AMOUNT_MISMATCH。
只比「净分录」——已被冲正的原始分录不参与匹配，这一步在银行侧的查询里就完成了（findNetByBookedAtBetween）。
金额不作为唯一匹配依据——如果金额匹配但 trade_id 不匹配，这不是同一笔交易。

匹配结果的分类：

结算记录	付款行分录	收款行分录	分类
有、状态=SETTLED	有、金额匹配	有、金额匹配	✅ 平
有、状态=SETTLED	无或金额不匹配	有	付款行漏记/金额偏差
有、状态=SETTLED	有	无或金额不匹配	收款行漏记/金额偏差
有、状态=SETTLED	方向与角色不符（金额对得上）	同左	方向记反（`DIRECTION_MISMATCH`）
有、状态=SETTLED	重复（同一 trade_id 多笔）	—	付款行重复入账
有、状态=SETTLED	—	重复（同一 trade_id 多笔）	收款行重复入账
无或状态≠SETTLED	—	—	待查：结算结果未知
有、状态=SETTLED	在途（trade_time 在截止点附近）	—	等待：数据可能尚未齐备

最后一行的「在途」指交易已经发起、但三幕还没走完的状态——比如第一幕工行记了账，第三幕的入账通知还在路上。这类记录不是错误，只是数据还没齐，下一批次再核。

这里有一处代码与表格的落差，直说：IN_FLIGHT（在途）作为差异类型和处理分支是存在的——processDiff 对它只发 [P2][在途] 告警、不动账，闭环验收也不把它算进失败——但 checkBank 当前并不会主动产出这一类差异。它实际判定的是 MISSING（漏记）、DUPLICATE（重复入账）、DIRECTION_MISMATCH（方向记反）、AMOUNT_MISMATCH（金额不符）四类，主循环另判 NO_SETTLEMENT（结算侧无记录）。主动判定在途需要一套「交易发起时间 vs 对账截止点」的口径规则，属于对账口径设计，留到讲口径的那一篇。

五、差异不是错误：分级处理，不是统一冲正

对账最容易被误解的地方是：发现了差异，不代表知道了问题。 差异只是一个信号——两侧记录不一致。至于不一致的原因，是漏记、多记、记错、还是数据还没到，对账本身无法区分。

回到开篇那个场景：报表上说建行侧多了一条分录。这条信息只告诉你「两边对不上」，它没告诉你该不该动、动哪一条、动了之后钱会不会退回去。

分级决策模型

对账 Job 对差异的处理不是「有一个差异就冲一笔」。它先判断这个差异的类型，再做对应动作：

%%{init: {'theme':'neutral'}}%%
flowchart TB
 DIFF["对账发现差异"]
 
 DIFF --> Q1{"结算侧
有对应记录？"}
 Q1 -->|"无"| WAIT1["待查：标记为 pending
下一批次重新核对"]
 Q1 -->|"有"| Q2{"结算状态
是 SETTLED？"}
 
 Q2 -->|"否"| WAIT2["等待：交易仍在途
下一批次重新核对"]
 Q2 -->|"是"| Q3{"哪一侧
不一致？"}
 
 Q3 -->|"付款行缺分录"| ACT1["补记：根据结算记录
补入借记分录"]
 Q3 -->|"收款行缺分录"| ACT2["补记：根据结算记录
补入贷记分录"]
 Q3 -->|"金额不符"| ACT3["挂起：查证原指令
人工裁决后修正"]
 Q3 -->|"重复入账"| ACT4["挂起：无法判断哪组多余
人工裁决后冲正"]

这个决策树的每一层都依赖一个前提：结算记录是权威数据源。 结算侧说这笔钱该付、该转，那它就是事实。银行分录如果缺了、多了、金额错了，以此为基准修正。

但反过来，如果结算侧没有记录、或状态不是 SETTLED，对账 Job 不做任何自动修正——它记一条 NO_SETTLEMENT 差异，走 [P1][待查] 告警，等下一个批次重新核对。权威源缺位时，宁可什么都不做也不猜。

自动处理 vs 人工裁决

哪一类差异能自动处理？

漏记 + 结算已确认：结算侧明确有一笔成功的清算结果，但某家银行没有对应的分录。这是最干净的情况——补记即可。补记的「正确动作」完全由结算记录决定（补哪一侧、补多少金额），没有歧义。

哪些只能人工裁决？

重复入账：同一 trade_id 在同一侧出现了多条分录。trade_id 相同说明这是重复，但无法判断「哪一组是正确的那组、哪一组该冲正」——自动冲正必须回答「冲哪一组」，而这个答案对账本身给不出来。开篇那个场景就落在这里：程序知道建行侧多了一条，但不知道该消哪条。
金额不符：两边金额对不上，而且结算结果看不出金额是对是错（结算结果本身的金额也是参与方上报的）。需要回溯原始支付指令确认。
结算侧无记录：可能是延迟、系统故障，也可能是欺诈交易。不自动处理。

区分「能自动处理」和「只能人工裁决」的边界很清晰：当正确的修正动作能由权威数据源唯一确定时，可以自动处理；当存在多个可能的动作、或正确动作无法从数据里推断时，只能挂起等人裁决。 漏记的补记动作由结算记录唯一确定（补、补多少都明确），所以能自动做；重复入账要冲正哪一组、金额不符到底哪边错，都存在歧义，所以只能人工。

一个易混淆的点：本地账务的冲正和外部资金的退回是两件事。 银行发现一笔跨行转账记重了，冲正的是本地账本里的多余分录——这不会自动把钱从对方银行退回来。那笔钱已经通过央行结算，结算最终性成立后不可撤销；要追回得走独立的退款流程，需要对方银行配合。如果资金还没完成结算，另一条路是止付——让央行拦下这笔尚未落地的资金，不再继续结算。对账 Job 只处理本地账务的一致性，不管外部资金的流向。

// settlement/recon/ReconJob.java（节选）：补记漏记分录
private void compensateMissing(String bankUrl, ReconDiff diff, SettlementRecord s) {
 try {
 restTemplate.postForEntity(bankUrl + "/api/bank/compensate",
 Map.of("tradeId", diff.tradeId(),
 "fromBank", s.getFromBank(),
 "toBank", s.getToBank(),
 "amountCents", s.getAmountCents(),
 "settledAt", s.getSettledAt().toString()),
 String.class);
 log.info("[recon] 补记完成: tradeId={}, 银行={}, 科目={}, 金额=¥{}.{}",
 diff.tradeId(), bankLabel(diff.bankCode()), diff.account().label(),
 s.getAmountCents() / 100, s.getAmountCents() % 100);
 } catch (Exception e) {
 // 补记失败不能中断整轮对账：记下来，下一批次重新核出同一条差异再补
 log.error("[recon] 补记失败: tradeId={}, 银行={}", diff.tradeId(), diff.bankCode(), e);
 }
}

补记动作本身在银行侧执行（BankController.compensate），它复用和消费记账相同的 LedgerService，所以补记的分录同样受借贷平衡和幂等约束——补一笔漏记，也是补「一组」分录（客户存款 + 存放央行款项），而不是孤零零补一条。

六、冲正不是删除，是追加式更正

「发现错了，能不能把那条错的分录删掉？」这是很多工程师的第一反应。答案是：不能。 已入账的分录一旦写入，本 demo 的设计是禁止后续修改或删除的。

这不是保守，而是两道硬约束决定的：

审计追溯：外部审计师需要看到完整的账务变迁历史。原始记录消失，审计就失去了锚点。
修复幂等：如果允许删除原始记录然后重新写入，对账 Job 重复执行时就会把已修复的数据再次标记为差异，进入死循环。

纸质账本上也是同一个道理：用圆珠笔记的账，写死的字划不掉，记错了只能在下面补记一笔反向的，两笔抵消，但两条笔迹都留在本子上。冲正的做法就是这一条：写一组金额相等、方向相反的新分录，来抵销原分录的影响。 而且关键的是——冲正不是「逐条反」某一条 posting，而是按 trade_id 找到这笔交易的整组分录（客户存款 + 存放央行款项两条），一起反向。

为什么必须整组反向？因为借贷平衡是对「一组分录」的约束。只反其中一条，这一组就不平了，postEntries 的校验会直接把它拒掉。

// bank/LedgerService.java（节选）
@Transactional
public int reverseByTradeId(String tradeId) {
 return reverseEntries(repo.findOriginalByTradeId(tradeId));
}

/** 冲正的实际动作：为一组原始分录生成等额反向分录并写入 */
private int reverseEntries(List<JournalEntry> originals) {
 if (originals.isEmpty()) {
 return 0;
 }

 List<JournalEntry> reversals = new ArrayList<>();
 for (JournalEntry original : originals) {
 String reversalEntryId = "REV-" + original.getEntryId();
 // 已有冲正记录则幂等跳过：重复执行冲正不会写出第二组反向分录
 if (repo.findByEntryId(reversalEntryId) != null) {
 continue;
 }
 Direction revDir = original.getDirection().opposite();
 reversals.add(new JournalEntry(reversalEntryId, original.getTradeId(),
 original.getAccountId(), revDir, original.getAmountCents(),
 original.getTradeTime(), original.getEntryId()));
 }

 // 整组反向分录同样走 postEntries，受借贷平衡校验
 if (!reversals.isEmpty()) postEntries(reversals);
 return reversals.size();
}

冲正的入口有两个：整笔撤销走 reverseByTradeId，人工裁决「只冲多余那组」走 reverseByEntryIds——后者必须由人指定冲哪几条，因为重复入账时一个 trade_id 下有两组分录，整组冲正会把合法的那组也冲掉。两个入口共用 reverseEntries，所以幂等和借贷平衡的行为完全一致。

注意三个要点：

冲正必须保持借贷平衡。 原分录是借记客户存款 ¥10,000、贷记存放央行款项 ¥10,000，冲正分录是贷记客户存款 ¥10,000（反向）、借记存放央行款项 ¥10,000（反向）。不是孤零零写一条 posting。
reversal_of 指向原始分录。 对账闭环验收时，通过这个链条确认「差异 → 原始分录 → 冲正分录 → 重新核对平了」。
冲正只更正本地账务。 前面说了，外部支付已经发生了，冲正不改外部事实。

原始分录和冲正分录并排看（以工行付款侧为例，两条原始分录共享同一个 trade_id，但各有独立的 entry_id；trade_id 是 TRD- 加 8 位随机大写十六进制，entry_id 的末尾 CUST / PBOC 是科目标记）：

分录类型	分录 ID	方向	科目	金额	备注
原始	`E-TRD-2B14449D-ICBC-CUST`	借	客户存款	¥10,000	正常记账
原始	`E-TRD-2B14449D-ICBC-PBOC`	贷	存放央行款项	¥10,000	正常记账
冲正	`REV-E-TRD-2B14449D-ICBC-CUST`	贷	客户存款	¥10,000	抵销上面那笔借方
冲正	`REV-E-TRD-2B14449D-ICBC-PBOC`	借	存放央行款项	¥10,000	抵销上面那笔贷方

四条分录合在一起，净借贷合计仍然是 0。账平了，原始记录还在，审计师可以看到「发生过什么、怎么修正的」。

七、为什么对账不能替代幂等

对账是事后发现，幂等是事前防护。很多人觉得「有了对账就不需要幂等」，这个想法有一个根本性的问题：对账只能发现「结果不一致」，它不知道「不一致的原因」。

上一篇讲的消费端幂等，防的是「同一条消息被处理两次」；这里的对账，查的是「处理完之后三本账对不对得上」。两者在链路上前后相接：幂等让第一节的第三个断点（重复投递）尽量不发生，对账在它还是发生了之后把差异捞出来。

有业务身份，对账能做的远比「人工裁决」多

这个问题的关键不在于幂等键本身，而在于业务身份是否可追溯。 如果每一笔交易都有一个唯一的 trade_id，并且这个 ID 贯穿了从结算指令、银行分录、到对账匹配的整条链路，那么：

对账可以准确判断两笔相同金额的记录是不是同一笔交易的重复执行（因为 trade_id 相同）。
对账可以区分「两笔金额一样的合法交易」和「同一笔交易记了两次」。

反过来，如果系统里根本没有 trade_id 这样的业务身份，记账时只写了金额、方向和时间戳，那对账面对两条 ¥10,000 的借记分录时，完全无法判断这是一笔重复记账还是两笔独立的合法转账。

但即便有了 trade_id，重复入账的自动修复也不是理所当然的。trade_id 相同只能说明「这是同一笔交易产生了多余的分录」，却不能告诉你「哪一组是正确的那组、哪一组该冲正」。这也是为什么 demo 里对重复入账（DUPLICATE）的处理是标记人工裁决，而不是自动冲正——自动冲正必须回答「冲哪一组」，而这个答案对账本身给不出来。

幂等键的三个必要条件

幂等键（Idempotency Key）只是第一步。要让对账能做到自动修复，还需要三个条件同时满足：

消费端实际执行唯一性控制。 不是生产端带了一个键就叫幂等——消费端必须在写入前检查这个键是否已经处理过。如果消费端收到带相同键的消息直接再次写入，键就是摆设。
去重记录与账务写入在同一个事务中。 先检查去重再记账，中间断开事务，竞态条件下仍然可能重复写入。
同一键携带不同金额时能拒绝冲突。 如果一个键第二次出现时带的金额和第一次不同，系统应该拒绝而不是覆盖。

// bank/LedgerService.java（节选）：消费端的幂等写入
@Transactional
public boolean postIfNew(List<JournalEntry> entries) {
 String tradeId = entries.getFirst().getTradeId();
 // 幂等检查：这个 trade_id 已经记过账了？
 if (repo.existsByTradeId(tradeId)) {
 return false; // 幂等跳过，不重复写入
 }
 // 记账：去重检查 + 分录写入在同一事务中完成
 postEntries(entries);
 return true;
}

消费端 BankSettlementConsumer.onSettlement 调用它，收到重复消息时返回 false 直接跳过——这是正常的幂等跳过，不是错误，所以不抛异常、照常 ack。

核心结论：决定对账自动修复能力的，不是有没有幂等键，而是业务身份是否可追溯、以及能否据此确定「正确的动作」。 有可追溯的业务身份，对账可以精准定位差异、判断漏记并补记；但没有业务身份、或虽有身份却无法判断哪边该修正（比如重复入账该冲哪一组），对账就只能标记差异，等着人来看。幂等键是让「不产生重复」成为可能，而对账负责在「已经产生差异」时给出能追溯的处理。

八、从银行对账到分布式系统设计

对账这件事，拆开来看，其实是一个通用分布式系统的设计骨架。把前面几节里出现的核心设计模式抽象出来，它们都对应着分布式系统中反复出现的工程手段。

对账系统中的设计	解决的问题	分布式系统通用表达
借贷平衡约束	保证单方账本不自相矛盾	可校验的内部一致性：任何系统都应该有办法自证「状态没乱」，但不等于状态正确
业务身份（`trade_id`）	让对账能准确匹配同一笔交易	全局唯一请求标识：跨服务追踪、去重、匹配的基础
追加式更正（冲正）	修正错误而不破坏审计链	不可变日志 + 补偿操作：Saga 的补偿动作、Event Sourcing 的逆事件
第三方结算数据	提供独立的事实来源	外部权威数据源：跨系统对账不能只靠两方互对
分级处理决策树	不同差异不同动作	错误分类 + 分级恢复策略：在途、补记、冲正、待查各有对应的处理方式
对账 Job 的幂等设计	重复执行不对数据造成二次伤害	可重入任务：修复操作的结果是幂等的

这张表里的每一行，回到第一节的三幕链条上都有具体落点：借贷平衡管住一幕之内的自洽，trade_id 把三幕串成同一笔交易，冲正让改错不毁历史，结算记录提供跨幕的裁判，分级决策决定每种断裂怎么收场。

对账最大的工程价值：分离「发现」和「修复」

很多人把对账理解成「一个定时任务，跑完报一堆差异」。但它的工程价值不在「发现差异」——任何简单的比对脚本都能做到。对账的真正价值在于：

对账确定了「差多少」，分级处理确定了「怎么补回去」。 这两个问题被拆成两个独立的步骤，各自有独立的执行逻辑、独立的幂等保证。

这个分离是金融系统能在出错后继续运行的基石。如果发现差异的同时就「自动修正」，那修正错了怎么办？修正再修正？系统会陷入不可追溯的循环。但把它们分开——对账先给出一个不可变的事实陈述（「2026 年 9 月 14 日的日终核对显示，trade_id=TRD-2B14449D 在工行的客户存款科目上缺失分录」），然后分级处理再给出可追溯的修正动作（「根据结算记录补记分录 entry_id=COMP-TRD-2B14449D-ICBC-CUST」）——每一步的结果都可以被验证、被追溯、被重新评估。

闭环验收：没有重新核对就不算修好

修复动作完成后，不能以「生成了补记分录」或「写入了冲正记录」作为成功标准。真正的成功标准是：对当前这批数据重新跑一遍对账逻辑，差异消失了。

// settlement/recon/ReconJob.java（节选）：闭环验收
private void verifyClosedLoop(List<ReconDiff> diffs, Map<String, SettlementRecord> settlementMap,
 Instant start, Instant end) {
 // 只有「本轮自动处理过」的差异参与闭环。挂起等人工的、等下一批次的不算失败——
 // 它们本来就不该在这一轮被修好，算进失败会让「闭环失败」失去信号意义。
 List<ReconDiff> autoFixed = diffs.stream()
 .filter(d -> d.type() == ReconDiffType.MISSING
 && settlementMap.containsKey(d.tradeId()))
 .toList();
 if (autoFixed.isEmpty()) {
 log.info("[recon] 本轮无自动处理的差异，跳过闭环验收");
 return;
 }

 // 重新拉取净分录（已被冲正的 journal 不再参与），复用 checkBank 重新核对
 Map<String, List<JournalEntry>> aRecheck = groupByTrade(fetchBankEntries(bankAUrl, start, end));
 Map<String, List<JournalEntry>> bRecheck = groupByTrade(fetchBankEntries(bankBUrl, start, end));

 List<String> remaining = new ArrayList<>();
 for (ReconDiff diff : autoFixed) {
 SettlementRecord s = settlementMap.get(diff.tradeId());
 Bank bank = Bank.fromCode(diff.bankCode());
 List<JournalEntry> now = (bank == Bank.ICBC ? aRecheck : bRecheck)
 .getOrDefault(diff.tradeId(), List.of());

 List<ReconDiff> recheckDiffs = new ArrayList<>();
 boolean ok = checkBank(now, s, bank, diff.tradeId(), recheckDiffs);
 if (!ok) {
 remaining.add(diff.tradeId() + "/" + diff.account().label());
 }
 }

 if (remaining.isEmpty()) {
 log.info("[recon] 闭环通过: {} 条自动处理的差异已重新核对为平", autoFixed.size());
 } else {
 log.error("[recon] 闭环失败: {} 条差异补记后仍不平: {}", remaining.size(), remaining);
 }
}

这里有一个容易被忽略的细节：闭环验收不能用「数一下分录条数对不对」这种简化判断。因为冲正是追加式的，原始分录不会删除，冲正后「原始分录条数」不会变——只有按「净分录」（原始分录中尚未被冲正的部分）重新跑一遍完整的匹配逻辑，才能确认差异真正消失。

闭环验收 + 不可变差异记录，构成了对账系统最底层的安全网：对账能证明自己修好了，而不是「相信」自己修好了。

参考资料

中国人民银行, 小额支付系统业务处理手续（试行）, 央行官网公开文档. https://www.pbc.gov.cn/eportal/fileDir/history_file/files/att_19041_2.pdf —— 冲正、止付与退回流程的官方定义
金融时报, 网联平台荣获 2019 年度银行科技发展奖特等奖, 2020-09-25. https://www.financialnews.com.cn/if/hydt/202009/t20200925_201999.html —— 网联「三地六中心」架构与小时级多批次对账设计
ACCA, Suspense accounts and error correction, Foundation Level Study Resources. https://www.accaglobal.com/gb/en/student/exam-support-resources/foundation-level-study-resources/ffa/ffa-technical-articles/suspense-accounts-error-correction.html —— 试算平衡无法发现的六类错账
Formance, Transaction Reconciliation at Scale: An Engineering Guide. https://www.formance.com/blog/engineering/transaction-reconciliation-at-scale-for-eng —— 对账前的四项账本不变约束：复式记账、幂等、不可变性、双时态

演示代码：完整实现在 GYD 仓库 c03-reconciliation，PostgreSQL 编排在仓库级 infra/。按各目录 README 的命令跑，不要复制这篇文章里零散的代码块。

第二话｜消息队列的可靠投递与可靠消费：不丢靠三段兜底，不重只能靠幂等

Wed, 11 Feb 2026 00:00:00 +0000

一张订单表里多了一行，下游的发货系统没有收到这条消息。

订单服务在创建订单成功后投递 order.created，发货、积分、通知三个下游各自消费它。这一笔的发送日志打着成功，订单表里有数据，下游的队列里没有消息。这条消息死在了哪一段？

消息队列从进入架构的第一天就带着「可靠」的承诺，但这句承诺不是某一个组件给的，而是生产者、Broker、消费者各兜一段才拼出来的。任何一段缺了兜底，都会出现「发送成功、下游没收到」。

这条链路的骨架：消息穿过生产者、Broker、消费者三个边界，Broker 里是交换机到队列的一段路由；路径上还有两个反向回执——Broker 回给生产者的 confirm、消费者回给 Broker 的 ack。

顺着这条消息的生命周期走一遍，它有三个可能消失的位置：

发送时：生产者以为发出去了，消息却没进 Broker，或者进了 Broker 却没进任何队列。那笔订单的发送日志打的就是「成功」。
存储时：Broker 收下了，回执也回了，消息还没挺过一次重启就从磁盘上消失。
消费时：消费者读到了，处理到一半进程挂掉，重启后不知道这一笔该不该再处理。

这三个位置分别由生产者、Broker、消费者兜住，彼此没有替代关系：生产端再严谨也管不到消费者崩溃，Broker 副本再多也管不到生产者发错了路由键。

这条链路上有两类问题，经常被混在一起谈：

不丢：一条消息从产生到被处理完，中途不能消失。
不重：同一笔业务不能被处理两次。

在 Broker 这一层，这两类目标是冲突的：要保证不丢，就得允许重复投递。真正的「既不丢也不重」要到消费端用幂等去拼，Broker 给不了。

GYD 这个系列讲分布式系统里各种解决方案的实现方式。消息队列出现得早，也最容易被当成「基础设施，接上就行」的一环，而可靠性缺口通常就藏在这个默认判断里。

这三段在 RabbitMQ 4.3.5 上分别跑一遍。结论对应的是 RabbitMQ 4.3.5 + Spring Boot 4.1.1 + Spring AMQP 4.1.1 + amqp-client 5.30.0 + JDK 21；完整实现、端点对照与复现方式在仓库 c02-mq-reliable-delivery，下面每处结论后面也各自带了落点。

一、生产端：confirm 和 return 是两件事

RabbitMQ 的投递路径是 生产者 → 交换机 → 绑定 → 队列。生产者把消息发给交换机，交换机再根据绑定关系决定它进哪些队列。

消息先到交换机这一层，意味着「到了 Broker」和「进了队列」是两个可以分开发生的事件。RabbitMQ 给了两个独立机制来报告它们：

机制	报告的是什么	触发条件
publisher confirm	视路由结果分情况：可路由＝路由到的队列已接收；不可路由＝确认没有目标队列	消息被交换机处理之后
publisher return	消息没能路由到任何队列	交换机找不到匹配的绑定，且投递时设置了 `mandatory`

这两道回执在配置里是两个分开的开关（publisher-confirm-type 收 confirm、publisher-returns 收退回），默认都不开；客户端代码侧还要给发送模板打上 mandatory 标记、并分别注册两个回调。缺了任何一处，等于少了一道回执。

把一条消息投到没有任何队列绑定的路由键上，日志会连出三件事：生产端记下自己把消息投了出去；Broker 退回一条 NO_ROUTE，说明没有任何队列接收它；紧接着是一条 confirm 的 ack，说 Broker 已确认。再去查队列深度，两个业务队列都是 0 条（端点 unroutable）。

confirm 返回了 ack，消息已经被丢掉了。

官方文档在描述这件事时语气很平淡：「对不可路由的消息，Broker 会在交换机确认没有队列可路由之后发出 confirm；如果消息同时以 mandatory 方式发布，basic.return 会在 basic.ack 之前发给客户端。」文档没有单独警告不处理 return 会怎样，但把两者的定义摆在一起，结论是清楚的：confirm 的 ack 不是一律「成功」，它跟着路由结果走。路由到了队列，ack 表示队列已接收；路由不到，ack 只表示「确认了没有队列」，这条消息已经丢了。

只监听 confirm 而不管 return 的服务，等于在发送环节装了一个常亮的绿灯。

这里还有个更隐蔽的边界：return 的语义是「一个队列都没路由到」，所以「没有 return」只说明至少有一个队列接收了，不能证明发货、积分、通知三个预期订阅都配置正确。漏配了一个订阅，消息照样 confirm ack、照样不 return，只是那个下游安静地没收到。这个边界单靠发送端的回执是看不见的。

flowchart LR
 A["投递一条消息"] --> B{"有队列绑定这个路由键吗"}
 B -- 有 --> C["消息进入队列
confirm: ack"]
 B -- 没有 --> D["没有队列接收
confirm: ack
return: NO_ROUTE"]

需要等回执再继续的场景，可以同步等确认结果（示例里给了 3 秒超时）。这里有一处容易写漏：不可路由时 confirm 依然返回 ack，此时消息已被退回、并未进队列，所以只查 ack 会把「路由不到队列」当成「发送成功」，必须再查一次退回结果。同步等回执会拖住发送方。文档里给了个量级：在持续负载下，ack 的延迟可以达到数百毫秒，因此它建议把 confirm 当作异步事件流处理，或者批量投递、统一等待整批回执。同步等待更适合这里这种单条验证，一眼就能看出这一条到底有没有被 Broker 收下。

生产端的可靠性到这里只解决了一半。ack 在「路由不到队列」时并不代表成功，不是回执说了假话，是应用把成功条件理解少了：只盯 confirm 不看 return，就把「没有队列」当成了「发送成功」。而一旦把发送失败当成功、靠重试兜底，「同一笔订单发了两遍」的概率就不再为零。可靠性问题的另一半，是从生产端的重试里长出来的。

二、Broker 端：持久化要分清「消息恢复」和「拓扑恢复」

消息进了队列，下一个问题是它会不会在 Broker 这一侧消失。这里要先把两件事分开：已经入队的消息能不能挺过重启，和重启后拓扑（交换机、绑定）还在不在。它们由不同的属性决定，不能混成一句话。

对一条 classic queue 里的消息，「能不能挺过重启」只看两个属性：

属性	落点	缺了会怎样
队列持久化	声明队列时标 `durable`	重启后队列连同消息一起消失
消息持久化	投递时标 `deliveryMode=2`	队列还在，队列里的这条消息不在

交换机的 durable(true) 是另一件事，管的是拓扑恢复：它决定重启后这个交换机还在不在、还能不能继续往它投，但不决定已经入队的消息能否恢复。所以别把交换机、队列、消息并列成「三个都要持久化」——交换机那条管的是「以后还能不能投」，跟「已经投进去的还在不在」是两码事。

官方文档对「能不能挺过重启」的说法是：durable queue 的元数据写磁盘，重启时会被恢复，「包括其中以 persistent 方式发布的消息。以 transient 方式发布的消息会在恢复过程中被丢弃，即使它们的队列是 durable 的。」

这两个属性里，消息持久化这条更容易被漏：队列的 durable 在声明时顺手就写了，消息的 deliveryMode 却要每次投递单独指定。

用一条不挂消费者的持久化探针队列做对照（这个实验只在 classic queue 上成立，quorum queue 的持久化不依赖 deliveryMode）：投一条持久化、一条非持久化，两条都会收到 confirm 的 ack；重启 Broker 之后队列深度从 2 掉到 1，messages_persistent 一直是 1。再单独投一条非持久化消息复验：重启前深度 1，重启后归 0（端点 probe）。

ack 是否意味着落盘，取决于消息和队列的持久化属性。 文档给「持久化消息投到持久化队列」这种组合打了包票，那时 ack 意味着已经写盘。但只要消息属性没标持久化，ack 照样返回，重启后它无声消失。

单机持久化挡得住进程重启，挡不住磁盘损坏和机器故障。要扛机器级故障，只能用副本，在 RabbitMQ 4.x 上意味着 quorum queue——文档里那句「Classic queue mirroring was removed starting with RabbitMQ 4.0」，把过去的退路一并关掉了。

quorum queue 基于 Raft，副本关系里有一个 leader 和若干 follower，可用性由「多数派是否在线」决定。单节点验证不了这件事，所以另起了一套 3 节点集群（infra/rabbitmq-cluster/，端口与单节点错开，可以同时运行）。观察到的是这样一串：声明出来的 quorum queue 副本组实为 3 个成员、leader 落在 rmq1；投 3 条持久化消息全部收到 confirm；停掉 leader 所在节点后重新选主（两次运行分别落在 rmq2 与 rmq3），2/3 在线时继续投 2 条都成功，而且能取回全部 5 条，原 3 条一条不少；再停一个、只剩 1/3 时投递被拒，15.0s 后返回 NackError: 0 message(s) NACKed；把停掉的节点恢复回来，队列自愈到 3/3、投递恢复，而被 NACK 的那条并没有留在队列里（脚本 quorum-majority.py）。

quorum queue 的可用性由多数派决定：2/3 在线可以读写，掉到 1/3 就无法提交写入。 这不是丢消息，是 Raft 为避免脑裂做的取舍：宁可拒绝写入，也不让两个分区各自接受写入。客户端看到的表现不一定是即时报错，可能是等待、超时，也可能是明确的 NACK（本次实测是 15s 后返回 NackError）。

顺带一个观测上的坑：失去多数派时，连读队列视图本身都会超时，list_queues 时好时坏。故障期间的监控图表断点，有一部分来自这里。

维度	单机 durable queue	quorum queue
数据存活范围	单节点磁盘	多数派副本
扛得住什么	进程重启、节点重启	节点重启、单机磁盘损坏、少数派节点丢失
可用性前提	节点在线	多数派在线（3 节点可容忍 1 个）
代价	—	每次投递要复制到多数派，写入路径更长

quorum queue 的 confirm 语义也跟着变严：只有在消息被复制到多数派成员之后，Broker 才会发出 publisher confirm。 这一点和单机队列不同，单机队列上「收到 ack」离「数据安全」还有距离，quorum queue 上这句话的分量更重。

副本组本身也有几条固定约束：quorum queue 必须是持久化队列（Raft 的副本机制不建立在内存队列上）；官方建议副本数为奇数，默认 group size 是 3；文档明确写了「不要在多过 7 个 RabbitMQ 节点上运行 quorum queue」，也提醒少于 3 个节点的集群拿不到 quorum queue 的完整保证。本次实测的 3 节点加 group size 3，正好是能观察到选主、多数派可用性和少数派拒写的最小配置。

三、消费端：ack 时机与 prefetch 决定崩溃后重投多少条

消息安全躺在队列里，最后一个缺口在消费者手里。ack 的时机就是一次投票：投给「不丢」，还是投给「不重」。

处理成功后再确认、还是先确认再处理，是两个方向相反的取舍：先处理成功后 ack，中途崩溃消息会重投，于是可能重复处理；先 ack 再处理，中途崩溃时消息已删除，于是可能丢失。autoAck 是后者的极端形式，消息一交给消费者就当作已确认，跑得最快，也最不设防。

这里要插一句和 Spring 的边界：上面两种只是 AMQP 层的 manual / autoAck；Spring 还有一个默认的 AUTO 模式，它是容器在监听方法成功返回后替你 ack，比 autoAck 保守，比 manual 省事。这套 demo 用的是 manual，配置里关掉框架自动确认，把 ack 时机完全交给业务代码：业务成功才 ack，失败则带 requeue=false 拒绝，交给重试链路（不重回原队列，否则会原地死循环）。

flowchart LR
 A["收到一条消息"] --> B{"先做哪一步"}
 B -- "先处理，成功后 ack" --> C["中途崩溃
消息重投，可能重复处理"]
 B -- "先 ack，再处理" --> D["中途崩溃
消息已删，可能丢失"]

选完 ack 时机，还有一个必须显式决定的参数：prefetch。

RabbitMQ 的消费模型是「未确认消息的集合」，不是 Kafka 那种记「读到哪了」的位点。Broker 把消息推给消费者，在收到 ack 之前一直记着这些消息属于这个消费者，没有 ack 就没有「位点前进」，只有「这条还没结清」。于是 prefetch（协议里的 basic.qos）决定了一个消费者最多同时持有多少条未确认消息。

这个参数不影响单条消息的处理速度，它影响的是消费者崩溃时有多少条要重投。用 50 条慢消息（每条处理 200ms）只改 prefetch 来对照：设成 1 时未确认条数恒为 1，设成 20 时恒为 20，而 50 条排空都花约 10s（端点 burst）。两者的吞吐相同，差别在同时在途的未确认条数。 如果消费者在任一时刻崩溃，prefetch=1 最多重投 1 条，prefetch=20 最多重投 20 条。

这里有个边界要说清楚：本实验的瓶颈在消费处理本身（每条固定 200ms），所以两者耗时相同。如果消费逻辑很快、网络往返占比高，prefetch 取值会明显影响吞吐，那是另一个结论，不能从这组数据外推。表里的「恒为」也只成立在积压充足阶段，消息源源不断时未确认条数稳定在 prefetch 上限；排空的最后一段，队列里剩不足 prefetch 条，未确认条数会掉下来。另外，实验只测了单消费者，多消费者共用一个队列时的负载分摊没有测。

还有一件事值得和 prefetch 分开看：消费者崩溃后，那些未确认的消息会被重新投递，但不一定回到同一个消费者。Broker 把它们放回队列等重新分配，多个消费者在场时通常落到别人手里。这就是为什么扩容之后「同一笔业务被两个消费者各处理一次」会更常见，幂等在那里不再是理论问题。

至于 prefetch 该定多少，没有一个可以照抄的数。它取决于单条消息的处理耗时、下游能承受的并发、以及你愿意接受崩溃时重投多少条。文档里 0 表示不设上限，等于把未确认集合交给内存和连接去决定，生产环境一般不会这么配。Broker 侧另有一个「消费者没指定时生效」的默认 prefetch，可在高级配置里调整（文档示例给的值是 250），所以不显式设置并不等于没有限制，只等于这个数由别人替你定了。

四、不丢和不重分别落在两层：Broker 管投递，幂等管效果

前三段各自解决了一类丢失，代价是把重复引了进来：生产端的重试会重发，消费端的 ack 时机（先处理再确认）会重投。要理解这件事的边界，得先看清 Broker 能承诺什么。

官方可靠性文档把话说得很直白：「使用 acknowledgements 保证 at least once 投递。不使用 acknowledgements 时，发布和消费过程中都可能丢消息，只能保证 at most once。」至于 exactly-once，文档在同一页给出了它的现实形态：生产者重传、确认丢失时消息可能重复，「因此消费端应用需要做去重，或者以幂等的方式处理收到的消息。」

Broker 能给的只有 at-least-once 和 at-most-once。exactly-once 不是队列的承诺，而是「at-least-once 投递 + 消费端幂等」拼出来的效果，而且这个 exactly-once 只覆盖被幂等机制管住的那些业务效果。

投递语义	谁提供	结果
at-most-once	关掉 ack / autoAck	不重，可能丢
at-least-once	手动 ack + 失败重投	不丢，可能重
exactly-once	队列不提供	由 at-least-once + 消费端幂等拼出

这里要分清三个层次，它们经常被混成一句话。投递可以重复：Broker 重投、生产者重发都会让同一条消息到两次。执行可以重复：处理函数被调用两次。业务副作用能不能只生效一次，取决于消费端有没有幂等，而且幂等只覆盖它自己管得住的那些副作用。数据库去重表能让「改库」只发生一次，但它不会自动让发货、短信、外部扣款也只发生一次；那些副作用要各自有幂等键（发货单号、短信去重、扣款流水号），或者接受「至少一次 + 人工对账」。

注意幂等这一层必须落在业务侧。Broker 手里也有一些计数，比如 quorum queue 会把一条消息失败的投递次数记在 x-delivery-count 头里，配合 delivery-limit 策略，投递超过上限的消息会被死信掉，而它解决的是「一条毒消息别在队列里无限打转」，不是「你的业务代码只跑一次」。这两个问题在不同的层，别指望前一层替后一层兜住。（delivery-limit 的计数规则在 4.3 有调整，不是所有显式 nack 都计入失败次数，与第六节讲的 delayed retry 相关。）

落回订单场景：这一笔订单可能被处理两次。幂等的最小形态是让消息带上业务唯一键，消费端用它去重，这套 demo 里就是消息体上的 orderId。它由订单服务生成，重发时不变；消费端拿到它，先查这一步业务是否已经做过，再决定要不要执行。但要小心并发：去重记录和业务写入必须原子提交（比如唯一索引 + 同库事务），否则两个消费者同时「查无记录」、都往下执行，幂等就失效了。去重表、唯一索引、状态机校验各有各的适用场景，本 demo 没有落到那一层，orderId 只负责把「同一笔业务」这个身份带过去。

五、兜底：死信与延迟重试链路

三段兜底之外，还有一类问题没有解决：消费一直失败怎么办。失败一次就重投，会得到一个高速空转的循环；失败三次就扔掉，会丢掉一条本该被处理的消息。

RabbitMQ 在这一层的原语是死信。消息在四种情况下会被重新投递到死信交换机：消费者以 requeue=false 拒绝（basic.nack / basic.reject）、消息因 TTL 到期（per-message TTL，或队列级 message-ttl）、队列超过长度上限、以及 quorum queue 上超过 delivery-limit 的投递次数。

这里有两个容易踩到的地方。如果队列上配了死信交换机，但消息需要死信时那个交换机并不存在，消息会被静默丢弃，没有回执，没有异常。拓扑声明因此不能只声明队列，交换机、绑定、队列的生命周期要一起管。

另一个和队列类型有关：classic queue 的死信过程默认不带 publisher confirm，消息从原队列删除后直接投给死信目标，目标不可用时它就丢了。quorum queue 可以做得更强，但默认仍是 at-most-once，要显式配置 dead-letter-strategy=at-least-once、overflow=reject-publish 并配好死信交换机，才切到带 confirm 的 at-least-once 死信。同一套死信拓扑，队列类型和策略配置不同，兜底强度并不一样。本 demo 没有显式配置这套策略，死信转移仍是 at-most-once 语义。

要做「重试 N 次再进死信」，标准做法是让业务队列的死信出口指向一条重试链路：业务队列 → nack → 重试交换机 → TTL 重试队列 → 到期回业务交换机 → 业务队列。这套 demo 的拓扑里，业务队列的死信出口不是最终死信队列，而是重试交换机；重试队列上配了 2000ms 的队列级 TTL，到期后经自身的死信出口回到业务交换机；最终死信交换机只接重试用尽以后由应用显式投递的消息。

flowchart LR
 Q["业务队列
收到消息"] --> C["处理失败
nack(requeue=false)"]
 C -- "还没用尽重试" --> R["重试队列
TTL 2000ms"]
 R -- "到期回投，x-death 计数 +1" --> Q
 C -- "重试用尽" --> D["最终死信队列
等待人工或定时任务"]

重试计数不一定非要应用自己维护，本 demo 读 Broker 写在 x-death 头里的死信记录。 应用自己维护一个进程内计数器，进程重启后就归零；要可靠就得把次数持久化到数据库、任务记录或消息头里，那是另一套存储。本 demo 选择读 x-death，它跟着消息走，避免了另建一套重试计数存储。官方文档对它的定义是：每条记录里 count 表示「这条消息因为这个原因从这个队列被死信了多少次」，并且记录会按 {队列, 原因} 压缩，同一个 (队列, 原因) 组合只保留一条，count 累加。

还要说清一个边界：x-death 记的是「死信」次数，不是「投递」次数。消费者崩溃后消息被直接重投、没走死信的那一次，不会在 x-death 里留记录。所以「rejected 次数 + 1 = 累计投递次数」这个等式，只在「每次失败都走 nack 死信」的本实验路径下成立。

实测一条一直失败的消息（orderId 里带 fail），队列级 TTL 2000ms、最多重试 3 次。第一次失败时 x-death 还是空的；第二次时里面已经有两条记录，业务队列上一条 rejected 计数 1、重试队列上一条 expired 计数 1；第三次两边各加 1；到第 4 次投递仍失败，消息转入最终死信队列，此时累计投递 4 次，也就是首次加上 3 次重试。相邻两次处理的间隔实测 2004 / 2003 / 2003ms，与配置的 2000ms 对得上（重跑会有几毫秒浮动）。

计数时要挑对条目：同一次失败会留下两条记录，业务队列上一条 reason=rejected，重试队列上一条 reason=expired，两个都算就重复计数了。示例里的计数只挑与业务队列同名的 rejected 记录求和。

重试用尽之后怎么收尾，有一个容易写错的地方。这里的业务队列死信出口是重试交换机，所以不能再用 nack 结束，它会再一次进入重试循环。正确做法是显式投到最终死信交换机，再 ack 掉原消息，同时把尝试次数写进消息头备查。

六、单个 TTL 重试队列的限制：混合延迟会出现队头阻塞

重试链路跑通之后，一个自然的想法是让间隔递增：1 秒、10 秒、60 秒，给下游留出恢复时间。这个想法在 RabbitMQ 的 TTL 上会撞到一件不那么直观的事。

队列级的 x-message-ttl 是队列的属性，同一条队列里的消息共用一个延迟，所以它天然只能做固定间隔，要递增就得给每一级配一条队列。另一条路是 per-message TTL：投递时给每条消息带上自己的 expiration。直觉上「谁先到期谁先走」，实测是「队头说了算」。

同一条队列投 3 条消息、各带不同的 expiration，只换入队顺序（脚本 ttl-head-of-line-blocking.py）：先投 6000ms 再投两条 1000ms，三条全部在 +6.0s 才死信；把顺序换成两条 1000ms 在前、6000ms 在后，前两条 +1.0s 就走，第三条 +6.0s。后两条的 expiration 明明只有 1000ms，却等到 +6.0s 才死信，被队头那条 6000ms 的消息卡了约 5 秒。

在本实验这种「同一条 classic 队列、只靠 per-message TTL 触发死信」的场景下，过期检查只在队头进行。 队头那条没到期，排在它后面、已经过期的消息也不会被处理。

官方文档写得很清楚：classic queue 与 quorum queue 都是「过期消息到达队头时才被死信掉」，并且「设置 per-message TTL 后，已过期的消息可能排在未过期消息后面，直到后者被消费或过期；这些过期消息占用的资源不会被释放，也会被计入队列的消息数」。

所以递增退避的「手搓」做法有两条：每一级一条队列（1s 队列、10s 队列、60s 队列各配一条，用路由键区分级别），或者装延迟消息插件。本 demo 用固定 2000ms 间隔，正是因为它只需要一条重试队列。

不过这两条都不是唯一的答案了。RabbitMQ 4.3 起给 quorum queue 提供了原生 delayed retry：通过 x-delayed-retry-type / x-delayed-retry-min / x-delayed-retry-max 三个参数，消息被拒绝（reject/nack）后按投递次数自动线性退避，延迟 = min(min_delay × delivery_count, max_delay)。它把「递增退避」做成了队列的内建能力，不用再叠一堆 TTL 队列或插件。注意三点：它只对 quorum queue 生效；默认 x-delayed-retry-type=disabled，要显式开启；本 demo 用的是 classic queue + 单条 TTL 重试队列，走的是上面那条「手搓」路径，正好能看清队头阻塞这个底层限制。

七、一致性补偿：Broker 之外的那一段

上面讲的都是「消息发出去之后」的可靠性。还有一类问题在更早的地方：订单写进了数据库，消息没发出去，或者反过来。

在 RabbitMQ 上这件事要靠应用层补偿。AMQP 的 channel 事务在这里帮不上忙，它的硬伤首先是事务边界：channel 事务只能包住「发消息」这一个动作，包不住「数据库写 + 发消息」这对跨系统的操作，所以它根本解决不了原子提交；顺带它还有吞吐代价（文档给的是降到约 1/250）且和 confirm 模式互斥。RabbitMQ 也没有 RocketMQ 那种 broker 级的事务消息（半消息 + 回查）。可行的模式是本地消息表（也叫 outbox）：在写订单的同一个本地事务里，往一张 outbox 表插一条待投递记录；事务提交后由后台任务把 outbox 里的记录投递出去，投递成功再标记完成；消费端仍然靠幂等兜底。

这个模式的关键在「同一个本地事务」，数据库事务保证订单和待发消息一起落库，消息投递则从「必须成功」降级成了「迟早成功」。本 demo 没有实现本地消息表，这里只说明它在链路里的位置：它是把「改库 + 发消息」这对跨系统操作，压回一个本地事务里的做法。

三个角色可以分开看：订单表和 outbox 表写在同一个事务里，解决「改库成功但消息没发出去」；后台投递任务负责重试，解决「投递时下游不可用」；消费端幂等兜最后一道，解决「投递重试带来的重复」。三处缺一处，一致性就漏一处。

这个模式也有自己的代价：outbox 表需要清理策略，否则它会跟着业务表一起无限增长；投递任务要独立控制并发和失败告警，它本身变成一条需要被监控的链路；投递逻辑和业务表放在同一个库时，事务的粒度会变大。它适合「本地写库、且要求通知最终一定送到」的场景，不适合拿来兜一个本来就不要求一致的通知。

八、Boot 4 与 RabbitMQ 4.3 上的几处版本差异

这套代码跑在 Spring Boot 4.1.1 + Spring AMQP 4.1.1 + amqp-client 5.30.0 + JDK 21 上，和大多数 Boot 3 时代的 RabbitMQ 教程有几处对不上的地方：

现象	原因	处理
`Jackson2JsonMessageConverter` 找不到依赖	Boot 4 用 Jackson 3（`tools.jackson`），类路径上只有 `com.fasterxml.jackson` 的注解包，没有 databind	改用 `JacksonJsonMessageConverter`
消费侧抛 `The class ... is not in the trusted packages`	转换器默认只信任 `java.util` / `java.lang`	按消息类的包名授权，不要写成 `"*"`
`Confirm.isAck()` 报弃用	Spring AMQP 4 起确认结果改成了 record	用 `ack()` / `reason()`
死信监听器反序列化失败	参数写成 `org.springframework.amqp.core.Message` 会走 typeId 反推，撞上信任包检查	参数直接用具体的消息类型
改完队列参数后应用启动失败，报 `inequivalent arg`	队列的 `x-dead-letter-exchange` 等参数不允许原地修改	先 `rabbitmqctl delete_queue` 再重启，让应用重新声明（只适用于可清空的实验环境，删除队列会连消息一起删；生产环境应改用 policy 动态配置）
脚本里声明非持久化的非排他队列报 `transient_nonexcl_queues is deprecated`	RabbitMQ 4.3 起默认不再允许这类队列	一律声明为持久化队列

最后一条是 4.3 引入的：官方文档把「transient（非持久化）且非排他的 classic queue」标为弃用，4.3.0 起默认不允许声明。写实验脚本时如果沿用了老教程里的 durable=False，会直接撞上这个报错。

九、收口：三段各兜住什么，以及它划出的边界

回到开篇那三个可能消失的位置，每一处现在都能对上兜底的一方，也能看清它兜到哪为止：

发送时：生产端的 confirm 加 return。两道回执都要看——confirm 跟着路由结果走，不可路由时它照样返回 ack，只监听 confirm 等于在发送环节装一盏常亮的绿灯；回执也覆盖不到订阅配置，没有 return 只说明至少有一个队列接收了。
存储时：Broker 端的持久化与副本。两个持久化属性回答「重启后还在不在」，副本回答「机器坏了还在不在」，后者把可用性前提从「节点在线」换成「多数派在线」，故障期间连读队列视图都会超时。
消费时：消费端的 ack 时机与 prefetch。前者决定崩溃时消息是重投还是丢失，后者决定重投的规模，但都没有改变「可能重复」这个结果。

重复这件事在三段里没有归宿：Broker 侧的 x-delivery-count 与 delivery-limit 管的是毒消息别在队列里无限打转，不是业务代码只跑一次；消掉重复的位置在消费端的业务幂等里，而幂等只覆盖它自己管得住的那几个副作用。三段拼出来的承诺是「不丢」加 at-least-once，不是「既不丢也不重」。

代价和上面三处一一对应：生产端要处理两道回执，并决定同步等还是异步收，同步等会把发送方拖进回执时延里（文档给的量级是持续负载下数百毫秒）；Broker 端要接受「多数派不在就拒绝写入」这个前提；消费端先处理再 ack 把重复引了进来，扩容之后同一笔业务落到两个消费者手里会更常见；重试链路上固定间隔只占一条 TTL 队列，改成递增退避，要么每级一条队列，要么接受过期检查只在队头这一条限制。

还有一段不在这三段的视野里：订单写进数据库、消息没发出去（或者反过来）发生在第七节的位置。三段兜底保证消息不消失，保证不了业务状态和消息一起生效；把这件事压回一个本地事务里的做法是本地消息表，它的代价是 outbox 的清理策略、投递链路自己的监控，以及变大的事务粒度。

参考资料

Consumer Acknowledgements and Publisher Confirms：publisher confirm 与 consumer ack 的定义与触发时机，mandatory 与 basic.return 的先后顺序。
Reliability Guide：at-least-once / at-most-once 的边界，以及消费端去重与幂等的必要性。
Queues：队列持久性与消息持久化的关系，transient 非排他 classic queue 的弃用说明。
Quorum Queues：Raft 副本、多数派可用性、publisher confirm 的发出时机、x-delivery-count 与 delivery-limit、at-least-once 死信（dead-letter-strategy/overflow）、4.3 原生 delayed retry。
Dead Letter Exchanges：死信的四种触发条件，x-death 头部结构与按 {队列, 原因} 压缩的规则。
Time-To-Live and Expiration：per-queue 与 per-message TTL 的区别，过期检查发生在队头的行为。
Consumer Prefetch：basic.qos 与未确认消息上限。
Metadata store：Khepri 自 4.2.0 起成为默认元数据存储，与 Mnesia 的关系。

演示代码：完整实现在 GYD 仓库 c02-mq-reliable-delivery，该目录的 README 列了环境、运行方式、端点与本文各节的对照，以及本文引用的完整输出记录；RabbitMQ 与 3 节点集群的编排在仓库级 infra/，两个实测脚本在 infra/rabbitmq/scripts/ 与 infra/rabbitmq-cluster/scripts/。