Go sql.Named 怎么让驱动按名称绑定参数

sql.Named 的作用不是改写 SQL，而是创建一个带名称和值的 sql.NamedArg。当它作为 ExecContext、QueryContext 等方法的参数传入后，database/sql 会把名称、序号和值整理成 driver.NamedValue 交给驱动。最终能否按名称绑定，以及查询里应该写 @name、:name 还是其他格式，取决于具体驱动。

官方地址：https://pkg.go.dev/database/sql#Named

最小可用写法：Name 不带占位符前缀

下面的仓储函数接收一条已经按当前驱动方言写好的 SQL。它只负责把业务值以名称传入，不在公共函数里猜测占位符符号。

package orderrepo

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

func updateStatus(ctx context.Context, db *sql.DB, query string, id int64, status string) error {
	result, err := db.ExecContext(
		ctx,
		query,
		// Name 只写标识符本身，不包含 @、: 等 SQL 方言前缀。
		sql.Named("status", status),
		sql.Named("id", id),
	)
	if err != nil {
		return fmt.Errorf("update order status: %w", err)
	}

	// 写操作继续核对影响行数，避免参数绑定成功但条件没有命中。
	affected, err := result.RowsAffected()
	if err != nil {
		return fmt.Errorf("read affected rows: %w", err)
	}
	if affected != 1 {
		return fmt.Errorf("unexpected affected rows: %d", affected)
	}
	return nil
}

调用方提供的 query 可能写成 UPDATE orders SET status = @status WHERE id = @id，也可能使用冒号或其他语法。这里刻意不把某一种写法包装成通用答案：查询中的符号属于数据库和驱动协议，而 sql.Named 的 Name 字段始终不带符号前缀。

名称是怎样交给驱动的

sql.Named("id", 42) 返回 sql.NamedArg{Name: "id", Value: 42}。进入 database/sql 后，每个参数还会得到一个从 1 开始的 Ordinal，随后形成 driver.NamedValue。这个驱动层结构包含三个关键字段：

• Name：非空时应当作为参数标识符使用，而且同样不含符号前缀。
• Ordinal：参数在调用列表里的位置，从 1 开始，总是会设置。
• Value：经过驱动检查或默认转换后交给驱动的值。

因此，“按名称绑定”并不是 Go 在客户端把 SQL 字符串搜索替换一遍。database/sql 负责保留名称和组织参数，具体驱动负责理解查询文本中的占位符，并把 NamedValue 映射到数据库协议。

权限与门禁：先确认驱动支持命名参数

标准库只定义了通用接口，没有承诺所有驱动都支持命名参数。如果驱动只能走旧式位置参数接口，而参数又携带 Name，标准库会返回 sql: driver does not support the use of Named Parameters。这不是 SQL 内容错误，而是驱动能力不匹配。

上线前至少确认两件事：驱动文档是否明确接受 sql.Named；该驱动要求查询文本使用哪一种命名占位符。不要根据另一个数据库的示例推断当前驱动，也不要把“数据库服务器支持命名参数”直接等同于“当前 Go 驱动支持”。

如果驱动不支持，应改用它文档要求的位置占位符和普通参数。不要同时保留命名占位符与位置参数，也不要在应用层用字符串替换模拟绑定；后者容易破坏转义规则，还会重新引入 SQL 注入风险。

流水线阶段：名称校验、值转换、驱动执行

一次命名参数调用可以按三个边界理解。第一层是名称校验：标准库允许空名称表示位置参数；非空名称的首个 Unicode 字符必须是字母。因此 sql.Named("1st", value) 会在到达数据库前失败。为了兼顾常见数据库规则，工程中通常使用英文字母开头、仅含字母数字和下划线的短名称。

第二层是值转换。标准库会依次寻找 Statement 或 Connection 上的 NamedValueChecker、旧式 ColumnConverter，最后使用默认参数转换器。默认转换支持 nil、整数、浮点数、布尔值、字符串、字节切片和时间等驱动值，也会调用实现 driver.Valuer 的类型。自定义值无法转换时，错误会在真正执行 SQL 前返回。

第三层才是驱动执行。实现了 driver.ExecerContext 或 driver.QueryerContext 的连接可以直接收到 []driver.NamedValue；否则标准库可能走准备语句等后备路径。无论走哪条路径，命名绑定的语义仍由驱动决定。

重复名称与参数顺序怎么判断

不要假定“同一个名字出现两次”在所有驱动中都有相同行为。有的驱动允许查询里重复引用同一个命名参数，有的要求为每个位置提供参数，还有的会按自身规则处理重复名称。最稳妥的做法是：把查询和参数列表视为一个由驱动文档约束的整体，并为项目实际使用的驱动写集成测试。

