标准库 Uuid Kotlin 2.0.20+

源：Kotlin standard library - Uuid

在 Kotlin 2.0.20 之前，处理 UUID (Universally Unique Identifier) 通常依赖于 Java 的 java.util.UUID 或其他平台的特定实现。这在 Kotlin Multiplatform (KMP) 项目中导致了额外的样板代码或依赖第三方库。

Kotlin 2.0.20 引入了 kotlin.uuid.Uuid 类，提供了一个纯 Kotlin、跨平台、高性能的 UUID 实现，支持生成、解析和格式化 UUID。

核心特性

• 跨平台一致性：在 JVM, Native, JS, Wasm 上行为一致。
• 符合标准：完全遵循 RFC 4122 标准。
• 性能优化：针对各平台进行了底层优化，特别是在字符串解析和序列化方面。
• 类型安全：实现了 Comparable 接口，支持自然排序。

基础用法

生成 UUID

目前标准库主要支持生成 版本 4 (基于随机数) 的 UUID，这是最常用的版本。

import kotlin.uuid.Uuid

// 生成一个新的随机 UUID (v4)
val randomId = Uuid.random()

println(randomId) 
// 输出示例: 550e8400-e29b-41d4-a716-446655440000

解析字符串

支持解析标准的 36 字符格式（带连字符）和 32 字符格式（不带连字符）。

标准格式

val uuidString = "550e8400-e29b-41d4-a716-446655440000"
val uuid = Uuid.parse(uuidString)

无连字符

val hexString = "550e8400e29b41d4a716446655440000"
val uuidFromHex = Uuid.parseHex(hexString)

安全解析

// 如果格式无效，返回 null 而不是抛出异常
val safeUuid = Uuid.parseOrNull("invalid-uuid") // null

格式化输出

val id = Uuid.random()

// 标准格式 (8-4-4-4-12)
println(id.toString()) 
// "550e8400-e29b-41d4-a716-446655440000"

// 十六进制格式 (32 chars)
println(id.toHexString()) 
// "550e8400e29b41d4a716446655440000"

进阶操作

字节操作

在网络传输或数据库存储时，直接操作字节通常比字符串更高效。Uuid 占用 16 个字节（128 位）。

val id = Uuid.random()

// 转换为字节数组
val bytes: ByteArray = id.toByteArray()

// 从字节数组重建
val restoredId = Uuid.fromByteArray(bytes)

从 Long 构建

UUID 本质上由两个 64 位的 Long 组成（高位和低位）。

val mostSigBits = 123456789L
val leastSigBits = 987654321L

val id = Uuid.fromLongs(mostSigBits, leastSigBits)

与 Java UUID 互操作 (JVM)

在 JVM 平台上，可能需要与遗留的 java.util.UUID 进行交互。虽然 Kotlin 的 Uuid 是独立实现的，但转换非常简单。

Kotlin to Java

import kotlin.uuid.Uuid
import kotlin.uuid.toJavaUuid

val kotlinUuid = Uuid.random()
val javaUuid: java.util.UUID = kotlinUuid.toJavaUuid()

Java to Kotlin

import java.util.UUID
import kotlin.uuid.toKotlinUuid

val javaUuid = UUID.randomUUID()
val kotlinUuid: kotlin.uuid.Uuid = javaUuid.toKotlinUuid()

最佳实践

1. KMP 项目首选：在任何多平台代码中，无条件使用 kotlin.uuid.Uuid。
2. 数据库实体 ID：配合 @Serializable (kotlinx.serialization) 使用时，能够直接序列化为字符串，无需额外的 Serializer（需确认 serialization 库版本支持或自定义 serializer）。
3. 避免手动构造：尽量使用 Uuid.random() 或 Uuid.parse()，避免手动位操作构造 UUID，除非你非常清楚 RFC 4122 的版本和变体位要求。