Go UUID 怎样生成按时间排序的 UUID v7

如果订单、事件或日志主键既希望保持 UUID 的分布式生成能力，又希望新记录按创建时间大致聚拢，可以在 Go 中使用 github.com/google/uuid 的 NewV7。它把 Unix 毫秒时间放在高位，其余位置保留随机性，因此比纯随机的 UUID v4 更适合按标识符做时间范围排序。

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

最小用法是调用 uuid.NewV7() 并检查 error；但“按时间排序”只表示时间前缀带来的排序倾向，不等于多节点、多进程下的严格全局递增序列。

先把 UUID v7 的排序语义说清楚

UUID v7 仍然是 128 位标识符。RFC 9562 规定，它的最高 48 位使用 Unix 毫秒时间戳，随后是版本位和随机字段。于是，来自不同时间点的 UUID 通常可以按二进制值或规范化字符串顺序排列，较新的记录更容易落在后面。

这解决的是索引局部性和时间范围检索的一个实际问题，不是给业务提供一个连续序号。同一毫秒内生成的值仍然依赖随机部分；多节点时钟不同、系统时钟回拨或数据库使用了不同的字符排序规则，都可能让“看起来递增”不再严格成立。

用 NewV7 生成一个可入库的标识

先在项目中添加依赖，再把生成动作收拢到一个小函数。这样业务层不需要到处判断空 UUID，也方便统一记录生成失败的原因。

# 添加官方 Go UUID 包，版本由项目的 go.mod 记录
go get github.com/google/uuid

package identity

import (
    "fmt"

    "github.com/google/uuid"
)

// CreateID 只负责生成一个新的 UUID v7，不把数据库写入混在这里。
func CreateID() (uuid.UUID, error) {
    // NewV7 使用当前 Unix 毫秒时间并返回可能的随机源错误。
    id, err := uuid.NewV7()
    if err != nil {
        // 返回包装后的错误，让上层日志保留失败原因和调用边界。
        return uuid.Nil, fmt.Errorf("create uuid v7: %w", err)
    }
    return id, nil
}

调用方拿到 uuid.UUID 后，可以按驱动需要传递二进制值或字符串。若数据库字段使用文本类型，id.String() 会得到标准的五段十六进制表示；若使用二进制字段，则应让驱动按 16 字节值写入，避免在业务层反复转换。

把生成逻辑放进生产边界

我在服务中更倾向于让“生成 ID”和“持久化实体”保持两个清晰边界：生成失败时立即返回，不创建带空 ID 的对象；写入成功后再把 ID 放进日志字段。日志里记录 ID、请求相关的内部追踪字段和错误类型即可，不要把完整请求体、令牌或个人数据拼进错误消息。

func NewOrderID() (uuid.UUID, error) {
    // 订单对象在进入仓储层前必须已经拥有非 Nil 主键。
    id, err := CreateID()
    if err != nil {
        // 上层日志应记录稳定的事件名，避免把敏感输入带入日志。
        return uuid.Nil, err
    }
    return id, nil
}

func IsUsableID(id uuid.UUID) bool {
    // Nil UUID 代表未生成成功，不能当作业务主键保存。
    return id != uuid.Nil
}

如果业务真的需要严格的先后关系，应额外保存 created_at、数据库序列或带约束的业务版本号。UUID v7 适合提供“可按时间聚拢的全局标识”，不应该承担支付流水号、库存版本号这类需要强顺序语义的职责。

发布前检查四个容易漏掉的点

1. 依赖边界：确认 go.mod 中的 github.com/google/uuid 版本已被提交，构建环境不会偷偷拉取另一份依赖。
2. 错误路径：确认 NewV7 的 error 会向上传递，失败时不会把 uuid.Nil 写入数据库。
3. 字段语义：UUID 字段用于唯一标识，时间范围查询仍使用明确的时间列和索引，不把字符串排序当业务时间。
4. 排序边界：在多节点和高并发场景中，把 UUID v7 描述为“时间有序倾向”，不要在接口文档中承诺严格递增。

最后，保留一条稳定的错误事件名，例如 identity.uuid_v7.create_failed，让监控能区分随机源、依赖配置或应用调用错误。这样即使未来更换 UUID 实现，业务代码仍只依赖自己的生成边界。

相关问题

UUID v7 能完全替代 created_at 吗？

不能。UUID v7 的时间前缀适合做排序线索，但业务审计、报表和时间范围条件仍应保存明确的时间字段。

同一毫秒生成的 UUID v7 会连续递增吗？

不要这样假设。同一毫秒内的随机字段主要用于区分标识，排序结果不等于连续序列。

什么时候继续使用 UUID v4？

如果只需要随机唯一标识且不关心时间局部性，UUID v4 仍然简单直接；是否改用 v7 应结合索引、查询和兼容要求决定。