Go uuid 怎样解析和格式化 UUID

我在 Go 服务里第一次处理 UUID 时，真正容易踩坑的不是“怎么生成”，而是同一个标识从请求、数据库到日志之间不断换形：请求里可能带连字符，旧系统可能传纯十六进制，日志又希望统一成一种可复制的文本。用 github.com/google/uuid 时，最稳的分工是：外部输入用 uuid.Parse 接收并检查错误，内部已有可信常量才考虑 uuid.MustParse，最终输出交给 UUID.String()。

官方地址：https://pkg.go.dev/github.com/google/uuid

这个包把 UUID 表示为 16 字节的 uuid.UUID 数组，既可以直接比较，也可以作为 map 的键。下面只围绕“解析与格式化”展开，示例中的输入是教学数据，不代表本次实际运行日志。

先把字符串和 uuid.UUID 分开

字符串适合传输，uuid.UUID 适合在程序内部表达一个已经拆解好的 128 位值。两者不要在业务层到处混用：入口处解析一次，核心逻辑接收 uuid.UUID，离开服务或写日志时再格式化。

# 在 Go module 根目录安装依赖；版本由项目当前的模块解析结果决定。
go get github.com/google/uuid

# 查看模块是否记录了该依赖，不把清理缓存当成解析问题的修复。
go list -m github.com/google/uuid

package main

import (
	"fmt"

	"github.com/google/uuid"
)

func main() {
	// UUID 是固定长度的 16 字节数组，不是任意长度的字符串别名。
	var id uuid.UUID
	// 零值可以表示 Nil UUID；它和“没有解析成功”不是同一个概念。
	fmt.Printf("%T %v\n", id, id)
}

这里先认识类型，是为了避免把解析失败后的零值继续当作有效业务 ID。真正的输入处理必须保留 error。

外部 UUID 用 Parse，错误要留在边界

uuid.Parse 返回 (UUID, error)。解析成功后，UUID 值才进入后续业务；失败时应返回参数错误、记录上下文或交给上层处理，而不是无视错误继续查询数据库。

package main

import (
	"errors"
	"fmt"

	"github.com/google/uuid"
)

func parseID(raw string) (uuid.UUID, error) {
	// 入口只负责把外部文本转换为类型，并保留原始解析错误。
	id, err := uuid.Parse(raw)
	if err != nil {
		// 用包装错误补充业务语境，调用方仍可继续检查原始错误。
		return uuid.Nil, fmt.Errorf("解析用户 ID %q 失败: %w", raw, err)
	}
	return id, nil
}

func main() {
	id, err := parseID("550e8400-e29b-41d4-a716-446655440000")
	if err != nil {
		// 示例只把错误分类为输入问题，不把失败值送进查询。
		fmt.Println(errors.Unwrap(err))
		return
	}
	fmt.Println(id.String())
}

官方文档说明，Parse 不只接受带连字符的标准形式，也接受 urn:uuid:、纯十六进制和 Microsoft 风格的大括号形式。因此它的职责是“能否解码成 UUID”，不是“输入是否严格符合你们 API 规定的外形”。

格式化统一交给 String

一个 UUID 经过解析后，不必自己切片、补连字符或转大小写。String() 返回标准的 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 形式；当 UUID 本身无效时，文档定义的结果是空字符串，所以日志或响应前仍应确保值来自成功的解析。

package main

import (
	"fmt"

	"github.com/google/uuid"
)

func formatID(raw string) (string, error) {
	// 先解析，再统一输出，避免保留调用方传入的多种外形。
	id, err := uuid.Parse(raw)
	if err != nil {
		return "", fmt.Errorf("UUID 输入无效: %w", err)
	}
	// String 负责标准连字符格式，适合响应体、日志和下游参数。
	return id.String(), nil
}

func main() {
	for _, raw := range []string{
		"550e8400-e29b-41d4-a716-446655440000",
		"550e8400e29b41d4a716446655440000",
	} {
		formatted, err := formatID(raw)
		if err != nil {
			fmt.Println(err)
			continue
		}
		fmt.Println(formatted)
	}
}

这段代码的重点不是接受多少种输入，而是让输出只有一个约定。这样日志检索、缓存键和接口响应不会因为调用方的原始写法不同而出现两份看似不同的 ID。

