Go database/sql/driver.ErrSkip 怎样让驱动回退到默认参数转换

如果驱动实现了 driver.NamedValueChecker，但它只认识少数自定义类型，不需要把所有普通参数都重新转换一遍。对当前检查器不负责的参数返回 driver.ErrSkip，database/sql 会继续尝试列转换器，最后使用默认参数转换。已识别但转换失败的类型则应该返回真实错误，不能也返回 ErrSkip。

记住一句话：ErrSkip 表示“当前快速路径不处理”，不是“参数转换成功”，也不是“忽略错误”。

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

ErrSkip 到底把参数交给谁

CheckNamedValue 收到的是带有名称、序号和实际值的 driver.NamedValue。官方文档给出的检查优先级是：语句上的 Stmt.NamedValueChecker，连接上的 Conn.NamedValueChecker，语句的 ColumnConverter，最后是 DefaultParameterConverter。如果检查器返回 ErrSkip，当前参数沿着后备路径继续判断。

因此，检查器应当只拦截自己的扩展类型。普通的 string、[]byte、数字、布尔值、time.Time 和 nil 不需要被重复包装。

只处理自定义类型，其余返回 ErrSkip

下面的示例假设驱动只额外支持一个 JSONArg 类型。转换成功后必须把可传输的 []byte 写回 NamedValue.Value；未知类型交给后备转换，编码失败则保留上下文错误。

package driverdemo

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

// JSONArg 是驱动额外认识的结构化参数。
type JSONArg map[string]any

// CheckNamedValue 只接管 JSONArg，其余类型继续走 database/sql 的后备路径。
func (c *conn) CheckNamedValue(nv *driver.NamedValue) error {
	arg, ok := nv.Value.(JSONArg)
	if !ok {
		// 当前检查器不负责普通值，不能把“未处理”伪装成成功。
		return driver.ErrSkip
	}

	data, err := json.Marshal(arg)
	if err != nil {
		// 已识别类型的转换失败要返回真实原因，便于调用方定位数据。
		return fmt.Errorf("编码 JSON 参数失败: %w", err)
	}
	nv.Value = data // 写回 driver.Value，后续驱动只接收 []byte。
	return nil
}

这里的 nil 只表示当前检查器已经完成转换。若把未知类型也改成 nil，后续就不会再调用默认转换，驱动可能收到它无法处理的 Go 类型。

用检查顺序定位“默认转换没有生效”

同一参数可能经过多个候选入口，但不是所有入口都会同时执行。若 Stmt 自己实现了检查器，它会先于 Conn；如果检查器返回 ErrSkip，才有机会进入列转换器或默认转换。排查时先确认实际执行的是哪一个语句对象，再看返回值。

ErrSkip、普通错误和 ErrRemoveArgument 的边界

ErrSkip 是后备转换信号；普通错误表示当前参数已经被检查并且不合法；ErrRemoveArgument 则表示这个值是驱动内部的查询选项，不应进入最终 SQL 参数列表。三者含义不同，不能用 ErrSkip 隐藏数据错误，也不能用 ErrRemoveArgument 代替占位符校验。

官方源码还表明，参数转换完成后才会检查期望数量，因此移除查询选项不会占用 SQL 参数位置；如果误删真实占位符参数，最终会得到“期望数量与实际数量不一致”的错误。

常见问题

所有未识别类型都应该返回 ErrSkip 吗？只有当前检查器确实不负责它们时才这样做。若类型属于驱动支持范围但数据本身不合法，应返回具体错误。

ErrSkip 会让参数直接跳过吗？不会。它让 database/sql 继续尝试后备转换；真正移除参数的是 ErrRemoveArgument。

为什么 Conn 上的检查器没有被调用？先检查 Stmt 是否已经实现同一接口，因为语句级检查器优先；再确认驱动是否把当前参数交给了该连接或语句对象。

本文配图由 ImageGen 生成，用于解释参数转换层次与返回契约，是静态说明图，不是浏览器、终端、IDE 或实际运行结果截图。