幂等消费者与重试副作用：Kafka 端点接入时的去重边界

一、读者要完成的一件事

假设你所在团队有一个存量订单库，业务部门希望把 Kafka 中不断流入的"订单变更事件"同步到旧系统的客户积分表里。Kafka 主题里同一条事件可能不止出现一次：生产者发送超时后重发、消费者处理完但提交位点前进程崩溃、再均衡后分区被重新分配，都会让同一业务事件再次进入你的处理逻辑。你要完成的任务不是"把 Kafka 教程再读一遍"，而是：让这条 Camel 路由在重复投递时只产生一次业务效果，并且能说清楚哪些重复它能挡住、哪些挡不住。

这件事听起来只加一个幂等组件即可，实际却牵涉三层：

消费语义层：Kafka 在什么条件下会重投？Camel Kafka 组件在什么时机提交位点？
路由执行层：Camel 的 Exchange 在重试、异常处理、拆分聚合过程中如何被复制或重用？
业务去重层：幂等仓库以什么键、什么生命周期记录"我已处理过"。

任何一层说错，结论就会错。例如"用了幂等消费者就不会重复"是错误直觉，因为幂等仓库本身可能先成功后失败，或者提交位点失败导致消息重投而幂等记录已在另一个事务里回滚。本文沿"具体问题 → 环境与兼容版本 → 核心机制 → 贯穿示例 → 执行与观察 → 失败反例 → 适用条件"推进，重点放在去重边界，而不是 Kafka 本体原理。

术语先用白话铺垫

端点（Endpoint） ：一个能被路由读写的"地址"，例如 kafka:orders-topic 或 file:inbox。它解决的问题是：让路由不关心底层客户端怎么建连接，只描述从哪里取、往哪里送。正式名称是 Endpoint。
组件（Component） ：一类端点的工厂，例如 kafka 组件负责根据 URI 创建 Kafka 消费者和生产者端点。
路由（Route）：一条"从哪来、做什么、到哪去"的处理流水线。
处理器（Processor）：路由中的一段 Java 逻辑，接收一个 Exchange，可以读写消息体与头。
交换（Exchange）：Camel 在一次消息流转中携带的上下文对象，包含输入消息（In）和可能的输出消息（Out）、属性（property）与异常信息。属性是路由内部传递状态的地方，不会自动发到下游系统。
消息（Message）：Exchange 里的载荷容器，包含 body 与 headers（头部）。

这些对象在幂等场景中非常关键：去重键应该放在哪里、重试时会不会被改写、会不会被下游看到，都由它们决定。

二、环境、兼容版本与前置条件

本文所有结论的适用范围如下，超出范围需要重新核对官方文档：

项目	版本	说明
JDK	Java 21 LTS	编译与运行
集成框架	Apache Camel 4.22 LTS	使用 `camel-kafka`、`camel-spring-boot`、`camel-mock`
Spring Boot	3.x（与所用 Camel 4.22 版本线的官方兼容矩阵一致）	具体小版本以官方兼容矩阵为准
Kafka	3.x 兼容 broker	仅作为连接端点，不展开 broker 原理
构建工具	Maven 3.9+	依赖坐标示例

必须明确区分三类陈述：

官方保证：例如 Kafka 消费者在关闭自动提交、处理完成后手工提交时，位点提交成功前崩溃会重投。这属于 Kafka 的消费语义。
特定条件下的行为：例如某组件在开启某种选项后才会在异常时重试或提交，属于配置相关行为，需以对应版本文档为准。
工程建议与待验证假设：例如"建议把幂等记录和业务写入放在同一事务里"，这是设计建议；而"你的数据库和 Kafka 恰好能组成原子事务"则是需要验证的假设。

本文不宣称任何实验已在生产环境运行。下文给出的执行步骤和预期输出，是按设计应当出现的可观察结果；读者需要在自己的环境复现，实际日志细节可能因版本和配置不同而变化。

三、重试为什么会制造重复：先把因果关系摆清楚

3.1 Kafka 的"至少一次"从哪来

Kafka 消费者按分区顺序读取，用"位点"标记已消费到哪。若消费者在处理完消息、但尚未提交位点之前退出，新的消费者会从上次提交的位点继续读，于是这条消息被再次投递。这就是常见的"至少一次"投递。它不是一个 bug，而是"先处理、后提交"这种顺序的必然结果：提交位点本身也是一次可能失败的操作。

于是重复有两个典型来源：

处理成功、提交失败：业务已经写入，位点没有推进，重投。
处理失败后重试：本地重试成功，但重试前后的多次调用都被下游看到。

注意这里有一个容易被忽略的细节：Kafka 层面"重投"和 Camel 内部"重试"是两件不同的事。前者来自 broker 与消费者组，后者来自路由的错误处理策略。它们都会让同一业务事件被处理多次，但位点是否推进、幂等键是否一致不同，处置方式也不同。

3.2 Camel 内部重试的副作用

Camel 的错误处理策略（例如默认的 DefaultErrorHandler 或 deadLetterChannel）可以在同一条消息上多次调用处理器。如果处理器是"把金额加到积分表"这种非幂等操作，那么重试 N 次就可能加 N 次。很多团队以为"重试是安全的，因为最终会成功"，实际是重试把不幂等的操作放大了。

