Go sql.NamedArg 为什么会被驱动拒绝

我第一次把位置参数改成 sql.Named 时，以为只要给参数起个名字，所有数据库驱动都会自动识别。真正上线前才发现：有的调用直接报错，有的驱动只认自己的占位符，还有的根本不接收带名称的参数。

结论先说：sql.NamedArg 只是把“名称和值”交给 database/sql 和具体驱动，它不会统一各数据库的占位符语法。被拒绝时，应依次检查名称是否合法、SQL 文本是否使用该驱动支持的写法，以及驱动是否支持命名参数；不支持时改回位置参数。

三个边界决定 NamedArg 能不能用

sql.Named("user_id", 42) 返回一个 NamedArg。标准库会检查参数名，并把它整理成驱动层使用的 driver.NamedValue。到这里为止，Go 只保证参数被规范地传递，不保证底层驱动一定接受名称。

名称正确，也可能被驱动拒绝

下面的写法在 API 层是合法的，但前提是 SQL 占位符和驱动能力能够对应。参数名本身不应包含前缀，前缀属于 SQL 方言。

row := db.QueryRowContext(ctx,
    "SELECT name FROM users WHERE id = @user_id",
    sql.Named("user_id", 42),
)
var name string
if err := row.Scan(&name); err != nil {
    return fmt.Errorf("query user: %w", err)
}

这段代码并不意味着每个驱动都支持 @user_id。如果驱动文档只展示 ? 或 $1，就按文档改写 SQL，并直接传值：

row := db.QueryRowContext(ctx,
    "SELECT name FROM users WHERE id = ?",
    42,
)

另一个容易踩的坑是把列名作为参数。参数绑定保护的是“值”，不能把 sql.Named("column", "created_at") 当作排序列或表名。此类标识符必须从代码内白名单选择，再拼入固定 SQL 片段。

把拒绝原因缩到一个可验证点

排查时不要只打印“查询失败”。保留错误链，同时记录驱动类型、参数名和参数值类型；不要记录密码、令牌等敏感值。下面的诊断信息足以判断失败发生在哪一层：

arg := sql.Named("user_id", userID)
err := db.QueryRowContext(ctx, query, arg).Scan(&name)
if err != nil {
    log.Printf("driver=%T arg_name=%s value_type=%T err=%v",
        db.Driver(), arg.Name, arg.Value, err)
}

先确认 arg.Name 没有符号前缀，再对照 SQL 占位符与驱动文档。若驱动不承诺命名参数支持，直接使用位置参数通常比猜测某种语法更可靠。参数值本身若不是驱动可接受的类型，也会在转换阶段失败，此时应先转成字符串、整数、字节或时间等明确类型。

常见问题

sql.Named 的名称要写成 @id 吗？

不要。传给 sql.Named 的名称写 id；SQL 文本里的占位符前缀按数据库和驱动文档书写。

换成 NamedArg 就能防止 SQL 注入吗？

它可以继续安全绑定“值”，但不能绑定表名、列名和排序方向。动态标识符仍要通过代码白名单控制。

我现在把 NamedArg 看成驱动契约的一部分，而不是跨数据库的统一语法。名称、SQL 文本和驱动能力三者一致时它很清晰；任一项不确定时，位置参数往往是更稳妥的选择。