Go sql.Rows.ColumnTypes 怎么读取查询结果字段类型

做动态报表、通用 SQL 控制台或 CSV 导出时，查询语句往往不是提前写死的，程序只有拿到 *sql.Rows 后才知道返回了哪些列。此时最直接的办法，是在结果集关闭前调用 rows.ColumnTypes()：它会按结果列顺序返回一组 *sql.ColumnType，可继续读取列名、数据库类型名、建议扫描类型，以及驱动愿意提供的长度、精度和可空性。

我通常把它当作“结果集元数据”接口，而不是“表结构反射”接口。两者看起来相近，但边界完全不同：ColumnTypes 描述的是这次查询最终返回的列，能自然处理别名和表达式；主键、默认值、索引、约束等表结构信息则应查询数据库目录。官方 API 说明可见 https://pkg.go.dev/database/sql。

使用场景：查询列无法在编译期确定

假设后台允许用户选择字段，最终 SQL 可能返回 id、order_total、note，也可能多出一个聚合表达式。静态结构体不再适合所有结果，程序却仍要生成表头、格式化数字、决定空值展示方式。只调用 Rows.Columns 能拿到表头，却拿不到类型线索；直接扫描一行再观察实际值，又会把“这一行碰巧是什么值”误当成列定义。

ColumnTypes 正好填补这层空白。它返回的信息与结果列一一对齐，最适合以下任务：

• 动态 CSV、Excel 或 JSON 导出；
• 通用 SQL 查询工具和数据预览；
• 根据精度、长度或类型名选择显示格式；
• 生成只针对本次查询结果的数据字典；
• 在不绑定固定结构体的情况下建立通用扫描目标。

它不保证每个驱动都返回全部信息。尤其是 Length、DecimalSize、Nullable，必须检查第二个返回值 ok。ok=false 的含义是“当前驱动没有提供或该属性不适用”，不是长度为 0、不可空或精度为 0。

最小可运行示例：先查询，再读取 ColumnTypes

下面示例使用标准库接口，数据库驱动和连接初始化按项目实际情况补充。占位符语法也依赖驱动：MySQL、SQLite 常见 ?，PostgreSQL 常见 $1，不能机械照搬。

package main

import (
    "context"
    "database/sql"
    "fmt"
    "time"
)

func inspectQuery(ctx context.Context, db *sql.DB, since time.Time) error {
    rows, err := db.QueryContext(ctx, `
        SELECT id, total AS order_total, note
        FROM orders
        WHERE created_at >= ?
    `, since)
    if err != nil {
        return fmt.Errorf("执行查询: %w", err)
    }
    // Rows 持有连接与游标，完成后必须关闭。
    defer rows.Close()

    columnTypes, err := rows.ColumnTypes()
    if err != nil {
        return fmt.Errorf("读取字段类型: %w", err)
    }

    for i, columnType := range columnTypes {
        // Name 是结果列名称，因此别名 order_total 会在这里出现。
        fmt.Printf("[%d] name=%s dbType=%s scanType=%v\n",
            i,
            columnType.Name(),
            columnType.DatabaseTypeName(),
            columnType.ScanType(),
        )

        // 可选属性必须根据 ok 判断是否真的可用。
        if length, ok := columnType.Length(); ok {
            fmt.Printf("  length=%d\n", length)
        }
        if precision, scale, ok := columnType.DecimalSize(); ok {
            fmt.Printf("  precision=%d scale=%d\n", precision, scale)
        }
        if nullable, ok := columnType.Nullable(); ok {
            fmt.Printf("  nullable=%t\n", nullable)
        }
    }

    for rows.Next() {
        // 这里只演示元数据读取，实际项目应在此扫描当前行。
    }
    // Next 结束后再检查游标迭代期间出现的错误。
    if err := rows.Err(); err != nil {
        return fmt.Errorf("遍历查询结果: %w", err)
    }
    return nil
}

调用时机有两个要点。第一，必须在查询成功并拿到 rows 之后；第二，必须在 rows 关闭之前。ColumnTypes 返回的切片顺序与 SQL 结果列顺序一致，这一点比类型名本身更重要，因为后续动态扫描和表头输出都依赖同一个下标。

ColumnType 的六类信息应该怎样理解

DatabaseTypeName 常用于展示、日志或粗粒度分组，但不适合直接写成跨数据库业务判断。例如，同类整数在不同数据库和驱动中可能返回 INTEGER、INT、INT4 或 BIGINT。如果程序需要精确识别，应该先按所支持的数据库建立归一化映射，并为未知值保留兜底。

