架构与系统设计 / 系统课时
接入 Outbox 保证事件发布
接入 Outbox 保证事件发布
订单事务已经提交,进程却在发消息前退出,库存服务就可能永远不知道这笔订单。本篇把订单变化与待发事件放进同一个数据库事务,再补上后台认领、发布确认和清理规则,让发送失败可以恢复,而不是靠请求线程碰运气。
学习目标
- 实现订单状态与 Outbox 事件的原子提交。
- 区分发布确认与消费确认,处理发送结果不确定的窗口。
- 设计可恢复的后台发布和只清理已确认事件的规则。
同库提交的是发布责任
Outbox 是订单数据库中的待发事件表。业务事务只负责同时保存订单变化和事件;独立发布器随后读取已提交记录并发送。这样解决的是数据库与消息系统之间的双写缺口,而不是把两者变成一个跨系统事务。([AWS 文档][1])
这里的保证有前提:数据库提交可靠、未发送记录不被删除、发布器持续运行,故障与暂停任务最终得到修复。Outbox 保存了必须继续发布的责任,不承诺消费者马上成功,也不消除重复消息。([AWS 文档][1])

写入订单与不可变事件
下面采用 PostgreSQL 16,在新测试库的同一会话执行,账号需要建表权限。示例限定为单商品订单,1001 是固定测试订单号;事件 UUID 由数据库生成。PostgreSQL 16 内置 gen_random_uuid(),不需要为此另装扩展。([PostgreSQL][2])
CREATE SCHEMA outbox_demo;
CREATE TABLE outbox_demo.orders (
order_id bigint PRIMARY KEY,
sku text NOT NULL,
quantity integer NOT NULL CHECK (quantity > 0),
status text NOT NULL CHECK (status IN ('DRAFT', 'CONFIRMED')),
version integer NOT NULL DEFAULT 0
);
CREATE TABLE outbox_demo.outbox (
event_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
order_id bigint NOT NULL REFERENCES outbox_demo.orders(order_id),
event_type text NOT NULL,
aggregate_version integer NOT NULL,
schema_version integer NOT NULL DEFAULT 1,
payload jsonb NOT NULL,
state text NOT NULL DEFAULT 'PENDING'
CHECK (state IN ('PENDING', 'SENDING', 'SENT', 'PAUSED')),
attempts integer NOT NULL DEFAULT 0,
next_attempt_at timestamptz NOT NULL DEFAULT now(),
lease_token uuid,
lease_until timestamptz,
created_at timestamptz NOT NULL DEFAULT now(),
published_at timestamptz,
last_error text,
-- 同一次订单变化只能产生一条同类型事件。
UNIQUE (order_id, event_type, aggregate_version)
);
CREATE INDEX outbox_pending_idx
ON outbox_demo.outbox(next_attempt_at, created_at)
WHERE state = 'PENDING';
CREATE INDEX outbox_lease_idx
ON outbox_demo.outbox(lease_until)
WHERE state = 'SENDING';
INSERT INTO outbox_demo.orders
(order_id, sku, quantity, status)
VALUES (1001, 'SKU-1', 3, 'DRAFT');
BEGIN;
-- 只有实际完成状态转换,才生成事件;重复确认不再次生成。
WITH changed AS (
UPDATE outbox_demo.orders
SET status = 'CONFIRMED', version = version + 1
WHERE order_id = 1001 AND status = 'DRAFT'
RETURNING order_id, sku, quantity, version
)
INSERT INTO outbox_demo.outbox
(order_id, event_type, aggregate_version, payload)
SELECT order_id, 'OrderConfirmed', version,
jsonb_build_object(
'orderId', order_id, 'sku', sku, 'quantity', quantity
)
FROM changed;
COMMIT;
-- 同时检查业务状态和事件记录,不能只看订单写入成功。
SELECT o.status AS order_status,
count(e.event_id) AS event_count,
min(e.state) AS event_state
FROM outbox_demo.orders o
LEFT JOIN outbox_demo.outbox e ON e.order_id = o.order_id
WHERE o.order_id = 1001
GROUP BY o.status;预期结果,省略建表与事务命令提示:
order_status | event_count | event_state
--------------+-------------+------------
CONFIRMED | 1 | PENDING只重放上述 BEGIN 到 COMMIT 的业务事务,事件数仍为 1。若事件插入失败,订单更新也必须回滚,应用不能吞掉异常后返回成功。事件保存的是当时的业务快照;后台重发直接使用原记录,不能重新读取最新订单并拼出另一份载荷。
event_id 标识同一事实,重试时不变;aggregate_version 表示订单变化版本;schema_version 表示载荷契约版本。后两者不是重试次数,也不应随后台发布次数增加。
后台认领与发布确认
发布器先用短事务认领一条到期记录,再释放数据库锁并执行网络请求。PostgreSQL 的 FOR UPDATE SKIP LOCKED 适合多个工作者读取队列式表,但跳过锁并不保证同一订单的所有事件严格有序。([PostgreSQL][3])
认领时写入租期和随机令牌。租期让崩溃后的任务能够回收;令牌让旧工作者不能覆盖新工作者的处理状态。以下是片段示例,用于嵌入已有后台任务,不包含连接建立和调度入口。
调用前准备 Python 3.11、Psycopg 3 与 Pika:pg 是启用自动提交、使用 dict_row 行工厂且没有外层事务的数据库连接;channel 是已调用 confirm_delivery() 的 Pika BlockingChannel;inventory.reserve 是已创建的持久队列。Psycopg 的事务上下文在正常退出时提交,异常退出时回滚。([Psycopg][4])
import json
import random
import pika
def relay_once(pg, channel) -> str:
# 认领与发送分开,避免等待Broker时一直持有数据库锁。
with pg.transaction():
task = pg.execute("""
WITH candidate AS (
SELECT event_id
FROM outbox_demo.outbox
WHERE (state = 'PENDING'
AND next_attempt_at <= clock_timestamp())
OR (state = 'SENDING'
AND lease_until <= clock_timestamp())
ORDER BY created_at, event_id
LIMIT 1
FOR UPDATE SKIP LOCKED
)
UPDATE outbox_demo.outbox AS e
SET state = 'SENDING',
attempts = e.attempts + 1,
lease_token = gen_random_uuid(),
lease_until = clock_timestamp() + interval '30 seconds'
FROM candidate c
WHERE e.event_id = c.event_id
RETURNING e.*
""").fetchone()
if task is None:
return "IDLE"
envelope = {
"eventId": str(task["event_id"]),
"type": task["event_type"],
"schemaVersion": task["schema_version"],
"aggregateVersion": task["aggregate_version"],
"data": task["payload"],
}
try:
# 确认模式下等待Broker结果;mandatory用于发现无队列可路由。
channel.basic_publish(
exchange="",
routing_key="inventory.reserve",
body=json.dumps(envelope, ensure_ascii=False).encode("utf-8"),
properties=pika.BasicProperties(
message_id=str(task["event_id"]),
content_type="application/json",
delivery_mode=2,
),
mandatory=True,
)
except (pika.exceptions.UnroutableError,
pika.exceptions.NackError) as exc:
# 路由配置错误暂停修复;明确否认采用带抖动的退避。
state = ("PAUSED" if isinstance(exc, pika.exceptions.UnroutableError)
else "PENDING")
delay = random.uniform(0, min(60, 2 ** min(task["attempts"], 6)))
with pg.transaction():
changed = pg.execute("""
UPDATE outbox_demo.outbox
SET state = %s, last_error = %s,
next_attempt_at = clock_timestamp()
+ %s * interval '1 second',
lease_token = NULL, lease_until = NULL
WHERE event_id = %s AND state = 'SENDING'
AND lease_token = %s
""", (state, type(exc).__name__, delay,
task["event_id"], task["lease_token"])).rowcount
return state if changed == 1 else "LEASE_LOST"
# 未捕获的断连或数据库异常交给调度器;任务保留,不能假装成功。
with pg.transaction():
changed = pg.execute("""
UPDATE outbox_demo.outbox
SET state = 'SENT', published_at = clock_timestamp(),
last_error = NULL, lease_token = NULL, lease_until = NULL
WHERE event_id = %s AND state = 'SENDING'
AND lease_token = %s
""", (task["event_id"], task["lease_token"])).rowcount
return "SENT" if changed == 1 else "LEASE_LOST"预期结果:在前述数据库状态和连接前提下,无其他工作者竞争时,成功调用一次返回 SENT,事件记录变为 SENT;再次调用返回 IDLE。代码本身不打印日志。LEASE_LOST 表示本工作者没有成功更新当前任务,不能用它断言消息未进入 Broker。
PAUSED 记录需要修复队列或路由后再恢复为 PENDING,同时保留原 event_id 与载荷。仅重启发布器不会解除暂停,也不应通过删除旧记录、创建新事件的方式绕过故障。
持久消息、持久队列、Publisher Confirm 和路由检查要配合使用。发布确认不等于库存消费完成;无队列可路由的消息也可能收到 Broker 的确认,因此不能省略 mandatory 对应的退回处理。Pika 的确认模式会把相关退回或否认表现为异常。([RabbitMQ][5])
后台循环遇到连接异常应记录错误、退避重连并恢复轮询;空闲时也应处理连接心跳。示例的 30 秒租期是演示配置,需要结合发送预算调整。即使使用令牌,旧工作者仍可能发出消息;令牌保护的是数据库更新,不是全链路去重。([Pika][6])
故障恢复与安全清理
最关键的窗口是:Broker 已接收,发布器却在写回 SENT 前退出,或者确认在网络中丢失。租期到期后重新发布必须沿用原 event_id;允许重复,才能避免把不确定状态当作成功而漏发。消费者需要自行幂等。([RabbitMQ][7])
先在测试环境做两项验证:
- 将主示例业务事务末尾的
COMMIT改为ROLLBACK,在新测试库执行;订单应保持DRAFT,事件数应为 0。 - 在发布调用正常返回后、写回
SENT前终止工作者,租期到期后恢复;同一事件可能再次到达队列,但 Outbox 不应创建新的事件 ID。
清理以 published_at 为依据,而不是创建时间。以下示例分批删除已发布超过 7 天的记录;7 天只是实验保留期,应按审计、排障与回放要求调整。PENDING、SENDING 和 PAUSED 都不能被年龄清理误删。
-- 只清理已确认发布的历史记录,限制单批事务大小。
WITH expired AS (
SELECT event_id
FROM outbox_demo.outbox
WHERE state = 'SENT'
AND published_at < now() - interval '7 days'
ORDER BY published_at, event_id
LIMIT 500
FOR UPDATE SKIP LOCKED
), removed AS (
-- 删除本批已锁定的记录,不扫描其他未发布状态。
DELETE FROM outbox_demo.outbox e
USING expired x
WHERE e.event_id = x.event_id
RETURNING e.event_id
)
SELECT count(*) AS deleted_rows FROM removed;预期结果:本次新建的事件尚未超过保留期。
deleted_rows
--------------
0上线后至少监控待发数量、最老待发年龄、失败次数和暂停记录,并为持续失败配置告警。需要订单内严格顺序时,还要按订单串行发布或校验聚合版本;不能把“最终能够重发”误当成“天然有序且只处理一次”。