订单提交了,消息却没发出:用 Python SQLite 拆解事务型 Outbox

举报
yd_215017870 发表于 2026/11/10 14:59:26 2026/11/10
【摘要】 数据库提交成功,不代表后续消息已经送达。本文用 Python 标准库和两个 SQLite 文件,通过确定性故障注入复现丢消息、重投与重复记账,再用事务型 Outbox 和消费端 inbox 验证本地事务边界,并说明并发、重试与外部副作用的限制。

验证范围:本文示例已在 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,而是把去重记录与限定范围的业务修改一起提交。

值得验收的不是正常流程能否跑通,而是每个提交前后失败时数据库留下什么、重试又改变什么。本次有限的本地教学实验已经运行通过;生产并发、重试调度、清理策略和外部副作用仍需分别设计与验证。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。