Go database/sql NamedValueChecker 怎样让驱动自定义参数

如果数据库驱动只接受 int64、float64、bool、[]byte、string、time.Time 和 nil，业务层的自定义参数就会在进入驱动前失败。解决办法是在驱动的 Conn 或 Stmt 上实现 driver.NamedValueChecker，在 CheckNamedValue 中把类型转换为驱动能处理的值。

最实用的写法是：只在检查器里处理驱动真正认识的自定义类型，转换成功返回 nil，暂时不处理返回 driver.ErrSkip；只有明确把参数当作查询选项而不是 SQL 参数时，才返回 driver.ErrRemoveArgument。

官方地址：https://pkg.go.dev/database/sql/driver@go1.27.3#NamedValueChecker

NamedValueChecker 处在参数生命周期的哪一段

database/sql 接收到 Exec 或 Query 的参数后，会先构造 driver.NamedValue，其中包含名称、从 1 开始的序号和参数值。若当前语句实现了检查器，优先调用 Stmt.NamedValueChecker；否则再看连接上的 Conn.NamedValueChecker，之后才可能进入 ColumnConverter 和默认转换。

这个顺序意味着检查器不是业务层的通用类型适配器，而是驱动边界的一部分。它应该把自定义类型变成驱动可识别的 driver.Value，而不是在这里解析 SQL、拼接字符串或改变业务参数语义。

在 Conn 上转换一个自定义参数

下面的示例把业务层的 JSONValue 转换为 []byte。示例只展示接口关系，真实驱动仍需要把转换后的值交给自己的执行接口。

package driverdemo

import (
	"database/sql/driver"
	"encoding/json"
	"fmt"
)

// JSONValue 表示业务层传入的结构化参数。
type JSONValue map[string]any

// CheckNamedValue 把驱动认识的自定义类型转换为 driver.Value。
func (c *conn) CheckNamedValue(nv *driver.NamedValue) error {
	switch value := nv.Value.(type) {
	case JSONValue:
		data, err := json.Marshal(value)
		if err != nil {
			return fmt.Errorf("编码 JSON 参数失败: %w", err)
		}
		// 转换后写回 NamedValue，后续驱动接口收到的是 []byte。
		nv.Value = data
		return nil
	default:
		// 非本驱动专属类型交给 ColumnConverter 或默认转换继续处理。
		return driver.ErrSkip
	}
}

返回 nil 后，NamedValue.Value 必须已经是驱动能够处理的值。若自定义类型编码失败，应返回带上下文的真实错误；不要把错误吞掉后返回 ErrSkip，否则后续转换可能产生更难定位的“类型不支持”。

ErrSkip 和 ErrRemoveArgument 不能混用

ErrSkip 表示“这个检查器暂时不处理当前参数”，database/sql 会继续尝试列转换器或默认参数转换。它适合处理器只覆盖少数自定义类型的情况。相反，ErrRemoveArgument 会让当前参数从最终参数列表中移除，适合驱动定义查询级选项，而不是 SQL 占位参数。

// CheckNamedValue 展示查询选项和普通参数的不同返回语义。
func (c *conn) CheckNamedValue(nv *driver.NamedValue) error {
	switch option := nv.Value.(type) {
	case QueryOption:
		c.options = append(c.options, option)
		// 该值只影响本次查询，不应继续传给 SQL 驱动接口。
		return driver.ErrRemoveArgument
	case JSONValue:
		data, err := json.Marshal(option)
		if err != nil {
			return fmt.Errorf("编码查询参数失败: %w", err)
		}
		nv.Value = data
		return nil
	default:
		// 保留 database/sql 的后备转换路径。
		return driver.ErrSkip
	}
}

使用 ErrRemoveArgument 时要同步考虑占位符数量。官方实现会在参数转换完成后再检查最终参数数量，因此被移除的选项不会占用驱动需要的 SQL 参数位置；如果普通参数被错误地移除，就会得到参数数量不匹配。

参数不生效时按四个位置排查

还要留意 driver.NamedValue.Name 的语义：名称没有占位符前缀，序号始终从 1 开始。检查器只负责驱动侧的类型与选项边界，命名参数最终如何映射到数据库语法，仍由具体驱动的执行逻辑决定。

常见问题

NamedValueChecker 应该实现在哪里？可以实现于 Conn 或 Stmt。同一条语句同时具备两者时，语句检查器优先。

所有未知类型都返回 ErrSkip 吗？只有检查器确实不负责的类型才这样做；已识别但转换失败的自定义类型应该返回具体错误。

ErrRemoveArgument 能用来跳过 SQL 参数吗？它适合移除驱动内部的查询选项，不应替代对 SQL 占位参数的正常校验。

本文配图由 ImageGen 生成，用于解释参数对象和接口关系，是静态说明图，不是浏览器、终端或实际运行结果截图。