Go database/sql ColumnType.ScanType 怎样支持动态查询导出

动态 SQL 导出最难的地方，不是把一行写成 CSV 或 JSON，而是查询列结构在编译期并不知道。Go 的 database/sql 可以先通过 Rows.ColumnTypes() 取得列元数据，再用每个 ColumnType 的 ScanType() 为 Rows.Scan 准备扫描目标。这样既能保留驱动提供的类型提示，又不必把导出器写死成某一张表。

实用结论是：把 ScanType() 当作“适合扫描的初始 Go 类型提示”，用 reflect.New 创建指针；驱动没有具体提示时回退到 any。扫描后再统一解引用、复制字节切片并保留 nil，就能得到相对稳定的通用导出值。

官方地址：https://pkg.go.dev/database/sql#ColumnType.ScanType

先分清 DatabaseTypeName、ScanType 与实际值

ColumnType 同时暴露列名、数据库类型名、可空性和扫描类型等信息，但它们的职责不同。Name() 适合生成表头；DatabaseTypeName() 适合记录数据库侧类型；Nullable() 可以辅助决定空值策略；真正用来准备 Rows.Scan 参数的是 ScanType()。

官方文档对 ScanType() 的定义是：返回适合使用 Rows.Scan 扫描的 Go 类型；如果驱动不支持这个属性，则返回空接口类型。因此，动态导出器应优先使用它，但仍要准备通用回退，不要看到某个数据库类型名就强行转换。

按 ColumnTypes 为每一列准备指针

Scan 需要的是可写目标，通常是指针，而 ScanType() 返回的是类型描述。两者之间可以用 reflect.New 连接：给定 int64 创建 *int64，给定 time.Time 创建 *time.Time。如果返回的是接口类型，则创建 *any 作为兜底。

package export

import (
    "database/sql"
    "reflect"
)

// newScanTargets 根据列元数据生成一组可写的 Scan 目标。
func newScanTargets(columnTypes []*sql.ColumnType) []any {
    targets := make([]any, len(columnTypes))
    for i, columnType := range columnTypes {
        scanType := columnType.ScanType()
        // 驱动没有具体提示时，让 database/sql 自己决定实际值类型。
        if scanType == nil || scanType.Kind() == reflect.Interface {
            var value any
            targets[i] = &value
            continue
        }
        // reflect.New 返回 *T，正好满足 Rows.Scan 的指针要求。
        targets[i] = reflect.New(scanType).Interface()
    }
    return targets
}

这里没有把 DatabaseTypeName() 写成一个很长的 switch。原因是数据库类型名属于驱动和数据库系统的命名空间，而 ScanType() 才是当前驱动对扫描入口给出的提示。导出器可以记录两者，但扫描目标应以实际驱动提供的类型为先。

扫描一行并转换为稳定的导出值

扫描目标的生命周期和最终导出值不同。目标是指针，方便 Scan 写入；导出器通常更希望得到普通值。转换时要递归解开指针和接口，空指针变成 nil，而字节切片需要复制，避免后续读取覆盖当前行的数据。

package export

import (
    "database/sql"
    "reflect"
)

var rawBytesType = reflect.TypeOf(sql.RawBytes{})

// stableValue 把 Scan 目标转换为可交给 CSV 或 JSON 编码器的值。
func stableValue(target any) any {
    if target == nil {
        return nil
    }
    value := reflect.ValueOf(target)
    // 兼容 *T、*any 以及接口中再包一层的情况。
    for value.Kind() == reflect.Pointer || value.Kind() == reflect.Interface {
        if value.IsNil() {
            return nil
        }
        value = value.Elem()
    }
    if !value.IsValid() {
        return nil
    }
    // RawBytes 可能指向驱动复用的缓冲区，导出前复制出独立切片。
    if value.Type() == rawBytesType {
        return append([]byte(nil), value.Bytes()...)
    }
    return value.Interface()
}