为什么不能把 Parse 当成严格格式校验

这是我觉得最值得单独强调的一点：如果接口契约规定必须是小写、必须带连字符、不能接受 URN，那么仅调用 uuid.Parse 还不够。因为它会兼容多种表示，兼容解析不等于满足外部协议。

package main

import (
	"fmt"
	"regexp"

	"github.com/google/uuid"
)

var canonicalUUID = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)

func parseCanonical(raw string) (uuid.UUID, error) {
	// 先按 API 契约限制外形，再交给 uuid.Parse 负责语义解码。
	if !canonicalUUID.MatchString(raw) {
		return uuid.Nil, fmt.Errorf("UUID 不符合小写标准格式")
	}
	// 这里仍保留 Parse 的错误，因为正则只约束外形，不替代字节解析。
	id, err := uuid.Parse(raw)
	if err != nil {
		return uuid.Nil, err
	}
	return id, nil
}

正则不是所有场景都必须使用的答案。如果系统愿意兼容历史输入，可以只用 Parse；如果要做严格接口校验，再增加清晰的外形规则。关键是把“兼容读取”和“协议约束”分成两层。

MustParse 只适合可信的固定值

MustParse 在无法解析时会 panic。它适合包级变量、测试夹具或代码中已经固定且经过人工确认的常量，因为初始化失败通常应该让程序直接暴露问题。它不适合 HTTP 参数、消息队列字段或数据库中读出来的内容。

package main

import (
	"fmt"

	"github.com/google/uuid"
)

// 固定命名空间属于源码常量，启动时失败比静默使用错误 ID 更容易发现。
var namespace = uuid.MustParse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")

func main() {
	// 可信常量可以在初始化阶段直接转换，业务请求不要照搬这种写法。
	fmt.Println(namespace.String())
}

可以把选择记成一句话：Parse 面向不可信输入，MustParse 面向可信常量，String 面向统一输出。这个分工比单纯记住函数名更不容易误用。

JSON、SQL 和日志边界怎么保持一致

uuid.UUID 实现了文本和数据库相关接口，具体编码仍应结合项目的 JSON 序列化器、数据库驱动和字段类型确认。业务层可以保持一个 UUID 类型，只有在边界转换为文本或数据库值，不要让每个 handler 自己拼字符串。

type User struct {
	// UUID 类型让业务字段不再接受任意字符串。
	ID uuid.UUID `json:"id"`
}

func userFromPath(raw string) (User, error) {
	// 路由参数先解析；后续查询函数接收 User.ID，而不是 raw。
	id, err := uuid.Parse(raw)
	if err != nil {
		return User{}, fmt.Errorf("路径 ID 无效: %w", err)
	}
	return User{ID: id}, nil
}

func logUser(u User) string {
	// 日志统一走 String，避免记录请求原文造成同一 ID 多种外形。
	return "user_id=" + u.ID.String()
}

数据库场景尤其要确认驱动对字符串和二进制字段的映射。该包提供 Scan 和 Value 接口，但表字段到底是文本、二进制还是数据库原生 UUID，仍然属于项目和驱动的契约，不能只凭函数名推断。

解析与格式化速查

几个容易混淆的问题

Parse 成功就说明输入一定是标准 36 字符吗？

不是。它会接受文档列出的多种形式。需要标准外形时，先做契约约束，再调用 Parse。

解析失败后可以直接使用返回的 UUID 吗？

不应该。应先判断 error；失败时返回明确的输入错误，避免把零值或不完整语义继续传给业务。

为什么不直接保存原始字符串？

原始字符串可能有多种表示，比较、日志检索和缓存命中都更容易出现分叉。入口解析、内部用类型、出口用 String，边界会清楚很多。

什么时候应该用 MustParse？

只在源码固定、启动或初始化阶段失败就应立即暴露的常量上使用。请求参数和数据库内容永远按不可信输入处理。

如果只记住一套最小方案，就是：uuid.Parse 负责把外部文本安全地转换成类型，uuid.MustParse 只服务可信常量，uuid.UUID.String() 负责把内部值格式化为统一文本；严格 API 还要额外约束输入外形。这样解析和格式化各自只做一件事，后续换接口、日志或数据库边界时也更容易保持一致。

参考资料：https://pkg.go.dev/github.com/google/uuid、https://github.com/google/uuid。