UUID v1、v4、v5 如何选择？节点标识、随机性与确定性映射

一、问题概述：UUID 版本的输入、排序与隐私属性不同

RFC 9562 定义了多个 UUID 版本。v1 组合 60 位 Gregorian 时间戳、时钟序列与 48 位节点字段；节点字段可以来自 IEEE 802 MAC，也可以按规范生成随机节点 ID。v4 的 122 个非版本/变体位来自随机或伪随机源。v5 把 Namespace 与 Name 经 SHA-1 映射成确定性 UUID。三者解决的问题不同。

二、最小复现：不同 UUID 版本的生成结构对比

下面的对比展示了 UUID v1、v4 与 v5 的字符串结构特点与确定性差异：

/* 1. UUID v1: 时间戳、时钟序列与节点字段 */
// "6c84fb90-12c4-11ee-be56-0242ac120002"
// 版本 nibble 为 1；末尾节点字段可能来自 MAC，也可能是规范允许的随机节点 ID

/* 2. UUID v4: 122 位完全密码学随机数 (最常用) */
// "f47ac10b-58cc-4372-a567-0e02b2c3d479"
// 版本 nibble 为 4；variant nibble 为 8、9、a 或 b

/* 3. UUID v5: 基于 Namespace + Name 的 SHA-1 确定性哈希 */
// 同一 Namespace 下传入相同 "user_123" 永远生成固定的 UUID v5 字符串！

三、根因分析：节点隐私、生日界与确定性映射

1. v1 隐私取决于节点来源：若实现使用真实 MAC，UUID 会暴露节点厂商线索与生成时间；使用规范允许的随机节点 ID 可降低这类风险。2. v4 碰撞是概率事件：122 位随机空间约为 2^{122}，接近 2^{61} 次生成时碰撞概率才进入生日界量级，但概率永远不是零，持久化层仍应保留唯一约束并处理重试。3. v5 是确定性映射：相同 Namespace 与 Name 必得相同 UUID；它适合稳定映射，不应当被当作不可猜测的安全令牌。

四、推荐方案：按语义选择并保留数据库约束

1. 无需排序的随机标识：使用密码学安全实现生成 v4。2. Namespace 内的稳定名称映射：使用 v5，并固定 Name 的编码与规范化规则。3. 时间有序且希望改善索引局部性：评估 RFC 9562 v7，但仍要测试暴露生成时间、同毫秒单调策略和数据库实现。4. 所有版本都不自动成为认证 Token；敏感令牌应使用专门的高熵随机方案，数据库主键仍设唯一约束。

五、完整代码：基于 Web Crypto API 模拟确定性 UUID v5 生成器

下面的 TypeScript 代码示范如何利用字符串与 Namespace 生成符合 RFC 4122 规范的确定性 UUID v5 字符串。

async function generateUUIDv5(name: string, namespaceHex: string): Promise<string> {
  const cleanNs = namespaceHex.replace(/-/g, "");
  const nsBytes = new Uint8Array(16);
  for (let i = 0; i < 16; i++) {
    nsBytes[i] = parseInt(cleanNs.substr(i * 2, 2), 16);
  }

  const encoder = new TextEncoder();
  const nameBytes = encoder.encode(name);
  const data = new Uint8Array(nsBytes.length + nameBytes.length);
  data.set(nsBytes, 0);
  data.set(nameBytes, nsBytes.length);

  const hashBuffer = await crypto.subtle.digest("SHA-1", data);
  const hashBytes = new Uint8Array(hashBuffer);

  hashBytes[6] = (hashBytes[6] & 0x0f) | 0x50;
  hashBytes[8] = (hashBytes[8] & 0x3f) | 0x80;

  const hex = Array.from(hashBytes.subarray(0, 16))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");

  return [
    hex.substring(0, 8),
    hex.substring(8, 12),
    hex.substring(12, 16),
    hex.substring(16, 20),
    hex.substring(20, 32),
  ].join("-");
}

generateUUIDv5("user_1001", "6ba7b810-9dad-11d1-80b4-00c04fd430c8").then(console.log);

六、常见错误方案

认为 UUID v4 是加密密钥（UUID 只是不重复的随机标识，不可代替对称加密 Token）；假设 UUID v4 会在短时间内频繁发生碰撞；混淆 v4 随机生成与 v5 幂等调用的应用界限。

七、边界条件：随机源质量与唯一性检测

Math.random() 不提供密码学不可预测性，但具体状态空间和碰撞表现由引擎实现决定，不能笼统说只剩“几千种组合”。生成 v4 应使用 crypto.randomUUID()、crypto.getRandomValues() 或成熟平台库；安全随机源仍不免除唯一索引与冲突处理。

八、如何验证 UUID 的格式与生成策略

可用 /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i 验证 RFC 9562 已定义版本的常见文本形式，再分别断言版本与变体位。批量无重复测试只能发现明显实现错误，不能证明未来绝不碰撞；还应检查随机 API、v5 测试向量和数据库冲突路径。

九、FAQ

问：UUID v4 会碰撞吗？答：使用高质量随机源时概率极低但不为零，数据库仍需唯一约束。

问：v5 使用 SHA-1 是否能当安全标识？答：不能。v5 的目的为确定性名称映射，不承诺不可猜测性或抗恶意碰撞；安全边界应使用适合的密码学构造。

问：v7 会替代自增主键吗？答：不一定。v7 提供按毫秒时间有序的布局和随机/单调字段选项，可能改善分布式生成与索引局部性，但存储宽度、页分裂、时间暴露和生态支持仍需实测。

十、总结

v4 适合随机标识，v5 适合稳定名称映射，v7 适合需要时间排序的分布式场景；v1 是否泄露 MAC 取决于节点字段实现。无论选择哪一版，都要保留唯一约束，并把认证 Token 与业务 ID 分开设计。