PostgreSQL Outbox:双写一致性与消费幂等

用 SQL 拆解事务内事件记录、可靠投递与消费去重,比较轮询和 CDC,并说明乱序、外部副作用及积压恢复的边界。

订单已经写进数据库,通知却没有发出去。这个故障通常不会在正常演示里出现:接口返回成功,表里也有订单,只有仓库、搜索索引或通知系统迟迟没有变化。给发送动作加三次重试并不能消除问题,因为进程可以在提交事务后、进入重试循环前退出。

Transactional Outbox 的价值就在这里:先把“要通知谁、通知什么”变成数据库里可以恢复的事实,再由独立进程投递。代价也很明确,系统需要接受延迟、重复,以及一套真正能够重放的消费逻辑。本文用 PostgreSQL 17 的语法设计一个订单创建链路,讨论它适合解决什么问题,以及哪些承诺不能轻易写进架构文档。

先定义成功,而不是先选消息中间件

假设订单服务和库存服务分别拥有自己的数据库。订单接口的成功条件是:订单记录已提交,同时存在一条对应的 OrderCreated 事件。库存是否已经完成预占,是另一个状态,需要异步回写,不能在返回值里冒充完成。这里没有跨库事务,也不承诺库存一定够用。库存不足仍然需要订单取消或补偿流程。

我们的目标有三个:已提交订单的事件不会因为应用进程退出而消失;同一个事件即使多次到达,消费端的本地业务变更只发生一次;消息系统短暂不可用时,订单请求可以继续提交,但积压必须可观测且有容量上限。这些目标依赖数据库正常持久化、任务最终恢复、积压没有被错误删除等前提,不等于任意灾难下绝对不丢数据。

最容易误判的是把“发出了请求”当作“对方可靠保存”。发送函数返回前超时,可能是消息根本没到,也可能是消息已经保存、确认包却丢了。重试时如果生成新事件 ID,消费者会把同一事实当成两个事件。重试必须沿用原始事件 ID;请求幂等键、订单 ID、事件 ID 则应分开设计,因为一个订单可能产生多次不同的业务事件。

三种做法的实际取舍

数据库提交后直接调用消息服务,代码最少,适合可丢失的遥测数据,却不满足订单通知目标。反过来先发消息再提交数据库,也只是把失败窗口搬到另一边:下游可能处理一张根本不存在的订单。AWS 的 Outbox 模式说明讨论了这种双写不一致,以及同一事务记录事件、重复消费和顺序方面的限制。

轮询 Outbox 是本文采用的方案。应用把订单和事件写在同一数据库事务里,投递进程扫描待发事件。它容易与现有部署结合,也便于人工定位一条卡住的记录;代价是额外查询、状态更新、清理和数据库负载。对于几百毫秒到数秒延迟可以接受、团队暂时没有维护 CDC 经验的业务,这是一个务实起点,具体吞吐仍要通过测试决定。

另一种方案是从事务日志捕获 Outbox 新增记录。Debezium 的 Outbox Event Router提供这种路径,把业务定义的事件表转换为消息,而不是直接把所有业务表变更暴露出去。它减少轮询式领取和回写,却引入连接器、复制位置、日志保留、消息路由与恢复的运维工作。如果组织已经可靠维护这套基础设施,CDC 往往更合适;为了一个小功能临时搭建整套平台,可能比要解决的问题更复杂。

把订单与事件放进同一事务

下面的表是可审查的最小模型,不是完整电商数据库。金额以最小货币单位保存,示例统一使用整数;身份校验、币种、库存和支付不在这一段 SQL 的覆盖范围内。UUID 由调用方生成,避免依赖额外扩展。实际服务必须把 SQL 参数绑定,不能把请求内容拼成字符串。