Ordinal 仍然存在，也说明命名参数不是完全脱离顺序的抽象。驱动可以根据 Name 绑定，也可以在其实现内部同时参考 Ordinal。应用代码不应据此猜测驱动行为，只需要保证名称、查询占位符和参数值一致。

失败处理：先区分三类错误

定位问题时，先看错误发生在哪一层，而不是立即改 SQL：

• 出现“name does not begin with a letter”：传给 sql.Named 的名称首字符不合法。
• 出现“driver does not support the use of Named Parameters”：当前驱动路径不支持命名参数。
• 数据库报告未知占位符、语法错误或缺少参数：查询文本使用的占位符方言或名称与驱动要求不一致。
• 错误提到转换参数或 Valuer：参数值类型无法转换，或自定义 Value() 返回了错误。

错误包装时保留操作名和原始错误，既方便日志定位，也允许上层用 errors.Is 判断驱动暴露的特定错误。不要把完整 SQL 和敏感参数值直接拼进错误消息。

可空值与自定义类型

SQL NULL 可以直接传 nil，也可以用实现 driver.Valuer 的类型表达。关键点不是 sql.Named 是否接受 nil，而是该值最终能否成为驱动可处理的 Value。

package orderrepo

import (
	"database/sql"
	"time"
)

func updateArgs(id int64, deliveredAt *time.Time) []any {
	var value any
	if deliveredAt != nil {
		// time.Time 是标准驱动值之一，可以直接交给参数转换链。
		value = *deliveredAt
	} else {
		// nil 表示写入 SQL NULL，具体列约束仍由数据库检查。
		value = nil
	}

	return []any{
		sql.Named("id", id),
		sql.Named("delivered_at", value),
	}
}

读取可空列时使用 sql.NullTime、sql.NullString 或项目自己的 Scanner 类型；那是结果扫描问题，与 NamedArg 的输入绑定是两条不同链路。

把约束固定在仓储层和集成测试里

推荐让每个仓储方法持有与当前驱动匹配的固定查询，而不是把任意 query 暴露给业务层。这样占位符方言、参数名称和业务字段会在同一处审查。测试不必覆盖所有数据库，只需覆盖生产实际使用的驱动。

package orderrepo_test

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

func TestNamedParameterBinding(t *testing.T) {
	db := openIntegrationDB(t) // 使用与生产一致的驱动和测试数据库。
	ctx := context.Background()

	query := integrationUpdateSQL() // 查询占位符由当前驱动的测试配置提供。
	result, err := db.ExecContext(ctx, query,
		sql.Named("status", "paid"),
		sql.Named("id", int64(101)),
	)
	if err != nil {
		t.Fatalf("named binding failed: %v", err)
	}

	// 绑定成功之外，还要确认确实更新了预置记录。
	rows, err := result.RowsAffected()
	if err != nil || rows != 1 {
		t.Fatalf("unexpected result: rows=%d err=%v", rows, err)
	}
}

这类测试验证的不是标准库是否存在，而是“当前版本驱动 + 当前占位符写法 + 当前参数类型”能否共同工作。驱动升级时保留这条用例，可以及时发现绑定语义变化。

复盘清单

• sql.Named 的 Name 只写名称本身，不带符号前缀。
• 查询文本中的占位符完全按当前驱动文档编写。
• 驱动必须支持命名参数，标准库不会为不支持的驱动模拟绑定。
• 名称以字母开头，参数值能通过驱动或默认转换链。
• 写操作同时检查错误和影响行数，错误包装不泄露敏感参数。
• 用生产同款驱动做一条最小集成测试，覆盖真实占位符语法。

相关问题

sql.Named 的名称应该写 @id 还是 id？

写 id。NamedArg.Name 必须省略符号前缀；@id 或其他形式只可能出现在查询文本中，且必须符合驱动文档。

sql.Named 会自动把问号占位符改成命名占位符吗？

不会。它只携带名称和值，不重写 SQL。占位符语法和参数绑定由驱动完成。

参数顺序写错后，名称还能保证绑定正确吗？

不能做跨驱动保证。NamedValue 同时带 Name 和 Ordinal，具体驱动如何处理要看实现；应用应保持清晰一致的参数顺序并用实际驱动测试。

可以把表名或列名放进 sql.Named 吗？

通常不可以。参数绑定用于数据值，不用于 SQL 标识符。动态表名、列名应通过白名单选择并由程序拼接受控片段，不能当作普通值参数。