Go ColumnType.ScanType 怎么为动态查询选择扫描类型

动态报表接口的 SQL 不是固定的：筛选条件变化会让列数变化，管理员还可能在配置里选择要返回的字段。此时把 string、int64 或 time.Time 写死在 rows.Scan 中，最先暴露的往往不是查询错误，而是“目标参数数量不匹配”或“不能把驱动值扫描进目标类型”。

解决办法是先调用 Rows.ColumnTypes() 获取每列的 *sql.ColumnType，再用 ColumnType.ScanType() 取得驱动认为适合 Rows.Scan 的 Go 类型，最后用 reflect.New 生成指针目标。要注意，ScanType 是扫描提示，不是 ORM 映射表；遇到可空列、驱动不提供类型信息或需要统一 JSON 输出时，还要单独决定兜底策略。

官方文档：https://pkg.go.dev/database/sql#ColumnType.ScanType

动态查询的故障是怎样出现的

一次典型场景是导出接口接收一段经过白名单筛选的列列表。开发者先用 rows.Columns() 得到列名，然后创建同样长度的 []any，但把所有元素都初始化成 new(string)。只要结果里出现数字、时间或驱动返回的二进制值，扫描就可能失败；即使扫描成功，统一转成字符串也会掩盖原始类型。

另一个常见修补是“每一列都用 new(any)”。它对动态导出很稳，因为 Rows.Scan 会把驱动提供的值放入空接口；但它放弃了驱动暴露的类型提示。真正需要的是先分清三个概念：

• 列名：Columns() 告诉你结果集有哪些名字。
• 数据库类型名：DatabaseTypeName() 是驱动报告的数据库侧类型名，可能为空。
• 扫描类型：ScanType() 返回适合传给 Rows.Scan 的 Go 类型，驱动不支持时会返回空接口类型。

所以问题的根因不是“反射太复杂”，而是把列名或数据库类型名直接当成了 Go 扫描目标。

ScanType 到底给了什么信息

ColumnType.ScanType() 的返回值是 reflect.Type。它描述的是“这个列可以尝试扫描进哪一种 Go 类型”，而不是说每一行的值一定都是这个类型，也不包含完整的业务语义。驱动可以不支持该属性；这时标准库约定返回空接口类型。

Rows.ColumnTypes() 返回的类型信息也可能因驱动而不完整。因此，动态读取器可以把 ScanType 当作首选提示，把 any 当作可预期的兜底，而不能根据一次驱动返回结果推断所有数据库都相同。

按 ScanType 创建动态扫描目标

最小实现可以分成两步：先为每列创建一个指针，再把这些指针作为可变参数传给 rows.Scan。扫描成功后，指针指向的值可以通过反射取出，和列名配成一条动态记录。

package dynamicrow

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

// scanOneRow 按驱动提供的 ScanType 创建目标，并把当前行组装成列名到值的映射。
// 调用方必须先执行 rows.Next，且 names 与 types 来自同一个结果集。
func scanOneRow(rows *sql.Rows, names []string, types []*sql.ColumnType) (map[string]any, error) {
	if len(names) != len(types) {
		return nil, fmt.Errorf("列名与列类型数量不一致: %d != %d", len(names), len(types))
	}

	dest := make([]any, len(types))
	for i, column := range types {
		scanType := column.ScanType()
		if scanType == nil {
			// 防御异常驱动，无法提供类型时退回空接口目标。
			dest[i] = new(any)
			continue
		}
		// reflect.New 返回 *T，正好满足 Rows.Scan 需要的指针参数。
		dest[i] = reflect.New(scanType).Interface()
	}

	if err := rows.Scan(dest...); err != nil {
		return nil, fmt.Errorf("动态扫描失败: %w", err)
	}

	row := make(map[string]any, len(dest))
	for i, target := range dest {
		value := reflect.ValueOf(target).Elem().Interface()
		row[names[i]] = value
	}
	return row, nil
}

这里的关键是 reflect.New(scanType)。例如驱动给出 reflect.TypeOf(int64(0))，代码就生成 *int64；给出 []byte 对应的类型，就生成相应的切片指针。Rows.Scan 的参数数量仍必须和结果列数完全一致，所以目标切片要以 ColumnTypes() 返回的长度为准。

把 ColumnTypes、Next 和错误处理连起来

只写一个“扫描当前行”的函数还不够。生产代码要保证列元数据、行游标和资源关闭处在同一条路径上。ColumnTypes() 失败时不能继续猜目标；Next() 返回 false 后，还要通过 rows.Err() 区分正常结束和迭代错误。