用 ASCII 图表示一次失败重试的链路：

text 复制代码

Kafka 分区位点(未提交)
        |
        v
[ from kafka ] --> [ 反序列化 ] --> [ 业务 Processor ] --失败--> [ 错误处理器重试]
                                            |                         |
                                            |<------- 第2次调用 ------+
                                            |
                                            +--> 第3次调用 ... 直到成功或耗尽
        |
        v
   提交位点(手工)

看这条链路：只要处理器第一次已经产生了部分或全部副作用，重试就会叠加。若处理器内部本身有本地缓存去重，它又可能是内存态，重启即失效。

3.3 再均衡带来的重复与顺序问题

消费者组内分区会在成员变化时重新分配。再均衡过程中，一个分区可能先被旧成员处理到一半，再交给新成员从头读（按已提交位点）。如果旧成员在失去分区后仍完成了业务写入但提交失败，新成员就会重做。任何"只在内存里记已处理 ID"的方案，在再均衡和重启面前都无效。

3.4 结论先行

要让重复投递不产生重复业务效果，需要同时满足三个条件：

业务操作可被一个稳定的去重键识别；
去重记录存放在跨进程、跨重启有效的仓库里；
去重记录的写入与业务效果的写入在一致性边界上被正确处理。

第 3 条最容易被忽视，也是后文重点。

四、Camel 的核心对象如何参与去重

4.1 Exchange、Message 与属性

当 from("kafka:...") 读入一条记录后，Camel 会构造一个 Exchange。消息头里通常包含 Kafka 相关的元数据，例如主题、分区、偏移量等（具体头名以对应版本组件文档为准）。这些头是判断"这次投递"的证据，但它们不是业务去重键：同一业务事件重投时偏移量可能变化，分区也可能变化。

业务去重键应来自消息体中的业务字段，例如订单事件里的 eventId 或 orderId + version。如果上游没有稳定 ID，你只能退而求其次用内容哈希，但内容哈希在字段顺序或精度变化时会误判，这属于适用条件问题。

属性（property）适合在路由内部传递"本次处理是否已完成""原始 key 是什么"，但属性默认不会序列化给下游。不要指望用属性跨路由实例传递去重状态。

4.2 Processor 的职责边界

Processor 适合做：抽取去重键、校验、调用业务服务、设置后续分支条件。不适合做：长时间阻塞等待、维护全局可变状态、把重试语义写死。Processor 抛出的异常会被错误处理器捕获，从而触发重试或进入死信路径。因此 Processor 必须是"可被重复调用而不改变业务结果"的，或者外部已有幂等保护。

4.3 幂等消费者的位置

"幂等消费者"这个模式解决的问题是：在消息可能重复到达时，只让第一次到达的消息进入后续处理。Camel 提供 idempotentConsumer 处理器，它用一个表达式算出键，然后去仓库里查"这个键是否处理过"，是则跳过，否则执行内部处理器并在成功后记录。正式名称是 Idempotent Consumer。

它的结构大致是：

text 复制代码

from(kafka) --> idempotentConsumer(key = eventId, repo)
                    |-- 已存在 --> 跳过(可选记录日志)
                    |-- 不存在 --> 业务处理器 --> 成功后写入 repo

关键点：仓库写入发生在业务处理器之后、且默认独立于业务事务。这正是去重边界问题的根源，后面会详细展开。

4.4 仓库选型的取舍

仓库	适用条件	失效条件
内存仓库	单实例、短生命周期、测试	重启、多实例、再均衡后失效
文件仓库	单实例且能保证文件独占	多实例共享同一文件、文件损坏、并发写
JDBC 仓库	多实例共享数据库、需要持久化	键表无唯一约束、事务边界错配、键过期清理策略缺失
分布式 KV（如 Redis）	高吞吐、可接受最终一致	键过期早于业务完成、网络分区导致误判

工程建议：多实例部署+Kafka 再均衡几乎必然发生，内存仓库基本不适用；JDBC 仓库最容易与业务写入共享事务，是常见选择；Redis 适合高吞吐但要仔细设计 TTL 与失败补偿。

五、贯穿示例：订单事件同步积分表

5.1 场景与最小数据

Kafka 主题 order-events，消息为 JSON：

json 复制代码

{"eventId":"evt-1001","orderId":"ord-77","customerId":"c-9","amount":120,"version":1}

要求：同一 eventId 只给客户 c-9 增加一次积分（积分 = amount）。重复投递必须被跳过。

去重键用 eventId。假设业务方保证 eventId 在事件重发时不变，这一点必须与上游确认，属于前置假设。

5.2 目录结构

text 复制代码

camel-idem-demo/
  pom.xml
  src/main/java/demo/
    DemoApplication.java
    OrderRoute.java
    PointsService.java
  src/main/resources/
    application.yml
    schema.sql

5.3 依赖（Maven 坐标示意）

xml 复制代码

