Golang生成UUID方法全解析

Go标准库不内置UUID支持，必须使用社区事实标准库github.com/google/uuid——它严格兼容RFC 4122，推荐默认采用线程安全、零错误返回的v4随机生成（uuid.NewUUID()），避免手搓或误用弃用API；更关键的是，UUID绝不能以字符串形式存入数据库，而应利用其二进制本质：PostgreSQL直接用原生UUID类型，MySQL选用BINARY(16)，配合u.Bytes()和uuid.FromBytes()实现高效存储与查询，从根本上规避大小写、连字符、索引性能及一致性陷阱——真正决定系统健壮性的，从来不是“怎么生成”，而是生成之后每一步是否严丝合缝。

Go 里生成 UUID 要用 google/uuid，标准库不提供

Go 标准库没有内置 UUID 支持，直接 import "uuid" 或 "crypto/rand" 手搓容易出错。官方推荐、社区事实标准是 github.com/google/uuid —— 它兼容 RFC 4122，支持 v4（随机）、v5（SHA-1 命名）等版本，且线程安全。

常见错误现象：import "uuid" 报错 no required module provides package uuid；或自己用 crypto/rand.Read 拼字符串，结果格式不合法（缺分隔符、长度不对、字符越界）。

• 安装命令必须是：go get github.com/google/uuid（注意不是 go.uuid 或其他变体）
• v4 是最常用场景，调用 uuid.NewUUID() 即可，它内部已处理熵源和格式化
• 不要用 uuid.Must(uuid.NewUUID()) 在热路径上——Must 是 panic 包装器，仅适合初始化阶段校验
• 该包默认生成的字符串带连字符（如 6ba7b810-9dad-11d1-80b4-00c04fd430c8），若需无连字符格式，用 u.String()[0:8] + u.String()[9:13] + ... 太笨重，应改用 u.ID().String()？不对——正确方式是 u.String()[0:8] + u.String()[9:13] + u.String()[14:18] + u.String()[19:23] + u.String()[24:]，但更推荐直接用 u.EncodeToString()？等等，google/uuid 并没有这个方法。实际做法：用 strings.ReplaceAll(u.String(), "-", "")，性能可接受（UUID 固定长度，一次分配）

生成 v4 UUID 时别忽略错误，但 uuid.NewUUID() 实际不会返回 error

google/uuid 的 NewUUID() 函数签名是 func NewUUID() UUID，不返回 error。它内部用 crypto/rand.Read，失败时 panic —— 所以你不需要、也不应该写 if err != nil 判断。

但注意：如果你用的是 uuid.Parse() 或 uuid.ParseBytes()，它们才真正返回 error，比如传入 "abc" 这种非法字符串。

• 生成阶段不需 error 处理，但解析外部输入的 UUID 字符串时，必须检查 err
• 别把 uuid.NewUUID() 和 uuid.NewRandom() 混用：后者是旧版 API（v1.2 之前），现已弃用，行为相同但命名易误导
• 如果项目强制要求不 panic（如嵌入式环境或 FIPS 模式），可用 uuid.NewRandomFromReader(r io.Reader) 自定义熵源，但绝大多数服务无需这么干

数据库存 UUID 用 uuid.UUID 类型，别存 string

PostgreSQL 有原生 UUID 类型，MySQL 8.0+ 支持 BINARY(16) 存二进制格式，比存 36 字符 string 节省空间、索引更快、避免大小写/连字符歧义。

常见错误现象：用 db.QueryRow("INSERT ... VALUES (?)", u.String())，导致后续查询因格式不一致失败（如前端传来的 UUID 带大写字母，而 Go 生成的是小写）；或者 WHERE 条件用 WHERE id = 'abc...' 触发全表扫描。

• 用 github.com/google/uuid 时，UUID 类型实现了 driver.Valuer 和 sql.Scanner，可直接传给 db.Query 参数
• PostgreSQL：字段类型设为 UUID，Go 侧用 uuid.UUID 变量绑定即可
• MySQL：字段用 BINARY(16)，插入前调用 u.Bytes()；查询时用 uuid.FromBytes() 还原（注意检查 error，FromBytes 可能失败）
• 别用 u.String() 当主键做 JOIN 或 IN 查询——字符串比较比二进制慢，且 MySQL 对长字符串索引效率低

并发高时 UUID 生成本身不瓶颈，但要注意时钟回拨对 v1/v7 的影响

google/uuid 默认生成 v4（纯随机），完全不依赖系统时钟，所以多 goroutine 同时调用 NewUUID() 没锁、无竞争、性能极好（实测单核每秒百万级）。

但如果你主动切换到 v1（时间戳+MAC）或实验性的 v7（毫秒级时间戳+随机），就得小心了：v1 在虚拟机或容器中可能因时钟不同步、回拨导致 UUID 重复或顺序倒置；v7 虽改进时间精度，仍依赖单调时钟。

• 除非业务强依赖时间序（如日志追踪 ID 需天然排序），否则坚持用 v4 —— 简单、可靠、无副作用
• v1 的 uuid.NewUUID() 已被移除，v1 需显式调用 uuid.NewTime()，但它需要传入 time.Time，且 MAC 地址获取在某些容器环境会失败或返回零值
• v7 目前在 google/uuid 中尚未稳定支持（截至 v1.6.0），别在生产环境尝试

真正麻烦的从来不是“怎么生成”，而是“生成后怎么用”——比如是否透出给前端、如何跟数据库类型对齐、要不要做大小写归一化。这些细节没对齐，后面查半天才发现是连字符少了一个。

到这里，我们也就讲完了《Golang生成UUID方法全解析》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！