消息队列 / 系统课时
实现数据库幂等与 Outbox
实现数据库幂等与 Outbox
订单服务同时修改数据库并发布 Kafka 事件时,最危险的情况是“数据库成功但消息没发出”或“消息重复发送”。这里用唯一约束和条件更新保证消费幂等,再用同一数据库事务写入 Outbox,让业务状态与待发布事件一起提交,最后由后台任务可靠投递。
学习目标
- 用唯一约束和条件更新阻止重复事件产生重复业务副作用
- 在同一事务中完成业务写入与 Outbox 记录写入
- 理解 Outbox 只能保证可恢复的至少一次发布,下游仍需幂等
建立幂等与 Outbox 表
最小模型需要三类数据:订单当前状态、已经处理过的事件 ID、等待发布的 Outbox 事件。processed_event.event_id 的主键负责拦截重复消费,订单状态条件负责阻止非法重复迁移,outbox_event 则承担“事务提交后再发送 Kafka”的缓冲。

下面以 PostgreSQL 为例建立表结构。
CREATE TABLE orders (
id UUID PRIMARY KEY,
status VARCHAR(32) NOT NULL,
version BIGINT NOT NULL DEFAULT 0
);
CREATE TABLE processed_event (
event_id UUID PRIMARY KEY,
processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE outbox_event (
id BIGSERIAL PRIMARY KEY,
event_id UUID NOT NULL UNIQUE,
aggregate_id UUID NOT NULL,
event_type VARCHAR(64) NOT NULL,
payload JSONB NOT NULL,
status VARCHAR(16) NOT NULL DEFAULT 'NEW',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
published_at TIMESTAMPTZ
);
CREATE INDEX idx_outbox_new
ON outbox_event (status, id);预期结果
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE INDEX在一个事务里完成三次写入
处理支付事件时,先尝试登记 event_id。如果插入受唯一约束影响而没有新增行,说明该事件已经成功处理过,可以直接返回。随后使用带前置状态的条件更新把订单从 CREATED 改为 PAID,最后写入 Outbox。三步放在同一个数据库事务中,任意一步失败都会一起回滚。
以下是片段示例,依赖 Spring JDBC、Jackson 和事务管理器,并假设 OrderPaidEvent 已提供 eventId() 与 orderId()。
package com.example.orders;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
public class OrderPaidHandler {
private final JdbcTemplate jdbc;
private final ObjectMapper objectMapper;
public OrderPaidHandler(JdbcTemplate jdbc, ObjectMapper objectMapper) {
this.jdbc = jdbc;
this.objectMapper = objectMapper;
}
@Transactional
public void handle(OrderPaidEvent event) throws JsonProcessingException {
int firstSeen = jdbc.update(
"INSERT INTO processed_event(event_id) VALUES (?) " +
"ON CONFLICT (event_id) DO NOTHING",
event.eventId());
if (firstSeen == 0) {
return; // 重复事件已经处理过,不再产生业务副作用。
}
int changed = jdbc.update(
"UPDATE orders SET status='PAID', version=version+1 " +
"WHERE id=? AND status='CREATED'",
event.orderId());
if (changed != 1) {
throw new IllegalStateException("order state transition rejected");
}
String payload = objectMapper.writeValueAsString(event);
jdbc.update(
"INSERT INTO outbox_event(event_id, aggregate_id, event_type, payload) " +
"VALUES (?, ?, 'OrderPaid', CAST(? AS jsonb))",
event.eventId(), event.orderId(), payload);
}
}这里有两个互补的幂等闸门:唯一约束回答“这个事件是否已经处理”,条件更新回答“当前业务状态是否允许这次变化”。如果订单更新或 Outbox 插入失败,事务会连同 processed_event 一起回滚,下一次 Kafka 重投仍可重新处理。
由 Outbox Relay 发布事件
后台发布器只扫描 NEW 记录。FOR UPDATE SKIP LOCKED 允许多个实例并发领取不同记录,避免同一批数据被同时处理。发送 Kafka 成功后再把记录标记为 SENT。
以下是片段示例,依赖 Spring JDBC、Spring Kafka 和已启用的定时任务能力。
package com.example.orders;
import java.util.List;
import java.util.concurrent.TimeUnit;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Transactional;
@Component
public class OutboxRelay {
private final JdbcTemplate jdbc;
private final KafkaTemplate<String, String> kafkaTemplate;
public OutboxRelay(JdbcTemplate jdbc, KafkaTemplate<String, String> kafkaTemplate) {
this.jdbc = jdbc;
this.kafkaTemplate = kafkaTemplate;
}
@Scheduled(fixedDelay = 1000)
@Transactional
public void publishBatch() throws Exception {
List<OutboxRow> rows = jdbc.query(
"SELECT id, aggregate_id, payload " +
"FROM outbox_event WHERE status='NEW' " +
"ORDER BY id LIMIT 100 FOR UPDATE SKIP LOCKED",
(rs, rowNum) -> new OutboxRow(
rs.getLong("id"),
rs.getObject("aggregate_id").toString(),
rs.getString("payload")));
for (OutboxRow row : rows) {
// 等待 broker 确认后再修改数据库状态。
kafkaTemplate.send("orders.events", row.aggregateId(), row.payload())
.get(5, TimeUnit.SECONDS);
jdbc.update(
"UPDATE outbox_event " +
"SET status='SENT', published_at=now() " +
"WHERE id=? AND status='NEW'",
row.id());
}
}
record OutboxRow(long id, String aggregateId, String payload) {}
}生效行为是:数据库提交后,即使应用进程立即崩溃,NEW 记录仍留在 Outbox 中,下一次调度会继续发送;如果 Kafka 发送成功但事务在标记 SENT 前回滚,这条事件可能再次发布,因此语义仍是至少一次而不是恰好一次。
验证重复消费和可恢复发布
为让第一轮结果可复现,先暂停 Relay,或在测试 Profile 中临时禁用调度,然后准备一笔订单。
INSERT INTO orders(id, status)
VALUES ('11111111-1111-1111-1111-111111111111', 'CREATED');预期结果
INSERT 0 1使用固定 event_id 为 22222222-2222-2222-2222-222222222222 的测试事件调用两次 handle 后,再查询订单、处理记录和 Outbox。第二次处理会命中 processed_event 唯一约束而直接返回。
SELECT id, status, version
FROM orders
WHERE id = '11111111-1111-1111-1111-111111111111';
SELECT count(*) AS processed_count
FROM processed_event
WHERE event_id = '22222222-2222-2222-2222-222222222222';
SELECT event_id, status
FROM outbox_event
WHERE event_id = '22222222-2222-2222-2222-222222222222';预期结果
id | status | version
--------------------------------------+--------+--------
11111111-1111-1111-1111-111111111111 | PAID | 1
processed_count
---------------
1
event_id | status
--------------------------------------+--------
22222222-2222-2222-2222-222222222222 | NEW当 Relay 成功投递后,最后一行的 status 应变为 SENT,published_at 被填写。生产环境还应监控 NEW 记录数量和最老记录年龄;它们持续增长通常说明 Kafka 不可达、序列化失败或发布器停摆。