消息队列 / 系统课时

实现数据库幂等与 Outbox

实现数据库幂等与 Outbox

订单服务同时修改数据库并发布 Kafka 事件时,最危险的情况是“数据库成功但消息没发出”或“消息重复发送”。这里用唯一约束和条件更新保证消费幂等,再用同一数据库事务写入 Outbox,让业务状态与待发布事件一起提交,最后由后台任务可靠投递。

学习目标

  • 用唯一约束和条件更新阻止重复事件产生重复业务副作用
  • 在同一事务中完成业务写入与 Outbox 记录写入
  • 理解 Outbox 只能保证可恢复的至少一次发布,下游仍需幂等

建立幂等与 Outbox 表

最小模型需要三类数据:订单当前状态、已经处理过的事件 ID、等待发布的 Outbox 事件。processed_event.event_id 的主键负责拦截重复消费,订单状态条件负责阻止非法重复迁移,outbox_event 则承担“事务提交后再发送 Kafka”的缓冲。

订单数据库幂等与 Outbox 一致性链路

下面以 PostgreSQL 为例建立表结构。

sql
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);

预期结果

text
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE INDEX

在一个事务里完成三次写入

处理支付事件时,先尝试登记 event_id。如果插入受唯一约束影响而没有新增行,说明该事件已经成功处理过,可以直接返回。随后使用带前置状态的条件更新把订单从 CREATED 改为 PAID,最后写入 Outbox。三步放在同一个数据库事务中,任意一步失败都会一起回滚。

以下是片段示例,依赖 Spring JDBC、Jackson 和事务管理器,并假设 OrderPaidEvent 已提供 eventId() 与 orderId()。

java
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 和已启用的定时任务能力。

java
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 中临时禁用调度,然后准备一笔订单。

sql
INSERT INTO orders(id, status)
VALUES ('11111111-1111-1111-1111-111111111111', 'CREATED');

预期结果

text
INSERT 0 1

使用固定 event_id 为 22222222-2222-2222-2222-222222222222 的测试事件调用两次 handle 后,再查询订单、处理记录和 Outbox。第二次处理会命中 processed_event 唯一约束而直接返回。

sql
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';

预期结果

text
                  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 不可达、序列化失败或发布器停摆。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现数据库幂等与 Outbox

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通