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 变更

导入语句变更

// 原始导入
import org.apache.commons.codec.binary.Base64;

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

方法调用变更

编码方法变更

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

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

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

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

解码方法变更

// 原始代码
X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(Base64.decodeBase64(publicKey));

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

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

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

签名和验证变更

// 原始代码
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 编码格式，添加了以下辅助方法：

/**
 * 根据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 变更

导入语句变更

// 原始导入
import org.apache.commons.codec.binary.Base64;

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

方法调用变更

// 原始代码
X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(Base64.decodeBase64(key.getBytes(StandardCharsets.UTF_8)));

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

// 原始代码
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