Go database/sql.NamedArg 怎样给 SQL 参数命名

在 Go 项目里，SQL 参数一多，单靠 ? 和参数位置很容易把 limit、status、owner_id 传错。database/sql.NamedArg 解决的是“参数同时带名字和值”这个问题，但它不会自动修改 SQL，也不能保证所有数据库驱动都支持同一种命名占位符。

官方文档地址：https://pkg.go.dev/database/sql#NamedArg

实用结论是：先写出驱动能够识别的占位符，再用 sql.Named("参数名", 值) 传参；如果仍然报参数数量或占位符错误，就检查驱动的命名参数转换能力，而不是继续改业务值。

先把 SQL 占位符和 NamedArg 分开看

NamedArg 本质上是一个带有 Name 和 Value 的参数描述。database/sql 会把它交给驱动层，驱动决定如何把名称映射为自己的占位符或参数位置。

因此，下面三件事不要混为一谈：

用 sql.Named 给查询参数命名

推荐使用 sql.Named 构造参数。示例中的值仍通过参数化接口传递，命名只改善了代码可读性，不应把用户输入拼进 SQL 字符串。

package main

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

func findOrder(ctx context.Context, db *sql.DB, ownerID int64, state string) (int64, error) {
    // 占位符写法要遵循所用驱动的规则；Named 只负责携带名称和值。
    const query = `
        SELECT id
        FROM orders
        WHERE owner_id = :owner_id AND state = :state
        ORDER BY created_at DESC
        LIMIT 1`

    var orderID int64
    row := db.QueryRowContext(ctx, query,
        sql.Named("owner_id", ownerID),
        sql.Named("state", state),
    )
    // Scan 负责接收查询结果；超时由调用方传入的 context 控制。
    if err := row.Scan(&orderID); err != nil {
        return 0, fmt.Errorf("scan order id: %w", err)
    }
    return orderID, nil
}

func withTimeout(parent context.Context) (context.Context, context.CancelFunc) {
    // 示例展示数据库调用常见的资源边界，调用方应及时释放 cancel。
    return context.WithTimeout(parent, 2*time.Second)
}

这里的关键不是变量名必须和数据库列名一致，而是 SQL 中的名称、sql.Named 的名称以及驱动的转换规则要形成同一套约定。项目如果使用的是 ? 位置占位符，就不要仅因为使用了 NamedArg 而强行把 SQL 改成冒号语法。

多个参数怎么命名，顺序还重要吗

业务代码可以把参数按语义排列，例如先放筛选条件，再放分页参数。这样即使驱动最终按位置转换，调用点也更容易阅读和审查。

args := []any{
    // 名称用于表达意图，值仍由 database/sql 作为参数传给驱动。
    sql.Named("tenant_id", tenantID),
    sql.Named("keyword", keyword),
    sql.Named("page_size", pageSize),
}

rows, err := db.QueryContext(ctx, `
    SELECT id, title
    FROM documents
    WHERE tenant_id = :tenant_id AND title LIKE :keyword
    ORDER BY id DESC
    LIMIT :page_size`, args...)
if err != nil {
    // QueryContext 失败时不要继续遍历 rows，先把错误返回给上层。
    return err
}
defer rows.Close()

for rows.Next() {
    // 每轮扫描都要处理 Scan 错误，避免把半条结果当成成功数据。
    if err := rows.Scan(&id, &title); err != nil {
        return err
    }
}
// 迭代结束后检查驱动在读取过程中报告的错误。
return rows.Err()

不要直接假设“参数名相同就可以重复使用”。有些驱动会把同名参数转换到同一个位置，有些驱动只接受位置参数，另一些驱动可能要求占位符名称符合自己的语法。重复引用要以目标驱动的文档和实际错误为准。

驱动不识别命名参数时按三层排查

1. 看 SQL 占位符：确认当前驱动接受的是 ?、$1、:name 还是其他形式。不要把某个 ORM 的写法直接迁移到原生 database/sql。
2. 看参数转换：database/sql/driver 提供了命名值检查接口，驱动可以据此处理或拒绝命名参数。遇到“参数数量不匹配”时，重点确认驱动是否把名称转换成了位置。
3. 看错误发生位置：SQL 准备阶段失败，通常先查占位符；执行阶段失败，再查值类型、参数顺序和驱动限制；扫描阶段失败，则是结果接收类型问题。

排查时可以先缩小到一个参数、一个条件和一个最小查询。最小化不是为了绕过错误，而是把“SQL 语法问题”“驱动转换问题”和“业务值问题”拆开。

命名参数和安全边界

NamedArg 不是 SQL 过滤器，也不是权限控制。它能帮助值保持在参数化通道中，但表名、列名、排序方向等 SQL 结构通常不能用普通参数代替。对这些结构应使用固定白名单映射。

orderBy := "created_at"
switch requestedOrder {
case "id":
    // 只从固定集合中选择列名，不能把请求字符串直接拼进 SQL。
    orderBy = "id"
case "created":
    orderBy = "created_at"
default:
    return fmt.Errorf("unsupported order: %s", requestedOrder)
}

query := "SELECT id FROM documents WHERE tenant_id = :tenant_id ORDER BY " + orderBy
// tenant_id 仍然通过 NamedArg 传递，结构片段与数据值保持不同边界。
row := db.QueryRowContext(ctx, query, sql.Named("tenant_id", tenantID))

这个例子里只有经过白名单选择的列名进入 SQL 文本；租户 ID 仍然是参数值。两条边界都清楚，审查时更容易发现误把用户输入当成 SQL 结构的代码。

最后记住这四点

• sql.Named 让参数携带名称和值，但不会自动重写 SQL。
• SQL 占位符必须符合当前驱动规则，不能只看 Go 代码表面。
• 同名参数是否可重复使用、名称是否参与转换，要以驱动支持为准。
• 数据值走参数化通道，表名和排序等结构使用固定白名单。

常见问题

NamedArg 的 Name 必须和数据库列名一样吗？

不必须。它首先是参数的业务名称，是否需要与 SQL 占位符对应由 database/sql 与驱动的转换逻辑决定。

使用 NamedArg 后还能按位置传参吗？

可以，但混用时要特别清楚驱动如何转换参数。为了降低维护成本，单个查询尽量采用一致的参数约定。

为什么示例能用冒号占位符，我的驱动却报错？

因为占位符语法不是由 NamedArg 统一规定的。回到驱动文档确认它支持的占位符形式，必要时改回该驱动的标准位置参数写法。