Go sql.Null[T] 怎么扫描可空自定义类型

可以。Go 1.22 起，database/sql 提供了泛型类型 sql.Null[T]，最适合承载“数据库列允许 NULL，但业务代码希望保留明确自定义类型”的场景。关键写法是把自定义类型建立在 string、int64、bool 等驱动值类型之上，然后把 &sql.Null[自定义类型] 传给 Scan。

不要用自定义类型的零值判断数据库 NULL。sql.Null[T] 的 Valid 才是 NULL 边界：为 true 表示读到了值，为 false 表示源列就是 NULL。

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

先分清 V、Valid 与自定义类型

sql.Null[T] 的结构很小：V T 保存结果，Valid bool 保存是否为非 NULL。官方文档还要求 T 属于驱动可接受的值类型，因此推荐使用“定义类型”包装标量，而不是直接塞进任意结构体。

用定义类型承载可空订单状态

下面的 OrderState 底层是字符串，所以可以接收驱动返回的字符串或字节数据；它仍然是独立的 Go 类型，业务代码不会把任意字符串都当成状态使用。

package main

import (
    "database/sql"
    "fmt"
)

// OrderState 用定义类型限制订单状态的业务语义。
type OrderState string

const (
    StatePaid    OrderState = "paid"
    StatePending OrderState = "pending"
)

func readState(row *sql.Row) (OrderState, bool, error) {
    var state sql.Null[OrderState]

    // Scan 必须接收指针，NULL 时由 Null[T] 重置 V 并设置 Valid=false。
    if err := row.Scan(&state); err != nil {
        return "", false, fmt.Errorf("scan order state: %w", err)
    }
    if !state.Valid {
        // 这里区分“列为 NULL”和“列值为空字符串”。
        return "", false, nil
    }
    return state.V, true, nil
}

如果列值是 NULL，Scan 不会返回错误，而是把 V 设为 OrderState("")，并把 Valid 设为 false；如果列值是空字符串，Valid 仍为 true。这正是指针字段或单独的布尔标记难以统一表达的地方。

Scan 失败时重点看转换边界

sql.Null[T].Scan 对非 NULL 数据使用 database/sql 的转换逻辑。对 type UserCode string、type Priority int64 这类标量定义类型，通常只要源数据能无损转换即可；源数据与 T 不匹配时，应保留错误，不要把 Valid 强行改成 true。

type UserCode string
type Priority int64

func scanColumns(row *sql.Row) (UserCode, Priority, error) {
    var code sql.Null[UserCode]
    var priority sql.Null[Priority]

    // 两个目标都保留 NULL 信息；任一列转换失败都让调用方感知。
    if err := row.Scan(&code, &priority); err != nil {
        return "", 0, fmt.Errorf("scan nullable columns: %w", err)
    }
    if !code.Valid {
        // 业务可以把缺少编码视为“未分配”，而不是空编码。
        code.V = "unassigned"
    }
    if !priority.Valid {
        // 只有在业务明确规定时，才把 NULL 映射成默认优先级。
        priority.V = 0
    }
    return code.V, priority.V, nil
}

上例的默认值只改变了返回给业务层的表达，不能反过来改变 Valid 的事实。若后续需要更新数据库，仍可根据 Valid 决定传 nil 还是传 V。

写回数据库与版本边界

sql.Null[T].Value 在 Valid=false 时返回 SQL NULL，在 true 时把 V 转成驱动值。因此可以直接作为参数使用，但 T 最好仍是驱动支持的标量定义类型。任意业务结构体应先编码成数据库列需要的字符串、字节或数字，再交给参数层。

这套泛型类型从 Go 1.22 才加入标准库。需要兼容更早版本时，继续使用 sql.NullString、sql.NullInt64 或自定义实现 sql.Scanner 的结构体，不要只改掉泛型语法却忘记 NULL 语义。

常见追问

sql.Null[T] 能直接扫描任意结构体吗？不建议。优先选择底层为驱动值类型的定义类型；复杂结构体应实现自己的 Scanner，把解码边界写清楚。

为什么 Valid=true 但 V 看起来是零值？因为“数据库非 NULL”和“业务值等于零值”是两件事，例如空字符串或数字 0 都可能是有效数据。

实际落地时，可以把 Valid 留在数据访问层，或者把它转换成业务对象中的可选字段；无论采用哪种方式，都不要用 V == 零值 替代 NULL 判断。