在事务函数中保证提交失败也能返回准确错误

在 Go 的 database/sql 中，业务函数返回 nil 只代表事务里的语句暂时没有报告错误，并不代表修改已经持久化。真正的成功边界是 tx.Commit() 返回 nil。网络中断、连接失效、数据库故障转移或驱动提交失败，都可能让最后一步报错；如果事务包装函数忽略这个返回值，调用方就会把“提交结果未知或失败”误当成成功。

提交阶段为什么必须单独返回错误

一个常见误区是：业务回调执行完毕就直接返回 nil，或者调用了 Commit 却没有检查错误。事务内部的 ExecContext 成功，只说明数据库接受了当前语句；提交时数据库仍需要完成日志刷新、约束检查或连接协议交互。官方文档明确要求检查 Commit 的返回值：只有它为 nil，事务结果才能视为整体生效。

因此事务函数至少有四个错误出口：BeginTx 失败、业务回调失败、回滚失败、Commit 失败。它们需要不同的上下文，否则日志里只剩“transaction failed”，调用方无法判断该重试业务、排查 SQL，还是处理数据库可用性问题。

用最小事务骨架锁定资源边界

最小可用骨架应在 BeginTx 成功后立即安排兜底回滚，然后执行回调，最后显式提交。延迟回滚在事务已经成功提交后通常会得到 sql.ErrTxDone，忽略它即可；它的价值是覆盖中途返回和 panic，避免未来修改代码时漏掉资源收尾。

func WithinTx(
    ctx context.Context,
    db *sql.DB,
    opts *sql.TxOptions,
    fn func(*sql.Tx) error,
) error {
    // BeginTx 失败时事务尚未创建，直接返回入口错误。
    tx, err := db.BeginTx(ctx, opts)
    if err != nil {
        return fmt.Errorf("开始事务: %w", err)
    }

    // 兜底回滚覆盖提前返回和 panic；提交成功后会返回 sql.ErrTxDone。
    defer func() { _ = tx.Rollback() }()

    // 业务回调只能使用 tx，避免部分语句绕过事务连接。
    if err := fn(tx); err != nil {
        rbErr := tx.Rollback()
        if rbErr != nil && !errors.Is(rbErr, sql.ErrTxDone) {
            // 同时保留原始业务错误和真正的回滚错误。
            return errors.Join(
                fmt.Errorf("执行事务逻辑: %w", err),
                fmt.Errorf("回滚事务: %w", rbErr),
            )
        }
        return fmt.Errorf("执行事务逻辑: %w", err)
    }

    // 业务成功不代表持久化成功，Commit 错误必须原样向上传递。
    if err := tx.Commit(); err != nil {
        return fmt.Errorf("提交事务: %w", err)
    }
    return nil
}

这里没有在提交失败后再次把回滚结果当成主错误。Commit 一旦返回，事务就不应再被使用；兜底 Rollback 即使得到 sql.ErrTxDone 也不会覆盖更重要的提交错误。调用方最终拿到的是带有“提交事务”上下文的原始错误链。

分别保留业务错误、回滚错误和提交错误

业务失败时，原始业务错误是主因。例如库存不足、唯一键冲突或第二条 SQL 执行失败，都应先保留。回滚错误只有在它真实存在且不是 sql.ErrTxDone 时才需要追加；使用 errors.Join 后，errors.Is 仍可匹配错误链中的任一底层错误。

提交失败则不同：这时不要根据前面语句的返回值推断最终状态，也不要返回 nil。上层应把操作视为失败或结果不确定，并根据业务幂等键、数据库约束和重试策略处理。尤其是支付、余额、订单状态等写入，重试前必须先确认业务操作具有幂等保护，不能只看到“提交失败”就无条件再执行一次。

完整事务函数：让每种失败都有准确上下文

下面的调用示例把转账的两条更新都放在同一个 sql.Tx 中。事务回调只描述业务操作，资源结束和错误归类由 WithinTx 统一完成。这样业务层不需要在每个分支重复写提交和回滚逻辑。

func transfer(ctx context.Context, db *sql.DB, fromID, toID int64, amount int64) error {
    if amount = ?`,
            amount, fromID, amount,
        )
        if err != nil {
            return fmt.Errorf("扣减付款方余额: %w", err)
        }

        rows, err := result.RowsAffected()
        if err != nil {
            return fmt.Errorf("读取扣款影响行数: %w", err)
        }
        if rows != 1 {
            return fmt.Errorf("付款方不存在或余额不足")
        }

        // 第二条更新失败时，WithinTx 会回滚第一条更新。
        if _, err := tx.ExecContext(ctx,
            `UPDATE accounts SET balance = balance + ? WHERE id = ?`,
            amount, toID,
        ); err != nil {
            return fmt.Errorf("增加收款方余额: %w", err)
        }
        return nil
    })
}

上下文取消、panic 与驱动差异

BeginTx 会让事务继承传入的 Context。当上下文被取消时，database/sql 会尝试回滚事务，随后 Commit 会返回错误。因此请求超时后仍然必须检查事务函数的最终返回值，不能因为业务回调刚好执行完就记录成功。

延迟回滚还能覆盖 panic：Go 在栈展开时会执行 defer，然后继续向上传播 panic。示例故意不在事务函数里恢复 panic，因为把未知编程错误悄悄转成普通错误会隐藏问题；如果服务已有统一恢复中间件，让它负责记录和响应即可。

不同数据库和驱动对提交失败的底层错误类型、取消响应速度和连接状态处理可能不同。通用封装只负责保留错误链，不应按错误字符串猜测结果。若业务需要自动重试，应在驱动文档和数据库隔离级别的基础上设计，并用幂等约束阻止重复写入。

常见写法为什么会丢失准确信息

相关问题

可以直接写 return tx.Commit() 吗？

可以保留提交错误，但缺少“提交事务”这一层业务上下文。封装函数中更推荐显式判断并用 %w 包装，日志和 errors.Is 都更清楚。

提交失败后一定能确定数据没有写入吗？

不能一概而论。错误可能发生在客户端无法确认服务端结果的阶段，具体语义取决于数据库和驱动。安全做法是把结果视为失败或不确定，并依赖业务幂等键、唯一约束或状态查询决定后续动作。

为什么 defer Rollback 可以忽略错误？

它只是兜底收尾。业务失败分支已经显式检查回滚错误，提交成功或事务已结束后，兜底调用通常只会得到 sql.ErrTxDone；真正需要返回的提交错误不会被覆盖。