package dynamicrow

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

// ReadDynamicRows 读取未知列的结果集；它不假设具体数据库驱动或 ORM。
func ReadDynamicRows(ctx context.Context, db *sql.DB, query string) ([]map[string]any, error) {
	rows, err := db.QueryContext(ctx, query)
	if err != nil {
		return nil, fmt.Errorf("执行动态查询失败: %w", err)
	}
	defer rows.Close() // 任何提前返回都要释放结果集。

	names, err := rows.Columns()
	if err != nil {
		return nil, fmt.Errorf("读取列名失败: %w", err)
	}
	types, err := rows.ColumnTypes()
	if err != nil {
		return nil, fmt.Errorf("读取列类型失败: %w", err)
	}

	result := make([]map[string]any, 0)
	for rows.Next() {
		row, err := scanOneRow(rows, names, types)
		if err != nil {
			return nil, err
		}
		result = append(result, row)
	}
	if err := rows.Err(); err != nil {
		// Next 返回 false 可能是驱动在读取下一行时遇到错误。
		return nil, fmt.Errorf("遍历结果集失败: %w", err)
	}
	return result, nil
}

这个流程把三类失败分开了：查询本身失败、列元数据读取失败、行扫描或遍历失败。这样排查日志时，不会把“驱动没有提供类型信息”和“数据库连接中途断开”混成同一个问题。

可空列和驱动差异应该怎样兜底

ScanType 解决的是目标类型选择，不会自动替你解决 NULL 的业务语义。一个返回 int64 的列如果某行是 NULL，直接扫描到 *int64 通常不能表达“没有值”；这时要么使用 new(any) 保留 nil，要么根据固定 schema 选择 sql.NullInt64 等可空类型。

// chooseDestination 在通用导出和强类型读取之间做一个明确取舍。
func chooseDestination(column *sql.ColumnType) any {
	nullable, known := column.Nullable()
	if known && nullable {
		// 通用导出需要保留 NULL；空接口可以接收 nil 和驱动原始值。
		return new(any)
	}

	scanType := column.ScanType()
	if scanType == nil {
		// 驱动没有类型提示时，不要让 reflect.New 接收空类型。
		return new(any)
	}
	// 非空或未知可空性时，优先使用驱动建议的扫描类型。
	return reflect.New(scanType).Interface()
}

上面的策略适合“尽量保留原值”的动态导出，但它并不替代业务层的字段定义。若接口必须返回统一的日期格式、金额精度或 JSON 字符串，就应在扫描后做显式归一化；不要因为 ScanType 返回了某个类型，就把它当成最终 API 类型。

用一张决策表防止再次误用

还要注意 []byte 的生命周期和表现形式。扫描到 *[]byte 时，标准库会保存一份调用方可以长期持有的副本；如果选择 sql.RawBytes，则只能在下一次 Next、Scan 或 Close 前使用。动态 JSON 输出若直接放入 []byte，编码层还可能按字节切片的规则处理，因此是否转成字符串必须由接口契约决定。

结论：把 ScanType 当提示，不当契约

ColumnType.ScanType() 最适合解决“我不知道这一列该传什么指针给 Rows.Scan”的问题。标准流程是：获取列名和列类型、为每列创建扫描目标、逐行扫描、检查 rows.Err()，并在可空列和驱动信息缺失时明确退回 any 或可空类型。

如果查询结果是固定业务模型，直接使用结构体和明确字段仍然更可靠；只有在动态列、通用导出或工具型查询中，才值得引入反射。这样既利用了 ScanType 的价值，也不会把驱动提示误当成跨数据库、跨接口的类型契约。

相关问题

ScanType 返回的类型和 DatabaseTypeName 有什么区别？

DatabaseTypeName 描述驱动报告的数据库侧类型名，ScanType 描述适合传给 Rows.Scan 的 Go 类型。前者不应该直接拿来做 Go 反射，后者也不等于完整的业务映射规则。

为什么不把所有动态列都扫描到 string？

数字、时间、二进制和 NULL 的语义会被压扁，某些值还可能因为转换规则或精度要求产生扫描错误。只有接口明确要求文本化时，才在扫描后做显式格式化。

ColumnTypes 失败时能不能继续用 Columns 扫描？

可以选择把所有目标改成 new(any)，但这已经是兜底策略，不能继续假设有类型提示。对于强类型业务接口，更稳妥的做法是返回错误并修复驱动或查询路径。