Scan 读取 NULL 到 string 失败的处理方式

使用 Go 的 database/sql 查询可空列时，如果直接把结果扫描到 string，遇到 SQL NULL 就可能返回类似“converting NULL to string is unsupported”的错误。根因不是字符串编码问题，而是数据库驱动把 NULL 交给 database/sql 后表示为 nil，普通 string 没有“无值”状态。

最稳妥的处理是让 Go 目标值也保留可空语义：使用 sql.NullString，或在 Go 1.22 及更新版本使用 sql.Null[string]。只有当业务明确规定 NULL 和空字符串等价时，才在 SQL 中用默认值折叠它们。

官方资料：https://pkg.go.dev/database/sql

先确认报错确实由 NULL 触发

值班时先看完整错误和字段定义，不要一看到 Scan 失败就把所有目标字段改成字符串。database/sql.Scanner 接口明确把 nil 作为 NULL 的来源值；因此下面三件事要同时对上：

• 查询结果中的目标列允许为 NULL，或者是外连接产生的 NULL。
• 扫描目标是 *string、*int 等不表示缺失值的普通指针。
• 错误发生在 Scan，而不是查询、连接或 SQL 语法阶段。

可以先把问题缩小到一列，确认 SQL 逻辑是否改变了 NULL 的来源。下面的查询只是排查示例，表名和列名需要替换成实际对象。

-- 用聚合统计可空列的 NULL 数量，确认问题是不是数据分布导致的
SELECT
    COUNT(*) AS total_rows,
    SUM(CASE WHEN nickname IS NULL THEN 1 ELSE 0 END) AS null_rows
FROM users;

如果 null_rows 大于 0，再检查是否有 LEFT JOIN。右表没有匹配行时，即使右表原始列定义为 NOT NULL，连接结果仍可能把它呈现为 NULL。

先决定 NULL 是否有业务含义

修复前要先回答一个问题：接口或领域对象是否需要区分“没有填写”和“填写了空字符串”。例如用户从未设置昵称，通常与用户主动设置为空文本不是一回事；如果报表只需要展示一个可选备注，二者可能都可以展示为 —。

不要为了消除一条告警就直接使用 COALESCE(nickname, '')。它会改变查询输出的语义，后续代码无法再判断原始记录究竟是 NULL 还是空字符串。

优先用 sql.NullString 读取可空文本

sql.NullString 是标准库提供的扫描目标，包含 String 和 Valid 两个字段。Valid 为 false 时表示源值是 NULL；为 true 时，String 才代表有效文本。

package main

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

type User struct {
	ID       int64
	Nickname *string
}

func loadUser(ctx context.Context, db *sql.DB, id int64) (User, error) {
	var (
		user     User
		nickname sql.NullString
	)

	// 让数据库 NULL 先进入带 Valid 状态的目标值，而不是直接写入 string。
	err := db.QueryRowContext(ctx,
		"SELECT id, nickname FROM users WHERE id = ?", id,
	).Scan(&user.ID, &nickname)
	if err != nil {
		// 查询错误继续向上返回，避免把连接或数据错误误判成空昵称。
		return User{}, fmt.Errorf("load user %d: %w", id, err)
	}

	if nickname.Valid {
		// 只有源值不是 NULL 时，领域对象才创建字符串指针。
		value := nickname.String
		user.Nickname = &value
	}
	return user, nil
}

这个写法把数据库层的可空类型转换成了领域对象的可选字段。调用方可以通过 Nickname == nil 判断没有值，而不是依赖某个特殊空字符串。

Go 1.22 及更新版本可使用泛型 Null

如果项目的 Go 版本已经支持标准库泛型 sql.Null[T]，可以用同一套结构表达字符串、整数等可空值。它仍然保留 Valid，所以并不会把 NULL 自动变成空字符串。

func loadNickname(ctx context.Context, db *sql.DB, id int64) (string, bool, error) {
	var nickname sql.Null[string]

	// 泛型 Null 仍然需要传地址，让 Scan 写入 V 和 Valid。
	err := db.QueryRowContext(ctx,
		"SELECT nickname FROM users WHERE id = ?", id,
	).Scan(&nickname)
	if err != nil {
		// 保留原始数据库错误，便于区分未找到、连接失败和字段转换失败。
		return "", false, fmt.Errorf("scan nickname: %w", err)
	}

	// bool 直接表达 NULL 是否存在，调用方无需猜测空字符串含义。
	return nickname.V, nickname.Valid, nil
}

