架构与系统设计 / 系统课时

接入 Outbox 保证事件发布

接入 Outbox 保证事件发布

订单事务已经提交,进程却在发消息前退出,库存服务就可能永远不知道这笔订单。本篇把订单变化与待发事件放进同一个数据库事务,再补上后台认领、发布确认和清理规则,让发送失败可以恢复,而不是靠请求线程碰运气。

学习目标

  • 实现订单状态与 Outbox 事件的原子提交。
  • 区分发布确认与消费确认,处理发送结果不确定的窗口。
  • 设计可恢复的后台发布和只清理已确认事件的规则。

同库提交的是发布责任

Outbox 是订单数据库中的待发事件表。业务事务只负责同时保存订单变化和事件;独立发布器随后读取已提交记录并发送。这样解决的是数据库与消息系统之间的双写缺口,而不是把两者变成一个跨系统事务。([AWS 文档][1])

这里的保证有前提:数据库提交可靠、未发送记录不被删除、发布器持续运行,故障与暂停任务最终得到修复。Outbox 保存了必须继续发布的责任,不承诺消费者马上成功,也不消除重复消息。([AWS 文档][1])

订单事务、后台发布与确认之间的时序及重复窗口

写入订单与不可变事件

下面采用 PostgreSQL 16,在新测试库的同一会话执行,账号需要建表权限。示例限定为单商品订单,1001 是固定测试订单号;事件 UUID 由数据库生成。PostgreSQL 16 内置 gen_random_uuid(),不需要为此另装扩展。([PostgreSQL][2])

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

预期结果,省略建表与事务命令提示:

text
 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])

python
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])

先在测试环境做两项验证:

  1. 将主示例业务事务末尾的 COMMIT 改为 ROLLBACK,在新测试库执行;订单应保持 DRAFT,事件数应为 0。
  2. 在发布调用正常返回后、写回 SENT 前终止工作者,租期到期后恢复;同一事件可能再次到达队列,但 Outbox 不应创建新的事件 ID。

清理以 published_at 为依据,而不是创建时间。以下示例分批删除已发布超过 7 天的记录;7 天只是实验保留期,应按审计、排障与回放要求调整。PENDING、SENDING 和 PAUSED 都不能被年龄清理误删。

sql
-- 只清理已确认发布的历史记录,限制单批事务大小。
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;

预期结果:本次新建的事件尚未超过保留期。

text
 deleted_rows
--------------
            0

上线后至少监控待发数量、最老待发年龄、失败次数和暂停记录,并为持续失败配置告警。需要订单内严格顺序时,还要按订单串行发布或校验聚合版本;不能把“最终能够重发”误当成“天然有序且只处理一次”。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入 Outbox 保证事件发布

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

登录哪都通