Go database/sql/driver.Stmt.NumInput 怎样避免参数数量错误

实现 Go 数据库驱动时，如果调用方传入的参数数量不对，错误可能在驱动执行前出现，也可能一路走到数据库。决定这条边界的关键接口就是 database/sql/driver.Stmt.NumInput：驱动能确定占位符数量时返回非负数，database/sql 可以先做参数个数检查；确实无法确定时返回 -1，通用层就不会替驱动猜测。

官方文档：https://pkg.go.dev/database/sql/driver#Stmt

NumInput 为什么会影响参数错误出现的位置

使用 sql.Stmt 时，SQL 文本已经在准备阶段交给驱动，后续的 Exec、Query 或 QueryRow 只接收占位符对应的值。Go 官方文档也强调，预编译语句的参数占位符由数据库和驱动决定，例如不同数据库可能使用 ? 或 $1。

驱动内部的 driver.Stmt 通过 NumInput() int 告诉 database/sql：这条语句的参数数量是否可知。调用链可以概括为“应用传参 → 通用层询问数量 → 数量匹配后再进入驱动执行”。

能数清占位符时返回非负数

如果驱动的预处理器已经可靠地知道占位符数量，就返回对应的非负整数。例如 SQL 只有两个参数占位符，NumInput 返回 2。这会让通用层在调用驱动的 Exec 或 Query 之前检查传入参数数量，减少无效网络往返。

下面的示例用一个最小的驱动语义模型表示这个判断。它不是完整数据库驱动，而是帮助理解“数量已知时先拦截”的流程：

package main

import (
    "errors"
    "fmt"
)

// checkArgs 模拟 database/sql 在进入驱动执行前做的数量检查。
func checkArgs(numInput int, args []any) error {
    // 非负数代表驱动知道占位符数量，可以直接比较。
    if numInput >= 0 && len(args) != numInput {
        return fmt.Errorf("参数数量错误：需要 %d 个，实际得到 %d 个", numInput, len(args))
    }

    // -1 表示数量未知，不能在通用层武断地拒绝。
    if numInput == -1 {
        return nil
    }
    if numInput 

真实的 database/sql 还会处理 driver.NamedValue、参数转换和可选接口，但判断重点不变：已知数量时，错误尽早返回；这不等于驱动可以省略真正的参数类型检查。

什么时候应该返回 -1

有些驱动无法在准备阶段可靠解析占位符，例如 SQL 方言允许复杂的字符串、注释、存储过程参数或驱动自定义语法。此时返回 -1 比猜一个数字更安全。官方契约明确规定，-1 表示驱动不知道占位符数量，database/sql 不会做参数数量预检。

返回 -1 并不是“参数随便传”。它只是把数量判断从通用层移开：驱动自己的 Exec、Query 或数据库服务器仍可能拒绝错误参数。文章标题里的“避免参数数量错误”，更准确的理解是避免驱动在不知道事实时做出错误的通用判断。

不要把 NumInput 和上下文执行接口混为一谈

NumInput 只描述参数数量。驱动如果实现 StmtExecContext 或 StmtQueryContext，还必须尊重传入的 context.Context，在取消或超时时及时返回。参数预检通过，并不意味着数据库操作一定成功。

import (
    "context"
    "database/sql/driver"
    "errors"
)

type stmt struct {
    query string
}

// NumInput 返回准备阶段已经确认的占位符数量。
func (s *stmt) NumInput() int {
    // 示例语句固定包含两个占位符，实际驱动应从解析结果得出。
    return 2
}

// ExecContext 展示驱动执行阶段仍要处理取消信号。
func (s *stmt) ExecContext(ctx context.Context, args []driver.NamedValue) (driver.Result, error) {
    // 参数数量预检完成后，执行仍可能因超时而结束。
    select {
    case 

生产驱动中要补齐对应的 context、database/sql/driver 导入，并返回符合驱动接口的 driver.Result。如果只实现旧的 Exec 或 Query，database/sql 可能走兼容路径；不要因为参数数量已经检查过，就忽略上下文接口的行为。

排查“参数数量错误”时按这个顺序看

1. 先确认应用传入的参数个数是否真的对应 SQL 占位符，尤其检查条件分支是否少传或多传。
2. 再看驱动的 NumInput 是否返回了真实数量；如果 SQL 方言复杂，不要为了通过预检硬编码一个数字。
3. 区分错误发生在通用层预检、驱动的 Exec/Query，还是数据库服务器解析阶段。
4. 检查语句是否在使用完后调用 Close，避免把参数错误排除后又留下预编译语句或连接资源。
5. 如果使用 StmtExecContext 或 StmtQueryContext，把超时和取消测试纳入驱动回归用例。

常见问题

NumInput 返回 0 是不是表示不允许传参数？

是。它表示通用层认为该语句没有占位参数；如果调用方传入参数，应在驱动执行前被判定为数量不匹配。

返回 -1 后还能检查参数吗？

可以由驱动自己的执行逻辑或数据库服务器检查，但 database/sql 不会再依据一个已知数量做通用预检。

NumInput 能判断参数类型吗？

不能。它只回答数量问题。参数类型转换和检查还涉及 NamedValueChecker、ColumnConverter 或驱动自身的协议实现。

参数数量匹配就一定能执行成功吗？

不一定。连接、权限、SQL 方言、类型转换、事务状态和上下文取消都可能在后续阶段产生错误。