如果项目还要兼容较早的 Go 版本，继续使用 sql.NullString 更稳妥。不要为了追求新写法而改变项目的最低 Go 版本。

只有语义允许时才用 COALESCE

当报表或展示接口明确规定“NULL 就按空文本处理”，可以在查询层折叠值。这个选择应该写进查询注释或数据契约，而不是作为通用的 Scan 修复。

-- 仅当业务把 NULL 和空字符串视为同一个展示结果时才折叠
SELECT
    id,
    COALESCE(nickname, '') AS nickname
FROM users
WHERE id = ?;

使用该方案后，目标可以是普通 string，但要注意：它只解决这条查询的输出。其它查询、写入路径和接口更新逻辑仍然可能看到 NULL，不能把它当成数据库字段已经变为非空。

回滚路径和告警确认

如果这是线上热修复，建议先采用只改 Go 映射的方案，因为它不改变数据库数据。回滚时恢复原来的扫描字段即可，不需要执行数据迁移。只有在确认全局数据契约允许非空后，才考虑修改表结构或批量回填。

处理后按下面顺序复查：

1. 用一条确实包含 NULL 的记录运行查询，确认 Scan 不再报转换错误。
2. 用一条包含空字符串的记录运行查询，确认它与 NULL 的分支没有被意外合并。
3. 遍历多行结果时检查 rows.Err()，避免只检查每次 Scan 而漏掉游标阶段错误。
4. 观察原错误告警是否停止，同时确认没有新增“默认值覆盖真实缺失”的业务指标。

func readUsers(ctx context.Context, db *sql.DB) error {
	rows, err := db.QueryContext(ctx, "SELECT id, nickname FROM users")
	if err != nil {
		// 查询未建立时直接返回，不进入遍历逻辑。
		return fmt.Errorf("query users: %w", err)
	}
	defer rows.Close() // 及时释放结果集，避免连接长期被占用。

	for rows.Next() {
		var (
			id       int64
			nickname sql.NullString
		)
		// 每行都用可空目标接收 nickname，避免某一行的 NULL 中断处理。
		if err := rows.Scan(&id, &nickname); err != nil {
			return fmt.Errorf("scan user %d: %w", id, err)
		}
	}
	if err := rows.Err(); err != nil {
		// Next 返回 false 还可能是迭代过程发生了驱动错误。
		return fmt.Errorf("iterate users: %w", err)
	}
	return nil
}

复盘时重点看这几个误区

• 把 NULL 当成空字符串。这会让“未设置”和“设置为空”无法区分，接口更新时尤其容易误覆盖。
• 只修改一处 Scan。同一张表可能有列表、详情、导出三条查询链路，要按字段语义统一映射。
• 把数据库迁移当成第一选择。如果旧数据确实允许缺失，直接改成 NOT NULL 可能让写入或迁移失败。
• 忽略外连接。右表本身的非空约束不能阻止未匹配行在连接结果中出现 NULL。

排障结论可以简单归纳为：SQL NULL 是一种状态，普通 string 不是它的容器。先用 sql.NullString 或 sql.Null[string] 保留状态，再根据接口和展示契约决定是否映射成指针或默认文本。

相关问题

为什么把目标改成 *string 也不能直接解决？

*string 表示 Go 指针可以为空，但 database/sql 的扫描转换仍要把驱动给出的 NULL 安全地写入目标。直接把它当成通用转换方案不如使用实现了 Scanner 的可空类型明确，具体行为也要看驱动和目标类型。

空字符串和 NULL 哪个更适合 API 返回？

如果客户端需要知道字段是否填写过，返回可选字段或显式状态；如果只是文本展示且契约规定缺失显示为空，才返回空字符串。关键是让数据库、领域对象和 JSON 契约保持同一语义。

能不能在数据库里统一把字段改成 NOT NULL？

可以，但要先盘点旧数据、写入端和外连接查询，完成回填后再迁移。它是数据契约变更，不是单纯的 Scan 报错修复。