数据库中的 UUID 字节序与 Go 结果不一致怎么办

数据库里的 UUID 和 Go 打印出来不一致，通常不是 UUID 被“重新生成”了，而是同一组 16 字节在链路中被换了顺序。最常见的分界点是 MySQL 的 UUID_TO_BIN(uuid, 1)：它会交换时间字段，适合特定的 UUID v1 索引场景；Go 的 github.com/google/uuid 默认按解析到的标准字节顺序保存。先统一字段契约，再决定是否使用交换布局，问题就能稳定复现和修复。

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

先把字符串、16 字节和数据库字段分开

标准 UUID 文本由五组十六进制字符组成，Go 包中的 UUID 是长度为 16 的字节数组。文本里的连字符、大小写不会改变 UUID；真正决定一致性的，是从左到右的 16 个字节是否相同。排查时至少记录三份值：

下面的 Go 片段只做内存层面的对照，不代表真实运行截图。FromBytes 要求输入恰好 16 字节；这一步失败时，应先检查驱动返回的是文本还是二进制。

package main

import (
    "encoding/hex"
    "fmt"

    "github.com/google/uuid"
)

func main() {
    // 统一从标准 UUID 文本解析，避免手工反转字段。
    u, err := uuid.Parse("6ccd780c-baba-1026-9564-5b8c656024db")
    if err != nil {
        panic(err) // 示例中直接终止；服务代码应把错误返回给调用方。
    }

    // String 是可读形式，切片内容才是写入 BINARY(16) 时要对照的字节。
    raw, err := u.MarshalBinary()
    if err != nil {
        panic(err) // UUID 的固定长度通常不会失败，但仍保留错误边界。
    }
    fmt.Println(u.String())
    fmt.Println(hex.EncodeToString(raw))
}

MySQL 的 swap_flag 不能在读写两端混用

MySQL 文档规定，UUID_TO_BIN(uuid, 0) 保持字符串的字节顺序；当第二个参数为 1 时，会交换第一组和第三组时间字段。该优化主要针对 UUID v1，不能把它当成所有 UUID 的通用“大小端修复”。

SET @id = '6ccd780c-baba-1026-9564-5b8c656024db';

-- 0 表示保持 canonical 顺序，适合和 Go 的 MarshalBinary 直接对照。
SELECT HEX(UUID_TO_BIN(@id, 0));

-- 1 会交换 time-low 与 time-high，只有确认整条链路采用该布局时才使用。
SELECT HEX(UUID_TO_BIN(@id, 1));

-- 读取时必须使用与写入相同的标志，才能还原原始文本。
SELECT BIN_TO_UUID(UUID_TO_BIN(@id, 0), 0);
SELECT BIN_TO_UUID(UUID_TO_BIN(@id, 1), 1);

如果写入使用了 UUID_TO_BIN(@id, 1)，读取却调用不带参数的 BIN_TO_UUID(id)，返回的文本会出现字段错位。反过来也一样。工程上应把这个标志写进数据访问层的固定配置，而不是散落在每条 SQL 中。

Go 与 BINARY(16) 统一成可逆读写链路

如果字段是 CHAR(36)，直接传 u.String() 最直观；如果字段是 BINARY(16) 或 VARBINARY(16)，就明确传 16 字节。下面的写法不依赖驱动替你猜测字节序：

func insertAndRead(ctx context.Context, db *sql.DB, id uuid.UUID) (uuid.UUID, error) {
    // BINARY(16) 接收原始 16 字节，不在 Go 侧做字段交换。
    raw, err := id.MarshalBinary()
    if err != nil {
        return uuid.Nil, err
    }
    if _, err = db.ExecContext(ctx, `INSERT INTO orders (id) VALUES (?)`, raw); err != nil {
        return uuid.Nil, err // 生产代码应让事务或上层决定是否重试。
    }

    var stored []byte
    // 扫描为 []byte，避免把二进制列误转成带不可见字符的字符串。
    if err = db.QueryRowContext(ctx, `SELECT id FROM orders WHERE id = ?`, raw).Scan(&stored); err != nil {
        return uuid.Nil, err
    }
    got, err := uuid.FromBytes(stored)
    if err != nil {
        return uuid.Nil, err // 长度不是 16 时，优先修复字段或驱动映射。
    }
    return got, nil
}

如果系统已经决定用 MySQL 的交换布局，Go 代码不能直接把 MarshalBinary() 的结果当成交换后的字节。应在数据访问层集中做一次明确的布局转换，并在读取时逆向转换；不要在业务对象、JSON 序列化和缓存层重复反转。

历史数据混用时按这张清单排查

1. 确认列类型：CHAR(36)、BINARY(16) 与 VARBINARY(16) 的读取形态不同。
2. 抽取同一条记录的原始文本、HEX(id)、Go 原始字节，先判断是否只是大小写或连字符差异。
3. 搜索所有 UUID_TO_BIN、BIN_TO_UUID 调用，记录是否传了 1。
4. 验证一个固定样本的四种组合，确认写入和读取使用同一 swap_flag。
5. 若旧数据有两种布局，不要直接全表回填；先增加版本标记或按批次迁移，并让读路径短期兼容。

相关问题

Go 的 UUID 字符串大小写不同，算字节序错误吗？

不算。十六进制大小写和连字符只影响展示；用规范化文本或比较 16 字节内容即可。

UUID_TO_BIN(uuid, 1) 能用于随机 UUID v4 吗？

不建议把它当成通用优化。MySQL 文档说明时间字段交换假设 UUID v1 的布局，随机 UUID v4 使用它不会得到同样的索引收益。

为什么 Go 的 Scan 有时拿到字符串，有时拿到 []byte？

这取决于数据库列类型和驱动返回值。先查看字段定义与驱动文档，再分别处理文本解析和 16 字节解析，不要靠强制类型断言掩盖差异。