很多 Go 项目里，UUID 生成几乎是一个“不用想”的刚需，而 github.com/google/uuid 也几乎成了事实标准。每开一个新服务，Go module 里多出一行 require github.com/google/uuid v1.6.0 是再正常不过的操作。但依赖就是债务，多一个外部包，就多一份版本冲突、安全审计、构建缓存失效的风险。现在，Go 1.23 标准库终于把 UUID 包收了进来，放在 crypto/uuid 下，这意味着我们终于可以认真考虑删掉那个用了很久的第三方依赖了。
这件事之所以值得认真对待，不是因为标准库就一定比第三方好，而是因为 UUID 这种基础件一旦被标准库吸收，依赖管理、安全性、长期维护的成本都会大幅降低。下面我们聊聊，标准库 UUID 到底能做什么、不能做什么，以及在实际项目里怎么平滑地切过去。
标准库 UUID 包的设计哲学
Go 标准库引入新包向来很克制，crypto/uuid 也不例外。它没有试图覆盖所有 RFC 9562 定义的版本，而是聚焦在工程上最常用的三个版本：V1（基于时间 + MAC 地址）、V4（随机）和 V7（时间排序的随机 UUID）。V7 是相对较新的规范，专门为数据库索引友好而设计，很多分布式系统已经在用。对于绝大部分业务场景，这三个版本已经够用了。
把包放在 crypto 之下，还传递了一个明确信号：安全性是内置的。所有随机 UUID 生成都会使用 crypto/rand，而不是 math/rand，这意味着你不需要再担心因为误用不安全的随机源而产生可预测的 UUID。这一点比若干年前第三方库默认使用 math/rand 要安全得多，虽然现在 google/uuid 也早已切换到安全随机源，但标准库直接把这条路径固化下来了。
标准库和 google/uuid 到底差在哪
我们习惯的 google/uuid 是一个功能很全的库，支持 V1 到 V5，以及 Nil UUID、解析、格式化等。标准库 crypto/uuid 则在功能上做了精简，但也有意覆盖了多数场景。下面这张表可以直观地看到两者的差异：
| 特性 | crypto/uuid (Go 1.23) | github.com/google/uuid |
|---|---|---|
| 支持的 UUID 版本 | V1, V4, V7 | V1, V2, V3, V4, V5, V6, V7 |
| 随机源 | crypto/rand（强制） | crypto/rand（默认，可自定义） |
| 命名空间 UUID（V3/V5） | 不支持 | 支持 |
| 解析与验证 | 支持 | 支持 |
| JSON/文本序列化 | 支持（encoding 接口） | 支持 |
| 外部依赖 | 无 | 无（但模块本身是依赖） |
| 维护方 | Go 团队 | 社区 |
可以看到，标准库缺失的主要是 V3 和 V5，也就是基于 MD5/SHA1 的命名空间 UUID。但在实际项目中，V3/V5 的需求并不多，因为用命名空间生成 UUID 的场景本身就很有限，而且 V3 的 MD5 在安全敏感场景下也不推荐。如果你确实需要从固定名称派生出确定性 UUID，V7 已经可以通过时间排序 + 应用层名称来部分替代，或者你仍然可以保留 google/uuid 用于少数模块。
另外，标准库的 API 设计非常简洁，没有“可选配置”和“多种生成器”的抽象层，这反而让代码意图更清晰。下面是一个生成 V4 UUID 的对比：
// 标准库 crypto/uuid
import "crypto/uuid"
id, err := uuid.NewV4()
if err != nil {
// handle error
}
fmt.Println(id.String())
// 原先的 google/uuid
import "github.com/google/uuid"
id := uuid.New()
fmt.Println(id.String())标准库的 NewV4() 返回 error，因为 crypto/rand 读取系统熵时可能失败，这个 error 需要显式处理。旧代码里 uuid.New() 虽然不会返回 error，但它在内部 panic 的可能性其实是被隐藏了。标准库让错误处理回归显式，对于写健壮的服务来说，这其实是一个更好的实践。
什么时候可以放心删掉第三方依赖
如果你的项目满足以下条件，那么迁移到标准库 UUID 几乎零风险：
- 只用了 V4 生成随机 UUID，没有使用命名空间功能。
- 依赖了
google/uuid的少数几个 API，比如New()、Parse()、String()，这些在标准库里都有对等实现。 - Go 版本已经升级到 1.23 或更高，且可以控制编译环境。
一个典型的场景是：一个微服务只需要生成请求 ID、事件 ID，或者数据库主键，之前引入了 google/uuid 只为这一件事。这种情况下，去掉一个外部依赖可以减小二进制体积，省去每次 go mod tidy 时的心智负担，更重要的是，在安全审计报告里少一个“外部组件”的条目。
但还有一种团队还不想动：项目里大量文件 import 了 google/uuid，而且部分代码可能间接依赖了它的某些高级特性，比如 uuid.MustParse、自定义时钟、或者 V6/V7 的实验性实现。这种场景建议先做一次依赖扫描，把直接调用和间接调用理清楚。标准库的 V7 虽然也支持时间排序，但 API 和 google/uuid 的 V7 实现略有不同，迁移时需要留意时间戳精度的差异。
迁移步骤和容易踩的两个坑
实际迁移过程并不复杂，但有两个地方容易让人卡住。
第一个坑是错误处理。 旧代码里 uuid.New() 不返回 error，很多地方直接赋值给变量。替换成 uuid.NewV4() 后，如果直接忽略 error，编译会通过，但 linter 会报警告，而且一旦系统熵不足，程序会拿到一个零值 UUID，这比直接 panic 更难排查。建议统一封装一个 MustNewV4 函数，让它在出错时 panic，和旧行为保持一致，但显式标明这是有风险的操作。
第二个坑是序列化行为。 标准库的 UUID 类型实现了 encoding.TextMarshaler 和 encoding/json.Marshaler，JSON 序列化时输出带连字符的标准格式，例如 "550e8400-e29b-41d4-a716-446655440000"。如果你的下游服务或数据库驱动期望的是去掉连字符的格式，需要在序列化时额外处理，或者用自定义类型包装。这在 google/uuid 里也有类似问题，但迁移时容易忽略。
一个相对安全的迁移流程可以是：
- 把项目里所有
uuid.New()替换为uuid.NewV4()，并处理好 error。 - 把
uuid.Parse()替换为uuid.Parse()（标准库同名函数），注意返回值类型变化。 - 跑一遍单元测试和集成测试，重点关注 UUID 序列化后的字符串是否被下游正确消费。
- 删除
go.mod里的github.com/google/uuid依赖，运行go mod tidy。
如果项目里只用了基础功能，整个过程通常不会超过半天。
标准库 UUID 的局限和未来
任何技术选择都有边界。标准库 UUID 目前不支持 V3/V5，也没有提供类似 uuid.Must 的便捷函数，文档和社区示例也还比较少。如果你正在维护一个需要频繁生成基于名称的 UUID 的系统，或者需要兼容一些老协议里的 V2 UUID，那么完全删除 google/uuid 还不现实。
但一个更重要的趋势是：标准库吸收社区成熟库的路径已经越来越清晰。从 golang.org/x/exp 到标准库，slices、maps、log/slog 都是先例，UUID 包进入标准库意味着核心团队认为它的设计已经足够稳定，并且值得长期维护。对于大多数团队来说，这意味着可以放心地把 UUID 生成这件事交给标准库，把精力放在业务逻辑上。
所以，下次新建项目，或者给老项目做依赖瘦身的时候，不妨试试把 google/uuid 从 go.mod 里划掉。你会发现，不仅代码更干净了一点，连带着构建时的那种“依赖焦虑”也少了一分。
原创文章，作者：fudengji，如若转载，请注明出处：https://fudengji.cn/article/371/