消息队列 / 系统课时
Outbox 事件发布模式
Outbox 事件发布模式
当一次业务写入既要落库又要发 Kafka 时,最危险的不是“发送失败”,而是数据库与消息系统各自成功一半。Outbox 用同一个本地事务同时写业务表和事件表,再由独立发布器或 CDC 异步投递,把跨系统原子性问题改造成可恢复的最终一致性问题。
学习目标
- 能说明 Outbox 为什么能消除“业务已提交但事件丢失”的窗口
- 能设计业务表、Outbox 表与本地事务的最小实现
- 能处理重复发布、发布确认与历史事件清理
先看清双写为什么不可靠
直接在业务代码里“先写数据库,再发 Kafka”,两个动作之间没有共同事务。数据库提交成功后进程崩溃,事件就永远不会发出;反过来先发消息再写数据库,则可能让消费者看到一个最终并不存在的业务状态。
Outbox 的关键不是让数据库和 Kafka 参加同一个分布式事务,而是只要求数据库内部保持原子性:业务记录与待发布事件必须同时提交或同时回滚。之后的消息发布允许重试。

用一个事务写业务数据与事件
下面示例使用 PostgreSQL。event_id 是事件唯一键,aggregate_id 指向业务实体,published_at 仅适用于轮询发布器;若采用 CDC,可以不依赖这个字段判断是否已发送。
CREATE TABLE orders (
order_id BIGINT PRIMARY KEY,
customer_id BIGINT NOT NULL,
amount NUMERIC(12, 2) NOT NULL,
status TEXT NOT NULL
);
CREATE TABLE outbox_events (
event_id UUID PRIMARY KEY,
aggregate_type TEXT NOT NULL,
aggregate_id BIGINT NOT NULL,
event_type TEXT NOT NULL,
payload JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
published_at TIMESTAMPTZ
);
BEGIN;
INSERT INTO orders(order_id, customer_id, amount, status)
VALUES (1001, 42, 199.00, 'CREATED');
INSERT INTO outbox_events(
event_id, aggregate_type, aggregate_id, event_type, payload
) VALUES (
'11111111-1111-1111-1111-111111111111',
'Order',
1001,
'OrderCreated',
'{"orderId":1001,"customerId":42,"amount":199.00}'
);
COMMIT;
SELECT o.order_id, o.status, e.event_type
FROM orders o
JOIN outbox_events e ON e.aggregate_id = o.order_id
WHERE o.order_id = 1001;预期结果
CREATE TABLE
CREATE TABLE
BEGIN
INSERT 0 1
INSERT 0 1
COMMIT
order_id | status | event_type
----------+---------+--------------
1001 | CREATED | OrderCreated
(1 row)如果任意一条 INSERT 失败,整个事务都会回滚,因此不会出现“订单存在但事件缺失”的中间状态。
选择轮询发布器还是 CDC
轮询发布器实现简单:周期性查询 published_at IS NULL 的记录,发送成功后再更新 published_at。为了避免多个发布实例抢同一行,通常需要 FOR UPDATE SKIP LOCKED、批次大小和失败重试策略。它的代价是额外查询与状态更新。
CDC 则读取数据库 WAL/binlog 里的变更,把 Outbox 插入转换成 Kafka 事件。优点是业务库不需要轮询和“标记已发送”写放大,缺点是要运维 CDC 组件,并明确表结构变更、断点恢复和事件路由规则。
把重复当成正常路径
Outbox 通常提供的是“至少一次”发布语义,因此事件必须有稳定的 event_id。消费者可以把这个 ID 作为幂等键:已处理过就直接跳过,未处理才执行业务副作用。
事件表也不能无限增长。轮询模式可以在确认发布并经过安全保留期后归档或删除;CDC 模式则要确认 CDC 已经越过对应日志位置后再清理。真正可靠的 Outbox 不是“绝不重复”,而是业务数据不丢、事件可重放、重复可识别。