CREATE TABLE orders (
    id uuid PRIMARY KEY,
    request_key text NOT NULL UNIQUE,
    total_minor bigint NOT NULL CHECK (total_minor >= 0),
    status text NOT NULL DEFAULT 'created',
    created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE outbox (
    event_id uuid PRIMARY KEY,
    aggregate_id uuid NOT NULL REFERENCES orders(id),
    event_type text NOT NULL,
    schema_version integer NOT NULL,
    payload jsonb NOT NULL,
    occurred_at timestamptz NOT NULL DEFAULT now(),
    published_at timestamptz
);

CREATE INDEX outbox_pending_idx
    ON outbox (occurred_at, event_id)
    WHERE published_at IS NULL;

订单和事件必须在同一个连接、同一个事务内提交。下面使用固定 UUID 只是为了让演示可复制;真实请求要生成自己的 ID。payload 保存消费所需的业务事实,不要求消费者再回调订单服务拼出创建时的状态。

BEGIN;

INSERT INTO orders (id, request_key, total_minor)
VALUES ('10000000-0000-0000-0000-000000000001',
        'demo-request-001', 19900);

INSERT INTO outbox
    (event_id, aggregate_id, event_type, schema_version, payload)
VALUES (
    '20000000-0000-0000-0000-000000000001',
    '10000000-0000-0000-0000-000000000001',
    'OrderCreated', 1,
    '{"orderId":"10000000-0000-0000-0000-000000000001",
      "totalMinor":19900}'::jsonb
);

COMMIT;

两条 INSERT 中任何一条失败,都必须回滚整个事务。接口层处理 request_key 冲突时,应读取已有订单并验证原请求内容是否相同,而不是忽略冲突后继续生成另一条事件。本文刻意没有用两个互不关联的 ON CONFLICT DO NOTHING 来缩短代码,那样很容易让“重试旧订单”和“新增新事件”脱离关系。

请求超时后,客户端可以用原来的 request_key 查询结果。这个键需要绑定认证用户或租户,防止不同用户的键发生混淆;还应保存请求摘要,拒绝用同一键提交不同金额。Outbox 解决的是事件记录和订单提交的原子性,接口重试的业务语义仍然需要应用负责。

投递进程:先接受重复,再收紧失败窗口

为便于解释,先采用一个低并发、每次领取一条记录的方案。投递进程开启事务,锁住一条待发记录,在收到消息代理的持久化确认后更新 published_at,最后提交事务。网络发送期间会持有数据库事务,这不是理想的高吞吐设计,但失败路径很直观。

BEGIN;

SELECT event_id, aggregate_id, event_type, schema_version, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY occurred_at, event_id
LIMIT 1
FOR UPDATE SKIP LOCKED;

-- 应用使用查询结果发送消息,并等待代理的可靠确认。
-- 只有确认成功,才执行以下参数化更新:
UPDATE outbox
SET published_at = now()
WHERE event_id = $1::uuid;

COMMIT;

这段不是能直接整段复制执行的 psql 脚本:中间的发送必须由应用实现,$1 是数据库驱动绑定的事件 ID。发送失败或超时就回滚,再按退避策略重试。不能把 UPDATE 放进 finally,也不能只要 HTTP 请求写入套接字就当作发送成功。确认的含义取决于消息代理的具体配置,必须核对持久化、复制和生产者确认机制。

PostgreSQL SELECT 文档说明,SKIP LOCKED 会跳过无法立即取得行锁的记录,适合队列式多消费者访问,但看到的不是普通查询意义上的一致视图。在这里它让多个投递者分摊工作,却没有提供全局顺序。较早事件被某个投递者锁住时,其他投递者可以先发送较晚事件。

关键故障窗仍然存在:消息代理已经确认,投递者却在数据库提交前退出。行锁会随事务结束释放,published_at 仍为空,下次会再次发送同一个事件。这正是消费端去重不可省略的原因。反过来先标记 published_at 再发送,会把可恢复的重复变成不可自动恢复的丢失,不能为了让监控数字好看而交换顺序。

网络波动时,持锁时间可能拖长,所以必须限制发送超时、数据库事务时间以及投递者并发数。不要一次锁住几千条再串行发送,那会放大锁持有时间和单次失败的重发范围。如果实际吞吐不够,可以改用短事务领取加租约:领取时记录过期时间和唯一令牌,确认时用令牌条件更新,过期后允许别人领取。租约会引入旧投递者恢复后的竞争,仍需消费者幂等;仅增加一个 processing 布尔值,进程崩溃后则可能永远卡住。

