yexuejc-base/docs/Base64_Migration_Documentation.md

# Base64 迁移文档

## 概述
本文档记录了将项目中 Apache Commons Codec Base64 实现迁移到 Java 内置 `java.util.Base64` 的完整过程。

## 迁移背景
为了减少对外部依赖的依赖，提高代码的标准化程度，决定将项目中使用的 Apache Commons Codec Base64 功能替换为 Java 8+ 内置的 Base64 实现。

## 影响范围

### 修改的文件
1. `src/main/java/com/yexuejc/base/encrypt/RSA.java`
2. `src/main/java/com/yexuejc/base/encrypt/RSACoder.java`

### 新增的测试文件
1. `src/test/java/com/yexuejc/base/encrypt/Base64MigrationTest.java`

## 具体变更

### 1. RSA.java 变更

#### 导入语句变更
```java
// 原始导入
import org.apache.commons.codec.binary.Base64;

// 修改后导入
import java.util.Base64;
```

#### 方法调用变更

##### 编码方法变更
```java
// 原始代码
publicKeyStr = Base64.encodeBase64URLSafeString(publicKey.getEncoded());
privateKeyStr = Base64.encodeBase64URLSafeString(privateKey.getEncoded());

// 修改后代码
publicKeyStr = Base64.getUrlEncoder().encodeToString(publicKey.getEncoded());
privateKeyStr = Base64.getUrlEncoder().encodeToString(privateKey.getEncoded());
```

```java
// 原始代码
publicKeyStr = Base64.encodeBase64String(publicKey.getEncoded());
privateKeyStr = Base64.encodeBase64String(privateKey.getEncoded());

// 修改后代码
publicKeyStr = Base64.getEncoder().encodeToString(publicKey.getEncoded());
privateKeyStr = Base64.getEncoder().encodeToString(privateKey.getEncoded());
```

##### 解码方法变更
```java
// 原始代码
X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(Base64.decodeBase64(publicKey));

// 修改后代码
X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(autoDecodeBase64String(publicKey));
```

```java
// 原始代码
PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.decodeBase64(privateKey));

// 修改后代码
PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(autoDecodeBase64String(privateKey));
```

##### 签名和验证变更
```java
// 原始代码
signBase64Str = Base64.encodeBase64URLSafeString(signature.sign());
signBase64Str = Base64.encodeBase64String(signature.sign());
signature.verify(Base64.decodeBase64(signStr));

// 修改后代码
signBase64Str = Base64.getUrlEncoder().encodeToString(signature.sign());
signBase64Str = Base64.getEncoder().encodeToString(signature.sign());
signature.verify(autoDecodeBase64String(signStr));
```

#### 新增辅助方法
为了支持自动检测 Base64 编码格式，添加了以下辅助方法：

```java
/**
 * 根据encodeBase64URLSafe标志解码Base64字符串
 * 
 * @param base64String Base64编码的字符串
 * @return 解码后的字节数组
 */
private byte[] decodeBase64String(String base64String) {
    if (encodeBase64URLSafe) {
        return Base64.getUrlDecoder().decode(base64String);
    } else {
        return Base64.getDecoder().decode(base64String);
    }
}

/**
 * 自动检测并解码Base64字符串（支持普通和URL安全两种格式）
 * 
 * @param base64String Base64编码的字符串
 * @return 解码后的字节数组
 */
private byte[] autoDecodeBase64String(String base64String) {
    // 检查是否包含URL安全的字符
    if (base64String.contains("-") || base64String.contains("_")) {
        // 包含URL安全字符，使用URL解码器
        return Base64.getUrlDecoder().decode(base64String);
    } else {
        // 使用普通解码器
        return Base64.getDecoder().decode(base64String);
    }
}
```

### 2. RSACoder.java 变更

#### 导入语句变更
```java
// 原始导入
import org.apache.commons.codec.binary.Base64;

// 修改后导入
import java.util.Base64;
```

#### 方法调用变更
```java
// 原始代码
X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(Base64.decodeBase64(key.getBytes(StandardCharsets.UTF_8)));

// 修改后代码
X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(key.getBytes(StandardCharsets.UTF_8)));
```

```java
// 原始代码
PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.decodeBase64(key.getBytes(StandardCharsets.UTF_8)));

// 修改后代码
PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.getDecoder().decode(key.getBytes(StandardCharsets.UTF_8)));
```

## 测试验证

### 创建的测试用例
`Base64MigrationTest.java` 包含以下测试：

1. **testNormalBase64EncodingDecoding** - 测试普通Base64编码解码
2. **testUrlSafeBase64EncodingDecoding** - 测试URL安全Base64编码解码
3. **testRsaKeyGenerationBase64** - 测试RSA密钥生成中的Base64功能
4. **testRsaEncryptionDecryptionBase64** - 测试RSA加解密中的Base64功能
5. **testBase64UrlSafeOption** - 测试Base64URLSafe选项

### 测试结果
所有测试均已通过，证明迁移成功且功能完整。

## 兼容性说明

### 向后兼容性
本次迁移完全向后兼容：
- 保留了原有的 `encodeBase64URLSafe` 配置选项
- 添加了自动检测机制，可以处理现有的URL安全Base64编码
- 不影响现有API接口的使用方式

### 性能影响
Java内置Base64实现通常比Apache Commons Codec具有更好的性能表现。

## 注意事项

1. **依赖移除**：迁移完成后可以考虑从项目依赖中移除 `commons-codec` 库
2. **编码格式**：URL安全Base64使用 `-` 和 `_` 替代 `+` 和 `/`
3. **填充字符**：两种实现都使用 `=` 作为填充字符

## 验证步骤

1. 编译项目：`mvn compile`
2. 运行基础测试：`mvn test -Dtest=Base64MigrationTest`
3. 运行RSA相关测试：`mvn test -Dtest=*RSATest*`
4. 运行完整测试套件：`mvn test`

## 结论
本次Base64迁移成功完成，所有功能均正常工作，代码质量得到提升，减少了外部依赖。

---
*文档创建日期：2026-02-24*
*作者：Base64 Migration Team*