Go sql.Null 泛型类型怎么扫描可空字段

查询结果里只要出现 SQL NULL，就不能把它当成普通字符串或整数直接接收。Go 从 1.22.0 开始在 database/sql 中提供泛型 sql.Null[T]：V 保存扫描到的值，Valid 表示这次结果是不是非 NULL。正确做法是把它的地址传给 Scan，先检查错误，再检查 Valid，不要仅凭 V 的零值猜测数据库状态。

先看清 sql.Null[T] 的两个字段

泛型空值容器的核心结构可以概括为 V T 和 Valid bool。当数据库返回非 NULL 值时，Scan 会把转换后的结果写入 V，并把 Valid 设为 true；返回 NULL 时，Valid 为 false。此时不要把 V 当成有业务意义的值。

下面的查询只取一个可能为空的昵称，关键点是把容器地址传入，而不是传值：

var nickname sql.Null[string]
err := db.QueryRowContext(ctx,
    "SELECT nickname FROM users WHERE id = ?", userID, // 只查询目标用户的可空列
).Scan(&nickname) // 传地址，让 database/sql 写入 V 和 Valid
if err != nil {
    return err // 查询失败与列为 NULL 是两件事
}
if nickname.Valid {
    fmt.Println("昵称：", nickname.V) // 非 NULL，即使内容为空也按真实值处理
} else {
    fmt.Println("昵称未设置") // SQL NULL
}

这里的 Valid 是状态位，不是对字符串内容的校验。数据库里的空字符串可以是合法业务值，不能用 nickname.V == "" 代替空值判断。

在多列 Scan 中保持字段和状态一一对应

实际查询通常同时返回多个可空列。每个容器都应保持自己的 Valid，并按 SELECT 的顺序传给 Scan：

var (
    nickname sql.Null[string]
    age      sql.Null[int64]
    joinedAt sql.Null[time.Time]
)
err := row.Scan(&nickname, &age, &joinedAt) // 三个地址分别接收三列
if err != nil {
    return err // 类型不兼容、列数不符等错误要直接返回
}

if age.Valid {
    fmt.Printf("年龄=%d\n", age.V) // 0 可能是真实年龄，不能用 0 判断 NULL
}
if joinedAt.Valid {
    fmt.Println("入职时间：", joinedAt.V) // 时间列也按 Valid 决定是否展示
}

这段代码还提醒了两个常见坑：一是 Scan 的目标顺序必须对应查询列顺序；二是 Scan 返回错误时，容器内容不能当成可靠结果继续使用。

类型选择要落在 driver.Value 边界内

官方文档要求 T 选择驱动可接受的类型。常见安全选择包括 string、int64、float64、bool、[]byte 和 time.Time，但最终还要看数据库驱动对列类型的转换规则。不要因为泛型语法允许写任意类型，就把一个业务结构体直接写成 sql.Null[Order] 并期待驱动自动拆装。

sql.Null[T] 同时实现了 sql.Scanner 和 driver.Valuer。读取时使用指针接收；写入参数时传容器本身，让 Valid=false 表达 SQL NULL：

var nickname sql.Null[string]
nickname.V = "小林"
nickname.Valid = true // 写入普通字符串

_, err := db.ExecContext(ctx,
    "UPDATE users SET nickname = ? WHERE id = ?", // 参数由驱动处理
    nickname, userID,
)
if err != nil {
    return err
}

nickname.Valid = false // 写入 NULL，而不是写入空字符串
_, err = db.ExecContext(ctx,
    "UPDATE users SET nickname = ? WHERE id = ?", // 复用同一容器表达清空
    nickname, userID,
)
return err

遇到扫描失败时按三步排查

1. 先看列是否真的可能返回 NULL，并确认目标是否传了指针。
2. 再核对 T 与驱动返回类型，例如整数列通常接收 int64，时间列遵循驱动的时间转换约定。
3. 最后检查 SELECT 列顺序、列数和驱动版本；不要用默认零值绕过 Scan 错误。

相关问题

sql.Null[T] 能替代所有旧的 Null 类型吗？

对新代码，它能统一字符串、整数、浮点数、布尔值和时间等常见场景；旧项目若受 Go 版本约束，仍可继续使用 NullString 等类型。

为什么 Valid=true 但 V 是 0？

0 可能就是数据库中的真实值。是否为 SQL NULL 只看 Valid，不要把业务零值和空值状态混为一谈。

传给 Scan 时可以不加取址符号吗？

不可以。扫描需要写入容器字段，应传 &value；写入 SQL 参数时则传实现了 Valuer 的容器值。

小结：使用 Go sql.Null[T] 扫描可空字段时，先用正确的指针接收，再用 Valid 区分 NULL 与合法零值，最后按驱动值类型选择 T。这样查询和写回都能保留数据库真实状态。