ScanType 返回 reflect.Type。它表示驱动认为“扫描到哪类 Go 值通常合适”，并不承诺 NULL、用户自定义类型和所有表达式都能无条件扫描进该类型。驱动无法给出更具体信息时，也可能退化为 interface{} 对应的类型。因此，我更愿意把它作为动态扫描策略的提示，而不是静态模式的权威来源。

把可选信息整理成稳定的应用结构

直接在业务代码里反复调用六个方法容易漏掉 ok。更稳妥的做法是先转成自己的元数据结构，用指针明确区分“值为零”和“信息未知”。

package metadata

import (
    "database/sql"
    "fmt"
)

type ColumnMeta struct {
    Name         string  `json:"name"`
    DatabaseType string  `json:"database_type"`
    ScanType     string  `json:"scan_type"`
    Length       *int64  `json:"length,omitempty"`
    Precision    *int64  `json:"precision,omitempty"`
    Scale        *int64  `json:"scale,omitempty"`
    Nullable     *bool   `json:"nullable,omitempty"`
}

func valuePtr[T any](value T) *T {
    // 返回独立地址，避免用零值表达“不知道”。
    return &value
}

func ReadColumnMeta(rows *sql.Rows) ([]ColumnMeta, error) {
    columnTypes, err := rows.ColumnTypes()
    if err != nil {
        return nil, fmt.Errorf("读取字段元数据: %w", err)
    }

    result := make([]ColumnMeta, 0, len(columnTypes))
    for _, columnType := range columnTypes {
        meta := ColumnMeta{
            Name:         columnType.Name(),
            DatabaseType: columnType.DatabaseTypeName(),
        }

        // ScanType 在不支持时可能退化为 interface{}，仍保留作提示。
        if scanType := columnType.ScanType(); scanType != nil {
            meta.ScanType = scanType.String()
        }
        if length, ok := columnType.Length(); ok {
            meta.Length = valuePtr(length)
        }
        if precision, scale, ok := columnType.DecimalSize(); ok {
            meta.Precision = valuePtr(precision)
            meta.Scale = valuePtr(scale)
        }
        if nullable, ok := columnType.Nullable(); ok {
            meta.Nullable = valuePtr(nullable)
        }
        result = append(result, meta)
    }
    return result, nil
}

这里没有把 DatabaseTypeName 转成枚举，是刻意保留驱动原始信息。通用层先忠实记录，数据库适配层再做归一化，能够避免在底层工具里埋入某一种数据库的假设。

候选方案对比：Columns、ColumnTypes、目录查询还是实际值

我在项目中常见到四种方案，它们不是互相替代，而是回答不同问题。

1. Rows.Columns：只要列名时最简单

rows.Columns() 返回结果列名称。它足够轻量、通用，非常适合只生成表头的场景。如果还要判断数字精度、数据库类型或可空性，它提供的信息就不够了。

2. Rows.ColumnTypes：动态结果元数据的默认选择

它直接描述当前结果集，别名、表达式、联表后的列顺序都跟查询结果一致。对于动态导出、预览和 SQL 工具，这是我优先选择的方案。代价是元数据丰富度受驱动支持程度影响，业务必须接受某些属性未知。

3. 查询 information_schema 或系统目录：需要真实表结构

如果目标是读取主键、默认值、索引、生成列、约束或完整字段定义，应查询数据库目录。它的信息更接近持久化模式，但 SQL 与字段含义高度依赖数据库；而且任意查询中的表达式、聚合列和别名，不一定能直接映射回某张表的一列。

4. Scan 到 any：观察当前行实际返回值

把值扫描到 any 可以看到驱动对这一行返回的具体 Go 类型，例如 int64、[]byte 或 time.Time。但它受当前值影响：NULL 行只告诉你值为空，不能说明声明类型；某些驱动还会把文本或数字统一返回为字节切片。这适合数据处理，不适合单独承担模式识别。

推荐实现：元数据与动态值按同一列序绑定

通用查询组件通常既要列信息，也要每行数据。可以先读取元数据，再建立 values 和 destinations 两个等长切片。destinations[i] 指向 values[i]，扫描后便能用同一个下标关联 metas[i]。

func readDynamicRows(rows *sql.Rows) error {
    metas, err := ReadColumnMeta(rows)
    if err != nil {
        return err
    }

    values := make([]any, len(metas))
    destinations := make([]any, len(metas))
    for i := range values {
        // Scan 需要接收地址，因此每个目标都指向对应的 values 元素。
        destinations[i] = &values[i]
    }

    for rows.Next() {
        if err := rows.Scan(destinations...); err != nil {
            return fmt.Errorf("扫描当前行: %w", err)
        }

        for i, value := range values {
            // metas[i] 与 value 始终对应同一结果列。
            fmt.Printf("%s (%s) = %v\n",
                metas[i].Name,
                metas[i].DatabaseType,
                value,
            )
        }
    }

    // 行遍历结束不等于成功，仍要读取延迟错误。
    if err := rows.Err(); err != nil {
        return fmt.Errorf("遍历动态结果: %w", err)
    }
    return nil
}

