零值 UUID 应该当成有效标识还是缺失值

直接结论：零值 UUID 在标准层面是一个有明确定义的特殊 UUID，也就是 Nil UUID；但它是否能作为业务标识，必须由领域契约决定。对用户、订单、任务这类必须存在的实体主键，通常应把零值视为“未赋值或非法输入”；只有协议明确规定全零 UUID 表示“无目标”“默认租户”或其他哨兵含义时，才把它当成可接受的特殊标识。

Go 标准库的 uuid.UUID 是 [16]byte，所以声明一个变量但不赋值时，16 个字节全部为零。包里的 uuid.Nil() 返回的正是 00000000-0000-0000-0000-000000000000。官方文档特别说明：Nil UUID 不等于 Go 的 nil。

官方文档：https://pkg.go.dev/uuid

先给结论：标准有效，不代表业务有效

这类争议往往是把三层语义混在了一起。标准层回答“全零 UUID 是什么”，Go 层回答“零值如何表现”，业务层才回答“这个字段能不能接收它”。

我在项目里更倾向于把“技术上能表示”和“业务上允许”分开：解析器可以接受全零文本，领域入口再根据字段职责决定是否拒绝。这样既尊重标准，也不会让特殊值悄悄混进实体数据。

Go 里怎样判断零值 UUID

uuid.UUID 是数组类型，数组在 Go 中可比较，因此可以直接与 uuid.Nil() 比较。不要通过字符串比较判断，也没有必要遍历 16 个字节。

package identity

import "uuid"

func IsZero(id uuid.UUID) bool {
    // UUID 是可比较的数组值，直接比较即可
    return id == uuid.Nil()
}

func RequireEntityID(id uuid.UUID) error {
    if IsZero(id) {
        // 实体主键的领域契约明确拒绝 Nil UUID
        return ErrMissingEntityID
    }
    return nil
}

var id uuid.UUID、uuid.Nil() 以及成功解析全零文本得到的值相等。解析成功只说明文本是可识别的 UUID，不代表它满足“必须是一个真实实体标识”的业务规则。

实体主键为什么通常应该拒绝零值

实体主键承担的是唯一定位职责。零值若被允许进入创建、更新或查询路径，常见后果不是立即报错，而是产生语义模糊：创建代码忘了生成 ID、调用方漏传字段、映射器没有赋值，最后都表现为同一个全零值。

把零值在边界处拒绝有三个收益：

• 遗漏生成 ID 的程序错误更早暴露，不会进入数据库。
• 查询接口不会把“缺少参数”误解为一个真实对象。
• 日志与指标可以把缺失标识单独统计，而不是把所有问题聚合到同一个 UUID。

func CreateOrder(input CreateOrderInput) (Order, error) {
    if input.CustomerID == uuid.Nil() {
        // 客户 ID 是必填关联，零值在领域入口直接拒绝
        return Order{}, fmt.Errorf("customer_id 不能为空")
    }

    orderID := uuid.New()
    // 新实体由创建逻辑生成非零 ID
    return Order{ID: orderID, CustomerID: input.CustomerID}, nil
}

这里的重点不是所有 UUID 字段都做同一条校验，而是把规则贴近字段职责。订单 ID 和可选推荐人 ID 即使类型相同，也可能需要完全不同的状态模型。

可选关联不要急着用 Nil UUID 代替缺失

对于“上级分类”“推荐人”“父任务”这类可选关联，使用 Nil UUID 作为“无关联”看起来很省事，但它会把两件事折叠到一个值：字段不存在，以及字段存在但明确提供了全零 UUID。数据库里也会出现 NULL 与全零 UUID 两套“空”语义。

如果业务只需要“有或没有”，优先使用指针或带有效性标记的包装类型：

type Task struct {
    ID       uuid.UUID
    ParentID *uuid.UUID // nil 明确表示没有父任务
}

func (t Task) HasParent() bool {
    // 指针表达存在性，UUID 值本身只表达标识
    return t.ParentID != nil
}

但指针也有边界：普通 JSON 解码时，“字段缺失”和“显式 null”通常都会落成 nil。如果 PATCH 接口必须区分“不修改”“清空关联”和“设置关联”，就需要三态或四态包装。

需要区分缺失、null、零 UUID 和普通 UUID 时怎么建模

更新接口最容易暴露状态不足的问题。一个值类型 uuid.UUID 只能保存 UUID 数值，无法告诉你字段是否出现；一个指针能表达“有/无”，但未必能区分省略和显式 null。此时应把“出现状态”和“值有效状态”分开。

type OptionalUUID struct {
    Present bool      // JSON 字段是否出现
    Valid   bool      // 出现后是否为非 null 的 UUID
    Value   uuid.UUID // Valid 为 true 时才读取
}

