5.7 KiB
5.7 KiB
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）
// 标准格式（带横杠）
String uuid = UuidUtil.generateRandomUuid();
// 输出: 550e8400-e29b-41d4-a716-446655440000
// 不带横杠
String uuid = UuidUtil.generateRandomUuidWithoutHyphens();
// 输出: 550e8400e29b41d4a716446655440000
2. 生成UUID V5（基础用法）
// 使用默认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
// 基于用户名
String userUuid = UuidUtil.generateUserUuid("john_doe");
// 基于邮箱
String emailUuid = UuidUtil.generateEmailUuid("john@example.com");
// 基于手机号
String phoneUuid = UuidUtil.generatePhoneUuid("13800138000");
重要：同一用户信息始终生成相同的UUID，适合用作稳定的用户标识符。
4. 使用UUID V5生成器的高级功能
// 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格式
// 验证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生成
// 为用户生成稳定的ID
String userId = UuidUtil.generateUserUuid(username);
// 即使用户注册多次，只要用户名相同，ID就相同
2. 数据迁移
// 从旧系统迁移时，可以基于原有标识生成新UUID
String legacyId = "user_12345";
String newUuid = UuidUtil.generateUuidV5("legacy:" + legacyId);
3. 分布式系统
// 在微服务中，基于业务键生成一致的UUID
String orderUuid = UuidUtil.generateUuidV5("order:" + orderNumber);
4. 缓存键生成
// 生成确定性的缓存键
String cacheKey = UuidUtil.generateUuidV5("cache:user:" + userId);
UUID版本对比
| 版本 | 类型 | 特点 | 适用场景 |
|---|---|---|---|
| V1 | 时间戳 | 基于时间和MAC地址 | 需要时间排序的场景 |
| V3 | MD5哈希 | 基于MD5（不安全） | 不推荐使用 |
| V4 | 随机 | 完全随机 | 大多数通用场景 |
| V5 | SHA-1哈希 | 确定性、可重现 | 需要稳定标识的场景 |
UUID V5命名空间
RFC 4122定义了4个标准命名空间：
-
DNS (
6ba7b810-9dad-11d1-80b4-00c04fd430c8)- 用于域名系统
-
URL (
6ba7b811-9dad-11d1-80b4-00c04fd430c8)- 用于统一资源定位符（默认）
-
OID (
6ba7b812-9dad-11d1-80b4-00c04fd430c8)- 用于对象标识符
-
X.500 (
6ba7b814-9dad-11d1-80b4-00c04fd430c8)- 用于X.500区分名称
最佳实践
-
选择合适的命名空间
- URL命名空间适合Web应用
- DNS命名空间适合域名相关
- 自定义命名空间适合特定业务
-
使用前缀区分类型
// 推荐：添加前缀以区分不同类型的标识 String userUuid = UuidUtil.generateUuidV5("user:" + username); String orderUuid = UuidUtil.generateUuidV5("order:" + orderNumber); -
保持一致性
- 一旦选择了命名空间和命名规则，不要随意更改
- 否则会导致生成的UUID不一致
-
安全性考虑
- UUID V5不是加密安全的
- 如果需要不可预测的ID，使用UUID V4
- UUID V5适合公开或非敏感的标识符
技术实现
UUID V5的生成过程：
- 将命名空间UUID转换为16字节数组
- 将名称字符串转换为UTF-8字节数组
- 拼接命名空间字节和名称字节
- 计算SHA-1哈希值
- 取前16字节作为UUID
- 设置版本号为5
- 设置变体位为RFC 4122标准
性能说明
- UUID V5生成涉及SHA-1哈希计算，比V4稍慢
- 但对于大多数应用场景，性能差异可以忽略
- SHA-1在此场景下仅用于生成哈希，不涉及安全认证