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{lethex='0123456789abcdef';lettpl='xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx';returntpl.replace(/[xy]/g,(c:string):string=>{letr=Math.floor(Math.random()*16);returnhex[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）

@Statecount: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"变成"在列表中迷失"。

大小写切换

@StateuseUppercase: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（使用新的大小写设置）。

去横线

@StateuseNoDash: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(leti=0;i<this.count;i++){letuuid=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