HarmonyKit | 鸿蒙新特性实践：UUID v4 生成器的纯 ArkTS 实现

引言：开发者为什么需要随时生成 UUID

UUID 是分布式系统时代最基础的身份标识工具。测试数据的主键需要一个唯一 ID、API 请求需要一个幂等键、临时文件需要一个不会重复的文件名、数据库迁移脚本需要一个引用 ID——这些场景都需要 UUID。

在桌面端，终端里跑一行 uuidgen 就能得到一个 UUID。但在移动端，iOS 没有内置的 UUID 命令行工具，Android 的终端模拟器也不是标配。一个离线的 UUID 生成器填补了这个空白。

HarmonyKit 的 UUID 生成器实现用了不到 30 行核心算法。但由于用户实际使用中需要"批量生成"而非"一次一个"，围绕它的交互设计包含了数量选择、大小写切换、去横线选项和全量复制——这些"非算法"功能才是真正的产品价值。

项目仓库：https://atomgit.com/VON-/harmony-kit

UUID 版本简介

UUID 标准（RFC 4122）定义了五个版本。每个版本使用不同的生成策略，适用于不同的场景：

• v1：基于 MAC 地址和时间戳。优点是可保证全球唯一性（假设 MAC 地址不冲突），缺点是暴露了生成设备的 MAC 地址和时间信息——隐私问题
• v2：DCE Security 版本。类似 v1，但加入了 POSIX UID/GID。极少使用
• v3：基于命名空间的 MD5 哈希。给定相同的命名空间和名称，总是生成相同的 UUID。适合需要"确定性 UUID"的场景
• v4：基于随机数。最常用。不需要 MAC 地址、不需要时间戳、不需要命名空间。唯一性由随机数的熵保证
• v5：基于命名空间的 SHA1 哈希。和 v3 一样是确定性的，但使用 SHA1 代替 MD5

HarmonyKit 实现的是 v4。理由很简单：v4 不需要任何外部信息——不需要 MAC 地址（v1 需要）、不需要命名空间（v3/v5 需要）、不需要时间同步。纯随机数实现，离线可用，不依赖任何网络或硬件信息。

核心算法：10 行

generateUuidV4(): string {
  let hex = '0123456789abcdef';
  let tpl = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx';
  return tpl.replace(/[xy]/g, (c: string): string => {
    let r = Math.floor(Math.random() * 16);
    return hex[c === 'x' ? r : (r & 0x3) | 0x8];
  });
}

这 10 行代码包含了实现 UUID v4 的全部逻辑。逐行拆解：

let hex = '0123456789abcdef'：十六进制字符集。UUID 的 32 个非连字符位置全部从这个字符集中取值。

let tpl = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'：UUID 模板。x 是占位符——将被替换为随机十六进制字符。4 是固定的 UUID 版本号。y 是变体标识符——将被替换为 8、9、a 或 b。

tpl.replace(/[xy]/g, callback)：对模板中的每个 x 和 y 执行替换。正则 /[xy]/g 匹配所有的占位字符。

Math.floor(Math.random() * 16)：生成 0-15 的随机整数。Math.random() 返回 [0, 1) 区间的浮点数，乘以 16 后范围是 [0, 16)，Math.floor() 截断小数部分得到 0-15 的整数。

hex[c === 'x' ? r : (r & 0x3) | 0x8]：对于 x 占位符——直接使用随机值 r 作为索引。对于 y 占位符——(r & 0x3) | 0x8 将 r 的低 2 位与 1000 做按位或。r & 0x3 保留 r 的最低 2 位（0-3），然后 | 0x8 将第 3 位设为 1。结果为 8（1000）、9（1001）、10（1010）、11（1011），即十六进制的 8、9、a、b。这是 UUID v4 变体标识的标准取值。

UUID v4 的结构布局：

xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
       版本号(4)    变体(8-b)

• 第 13 位是版本号：固定为 4，表示 UUID v4
• 第 17 位是变体标识：取值范围 8-b，标识这是一个标准 UUID 变体

总共 32 个十六进制位中，版本号占 4 位（固定），变体占 2 位（限定范围），其余 122 位全部是随机位。因此 UUID v4 的唯一性空间是 2^122——约 5.3 × 10^36。这个空间如此之大，即使地球上的每一台计算机每秒生成 10 亿个 UUID 并持续 100 年，仍然几乎不可能产生碰撞。

