做后端开发的同行应该都有过这种经历系统里到处散落着加解密相关的代码订单号转码一个写法接口参数加密一个写法数据库里存的敏感字段用的又是另一套逻辑。我这次要讲的就是我把这类散落逻辑收拢成一个统一工具类的全过程围绕 Base64 解码编码、DES 加密解密以及最终对外暴露的 PasswordUtils 解加密工具类把这几个东西彻底理清楚、做成一套可测试、可替换、能平滑迁移的代码。这篇文章适合几类人看项目里到处复制粘贴加解密代码、想统一收口却不知道怎么设计的开发者接手遗留系统、看到老数据的密文却不知道当时用什么参数加密的维护者以及刚接触对称加密和 Base64想系统搞懂原理的新手。不管你是哪种读完至少能直接照着把工具类写出来还能避开我在实际项目中踩过的那些坑。1. 从一次代码评审说起为什么需要统一加解密工具1.1 项目里那些散落的代码我接手的这个内部系统不算大但是跑的业务时间长了代码里积累了不少历史包袱。做一次代码评审时我随手搜了一下加密相关的关键字结果发现光 DES 就有三四个实现版本分布在不同模块里有的直接用DES/ECB/PKCS5Padding有的用DES/CBC/PKCS5Padding有的加密结果用 Base64 输出有的转成十六进制字符串有的干脆把byte[]直接存储到数据库密钥写在不同的常量类里同一个系统的不同模块居然用的是不同的工作密钥中文文本加密时有的地方用getBytes()不指定字符集依赖服务器默认编码结果在 Linux 上好好的迁到 Windows 上加密结果就变了。这种状态最直接的后果就是新同学写代码时不知道该用哪一套只能照着最近的调用抄一份于是又多出一份变体出问题的时候排查的人得把五六处加密代码全部看一遍才能确定当时用的是哪种模式和填充方式。更有一次两个服务之间做接口对接A 服务用 CBC 加密B 服务用 ECB 解密联调了好几个小时才定位到模式不一致。1.2 我的设计目标所以我在这次整改里给自己定了几个明确的目标对外只暴露一个入口类PasswordUtils把 Base64 和 DES 的复杂度全部封装在内部所有编码统一走 Base64不使用十六进制、不直接存byte[]所有字符集统一 UTF-8杜绝平台差异工作密钥从外部注入不散落在业务代码里把加密模式、填充方式这些参数固定在一个地方不允许调用方自行指定必须有对应的单元测试并且固化一批锚点密文防止以后有人改动算法细节导致老数据解不开。这几个目标说起来简单落地的时候牵扯到的技术细节可不少。下面我从 Base64 和 DES 的原理开始把每一步都拆开讲清楚。2. Base64 是什么编码、变体与误用2.1 Base64 的原理其实很简单很多初学者容易把 Base64 当成加密这其实是个误区。Base64 是一种编码方式它的作用是把任意二进制数据转换成由 64 个可打印字符组成的文本。为什么需要它因为二进制数据在传输和存储过程中很容易出问题JSON 里不能直接放byte[]URL 参数里不能出现不可见字符数据库文本字段可能不兼容二进制内容日志打印二进制会变成一堆乱码。把这些二进制数据转换成纯文本就能安全地放进各种容器里。Base64 的转换规则是把原始字节流按每 3 个字节一组也就是 24 个 bit拆成 4 个 6 bit 的单元每个 6 bit 单元对应A-Z、a-z、0-9、、/这 64 个字符中的一个。如果原始数据字节数不是 3 的倍数就补零并在末尾加号表示补位。比如字符串Hello一共 5 个字节转成 Base64 是SGVsbG8这个就是用来告诉解码端最后一组只有 2 个字节。在 Java 8 之前标准库里的 Base64 编码器写起来又长又绕很多人干脆用第三方库或者自己手写。Java 8 之后官方提供了java.util.Base64这才是推荐做法。自己手写 Base64 纯属给自己挖坑性能和正确性都很难保证。2.2 不同变体怎么选Base64 不是只有一种。标准编码里包含和/两个字符这俩在 URL 里会有问题会被解析成空格/会干扰路径分隔。所以互联网场景下要用 URL 安全的变体把换成-、把/换成_并且通常会去掉末尾的因为在部分框架里也会引起解析异常。还有一种 MIME 变体每 76 个字符插入一个换行主要用在邮件附件场景企业内部服务间调用一般用不到这里就不展开。我的建议是对外传输、链接参数场景一律用 URL Safe 变体数据库存储、配置文件存储用标准变体即可但工具类里两种都可以提供由上层决定。2.3 工具类实现Base64Utils基于上面的分析我先写了一个Base64Utils把编码解码统一封装起来。这段代码看起来平淡无奇但至少解决了三件事统一字符集为 UTF-8、统一入口、提供 URL Safe 变体。import java.nio.charset.StandardCharsets; import java.util.Base64; public final class Base64Utils { private Base64Utils() { } public static String encode(String plainText) { if (plainText null) { return null; } return Base64.getEncoder() .encodeToString(plainText.getBytes(StandardCharsets.UTF_8)); } public static String decode(String base64Text) { if (base64Text null) { return null; } byte[] bytes Base64.getDecoder().decode(base64Text); return new String(bytes, StandardCharsets.UTF_8); } public static String encodeUrlSafe(String plainText) { if (plainText null) { return null; } return Base64.getUrlEncoder().withoutPadding() .encodeToString(plainText.getBytes(StandardCharsets.UTF_8)); } public static String decodeUrlSafe(String base64Text) { if (base64Text null) { return null; } byte[] bytes Base64.getUrlDecoder().decode(base64Text); return new String(bytes, StandardCharsets.UTF_8); } }这里有一个值得注意的细节getUrlDecoder()能容忍没有 padding 的输入所以encodeUrlSafe去掉之后decodeUrlSafe依然可以正确解码。如果将来对接方传来的是带的 URL Safe 内容也不会有问题。注意Base64 编码不是加密任何人拿到 Base64 字符串都可以直接解码得到原文。它的作用是让二进制数据变成文本不是保护数据机密性。3. DES 加解密参数、模式与填充3.1 对称加密和 DES 的基本规则DES 是对称加密算法加密和解密使用同一个密钥。它是 1977 年被采纳为联邦标准的算法分组大小 64 bit8 字节密钥也是 64 bit8 字节但其中 8 位是奇偶校验位真正有效的是 56 位。也正因为有效密钥只有 56 位DES 在现代计算能力下已经可以被暴力破解早就不推荐用于高安全场景了。但现实是很多遗留系统还在使用 DES或者外部系统对接时只支持 DES。既然项目定了用 DES我们能做的就是把它封装得正确、稳定、可维护同时规划好迁移路径。在 Java 里使用 DES 有几个关键参数必须搞清楚算法名称DES转换字符串DES/CBC/PKCS5Padding这个字符串决定算法、模式、填充三件事密钥必须是 8 字节的字节数组CBC 模式下还需要一个 8 字节的初始向量 IV。密钥这块特别容易踩坑。SecretKeySpec构造时不会立刻校验密钥长度非法长度的密钥要等到Cipher.init()甚至Cipher.doFinal()才报错。所以工具类里应该在入口先做一次校验把问题提前暴露出来。有些同学直接用超过 8 字节的字符串当密钥结果getBytes()之后被SecretKeySpec默默截断只在特定的输入下才偶发异常这种问题排查起来非常痛苦。3.2 CBC 与 ECB 怎么选ECB电子密码本模式是最简单的一种模式每个 8 字节明文块独立加密成 8 字节密文块。问题在于相同的明文块永远产生相同的密文块这会导致加密结果泄露结构信息。一个经典的例子是如果明文是一张图片ECB 加密后图片的轮廓特征仍然肉眼可见。所以除非极特殊的兼容性需求ECB 都不是推荐选项。CBC密码块链接模式引入了初始向量 IV每个明文块先与上一个密文块做异或运算然后再加密。这样做的好处是相同的明文块在不同的位置会产生不同的密文块模式的泄露被弱化。第一个明文块没有上一个密文块可用就和 IV 异或。所以 CBC 模式里 IV 的选择也很关键固定 IV 的缺陷后面会展开说。Java 里 CBC 模式的 IV 必须是 8 字节常见的错误是IV 字符串长度不是 8 字节加密和解密用了不同的 IV不同服务实例配置的 IV 不一致。3.3 填充方式 PKCS5PaddingDES 是分组加密每次处理 8 字节但明文长度不一定是 8 的倍数。这时候就需要填充。PKCS5Padding 的规则是缺 n 个字节就补 n 个字节每个字节的值都是 n。比如明文最后一块只有 5 字节缺 3 个字节那就补 3 个0x03如果明文恰好是 8 的倍数也要补整整 8 个字节的0x08这是为了让解密端能明确区分原始数据末尾本身是 0 还是填充值。Java 里的DES/CBC/PKCS5Padding实际上对应的是 PKCS7只是 Java 沿用了 PKCS5 这个名字。真正实现的时候填充和去填充都由Cipher自动完成我们只需要保证指定转换字符串即可。如果选了NoPadding调用方必须自己保证明文长度是 8 字节的倍数否则doFinal会直接抛异常。这个选项只适用于二进制数据和特殊协议普通文本场景没有必要用。4. PasswordUtils 工具类的完整落地4.1 分层结构我把整个工具类拆成三个层级职责各不重叠Base64Utils负责编码层把加密后的字节数组转成字符串或者把字符串解码成字节数组DesUtils负责算法层处理 DES 的密钥规格、IV、Cipher 生命周期输入输出统一为字符串PasswordUtils负责外观层是业务代码唯一依赖的入口内部持有工作密钥提供encrypt/decrypt两个方法。为什么不让业务代码直接调DesUtils因为一旦DesUtils散落到业务代码里就会出现前面说的那种问题今天有人传工作密钥 A明天有人传工作密钥 B后天有人改用 ECB。PasswordUtils作为门面把工作密钥的注入限制在一处业务侧只需要说我要加密这个字符串和我要解密这个字符串不用关心底层算法细节。4.2 核心实现先看DesUtils。这里我选择 CBC PKCS5Padding密钥和 IV 都从方法入参传入。IV 实际项目中一般从配置读取这里给出一个默认值仅作为演示。import javax.crypto.Cipher; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.util.Base64; public final class DesUtils { public static final String TRANSFORMATION DES/CBC/PKCS5Padding; private static final String ALGORITHM DES; private static final int KEY_LENGTH 8; private DesUtils() { } public static String encrypt(String plainText, String key, String iv) { if (plainText null) { throw new IllegalArgumentException(明文不能为空); } validateKeyAndIv(key, iv); try { SecretKeySpec keySpec new SecretKeySpec( key.getBytes(StandardCharsets.UTF_8), ALGORITHM); IvParameterSpec ivSpec new IvParameterSpec( iv.getBytes(StandardCharsets.UTF_8)); Cipher cipher Cipher.getInstance(TRANSFORMATION); cipher.init(Cipher.ENCRYPT_MODE, keySpec, ivSpec); byte[] encrypted cipher.doFinal( plainText.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(encrypted); } catch (Exception e) { throw new IllegalStateException(DES 加密失败, e); } } public static String decrypt(String encryptedText, String key, String iv) { if (encryptedText null) { throw new IllegalArgumentException(密文不能为空); } validateKeyAndIv(key, iv); try { SecretKeySpec keySpec new SecretKeySpec( key.getBytes(StandardCharsets.UTF_8), ALGORITHM); IvParameterSpec ivSpec new IvParameterSpec( iv.getBytes(StandardCharsets.UTF_8)); Cipher cipher Cipher.getInstance(TRANSFORMATION); cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec); byte[] decrypted cipher.doFinal( Base64.getDecoder().decode(encryptedText)); return new String(decrypted, StandardCharsets.UTF_8); } catch (Exception e) { throw new IllegalStateException(DES 解密失败, e); } } private static void validateKeyAndIv(String key, String iv) { if (key null || key.getBytes(StandardCharsets.UTF_8).length ! KEY_LENGTH) { throw new IllegalArgumentException(DES 工作密钥必须是 8 字节); } if (iv null || iv.getBytes(StandardCharsets.UTF_8).length ! KEY_LENGTH) { throw new IllegalArgumentException(DES 初始向量 IV 必须是 8 字节); } } }再写一个外观层PasswordUtils。这里我采用了构造器注入工作密钥的方式避免每次调用都传入密钥。关于密钥从哪里来下一小节单独讲。import java.nio.charset.StandardCharsets; public final class PasswordUtils { private final String workKey; private final String iv; public PasswordUtils(String workKey, String iv) { this.workKey workKey; this.iv iv; } public String encrypt(String plainText) { return DesUtils.encrypt(plainText, workKey, iv); } public String decrypt(String encryptedText) { return DesUtils.decrypt(encryptedText, workKey, iv); } public static String encodeBase64(String plainText) { return Base64Utils.encode(plainText); } public static String decodeBase64(String encodedText) { return Base64Utils.decode(encodedText); } }这样一个简单的PasswordUtils就完成了。业务代码里只需要PasswordUtils passwordUtils new PasswordUtils(k3y!2024, initvect); String cipher passwordUtils.encrypt(需要保护的敏感信息); String plain passwordUtils.decrypt(cipher);initvect正好 8 字节k3y!2024也正好 8 字节两个都满足 DES 的长度要求。4.3 工作密钥管理密钥的存储和轮换是这套工具类落地时最容易被低估的部分。我见过有人在代码仓库里明文提交密钥后来仓库权限泄露等于密钥也跟着泄露了。还有人在配置文件里写密钥结果文件被日志系统采集走密钥直接进了日志平台。我的建议是至少做到这几层工作密钥不写死在 Java 代码里工作密钥不放在会进日志的配置文件中而是从环境变量或者配置中心读取如果成本允许使用专门的密钥管理服务把密钥明文与业务代码彻底隔离设计密钥版本化机制比如密文格式统一为版本号:密文这样密钥轮换时老数据还能用旧密钥解新数据用新密钥加密实现无缝过渡。密钥轮换这块有一个很实用的过渡方案在PasswordUtils里维护一个当前密钥和一个历史密钥池。解密时先尝试当前密钥失败再遍历历史密钥。等所有老数据都重加密到新密钥之后再逐步下线旧密钥。这个方案不需要停机代价是解密逻辑会多一点分支但相比强制替换全部密文成本和风险低得多。5. 实操过程单元测试与项目集成5.1 回环测试与锚点密文工具类写完后第一件事不是接业务而是写测试。最基本的测试是回环测试加密之后的密文能解密回原始明文这个测试保证工具类的两个方向都通。我用的是常见的单测框架直接看代码import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class PasswordUtilsTest { private static final String WORK_KEY k3y!2024; private static final String IV initvect; Test void encryptThenDecryptShouldReturnOriginalText() { PasswordUtils utils new PasswordUtils(WORK_KEY, IV); String plain hello 中文这是一个回环测试; String cipher utils.encrypt(plain); assertNotNull(cipher); assertNotEquals(plain, cipher); assertEquals(plain, utils.decrypt(cipher)); } Test void sameInputShouldProduceStableCipherWithFixedIv() { PasswordUtils utils new PasswordUtils(WORK_KEY, IV); String plain stable input; String cipher1 utils.encrypt(plain); String cipher2 utils.encrypt(plain); assertEquals(cipher1, cipher2); } }第二个测试看起来有点反直觉我们前面刚说过固定 IV 有风险为什么还要断言密文可复现因为这里测试的不是安全性而是稳定性。在遗留系统迁移场景中老数据必须能在新代码里解开这就需要固定参数下密文结果可复现。安全诉求用随机 IV方案解决稳定性诉求用固定 IV方案解决两者适用于不同场景要区分开。除了回环测试我强烈建议做锚点测试固定一个密钥和 IV手动跑一次加密把产生的密文写死在测试代码里。这样以后任何人改动算法参数比如把 CBC 换成 ECB、把 UTF-8 改成 GBK锚点测试都会直接失败提醒你不要破坏老数据的兼容性。这个习惯在内部系统重构中价值巨大。5.2 配置文件和数据库的接入工具类封装完成后接入业务是有套路的。数据库里存敏感字段时我一般建议存密文用varchar类型长度按 Base64 后的大小预留。DES 是 8 字节分组加密每 8 字节明文变成 8 字节密文Base64 输出长度大概比原始明文多三分之一左右再考虑到中文 UTF-8 编码后一个字符占 3 字节预留 255 甚至 512 字符长度基本够用。配置文件接入时常见做法是采用ENC(密文)这种包裹格式项目启动时统一解码。但这里要提醒一点如果配置文件本身是通过模板渲染的渲染工具可能会对、/、做转义导致密文在启动时解析失败。所以配置文件里的密文尽量使用 URL Safe 变体或者确保渲染工具不会改动这些字符。5.3 日志与安全审查日志是加解密工具类最容易泄露信息的环节。很多框架会默认打印方法入参和返回值如果业务代码直接调passwordUtils.encrypt(明文)框架日志立刻把明文打出来了。我的做法是业务日志里禁止打印加解密入参和结果需要排查问题时只打印密文不打印明文在PasswordUtils内部可以在加密前对明文做脱敏但更根本的是要求上层代码不要记录敏感原文。这个问题容易被忽略但真出事儿的时候日志平台泄露的数据比数据库泄露的还多。6. 常见问题速查与避坑记录6.1 解不开、乱码、报错怎么排查我在实际排查和帮别人看代码的过程中整理了一份高频问题表按症状到解决方案的路径梳理如下症状可能原因排查方法解决方案javax.crypto.BadPaddingException密钥不一致、密文被截断、密文经过 URL 编码后字符被替换先用 Base64 解码密文确认解出来的字节数组长度是 8 的倍数核对密钥和 IV确认传输过程中没有对密文字符串做额外转义java.security.InvalidKeyException: Wrong key size密钥长度不是 8 字节打印密钥字节数组的长度密钥统一控制在 8 字节超长密钥不要指望自动截断解密成功但中文乱码加密和解密时用了不同的字符集检查getBytes()是否省略了StandardCharsets.UTF_8明文转字节、字节转明文都显式指定 UTF-8测试环境正常生产环境失败服务器默认字符集不同比如 Windows 下 GBK、Linux 下 UTF-8看启动日志里的file.encoding所有字符串和字节的转换都显式指定字符集相同明文加密结果总是一样怀疑不安全使用了 ECB 模式或固定 IV 的 CBC查看转换字符串需要高安全场景使用随机 IVIV 与密文一同存储Base64 字符串里出现、/、导致 URL 传输报错使用了标准 Base64 变体检查编码入口改用 URL Safe 变体6.2 我从这些问题里总结的套路排查加解密问题我一般按三段式来定位第一段验证 Base64 链是否畅通。把密文字符串用同样的解码器解开看得到的字节数组长度是否正常、开头几个字节是否符合 DES 密文的特征。这一步能把编码层的问题先排除掉。第二段验证 Cipher 参数是否一致。加密和解密两侧的算法、模式、填充、密钥、IV 必须逐一比对。我见过最隐蔽的错误是密钥字符串表面一样但一边是 UTF-8 的getBytes()另一边是 ISO-8859-1 的getBytes()字节内容不同解密自然失败。第三段验证数据完整性。Base64 字符串在传输过程中有没有被截断、有没有被 URL 编码器二次编码、有没有被数据库字段长度截断。这些都可能导致解密时报 padding 异常而不是算法本身有问题。还有一个经验是不要在线上环境反复试错。每次解密失败都可能是同一个原因但日志里只看到最终异常。正确的做法是在本地写一个最小复现用例把线上的密文、密钥和 IV 都固定下来跑一次就能看出是哪一段挂了。7. 后续升级与边界提醒7.1 从 DES 平滑迁移到 AESDES 的密码学强度已经跟不上时代凡是能改的场景都应逐步迁移到 AES。好消息是AES 在 Java 里的编程模型和 DES 几乎一样SecretKeySpec、IvParameterSpec、Cipher的用法完全复用只需要改三个地方算法名从DES改成AES密钥长度从 8 字节改成 16 字节AES-128或 32 字节AES-256转换字符串改成AES/CBC/PKCS5Padding。迁移的时候可以走双算法并存的过渡期新增数据用 AES 加密老数据继续用 DES 解密。在PasswordUtils里维护两套实现解密时先按密文里的版本标识选择算法等老数据消化完再下线 DES 分支。这里要特别提醒一点AES-256 在部分 JDK 版本里默认受限于 JCE 策略文件会报Illegal key size异常。实际上较新的 JDK 已经默认支持 AES-256但如果你维护的是老版本 JDK 环境需要确保没有额外限制。7.2 用户口令不应该用可逆加密说到PasswordUtils这个名字很多人第一反应是拿来存用户密码。这是一个非常危险的误用。用户口令的正确存储方式是加盐哈希也就是单向的摘要算法加随机盐值而不是可逆的对称加密。DES 加密是双向的存进数据库的密文在密钥泄露后可以直接解出原文用户口令一旦被还原就是批量泄露。我的建议是PasswordUtils定位为敏感数据保护工具用于加密数据库中的证件号、手机号、第三方接口凭据这类需要还原原文的场景用户口令的校验单独使用 PBKDF2、BCrypt 这类专门的口令哈希算法二者不要混用。我在项目里看到过有人用 DES 加密用户密码密钥还硬编码在代码里这种问题在评审时一定要拦下来。7.3 一些更进一步的设计思路如果这套工具类要继续演进以下几个方向值得考虑引入随机 IV当前实现固定 IV 便于回归测试但在生产环境更好的做法是每次加密生成随机 IV把 IV 直接拼在密文头部解密时先切分再解。这是可测试性和安全性的折中引入完整性校验CBC 模式无法检测密文篡改如果有人改了密文中的某个字节解密输出会变成乱码但程序不会主动报错。如果要防止篡改可以升级到 AEAD 模式比如AES/GCM/NoPadding它同时提供保密性和完整性统一异常码把加密失败、解密失败、参数非法映射成业务异常码方便上层统一处理。这些改动说起来都不复杂但每改一处都要重新跑锚点测试确保老数据的兼容性不被破坏。回到最初的问题Base64、DES、PasswordUtils 这三个概念放在一起本质上是在回答二进制数据如何安全、规范地完成加密、编码、存储、传输这件事。Base64 解决二进制不可读的问题DES 解决数据可逆保护的问题PasswordUtils 解决代码复用和参数统一的问题。工具类本身不难写真正难的是把每个细节的为什么想清楚。我自己在实际项目中把这些整理完之后最大的感受是排查加解密问题时绝大多数疑难杂症都来自参数不统一、字符集不统一、密钥管理失控而不是算法本身出了问题。所以封装的核心价值不在代码量而在把可变的东西收敛到一处把容易错的东西用测试固定下来。最后再分享一个小技巧在项目里做这种基础工具封装时不管当前需求多么简单都先把测试向量固化下来。哪怕只是自己本地跑出来的一条密文写进测试注释里一年后别人动这块代码时会少走很多弯路。这个习惯我保持了好几年每次都在关键时刻救回一命。