这个版本刻意没有根据 ScanType 动态创建强类型指针。扫描到 any 更容易兼容 NULL 和驱动差异，适合通用工具。若业务确定只支持一个驱动并需要减少后续转换，可以用 reflect.New(columnType.ScanType()) 创建目标，但仍要为 NULL、未知类型和驱动特例准备回退路径。

驱动差异与常见误区

把 ok=false 当成属性为 false

这是最危险也最常见的错误。nullable, ok := ct.Nullable() 中，ok=false 表示“不知道”，不能据此拒绝 NULL。类似地，Length 和 DecimalSize 不可用时也不能填 0，因为 0 可能是一个真实值。应用结构中使用指针或显式的 Known 字段更可靠。

把 DatabaseTypeName 当成跨库标准枚举

数据库类型名来自驱动。若用字符串判断格式，应先进行大写化和受控映射，并记录未识别类型。不要因为一个驱动返回 INT64，就假设另一个驱动也会如此。

把 ScanType 当成业务字段类型

ScanType 解决的是“用什么 Go 目标承接驱动值更合适”，而不是“领域对象应该是什么类型”。金额字段的业务模型可能需要定点十进制库，数据库驱动却可能建议字符串或字节切片；时间字段也可能受连接参数影响。领域转换仍应在扫描之后明确完成。

忘记处理 SQL 表达式和别名

COUNT(*)、CASE、函数调用与联表别名都会产生结果列。Name 面向查询结果，因此可能是数据库生成的名称，也可能是显式别名。需要稳定表头时，SQL 应主动写 AS，不要依赖数据库自动命名表达式。

在 Rows 关闭后读取元数据

Rows 关闭后，再调用依赖结果集的方法可能报错。把“读取元数据—遍历数据—检查 Err—关闭资源”放在同一个函数作用域内，通常最不容易出错。

不适用情况

以下任务不建议只依赖 ColumnTypes：

• 要判断主键、唯一约束、外键、索引、默认值或生成表达式；
• 要生成数据库迁移脚本或对比完整表结构；
• 要证明某一列来自哪张物理表；
• 必须获得跨驱动完全一致的类型分类，却没有数据库适配层；
• 查询结果已经映射到固定领域结构，额外读取动态元数据没有收益。

这些场景应改用数据库目录、ORM 模式描述或项目自有的数据字典。ColumnTypes 的优势是紧贴当前结果集，不是替代所有模式管理工具。

落地检查清单

1. 在 QueryContext 成功后、Rows 关闭前调用 ColumnTypes。
2. 把返回切片顺序作为列与值对应关系的基准。
3. 对 Length、DecimalSize、Nullable 检查 ok。
4. 把未知属性保存成未知，不用零值伪装。
5. 不要把 DatabaseTypeName 当成跨数据库统一枚举。
6. 不要把 ScanType 当成最终领域类型。
7. 动态扫描时让元数据、目标切片和值切片保持相同长度与顺序。
8. 用 defer rows.Close() 释放资源，并在循环后检查 rows.Err()。

常见问题

ColumnTypes 会不会执行额外查询？

标准库只定义返回结果列信息的接口，具体信息如何获得由驱动实现。应用不应依赖某种内部机制；如果性能敏感，应针对实际驱动与查询做基准测试，而不是凭接口名称猜测开销。

为什么 DatabaseTypeName 是空字符串？

驱动可能不支持该信息，或者当前表达式没有可稳定暴露的数据库类型名。程序应提供“未知类型”回退，而不是把空字符串当成错误或某个固定类型。

能否只调用 ColumnTypes，不遍历 rows？

可以在拿到结果集后先读取元数据。如果业务只需要元数据，也仍应关闭 Rows。如果继续读取数据，则按正常流程调用 Next、Scan 并检查 Err。

Columns 和 ColumnTypes 的列顺序是否一致？

它们都面向当前结果集，顺序对应查询返回列。实际代码中通常任选一个作为列名来源；需要类型信息时直接使用 ColumnTypes 的 Name，避免维护两份可错位的数据。

总结来说，读取查询结果字段类型时，先用 Rows.ColumnTypes 获取按列排列的元数据，再把驱动可选信息按“已知/未知”保存。动态导出和通用查询工具优先使用它；完整表结构则交给数据库目录。把这条边界守住，代码既能利用驱动提供的信息，也不会在驱动没有提供信息时做出错误推断。