UUID 文本与二进制格式怎样在 Go 中互转

在 Go 标准库的 uuid 包里，uuid.UUID 的底层类型是 [16]byte。因此互转规则可以浓缩成四句话：文本转 UUID 用 uuid.Parse 或 UnmarshalText；UUID 转规范文本用 String 或 MarshalText；原始二进制转 UUID 必须先确认长度恰好是 16；UUID 转二进制时按需要复制出独立切片。

最容易犯的错误，是把“文本占用的字节”和“UUID 的 16 字节原始值”当成同一种东西。规范文本例如 550e8400-e29b-41d4-a716-446655440000 有 36 个 ASCII 字节，而原始二进制永远只有 16 字节。

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

先分清三种 UUID 表示

同一个 UUID 在业务中通常有三种表示。第一种是带短横线的规范文本，共 36 个字符；第二种是去掉短横线的 32 个十六进制字符，Parse 也能接受；第三种是网络协议和紧凑存储常用的 16 字节原始二进制。

Parse 的输入范围比规范输出更宽：除了常见的带短横线形式，还能接受无短横线十六进制文本、带花括号的形式和 URN 形式。无论输入是哪种兼容形式，String 都会输出小写、带短横线的规范文本。

文本转 UUID：优先使用 Parse

处理 HTTP 参数、JSON 字段或配置字符串时，直接调用 uuid.Parse，并把错误交给上层决定如何返回。外部输入不要使用 MustParse，因为格式错误会触发 panic。

package main

import (
    "fmt"
    "uuid"
)

func parseRequestID(input string) (uuid.UUID, error) {
    // Parse 会校验格式，并接受包文档列出的多种文本形式
    id, err := uuid.Parse(input)
    if err != nil {
        return uuid.UUID{}, fmt.Errorf("请求 ID 格式错误: %w", err)
    }
    return id, nil
}

如果接收到的是文本字节，例如解码器给出的 []byte，可以使用 UnmarshalText。它接受的格式与 Parse 一致，适合实现统一的文本编解码边界。

func parseTextBytes(text []byte) (uuid.UUID, error) {
    var id uuid.UUID

    // 这里的 text 仍然是十六进制文本，不是 16 字节原始值
    if err := id.UnmarshalText(text); err != nil {
        return uuid.UUID{}, fmt.Errorf("解析 UUID 文本失败: %w", err)
    }
    return id, nil
}

UUID 转文本：String 与 MarshalText

用于日志、URL 和普通 JSON 字段时，id.String() 最直观。它输出固定的规范形式。需要满足 encoding.TextMarshaler 风格接口时使用 MarshalText，两者编码结果一致。

func formatID(id uuid.UUID) (string, []byte, error) {
    // String 返回小写、带短横线的规范文本
    canonical := id.String()

    // MarshalText 返回同一种文本编码，只是结果类型为 []byte
    text, err := id.MarshalText()
    if err != nil {
        return "", nil, fmt.Errorf("编码 UUID 文本失败: %w", err)
    }
    return canonical, text, nil
}

较新的编码接口若需要把文本追加到已有缓冲区，可以使用包提供的 AppendText；其输出同样是规范 UUID 文本。选择哪个方法取决于调用方接口，不要手工拼接短横线。

原始二进制转 UUID：先检查长度再复制

二进制输入没有分隔符或十六进制字符，它应当恰好包含 16 个字节。因为切片长度是运行时数据，转换前必须显式检查；长度不足时静默补零、长度过长时静默截断，都会制造难以追踪的数据错误。

func UUIDFromBinary(raw []byte) (uuid.UUID, error) {
    const uuidSize = 16
    if len(raw) != uuidSize {
        // 固定长度校验可以阻止截断和隐式补零
        return uuid.UUID{}, fmt.Errorf("UUID 二进制长度必须为 %d，实际为 %d", uuidSize, len(raw))
    }

    var id uuid.UUID
    // copy 将调用方切片内容复制进独立的固定长度数组
    copy(id[:], raw)
    return id, nil
}

这里使用复制有两个好处：得到的 uuid.UUID 长度由类型保证；调用方以后修改原始切片，也不会改变已经解析出的 UUID。若输入来自数据库驱动或复用缓冲区，这个所有权边界尤其重要。

