Java 后端 / 系统课时
保证消息处理幂等
保证消息处理幂等
本课解决消息至少一次投递下的重复消费问题。你将用稳定事件编号、数据库唯一约束和同一事务内的去重记录保护业务写入,使消费者在重启、超时或位点未提交时能够安全重放。
学习目标
- 为事件选择跨重试保持不变的业务唯一键
- 使用数据库唯一约束原子地判定消息是否首次处理
- 正确划定去重记录、业务写入与消费位点之间的事务边界
幂等的判断标准
幂等不是“没有重复消息”,而是同一业务事件执行一次或多次,最终业务状态相同。Kafka 的消息键主要用于分区和顺序控制,不能替代事件唯一编号;同一个订单可能产生多个不同事件,而同一个事件也可能因生产重试或消费恢复再次出现。
事件编号应由业务源头生成,并在所有转发、重试和死信回放中保持不变。例如支付成功事件使用 paymentEventId,而不是消费时间、Kafka 位点或消费者实例生成的随机值。
建立数据库去重约束
多实例消费者不能采用“先查询是否存在,再插入”的写法,因为两个实例可能同时查到不存在。正确方式是让数据库唯一约束完成原子竞争,并把消费组与事件编号组成主键,使不同逻辑消费者仍可各自处理同一事件。
CREATE TABLE consumed_message (
consumer_group VARCHAR(100) NOT NULL,
event_id VARCHAR(100) NOT NULL,
processed_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (consumer_group, event_id)
);
CREATE TABLE payment_record (
event_id VARCHAR(100) PRIMARY KEY,
order_id BIGINT NOT NULL,
amount NUMERIC(18, 2) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);预期结果
CREATE TABLE
CREATE TABLEconsumed_message 负责通用消费去重,payment_record.event_id 则是业务层第二道唯一约束。两层约束可以防止代码路径变化或人工补偿绕过通用去重后重复落账。
在同一事务内完成判重与业务写入
下面是 PostgreSQL 与 JdbcTemplate 的片段示例。插入去重记录返回 0 表示该事件已经处理,消费者直接正常返回;首次处理时,去重记录、支付记录和订单状态更新处于同一个数据库事务。
package com.example.payment.messaging;
import java.math.BigDecimal;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
public class PaymentSucceededConsumer {
private static final String GROUP_ID = "payment-order-updater";
private final JdbcTemplate jdbcTemplate;
public PaymentSucceededConsumer(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
@Transactional
@KafkaListener(topics = "payment-succeeded", groupId = GROUP_ID)
public void consume(PaymentSucceededEvent event) {
int inserted = jdbcTemplate.update("""
INSERT INTO consumed_message(consumer_group, event_id)
VALUES (?, ?)
ON CONFLICT DO NOTHING
""", GROUP_ID, event.eventId());
// 重复消息正常结束,不抛异常,也不再次执行副作用
if (inserted == 0) {
return;
}
jdbcTemplate.update("""
INSERT INTO payment_record(event_id, order_id, amount)
VALUES (?, ?, ?)
""", event.eventId(), event.orderId(), event.amount());
int updated = jdbcTemplate.update("""
UPDATE orders
SET payment_status = 'PAID'
WHERE id = ?
""", event.orderId());
if (updated != 1) {
throw new IllegalStateException("order not found: " + event.orderId());
}
}
public record PaymentSucceededEvent(
String eventId,
long orderId,
BigDecimal amount
) {
}
}生效行为:任一步骤抛出异常,数据库事务整体回滚,去重记录不会提前留下;数据库提交后若消费者在位点提交前崩溃,消息会再次投递,但唯一键冲突会让第二次处理直接结束。

Spring Kafka 的事务机制可以把监听器中的 Kafka 写入与消费位点纳入同一 Kafka 事务,但官方也明确区分:读取和业务处理本身仍可能再次发生。因而当副作用落在外部数据库时,仍应使用业务幂等,而不能只依赖 Kafka 事务。:contentReference[oaicite:1]{index=1}
验证重复消息不会重复落账
连续发送两次完全相同的 eventId 后,查询去重表和业务表。下面假设测试事件编号为 pay-2026-0001。
SELECT consumer_group, event_id, COUNT(*) AS row_count
FROM consumed_message
WHERE event_id = 'pay-2026-0001'
GROUP BY consumer_group, event_id;
SELECT event_id, COUNT(*) AS row_count
FROM payment_record
WHERE event_id = 'pay-2026-0001'
GROUP BY event_id;预期结果
consumer_group | event_id | row_count
-----------------------+-----------------+----------
payment-order-updater | pay-2026-0001 | 1
event_id | row_count
------------------+----------
pay-2026-0001 | 1若消费者还会调用支付、短信或物流等远程系统,应把同一个 eventId 作为对方支持的幂等键;若对方不支持幂等键,应先写本地命令表或 Outbox,再由独立任务可靠发送。数据库事务无法回滚已经成功的远程调用。