Caiji/Uni_Login_system

Fork 0

Files

T

Caiji e69168775c 第一次提交

2026-05-31 04:36:59 +08:00

5.7 KiB

Raw Blame History

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在此场景下仅用于生成哈希，不涉及安全认证

5.7 KiB Raw Blame History Unescape Escape