订单提交了,消息却没发出:用 Python SQLite 拆解事务型 Outbox
验证范围:本文示例已在 Python 3.12.14、SQLite 3.53.1 环境实际运行,退出码为 0。实验只有标准库、两个独立 SQLite 文件和合成数据,验证的是确定性异常下的本地事务状态,不代表生产系统已经实现分布式 exactly-once。
一、一个本地事务,包不住两件事
假设创建一笔订单后,需要通知另一个组件增加积分。最直接的顺序是:提交订单,再发送消息。问题出现在两步之间:订单已经提交,进程却在发送前中断。数据库里有订单,消费端却没有收到通知。
把顺序反过来也不行。先发消息,再提交订单,可能出现消费端已经加分、订单事务却回滚的情况。两个动作相邻,不意味着它们构成原子操作。普通数据库事务不能自动把另一个数据库、消息系统或 HTTP 服务纳入同一次提交。
事务型 Outbox 的目标更窄:创建订单时,在同一个数据库事务里同时保存“需要投递的事件”。投递器随后读取事件,成功后再标记完成。它把容易消失的发送意图变成可以恢复读取的记录,而不是让远端只执行一次。
二、先画清三段事务边界
生产端文件包含 orders 与 outbox;消费端文件包含 credits 与 inbox。两个文件事务独立,没有使用 ATTACH。
| 阶段 | 同一本地事务内的写入 | 不在这个事务里的动作 |
|---|---|---|
| 创建订单 | orders 与 outbox 一起提交 | 调用消费端 |
| 消费事件 | inbox 与 credits 一起提交 | 修改生产端 outbox |
| 确认完成 | 把 outbox.sent 改为 1 | 之前已经发生的消费 |
订单与待发事件要么同时存在,要么同时不存在;采用 inbox 时,去重记录与业务效果也要一起提交。中间的投递仍可能重复。
独立测试场景使用 order-1、event-1 和整数积分 100。真实系统需要给不同事件分配稳定、唯一的标识,同一事件重试时复用编号,不能每次重新生成。
三、完整代码:在确定的位置主动失败
将下列代码保存为 outbox_demo_20261110.py,可在保存目录运行:
python outbox_demo_20261110.py
只需 Python 标准库,SQLite 需支持 ON CONFLICT DO NOTHING。不要使用 python -O 验收,因为它会禁用 assert。临时目录只存合成数据,每个场景独立建库;连接关闭后自动清理。
"""Deterministic local Outbox demo; standard library, synthetic data only."""
from contextlib import contextmanager
from pathlib import Path
import sqlite3
from tempfile import TemporaryDirectory
class InjectedFailure(RuntimeError):
pass
@contextmanager
def database(path):
db = sqlite3.connect(path, isolation_level=None)
try:
yield db
finally:
db.close()
@contextmanager
def transaction(db):
db.execute("BEGIN IMMEDIATE")
try:
yield
except BaseException:
db.execute("ROLLBACK")
raise
else:
db.execute("COMMIT")
def setup(root, name):
producer = root / (name + "-p.db")
consumer = root / (name + "-c.db")
with database(producer) as db:
db.executescript("""
CREATE TABLE orders(id TEXT PRIMARY KEY, amount INTEGER NOT NULL);
CREATE TABLE outbox(
event_id TEXT PRIMARY KEY, order_id TEXT NOT NULL,
amount INTEGER NOT NULL, sent INTEGER NOT NULL DEFAULT 0
);
""")
with database(consumer) as db:
db.executescript("""
CREATE TABLE inbox(event_id TEXT PRIMARY KEY);
CREATE TABLE credits(event_id TEXT NOT NULL, amount INTEGER NOT NULL);
""")
return producer, consumer
def create_order(path, use_outbox=True, fail=False):
with database(path) as db, transaction(db):
db.execute("INSERT INTO orders VALUES (?, ?)", ("order-1", 100))
if fail:
raise InjectedFailure("before outbox insert")
if use_outbox:
db.execute("INSERT INTO outbox(event_id, order_id, amount) "
"VALUES (?, ?, ?)", ("event-1", "order-1", 100))
def consume(path, event, dedupe, fail=False):
event_id, order_id, amount = event
with database(path) as db, transaction(db):
if dedupe:
changed = db.execute(
"INSERT INTO inbox VALUES (?) "
"ON CONFLICT(event_id) DO NOTHING", (event_id,)
).rowcount
if changed == 0:
return False
db.execute("INSERT INTO credits VALUES (?, ?)", (event_id, amount))
if fail:
raise InjectedFailure("before consumer commit")
return True
def relay(producer, consumer, dedupe, fail_after_consume=False):
with database(producer) as db:
event = db.execute("SELECT event_id, order_id, amount FROM outbox "
"WHERE sent = 0 ORDER BY event_id LIMIT 1").fetchone()
if event is None:
return False
# A direct call models delivery; there is no broker or shared transaction.
consume(consumer, event, dedupe)
if fail_after_consume:
raise InjectedFailure("consumer committed; outbox still pending")
with database(producer) as db, transaction(db):
db.execute("UPDATE outbox SET sent = 1 WHERE event_id = ?", (event[0],))
return True
def snapshot(producer, consumer):
with database(producer) as db:
orders = db.execute("SELECT count(*) FROM orders").fetchone()[0]
pending = db.execute("SELECT count(*) FROM outbox WHERE sent = 0").fetchone()[0]
with database(consumer) as db:
credits, total = db.execute(
"SELECT count(*), coalesce(sum(amount), 0) FROM credits"
).fetchone()
inbox = db.execute("SELECT count(*) FROM inbox").fetchone()[0]
return orders, pending, credits, total, inbox
def expect_failure(action):
try:
action()
except InjectedFailure:
return
raise AssertionError("injected failure did not occur")
def check(label, producer, consumer, expected):
actual = snapshot(producer, consumer)
assert actual == expected, (label, actual, expected)
print(f"{label}: orders={actual[0]} pending={actual[1]} "
f"credits={actual[2]} total={actual[3]} inbox={actual[4]}")
def main():
with TemporaryDirectory(prefix="outbox-demo-") as folder:
root = Path(folder)
p, c = setup(root, "naive")
def naive_send():
create_order(p, use_outbox=False)
raise InjectedFailure("committed order; send never called")
expect_failure(naive_send)
check("naive.loss", p, c, (1, 0, 0, 0, 0))
p, c = setup(root, "atomic")
expect_failure(lambda: create_order(p, fail=True))
check("producer.rollback", p, c, (0, 0, 0, 0, 0))
create_order(p)
check("producer.commit", p, c, (1, 1, 0, 0, 0))
delivered = relay(p, c, dedupe=True)
assert delivered
check("producer.recovered", p, c, (1, 0, 1, 100, 1))
for dedupe, name in [(False, "plain"), (True, "inbox")]:
p, c = setup(root, name)
create_order(p)
expect_failure(lambda: relay(p, c, dedupe, fail_after_consume=True))
check(name + ".gap", p, c, (1, 1, 1, 100, int(dedupe)))
delivered = relay(p, c, dedupe)
assert delivered
n = 1 if dedupe else 2
check(name + ".retry", p, c, (1, 0, n, 100 * n, int(dedupe)))
delivered = relay(p, c, dedupe)
assert delivered is False
p, c = setup(root, "consumer-rollback")
create_order(p)
expect_failure(lambda: consume(c, ("event-1", "order-1", 100), True, fail=True))
check("consumer.rollback", p, c, (1, 1, 0, 0, 0))
delivered = relay(p, c, dedupe=True)
assert delivered
check("consumer.recovered", p, c, (1, 0, 1, 100, 1))
print("ALL CHECKS PASSED")
if __name__ == "__main__":
main()
isolation_level=None 关闭隐式事务管理,transaction 显式执行 BEGIN IMMEDIATE、COMMIT 和 ROLLBACK。建表在业务事务之外执行。每次操作结束关闭连接,后续重新打开文件读取,不靠同一连接中的未提交状态得出结论。
故障为主动抛出的异常,不是随机 sleep,更不是真正断电。它可以确定提交前后的窗口,不能据此声称验证了操作系统崩溃、磁盘损坏或持久化配置。
四、实际运行输出
本次通过 Python 标准输入执行上述完整代码,未依赖预先保存的脚本文件。执行包装层先打印 Python 和 SQLite 版本,脚本随后输出如下内容,进程退出码为 0。读者保存为文件后执行,正文脚本本身不打印前两行版本信息。
Python 3.12.14
SQLite 3.53.1
naive.loss: orders=1 pending=0 credits=0 total=0 inbox=0
producer.rollback: orders=0 pending=0 credits=0 total=0 inbox=0
producer.commit: orders=1 pending=1 credits=0 total=0 inbox=0
producer.recovered: orders=1 pending=0 credits=1 total=100 inbox=1
plain.gap: orders=1 pending=1 credits=1 total=100 inbox=0
plain.retry: orders=1 pending=0 credits=2 total=200 inbox=0
inbox.gap: orders=1 pending=1 credits=1 total=100 inbox=1
inbox.retry: orders=1 pending=0 credits=1 total=100 inbox=1
consumer.rollback: orders=1 pending=1 credits=0 total=0 inbox=0
consumer.recovered: orders=1 pending=0 credits=1 total=100 inbox=1
ALL CHECKS PASSED
orders 是订单数,pending 是待发事件数,credits 是记账行数,total 是积分合计,inbox 是去重记录数。十个状态快照、故障确实发生及无待发事件的断言均通过;这不是吞吐量或可靠性压测。
五、沿着故障窗口读结果
naive.loss 中订单存在、记账为零。没有 outbox,也没有扫描 orders 重建事件的补偿机制,因此给定流程没有可以继续投递的发送意图。
producer.rollback 在订单插入后、outbox 插入前失败,订单也回滚。producer.commit 返回后,订单和待发事件均能重新读取,后续 relay 完成一次记账。Outbox 修复的是这个窗口,而不是让所有异常自动成功。
plain.gap 中消费端已经提交 100 积分,生产端尚未更新 sent。再次读取待发事件,同一个 event-1 又被消费,没有去重就写入两行、合计 200。若先标记 sent 再调用消费端,又会产生“标记完成但实际没消费”的丢失窗口。
inbox.retry 承认同一事件可能再次到达。消费端在自己的事务里插入 inbox,主键冲突就不再记账;首次插入才执行业务写入。重复投递仍可正常返回,使投递器标记完成。consume 返回 False 表示已去重,relay 返回 True 表示本次待发事件已处理,含义不同。
consumer.rollback 验证去重与业务写入必须原子。如果先独立提交 inbox,记账失败会使重试误判完成。示例在两项写入后、消费事务提交前失败,实测两项都回滚,随后重试才完成真正的记账。
六、这个小模型还没有解决什么
并发领取。 本例只有一个投递器。查询与更新不构成领取协议;多个工作进程可能读到同一记录。生产环境还需领取、租约、超时回收、条件更新。网络调用不宜放进长写事务。
重试与坏消息。 待发不等于最终必达。还要设计退避、重试次数、可再次尝试时间、错误分类、告警、失败队列和人工重放。本例只有再次调用 relay,没有后台调度,也没有真实 broker 确认协议。
保留期与事件身份。 inbox 保留期要覆盖重投与人工重放窗口;过早清理会使旧消息再次记账,永久保留则增加容量与索引负担。事件编号应绑定不可变载荷,生产中还要检查同编号不同内容的冲突;本例固定合成载荷没有实现此检查。
外部副作用。 inbox 仅覆盖当前数据库事务。若记账换成发邮件、扣款接口或另一个数据库,边界再次分裂,需要下游幂等键、进一步的 outbox、状态查询或业务补偿,不能用本地表宣称远端也只执行一次。
顺序与恢复。 事件顺序、业务状态变化、格式升级、备份恢复、存储故障不在本例验收范围。真实 broker 接收成功未必等于消费端提交,何时标记发送成功必须按实际确认语义决定。直接调用 consume 只是展示两个独立提交间的窗口,不是消息中间件替代品。
七、结语:把保证说到边界为止
Outbox 不消灭重复,而是让发送意图与订单留在同一本地事务中;inbox 也不提供神奇的分布式 exactly-once,而是把去重记录与限定范围的业务修改一起提交。
值得验收的不是正常流程能否跑通,而是每个提交前后失败时数据库留下什么、重试又改变什么。本次有限的本地教学实验已经运行通过;生产并发、重试调度、清理策略和外部副作用仍需分别设计与验证。
- 点赞
- 收藏
- 关注作者
评论(0)