Go uuid 怎样区分无效 UUID 与零值 UUID

使用 github.com/google/uuid 时，不要用“返回的 UUID 是不是全零”来判断输入字符串是否无效。正确的分工是：uuid.Parse 返回的 error 负责说明输入能不能被解析；解析成功后，再把结果与 uuid.Nil 比较，判断它是不是零值 UUID。

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

无效 UUID 和零值 UUID 是两个维度：前者是解析失败，后者是解析成功后得到的合法全零 UUID。先判断 error，再判断 uuid.Nil，才能避免把两种状态混在一起。

解析错误与零值 UUID 不是一回事

uuid.UUID 是一个 16 字节数组，包里提供的 uuid.Nil 表示 16 个字节全为零。另一方面，Parse 的返回签名是 (UUID, error)：字符串无法解析时，错误信息在第二个返回值中；字符串是合法的全零形式时，错误为 nil，UUID 才是 uuid.Nil。

这也是为什么“先看 UUID，再看 error”容易写错：解析失败时返回的 UUID 可能正好是数组零值，但它的业务含义是“没有得到可用输入”，不是“用户明确提交了一个合法的零值 UUID”。

用 Parse 把三种结果分成清晰分支

package main

import (
    "errors"
    "fmt"

    "github.com/google/uuid"
)

func classify(raw string) (string, error) {
    parsed, err := uuid.Parse(raw)
    if err != nil {
        // 解析失败先返回错误；此时 parsed 不能当作业务 UUID 使用。
        return "无效输入", fmt.Errorf("解析 UUID 失败: %w", err)
    }

    if parsed == uuid.Nil {
        // 解析成功但全零，表示合法的零值 UUID。
        return "零值 UUID", nil
    }

    // 既没有解析错误，也不是全零值，才是普通 UUID。
    return "普通 UUID", nil
}

func main() {
    samples := []string{
        "not-a-uuid",
        "00000000-0000-0000-0000-000000000000",
        "550e8400-e29b-41d4-a716-446655440000",
    }

    for _, raw := range samples {
        label, err := classify(raw)
        if err != nil {
            // 示例只打印分类错误；真实接口可映射为参数错误响应。
            fmt.Printf("%q -> %s: %v\n", raw, label, err)
            continue
        }
        fmt.Printf("%q -> %s\n", raw, label)
    }
}

这段代码中，parsed == uuid.Nil 是数组的直接比较，不需要把 UUID 转成字符串再比较。判断顺序也很重要：只有 err == nil 时，parsed 才进入后续业务分支。

判断零值时要保留 error 语义

如果函数只返回一个 uuid.UUID，调用方就无法知道全零值来自“合法零值”还是“解析失败后的默认数组”。因此封装函数至少要返回 (uuid.UUID, error)，或者返回带状态的结果对象。

func parseRequired(raw string) (uuid.UUID, error) {
    parsed, err := uuid.Parse(raw)
    if err != nil {
        // 用 %w 保留底层错误，调用方仍可用 errors.Is 或 errors.As 判断。
        return uuid.Nil, fmt.Errorf("用户标识格式错误: %w", err)
    }
    if parsed == uuid.Nil {
        // 这里是业务拒绝零值，而不是库解析失败。
        return uuid.Nil, errors.New("用户标识不能是零值 UUID")
    }
    return parsed, nil
}

这个封装把“库能否解析”和“业务是否接受零值”拆开了。比如数据库中的可选外键可能允许 uuid.Nil 作为占位值，但创建用户、订单或租约的主标识通常不应该接受它；是否拒绝应由业务字段契约决定，而不是由 Parse 替你决定。

Parse 和 Validate 的契约边界要看清

官方文档特别说明，Parse 除了标准连字符形式，还接受 urn:uuid: 前缀、去掉连字符的 32 位十六进制串和带大括号的形式。因此，“Parse 没有返回错误”只能说明该字符串符合包支持的解析编码，不等于它符合你接口要求的唯一文本格式。

如果接口必须只接受标准的 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 形式，可以先使用 uuid.Validate 检查格式，再调用 Parse 取得 UUID。若接口还要求版本、业务前缀或不能为零，则继续在业务层补充判断。

func parseStandard(raw string) (uuid.UUID, error) {
    if err := uuid.Validate(raw); err != nil {
        // Validate 负责格式契约；它不替业务判断 UUID 是否为零值。
        return uuid.Nil, fmt.Errorf("UUID 文本格式不符合接口约定: %w", err)
    }

    parsed, err := uuid.Parse(raw)
    if err != nil {
        // 保留 Parse 的错误分支，避免未来更换输入来源后丢失语义。
        return uuid.Nil, fmt.Errorf("UUID 解析失败: %w", err)
    }
    return parsed, nil
}

把零值策略放在调用方边界

落到 HTTP、消息消费或数据库写入时，可以按字段性质决定策略：

不要把 uuid.Nil.String() 当作“无效值”的统一表示，也不要在解析失败时继续把返回的数组写入数据库。先把错误返回出去，再由边界层决定错误码、日志字段和用户提示，接口语义会更稳定。

常见问题

Parse 返回 error 时，返回的 UUID 能不能继续用？

不能把它当作有效业务值使用。解析失败应优先处理 error；即使返回数组看起来是全零，也不能据此推断用户提交了合法的零值 UUID。

零值 UUID 一定是无效 UUID 吗？

不一定。它是可以被解析的全零 UUID，是否“无效”取决于字段契约。主标识通常会拒绝它，可选关联字段则可能把它当作缺失占位。

只用 parsed == uuid.Nil 能判断输入是否合法么？

不能。这个判断只能识别解析结果是否为零值，不能替代对 error 的检查。

Parse 能不能做严格文本格式校验？

不能只依赖它。Parse 支持多种编码；需要更窄的文本契约时，使用 uuid.Validate 并结合业务规则。