消费端去重必须与业务变更一起提交

不要先向 Redis 写“处理过”,再更新业务数据库。中间失败会让业务没有执行,消息却被永久跳过。同样,先提交业务变更再另写去重记录,也会在重试时重复执行。最容易审查的方式是把去重记录和业务更新放在消费服务自己的同一数据库事务里。

下面以统计已创建订单的消费端为例。它只累加订单数和金额,操作可交换,因此允许不同订单的事件乱序到达。示例只处理可信生产者的 OrderCreated v1,应用必须先验证类型、版本、字段和金额范围。不要把未知消息类型也插进去重表再静默丢弃。

CREATE TABLE processed_events (
    consumer_name text NOT NULL,
    event_id uuid NOT NULL,
    processed_at timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (consumer_name, event_id)
);

CREATE TABLE order_totals (
    bucket text PRIMARY KEY,
    order_count bigint NOT NULL DEFAULT 0,
    total_minor bigint NOT NULL DEFAULT 0
);

INSERT INTO order_totals (bucket) VALUES ('all');

处理一条事件时,在同一事务中执行下面的语句。$1 是稳定的事件 ID,$2 是已经验证的金额。示例只有一个消费逻辑,名称保持为 order-summary-v1;重构代码时随意改名,会让旧消息绕过去重。

BEGIN;

WITH accepted AS (
    INSERT INTO processed_events (consumer_name, event_id)
    VALUES ('order-summary-v1', $1::uuid)
    ON CONFLICT DO NOTHING
    RETURNING event_id
)
UPDATE order_totals
SET order_count = order_count + 1,
    total_minor = total_minor + $2::bigint
WHERE bucket = 'all'
  AND EXISTS (SELECT 1 FROM accepted);

COMMIT;
-- 数据库提交成功之后,才确认消息消费。

PostgreSQL INSERT 文档明确了 ON CONFLICT 和 RETURNING 的行为。这里借助唯一键竞争,只有真正插入去重记录的一次执行能更新汇总。消费后、确认消息前退出,会造成再次投递,但下一次不会再次累计。要注意,示例要求 all 这条汇总记录预先存在;生产实现应核验这个前提,不能在目标行意外缺失时照样提交去重记录。

这个设计也有性能边界:所有订单更新同一行,行锁会串行化统计。它适合展示正确性,不适合直接照搬成高吞吐实时分析系统。可以按日期、租户或哈希分桶,再异步汇总,但要先定义查询的一致性要求。架构设计应该明确示例为了讲清什么而简化了什么,不应把一段演示 SQL 宣称为通用生产方案。

外部副作用仍然需要另一层协议

如果消费动作是发邮件、调用第三方接口或扣款,本地事务不能把对方系统也包含进来。消费端可以再建立自己的 Outbox,也可以使用对方提供的幂等键;没有这些能力时,只能根据业务风险选择接受重复、人工核对或补偿。尤其不能用本地 processed_events 表声称已经实现跨系统的“恰好一次”。

另外,事件 ID 去重只能拦住同一事件的重复投递。如果生产者为同一业务事实错误生成两个 ID,消费端仍会执行两次。对于不能重复的业务动作,还要在领域层建立唯一约束,例如订单预占记录以订单 ID 和预占类型形成唯一键。传输去重与业务唯一性分别防守不同的错误,不应互相替代。

顺序、积压与恢复,要在上线前写成数字

假设一个订单还会产生 Paid 和 Cancelled 事件,消费者就不能只靠去重。可以给聚合维护单调递增版本,并在更新订单时一起分配版本;消费者记录最后应用的版本,发现缺口时暂停该订单、重试或回源修复。按订单 ID 路由到同一分区有助于保持队列顺序,但并不能自动修复多投递者在进入队列前已经造成的乱序。

