Go database/sql.Null[T] 如何区分数据库 NULL 与类型零值：Valid 字段和 Scan 边界

接口把可空金额读进 Go 结构体时，最容易踩的坑不是 SQL 语句，而是把金额 0 和数据库 NULL 当成同一件事。Go 1.22 起，database/sql.Null[T] 用泛型承载这类字段：V 保存值，Valid 单独说明数据库列是否为 NULL。

判断空值只看 Valid；即使 V 恰好是字符串空串、整数 0 或时间零值，只要 Valid 为 true，它就是数据库里读到的有效值。

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

源码中的定义很短：

type Null[T any] struct {
    V     T
    Valid bool
}

V 是普通 Go 值，Valid 才是空值标志。下面用一个不依赖数据库驱动的片段模拟 Rows.Scan 传入值，先把边界固定下来。

package main

import (
    "database/sql"
    "fmt"
)

func main() {
    var price sql.Null[int64]

    _ = price.Scan(nil)
    fmt.Printf("NULL: V=%d Valid=%v\n", price.V, price.Valid)

    _ = price.Scan(int64(0))
    fmt.Printf("zero: V=%d Valid=%v\n", price.V, price.Valid)
}

输出中的两行都可能显示 V=0，但第一行是空值，第二行是明确存储的 0。业务判断若写成 price.V == 0，就会把两种状态合并。

Scan(nil) 和 Scan(0) 到底差在哪里

Null[T].Scan 接收数据库驱动传来的 any。当参数为 nil 时，它执行 n.V, n.Valid = *new(T), false；否则先把 Valid 置为 true，再把参数转换到 V。

数据库列是 NULL 时

先前对象里残留的值也会被清掉，这一点对复用扫描变量很重要：

var name sql.Null[string]

_ = name.Scan("Go")
_ = name.Scan(nil)

fmt.Printf("V=%q Valid=%v\n", name.V, name.Valid)
// V="" Valid=false

不能只检查 name.V 是否为空。正确的业务分支是先看 Valid，只有它为 true 时才读取 V。

数据库列是 0、空串或 false 时

这些都是有效值，只是它们碰巧等于各自类型的零值：

var count sql.Null[int64]
var enabled sql.Null[bool]

_ = count.Scan(int64(0))
_ = enabled.Scan(false)

// count.Valid == true
// enabled.Valid == true

如果数据库列允许 NULL，而接口返回 JSON 又要区分“没填”和“填了 0”，可以把 Valid 映射成指针或显式的响应字段，不要在序列化前直接丢掉它。

Value() 写回参数时如何保留 NULL

Null[T] 同时实现了 driver.Valuer。当 Valid=false 时，Value() 返回 nil, nil，数据库驱动会把它当作 SQL NULL；当 Valid=true 时，才转换并返回 driver.Value。

empty := sql.Null[string]{V: "", Valid: false}
zero := sql.Null[int64]{V: 0, Valid: true}

a, _ := empty.Value()
b, _ := zero.Value()
fmt.Printf("empty=%#v zero=%#v\n", a, b)
// empty= zero=0

这里的关键不是把 V 清空，而是维护 Valid。例如用户明确清空备注时，应构造 sql.Null[string]{Valid: false}；用户输入空串并希望保留空串时，则应使用 Valid: true。

泛型参数和 Scan 错误边界

官方文档要求 T 属于驱动参数能接受的类型。常见的 string、整数、浮点数、bool、[]byte 和 time.Time 通常更容易与驱动配合；自定义结构体不能因为“能编译”就直接作为数据库参数。

还要检查 Scan 返回的 error。非 NULL 值转换失败时，Valid 的最终状态与转换结果相关，忽略错误会留下一个看似有效但没有业务意义的对象。

var id sql.Null[int64]
if err := id.Scan("not-a-number"); err != nil {
    // 记录转换错误，不要继续把 id.V 当成查询结果
    fmt.Println(err)
}

项目里最稳妥的判断方式

读路径统一封装成“先判 Valid，再读 V”；写路径明确表达“SQL NULL”还是“有效零值”。审查代码时重点找两类危险写法：直接比较 V 的零值，以及构造对象时只填 V 却忘了填 Valid。

• 允许为空的列：扫描后保留 sql.Null[T]，业务分支检查 Valid。
• 明确必填的列：可以扫描到普通类型，让数据库约束负责拦截异常。
• 更新接口的“清空字段”：传入 Valid=false，不要用空串或 0 猜测意图。

相关问题

sql.Null[T] 是从哪个 Go 版本开始提供的？

官方包文档标注为 Go 1.22.0 新增。低于 Go 1.22 的项目应继续使用 NullString、NullInt64 等旧类型，或自行维护兼容类型。

Valid=true 但 V 是零值，算空吗？

不算。Valid=true 表示数据库返回了有效值，零值只是该类型的具体内容。

调用 Value() 后会自动修改 Valid 吗？

不会。Value() 只根据当前状态返回参数值；是否为空由构造对象或扫描结果决定。

小结

sql.Null[T] 解决的是“值”和“是否存在”必须同时传递的问题。把 V 当内容、把 Valid 当状态，读写两条路径都按这个约定走，数据库 NULL、空串和 0 就不会在接口层悄悄混为一谈。