Go 标准库 uuid 如何生成并写入数据库字段

如果项目已经升级到 Go 1.27，生成 UUID 不必再额外引入第三方包：标准库的 uuid 提供了 uuid.New()、uuid.NewV4()、uuid.NewV7()、String() 和 Parse()。真正容易出错的地方在数据库字段：uuid.UUID 本身是 16 字节数组，写入 BINARY(16) 要传字节切片，写入 CHAR(36) 才传带连字符的字符串。

先看清 uuid.UUID 和数据库列的对应关系

Go 官方文档把 UUID 定义为 [16]byte。因此它有两种常见外部表示：原始 16 字节，或者 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 形式的 36 字符文本。前者更省空间，后者更容易在日志和 SQL 客户端中阅读。

生成 UUID 后按列类型绑定参数

无须自己拼接十六进制字符串，也不要把 UUID 直接插入 SQL 文本。让驱动处理参数绑定，代码只负责选择正确的值表示。下面用 users 表演示两种列各自的写法。

-- 二进制列适合主键或高频关联字段
CREATE TABLE users_binary (
  id BINARY(16) NOT NULL PRIMARY KEY,
  email VARCHAR(255) NOT NULL
);

-- 文本列便于人工阅读和跨系统传输
CREATE TABLE users_text (
  id CHAR(36) NOT NULL PRIMARY KEY,
  email VARCHAR(255) NOT NULL
);

package user

import (
    "context"
    "database/sql"
    "fmt"
    "uuid"
)

func insertUser(ctx context.Context, db *sql.DB, email string) error {
    id := uuid.New()

    // BINARY(16) 接收 UUID 的原始 16 字节，避免先转成 36 字符文本。
    if _, err := db.ExecContext(ctx,
        "INSERT INTO users_binary (id, email) VALUES (?, ?)", id[:], email,
    ); err != nil {
        return err
    }

    // CHAR(36) 需要标准的小写十六进制加连字符表示。
    _, err := db.ExecContext(ctx,
        "INSERT INTO users_text (id, email) VALUES (?, ?)", id.String(), email,
    )
    return err
}

示例里的两个插入是为了对照列类型，真实业务通常只保留其中一种。id[:] 是对数组的切片视图，参数绑定完成后由驱动读取；不要把它改成手写十六进制，也不要把用户输入拼入 SQL。

读回时先校验格式，再交给业务层

查询结果的类型由数据库列和驱动共同决定。二进制列通常读为 []byte，文本列通常读为 string。前者必须检查长度正好为 16，后者必须让 uuid.Parse 负责格式校验。

func loadBinaryID(ctx context.Context, db *sql.DB, email string) (uuid.UUID, error) {
    var raw []byte
    err := db.QueryRowContext(ctx,
        "SELECT id FROM users_binary WHERE email = ?", email,
    ).Scan(&raw)
    if err != nil {
        return uuid.Nil(), err
    }
    if len(raw) != 16 {
        // 长度不对说明列类型、驱动返回值或数据迁移存在问题。
        return uuid.Nil(), fmt.Errorf("invalid UUID bytes: %d", len(raw))
    }

    var id uuid.UUID
    // 复制而不是保存驱动可能复用的底层切片。
    copy(id[:], raw)
    return id, nil
}

func loadTextID(ctx context.Context, db *sql.DB, email string) (uuid.UUID, error) {
    var text string
    if err := db.QueryRowContext(ctx,
        "SELECT id FROM users_text WHERE email = ?", email,
    ).Scan(&text); err != nil {
        return uuid.Nil(), err
    }

    // Parse 同时完成格式检查，失败时不要把不完整 ID 继续向下传。
    return uuid.Parse(text)
}

这里故意把二进制和文本读回拆成两个函数，避免一个函数里用类型断言猜测驱动行为。

排序需求决定是否采用 UUID v7

uuid.New() 适合只需要唯一标识的场景；当前标准库实现等价于 NewV4()，随机部分更多。若主键还承担“近似按创建时间排序”的工程需求，可以考虑 uuid.NewV7()。官方说明指出 v7 的高位包含时间戳，通常按递增顺序排列，但系统时钟回拨时不能把它当作严格时间序列。

无论选择 v4 还是 v7，数据库列类型仍按存储和运维需求决定。迁移时要同时检查：旧列是否允许空字符串、驱动返回的是 []byte 还是 string、是否存在全零的 Nil UUID，以及索引排序是否真的符合业务语义。

常见问题

Go 1.26 项目能直接 import uuid 吗？

本文写法依赖 Go 1.27 标准库的 uuid 包。旧版本项目应先确认工具链版本，再决定升级或使用项目已经批准的 UUID 依赖，不要只修改 import 路径。

BINARY(16) 一定比 CHAR(36) 更好吗？

不一定。二进制更紧凑，适合高频索引；文本更容易人工查询、日志比对和跨语言交换。最终选择取决于索引体积、排障方式和上下游协议。

为什么不直接 Scan 到 uuid.UUID？

uuid.UUID 提供文本解析方法，但数据库驱动的返回类型仍可能不同。显式接收 []byte 或 string，再检查或解析，错误边界更清楚。

依据：Go 标准库 uuid 文档与 Go 1.27 发布说明；数据库调用使用标准库 database/sql 的参数绑定和 Scan 接口。