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