如果驱动返回的是 sql.RawBytes，它只在下一次调用 Next 前有效；直接把它保存到结果集合，可能在读取下一行后看到已变化的内容。复制操作会多一次分配，但对于需要把整批结果交给编码器或异步写入器的导出流程，这是清晰的所有权边界。

为动态导出收紧边界

ScanType() 解决的是“应该先分配什么扫描目标”，并不保证每个驱动、每个数据库列和每个业务格式都给出相同的 Go 类型。尤其要留意下面几种情况：

• 驱动提示不完整：返回接口类型时，不要继续调用 reflect.New 去构造一个不可用的具体对象，直接使用 *any 更稳妥。
• NULL：可空列不应一律扫描到 string 或数值指针。保留 nil，再由 CSV 或 JSON 层决定空字段表示。
• 时间和数值：保留驱动提供的 time.Time、整数或浮点值，格式化应放在导出层，避免扫描阶段损失信息。
• 列结构变化：ColumnTypes() 描述的是当前 Rows 的列。查询、分页或多结果集切换后，不能盲目复用上一组目标。

工程上可以把“扫描值”和“展示值”分开：前者尽量忠实保留驱动结果，后者根据 CSV、JSON、Excel 或接口响应的规则格式化。这样数据库驱动变化时，影响范围会小很多。

用最小骨架串起完整流程

下面的骨架只演示动态列导出的核心控制流，不绑定某个数据库驱动。它先取列名和列类型，再逐行创建目标、扫描、稳定化，最后检查迭代错误并释放资源。

package export

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

// ReadDynamicRows 读取未知列结构的结果，返回列名与通用行值。
func ReadDynamicRows(ctx context.Context, db *sql.DB, query string, args ...any) ([]string, [][]any, error) {
    rows, err := db.QueryContext(ctx, query, args...)
    if err != nil {
        return nil, nil, fmt.Errorf("query dynamic rows: %w", err)
    }
    defer rows.Close() // 查询失败或中途返回时，都要释放 Rows。

    columnTypes, err := rows.ColumnTypes()
    if err != nil {
        return nil, nil, fmt.Errorf("read column types: %w", err)
    }
    names := make([]string, len(columnTypes))
    for i, columnType := range columnTypes {
        names[i] = columnType.Name()
    }

    result := make([][]any, 0)
    for rows.Next() {
        targets := newScanTargets(columnTypes)
        if err := rows.Scan(targets...); err != nil {
            return nil, nil, fmt.Errorf("scan dynamic row: %w", err)
        }
        row := make([]any, len(targets))
        for i, target := range targets {
            row[i] = stableValue(target)
        }
        result = append(result, row)
    }
    if err := rows.Err(); err != nil {
        return nil, nil, fmt.Errorf("iterate dynamic rows: %w", err)
    }
    return names, result, nil
}

这个流程的关键不是反射本身，而是把职责拆开：ColumnTypes 负责描述当前结果，newScanTargets 负责准备写入位置，stableValue 负责所有权和 NULL 边界，最后的编码器只处理已经稳定的通用值。

常见问题

ScanType 和 DatabaseTypeName 是一回事吗？

不是。前者返回适合 Go Rows.Scan 的 reflect.Type，后者返回数据库系统侧的类型名。导出器可以同时记录它们，但准备扫描目标时应优先看 ScanType。

ScanType 返回接口类型时应该怎么办？

把目标设置为 *any，让驱动把实际值写入接口，再在稳定化阶段根据实际值处理。不要为了得到“看起来具体”的类型而硬编码一套跨驱动映射。

为什么不能直接保存 RawBytes？

sql.RawBytes 可能引用驱动复用的内存，下一次 Next 后内容就可能变化。需要跨行保存或异步导出时，应复制成独立的 []byte。

动态导出还需要 ORM 模型吗？

不需要。本文的目标是把未知列转换为通用行值；ORM 模型生成属于另一条边界，涉及字段命名、业务类型和写回策略，不应与扫描目标选择混在一起。

相关文档：https://pkg.go.dev/database/sql#ColumnType.ScanType