Go 数据库事务如何处理提交后副作用：Outbox、重试边界与幂等消费

订单写进数据库后，服务进程正好在发送通知前重启，数据库里已经有订单，消息队列却没有任何记录。这类故障很难靠“把发送代码放到事务后面”解决，因为提交成功和副作用完成之间天然存在一段不可回滚的时间窗。Go 服务要把这件事做稳，关键是把待发送事件和业务数据放进同一个事务，再让独立投递器负责重试，消费者用业务幂等键挡住重复消息。

先复现一次提交成功但消息缺失

最直观的写法通常是先提交订单，再调用队列客户端：

if err := saveOrder(ctx, db, order); err != nil {
    return err
}
if err := broker.Publish(ctx, "order.created", order.ID); err != nil {
    return err
}
return nil

如果 saveOrder 已经提交，进程在 Publish 前退出，调用方下一次查询会看到订单已经存在，但通知永远不会出现。把 Publish 放进数据库事务也不能真正解决问题：队列不是数据库事务参与者，数据库回滚时无法撤销已经发出的消息；而队列调用超时还可能处于“服务不知道对方到底收没收到”的状态。

把业务写入和 Outbox 放在同一个事务

Outbox 的边界很简单：业务表描述“事情已经发生”，Outbox 表描述“还需要把这件事通知出去”。两张表在同一个 sql.Tx 中写入，只有二者一起提交，调用方才会看到完整状态。

func CreateOrder(ctx context.Context, db *sql.DB, order Order) error {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()

    if _, err = tx.ExecContext(ctx,
        `INSERT INTO orders (id, user_id, amount, status)
         VALUES (?, ?, ?, 'created')`,
        order.ID, order.UserID, order.Amount,
    ); err != nil {
        return err
    }

    payload, err := json.Marshal(OrderCreated{OrderID: order.ID})
    if err != nil {
        return err
    }
    if _, err = tx.ExecContext(ctx,
        `INSERT INTO outbox_events (event_id, topic, aggregate_id, payload, status, attempts)
         VALUES (?, 'order.created', ?, ?, 'pending', 0)`,
        order.EventID, order.ID, payload,
    ); err != nil {
        return err
    }
    return tx.Commit()
}

这里的 event_id 不要每次重试都重新生成。它是一次业务事件的稳定身份，既可以作为投递日志的关联字段，也可以作为消费者的幂等键。Outbox 表至少要有 status、attempts、next_attempt_at、last_error 和创建时间；生产环境还应为待投递状态建立索引。

投递器只改变事件状态，不替业务事务补偿

独立投递器定期读取到期的 pending 事件，先取得一个短租约，再发送消息。发送成功后把状态改成 sent；失败则增加尝试次数并写入下一次时间。租约过期后，另一个投递器可以接管，但这意味着“至少一次投递”，不是“绝不重复”。

type Event struct {
    ID            string
    Topic         string
    Payload       []byte
    Attempts      int
    NextAttemptAt time.Time
}

func deliver(ctx context.Context, event Event, broker Broker) error {
    // event.ID 固定不变；重试只重发同一个事件身份。
    return broker.Publish(ctx, event.Topic, event.ID, event.Payload)
}

func nextDelay(attempt int) time.Duration {
    if attempt > 6 {
        attempt = 6
    }
    return time.Duration(1

发送和状态更新之间仍可能出现故障：消息已经进入队列，但服务在写入 sent 前重启。不要试图用一次查询消灭这个窗口，而要接受重复投递，并让下游能安全地再次处理同一个 event_id。对于无法无限重试的事件，超过上限后进入死信状态，保留原始错误和最后一次尝试时间，便于人工或补偿任务处理。

消费者用幂等键守住重复消息

消费者不能把“收到消息”当成“业务只执行了一次”。常见做法是在业务库中建立消费记录唯一键，或者把幂等键直接放进目标表的唯一约束里。处理流程通常是：开始本地事务，插入消费记录，执行业务变化，最后提交；唯一键冲突就说明这条事件已经成功处理，可以安全确认消息。

func HandleOrderCreated(ctx context.Context, db *sql.DB, msg Message) error {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()

    if _, err = tx.ExecContext(ctx,
        `INSERT INTO consumed_events (event_id, consumer)
         VALUES (?, 'email-notifier')`, msg.ID,
    ); err != nil {
        if isUniqueViolation(err) {
            return nil // 重复投递：业务已成功，直接确认
        }
        return err
    }
    if _, err = tx.ExecContext(ctx,
        `INSERT INTO notification_tasks (order_id, kind)
         VALUES (?, 'order-created')`, msg.OrderID,
    ); err != nil {
        return err
    }
    return tx.Commit()
}

如果副作用本身又是外部服务调用，例如发送邮件，最好把“待发送通知”也落在本地表里，再由通知投递器完成后续动作。不要在持有数据库事务的同时等待慢网络；这样既延长锁时间，也无法获得跨系统回滚。

用故障注入验收三个关键窗口

只跑一条成功路径，无法证明 Outbox 真的可靠。至少要模拟下面三种故障，并检查数据库状态、消息数量和消费结果：

• 业务事务提交前退出：订单和 Outbox 都不应出现。
• 事务提交后、投递状态更新前退出：Outbox 仍为待投递，下一轮能够继续发送。
• 消息已发送、消费者提交前退出：同一 event_id 重投后，目标业务只保留一份结果。

验收指标要拆开看：Outbox 待投递数量反映积压，最老事件年龄反映延迟，attempts 反映失败重试，重复消费计数则反映下游的幂等压力。只统计“发送成功数”会掩盖事件丢失和重复处理。

常见问题

Outbox 能保证消息只发送一次吗？

不能。它主要避免业务提交成功后事件完全丢失，投递器仍可能在发送成功后崩溃，从而重复发送。只要按至少一次投递设计消费者，就能把重复变成可接受的正常情况。

为什么不直接在订单表里加一个 sent 字段？

单个布尔字段难以承载多个副作用、失败原因、重试时间和事件载荷。Outbox 把事件作为独立记录，能够逐条重试、观测和进入死信状态。

重试次数应该设置成多少？

没有通用数字。短暂网络故障可以指数退避，永久参数错误则应尽快进入死信。重试上限要结合业务时效，并给运维留下人工重放或修复入口。

消费者幂等记录和业务变更必须同一事务吗？

如果两者使用同一数据库，通常应放进同一事务，否则可能出现记录已写但业务未完成，或业务已完成但幂等记录缺失的反向窗口。

把可靠性边界写进代码和指标

Go 服务使用 Outbox 后，事务只负责保证“业务事实”和“待办事件”一起落库；投递器负责最终送达，消费者负责重复安全。三层边界各自可观测，故障注入也能对应到明确的恢复动作。上线前把 event_id、租约、重试退避、死信和幂等唯一键写进测试用例，远比在发送函数外层再包一个重试循环更可靠。