Go database/sql.Tx.StmtContext 怎样复用预编译语句

如果一条 SQL 已经通过 DB.PrepareContext 准备好，但这次业务必须在事务里执行，不要把原来的 *sql.Stmt 直接当成事务语句使用。更稳妥的做法是：事务开始后调用 tx.StmtContext(ctx, stmt)，得到一个只在当前事务中运行的语句，再用它完成多次执行。

官方资料：https://pkg.go.dev/database/sql#Tx.StmtContext

这里的关键不是“把 SQL 再写一遍”，而是把已有预编译语句映射到当前事务的连接和生命周期。StmtContext 的上下文只用于准备这个事务语句，真正执行时仍应使用 ExecContext、QueryContext 等带上下文的方法。

先区分三种预编译方案

Go 官方把预编译语句分成几个作用域。DB.PrepareContext 适合把固定 SQL 准备一次，之后在不同调用中复用；Tx.PrepareContext 直接创建只属于当前事务的语句；Tx.StmtContext 则接收一个已有的 *sql.Stmt，把它转换成当前事务里的语句。

因此，标题中的“复用”指的是复用已经准备好的 SQL 定义，不是让同一个事务语句跨事务长期持有。事务提交或回滚后，Tx.StmtContext 返回的语句会随事务关闭。

在事务入口绑定已有语句

下面的例子假设 updateBalance 是应用启动时准备好的语句。一次转账事务中需要更新两行余额，两个执行都使用同一个事务语句。

package account

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

// Transfer 在一个事务中完成扣款和入账，避免两步只成功一步。
func Transfer(ctx context.Context, db *sql.DB, updateBalance *sql.Stmt, fromID, toID int64, amount int64) error {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin transaction: %w", err)
    }
    // 函数提前返回时回滚；提交成功后 Rollback 会返回 sql.ErrTxDone，可安全忽略。
    defer tx.Rollback()

    // 把 DB 级语句转换为当前事务专用语句，ctx 只参与这次绑定准备。
    txStmt := tx.StmtContext(ctx, updateBalance)
    defer txStmt.Close()

    if _, err := txStmt.ExecContext(ctx, -amount, fromID); err != nil {
        return fmt.Errorf("debit account %d: %w", fromID, err)
    }
    if _, err := txStmt.ExecContext(ctx, amount, toID); err != nil {
        return fmt.Errorf("credit account %d: %w", toID, err)
    }
    if err := tx.Commit(); err != nil {
        return fmt.Errorf("commit transfer: %w", err)
    }
    return nil
}

这个写法有三个值得保留的动作：先用 BeginTx 建立边界，再用 StmtContext 绑定已有语句，最后让所有执行都走 txStmt。如果任意一次执行失败，延迟的 Rollback 会撤销事务；如果提交成功，后续回滚会被数据库/sql 忽略。

执行重复写入并处理失败

Tx.StmtContext 返回的仍然是 *sql.Stmt，所以参数只传占位符对应的值，不要再次传入 SQL 字符串。每次执行都建议使用 ExecContext，这样执行阶段的超时或取消可以由调用方控制。

// PrepareSharedStatements 在初始化阶段准备可跨调用复用的固定 SQL。
func PrepareSharedStatements(ctx context.Context, db *sql.DB) (*sql.Stmt, error) {
    const query = `UPDATE account_balance SET balance = balance + ? WHERE account_id = ?`

    stmt, err := db.PrepareContext(ctx, query)
    if err != nil {
        return nil, fmt.Errorf("prepare balance update: %w", err)
    }
    // 调用方在应用关闭时负责关闭 DB 级语句，释放驱动侧资源。
    return stmt, nil
}

// applyPair 展示同一事务语句的多次执行；参数顺序必须对应 ? 占位符。
func applyPair(ctx context.Context, tx *sql.Tx, shared *sql.Stmt, firstID, secondID int64) error {
    txStmt := tx.StmtContext(ctx, shared)
    defer txStmt.Close()

    if _, err := txStmt.ExecContext(ctx, 10, firstID); err != nil {
        return fmt.Errorf("update first account: %w", err)
    }
    if _, err := txStmt.ExecContext(ctx, -10, secondID); err != nil {
        return fmt.Errorf("update second account: %w", err)
    }
    return nil
}

如果两次执行使用不同 SQL，就不应该强行复用同一个 txStmt；可以为每条固定 SQL 准备一个 DB 级语句，或者直接在事务里分别调用 tx.PrepareContext。复用的前提是 SQL 文本和占位符结构稳定。

理解 context 和 Close 生命周期

最容易误解的地方是 StmtContext 的 ctx。官方文档明确指出，它用于准备事务语句，不是执行阶段的上下文。因此，即使绑定时使用了一个短超时上下文，也要在每次 ExecContext 或 QueryContext 中传入真正控制数据库操作的上下文。

生命周期可以按两层管理：

• DB 级 stmt：由初始化代码创建，使用周期覆盖多个事务，在应用关闭或不再使用时调用 Close。
• 事务级 txStmt：在事务开始后由 StmtContext 得到，函数内用完就关闭；提交或回滚也会结束它的事务作用域。

同时保留 defer tx.Rollback() 是为了覆盖所有提前返回路径。它不是用来替代 Commit 的，而是让错误处理保持集中。

什么时候不该使用 Tx.StmtContext

它很适合“固定 SQL + 多个事务”的场景，但不是所有查询都需要预编译。一次性 SQL、只执行一次的后台任务，直接使用 tx.ExecContext 反而更直观；如果 SQL 只属于当前事务，tx.PrepareContext 可以直接表达所有权，减少共享语句的管理。

还要注意两个边界：第一，Tx.StmtContext 不会替你开始事务，调用它之前必须已经有 *sql.Tx；第二，返回语句不能在事务结束后继续用于下一次事务。下一次事务应再次从 DB 级语句调用 StmtContext，或者重新准备。

用一张表做最后决策

一句话记忆：DB.PrepareContext 负责准备可复用的 SQL，Tx.StmtContext 负责把它放进当前事务，ExecContext 负责用执行阶段上下文真正运行。三者各自承担一层职责，代码就不容易把语句作用域和事务作用域混在一起。

常见追问

Tx.StmtContext 会复制原来的 SQL 吗？

它返回当前事务的预编译语句视图，调用者不需要重新传入 SQL 文本；具体底层准备和复用方式由 database/sql 与驱动协作完成。

绑定时的 context 会取消后续 ExecContext 吗？

不会。绑定用的 context 只用于准备，后续执行必须传入自己的执行上下文。

tx.StmtContext 返回的语句要不要 Close？

建议在当前函数中显式 defer txStmt.Close()，同时依赖事务提交或回滚结束其事务作用域；原始 DB 级语句则按跨调用的生命周期单独关闭。