Go sql.Named 怎么传递具名查询参数

sql.Named 用来把一个参数名和一个 Go 值包装成 sql.NamedArg，再传给 QueryContext、ExecContext 等方法。SQL 中写驱动支持的具名占位符，例如 @status；Go 代码里写 sql.Named("status", value)，参数名不要包含 @、冒号或其他前缀。

官方文档：https://pkg.go.dev/database/sql#Named

sql.Named 实际传递了什么

sql.Named(name, value) 是创建 sql.NamedArg 的简写。NamedArg 只有两个核心信息：Name 是占位符名称，Value 是要交给驱动的参数值。官方文档要求 Name 省略符号前缀，因此 SQL 里即使写的是 @status，Go 里也只传 "status"。

它的价值在于让多参数 SQL 更容易核对，不再只靠参数位置判断“第三个问号到底对应哪个值”。但是否支持具名参数、SQL 里使用 @name、:name 还是其他形式，仍取决于数据库和驱动。

多条件查询的完整写法

下面示例按状态和创建时间查询用户。示例使用 @name 形式表达具名占位符；如果你的驱动采用其他语法，应同时调整 SQL 文本，并查阅驱动对 NamedArg 的支持说明。

func listUsers(
    ctx context.Context,
    db *sql.DB,
    status string,
    start time.Time,
) ([]User, error) {
    rows, err := db.QueryContext(ctx, `
        SELECT id, name
        FROM users
        WHERE status = @status
          AND created_at >= @start
        ORDER BY id
    `,
        // 参数名不写 @；符号只属于 SQL 占位符语法。
        sql.Named("status", status),
        sql.Named("start", start),
    )
    if err != nil {
        return nil, fmt.Errorf("按条件查询用户: %w", err)
    }
    defer rows.Close() // 无论扫描成功或失败，都释放结果集资源。

    users := make([]User, 0)
    for rows.Next() {
        var user User
        if err := rows.Scan(&user.ID, &user.Name); err != nil {
            return nil, fmt.Errorf("读取用户行: %w", err)
        }
        users = append(users, user)
    }
    // Next 停止后检查迭代错误，避免返回不完整结果。
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("遍历用户结果: %w", err)
    }
    return users, nil
}

调用侧只提供业务值，SQL 结构保持固定。这样既便于阅读，也让驱动负责参数编码和绑定。sql.Named 同样可以传给 ExecContext，用于 UPDATE、DELETE 等不返回结果集的语句。

三个最容易写错的地方

还有一个细节：NamedArg 的 Name 为空时，会按参数在列表中的位置处理。这适合底层统一构造参数列表，但普通业务代码通常直接传位置值更清楚，不必特意创建空名称的 NamedArg。

什么时候适合用具名参数

当 SQL 有多个同类型条件、参数顺序容易看错，或者同一名称需要在驱动支持的语法中重复引用时，具名参数更易维护。只有一两个简单条件时，位置参数通常更短。选择标准不是“哪种更高级”，而是当前驱动是否支持、团队能否快速核对 SQL 与参数。

无论选哪种方式，都不要把表名、列名或排序方向当成普通参数绑定。参数绑定面向数据值；动态标识符应从程序内的白名单选择，再拼出受控 SQL 结构。

常见问题

sql.Named 会自动把问号替换成具名占位符吗？

不会。它只创建 NamedArg。SQL 占位符文本仍要按数据库和驱动要求编写。

同一个参数名能在 SQL 中出现多次吗？

这取决于具体驱动的具名参数实现。不要仅凭标准库 API 推断驱动一定支持重复引用，应查看对应驱动文档或使用多个明确参数。

NamedArg 能绑定表名或列名吗？

不能把标识符当作普通值参数。表名、列名和排序关键字应使用程序控制的白名单，而不是接收任意用户输入。

结语

sql.Named 的正确心智模型很简单：SQL 里写驱动支持的具名占位符，Go 里用不带符号的名称配上值，最后让驱动完成绑定。先确认驱动语法，再核对名称和值，就能避免多数“不生效”问题。