Go database/sql Rows.Columns 怎样正确对应 Scan 字段

在 Go 的 database/sql 中，Rows.Columns() 返回的是当前结果集的列名，Rows.Scan() 则按照同一个结果集的列顺序，把这一行的值写入传入的目标地址。两者不是“按字段名自动匹配”，而是“按下标位置对应”。

因此，想让动态查询可靠工作，核心规则只有一句：第 i 个列名描述第 i 个扫描值，第 i 个扫描值写入第 i 个目标地址。列名切片适合解释和建立映射，但不会改变 Scan 的位置语义。

官方参考：https://pkg.go.dev/database/sql#Rows.Columns

Rows.Columns 返回的是什么，为什么不能直接当成 Scan 参数

Rows.Columns() 的返回值是一个字符串切片，描述当前结果集的列名。它回答的是“这一行有哪些列、按什么顺序排列”，并不包含当前行的值，也不会替你创建接收变量。

可以把一次查询想成两个并排的数组：

常见误区是把列名切片直接传给 Scan，例如 rows.Scan(columns...)。这会把字符串值当成接收目标，既没有表达“按列名寻找字段”的意图，也不符合 Scan 需要可写目标地址的要求。

旧写法的问题：把列名顺序误认为字段名匹配

固定查询的列顺序通常在代码里是可见的，所以可以直接写出结构体字段对应的指针：

rows, err := db.QueryContext(ctx, `SELECT id, name FROM users`)
if err != nil {
    return err
}
defer rows.Close() // 无论中途如何返回，都释放结果集持有的资源

for rows.Next() {
    var id int64
    var name string

    // Scan 按 SELECT 的列顺序写入两个目标地址。
    if err := rows.Scan(&id, &name); err != nil {
        return err
    }
    fmt.Println(id, name)
}

// 迭代结束后仍要读取 Rows.Err，发现驱动在遍历阶段报告的错误。
if err := rows.Err(); err != nil {
    return err
}

这里没有使用 Columns()，并不是因为它不重要，而是因为查询列已经固定。真正危险的是查询语句、扫描目标和后续字段解释的顺序不一致：SQL 改了列顺序，代码却只按变量名“想当然”地读取，结果就可能悄悄错位。

新规则：用下标建立列名与 Scan 目标的对应

动态列场景需要先拿到列名，再为每一列准备一个可写的接收槽位。最小的关系是：

• columns[i] 只说明第 i 列的名字。
• values[i] 保存第 i 列的当前行值。
• dest[i] 必须是指向 values[i] 的指针。
• rows.Scan(dest...) 仍然按位置写入，不会按列名重排。

columns, err := rows.Columns()
if err != nil {
    return err
}

for rows.Next() {
    values := make([]any, len(columns))
    dest := make([]any, len(columns))

    for i := range values {
        // 每个目标地址固定指向同下标的值槽位，避免列名与数据错位。
        dest[i] = &values[i]
    }

    if err := rows.Scan(dest...); err != nil {
        return err
    }

    for i, column := range columns {
        // 列名只负责解释同下标的数据，不能改变 Scan 的位置语义。
        fmt.Printf("%s=%v\\n", column, values[i])
    }
}

if err := rows.Err(); err != nil {
    return err
}

这段写法的关键不在 any，而在两个切片长度完全一致，并且通过同一个下标建立了稳定关系。它适合列集合在运行时才确定的导出、通用查询和调试工具；如果业务字段固定，显式声明变量通常更容易维护。

代码对比：固定字段和动态字段怎样选择

不要把动态映射和“按名字写入结构体字段”混为一谈。后者需要应用层另外建立列名到字段地址的映射，还要处理重复列名、别名和大小写策略；Rows.Columns() 本身只提供当前结果集的名字顺序。

兼容边界：NULL、Close 和 Err 都要单独处理

NULL 不等于空字符串

如果数据库列可能为 NULL，固定结构可以使用 sql.NullString、sql.NullInt64 等带有 Valid 状态的类型。动态读取时，值槽位常见的是驱动返回的基础值或字节切片，不能把所有值都直接断言为字符串。

var nickname sql.NullString

// 目标类型要能表达 NULL，否则 Scan 可能因为无法转换而返回错误。
if err := rows.Scan(&nickname); err != nil {
    return err
}
if nickname.Valid {
    fmt.Println(nickname.String)
} else {
    fmt.Println("nickname is NULL")
}

Close 是资源边界，Err 是遍历结果边界

成功走完 Next 循环时，结果集通常会被隐式关闭，但仍建议在拿到 Rows 后立即 defer rows.Close()，这样提前返回、扫描失败或业务分支都能覆盖。循环结束后读取 rows.Err()，用于发现遍历过程中由驱动报告的错误；它和 Scan 当前行返回的错误不是同一个位置。

采用清单：把列名映射写成可审查的代码

1. 先确认查询返回的是单行还是多行；多行结果使用 Rows.Next 和 Rows.Scan。
2. 固定列优先显式写出目标地址，只有列集合不确定时才引入动态槽位。
3. 动态读取时保持 columns、values、dest 三个切片同长度、同下标。
4. 不要把列名当成自动映射规则；需要按名字写结构体时，另写明确的映射层。
5. 为可空列选择能表达 NULL 的目标类型，并处理 Scan 的转换错误。
6. 保留 defer rows.Close()，在循环后检查 rows.Err()。

常见问题

Rows.Columns 返回的列名能直接改变 Scan 的顺序吗？

不能。它只返回结果集元信息；Scan 的目标顺序仍由调用参数的位置决定。

列名和结构体字段名不同，database/sql 会自动匹配吗？

不会。需要在应用层根据列名建立字段地址映射，或者直接使用固定顺序的显式扫描。

动态读取时为什么要把指针放进 dest？

Scan 需要把值写入目标，因此 dest[i] 必须保存 values[i] 的地址，而不是保存值本身或列名字符串。

只检查 rows.Err 不检查 Scan 错误可以吗？

不可以。Scan 负责当前行到目标类型的转换，Rows.Err 负责遍历阶段错误，两者覆盖的边界不同。

总结

Rows.Columns() 解决的是“第几列叫什么”，Rows.Scan() 解决的是“第几列写入哪个目标”。固定结构使用显式变量，动态结构用列名切片解释同下标的值槽位；再补上 NULL、Close 和 Err 的边界处理，就能避免把列名匹配、位置扫描和资源释放混成一个问题。