225 lines
5.7 KiB
Markdown
225 lines
5.7 KiB
Markdown
# UUID生成器使用说明
|
||
|
||
## 概述
|
||
|
||
本项目提供了完整的UUID生成工具，特别支持基于SHA-1哈希的UUID V5（确定性UUID）。
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
src/main/java/com/caiji/uls/utils/uuid/
|
||
├── UuidV5Generator.java # UUID V5核心生成器
|
||
└── UuidUtil.java # UUID通用工具类
|
||
|
||
src/main/java/com/caiji/uls/controller/
|
||
└── UuidTestController.java # 测试控制器
|
||
```
|
||
|
||
## UUID V5特性
|
||
|
||
UUID V5的主要特点：
|
||
- **确定性**：相同的命名空间和名称总是生成相同的UUID
|
||
- **可重现**：不需要存储UUID，可以随时重新生成
|
||
- **唯一性**：不同名称生成不同的UUID
|
||
- **基于SHA-1**：使用SHA-1哈希算法确保分布均匀
|
||
|
||
## 主要功能
|
||
|
||
### 1. 生成随机UUID（V4）
|
||
|
||
```java
|
||
// 标准格式（带横杠）
|
||
String uuid = UuidUtil.generateRandomUuid();
|
||
// 输出: 550e8400-e29b-41d4-a716-446655440000
|
||
|
||
// 不带横杠
|
||
String uuid = UuidUtil.generateRandomUuidWithoutHyphens();
|
||
// 输出: 550e8400e29b41d4a716446655440000
|
||
```
|
||
|
||
### 2. 生成UUID V5（基础用法）
|
||
|
||
```java
|
||
// 使用默认URL命名空间
|
||
String uuid = UuidUtil.generateUuidV5("example-name");
|
||
|
||
// 使用自定义命名空间
|
||
UUID customNamespace = UUID.fromString("12345678-1234-5678-1234-567812345678");
|
||
String uuid = UuidUtil.generateUuidV5(customNamespace, "example-name");
|
||
```
|
||
|
||
### 3. 基于用户信息生成确定性UUID
|
||
|
||
```java
|
||
// 基于用户名
|
||
String userUuid = UuidUtil.generateUserUuid("john_doe");
|
||
|
||
// 基于邮箱
|
||
String emailUuid = UuidUtil.generateEmailUuid("john@example.com");
|
||
|
||
// 基于手机号
|
||
String phoneUuid = UuidUtil.generatePhoneUuid("13800138000");
|
||
```
|
||
|
||
**重要**：同一用户信息始终生成相同的UUID，适合用作稳定的用户标识符。
|
||
|
||
### 4. 使用UUID V5生成器的高级功能
|
||
|
||
```java
|
||
// DNS命名空间
|
||
UUID dnsUuid = UuidV5Generator.generateFromDns("example.com");
|
||
|
||
// URL命名空间
|
||
UUID urlUuid = UuidV5Generator.generateFromUrl("https://example.com");
|
||
|
||
// OID命名空间
|
||
UUID oidUuid = UuidV5Generator.generateFromOid("1.2.3.4");
|
||
|
||
// X.500命名空间
|
||
UUID x500Uuid = UuidV5Generator.generateFromX500("CN=John Doe, O=Example");
|
||
```
|
||
|
||
### 5. 验证UUID格式
|
||
|
||
```java
|
||
// 验证UUID格式
|
||
boolean isValid = UuidUtil.isValidUuid("550e8400-e29b-41d4-a716-446655440000");
|
||
|
||
// 获取UUID版本
|
||
int version = UuidUtil.getUuidVersion("550e8400-e29b-41d4-a716-446655440000");
|
||
// 返回: 4 (表示UUID V4)
|
||
```
|
||
|
||
## API接口示例
|
||
|
||
启动应用后，可以使用以下API接口测试UUID生成功能：
|
||
|
||
### 生成随机UUID
|
||
```
|
||
GET /api/uuid/random
|
||
```
|
||
|
||
### 生成UUID V5
|
||
```
|
||
GET /api/uuid/v5?name=test-user
|
||
```
|
||
|
||
### 基于用户名生成UUID
|
||
```
|
||
GET /api/uuid/user?username=john_doe
|
||
```
|
||
|
||
### 基于邮箱生成UUID
|
||
```
|
||
GET /api/uuid/email?email=john@example.com
|
||
```
|
||
|
||
### 验证UUID格式
|
||
```
|
||
GET /api/uuid/validate?uuid=550e8400-e29b-41d4-a716-446655440000
|
||
```
|
||
|
||
### 演示UUID V5的确定性
|
||
```
|
||
GET /api/uuid/v5/deterministic?name=test
|
||
```
|
||
此接口会多次生成相同名称的UUID，证明其确定性特征。
|
||
|
||
### 不同命名空间对比
|
||
```
|
||
GET /api/uuid/v5/namespaces?name=example
|
||
```
|
||
展示相同名称在不同命名空间下生成的不同UUID。
|
||
|
||
## 应用场景
|
||
|
||
### 1. 用户ID生成
|
||
```java
|
||
// 为用户生成稳定的ID
|
||
String userId = UuidUtil.generateUserUuid(username);
|
||
// 即使用户注册多次，只要用户名相同，ID就相同
|
||
```
|
||
|
||
### 2. 数据迁移
|
||
```java
|
||
// 从旧系统迁移时，可以基于原有标识生成新UUID
|
||
String legacyId = "user_12345";
|
||
String newUuid = UuidUtil.generateUuidV5("legacy:" + legacyId);
|
||
```
|
||
|
||
### 3. 分布式系统
|
||
```java
|
||
// 在微服务中，基于业务键生成一致的UUID
|
||
String orderUuid = UuidUtil.generateUuidV5("order:" + orderNumber);
|
||
```
|
||
|
||
### 4. 缓存键生成
|
||
```java
|
||
// 生成确定性的缓存键
|
||
String cacheKey = UuidUtil.generateUuidV5("cache:user:" + userId);
|
||
```
|
||
|
||
## UUID版本对比
|
||
|
||
| 版本 | 类型 | 特点 | 适用场景 |
|
||
|------|------|------|----------|
|
||
| V1 | 时间戳 | 基于时间和MAC地址 | 需要时间排序的场景 |
|
||
| V3 | MD5哈希 | 基于MD5（不安全） | 不推荐使用 |
|
||
| V4 | 随机 | 完全随机 | 大多数通用场景 |
|
||
| V5 | SHA-1哈希 | 确定性、可重现 | 需要稳定标识的场景 |
|
||
|
||
## UUID V5命名空间
|
||
|
||
RFC 4122定义了4个标准命名空间：
|
||
|
||
1. **DNS** (`6ba7b810-9dad-11d1-80b4-00c04fd430c8`)
|
||
- 用于域名系统
|
||
|
||
2. **URL** (`6ba7b811-9dad-11d1-80b4-00c04fd430c8`)
|
||
- 用于统一资源定位符（默认）
|
||
|
||
3. **OID** (`6ba7b812-9dad-11d1-80b4-00c04fd430c8`)
|
||
- 用于对象标识符
|
||
|
||
4. **X.500** (`6ba7b814-9dad-11d1-80b4-00c04fd430c8`)
|
||
- 用于X.500区分名称
|
||
|
||
## 最佳实践
|
||
|
||
1. **选择合适的命名空间**
|
||
- URL命名空间适合Web应用
|
||
- DNS命名空间适合域名相关
|
||
- 自定义命名空间适合特定业务
|
||
|
||
2. **使用前缀区分类型**
|
||
```java
|
||
// 推荐：添加前缀以区分不同类型的标识
|
||
String userUuid = UuidUtil.generateUuidV5("user:" + username);
|
||
String orderUuid = UuidUtil.generateUuidV5("order:" + orderNumber);
|
||
```
|
||
|
||
3. **保持一致性**
|
||
- 一旦选择了命名空间和命名规则，不要随意更改
|
||
- 否则会导致生成的UUID不一致
|
||
|
||
4. **安全性考虑**
|
||
- UUID V5不是加密安全的
|
||
- 如果需要不可预测的ID，使用UUID V4
|
||
- UUID V5适合公开或非敏感的标识符
|
||
|
||
## 技术实现
|
||
|
||
UUID V5的生成过程：
|
||
1. 将命名空间UUID转换为16字节数组
|
||
2. 将名称字符串转换为UTF-8字节数组
|
||
3. 拼接命名空间字节和名称字节
|
||
4. 计算SHA-1哈希值
|
||
5. 取前16字节作为UUID
|
||
6. 设置版本号为5
|
||
7. 设置变体位为RFC 4122标准
|
||
|
||
## 性能说明
|
||
|
||
- UUID V5生成涉及SHA-1哈希计算，比V4稍慢
|
||
- 但对于大多数应用场景，性能差异可以忽略
|
||
- SHA-1在此场景下仅用于生成哈希，不涉及安全认证 |