Java Uuid Generator (JUG) 技术文档

本文档将详细介绍如何安装和使用 Java Uuid Generator (JUG)，并包括项目 API 使用文档以及安装方式。

1. 安装指南

JUG 支持通过 Maven 和 Gradle 进行安装。

Maven 安装

在 Maven pom.xml 文件中添加以下依赖：

<dependency>
  <groupId>com.fasterxml.uuid</groupId>
  <artifactId>java-uuid-generator</artifactId>
  <version>5.1.0</version>
</dependency>

Gradle 安装

在 Gradle build.gradle 文件中添加以下依赖：

implementation 'com.fasterxml.uuid:java-uuid-generator:5.1.0'

2. 项目的使用说明

JUG 可以作为命令行工具使用，也可以作为可插入的组件。

生成 UUID

JUG 的主要用途是生成 UUID 值。首先选择要使用的生成器类型，然后调用其 generate() 方法。以下是一些示例：

UUID uuid = Generators.timeBasedGenerator().generate(); // 版本 1
UUID uuid = Generators.randomBasedGenerator().generate(); // 版本 4
UUID uuid = Generators.nameBasedGenerator().generate("要哈希的字符串"); // 版本 5
// 从 JUG 4.1+ 开始：支持 https://github.com/uuid6/uuid6-ietf-draft 版本 6 和 7:
UUID uuid = Generators.timeBasedReorderedGenerator().generate(); // 版本 6
UUID uuid = Generators.timeBasedEpochGenerator().generate(); // 版本 7
// 从 JUG 5.0 添加的变体：
UUID uuid = Generators.timeBasedEpochRandomGenerator().generate(); // 版本 7，每次调用带有随机值

如果需要自定义生成器，可以保留生成器实例：

TimeBasedGenerator gen = Generators.timeBasedGenerator(EthernetAddress.fromInterface());
UUID uuid = gen.generate();
UUID anotherUuid = gen.generate();

如果你的机器有一个标准的 IP 网络设置，Generators.defaultTimeBasedGenerator（从 JUG 4.2 添加）工厂方法将尝试确定哪个网络接口对应于所有外出网络流量的默认路由，并使用该接口创建基于时间的生成器。如果你想要版本 1 的 UUID 生成器，这通常是一个不错的选择。

TimeBasedGenerator gen = Generators.defaultTimeBasedGenerator();
UUID uuid = gen.generate();
UUID anotherUuid = gen.generate();

生成器是完全线程安全的，因此可以在多个线程之间共享单个实例。

转换 java.util.UUID 值为 byte[]

有时你可能需要将 java.util.UUID 转换为外部序列化形式，例如 String 或字节数组 (byte[])。转换为 String 很简单，可以使用 UUID.toString()（由 JDK 提供）。但是，没有直接的功能将 UUID 转换为 byte[]。

但是 UUIDUtil 类提供了高效的转换方法：

byte[] asBytes = UUIDUtil.asByteArray(uuid);
// 或者如果你已经有了一个更长的缓冲区
byte[] outputBuffer = new byte[1000];
// 在位置 #100 添加
UUIDUtil.toByteArray(uuid, outputBuffer, 100);

从 String、byte[] 构造 java.util.UUID 值

UUID 值通常以 Java String 或 byte[]（字节数组）的形式传递，并且需要转换为实际的 java.util.UUID 实例。JUG 提供了优化的转换功能，通过 UUIDUtil 类（包 com.fasterxml.uuid.impl）使用，如下所示：

UUID uuidFromStr = UUIDUtil.uuid("ebb8e8fe-b1b1-11d7-8adb-00b0d078fa18");
byte[] rawUuidBytes = ...; // 包含 16 字节的字节数组
UUID uuidFromBytes = UUIDUtil.uuid(rawUuidBytes)

请注意，虽然 JDK 提供了从 String 构造 UUID 的功能，如 UUID.fromString("ebb8e8fe-b1b1-11d7-8adb-00b0d078fa18")，但它的速度较慢。有关更多信息，请阅读 Measuring performance of Java UUID.fromString()。

3. 项目 API 使用文档

JUG 的 API 使用文档可以在项目的 GitHub Wiki 上找到。这里提供了一些基本的使用示例：

• 生成 UUID
• 转换 java.util.UUID 为 byte[]
• 从 String、byte[] 构造 java.util.UUID

有关更多详细信息和示例，请参考项目 Wiki。

4. 项目安装方式

项目的安装方式已在“安装指南”部分中说明，可以通过 Maven 或 Gradle 进行安装。具体步骤如下：

• Maven：在 pom.xml 文件中添加依赖。
• Gradle：在 build.gradle 文件中添加依赖。

以上就是 Java Uuid Generator (JUG) 的技术文档，希望对您有所帮助。