Go UUID 怎样为可空数据库字段使用 NullUUID

使用 github.com/google/uuid 的 uuid.NullUUID 表示可空数据库字段。读取时把 &value 传给 Scan，先处理扫描错误，再看 value.Valid：false 表示空值，true 时才把 value.UUID 当成有值字段。写入时将 NullUUID 作为参数传给 database/sql，由它的 Value 方法表达 SQL NULL 或 UUID 字符串。

官方地址：https://github.com/google/uuid

这里讨论一个工单可选关联 project_id 的场景：没有关联项目时存 NULL，已有关联时存 UUID。表中存在这一行但字段为空，与根本没有查询到工单，是两种不同情况。

为什么零 UUID 不能替代 NULL

NullUUID 由 UUID 和 Valid 两部分组成。SQL NULL 是缺少值，uuid.Nil 是所有字节为零的 UUID 数值。是否接受零 UUID 作为业务标识应由业务决定，但它不是数据库空值的同义词。

不能用 value.UUID == uuid.Nil 代替 Valid 判断。那会把有值的全零 UUID 和空字段混到一起。类型和方法定义见 NullUUID 官方 API。

结构图中的 NullUUID 包含 UUID 与 Valid；SQL NULL、有值UUID、零UUID 描述不同语义状态。Valid 对应是否有值，UUID 对应具体标识；零UUID 仍属于一种有值UUID。

读取时扫描到指针并检查 Valid

下面是一个独立的 repository.go 文件，使用调用方已经建立的连接池，展示 PostgreSQL 风格的占位符。示例未连接数据库、未执行 SQL；项目需声明并固定 google/uuid 依赖，并由主程序注册所选数据库驱动。

package repository

import (
    "context"
    "database/sql"
    "fmt"

    "github.com/google/uuid"
)

func LoadProjectID(ctx context.Context, db *sql.DB, ticketID int64) (uuid.NullUUID, error) {
    var projectID uuid.NullUUID
    // 扫描目标必须传指针，列为 NULL 时由 NullUUID 记录 Valid=false。
    err := db.QueryRowContext(ctx,
        "SELECT project_id FROM support_tickets WHERE id = $1",
        ticketID,
    ).Scan(&projectID)
    if err != nil {
        // 包装后调用方仍可用 errors.Is 判断 sql.ErrNoRows。
        return uuid.NullUUID{}, fmt.Errorf("读取工单项目关联失败: %w", err)
    }
    return projectID, nil
}

func SaveProjectID(ctx context.Context, db *sql.DB, ticketID int64, text *string) error {
    var projectID uuid.NullUUID
    if text != nil {
        // 非空输入必须解析，非法文本不能被静默当成清空操作。
        id, err := uuid.Parse(*text)
        if err != nil {
            return fmt.Errorf("项目UUID格式错误: %w", err)
        }
        projectID = uuid.NullUUID{UUID: id, Valid: true}
    }
    // text=nil 时 projectID 保持无值，Valuer 会提供 SQL NULL。
    result, err := db.ExecContext(ctx,
        "UPDATE support_tickets SET project_id = $1 WHERE id = $2",
        projectID, ticketID,
    )
    if err != nil {
        return fmt.Errorf("写入项目关联失败: %w", err)
    }
    count, err := result.RowsAffected()
    if err != nil {
        return fmt.Errorf("读取更新行数失败: %w", err)
    }
    if count == 0 {
        return sql.ErrNoRows
    }
    return nil
}

查询成功返回后，调用方用 projectID.Valid 决定显示“未关联项目”还是 projectID.UUID.String()。如果 Scan 返回错误，应先退出错误分支，不能只看 Valid 就把连接失败、数据损坏或无行结果解释成字段为空。

QueryRow 的错误通常在 Scan 时返回；无匹配行对应 sql.ErrNoRows，并不等于成功查询到 NULL。标准库约定见 Row.Scan 文档。这里使用 QueryRow，没有需要调用方关闭的 Rows 对象；连接池由创建它的主程序管理。

写入时用 Valid 明确表达是否为空

在上面的保存函数里，nil 指针明确表示清空关联；非 nil 指针必须包含可解析的 UUID。这个函数的输入契约由应用定义，不能直接把任何 HTTP PATCH 字段套进来而忽略“未提供字段”的含义。

NullUUID 的 Value 在 Valid=false 时返回 nil，在 Valid=true 时交给 UUID 的 Value 方法，后者提供 UUID 文本。应把值作为占位参数传递，不要手工拼接 SQL。对于不同数据库和列类型，驱动是否接受相应表示，应按驱动文档选择；不能假设这段代码同时适用于文本 UUID、原生 UUID 和所有 BINARY(16) 写入方式。

另一张结构图使用 数据库列、Scan、NullUUID、Value、SQL参数、业务判断 六个节点：Scan 关联数据库列与可空值，Value 关联可空值与参数表达，业务判断读取 NullUUID 的状态。

空字符串与扫描错误怎么处理

不要让可空文本列用空字符串模拟 SQL NULL。项目当前 UUID.Scan 实现会接受空字符串或空字节切片而不更新 UUID；NullUUID 的外层 Scan 在该调用未报错时又会把 Valid 设为 true。因此空字符串并不能可靠表达 NullUUID 的“无值”，复用扫描目标时还可能留下先前数值。

这项区别可从 UUID SQL 转换源码 与 NullUUID 源码看出。数据库字段应统一用 NULL 表达空关联；若历史数据已有空字符串，应在迁移或读取边界明确处理，而不是期待 Scan 自动等同二者。

扫描非法 UUID 失败时，Valid 会被置为 false，但错误仍必须返回。false 既可能是正常 NULL 状态，也可能是出错后的状态；只有“扫描成功且 Valid=false”才能按正常空值处理。不要在错误发生后继续使用 UUID 字段。

JSON 空值与接口更新还差哪一层

NullUUID 还实现了 JSON 编解码：无值可表示为 JSON null，有值表示为 UUID 字符串。这便于把数据库空值传到接口，但不自动解决 PATCH 的三态问题：字段未提供、显式 null、提供具体 UUID，应由请求模型分别保留。

例如新增请求中把未提供与 null 都解释为无关联可能合理；更新请求中，未提供通常意味着保留旧值，而显式 null 才意味着清空。前文 SaveProjectID 已约定 nil 为清空，调用它之前应由上层决定本次是否需要更新该字段。

只给 UUID 赋值，忘记设置 Valid 会怎样？

Value 依据 Valid 判断是否为空，因此即使 UUID 字段非零，只要 Valid=false，写入仍按 NULL 表达。构造有值对象时，应同时赋 UUID 和 Valid=true。

需要先调用 Value，再传给 ExecContext 吗？

通常不需要。将实现 driver.Valuer 的 NullUUID 直接作为 database/sql 参数即可。手工调用适合显式转换场合，但不会替你确认数据库列或驱动的二进制格式要求。

可以通过 Valid 判断 UUID 是否符合业务版本要求吗？

不能。这里 Valid 主要表达空值状态与转换是否成功，不意味着符合某个 UUID 版本、非零约束或业务关联存在性。需要这些条件时另行判断，不能把可空容器当成完整业务校验器。