Math.random() 的安全性说明

Math.random() 不适用于密码学场景——它的随机性由伪随机数生成器（PRNG）保证，seed 可预测，且不能抵御时序攻击。但对于 UUID v4 的用途——生成唯一标识符而非加密密钥——Math.random() 的随机性完全足够。

如果确实需要密码学安全的随机 UUID（比如用于密钥生成），应使用 cryptoFramework.createRandom() 或 cryptoFramework.Random。但 HarmonyKit 的场景是"生成测试数据 key"和"文件命名"，不需要密码学安全性。

三个交互选项

生成数量（1-50）

@State count: number = 5;

Row() {
  Button('-').width(32).height(32)
    .backgroundColor('#f0f0f0').fontColor('#333').borderRadius(6)
    .onClick(() => { if (this.count > 1) this.count--; });

  Text(String(this.count)).fontSize(16).fontWeight(FontWeight.Medium)
    .width(40).textAlign(TextAlign.Center);

  Button('+').width(32).height(32)
    .backgroundColor('#f0f0f0').fontColor('#333').borderRadius(6)
    .onClick(() => { if (this.count < 50) this.count++; });
}

默认生成 5 个 UUID，用户可以在 1-50 之间调节。为什么默认是 5 个而不是 1 个？因为开发者最常见的 UUID 使用场景是"生成一组 ID 然后粘贴到代码中"，批量生成比单个生成效率高得多。

50 的上限是为了 UI 的可控性——50 行 UUID 在移动屏幕上已经需要翻页了。如果生成 100 个或者更多，用户的注意力会从"找到需要的 UUID"变成"在列表中迷失"。

大小写切换

@State useUppercase: boolean = false;

Button(this.useUppercase ? '大写 ON' : '小写 off')
  .fontSize(11).height(28)
  .backgroundColor(this.useUppercase ? '#007aff' : '#f0f0f0')
  .fontColor(this.useUppercase ? '#ffffff' : '#333')
  .borderRadius(6).padding({ left: 10, right: 10 })
  .onClick(() => { this.useUppercase = !this.useUppercase; });

UUID 标准（RFC 4122）规定十六进制字符使用小写字母。但实际使用中——Microsoft COM 接口使用大写 UUID、某些数据库的 UUID 存储也偏爱大写。提供大小写切换纯粹是为了兼容性。

实现上就是一行 .toUpperCase()。切换后立即触发 generate() 重新生成所有 UUID（使用新的大小写设置）。

去横线

@State useNoDash: boolean = false;

Button(this.useNoDash ? '无横线 ON' : '有横线 off')
  .onClick(() => { this.useNoDash = !this.useNoDash; });

标准 UUID 格式：550e8400-e29b-41d4-a716-446655440000（4 个连字符）
无横线格式：550e8400e29b41d4a716446655440000（32 个连续十六进制字符）

某些数据库的 UUID 存储和索引使用无横线格式。实现就是 uuid.replace(/-/g, '')。

批量生成和结果展示

generate() {
  this.uuidList = [];
  for (let i = 0; i < this.count; i++) {
    let uuid = this.generateUuidV4();
    if (this.useUppercase) uuid = uuid.toUpperCase();
    if (this.useNoDash) uuid = uuid.replace(/-/g, '');
    this.uuidList.push(uuid);
  }
}

每行展示包含序号、UUID 文本和独立的复制按钮。"复制全部"按钮用 join('\n') 合并所有 UUID，一次复制整个列表。

Row() {
  Blank();
  CopyButton({ text: this.uuidList.join('\n'), btnText: '复制全部' });
}

aboutToAppear 的预生成策略

aboutToAppear() {
  this.generate();
}

页面打开时自动生成 5 个 UUID。用户看到页面时已经有了"产品"——可以立刻复制使用，也可以调整参数重新生成。空状态（空白列表）对 UUID 生成器来说没有意义——这和 JSON 格式化工具不同（空白输入等待用户粘贴 JSON）。

项目仓库：https://atomgit.com/VON-/harmony-kit