google/uuid 不支持 UUID v7，因其截至 v1.6.x 仅支持 v1–v5 和 v18，解析 v7 字符串时 Version() 返回 0；需改用 tidwall/uuid 才能正确生成、解析并验证 v7，且须自行处理时钟回拨风险。
为什么 google/uuid 不能用 UUID v7
调用 uuid.New() 或 uuid.NewV4() 得到的永远是 v4；即使你传入一个形如 "0190----" 的字符串，uuid.Parse() 能成功，但 u.Version() 返回 0——它根本没识别版本位。这是因为 github.com/google/uuid 截至 v1.6.x（2026 年 7 月最新版）只支持 v1–v5 和 v18（nil），RFC 9562 定义的 v7 不在支持列表里。
常见错误现象：SELECT '0190abcd-1234-7def-8901-23456789abcd'::UUID 在 PostgreSQL 里能过，但下游 gRPC 接口或 OpenAPI validator 检查 version 字段时会失败，因为第 13 个 hex 字符虽是 7，但解析后版本号未被提取。
用 tidwall/uuid 替换 google/uuid 的实操步骤
这是目前 Go 生态中唯一完整实现 RFC 9562 的库，生成的字节布局、时间戳编码、变体位（0b10xx）、版本位（0b0111）全部合规，且字符串格式与标准 UUID 完全一致。
- 安装：
go get github.com/tidwall/uuid - 生成：
id, err := uuid.NewV7()（推荐）或id := uuid.Must(uuid.NewV7())（panic on error） - 验证：
id.Version() == 7返回true；id.String()[14] == '7'（注意：索引从 0 开始，第 13 位字符对应下标 14） - 兼容性：可直接赋值给
pgtype.UUID、sql.NullString或 JSON 字段，无需额外转换
时钟回拨是 v7 最容易被忽略的风险点
uuid.NewV7() 底层依赖 time.Now().UnixMilli()，不是纳秒也不是微秒——它用毫秒级时间戳作为前缀主体。这意味着：
立即学习“go语言免费学习笔记（深入）”；
- 同一毫秒内并发调用，靠 70-bit 随机后缀兜底，概率极低但非零
- 若 NTP 校正导致系统时间跳回（哪怕只跳 1ms），前缀重复，后续随机部分无法保证全局唯一
- 该库不内置时钟回拨补偿，生产环境必须自行处理：例如 fallback 到本地单调计数器段，或结合 etcd 分布式锁做时间戳仲裁
别指望“v7 天然防回拨”——它只是比 v1 更紧凑、比 v4 更有序，但没解决分布式时钟同步这个本质问题。
别拿 ULID/KSUID 当 v7 用
它们看起来也带时间戳、可排序、全局唯一，但和 UUID v7 是两套东西：
-
github.com/oklog/ulid编码为 26 字符 base32，二进制结构是 48-bit 时间 + 80-bit 随机，不满足 128-bit 布局要求 -
github.com/segmentio/ksuid是 160-bit，且 version 字段不在固定位置 - PostgreSQL 的
UUID类型会拒绝 ULID 字符串；OpenAPIformat: uuid校验器会因 version 位不匹配而报错
如果你的 API 文档写明 “accepts UUID v7”，那传 ULID 就是协议违规，不是兼容性问题，是类型错误。
