Go sql.Null[T] 扫描可空字段时怎么判断 Valid

使用 database/sql.Null[T] 扫描可空字段时，判断是否有值看 Valid，不要看 V 的零值。Valid == false 表示当前结果是 SQL NULL；Valid == true 时，V 才是可以交给业务代码使用的值，即使这个值本身是空字符串、0 或 false。

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

如果扫描结果“看起来总是空”，先按下面的顺序排查：是否把 Null[T] 当成值而不是指针传给 Scan，是否用 V == 零值 代替了 Valid，以及扫描是否其实已经返回了类型转换错误。

现象：空字符串和 NULL 被混成了一种状态

Null[T] 的核心结构只有两个字段：

因此，数据库中的空字符串与 NULL 不能用 V == "" 区分。前者可以是“有值且内容为空”，后者是“没有值”；同样，数字 0 和布尔值 false 也可能是有效数据。

第一层检查：Scan 是否拿到了可写入的指针

扫描目标必须传入指针，例如 &name。如果把 sql.Null[string]{} 直接传入，Scan 没有办法修改结构体，通常会返回目标类型不支持或不可扫描的错误。

package main

import (
	"database/sql"
	"fmt"
)

func readName(row *sql.Row) (string, bool, error) {
	var name sql.Null[string]
	// Scan 必须接收 &name，database/sql 才能写入 V 和 Valid。
	if err := row.Scan(&name); err != nil {
		// 查询错误和字段转换错误都要先返回，不能把它们当作 NULL。
		return "", false, err
	}
	if !name.Valid {
		// Valid=false 表示数据库值为 NULL，V 的内容不应当参与业务判断。
		return "", false, nil
	}
	// Valid=true 时，即使 name.V 是空字符串，也表示该字段有值。
	return name.V, true, nil
}

func printName(row *sql.Row) {
	// 这个示例只展示状态分支，不负责创建具体数据库连接。
	value, ok, err := readName(row)
	if err != nil {
		fmt.Println("扫描失败:", err)
		return
	}
	fmt.Println("值:", value, "是否存在:", ok)
}

这一层的证据很明确：如果 row.Scan 返回错误，问题还没有进入“判断 Valid”的阶段；只有扫描成功后，才应该根据 Valid 选择业务路径。

第二层检查：先看 Valid，再读取 V

官方实现对 Scan(nil) 的处理是把 V 重置为类型零值，并将 Valid 设为 false。对非空值，它尝试把驱动值转换为 T，转换成功后才把 Valid 设为 true。

func describe[T any](value sql.Null[T]) string {
	if !value.Valid {
		// NULL 与 T 的零值不是同一个业务状态。
		return "数据库字段为 NULL"
	}
	// 只有通过 Valid 判断后，才把 V 当作真实字段值。
	return fmt.Sprintf("字段有值: %v", value.V)
}

func stateTable() {
	var text sql.Null[string]
	// 模拟 NULL：结果是 V=""，但 Valid=false。
	_ = text.Scan(nil)
	fmt.Println(describe(text))

	// 模拟有效空字符串：V 仍为空，但 Valid=true。
	_ = text.Scan("")
	fmt.Println(describe(text))
}

上面的两个状态都可能打印出空字符串，但只有第二次扫描后的 Valid 为 true。这也是“看字段内容判断是否存在”最常见的误区。

第三层检查：扫描错误不能伪装成 Valid=false

如果非空驱动值无法转换为目标类型，Scan 会返回错误，并将 Valid 设为 false。这时“无效”是失败后的状态，不是一次成功扫描得到的 NULL 结论，所以必须先处理错误。

func scanAmount(row *sql.Row) error {
	var amount sql.Null[int64]
	// 目标类型要与驱动返回值可转换；错误不能被忽略。
	if err := row.Scan(&amount); err != nil {
		return fmt.Errorf("扫描金额失败: %w", err)
	}
	if !amount.Valid {
		// 这里才是成功扫描后的 NULL 分支。
		fmt.Println("金额为空")
		return nil
	}
	// 0 也可能是有效金额，因此不能用 amount.V == 0 代替 Valid。
	fmt.Println("金额:", amount.V)
	return nil
}

排查时可以把三种结果分开记录：Scan 返回错误表示转换或目标问题；Scan 成功且 Valid=false 表示 NULL；Scan 成功且 Valid=true 表示有值，包括有效零值。

第四层检查：写入参数时 Value 也看 Valid

Null[T] 同时实现了 driver.Valuer。当 Valid=false 时，Value() 返回 nil，交给驱动表示 SQL NULL；当 Valid=true 时，才把 V 转换为驱动可接受的参数。

func argument() (sql.Null[string], sql.Null[string]) {
	missing := sql.Null[string]{}
	present := sql.Null[string]{V: "", Valid: true}

	// missing.Value() 返回 nil，表示要写入 NULL。
	missingDriverValue, _ := missing.Value()
	// present.Value() 保留空字符串，因为 Valid=true 表示它是有效值。
	presentDriverValue, _ := present.Value()
	fmt.Printf("missing=%#v present=%#v\\n", missingDriverValue, presentDriverValue)
	return missing, present
}

如果业务对象把“未填写”映射为 sql.Null[string]{}，它会写入 NULL；如果需要保存用户明确提交的空字符串，就要构造 V: "", Valid: true。读取和写入必须采用同一套语义。

反向复查：用这份清单定位“Valid 不对”

1. 确认 Go 版本至少支持文档中标注的 sql.Null[T]，不要把泛型类型名当成旧版别名。
2. 确认 Scan 的目标是 *sql.Null[T]，也就是传入 &field。
3. 确认先判断 err，再判断 Valid；不要忽略转换错误。
4. 确认业务代码读取的是 Valid，不是 V == ""、V == 0 或 !V。
5. 确认写入参数时，空值和有效零值分别构造了 Valid=false 与 Valid=true。
6. 确认 T 属于驱动值可接受或可转换的类型，复杂业务类型不要直接假设能被驱动处理。

可以把判断顺序固定成一句话：先处理 Scan 错误，再用 Valid 区分 NULL，最后才读取 V；写入时也先看 Valid 决定 NULL 还是具体值。

相关问题

Valid=false 时 V 一定是零值吗？

官方实现的 Scan(nil) 会将 V 重置为类型零值；但业务代码不应依赖 V 来判断 NULL，判断职责始终属于 Valid。

有效的空字符串应该怎么表示？

使用 sql.Null[string]{V: "", Valid: true}。这样读取时它与 NULL 不同，写入时 Value() 也会保留空字符串。

可以直接把 Null[T] 传给 Scan 吗？

不可以。扫描需要修改结构体，应该传入指针，例如 row.Scan(&field)，并检查返回错误。