Go sql.Tx 提交成功后回滚错误的处理约定

使用 database/sql 时，最容易误判的一条日志是：Commit 已经返回成功，defer 里的 Rollback 却记录了 sql: transaction has already been committed or rolled back。这不是提交后又发生了数据库回滚，而是同一个 sql.Tx 已经结束，清理动作按约定返回了 sql.ErrTxDone。

官方地址：https://pkg.go.dev/database/sql

提交成功后的 Tx 已经不能再次回滚

Go 官方文档把 Tx 定义为进行中的事务，并要求事务最终调用 Commit 或 Rollback。源码中的完成标记只从未完成切换到完成一次，因此这两个方法不是可以反复调用的互斥按钮，而是结束事务生命周期的入口。

常见的保护写法是先注册 defer tx.Rollback()，正常路径最后执行 tx.Commit()。提交成功后，defer 仍会运行，但此时回滚只是一次收尾尝试，返回 sql.ErrTxDone。它说明对象已结束，不代表数据库撤销了刚才的提交。

业务操作失败时才把 Rollback 当作补偿动作

事务中的 SQL 执行、扫描或业务校验失败时，事务通常仍处于进行中，Rollback 才有实际的撤销意义。此时应优先保留业务错误；回滚错误可以单独写入日志或指标，除非系统明确规定回滚失败必须升级为新的错误。

因此，直接在 defer 中对所有回滚错误都打 error 日志，会把成功提交后的正常清理误报成线上故障。日志至少要区分 sql.ErrTxDone、驱动错误和业务错误。

Commit 返回错误时不要用 ErrTxDone 覆盖根因

Commit 返回非 nil 时，调用方只能确认提交操作没有得到成功结果，不能简单推断为“肯定没有写入”。网络断开、驱动返回错误或上下文取消都可能让结果需要结合业务幂等设计判断。此时再次调用 Rollback 通常只会得到 sql.ErrTxDone，它不是比提交错误更有价值的新结论。

重试前要先确认写入是否具备幂等键、唯一约束或可查询的业务状态；不要把一次不确定的提交错误直接包装成可安全重试。特别是支付、库存、订单这类操作，重试策略应放在能理解业务状态的上层。

一个不会误报的事务封装

下面的封装使用命名返回值：业务函数失败时执行清理，提交成功后的 ErrTxDone 被忽略，提交错误原样保留。真实项目可以在非预期回滚失败的位置接入结构化日志或指标。

package txhelper

import (
    "context"
    "database/sql"
    "errors"
    "fmt"
)

func WithTx(ctx context.Context, db *sql.DB, work func(*sql.Tx) error) (err error) {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }

    defer func() {
        // Commit 成功后 Rollback 只会返回 ErrTxDone，这属于正常收尾。
        rbErr := tx.Rollback()
        if rbErr != nil && !errors.Is(rbErr, sql.ErrTxDone) && err == nil {
            // 没有更早的业务错误时，才把真实回滚失败返回给调用方。
            err = fmt.Errorf("rollback transaction: %w", rbErr)
        }
    }()

    if err = work(tx); err != nil {
        // work 失败时事务仍可能有效，defer 会尝试回滚。
        return err
    }

    // Commit 的错误必须保留，不能被 defer 中的 ErrTxDone 覆盖。
    return tx.Commit()
}

这段代码的关键不是“所有回滚错误都忽略”，而是只忽略明确的 sql.ErrTxDone。如果事务尚未结束却出现连接断开、驱动拒绝等回滚错误，应记录原始业务错误和回滚错误，便于判断连接池、驱动或数据库状态。

排查日志时按三步确认边界

1. 先看 Commit 的返回值：为 nil 时，后续 ErrTxDone 多半是预期清理；非 nil 时，以提交错误为主线。
2. 再看错误发生前是否执行过 Commit 或 Rollback，避免重复收尾或并发使用同一 Tx。
3. 最后判断是否需要业务重试：只有具备幂等依据时，才在上层查询状态后决定重试。

常见问题

提交成功后还需要手动调用 Rollback 吗？

不需要。可以保留 defer 作为异常路径清理，但要把提交后的 sql.ErrTxDone 当作预期结果处理。

能不能把 Rollback 的错误直接返回？

不能无条件返回。它可能覆盖更早的业务错误或 Commit 错误；应先判断是否为 sql.ErrTxDone，再按错误优先级记录。

Commit 失败后再次执行 Commit 或 Rollback 能恢复吗？

通常不能靠同一个 Tx 恢复，因为事务已经进入结束状态。应保留原错误，结合幂等键和业务状态查询决定后续动作。