UUID 转原始二进制：是否复制取决于所有权

uuid.UUID 是数组值，id[:] 可以得到长度为 16 的切片。不过把切片交给会长期持有它的代码时，最好显式复制，避免生命周期和别名关系变得模糊。

func UUIDToBinary(id uuid.UUID) []byte {
    // 返回独立切片，调用方可以安全保存或修改
    return append([]byte(nil), id[:]...)
}

func writeUUID(id uuid.UUID, dst []byte) error {
    if len(dst) 

如果切片只在当前调用中立即读取，且不会被保存，直接使用 id[:] 也可以减少一次分配。关键不是一律复制，而是明确谁拥有这段内存、谁可以修改、使用时间有多长。

在接口和存储边界选择格式

表示形式应由边界决定，而不是为了少几个字节在所有地方都使用二进制。对人和通用协议可见的边界，规范文本更容易排查；内部数据库或已有固定二进制协议，16 字节形式更紧凑。

一个可复用的边界封装

在项目中把转换集中到一个小模块，比到处写 copy 和长度判断更可靠。接口层只处理字符串，存储层只处理固定 16 字节，业务层始终使用 uuid.UUID。

type UUIDCodec struct{}

func (UUIDCodec) FromText(input string) (uuid.UUID, error) {
    // 外部文本统一走标准解析器
    return uuid.Parse(input)
}

func (UUIDCodec) ToText(id uuid.UUID) string {
    // 对外统一输出规范形式
    return id.String()
}

func (UUIDCodec) FromBinary(raw []byte) (uuid.UUID, error) {
    // 二进制边界复用固定长度校验
    return UUIDFromBinary(raw)
}

func (UUIDCodec) ToBinary(id uuid.UUID) []byte {
    // 持久化边界返回独立数据
    return UUIDToBinary(id)
}

这样设计后，数据库字段从文本改为二进制时，只需调整存储适配层；HTTP API 仍能保持规范字符串，不会把底层优化泄漏给调用方。

五个高频错误

1. 把文本字节当成原始二进制

[]byte(id.String()) 得到的是 36 个 ASCII 字节，里面包含短横线。它适合写入文本流，但绝不是数据库二进制列期待的 16 字节 UUID。

2. 把原始字节直接转成字符串

string(id[:]) 只是让任意二进制字节使用 Go 字符串承载，结果可能不可打印，也不是规范 UUID。需要可读文本时始终调用 String。

3. 不检查二进制长度

copy 不会因为源切片长度错误而自动报错。先验证恰好 16 字节，才能避免截断或补零后的错误标识。

4. 对外部输入使用 MustParse

MustParse 适合源码中由开发者控制的常量，不适合请求参数、消息或数据库内容。外部数据应返回可处理的错误，而不是让进程路径出现 panic。

5. 忽略切片的所有权

临时读取可以使用 id[:]，跨调用保存则复制。把这条规则写进转换函数，可以避免调用方无意修改共享数据。

常见问题

Parse 接受大写十六进制吗？

接受。解析器允许十六进制字母使用大小写；String 输出时会规范化为小写、带短横线的形式。

无短横线的 32 字符文本需要自己补短横线吗？

不需要。直接交给 uuid.Parse 即可，手工切片和拼接反而会增加边界错误。

标准库 uuid 包有 MarshalBinary 和 UnmarshalBinary 吗？

当前 API 提供文本编解码方法，但没有列出对应的二进制编解码方法。原始二进制应基于 uuid.UUID 的 16 字节数组表示，配合明确的长度检查和复制函数处理。

数据库应该存文本还是二进制？

取决于数据库类型、索引策略和团队运维习惯。文本更直观，16 字节更紧凑。无论选择哪种，都应在数据访问层统一转换，并避免同一列混用两套表示。

最终可以记住一个稳定边界：外部文本交给标准解析器，业务内部使用 uuid.UUID，原始二进制只在固定 16 字节的存储或协议边界出现。只要不混淆文本字节与原始字节，并明确长度和所有权，UUID 的互转就会非常直接。