Go sql.NullString 扫描 NULL 后如何避免空字符串混淆

遇到这个问题，关键不是把空字符串再处理一遍，而是同时读取 sql.NullString.String 和 sql.NullString.Valid。数据库返回 NULL 时，String 会被设为空字符串、Valid 为 false；数据库返回真实的 '' 时，两个字段分别是空字符串和 true。因此只判断 String == "" 必然丢失语义。

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

先看懂 sql.NullString 的两个状态

NullString 是 database/sql 提供的可空字符串扫描目标，包含 String 和 Valid。官方实现的 Scan 在收到 nil 时会把字符串清空并将 Valid 设为 false；收到其他可转换值时才标记为有效。

这也是直接扫描到 string 容易出错的地方：普通字符串没有第三个状态，驱动返回 NULL 时通常会得到类似“converting NULL to string is unsupported”的转换错误。可空列就应该把可空性保留到扫描目标里。

扫描后先判断 Valid，再做领域映射

下面的例子假设 profiles.nickname 允许 NULL。示例用一个单独的映射函数把数据库状态转换成接口需要的三个结果：未设置、空文本和具体昵称。注释保留在代码中，便于直接改成项目里的查询。

package profile

import (
    "context"
    "database/sql"
)

type Profile struct {
    ID       int64
    Nickname sql.NullString
}

type NicknameView struct {
    Value  string
    Set    bool
    Empty  bool
}

func loadProfile(ctx context.Context, db *sql.DB, id int64) (NicknameView, error) {
    var nickname sql.NullString
    // 让数据库 NULL 进入 NullString，而不是强行转换成普通 string。
    err := db.QueryRowContext(ctx,
        "SELECT nickname FROM profiles WHERE id = ?", id,
    ).Scan(&nickname)
    if err != nil {
        // 查询、无行和类型转换错误都交给调用方处理，不能静默吞掉。
        return NicknameView{}, err
    }

    if !nickname.Valid {
        // NULL 与空字符串都可能让 String 等于 ""，这里必须先看 Valid。
        return NicknameView{Set: false}, nil
    }
    if nickname.String == "" {
        // Valid=true 且内容为空，说明数据库里是明确的空字符串。
        return NicknameView{Set: true, Empty: true}, nil
    }
    return NicknameView{Value: nickname.String, Set: true}, nil
}

这里的 Set 和 Empty 只是示例领域字段，项目也可以改成 *string、枚举或带状态的响应对象。重要的是映射层不要在第一步就把 NullString 转成普通字符串，否则后面无法恢复 NULL 信息。

写回时不要让默认值覆盖 NULL

更新接口常见的 bug 是：读取时正确区分了 NULL，写回时却直接传 nickname.String，结果把 NULL 变成了空字符串。NullString 实现了 driver.Valuer，当 Valid=false 时，Value 返回 nil；当 Valid=true 时才返回字符串。

func updateNickname(ctx context.Context, db *sql.DB, id int64, value *string) error {
    var nickname sql.NullString
    // nil 表示调用方要求清除昵称，写回数据库 NULL。
    if value != nil {
        nickname = sql.NullString{String: *value, Valid: true}
    }

    _, err := db.ExecContext(ctx,
        "UPDATE profiles SET nickname = ? WHERE id = ?",
        nickname, id, // Valuer 会根据 Valid 选择 NULL 或文本。
    )
    return err
}

如果业务规定“空字符串也代表清除”，可以在构造 NullString 前显式归一化；但这应是产品规则，而不是因为误把 NULL 和空字符串当成一回事。读接口与写接口最好共用同一套状态约定。

四项排查清单：为什么结果看起来仍然混淆

1. 看 Scan 错误：不要只打印结构体。先判断 err，否则查询失败时的零值可能被误认为 NULL。
2. 检查行循环：每次 rows.Scan 都应覆盖同一个 NullString；不要在错误分支继续使用上一行的数据。
3. 检查 JSON 边界：直接序列化 sql.NullString 会暴露内部字段，接口层应定义自己的响应类型，明确 NULL 的输出约定。
4. 检查 SQL 表达式：COALESCE(nickname, '') 会在数据库侧主动抹掉 NULL。只有确认业务不需要区分时才使用它。

反向验证可以准备三行数据：NULL、空字符串和普通文本，逐行检查 Valid 与 String。预期结果必须与上表一致；如果三行都变成空字符串，问题通常发生在 SQL 的 COALESCE、扫描目标类型或领域映射层。

常见问题

sql.NullString.Valid 为 false 时 String 一定是空字符串吗？

标准库的 Scan(nil) 会把它清空并设为 false。业务上仍应把 Valid 作为 NULL 判断依据，不要单独依赖 String 的零值。

可以直接把 sql.NullString 改成 *string 吗？

可以，指针也能表达 NULL，但团队需要统一指针生命周期、JSON 输出和写回规则。NullString 的 Valid 字段通常更直观。

Go 1.22 的 sql.Null[string] 能替代 NullString 吗？

可以在支持该版本的项目中使用泛型 sql.Null[string]，它同样通过 Valid 表达可空性；旧代码继续使用 NullString 没有问题，迁移时要同步字段名和序列化逻辑。