Go database/sql 怎样用 ConvertAssign 复用扫描转换

如果你是在业务代码里读取查询结果，通常继续使用 Rows.Scan；如果你正在实现 Go 1.27+ 的数据库驱动，并让 RowsColumnScanner.ScanColumn 把驱动值写入用户提供的目标，就可以用 database/sql.ConvertAssign 复用标准库的扫描转换规则。它不是一个替代查询 API，而是驱动侧的转换边界。

官方文档入口：https://pkg.go.dev/database/sql@go1.27.3#ConvertAssign。官方说明明确指出，ConvertAssign 主要给 driver 实现使用；普通调用方不需要直接调用它。

最小判断：业务层用 Rows.Scan，驱动的 ScanColumn 用 sql.ConvertAssign(scanCtx, dest, src)。不要把一个驱动内部辅助函数当成通用的数据库查询入口。

• 保护对象：用户传入的目标指针或 Scanner。
• 转换来源：驱动允许返回的 driver.Value，例如 int64、float64、bool、[]byte、string、time.Time 和 nil。
• 失败边界：目标不是可写指针、数值转换溢出、NULL 无法落入目标类型，或自定义 Scanner 返回错误。

先分清 Rows.Scan 和 ConvertAssign 的责任

Rows.Scan 是应用侧的读取入口，它已经负责把当前行的每一列交给目标参数。ConvertAssign 的签名是 ConvertAssign(scanCtx driver.ScanContext, dest any, src driver.Value) error，更靠近驱动实现：驱动已经拿到了某一列的 driver.Value，需要把它转换到调用方的目标中。

从安全边界看，dest 是写入边界，src 是驱动输入。转换函数会拒绝会造成信息丢失的转换，但不会替应用决定字段的业务含义；例如把数字转成字符串，不代表它就是合法的订单状态。

在 ScanColumn 中复用标准转换

Go 1.27 新增的 driver.RowsColumnScanner 扩展了 driver.Rows，驱动可以通过 NextRow 前进，再由 ScanColumn 处理某一列。最小实现只需要把当前单元格交给 ConvertAssign，不要复制一份自己的数字、字符串和 NULL 转换表。

// Go 1.27+：自定义 RowsColumnScanner 的核心转换边界。
type driverRows struct {
    columns []string
    values  [][]driver.Value
    current int
}

// ScanColumn 只负责当前行的一个列，转换规则交给 database/sql。
func (r *driverRows) ScanColumn(
    scanCtx driver.ScanContext,
    index int,
    dest any,
) error {
    if r.current == 0 || r.current > len(r.values) {
        // 没有先 NextRow 时，拒绝把上一行或空行写入目标。
        return errors.New("没有可扫描的当前行")
    }
    if index = len(r.columns) {
        // 列索引由 database/sql 传入，越界必须保留为驱动错误。
        return fmt.Errorf("列索引越界: %d", index)
    }

    // 上下文原样传递，RawBytes 等需要行上下文的转换才能保持语义。
    return sql.ConvertAssign(scanCtx, dest, r.values[r.current-1][index])
}

这里的关键不是让驱动“更聪明”，而是保持一个单一转换来源。目标可以是 *int64、*string、*[]byte，也可以是实现了 sql.Scanner 的类型，例如 *sql.NullString。如果目标指针为空、数值超出范围，或自定义 Scanner.Scan 返回错误，驱动应该直接把错误返回给 database/sql。

ScanContext、当前行和旧版本兼容

driver.ScanContext 是一次扫描相关的上下文载体。官方要求实现 driver.RowsColumnScanner 的驱动把它传给 database/sql.ConvertAssign；如果没有这个上下文的场景，才使用空的 driver.ScanContext{}。不要在 ScanColumn 里无条件重建上下文，也不要把它转成普通字符串写日志。

// 这个 Rows 同时保留旧式 Next，便于旧 Go 版本继续使用驱动。
func (r *driverRows) NextRow() error {
    if r.current >= len(r.values) {
        // EOF 表示没有下一行，不应伪造一个空行。
        return io.EOF
    }
    r.current++
    return nil
}

// Next 是旧式 Rows 的整行写入路径；Go 1.27 会优先使用 NextRow/ScanColumn。
func (r *driverRows) Next(dest []driver.Value) error {
    if err := r.NextRow(); err != nil {
        return err
    }
    copy(dest, r.values[r.current-1])
    return nil
}

// 调用方在 ScanColumn 中检查错误，不能只记录日志后继续返回成功。
func scanName(scanCtx driver.ScanContext, rows *driverRows) error {
    if err := rows.NextRow(); err != nil {
        return err
    }
    var name sql.NullString
    if err := rows.ScanColumn(scanCtx, 0, &name); err != nil {
        return fmt.Errorf("扫描 name 失败: %w", err)
    }
    if !name.Valid {
        return errors.New("name 不能为 NULL")
    }
    return nil
}

实现兼容路径时，Next 的整行写入和 ScanColumn 的单列写入应共享同一份行数据，但不应同时推进游标。Go 1.27 在检测到 RowsColumnScanner 后不会调用 Next；保留它只是为了让驱动能够支持旧版本。

把错误和资源边界留在驱动里

使用 ConvertAssign 后，至少要区分四类失败：没有当前行、列索引越界、目标类型无法接收源值，以及 Scanner 自己返回的业务错误。不要把它们统一改成“数据库扫描失败”，否则上层无法判断是驱动游标问题还是字段类型不匹配。

• NULL：可空列优先提供 sql.NullString 或自定义 Scanner，不要强行写进普通字符串。
• 数值：让标准转换检查溢出，不能先把大数截断成较小整数。
• 字节：需要长期持有时使用会复制数据的目标；涉及 RawBytes 时必须遵守它只在下一次行操作前有效的生命周期。
• 游标：结束时返回 io.EOF，关闭时释放驱动资源，并保留最终错误。

如果只是写业务查询，记住 rows.Next、rows.Scan 和 rows.Err 这一常规路径；只有在维护驱动或中间层 Rows 实现时，才需要直接面对 ConvertAssign。

两个容易混淆的问题

ConvertAssign 能不能替代 Rows.Scan？ 不能。它只处理“一个源值写入一个目标”的转换，行遍历、列数量和关闭仍属于 database/sql.Rows 的职责。

调用成功是不是说明数据合法？ 也不是。成功只表示值能按扫描规则写入目标；字段是否符合业务范围、权限和状态机，仍要在业务层单独检查。

归纳起来，ConvertAssign 的价值是让自定义驱动复用标准扫描语义：先维护好当前行和列边界，再原样传递 ScanContext，最后把转换错误和资源生命周期完整交回上层。