<properties>
  <java.version>21</java.version>
  <camel.version>4.22.0</camel.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-spring-boot-starter</artifactId>
    <version>${camel.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-kafka-starter</artifactId>
    <version>${camel.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-sql-starter</artifactId>
    <version>${camel.version}</version>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
  </dependency>
  <dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
  </dependency>
</dependencies>

版本号请以官方兼容矩阵核对；此处 4.22.0 为示意精确版本，实际以仓库中可用的 4.22 LTS 补丁版本为准。

5.4 配置

yaml 复制代码

spring:
  datasource:
    url: jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1
    username: sa
    password: ""

camel:
  component:
    kafka:
      brokers: ${KAFKA_BROKERS:localhost:9092}
      groupId: points-group
      autoCommitEnable: false
      allowManualCommit: true
      autoOffsetReset: earliest

这里刻意关闭自动提交并允许手工提交，让位点推进的时机由路由控制。具体选项名以 camel-kafka 对应版本文档为准。

schema.sql：

sql 复制代码

CREATE TABLE points (
  customer_id VARCHAR(64) PRIMARY KEY,
  total INT NOT NULL
);

CREATE TABLE camel_idem (
  idem_key VARCHAR(128) PRIMARY KEY,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

注意 camel_idem 的 idem_key 有主键/唯一约束，这是防止并发插入重复键的基础。若没有唯一约束，两个实例可能同时插入同一键。

5.5 路由（Java DSL 示意）

java 复制代码

@Component
public class OrderRoute extends RouteBuilder {

  @Override
  public void configure() {
    from("kafka:order-events?groupId=points-group")
      .routeId("order-points")
      .unmarshal().json()
      .idempotentConsumer(
          jsonpath("$.eventId"),
          new JdbcIdempotentRepository(dataSource, "camel_idem", "idem_key"))
        .process(new PointsProcessor(pointsService))
      .end()
      .process(exchange -> {
        // 位点提交示意：具体 API 以对应版本 Kafka 组件文档为准
      });
  }
}

这段是示意代码 ，不是可直接编译的完整程序：json()、jsonpath()、JdbcIdempotentRepository 的构造参数与提交 API 需要按版本核对。它的意图是展示三个位置：去重键抽取、去重仓库、业务处理。

5.6 业务处理器

java 复制代码

public class PointsProcessor implements Processor {
  private final PointsService service;

  public PointsProcessor(PointsService service) { this.service = service; }

  @Override
  public void process(Exchange exchange) {
    String customerId = exchange.getMessage().getHeader("customerId", String.class);
    Integer amount = exchange.getMessage().getHeader("amount", Integer.class);
    if (customerId == null || amount == null) {
      throw new IllegalArgumentException("missing required fields");
    }
    service.addPoints(customerId, amount);
  }
}

输入是 Exchange 的消息头；状态变化是把积分累加到 points 表；结果原因是业务服务执行了 UPSERT。边界：如果 addPoints 内部先查后加，两个并发线程可能都读到旧值，应使用数据库原子更新（例如 UPDATE ... SET total = total + ? 或带冲突处理的 UPSERT）。

5.7 执行步骤与预期观察

启动本地 Kafka（任意 3.x 兼容 broker，或以容器方式启动，具体命令以你环境的镜像文档为准）。
创建主题：order-events，1 个分区便于观察顺序。
启动应用：mvn spring-boot:run。
发送一条消息：用 kafka-console-producer 发送上文 JSON。
观察：日志出现一次业务处理；积分表 c-9 的 total 为 120。
再发送完全相同的 JSON。
预期：幂等仓库命中，业务处理器不再执行，total 仍为 120。

验证查询：

sql 复制代码

SELECT customer_id, total FROM points WHERE customer_id = 'c-9';
SELECT COUNT(*) FROM camel_idem WHERE idem_key = 'evt-1001';

预期：第一条返回 120，第二条返回 1。若第二条返回 0 而积分已加，说明幂等记录没有落库，这正是下一节要讨论的边界。

资源清理：停止应用；删除测试主题或使用独立容器；内存 H2 随进程结束消失，若用文件 H2 需删除数据文件。

5.8 手工提交的边界

关闭自动提交后，位点必须在业务成功后提交。这里有一个无法回避的顺序问题：业务写入成功、幂等记录成功，但提交失败 → 消息重投 → 幂等命中 → 跳过业务，但此时若跳过分支也不提交位点，就会无限重投。工程上常见的处理是：幂等命中时仍然推进位点（因为业务效果已经存在），或者把提交动作放在"幂等命中"和"首次成功"两条路径都会经过的位置。具体提交 API 与幂等命中时能否安全推进位点，必须以对应版本文档与实际测试确认。

六、失败与反例：去重挡不住什么

6.1 反例一：幂等记录独立事务、业务失败后回滚

假设业务写入在事务 A，幂等记录在事务 B。顺序是先写业务、后写幂等：业务成功但写幂等前进程崩溃 → 重投 → 幂等未命中 → 业务再执行一次 → 重复。

若顺序反过来：先写幂等、后写业务，业务失败 → 幂等已存在 → 重投被跳过 → 丢失业务效果。

这说明：当幂等记录和业务效果不在同一事务边界时，去重只能减少重复，不能严格保证"恰好一次"。 可行的工程做法包括：让两者共享同一数据库事务；或者在业务表中直接用业务主键做 UPSERT，让数据库唯一约束承担去重；或者接受"至少一次+可排查"的语义，并保留对账。

6.2 反例二：键不稳定

用 orderId 做去重键，但同一订单会有多次"金额变更"事件，那么第二次变更会被错误跳过 → 丢失更新。去重键必须对应"业务上的一次性动作"，不是任意 ID。

6.3 反例三：内存仓库在再均衡后失效

单实例测试时一切正常，上线多实例后，同一分区在不同实例间迁移，内存仓库各自为空，重复处理出现。这类问题在测试环境很难复现，因为实例数少、重启少。

6.4 反例四：重试放大副作用

假设业务处理器内部调用远程积分接口，网络超时后 Camel 错误处理器重试 3 次。远程接口可能已经成功但响应超时，于是积分被加 3 次。此时幂等键若只在 Camel 侧检查，重试期间它仍在同一"未记录"状态，无法拦截。需要在远程接口侧也支持幂等键，或把重试策略与业务幂等配合设计。

七、排障证据与验证方法

当出现重复时，按以下顺序取证：

看位点：重投前最后一次成功提交的偏移量是多少？是否存在"处理了但没提交"。
看去重表：对应键是否存在？存在时间是否早于业务写入？
看日志时间线：同一条事件的处理日志是否出现两次，中间是否伴随再均衡、重启或异常。
看事务：业务写入和幂等写入是否在同一事务；失败时哪一侧回滚。

一个有用的观察方式是把 eventId、偏移量、处理结果写入一张审计表，重投时对比。这属于工程建议，不是框架保证。

八、适用条件与结论

本文的结论适用条件是：Kafka 作为端点、Camel 4.22 LTS、Java 21、消费者使用手工提交、去重键由上游保证稳定、去重仓库可跨进程持久化。

在这一条件下：

幂等消费者能挡住"同一稳定键的重复投递"，前提是仓库写入可靠。
它不能在业务写入与幂等记录不在同一事务时严格保证恰好一次。
重试会放大不幂等副作用，必须让 Processor 可重复调用或在下游再做幂等。
手工提交边界决定重投频率，幂等命中路径也要考虑位点推进。

最终交付建议：先用业务表唯一约束兜底，再叠加幂等消费者减少无效处理；把去重键设计写进接口契约；对无法去重的操作保留对账与告警。不要把"加了幂等消费者"当作"不会重复"的证明，而应当作为减少重复的一道防线。

九、把去重键落到消息契约：从头部到序列化的边界

上一部分把重点放在事务与提交顺序上，本节补齐一个更靠前、也更容易在联调期暴露的位置：去重键在 Exchange 中的存放形态。同一段路由，键是"消息头字符串"还是"反序列化后的 JSON 字段"，在不同失败场景下表现不同。

9.1 三种取键方式及其代价

取键方式	优点	失效或误判场景
从 Kafka 消息头取（生产者在记录头写入 eventId）	无需反序列化即可去重，开销最小	上游未统一写入、头被中间链路丢弃、头编码不一致
从 JSON 体用表达式提取	与业务契约绑定，直观	反序列化失败时取不到键，异常发生在去重之前
用整条消息摘要	不依赖上游提供 ID	字段顺序、空格、数值精度差异导致同一业务事件摘要不同

工程上的取舍建议：优先要求上游在消息中提供稳定业务 ID，并把它同时写入 Kafka 记录头。这样路由可以在反序列化之前用记录头去重，把"坏消息"的重复投递成本降到最低。若上游无法改造，再退回用体字段提取，并在文档里写明这是假设。

9.2 反序列化失败发生在去重之前会怎样

如果路由是"先 unmarshal 再进 idempotentConsumer"，那么一条格式错误的消息会在反序列化阶段抛异常。此时：

幂等仓库尚未查询，也没有记录；
错误处理器若配置为无限制重试，同一条坏消息会被反复重试，永远进不了去重分支；
若配置为进入死信，则坏消息被搬走，位点如何处理仍取决于提交策略。

这是一个典型的"去重帮不上忙"的边界：幂等消费者只能拦截能被正确解析并算出键的消息。可复现的观察方式（示意，需在自己环境执行）：

向主题发送非法 JSON，例如 {"eventId":（截断）。
预期：日志出现反序列化异常，业务处理器未被调用，camel_idem 表没有新增该键对应记录。
若错误处理器配置了最大重试次数，预期日志中同一偏移量出现多次重试记录，随后进入死信或抛出最终异常。

对应的防御写法是把"取键、校验、去重"前置，把"重活"后置，并用一个显式的校验处理器在去重之前把明显无效的消息路由到死信：

java 复制代码

from("kafka:order-events?groupId=points-group")
  .routeId("order-points-hardened")
  .process(exchange -> {
      String raw = exchange.getMessage().getBody(String.class);
      // 只做最轻量的可用性判断，不在这里做业务校验
      if (raw == null || raw.isBlank()) {
          throw new IllegalArgumentException("empty payload");
      }
  })
  .unmarshal().json()
  .idempotentConsumer(jsonpath("$.eventId"), idempotentRepository)
    .process(new PointsProcessor(pointsService))
  .end();

这段仍是示意：jsonpath 的返回类型、idempotentRepository 的注入方式需按版本核对。意图是说明校验与去重的先后顺序会影响重复成本，而不是提供一个可直接上线的完整实现。

十、让仓库写入与业务写入共享一个事务

前文结论是"不同事务边界时无法严格保证恰好一次"。本节给出一个可操作的收敛方向：把幂等记录表放在与业务表相同的数据库中，并让两者在同一数据库事务内提交。

10.1 结构上的前提

业务表（如 points）和幂等表（如 camel_idem）在同一数据源、同一 schema 下，能参与同一本地事务；
路由使用的处理器在同一个事务模板内执行，异常能让事务回滚；
数据库支持唯一约束冲突的确定行为（插入重复主键报错），这样才能用"先插入幂等键，冲突即视为重复"的策略。

10.2 用唯一约束承担去重的写法

相比"查询是否已存在，再决定是否处理"，更稳的是"先尝试插入幂等键，插入成功才处理业务"，让数据库的唯一约束成为并发下的裁决者：

java 复制代码

public class PointsProcessor implements Processor {
  private final JdbcTemplate jdbc;

  public PointsProcessor(JdbcTemplate jdbc) { this.jdbc = jdbc; }

  @Override
  public void process(Exchange exchange) {
    String eventId = exchange.getProperty("idemKey", String.class);
    String customerId = exchange.getMessage().getHeader("customerId", String.class);
    Integer amount = exchange.getMessage().getHeader("amount", Integer.class);

    // 期望：整个方法运行在同一个数据库事务内
    jdbc.update("INSERT INTO camel_idem(idem_key) VALUES (?)", eventId);
    jdbc.update("UPDATE points SET total = total + ? WHERE customer_id = ?", amount, customerId);
  }
}

说明与边界：

若插入幂等键抛唯一约束异常，说明该键已处理过，此时应回滚并让路由走"跳过"分支，而不是把异常当作业务失败重试；
若 UPDATE 影响行数为 0（客户行不存在），是否回滚取决于业务语义：要么回滚使整条消息重投，要么先插入客户行再更新，需明确选择；
该写法要求事务由外层控制（例如通过 Spring 的事务模板把处理器包起来），示意代码没有展示事务注解或模板，不能假定其自带事务。
这里的"恰好一次"仅限该数据库内的业务效果；若下游还有远程系统，跨系统仍不成立。

10.3 预期观察与验证

在本地用内存数据库验证时，可按以下方式观察（预期结果按设计给出，非实测记录）：

发送一条合法消息，预期 points 增加、camel_idem 新增一行。
发送完全相同的消息，预期进入唯一约束冲突分支，points 不再增加。
人为让 UPDATE 语句失败（例如临时改成引用不存在的列），预期整条消息回滚，camel_idem 不留下该键，重投后仍会被重新处理。第 3 条正是"同一事务"带来的行为差异，可与 6.1 的反例对照理解。

十一、重试策略与去重的配合方式

前面提到 Camel 内部重试会放大副作用。这里补一个判断框架，帮助在配置重试前先想清楚"这条路由能不能重试"。

11.1 只有三类操作可以安全重试

幂等写 ：如 UPDATE ... SET total = total + ? 配合唯一键插入，重复执行不改变结果；
可判定的读：只读查询，重试只是多一次读；
外部已幂等：下游接口接受幂等键并保证同一键只生效一次。

"先查后写""发送通知""扣减库存"这类操作默认不满足上述三点，必须显式加幂等键或改为条件更新。

11.2 路由层面可观察的重试行为

text 复制代码

from(kafka)
   |
   +--> idempotentConsumer(key)
          |-- 命中 --> 跳过 --> 提交位点(策略需明确)
          |-- 未命中 --> 业务处理器 --异常--> 错误处理器重试
                                           |
                                           +-- 重试耗尽 --> 死信 / 抛出

关键观察点：

重试发生在同一条消息、同一个 Exchange上，幂等键在重试期间不变；因此若仓库写入发生在业务处理器内部（如 10.2 的写法），第一次失败回滚后键不存在，重试可以重新插入；
若采用"Camel 幂等消费者在业务成功后写仓库"的默认顺序，业务失败时仓库不写，重试行为与前者类似；但业务部分成功（如远程调用已生效）时，两者都无法阻止重复；
死信路径上的消息是否推进位点，必须显式决定，否则会出现"反复投递到死信"的观察结果。

11.3 一个容易忽略的配置边界

若路由把消息拆分（split）后分别处理，每个子消息会得到新的 Exchange。此时如果在拆分之后才做幂等判断，键可能相同而子消息不同，去重语义会被破坏；正确做法是在拆分之前完成整条事件级的去重，或在拆分后为每个子消息构造稳定的复合键。这条结论不依赖具体版本，但具体 API 行为需核对。

十二、键的生命周期与清理策略

幂等表不是只增不减就万事大吉。键的保留期必须与"消息可能重投的最长时间窗口"对齐，短了会漏判重复，长了会无限膨胀并且拖慢唯一索引。

12.1 保留期如何估算

需要考虑的最长重投窗口大致由三部分组成：

主题的消息保留时间；
消费者最长停机或积压追赶时间；
死信重放的时间跨度。

如果幂等键的保留期短于上述之和，一条很晚才被重放的消息就会因为键已被清理而被当成新消息处理。这个结论是推理而非框架保证，需结合自己环境的保留配置判断。

12.2 清理的可行做法与风险

按时间删除：定期删除早于保留期的记录。风险是删除与正在进行的事务并发时，可能删掉刚插入的键；应使用"早于某时间点"的条件，避免删除新记录。
分区表按时间滚动：把幂等表按天分区，删除过期分区。风险是分区键设计与查询条件不匹配时性能下降。
分布式 KV 的 TTL：设置过期时间。风险是 TTL 早于业务完成会误判，前文仓库选型表已提过。

清理脚本本身也要能重复执行而不报错，这是运维层面的幂等。

十三、可复现实验清单与判定标准

为便于在自己环境验证，这里给出一个不依赖真实事故的验证矩阵。所有"预期"均为设计意图，实际日志与耗时以你的环境为准。

实验	操作	预期观察	若不符合说明什么
正常去重	同一 eventId 发送两次	第二次业务处理器未执行，表中该键仅一行	仓库未生效或键提取不对
键不稳定	同一订单两次变更用不同 eventId	两次都执行	键定义正确
键过粗	两次变更复用同一 eventId	第二次被跳过	键粒度错误，导致丢失更新
事务错配	让业务写失败	幂等键不应残留	事务未覆盖两者
坏消息	发送非法 JSON	业务不执行，按策略重试或入死信	去重位置或错误处理配置问题
多实例	两个实例消费同一分区	内存仓库会失效，持久仓库不失效	仓库选型不满足跨进程要求

执行顺序建议：先单实例跑通正常路径，再逐步引入失败与多实例，避免一次引入多个变量导致无法归因。每次实验后清理主题、清空幂等表或重建内存库，保证下一轮从干净状态开始。

十四、边界小结

本段补充的实质是四个容易被忽略的边界：取键发生在反序列化之前还是之后、幂等写入与业务写入是否共享同一事务、重试是否只作用于可安全重试的操作、键的保留期是否覆盖最长重投窗口。它们都不改变前文的主结论，但决定了同一套路由在真实重复投递下是"减少重复"还是"看似去重、实际漏判"。把这些边界写进接口契约和运维文档，比在代码里堆更多判断更有效。

十五、再均衡与分区撤销：最容易漏掉的两段窗口

前文把再均衡列为重复来源，但没有拆开看"旧成员失去分区"和"新成员接管分区"之间的时间差。这段窗口里发生的事，决定了你的提交策略是否真的有效。

15.1 失去分区后处理仍在跑

Kafka 消费者在再均衡时会被通知分区即将被撤销（revoke）。如果此时某条消息的业务处理已经进入数据库调用、但事务还没提交，那么可能出现两种方向相反的结果：

撤销后应用继续把这条消息处理完并提交位点：若提交发生在分区已被移交给新成员之后，这次提交可能被拒绝或产生不确定行为，具体以客户端版本文档为准；
撤销后应用中止处理、回滚事务：消息未被处理，新成员从上次提交位点重读，属于正常重投，不是重复。

关键判断标准是："位点是否已提交"与"业务事务是否已提交"谁先落地。如果在撤销窗口里两者顺序颠倒，就会出现前文 6.1 描述的错配。

15.2 可观察的取证方式

在测试环境让两个实例交替启停，观察日志中分区分配变化与业务处理器输出（示意，需自行执行）：

text 复制代码

实例 A: partitions assigned=[order-events-0]
实例 A: 处理 evt-1001 开始
实例 B: 启动，触发再均衡
实例 A: partitions revoked=[order-events-0]
实例 A: 处理 evt-1001 结束（事务提交结果需看日志）
实例 B: partitions assigned=[order-events-0]
实例 B: 从上次提交位点重读，可能再次处理 evt-1001

判定要点：如果实例 B 再次处理 evt-1001 时幂等仓库命中，说明去重生效；如果未命中且积分被再次累加，说明实例 A 的事务提交晚于幂等记录可见，或幂等记录根本未提交。这不是框架 bug，而是提交边界选择的结果。

15.3 缩短窗口的工程手段

让业务处理尽量短，避免在处理器里做长耗时远程调用；长任务应改为"快速落本地待处理表 + 异步执行"，去重键在落表时即为唯一约束；
若组件提供了再均衡监听回调，可在撤销时主动停止接收新消息，具体接口与行为需按版本核对；
不要假设"单分区单实例"能长期成立，滚动发布和扩容都会破坏这个假设。

十六、跳过分支的位点推进：一个必须显式决策的分支

前文提到幂等命中时要考虑是否推进位点。这里把它展开成一个可执行的决策表，因为它直接决定重投是"结束"还是"无限循环"。

场景	幂等命中时是否推进位点	理由	风险
业务效果已确认提交到持久存储	推进	效果已存在，无需再处理	若幂等记录来自回滚的事务，可能误推进（需保证记录可见即效果可见）
幂等记录写在业务事务之前、业务可能回滚	谨慎	记录可能"假存在"	推进会丢失业务效果
下游远程系统已幂等且状态未知	不推进，转人工	无法确认效果	积压

这张表的核心不是给出唯一答案，而是提醒：跳过分支必须有明确的提交动作或明确的"不提交并告警"策略，不能留空。 留空的结果通常是消费者在同一个偏移量上反复命中幂等、反复跳过、永不前进，表现为分区 lag 不下降而业务日志持续输出"已跳过"。

可复现的观察：发送一条合法消息使幂等键存在，再发送同一消息，观察分区当前消费位点是否随第二条消息前进。若不前进，即证明跳过分支没有提交。这是判断实现是否完整的低成本手段。

十七、并发去重：唯一约束之外还要想清楚的三件事

使用唯一约束承担去重时，并发下的行为依赖数据库的具体语义，这里列出三个必须验证的点。

17.1 冲突是异常还是"影响 0 行"

不同数据库、不同插入语句在遇到重复键时，可能抛出唯一约束异常，也可能返回影响行数 0（取决于是否使用了冲突忽略语法）。处理器必须能区分这两种情况，否则会把"重复"误当成"业务失败"从而触发重试。验证方式：在同一事务里对同一键插入两次，观察异常类型或返回值。

17.2 冲突后事务是否已失效

某些数据库在事务中发生约束冲突后，整个事务进入不可继续状态，后续语句会报错。此时"捕获异常后继续执行跳过逻辑并提交"是不成立的，必须回滚整个事务。若你的跳过分支是在同一事务内捕获异常后继续，需要先用最小用例确认数据库是否允许。

17.3 键的并发可见性

两个实例同时处理同一键时，先插入者持有未提交的行，后插入者通常会被阻塞直到前者提交或回滚，然后得到冲突或成功。这意味着重复消息的处理会被数据库串行化，吞吐与键的分布相关。若同一键短时间高频重复，可能出现等待超时，应把超时设为可诊断的值并在日志中记录，而不是无限等待。

十八、把边界写进契约：三个交付物

前文分散提到"写进接口契约"，这里给出具体形态，便于团队落地。

事件契约文档 ：明确 eventId 的生成规则、重发时是否保持不变、跨系统是否复用同一 ID、字段精度与格式；对没有稳定 ID 的上游，明确内容哈希的字段集合与归一化规则（如数值统一为字符串、去除空白），并声明其误判风险。
路由边界说明：用一页文字写清"本路由能挡住什么、挡不住什么"，包括：只对可解析消息去重、只在数据库内保证效果唯一、跨系统调用仍可能重复、键保留期多长。
运维处置手册：lag 持续不下降时的检查顺序（跳过分支是否提交 → 幂等表是否被清理误删 → 死信是否堆积 → 是否坏消息循环重试），以及每项对应的观察命令或日志关键字。

这三个交付物的价值在于：当重复真的发生时，团队能快速判断是契约问题、路由问题还是运维问题，而不是把"加幂等"当作唯一手段反复加码。

十九、本段补充的适用边界

本节内容全部建立在同一前提上：Kafka 仅作为端点、Camel 4.22 LTS 与 Java 21、去重键由上游保证稳定、幂等仓库可跨进程持久化。超出该前提（例如上游无法提供稳定 ID、或业务效果落在多个异构系统）时，前文的"减少重复"结论仍然成立，但"严格唯一"不再成立，必须引入对账或人工核查。所有执行步骤与预期输出均为设计意图，读者需在自有环境复现后据实记录，不得将本文示例当作已验证的实测结论。

二十、死信与重试队列交接时的位点归属

前文把错误处理器、死信路径和位点推进分散讨论过，这里集中说明一个交接点：当一条消息处理失败并被移交到死信或重试主题时，谁负责让原分区位点前进。若这一点含糊，常见的观察就是原主题 lag 不下降，而死信主题持续增长。

20.1 三条可能的执行顺序

失败消息的去向大致有三种编排方式，每种对应不同的位点归属：

先投递死信，再提交原位点：投递成功才算处理结束。若投递本身失败，原位点不应提交，消息会被重投，可能产生多次死信副本，因此死信侧也需能容忍重复。
先提交原位点，再投递死信：提交成功但投递失败时，消息从原主题消失，只能依赖死信写入失败时的补偿日志或审计表找回，风险最高。
不提交，交由错误处理器重试耗尽后抛出：最终是否提交取决于组件在异常路径上的默认行为，必须以对应版本文档确认，不能凭直觉假设。

工程上倾向第一种顺序，因为它把"消息已安全转移"作为位点前进的前提。代价是死信主题必须接受重复副本。

20.2 可直接观察的判定方式

在与前文相同的单分区测试主题上，构造一条必然抛出业务异常的消息，然后观察三件事（预期结果按设计给出，需自行执行）：

原主题该分区的 lag 是否随时间归零；
死信主题是否恰好收到预期份数的副本；
原主题中该偏移量的重试日志是否停止增长。

若 lag 归零而死信为空，说明消息被吞掉，检查是否先提交后投递且投递失败；若死信持续增长而 lag 不降，说明投递成功但原位点没有提交，属于顺序编排缺陷。

20.3 重试主题与延迟

把失败消息投递到重试主题再延迟回流的做法，会拉长单条消息的生命周期。此时要重新审视前文的键保留期估算：重试主题里停留的时间也计入最长重投窗口。若幂等键在回流前被清理，回流消息会被当成新事件处理。延迟时长与保留期必须一起配置，并在运维文档里写清两者的关系。

二十一、无稳定业务 ID 时的降级方案

前文假设上游能提供稳定 eventId。现实中遗留系统常见的问题是事件体里只有业务字段。此时不要直接宣布"无法去重"，而应分层降级，并把每一层的误判方向写明。

21.1 三层降级

层次	键的构造	误判方向	适用条件
首选	上游业务 ID	无	上游可改造
次选	业务主键 + 版本号或变更时间戳	两种事件共用同一版本号时会漏判	上游能保证版本单调递增
兜底	规范化后的内容摘要	内容相同但语义不同的两次事件被判为重复	写入侧本身已幂等，去重只用于降负载

规范化要明确规则：字段排序、数值统一为字符串形式、去除不影响语义的空白。规则本身要写进契约文档，否则同一系统换一个序列化库就可能得到不同摘要。

21.2 摘要方案的风险与验证

内容摘要最大的问题是把"同一内容"当作"同一事件"。若业务允许两次内容相同但独立的操作（例如两笔金额相同的充值），摘要方案会把第二笔丢掉。验证方法很直接：构造两条字段完全相同但业务上独立的输入，观察第二条是否被跳过。如果被跳过，说明该场景不适合摘要方案，要么改用上游 ID，要么把去重边界收缩到写入侧唯一约束，不再做消息级跳过。

二十二、多实例下的最小验证程序

前文把多实例列为内存仓库的失效场景，但没有给出判定步骤。下面是一套不依赖真实事故的最小验证流程，结论以你自己环境的日志为准。

text 复制代码

步骤1  启动实例 A（持久化幂等仓库），确认分区被分配
步骤2  停止实例 A，确认分区被释放
步骤3  启动实例 B，确认分区被分配给 B
步骤4  在 B 上重放一条 A 已处理完成的同一 eventId
步骤5  观察：B 是否跳过业务处理

判定：若第 5 步跳过了业务处理，说明仓库跨进程有效；若 B 再次累加了积分，说明 A 处理时根本没写仓库，或写到了无法被 B 读到的地方。把内存仓库单独再跑一遍同样的步骤，应当观察到重复处理，这正好用来确认测试装置本身是有效的。

注意步骤 2 要等待分区释放完成再启动 B，否则两次启动可能重叠，观测结果会混杂再均衡窗口内的行为，难以归因。

二十三、把本节纳入判定清单

本段补充可以归纳为三条可检查项，与前面的实验矩阵并列使用：

失败消息的去向与位点提交的先后顺序被明确写出，而不是留在默认行为上；
无稳定业务 ID 时采用的降级方案及其误判方向被写进契约，而非临时在代码里拼接字符串；
多实例验证包含"停止---释放---接管---重放"四步，且用内存仓库做过对照组。

这三条不改变前文主结论，只是把"去重边界"从单机推理延伸到交接、降级与多实例三个真实运营场景。所有步骤与预期均为设计意图，读者需在自有环境复现并据实记录，不得将本文示例当作已完成的实测结果。

二十四、批量读取与幂等判定：一次拉取里既有重复又有新消息

前面各节大多以"一条消息一个 Exchange"为默认心智模型。接入真实端点后，还需要面对同一批拉取内多条记录混合出现的情况：其中有一部分键已存在、一部分是新键。这会把去重判定从"单次判定"变成"一批内的逐条判定"，也把位点推进从"单点提交"变成"批量推进"。

24.1 批内判定必须逐条进行

幂等消费者的判定单位是每条消息各自的键，批内不同记录之间互不影响。但在编排上要避免一个常见笔误：把判定表达式误写成对整个批次的键。示意结构如下：

text 复制代码

一次 poll 得到 [evt-1, evt-2, evt-1]
   |
   +--> idempotentConsumer(逐条 key)
          evt-1 -> 未命中 -> 业务写入 -> 记录
          evt-2 -> 未命中 -> 业务写入 -> 记录
          evt-1 -> 命中   -> 跳过

预期观察：业务写入恰好两次，幂等表新增两个键。这一结果依赖"同一批次内前一条记录写入的记录对后一条可见"。如果幂等仓库自身有缓存层或延迟写入，批内去重可能失效，需要以仓库实现文档确认。

24.2 批量提交与单条失败的关系

如果位点提交按"整批推进"，而批内某条记录处理失败并被重试耗尽，那么整批后续记录是否推进就成为一个显式决策。两种编排的观察结果不同：

失败即中止整批处理：该批次未提交，重启后整批重放，已成功的记录靠幂等跳过，代价是重复的无效处理。
允许跳过失败记录并推进到其后的位点：失败记录需要先被安全转移到死信或重试主题，否则会直接丢失。

可复现的判定方式：在单分区主题上连续发送三条消息，让中间那条必然失败，观察重启后哪几条被再次处理、哪几条被跳过。这一观察能直接暴露编排采用的是整批中止还是逐条推进。所有结果以自己环境为准，不构成对框架默认行为的保证。