Go Tx.StmtContext 怎样让预处理语句绑定事务生命周期

我在把一条可复用的预处理语句放进事务时，最容易混淆的是：tx.StmtContext(ctx, stmt) 返回的新值到底是不是原来的 stmt。它不是把原始语句从 DB 中搬走，而是为当前事务得到一个事务专用的 *sql.Stmt。这个事务级语句只在当前事务里工作，事务提交或回滚后会随事务关闭。

Tx.StmtContext 返回的到底是什么

database/sql 将预处理语句分成两个容易被混在一起的层次：原始 Stmt 依附于 DB，而 Tx.StmtContext 返回的语句依附于当前 Tx。可以把它理解成“同一条 SQL 的事务内适配版本”，而不是复制出一份需要由调用方在事务结束后长期保存的对象。

这样设计的好处是，原始语句仍然可以被后续事务复用；当前事务内的执行则明确落在同一个事务边界里。事务结束时，事务级语句一起收口，调用方不需要再用它去做下一次事务的执行。

先准备一个可以跨事务复用的 Stmt

一个典型的写法是让 DB 负责准备原始语句，在应用或仓储对象结束时关闭它；每次开启事务后，再用 StmtContext 取得当前事务版本。下面的示例使用占位符，具体占位符形式仍由数据库驱动决定。

package main

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

func updateBalance(ctx context.Context, db *sql.DB, stmt *sql.Stmt, id int64, delta int64) error {
    // BeginTx 让事务从同一个 context 开始，便于统一取消和回滚。
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin transaction: %w", err)
    }

    // 无论后续哪一步失败，都先尝试回滚；提交成功后 Rollback 会返回已完成状态。
    defer func() {
        _ = tx.Rollback()
    }()

    // 这里得到的是绑定到 tx 的事务级 Stmt，不要把它保存到下一次事务中复用。
    txStmt := tx.StmtContext(ctx, stmt)
    _, err = txStmt.ExecContext(ctx, delta, id)
    if err != nil {
        return fmt.Errorf("update balance: %w", err)
    }

    // Commit 成功后，事务级 Stmt 随事务结束；原始 stmt 仍属于 db。
    if err := tx.Commit(); err != nil {
        return fmt.Errorf("commit transaction: %w", err)
    }
    return nil
}

func main() {
    // 示例只展示生命周期关系，driver 和 DSN 由实际项目配置。
    var db *sql.DB
    ctx := context.Background()
    stmt, err := db.PrepareContext(ctx, "UPDATE balance SET amount = amount + ? WHERE id = ?")
    if err != nil {
        log.Fatal(err)
    }
    defer stmt.Close() // 原始 DB 级 Stmt 在 DB 使用结束时关闭。

    if err := updateBalance(ctx, db, stmt, 42, 100); err != nil {
        log.Fatal(err)
    }
}

示例中的 defer tx.Rollback() 是常见的兜底清理动作：如果中途返回，事务会尝试回滚；如果已经成功提交，回滚不会重新打开事务。真正的资源重点是：不要把 txStmt 放进全局缓存，也不要在事务结束后继续调用它。

context 到底管准备还是管执行

Tx.StmtContext(ctx, stmt) 的 context 负责把已有语句准备成当前事务要使用的语句。它不等于后续执行动作的 context。执行可能阻塞在数据库驱动或网络上，因此仍然要把可取消的 context 传给 ExecContext、QueryContext 或 QueryRowContext。

func updateWithTimeout(parent context.Context, db *sql.DB, stmt *sql.Stmt) error {
    // 准备事务级 Stmt 和真正执行分别使用明确的 context。
    prepareCtx, cancelPrepare := context.WithTimeout(parent, 2*time.Second)
    defer cancelPrepare()

    tx, err := db.BeginTx(parent, nil)
    if err != nil {
        return err
    }
    defer func() {
        _ = tx.Rollback()
    }()

    // prepareCtx 只覆盖绑定到事务的准备阶段。
    txStmt := tx.StmtContext(prepareCtx, stmt)

    // execCtx 控制执行阶段；超时后让驱动收到取消信号。
    execCtx, cancelExec := context.WithTimeout(parent, 3*time.Second)
    defer cancelExec()
    if _, err := txStmt.ExecContext(execCtx, 100, 42); err != nil {
        return err
    }

    // 只有提交成功，调用方才把这次事务当作完成。
    return tx.Commit()
}

上面的代码只用于说明边界，实际编译时别忘记导入 time。如果项目不需要分开控制准备和执行，也可以直接复用同一个请求 context；关键不是变量名，而是不要以为 StmtContext 会替代执行阶段的取消控制。

提交、回滚和 Close 应该怎样安排

通常不需要在每个调用点显式 txStmt.Close() 来模拟事务结束；更重要的是让事务确定结束，并且不再使用返回的事务级语句。原始 stmt.Close() 则不能省略到永久，因为它是 DB 级对象，仍可能保留驱动资源。

几个容易踩到的边界

可以直接用原始 stmt 执行吗？

如果调用 stmt.ExecContext，它的执行不等于通过当前 Tx 获得的事务级语句。需要让预处理语句参与当前事务时，应使用 tx.StmtContext 返回的值，或者直接使用 tx.PrepareContext。

Tx.Stmt 和 Tx.StmtContext 有什么区别？

两者都返回事务专用语句；Tx.Stmt 内部使用背景 context，Tx.StmtContext 允许你为准备阶段提供 context。需要把取消、超时和请求生命周期传入准备阶段时，优先使用后者。

事务提交后还能复用 txStmt 吗？

不能把它当作下一次事务的 Stmt。提交或回滚后它已经到达自己的生命周期边界；下一次事务应再次从原始 DB 级 stmt 调用 StmtContext，或者重新准备事务级语句。

最后用一句话判断是否写对

如果一条语句需要跨多个事务复用，就把原始 stmt 留在 DB 层；如果它要参加当前事务，就在事务内部调用 tx.StmtContext(ctx, stmt)，用执行阶段的 context 调用 ExecContext，最后让 Commit 或 Rollback 结束事务级对象。这样准备、执行和清理各自有清楚的归属，代码也不会把已结束的事务语句带到下一次请求中。