Go sql.Scan NULL 到字符串失败的字段适配

Go 里把数据库可空字段直接扫描到 string，遇到 SQL NULL 时会失败，常见错误是 converting NULL to string is unsupported。处理重点不是把错误吞掉，而是先决定业务是否需要区分“没有值”和“值为空字符串”。需要保留这个区别时使用 sql.NullString 或 sql.Null[string]；不需要区别时，才在 SQL 查询层或应用层统一给出默认值。

官方文档地址：https://pkg.go.dev/database/sql

先从错误信息定位字段适配边界

database/sql 的扫描过程会根据数据库驱动返回的值适配目标指针。普通文本可以进入 *string，但 nil 没有字符串内容，Go 不会替你猜它应该变成空串、缺省文案还是一个缺失状态。因此下面这种写法在字段可能为 NULL 时不可靠：

// 直接扫描只适用于数据库列保证 NOT NULL 的场景。
var nickname string
err := db.QueryRowContext(ctx,
    "SELECT nickname FROM users WHERE id = ?", userID,
).Scan(&nickname)
if err != nil {
    // 这里要保留原始错误，便于定位具体列和输入状态。
    return fmt.Errorf("读取用户昵称失败: %w", err)
}

如果错误发生在 Scan，而 SQL 能正常执行，优先检查列约束、左连接结果和聚合表达式。尤其是 LEFT JOIN 未匹配时，右表字段天然可能变成 NULL。

用 sql.NullString 保留 NULL 与空字符串的区别

最稳妥的修复是让扫描目标显式表达可空性。sql.NullString 实现了 Scanner，扫描 NULL 时把 Valid 设为 false；扫描普通文本时再读取 String。这样不会把两个业务状态悄悄合并。

// NullString 同时承载文本内容和“是否有值”的状态。
var nickname sql.NullString
err := db.QueryRowContext(ctx,
    "SELECT nickname FROM users WHERE id = ?", userID,
).Scan(&nickname)
if err != nil {
    return fmt.Errorf("扫描 nickname 失败: %w", err)
}

displayName := "未设置"
if nickname.Valid {
    // Valid=true 时，String 可能是空串，仍不要把它当成 NULL。
    displayName = nickname.String
}
fmt.Println(displayName)

如果项目使用 Go 1.22 或更高版本，也可以写成 sql.Null[string]，把可空类型直接放进领域结构体：

// 泛型 Null 保留同样的 Valid 语义，适合统一封装可空字段。
var nickname sql.Null[string]
if err := row.Scan(&nickname); err != nil {
    return fmt.Errorf("扫描 nickname 失败: %w", err)
}
if nickname.Valid {
    fmt.Println(nickname.V)
} else {
    fmt.Println("未设置")
}

默认值应该放在 SQL 还是 Go 代码里

两种方案都能避免扫描失败，但语义不同。查询结果只服务于列表展示、报表或导出，并且下游不需要知道 NULL 是否存在，可以在 SQL 中使用 COALESCE；领域对象还要参与更新、审计或权限判断时，建议保留 Valid，在展示层再决定文案。

// 只有业务确认 NULL 与空串等价时，才在 SQL 层归一化。
const query = `
    SELECT COALESCE(nickname, '')
    FROM users
    WHERE id = ?
`
var nickname string
if err := db.QueryRowContext(ctx, query, userID).Scan(&nickname); err != nil {
    return fmt.Errorf("读取展示昵称失败: %w", err)
}

不要为了让页面显示正常，就把所有可空列都改成 COALESCE。一旦后续流程需要判断“用户从未填写”，这个信息已经在查询阶段丢失。

用三种输入做扫描回归检查

修复后至少覆盖 NULL、空字符串和普通文本。三者都能成功扫描，但业务结果应不同。检查清单可以固定在数据访问层测试中：

• 列值为 NULL：扫描成功，Valid=false。
• 列值为 ''：扫描成功，Valid=true 且内容为空。
• 列值为普通文本：扫描成功，Valid=true 且内容保持原值。
• 写回数据库：Valid=false 应写回 NULL，而不是意外写入空串。

最终的字段适配原则很简单：数据库允许 NULL，就让 Go 类型显式承认它；业务要默认值，再在靠近业务决策的位置处理。这样既能消除 sql.Scan 的运行时失败，也不会为了方便展示而损失数据含义。

相关问题

sql.NullString 的 String 为空时代表 NULL 吗？

不一定。必须先看 Valid；Valid=true 且 String="" 表示数据库保存的是空字符串。

可以把 NULL 直接扫描到 *string 指针吗？

可以考虑使用 *string 这类可为 nil 的目标，但团队封装和结构体序列化更容易统一时，sql.NullString 的状态字段通常更清楚。

Go 1.22 之前怎么写？

使用 sql.NullString、sql.NullInt64 等专用类型；不要为了使用泛型 Null 而强行提高旧项目的最低 Go 版本。