事务型 Outbox:业务写入同事务落副作用

直接回答: 先写库再调邮件 API、webhook 或 ERP,是双重写入:任何一步都可能单独成功。把 outbox 行放进和业务变更同一事务。独立中继读已提交的行,至少一次投递;接收端必须幂等。

事务型 outbox 示意图:请求处理在同一数据库事务里写业务行和 outbox 行;提交后,中继轮询或跟踪 outbox,至少一次投递邮件、webhook 或 ERP;接收端做幂等闸门。底部提示:勿在无持久 outbox 时提交业务写入后直接调网络。
图 1 业务写入与 outbox 行在同一事务;中继在提交后负责投递。

1.0 双重写入问题

一个处理函数先保存订单再发确认邮件,就是在写两个系统:数据库和邮件服务商。把单据推到 ERP,或向合作方发 webhook,形状一样。

库提交成功、网络调用失败,业务状态已成立,却没人收到通知。先通知再提交失败,对端已经按根本不存在的事实行动了。跨数据库和邮件 API 做两阶段提交很少见,通常也不值得。这就是事务型 outbox 模式要对付的双重写入问题(见文末 Chris Richardson 的模式说明和 AWS Prescriptive Guidance)。

2.0 同一事务里放什么

写入是否与业务变更同一事务?
业务行(订单、付款、工单……)是
Outbox 行(type、message id、payload、status)是
邮件 / webhook / ERP 的 HTTP 调用否 — 提交之后,由中继执行
把 outbox 行标成 published / 删掉中继成功之后(或由日志跟踪清理)

Outbox 行不是线上已经发生过什么的日志。它是做副作用的持久意图,只有业务写入提交时才记下来。

3.0 中继:轮询或跟踪日志

单独进程(或同一服务里的 worker)把已提交的 outbox 行推到外部世界。

做法怎么找活常见取舍
轮询发布按 id 或 created_at 排序 SELECT 待处理行简单;普通 SQL 就能用;延迟和负载随轮询间隔和表大小涨
事务日志跟踪从库日志读插入(WAL、binlog、streams)延迟更低;依赖库特定工具;仍是至少一次

microservices.io 把两者都写成 outbox 的配套。流量或延迟还没逼你之前,先用轮询;要上日志跟踪再投入。无论哪种,发布都按 至少一次 处理:卡在「发送成功」和「行已标完成」之间的崩溃会再发一遍。

4.0 我们保持稳定的行结构

列要够运维回答「卡在哪了」,不必去读应用内存:

  • id — 单调或 ULID;排序和中继检查点用。
  • message_id / 幂等键 — 对这次逻辑副作用稳定;接收端靠它去重。
  • type — 哪个中继处理器跑(email.order_paid、erp.order_push……)。
  • aggregate_key — 订单 id、线索 id、设备 id;排序和支持查询用。
  • payload — 处理器需要的带版本 JSON;别往里塞密钥。
  • status — pending → publishing(可选租约)→ published / failed_terminal。
  • attempts、next_attempt_at、last_error — 退避和告警用。
  • created_at — 可选再加 published_at。

用原子更新认领一行(pending → publishing,带持有者和租约过期),避免两个中继 worker 发出同一封邮件。成功则标 published(或删除,若你更想保持小表、靠备份做审计)。可重试失败则增加 attempts 并设 next_attempt_at。超过配置上限后进 failed_terminal 并告警给人看。

5.0 顺序与重复

对同一聚合,按 outbox id(或序号)分配顺序发布,避免合作方先看到「已发货」再看到「已创建」。跨聚合可以并行 worker。

重复是预期内的。把本笔记和 Webhook 幂等与重试:去重键、保留期和副作用怎么放 一起看:outbox 保证业务写入成功后副作用会被尝试;接收端的去重存储保证只被应用一次。推 ERP 在对端也要同样纪律 — 单据上稳定的业务键,见 和 ERP 对接订单:异步审核、幂等推送与同步日志。

6.0 别放在请求路径上的事

  • 不要开着 DB 事务去调第三方 HTTP,再提交。超时和锁会让失败模式很难推理。
  • 若崩溃时丢掉该副作用不可接受,不要在没有持久 outbox(或等价物)的情况下 fire-and-forget 起 goroutine 或往队列发。
  • 不要把「邮件 API 回了 HTTP 200」当成「客户已通知」的权威记录,除非你也持久化了这个结果。更稳妥:outbox 已 published,并把提供方 message id 记在行上。

7.0 可观测性

  • 指标:pending 年龄(p50/p95)、发布成功/失败率、终态失败、中继延迟。
  • 告警:最老的 pending/publishing 超过阈值;发布后终态失败尖峰。
  • 支持:按 aggregate_key 查,在业务记录旁展示 outbox 状态。

如果你在接支付、ERP 或设备云的副作用,见 Web、云端与设备管理,也可以直接聊聊项目。

参考资料

常见问题

Outbox 和消息队列是一回事吗?

Outbox 是业务库里的一张表(或文档字段),和业务写入同库,要么一起提交要么一起回滚。队列或中间件排在中继之后。有了它,发布不会在业务写入失败时成功,反过来也一样。

接收端还要不要做幂等?

还要。中继可能投递不止一次:发送已成功、标记行完成之前进程崩溃就会再发。消费方必须按至少一次来接,例如用我们 webhook 笔记里的幂等键和保留窗口。

能在数据库事务里直接调邮件 API 吗?

别这么干。事务开着等网络调用,锁会拖得更久;一旦超时,邮件到底发出没有也说不清。先写 outbox 行、提交,再让中继去做网络调用。

轮询 outbox 表看起来很浪费,有没有别的办法?

轮询在任何 SQL 库上都能用,中等流量通常够用。库支持的话,跟踪事务日志(例如从 WAL 或 binlog 读 outbox 插入)能降低延迟和负载。两种方式仍然是至少一次投递。

Outbox 的 payload 里该放什么?

够中继直接干活、不必再推一遍意图即可:类型、稳定的幂等或消息 id、业务键,以及下游调用需要的字段。优先用带版本的 schema,别把整个聚合不透明地 dump 进去,这样代码改了之后旧行还能读。