func (o OptionalUUID) ValidateNonZero() error {
    if !o.Present || !o.Valid {
        // 缺失和 null 由调用场景决定，不在这里混成零 UUID
        return nil
    }
    if o.Value == uuid.Nil() {
        return fmt.Errorf("明确提供的 UUID 不能为 Nil UUID")
    }
    return nil
}

这个包装并不是要求每个项目都复制同一种实现，而是展示一个原则：如果业务关心差异，就必须在类型里保留差异。仅靠全零值无法还原输入时到底是缺失、null 还是明确的 Nil UUID。

什么时候可以把 Nil UUID 当成有效特殊值

只有当契约明确写出它的特殊含义时才建议允许，例如协议定义 Nil UUID 表示“广播目标”“匿名主体”或“未指定命名空间”。此时它不是普通实体 ID，而是一个保留哨兵。

允许哨兵值时应同时满足四个条件：

• 含义写入接口或协议文档，不依赖团队口头约定。
• 字段命名能体现其特殊职责，而不是伪装成普通实体主键。
• 数据库约束和索引策略允许这个保留值。
• 测试覆盖普通 UUID、Nil UUID、缺失和非法文本。

func ResolveTarget(target uuid.UUID) TargetScope {
    if target == uuid.Nil() {
        // 该协议明确约定 Nil UUID 表示全部目标
        return TargetScopeAll
    }

    // 非零 UUID 仍然表示单个具体目标
    return TargetScopeOne{ID: target}
}

如果没有这样的明确契约，就不要事后为零值编造含义。默认拒绝比默认接受更容易发现错误，也更不容易让将来的迁移背上隐性规则。

API 边界应该在哪里校验

推荐把校验拆成两层。传输层负责解析字符串和报告格式错误，领域层负责判断零值是否被当前用例允许。这样全零 UUID 可以成功解析，但在“读取订单”用例中被拒绝，在“协议广播目标”用例中被接受。

func ParseRequiredID(raw string) (uuid.UUID, error) {
    id, err := uuid.Parse(raw)
    if err != nil {
        // 第一层只报告文本不是合法 UUID
        return uuid.UUID{}, fmt.Errorf("UUID 格式错误: %w", err)
    }
    if id == uuid.Nil() {
        // 第二层应用“必填标识不能为零”的接口契约
        return uuid.UUID{}, fmt.Errorf("UUID 不能为零值")
    }
    return id, nil
}

不要用 MustParse 处理请求数据，因为非法文本会 panic。它更适合源码中受开发者控制的固定常量，而不是用户、消息队列或数据库返回的数据。

数据库应统一 NULL 与 Nil UUID 的策略

数据库层最怕两套空值并存：部分记录使用 NULL，部分记录使用全零 UUID。查询、唯一约束、外键和统计都会因此变复杂。建议在表设计时做一次明确选择：

如果旧系统已经混用，迁移前先统计 Nil UUID 和 NULL 的数量、来源与调用路径，再选择统一方向。直接替换可能误伤确实依赖哨兵语义的记录。

采用这套规则时观察什么

零值策略是否有效，不只看代码能否通过编译。上线后可以观察以下信号：

• 请求边界出现 Nil UUID 的次数，以及来源接口和客户端版本。
• 创建实体时因未生成 ID 被拒绝的次数。
• 数据库中全零 UUID 与 NULL 的存量和新增趋势。
• 可选关联清空操作是否被误判为“不修改”。
• 协议哨兵是否只出现在被允许的字段和消息类型中。

这些指标能帮助团队判断：当前的零值究竟是有意的业务表达，还是漏赋值、错误映射或兼容逻辑留下的痕迹。

常见问题

uuid.Parse 会拒绝全零文本吗？

不会因为它是全零就把它当成格式错误。Nil UUID 是标准定义的特殊值；是否允许应由业务校验决定。

Nil UUID 和 nil 指针有什么区别？

Nil UUID 是 16 个字节全为零的 UUID 值；nil 指针表示没有指向任何 UUID 值。前者有数值，后者表达引用缺失。

能否用 id.String() == 全零字符串判断？

技术上可以比较出结果，但没有必要，还会引入字符串分配和魔法常量。直接使用 id == uuid.Nil() 更清楚。

所有可选 UUID 都应该用指针吗？

不一定。只需两态时指针很直接；需要区分省略、null、零 UUID 和普通 UUID 时，应使用带出现与有效性标记的包装类型。

所以，零值 UUID 没有一个脱离上下文的统一答案：它在 RFC 中是有效的 Nil UUID，在 Go 中是自然零值，在实体标识领域通常代表缺失或非法，在明确协议中又可能是合法哨兵。最稳妥的做法，是让每个字段的契约明确回答“Nil UUID 是否允许”，并让 API、类型、数据库和测试共同执行同一答案。