事务型 Outbox:业务写入同事务落副作用
直接回答: 先写库再调邮件 API、webhook 或 ERP,是双重写入:任何一步都可能单独成功。把 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、云端与设备管理,也可以直接聊聊项目。
参考资料
- Chris Richardson, Pattern: Transactional outbox: https://microservices.io/patterns/data/transactional-outbox.html
- Chris Richardson, Pattern: Polling publisher: https://microservices.io/patterns/data/polling-publisher.html
- Chris Richardson, Pattern: Transaction log tailing: https://microservices.io/patterns/data/transaction-log-tailing.html
- AWS Prescriptive Guidance, Transactional outbox pattern: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
常见问题
Outbox 和消息队列是一回事吗?
Outbox 是业务库里的一张表(或文档字段),和业务写入同库,要么一起提交要么一起回滚。队列或中间件排在中继之后。有了它,发布不会在业务写入失败时成功,反过来也一样。
接收端还要不要做幂等?
还要。中继可能投递不止一次:发送已成功、标记行完成之前进程崩溃就会再发。消费方必须按至少一次来接,例如用我们 webhook 笔记里的幂等键和保留窗口。
能在数据库事务里直接调邮件 API 吗?
别这么干。事务开着等网络调用,锁会拖得更久;一旦超时,邮件到底发出没有也说不清。先写 outbox 行、提交,再让中继去做网络调用。
轮询 outbox 表看起来很浪费,有没有别的办法?
轮询在任何 SQL 库上都能用,中等流量通常够用。库支持的话,跟踪事务日志(例如从 WAL 或 binlog 读 outbox 插入)能降低延迟和负载。两种方式仍然是至少一次投递。
Outbox 的 payload 里该放什么?
够中继直接干活、不必再推一遍意图即可:类型、稳定的幂等或消息 id、业务键,以及下游调用需要的字段。优先用带版本的 schema,别把整个聚合不透明地 dump 进去,这样代码改了之后旧行还能读。