Kotlin 语言参考文档 中文版 Help

UUID

Uuid 类表示通用唯一标识符 (Universally Unique Identifier, UUID), 也称为全局唯一标识符 (Globally Unique Identifier, GUID).

Uuid 是一个 128 位的值, 用于在不依赖集中式 ID 分配系统的情况下, 唯一标识一个实体. 这使得 UUID 在分布式应用程序, 数据库, 客户端生成的记录, 或 Kotlin Multiplatform 应用程序中非常有用.

请使用 Uuid 类来处理 UUID 值. 与普通字符串不同, 专用的 UUID 类型能够让你的代码更加明确, 并防止意外使用无效的值.

要在你的项目中使用 UUID, 请从 kotlin.uuid 包导入 Uuid 类:

import kotlin.uuid.Uuid

生成 UUID

要生成一个随机的版本 4 的 UUID 用做通常的标识符 (例如用户或数据库 ID), 请使用 Uuid.random() 函数:

import kotlin.uuid.Uuid fun main() { //sampleStart val id = Uuid.random() println(id) //sampleEnd }

你还可以使用以下 实验性 函数, 生成特定版本的 UUID:

这些 UUID 生成函数是实验性的. 要选择使用者同意, 请使用 @OptIn(ExperimentalUuidApi::class) 注解, 或在你的构建文件中添加以下编译器选项:

kotlin { compilerOptions { freeCompilerArgs.add("-opt-in=kotlin.uuid.ExperimentalUuidApi") } }
<build> <plugins> <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <configuration> <args> <arg>-opt-in=kotlin.uuid.ExperimentalUuidApi</arg> </args> </configuration> </plugin> </plugins> </build>

下面的示例生成指定版本的 UUID:

import kotlin.time.Instant import kotlin.time.ExperimentalTime import kotlin.uuid.Uuid @OptIn(kotlin.uuid.ExperimentalUuidApi::class, ExperimentalTime::class) fun main() { // 生成版本 4 的 UUID val idVersion4 = Uuid.generateV4() println(idVersion4) // 生成版本 7 的 UUID val idVersion7 = Uuid.generateV7() println(idVersion7) // 为指定时间戳生成版本 7 的 UUID val timestamp = Instant.fromEpochMilliseconds(1757440583000L) val idVersion7SpecificTime = Uuid.generateV7NonMonotonicAt(timestamp) println(idVersion7SpecificTime) }

解析 UUID

UUID 值通常以字符串形式表示, 例如在 URL 参数或数据库记录中.

要将 String 值转换为 Uuid 值, 请使用 Uuid.parse() 函数:

import kotlin.uuid.Uuid fun main() { //sampleStart val id = Uuid.parse("de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a") println(id) //sampleEnd }

Uuid.parse() 函数接受标准的 16 进制加横线分隔符格式, 以及不带横线分隔符的 16 进制格式.

如果输入无效, Uuid.parse() 函数会抛出 IllegalArgumentException 异常:

import kotlin.uuid.Uuid fun main() { //sampleStart val id = Uuid.parse("10") println(id) //sampleEnd }

如果你的应用程序只接受一种表示形式, 请使用特定格式的函数:

例如:

import kotlin.uuid.Uuid fun main() { //sampleStart val standard = Uuid.parseHexDash("de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a") val compact = Uuid.parseHex("de2bc56cea734f3c8a375a46fdb2d79a") println(standard) println(compact) //sampleEnd }

如果你有来自外部来源的 UUID, 并且必须安全地处理无效输入, 请使用 Uuid.parseOrNull(), Uuid.parseHexDashOrNull(), 或 Uuid.parseHexOrNull() 函数. 这些函数在输入无效时会返回 null:

fun parseId(input: String): Uuid? { return Uuid.parseOrNull(input) }

将 UUID 转换为字符串

你可以使用以下函数, 将 Uuid 值转换为 String 值:

例如:

import kotlin.uuid.Uuid fun main() { //sampleStart val id = Uuid.parse("de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a") println(id.toString()) // 输出结果为: de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a println(id.toHexDashString()) // 输出结果为: de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a println(id.toHexString()) // 输出结果为: de2bc56cea734f3c8a375a46fdb2d79a //sampleEnd }

比较 UUID

你可以使用 == 运算符, 检查 Uuid 值是否相等.

Kotlin 根据 UUID 值进行比较, 而不是根据文本表示. 例如, 如果不同形式的两个值表示相同的 128 位值, 则判定为相等:

import kotlin.uuid.Uuid fun main() { //sampleStart val first = Uuid.parse("de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a") val second = Uuid.parse("de2bc56cea734f3c8a375a46fdb2d79a") println(first == second) // 输出结果为: true //sampleEnd }

这使得 Uuid 的比较比字符串比较更可靠, 因为字符串比较会将相同值的不同格式视为不同. Uuid 比较检查的是实际的标识符值.

Uuid 实现了 Comparable<Uuid> 接口, 因此 UUID 值可以使用标准的集合函数(例如 sorted()) 进行排序. 在这种情况下, Kotlin 按字典序比较值 (从最高有效位到最低有效位):

import kotlin.uuid.Uuid fun main() { //sampleStart val first = Uuid.generateV7() val second = Uuid.generateV7() val sorted = listOf(first, second).sorted() println(sorted) //sampleEnd }

使用二进制表达

某些 API, 存储格式, 以及二进制协议, 不以字符串形式表示 UUID. 相反, 它们将 128 位 UUID 值存储为:

  • 16 字节数组

  • 两个 64 位值

当你需要与期望二进制 UUID 数据的系统交换 UUID 时, 请使用这些表达.

要在 UUID 和 16 字节表达之间进行转换, 请使用 .toByteArray() 和 Uuid.fromByteArray() 函数:

import kotlin.uuid.Uuid fun main() { //sampleStart val id = Uuid.random() val bytes = id.toByteArray() val original = Uuid.fromByteArray(bytes) println(id) println(bytes) println(original) println(id == original) // 输出结果为: true //sampleEnd }

也可以将相同的 128 位 UUID 值表示为 2 个 Long 值. 这很有用, 因为 Kotlin 没有提供内置的 128 位整数类型. 这 2 个 Long 值将 UUID 分为 2 部分存储:

  • mostSignificantBits 参数, 存储 UUID 的前 64 位.

  • leastSignificantBits 参数, 存储 UUID 的后 64 位.

要从 2 个 Long 值创建 Uuid 值, 请使用 Uuid.fromLongs() 函数:

import kotlin.uuid.Uuid fun main() { //sampleStart val id = Uuid.fromLongs( mostSignificantBits = -4653685776373167443, leastSignificantBits = -6288180676521310383.toLong() ) println(id) // 输出结果为: bf6ac971-52fd-4aad-a8bb-e4fdac78c751 //sampleEnd }

要从现有的 Uuid 值中提取 2 个部分, 请使用 Uuid.toLongs() 函数:

import kotlin.uuid.Uuid fun main() { //sampleStart val id = Uuid.random() id.toLongs { mostSignificantBits, leastSignificantBits -> println(mostSignificantBits) println(leastSignificantBits) } //sampleEnd }

序列化 UUID

Kotlin 支持对 Uuid 值进行序列化. 使用这个功能, 可以在 Kotlin 代码之外存储或传输 UUID 值, 例如在 JSON API 中, 或在配置文件中.

要序列化 Uuid 值, 请将其表示为字符串, 除非你的应用程序需要其他格式. kotlinx.serialization 库使用 16 进制加横线分隔符格式:

//sampleStart import kotlin.uuid.Uuid import kotlinx.serialization.Serializable import kotlinx.serialization.encodeToString import kotlinx.serialization.json.Json @Serializable data class User( val id: Uuid, val name: String ) fun main() { val user = User( id = Uuid.parse("de2bc56cea734f3c8a375a46fdb2d79a"), name = "Kotlin" ) println(Json.encodeToString(user)) // 输出结果为: {"id":"de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a","name":"Kotlin"} } //sampleEnd

在 Java API 中使用 UUID

Java 使用 java.util.UUID 类来表示 UUID. 在 JVM 上, Java API 可能接受或返回此类型. 尽管 java.util.UUID 和 kotlin.uuid.Uuid 都表示 UUID, 但它们是两种不同的类型.

要在 Kotlin 和 Java 之间传递 UUID, 请进行明确的转换:

  • 使用 .toKotlinUuid() 扩展函数, 将 Java UUID 转换为 Kotlin:

    import kotlin.uuid.toKotlinUuid val kotlinId: Uuid = javaId.toKotlinUuid()

  • 使用 .toJavaUuid() 扩展函数, 将 Kotlin UUID 转换为 Java:

    import kotlin.uuid.toJavaUuid val javaId: java.util.UUID = kotlinId.toJavaUuid()

通过这些函数, 你可以在 JVM 互操作边界处使用 Uuid 来表示 UUID 值.

Kotlin 还提供了对 Java 缓冲区的支持. 请使用 JVM 专用的函数, 在 ByteBuffer 中操作 UUID:

  • 使用 .getUuid() 函数, 从缓冲区读取 UUID.

  • 使用 .putUuid() 函数, 将 UUID 写入缓冲区.

2026/08/12
时间测量协程指南