Go UUID 怎样在二进制协议中读写 UUID 的十六字节表示

二进制协议里的 UUID，推荐固定为连续的 16 个原始字节。使用 github.com/google/uuid 时，发送端调用 MarshalBinary，接收端按 16 字节读满后调用 UnmarshalBinary；不要把 550e8400-e29b-41d4-a716-446655440000 这类 36 字符文本直接塞进同一个字段。

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

线路格式先约定“UUID 字段长度为 16”，再处理读写。ParseBytes 适合解析文本表示，二进制协议则应使用 Binary 方法，并把半包、短写和长度错误交给协议层处理。

先把 UUID 字段固定成 16 个原始字节

google/uuid 的 UUID 类型是 [16]byte。这意味着二进制协议不需要为 UUID 重新设计十六进制编码，也不需要对 16 个字节整体套一次整数的大小端转换。真正需要写入线路的是这 16 个八位组；连字符、花括号和 urn:uuid: 都属于文本表示层。

如果协议设计成“前面一个长度字段，后面跟 UUID”，长度字段描述的是 UUID 字段本身的 16，而不是字符串长度 36。若协议还有版本、类型或校验和，也应把它们作为独立字段写在帧格式中，避免接收方无法判断 UUID 的起止位置。

发送端用 MarshalBinary 得到可写入线路的字节

MarshalBinary 实现了 encoding.BinaryMarshaler，返回的切片长度为 16。下面的辅助函数处理 Writer 可能出现的短写：即使没有错误，也不能忽略实际写入的字节数。

package wire

import (
    "io"

    "github.com/google/uuid"
)

func writeFull(w io.Writer, data []byte) error {
    for len(data) > 0 {
        // Writer 可能只接受前半段，必须从剩余切片继续写。
        n, err := w.Write(data)
        if err != nil {
            return err
        }
        if n == 0 {
            // 防止异常 Writer 让循环永久停留在原地。
            return io.ErrShortWrite
        }
        data = data[n:]
    }
    return nil
}

func writeUUID(w io.Writer, id uuid.UUID) error {
    // Binary 形式就是固定的十六字节字段，不转成带连字符的文本。
    raw, err := id.MarshalBinary()
    if err != nil {
        return err
    }
    return writeFull(w, raw)
}

对于已经明确不会短写的内存缓冲区，直接 buf.Write(raw) 也可以；跨 socket、压缩层或自定义 Writer 时，保留完整写入逻辑更稳妥。这里的字节顺序不是把 UUID 当作 uint64 或 uint128 转换，而是保持库给出的 16 个字节原样发送。

接收端用 io.ReadFull 解决半包，再调用 UnmarshalBinary

网络 Reader 一次只返回部分数据是正常现象。接收端应先准备长度为 16 的缓冲区，让 io.ReadFull 负责持续读取；缓冲区填满后，UnmarshalBinary 会再次以长度 16 作为边界检查。

func readUUID(r io.Reader) (uuid.UUID, error) {
    var raw [16]byte
    // ReadFull 会持续读取，直到 16 字节填满或返回 EOF/底层错误。
    if _, err := io.ReadFull(r, raw[:]); err != nil {
        return uuid.Nil, err
    }

    var id uuid.UUID
    // UnmarshalBinary 只接受长度为 16 的原始 UUID 字段。
    if err := id.UnmarshalBinary(raw[:]); err != nil {
        return uuid.Nil, err
    }
    return id, nil
}

如果协议在 UUID 前有长度字段，先读取并检查长度，再读取对应 payload；不要把任意长度的 payload 直接交给 UnmarshalBinary。长度不是 16 时，错误应让当前帧失败，不能静默截断或补零，否则后续字段会从错误偏移继续解析。

用往返检查确认没有混入文本或大小端逻辑

测试时可以把一个 UUID 写入 bytes.Buffer，再读回并比较 id == got；同时补一组 15 字节和 17 字节输入，确认长度边界不会被悄悄放宽。这样验证的是协议约定和库 API 的组合，不需要把示例误认为某个真实服务的抓包结果。

结论

Go UUID 写入二进制协议的核心是保持格式简单：线路字段固定 16 字节，发送端用 MarshalBinary 并处理短写，接收端用 io.ReadFull 处理半包，再用 UnmarshalBinary 校验长度。只要把文本表示、帧长度和 UUID 原始字节分开，跨语言实现就有清晰且可测试的边界。

相关问题

为什么不能直接写 id.String？

String 生成的是带连字符的文本表示，通常占 36 个 ASCII 字节；它和协议约定的 16 字节原始字段不是同一种格式。只有协议明确规定传文本时，才应发送字符串。

UnmarshalBinary 为什么报 got 15 bytes？

这表示当前切片没有满足 UUID 的固定长度约定。检查帧长度、读取循环和前置字段偏移，不能通过补零或截断来掩盖半包、错位或协议版本不一致。