本文的最小投递实现没有保证同一订单事件顺序,因此它的直接适用范围是可交换操作、独立通知或消费端能处理乱序的场景。不要在只增加 ORDER BY 后就把它用作严格按序的状态机日志。需要严格顺序时,应增加每个聚合的串行投递机制,或选用有明确顺序语义的 CDC 路径,并验证恢复和重放时的行为。

容量可以先用模型算,再用压测校准。例如假设每秒产生 200 条事件,每条业务载荷约 2 KB,消息系统停机一小时会积压 72 万条,仅载荷约 1.44 GB。这个数字未包含行头、索引、WAL、复制和膨胀,所以不能直接拿来配置磁盘。若恢复后持续投递能力为每秒 500 条,而新事件仍以每秒 200 条进入,净消化速度为每秒 300 条,理论上约 40 分钟清空积压。这些是明确假设下的算术推演,不是本文实测吞吐。

监控应至少覆盖最老待发事件年龄、待发数量、发送失败率、重复消费次数、数据库事务时长和存储增长。只看平均延迟会掩盖一条永远重试的坏消息。毒性事件需要保留原始 ID、失败原因和可审计的人工处理路径;将它标为成功会制造业务漏处理,直接删除则会破坏恢复证据。

已发送记录与去重记录的保留期要联动设计。假如队列允许回放三十天,而去重记录七天就删除,旧事件重放可能再次执行。保留期还应覆盖备份恢复、人工重试和跨区域恢复窗口。清理应分批进行并观察数据库维护压力,不要一次删除整个月数据后才发现业务查询受影响。

如何验证这套设计,而不是只验证正常路径

本文核对了 PostgreSQL 17 语法和官方模式说明,但当前编写环境没有 PostgreSQL 服务,也没有连接消息代理。因此,文中的 SQL 与网络投递代码尚未完成真实 PostgreSQL 集成测试;不能把下面的预期结果当成性能或可靠性验收报告。可以先在隔离测试环境创建上述表,再按以下顺序注入故障。

第一,在第二条 INSERT 前主动报错并回滚,确认订单和事件都不存在。第二,提交订单后停止投递进程,确认事件仍保留且最老待发时间增长。第三,让消息代理确认后、数据库标记提交前终止投递进程,确认同一 event_id 再次出现,而消费汇总只增加一次。第四,在消费事务提交后、确认消息前终止消费者,确认重投不会再次累计。

第五,并发发送两份相同 ID 的消息,验证唯一约束竞争下只有一次业务变更。第六,把消息版本改成不支持的值,验证它进入可诊断的失败路径,而不是被当成成功消费。第七,停止消息代理并持续写入订单,观察连接数、事务时长、积压和磁盘趋势,确认故障没有通过投递线程拖垮在线接口。

测试还应故意删除示例中的汇总目标行,确认实现会报警并回滚;故意修改同一请求键对应的金额,确认接口会拒绝而不是复用旧结果。正常路径验证代码能运行,故障路径验证系统到底承诺了什么。只有两者一起成立,才值得将延迟和恢复目标写进上线标准。

选型结论:把不可解释的双写,改成可检查的状态

对于有独立消息系统、允许异步完成、暂时不需要复杂 CDC 平台的服务,事务内写 Outbox、可靠确认后标记、消费端事务去重,是一条可逐步落地的路线。它让每一次未完成投递有迹可查,也把重复处理变成可以系统测试的问题。

如果业务根本不需要跨服务异步,直接在同一个数据库事务里完成操作往往更简单。如果团队已经维护成熟 CDC,或者轮询数据库的成本超过可以接受的范围,就应比较日志捕获方案。若业务要求跨多个外部系统立即、严格地全部成功,则需要重新讨论业务状态、补偿协议和用户可见承诺,不能指望一张 Outbox 表替代这些决定。

这套模式最终交付的应是一组明确边界:什么随事务一起成功,什么允许稍后完成,哪里可能重复,哪里需要顺序,以及失败后由谁依据什么记录恢复。代码和监控如果不能回答这些问题,架构图里再多一个消息队列也不会让系统更可靠。

相关文章

评论

登录后即可参与讨论

暂无评论。