消息队列 / 系统课时
幂等消费者实现
幂等消费者实现
幂等消费要解决的不是“RabbitMQ 会不会重复”,而是“同一业务事件再次到达时,结果是否仍然正确”。本节把稳定事件标识、去重记录、业务状态校验和数据库事务放进同一个处理边界,并把 ACK 放到事务提交之后。
学习目标
- 使用
event_id与消费者名称建立可持久化的去重键 - 在同一数据库事务中完成去重登记和业务状态变更
- 正确安排 ACK、重试和不可恢复错误,避免“已确认但业务未提交”
先确定一次消费的提交点
消费者使用手动 ACK 时,RabbitMQ 只有收到 basic.ack 后才会把该次投递视为成功处理。进程断开、Channel 关闭或 ACK 未到达时,消息可能再次投递,所以业务逻辑必须能够承受重复执行。
可靠的提交点应当是:数据库事务先成功提交,然后才发送 ACK。若应用在数据库提交后、ACK 前崩溃,RabbitMQ 会再次投递;此时去重表能够识别已经处理过的 event_id,消费者只需再次 ACK,不再重复修改业务数据。

用两层条件保证幂等
第一层是事件级去重:以 (consumer_name, event_id) 建唯一键。同一消费者看到同一事件两次时,第二次插入返回 0 行,不再执行副作用。消费者名称必须稳定,因为不同订阅者有权各自处理同一事件。
第二层是业务状态校验:即使上游错误地用不同 event_id 重发了语义相同的事件,也不应重复扣款、重复发货或把状态从非法节点强行推进。去重键保护“同一个事件”,状态机保护“同一个业务动作”。
CREATE TABLE consumer_event_log (
consumer_name VARCHAR(120) NOT NULL,
event_id UUID NOT NULL,
processed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (consumer_name, event_id)
);
CREATE INDEX idx_orders_status
ON orders (order_id, status);这是数据结构定义。执行后应确认联合主键存在;业务表仍应保留自己的主键、唯一约束和合法状态迁移条件,不能把全部正确性都压在去重表上。
在一个事务里登记事件并修改业务
片段示例:以下代码使用 RabbitMQ Java Client、JDBC DataSource 和 Jackson。消息体假设包含 eventId 与 orderId。数据库提交成功后才 ACK;如果提交成功而 ACK 丢失,下一次投递会命中去重键,因此不会重复推进订单状态。
import com.fasterxml.jackson.databind.ObjectMapper;
import com.rabbitmq.client.Channel;
import javax.sql.DataSource;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.util.UUID;
final class OrderPaidHandler {
private static final String CONSUMER = "billing-order-paid";
private final DataSource dataSource;
private final ObjectMapper mapper;
OrderPaidHandler(DataSource dataSource, ObjectMapper mapper) {
this.dataSource = dataSource;
this.mapper = mapper;
}
void handle(Channel channel, long deliveryTag, byte[] body) throws Exception {
OrderPaidEvent event;
try {
event = mapper.readValue(
new String(body, StandardCharsets.UTF_8),
OrderPaidEvent.class
);
} catch (Exception invalidMessage) {
channel.basicReject(deliveryTag, false);
return;
}
try (Connection db = dataSource.getConnection()) {
db.setAutoCommit(false);
try {
boolean firstDelivery = registerEvent(db, event.eventId());
if (firstDelivery) {
applyOrderState(db, event.orderId());
}
db.commit();
} catch (IllegalStateException permanentError) {
db.rollback();
channel.basicReject(deliveryTag, false);
return;
} catch (Exception transientError) {
db.rollback();
channel.basicNack(deliveryTag, false, true);
return;
}
}
// ACK 放在数据库提交之后;ACK 丢失只会触发可安全吸收的重复投递。
channel.basicAck(deliveryTag, false);
}
private boolean registerEvent(Connection db, UUID eventId) throws Exception {
try (PreparedStatement ps = db.prepareStatement(
"INSERT INTO consumer_event_log(consumer_name, event_id) " +
"VALUES (?, ?) ON CONFLICT DO NOTHING")) {
ps.setString(1, CONSUMER);
ps.setObject(2, eventId);
return ps.executeUpdate() == 1;
}
}
private void applyOrderState(Connection db, String orderId) throws Exception {
try (PreparedStatement ps = db.prepareStatement(
"UPDATE orders SET status='PAID' WHERE order_id=? AND status='CREATED'")) {
ps.setString(1, orderId);
if (ps.executeUpdate() == 1) return;
}
try (PreparedStatement ps = db.prepareStatement(
"SELECT status FROM orders WHERE order_id=?")) {
ps.setString(1, orderId);
try (ResultSet rs = ps.executeQuery()) {
if (rs.next() && "PAID".equals(rs.getString(1))) return;
}
}
throw new IllegalStateException("order state does not allow PAID");
}
record OrderPaidEvent(UUID eventId, String orderId) {}
}示例中的 basicNack(..., true) 只用于表达“临时失败可再次投递”。生产环境不要让持续故障形成高速原地重投,应给重试设置次数和退避,并把不可恢复消息送入死信处理路径。
验证重复投递不会重复生效
向同一队列连续发送两次完全相同的事件,其中 event_id=<ID>、order_id=ORD-1001。处理完成后执行下面的查询;如果第二次投递被正确吸收,去重表中只有一行,订单状态仍然只是 PAID。
SELECT count(*) AS dedup_rows
FROM consumer_event_log
WHERE consumer_name = 'billing-order-paid'
AND event_id = '<ID>';
SELECT status
FROM orders
WHERE order_id = 'ORD-1001';预期结果
dedup_rows
1
status
PAID<ID> 替换为实际事件 UUID。验收时还应主动模拟“数据库已提交但 ACK 前进程退出”:恢复消费者后消息会再次到达,但 dedup_rows 仍为 1,业务状态不再变化;这正是幂等消费者需要保证的结果。