1. 工具选型为什么Java里做AES加密要选Hutool先说说我自己的体会。做后端开发这几年凡是牵扯到敏感数据落库、接口报文加密、Token签名这类需求AES都是绕不开的标准答案。但你如果真拿JDK原生的JCE接口去写那酸爽程度基本等于用筷子喝汤——能喝但费劲。原生写法大概是这样的先搞KeyGenerator再配SecretKeySpec然后手动初始化Cipher指定algorithm、mode、padding还得处理Base64编码、byte[]和String互转稍微不留神就是一个BadPaddingException砸脸上。这套流程写个三五次也就罢了如果每个项目都有那纯属重复造轮子还没造好。Hutool的crypto模块做得比较聪明的点是把复杂的东西收敛成了几个高频入口。你要做对称加密就只跟SecureUtil和AES这俩类打交道你要做非对称有RSA摘要有DigestUtil签名有SignUtil。不需要理解底层的Cipher初始化细节但它又保留了让你自定义mode、padding、iv的能力。说白了就是——默认给你最省事的写法同时也留了让你精细控制的接口这比很多工具类一锤子买卖的设计要实在得多。拿AES举例Hutool提供的默认行为是这样的不传参调用SecureUtil.aes()时自动生成一个随机密钥加密输出默认是Base64字符串如果你传了密钥字节数组则使用你指定的密钥。这个接口设计对业务代码特别友好——你不需要关心SecureUtil.aes()底层到底是ECB还是CBC因为它在内部已经把Cipher.getInstance(AES)这套流程封装好了。我实际用下来还有一个很直观的感受Hutool的加密结果在跨语言验证时挖坑少。Java默认的AES/ECB/PKCS5Padding在Hutool里就是默认配置这意味着你用Hutool加密出来的东西放到Python、Go或者Node.js里去解密彼此之间用同样参数就能对齐。这一点对微服务架构里多个团队各写各的服务端尤其重要——大家都用同一个标准的算法参数沟通成本直线降低。当然也不是说Hutool就是银弹。如果你的项目本身有严格的等保要求或者你们安全团队明确要基于Bouncy Castle做定制化加密方案那Hutool不是一个必须项。但就“日常开发里快速、靠谱地实现AES加解密”这个需求来说它的性价比几乎是最高的。2. AES加密的核心参数不懂这些等于白做很多新手上来就跑SecureUtil.aes()一把梭倒也能跑通。但一旦遇到要和别的系统联调或者需要改模式、换IV就直接抓瞎了。所以编码之前这几个概念最好先搞清楚。它们决定了你能不能用好AES也决定了你的密文到底是“可解密的”还是“一锤子买卖”。2.1 密钥长度128、192、256究竟怎么选AES是一种分组密码它支持三种密钥长度128位16字节、192位24字节、256位32字节。不用被数字吓到直接理解成密钥越长暴力破解的成本越高。128位在当前算力下已经足够安全商用场景里大部分系统选128位如果项目里有安全合规的硬性指标、或者传输的数据特别敏感可以上256位但代价并不是加密变慢——256位AES的单次运算开销其实高不了多少——真正的坑在于JDK默认不支持256位密钥。Java 8及更早版本的JDK里如果没装Java Cryptography ExtensionJCE无限制权限策略文件AES-256直接抛InvalidKeyException: Illegal key size。JDK 9以后这限制才默认放开。所以你如果是老项目跑在JDK 8上想用256位密钥第一件事是确认JCE补丁装没装不然代码写对了一样跑不起来。实际操作里选多少位我一般看对接方的标准。自研系统内部用我会直接上256但要对外联调先问对方支持什么长度。因为有些老系统的加密模块写死了128位你要用256两边一通折腾就是浪费工时。2.2 工作模式ECB、CBC、GCM的取舍这是最容易搞混的部分也是联调时最容易翻车的部分。AES底层是按固定长度分组加密的分组长度固定为128位16字节但多个分组之间怎么关联就是“模式”的事了。ECB模式每个分组独立加密相互不影响。优点是简单、能并行计算缺点也致命——相同明文块会产生相同密文块有概率性泄漏信息。现在安全性要求高的场景都不推荐ECB但为什么Hutool的默认还是ECB因为Java原生Cipher.getInstance(AES)默认就是它Hutool保持了这个兼容性。如果你只在系统内部用、且数据没有明显的重复模式比如随机生成的TokenECB勉强能用如果加密的是JSON、XML这种结构重复明显的文本建议老老实实换CBC。CBC模式每个分组先和上一个分组的密文做异或再加密。这样相同的明文块在不同位置也产生不同的密文块。它需要一个初始向量IV第一个分组没有“上一个密文”就用IV顶替。CBC的加密是串行的性能比ECB略低但安全性好很多是目前应用最广的模式之一。GCM模式属于AEAD模式加密的同时生成认证标签能同时保证机密性、完整性还天然防篡改。现在很多新系统的接口加密、或者TLS里的数据加密都在用GCM。它的好处是省掉了额外做HMAC的活儿一个方案解决两个问题。选型建议其实就一句话没有强烈的兼容性要求优先选CBC或GCM如果允许我用GCM我就不会选CBC因为认证标签真的能帮你挡掉一堆“密文被人改了”的麻烦。2.3 填充方式PKCS5Padding和PKCS7Padding的选择AES加密是按16字节分组进行的但你要加密的数据长度不可能刚好都是16的倍数所以最后一块需要填充。Java原生只提供了PKCS5Padding但大家心里都清楚AES的分组是16字节严格来说应该叫PKCS7PaddingJava里之所以叫PKCS5是因为JDK早期把这两个概念混用了。Hutool的做法是二者都支持你传Padding.PKCS5Padding或Padding.PKCS7Padding都行底层效果一致都是缺几字节就补几字节填充的值就是缺的字节数本身。还有一点值得注意如果你用Hutool默认的SecureUtil.aes()但它内部用的其实是AES/ECB/PKCS5Padding所以你在联调文档里写加密方式时最好写清楚是AES/ECB/PKCS5Padding而不是含含糊糊一个“AES加密”。跨语言实现时这个字符串是对方唯一关心的事。2.4 IV参数为什么CBC模式下IV这么重要IV在最简单层面可以理解为“给加密过程加盐”。相同明文、相同密钥只要IV不同加密出的密文就不同。使用IV有几个硬规矩IV长度必须和分组长度一致AES就是16字节IV不需要保密可以随密文一起传输但它不能被重复使用——同一个密钥下每次加密IV要变在实际系统中IV通常随机生成然后拼在密文前面一起发给对方Hutool的默认SecureUtil.aes()在CBC模式下会自动使用固定IV还是随机IV这里要说清楚Hutool对默认构造的处理偏向“你能用”并不保证每次IV随机所以在生产环境里不要依赖它的默认行为而是要显式传IV进去并且设计好IV的生成与传递方案。3. 5分钟跑通Hutool AES加解密完整实操先说好这一节我直接按“最终能用”的标准来写每一步都是我在项目里实际验证过的。你跟着操作五分钟之内能跑出一个可用的加密工具类。3.1 环境准备与依赖引入Hutool的依赖很简单就一个包dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.25/version /dependency如果你只想引入加密模块不想把整个工具包都拖进来也可以拆分成dependency groupIdcn.hutool/groupId artifactIdhutool-crypto/artifactId version5.8.25/version /dependency第二种子依赖方式需要手写hutool-core的引入吗不需要Hutool的模块化做得挺好hutool-crypto内部会自动带上hutool-core你只管用就行。JDK版本的话1.8以上都能跑没额外要求。3.2 最简用法随机密钥一把梭这个用法适合你只是想快速验证功能、或者不要求跨系统联调的场景import cn.hutool.crypto.SecureUtil; import cn.hutool.crypto.symmetric.AES; public class QuickAesDemo { public static void main(String[] args) { AES aes SecureUtil.aes(); String plainText hello hutool aes; String encryptHex aes.encryptHex(plainText); String encryptBase64 aes.encryptBase64(plainText); String decryptFromHex aes.decryptStr(encryptHex); String decryptFromBase64 aes.decryptStr(encryptBase64); System.out.println(Hex加密结果: encryptHex); System.out.println(Hex解密结果: decryptFromHex); System.out.println(Base64加密结果: encryptBase64); System.out.println(Base64解密结果: decryptFromBase64); System.out.println(密钥: aes.getSecretKey()); } }跑完后你会看到encryptHex出来的是64位十六进制字符encryptBase64出来的是44位Base64字符串解密后都变回hello hutool aes。这两种输出格式有什么差别适用范围不同而已。十六进制在日志、URL参数里比较好读Base64字符串更紧凑但里面可能含有、/、这类需要URL编码的字符。你放到HTTP请求参数里尽量用Hex或者对Base64做一次URL编码不然大概率踩到参数被截断的坑。3.3 自定义密钥真正的业务姿势随机密钥一把梭的问题在于你没法把密钥告诉别人。你加密的数据发给另一个服务对方手里也得有这把密钥才能解密。所以实际开发中密钥一定是双方提前约定、或者通过配置中心分发的固定值。自定义密钥的核心代码import cn.hutool.crypto.SecureUtil; import cn.hutool.crypto.symmetric.AES; import java.nio.charset.StandardCharsets; public class CustomKeyAesDemo { public static void main(String[] args) { // 16字节 - AES-128 String key 1234567890abcdef; // 24字节 - AES-192 // String key 1234567890abcdef12345678; // 32字节 - AES-256 // String key 1234567890abcdef1234567890abcdef; AES aes SecureUtil.aes(key.getBytes(StandardCharsets.UTF_8)); String plainText {\name\:\张三\,\age\:18}; String encryptData aes.encryptBase64(plainText); String decryptData aes.decryptStr(encryptData); System.out.println(密文: encryptData); System.out.println(明文: decryptData); } }这里有个最常见的翻车点密钥字节数不对。你写String key abc然后key.getBytes()拿到的只有3个字节AES初始化直接抛InvalidKeyException。注意Hutool在密钥长度校验上做了一定容错有些版本里它不是直接拒绝而是通过SecureUtil.aes(key)自动补全但这个行为很危险——补全后生成的密钥和你预期的密钥完全不是同一个加解密两边对不上。所以我建议不要依赖工具的自动补全密钥长度必须自己掌控。16字节就是128位24字节就是192位32字节就是256位少了补0或者补到指定长度都行但一定要和对方约定一致。3.4 指定CBC模式与IV一个靠谱的通用模板要说“生产环境直接能用的模板”我推荐用下面这个。它固定使用AES/CBC/PKCS7PaddingIV显式传入密钥来源外部化。import cn.hutool.core.util.CharsetUtil; import cn.hutool.crypto.Mode; import cn.hutool.crypto.Padding; import cn.hutool.crypto.symmetric.AES; import cn.hutool.core.util.HexUtil; import java.nio.charset.StandardCharsets; public class AesCbcWithIvDemo { /** * 加密 * * param data 明文 * param key 密钥, 支持 16/24/32 字节 * param iv 初始化向量, 固定16字节 * param useBase64 true输出Base64false输出Hex */ public static String encrypt(String data, String key, String iv, boolean useBase64) { AES aes new AES(Mode.CBC, Padding.PKCS7Padding, key.getBytes(StandardCharsets.UTF_8), iv.getBytes(StandardCharsets.UTF_8)); return useBase64 ? aes.encryptBase64(data) : aes.encryptHex(data); } /** * 解密 */ public static String decrypt(String data, String key, String iv, boolean isBase64) { AES aes new AES(Mode.CBC, Padding.PKCS7Padding, key.getBytes(StandardCharsets.UTF_8), iv.getBytes(StandardCharsets.UTF_8)); return isBase64 ? aes.decryptStr(data, CharsetUtil.CHARSET_UTF_8) : aes.decryptStr(HexUtil.decodeHex(data)); } public static void main(String[] args) { String key abcdef0123456789abcdef0123456789; // 32字节 String iv 0123456789abcdef; // 16字节 String plainText Hutool AES/CBC/PKCS7Padding 加密测试; String cipherBase64 encrypt(plainText, key, iv, true); String cipherHex encrypt(plainText, key, iv, false); System.out.println(Base64密文: cipherBase64); System.out.println(Hex密文: cipherHex); System.out.println(Base64解密: decrypt(cipherBase64, key, iv, true)); System.out.println(Hex解密: decrypt(cipherHex, key, iv, false)); } }这里面有几个细节值得说明new AES(Mode.CBC, Padding.PKCS7Padding, keyBytes, ivBytes)这个构造是Hutool AES类里比较标准的初始化方式参数顺序别写反前两个是模式和填充后两个是密钥和IV。解密时如果是Base64传入直接decryptStr就行如果是Hex传入你要先HexUtil.decodeHex转成字节数组否则Hutool会把这段Hex字符串当作普通字符串去解密结果必然报错。严格来说PKCS7Padding从JDK原生只支持PKCS5Padding但Hutool内部通过Bouncy Castle做了补充支持所以这里传PKCS7Padding是OK的。但要注意一点——如果你们后续要脱离Hutool、回到原生JCE去解密Hutool加密的数据原生这边用AES/CBC/PKCS5Padding也能解两种填充算法在AES的场景下效果一样。3.5 解密时的一键智能识别有时候你无法确定对方传来的密文到底是Base64还是Hex尤其接口层面两方各写各的很容易格式不统一。Hutool的AES类提供了一个叫decryptStr(String)的方法它内部会自动判断输入的字符串是Hex还是Base64省去手工判断的麻烦。实际测试下来这个方法判断逻辑是能按HexUtil解析成标准Hex字符串就按Hex解否则按Base64解。日常够用但严谨的开发里不要过度依赖这个“自动识别”因为密文如果恰好同时满足Hex和Base64的字符集就可能产生歧义。接口文档里明确格式才是最稳的做法。4. 踩过的坑与排查实录这节算是“花钱买教训”的合集。AES本身不难但细节坑一个接一个我把实际项目中踩过的、帮别人排查过的高频问题都列出来按遇到概率排序。4.1 密钥长度又是上一把钥匙的坑上面其实提过一次这里再展开一下。最经典的错误就是String key password; AES aes SecureUtil.aes(key.getBytes());password只有8个字节肯定不满足16字节要求。不同版本的Hutool行为略有差异有些版本会抛异常提示InvalidKeyException: Invalid AES key length有些版本内部会自动做MD5或者哈希生成一个固定长度密钥第二种行为非常隐蔽。你本地的加密、解密、测试全都能通过直到哪天你把密钥复制到另外一个服务里发现解密出来是乱码——因为两边对同一个原始字符串做的密钥派生方式不同。我的建议是写一个工具方法集中做密钥规范化private static byte[] normalizeKey(String key, int length) { byte[] keyBytes key.getBytes(StandardCharsets.UTF_8); if (keyBytes.length length) { return keyBytes; } // 长度不够就补0长度超出就截断具体策略由双方约定 byte[] normalized new byte[length]; System.arraycopy(keyBytes, 0, normalized, 0, Math.min(keyBytes.length, length)); return normalized; }密钥规范化策略一旦定下来甲乙双方都按这个规则处理就不会出现“本地加解密正常、对接就挂”的诡异问题。4.2 初始化向量写死导致的安全隐患有不少项目图省事把IV写成一个固定字符串放到配置文件里。省事是真省事但安全性大打折扣——因为固定的IV配合固定的密钥CBC模式下相同明文永远产生相同密文等于把ECB模式的毛病又绕回来了。还有一种更麻烦的场景两个系统的IV规则对不上。比如你这边IV是16字节的字符串对方那边IV是32字节的字符串直接对解密抛InvalidAlgorithmParameterException: Wrong IV length。排查半天发现不是算法问题就是IV长度不匹配。正确做法有两种CBC模式下每次加密随机生成IV把IV拼在密文前面比如前16字节是IV后面是密文解密时取前16字节做IV。如果为了简化处理固定IV也可以但密钥必须足够随机且不易泄露同时每次加密内容加上时间戳、随机数等扰动因素避免同样的明文重复出现。我个人在实际项目里更倾向第一种虽然多传了16字节但安全性提升是实打实的。4.3 Base64字符串放进URL被截断Hutool默认的encryptBase64输出可能包含、/、这三个特殊字符。当你把密文放到HTTP GET请求的Query参数里时如果不做URL编码会被解析成空格服务端拿到密文一解就报错。解决方式有几种换encryptHex输出Hex字符串完全避开URL特殊字符问题用URLEncoder.encode(cipherText, UTF-8)编码后再传用Java 8以后的Base64.getUrlEncoder()变体生成URL安全的Base64字符串第三种做法更优雅但Hutool默认的Base64输出是标准Base64所以你要真用这种方案得在拿到encryptBase64结果后再做一次替换处理把换成-把/换成_去掉末尾的。当然如果对端能用标准Base64解码最简单还是方案一。4.4 跨语言联调对齐的细节Hutool加密的数据用Java外的语言解密通常会遇到下面这些坑字符集问题加密时明文转字节数组用的编码不一致两边字符串变成了不同的字节解密出来自然乱码。Java侧我统一用StandardCharsets.UTF_8对方也要保证UTF-8。填充算法叫法不同Java传PKCS5PaddingPython那边是PKCS7两边其实能对齐但前提是双方都明白这个等价关系别一看名字不同就觉得算法不匹配。输出编码格式标识不清一个方用Hex另一个方用Base64联调的时候鸡同鸭讲。文档里一定要写清“密文编码Hex”或者“密文编码Base64”。4.5 解密报错的各种Exception含义速查我整理过一份速查排查问题的时候对着看非常管用。异常类型常见原因解决思路InvalidKeyException密钥长度不是16/24/32字节检查密钥字节数规范化密钥InvalidAlgorithmParameterExceptionIV长度不是16字节检查IV长度CBC/GCM必须16字节BadPaddingException密钥不对、密文被篡改、格式不对用测试数据逐步排查确认密钥、IV、输出格式IllegalBlockSizeException输入的密文不是合法的AES块长度确认Base64/Hex是否正确解码不能直接把字符串塞给解密AEADBadTagExceptionGCM模式下认证标签校验失败密文在传输中被改了或者密钥/IV对不上这个表格我建议你截图存一份。实际项目里遇到解密报错90%都能在上面找到对应解法。5. 生产落地从Demo到可用系统的几个关键动作Demo跑通只是第一步。把加密能力真正落到项目里还有几件事要提前想清楚。5.1 密钥管理策略从第一天就要定我见过最揪心的场景项目上线三个月要对接新服务发现当初的密钥写死在代码里而且没人知道这个密钥是怎么生成的、存到了哪里。所以密钥管理这块越早设计越省事。按复杂度从低到高排序有这几种方案配置文件管理密钥写到application.yml里通过环境变量注入。适合小项目、内网系统但密钥会随着配置一起分发泄露风险高。配置中心管理用配置中心统一管理密钥按环境隔离。应用启动时拉取密钥可以实现不重启就轮换密钥适合大多数中大型项目。KMS/密码机管理密钥由专业密钥管理系统保管应用通过API获取明文密钥或者直接在KMS内部完成加解密运算。适合金融、政务等高安全要求场景代价是引入额外的系统依赖和运维成本。大部分普通互联网项目到配置中心这步就够了。密钥轮换这件事也别忽略真出安全事件时能救你一命。5.2 加密工具类封装的正确姿势虽然Hutool已经把门槛降得很低但我不建议业务代码里到处直接new AES()。比较好的做法是做一个统一静态工具类把密钥来源、模式配置、异常转换都收敛到一处。import cn.hutool.crypto.Mode; import cn.hutool.crypto.Padding; import cn.hutool.crypto.symmetric.AES; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; Component public class AesService { Value(${app.crypto.key:abcdef0123456789abcdef0123456789}) private String key; Value(${app.crypto.iv:0123456789abcdef}) private String iv; private AES aes; private AES getAes() { if (aes null) { synchronized (this) { if (aes null) { aes new AES(Mode.CBC, Padding.PKCS7Padding, key.getBytes(java.nio.charset.StandardCharsets.UTF_8), iv.getBytes(java.nio.charset.StandardCharsets.UTF_8)); } } } return aes; } public String encrypt(String plainText) { return getAes().encryptBase64(plainText); } public String decrypt(String cipherText) { return getAes().decryptStr(cipherText); } }注意AES对象是不是线程安全的Hutool的AES内部持有Cipher而Cipher不是线程安全的。所以你直接用单例AES做并发加解密是有风险的。上面这个例子虽然写了单例但我在实际项目里更推荐的做法是每次调用都创建一个新的AES实例反正创建成本极低。要封装单例就得用ThreadLocalAES或者每次copy避免并发环境下出现加密结果错乱这类诡异问题。5.3 数据签名与加密结合还有一个很容易被忽略的点AES只保证机密性不保证完整性。攻击者虽然解不开你的密文但他可以篡改密文的某一段让解密结果变成一坨乱码或者被截断的残缺数据某些业务系统可能因此产生异常行为。所以对安全性要求高的接口常见的做法是“加密签名”组合先用AES加密数据再对密文或原文做一次HMAC/SHA签名接收方先验证签名再解密。这样密文被篡改签名校验就会失败直接拒绝处理不会走到解密那一步。Hutool也提供了SM4、Hmac等工具类来实现这类组合逻辑。核心思路是加密解决“别人看不懂”签名解决“别人改不了”两者各有分工别混为一谈。6. 用GCM模式实现带认证的现代加密方案前文提到GCM更好这里单独给一套完整可用的GCM代码因为很多人在Hutool里用GCM会遇到一些配置上的小障碍。Hutool的AES类对GCM的封装主要有两种方式通过SecureUtil.aes()默认配置无法直接指定GCM需要手动传入Mode.GCMGCM模式下需要配置GCMParameterSpecHutool的AES构造没有直接暴露这个参数所以更推荐用Cipher配合Hutool的辅助方法来写实际操作中我一般会用原生Cipher实现GCM但复用Hutool的HexUtil和SecureUtil来做编码与密钥生成import cn.hutool.core.util.HexUtil; import cn.hutool.crypto.SecureUtil; import javax.crypto.Cipher; import javax.crypto.spec.GCMParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.SecureRandom; import java.util.Arrays; import java.util.Base64; public class AesGcmDemo { private static final int GCM_IV_LENGTH 12; private static final int GCM_TAG_LENGTH 16; public static String encrypt(String plainText, String key) throws Exception { byte[] keyBytes normalizeKey(key, 32); byte[] iv new byte[GCM_IV_LENGTH]; new SecureRandom().nextBytes(iv); Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); SecretKeySpec keySpec new SecretKeySpec(keyBytes, AES); GCMParameterSpec gcmSpec new GCMParameterSpec(GCM_TAG_LENGTH * 8, iv); cipher.init(Cipher.ENCRYPT_MODE, keySpec, gcmSpec); byte[] cipherBytes cipher.doFinal(plainText.getBytes(StandardCharsets.UTF_8)); // 返回: IV 密文 的 Base64 byte[] result new byte[iv.length cipherBytes.length]; System.arraycopy(iv, 0, result, 0, iv.length); System.arraycopy(cipherBytes, 0, result, iv.length, cipherBytes.length); return Base64.getEncoder().encodeToString(result); } public static String decrypt(String encryptData, String key) throws Exception { byte[] bytes Base64.getDecoder().decode(encryptData); byte[] iv Arrays.copyOfRange(bytes, 0, GCM_IV_LENGTH); byte[] cipherBytes Arrays.copyOfRange(bytes, GCM_IV_LENGTH, bytes.length); Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); SecretKeySpec keySpec new SecretKeySpec(normalizeKey(key, 32), AES); GCMParameterSpec gcmSpec new GCMParameterSpec(GCM_TAG_LENGTH * 8, iv); cipher.init(Cipher.DECRYPT_MODE, keySpec, gcmSpec); byte[] plainBytes cipher.doFinal(cipherBytes); return new String(plainBytes, StandardCharsets.UTF_8); } private static byte[] normalizeKey(String key, int length) { byte[] keyBytes key.getBytes(StandardCharsets.UTF_8); byte[] normalized new byte[length]; System.arraycopy(keyBytes, 0, normalized, 0, Math.min(keyBytes.length, length)); return normalized; } public static void main(String[] args) throws Exception { String key abcdef0123456789abcdef0123456789; String plainText GCM模式加密测试; String cipherData encrypt(plainText, key); System.out.println(密文: cipherData); System.out.println(解密: decrypt(cipherData, key)); } }这套GCM方案有几个特点值得说NoPadding是因为GCM自身带有CTR模式的流式加密特性不需要分组填充IV长度用了12字节这是GCM的推荐长度比CBC的16字节短但GCM内部会把IV扩展为完整计数器用于认证密文末尾包含了16字节的认证标签doFinal后整体输出已经是“密文标签”所以解密时你会看到输出的字节数比明文多16字节我踩过一次比较有意思的坑GCM模式下解密时如果GCMParameterSpec里tag长度传的和密文自带标签长度不一致会抛AEADBadTagException。加密时用了128位tag解密时只给96位直接报错。所以GCM的tag长度一定要两边约定一致不然排查起来很容易忽略。如果你不想在项目里混用原生Cipher和Hutool就用前面CBC那套模板也行。只是从安全性角度新系统如果没历史包袱我强烈建议直接上GCM——CBC加解密之后还得再想方案解决完整性校验GCM一步到位。7. 一个绕不开的话题加密性能与大数据量处理有人可能会问Hutool的AES工具类加密大文件或者批量数据时会不会卡成狗这个问题得分情况看。AES是对称加密加解密速度非常快几MB级别的数据在现代硬件上根本感觉不到延迟。但如果你的业务涉及几百MB甚至GB级文件的加密用Hutool一把梭的方式就不可行了——因为encryptBase64这类方法内部是一次性把数据读入内存大文件会直接OOM。处理大文件的正确姿势是流式加密。Java的CipherInputStream/CipherOutputStream配合AES模式可以边读边加密内存占用恒定。Hutool对这块没有做太多封装所以建议直接用原生API配合一个简单的流式工具方法。import javax.crypto.Cipher; import javax.crypto.CipherInputStream; import javax.crypto.CipherOutputStream; import javax.crypto.spec.SecretKeySpec; import java.io.*; public class AesFileDemo { public static void encryptFile(File src, File dest, String key) throws Exception { Cipher cipher Cipher.getInstance(AES/ECB/PKCS5Padding); SecretKeySpec keySpec new SecretKeySpec(normalizeKey(key, 16), AES); cipher.init(Cipher.ENCRYPT_MODE, keySpec); try (InputStream in new FileInputStream(src); OutputStream out new CipherOutputStream(new FileOutputStream(dest), cipher)) { byte[] buffer new byte[8192]; int len; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); } } } private static byte[] normalizeKey(String key, int length) { byte[] keyBytes key.getBytes(java.nio.charset.StandardCharsets.UTF_8); byte[] normalized new byte[length]; System.arraycopy(keyBytes, 0, normalized, 0, Math.min(keyBytes.length, length)); return normalized; } }这个代码保留了大文件的处理能力同时在密钥处理上复用前面的规范化思想。小业务系统处理个几十MB文件完全够用再大的文件就得考虑分片加密或者对象存储服务端加密了。还有一个性能关注点是加解密本身不是瓶颈密文传输和解码才是。Base64会带来约33%的体积膨胀Hex是100%的膨胀。如果对性能特别敏感比如每秒加解密几十万次的高并发接口可以考虑用二进制密文直接走HTTP Body传输不要转字符串。但代价是日志和排查麻烦这个取舍要看具体业务场景。8. 一些实用建议关于用好Hutool AES这件事代码层面的东西讲得差不多了最后说几个我长期实践下来觉得特别有用的经验和习惯。8.1 测试数据的固定化写单元测试的时候最好用一个编译期固定的密钥和IV并且在测试里写死期望的密文结果。这样做的意义是以后某次升级了Hutool版本、或者换了JDK跑一遍测试就能发现加解密行为是否被影响。加密这块最怕“悄悄变掉”固定测试向量能提前暴露问题。8.2 密文日志脱敏这是很多团队容易忽略的。接口日志里打印了密文看起来似乎无伤大雅因为反正AES解不开。但如果日志系统被拖库攻击者拿着密文和配置泄露的密钥一拼敏感数据就全裸奔了。所以日志里应该打密文的前几位长度比如cipherText3f8a...(48 chars)而不是完整密文。8.3 版本升级时多看release notesHutool的API相对稳定但一些底层细节可能会变。比如早期版本里SecureUtil.aes()对密钥长度的容错行为不同版本之间就有差异。升级依赖的时候如果项目里用了加密能力建议翻一下hutool-crypto模块的变更记录确保没有破坏性改动。8.4 加密≠安全别把AES当成万能神最后也是最重要的一点认知AES加密只是安全方案里的一个环节不是全部。你还需要考虑密钥存储安全、传输通道安全至少要有TLS、日志脱敏、访问控制、审计等一整套措施。把AES用对只是保证“算法层面没拖后腿”但整个系统的安全性是一个体系工程。回到Hutool本身我个人的评价是它是目前Java生态里少有的“把加密工具做得让业务开发能直接用”的库。AES这类对称加密用Hutool和用原生JCE代码量差距肉眼可见但安全性没有任何妥协——底层还是标准的JCE实现算法参数都是标准的。这也是为什么我在团队内部一直推荐大家优先考虑Hutool的原因。如果有人问我“5分钟搞定Java AES加密”是不是噱头我会说如果只是把加密解密跑通五分钟都不用但要在真实项目里用得靠谱、踩的坑少那我上面写的内容值得你花一整个下午过一遍。密码学这行当从来都是“会用”容易“用对”难。希望你读完这篇不只是会调那三个API而是真的理解了背后那几组参数意味着什么。 
长河君 · 2026/10/20 4:53:16 · 阅读 1.2k Hutool实战：Java AES加密参数详解与踩坑指南
1. 工具选型为什么Java里做AES加密要选Hutool先说说我自己的体会。做后端开发这几年凡是牵扯到敏感数据落库、接口报文加密、Token签名这类需求AES都是绕不开的标准答案。但你如果真拿JDK原生的JCE接口去写那酸爽程度基本等于用筷子喝汤——能喝但费劲。原生写法大概是这样的先搞KeyGenerator再配SecretKeySpec然后手动初始化Cipher指定algorithm、mode、padding还得处理Base64编码、byte[]和String互转稍微不留神就是一个BadPaddingException砸脸上。这套流程写个三五次也就罢了如果每个项目都有那纯属重复造轮子还没造好。Hutool的crypto模块做得比较聪明的点是把复杂的东西收敛成了几个高频入口。你要做对称加密就只跟SecureUtil和AES这俩类打交道你要做非对称有RSA摘要有DigestUtil签名有SignUtil。不需要理解底层的Cipher初始化细节但它又保留了让你自定义mode、padding、iv的能力。说白了就是——默认给你最省事的写法同时也留了让你精细控制的接口这比很多工具类一锤子买卖的设计要实在得多。拿AES举例Hutool提供的默认行为是这样的不传参调用SecureUtil.aes()时自动生成一个随机密钥加密输出默认是Base64字符串如果你传了密钥字节数组则使用你指定的密钥。这个接口设计对业务代码特别友好——你不需要关心SecureUtil.aes()底层到底是ECB还是CBC因为它在内部已经把Cipher.getInstance(AES)这套流程封装好了。我实际用下来还有一个很直观的感受Hutool的加密结果在跨语言验证时挖坑少。Java默认的AES/ECB/PKCS5Padding在Hutool里就是默认配置这意味着你用Hutool加密出来的东西放到Python、Go或者Node.js里去解密彼此之间用同样参数就能对齐。这一点对微服务架构里多个团队各写各的服务端尤其重要——大家都用同一个标准的算法参数沟通成本直线降低。当然也不是说Hutool就是银弹。如果你的项目本身有严格的等保要求或者你们安全团队明确要基于Bouncy Castle做定制化加密方案那Hutool不是一个必须项。但就“日常开发里快速、靠谱地实现AES加解密”这个需求来说它的性价比几乎是最高的。2. AES加密的核心参数不懂这些等于白做很多新手上来就跑SecureUtil.aes()一把梭倒也能跑通。但一旦遇到要和别的系统联调或者需要改模式、换IV就直接抓瞎了。所以编码之前这几个概念最好先搞清楚。它们决定了你能不能用好AES也决定了你的密文到底是“可解密的”还是“一锤子买卖”。2.1 密钥长度128、192、256究竟怎么选AES是一种分组密码它支持三种密钥长度128位16字节、192位24字节、256位32字节。不用被数字吓到直接理解成密钥越长暴力破解的成本越高。128位在当前算力下已经足够安全商用场景里大部分系统选128位如果项目里有安全合规的硬性指标、或者传输的数据特别敏感可以上256位但代价并不是加密变慢——256位AES的单次运算开销其实高不了多少——真正的坑在于JDK默认不支持256位密钥。Java 8及更早版本的JDK里如果没装Java Cryptography ExtensionJCE无限制权限策略文件AES-256直接抛InvalidKeyException: Illegal key size。JDK 9以后这限制才默认放开。所以你如果是老项目跑在JDK 8上想用256位密钥第一件事是确认JCE补丁装没装不然代码写对了一样跑不起来。实际操作里选多少位我一般看对接方的标准。自研系统内部用我会直接上256但要对外联调先问对方支持什么长度。因为有些老系统的加密模块写死了128位你要用256两边一通折腾就是浪费工时。2.2 工作模式ECB、CBC、GCM的取舍这是最容易搞混的部分也是联调时最容易翻车的部分。AES底层是按固定长度分组加密的分组长度固定为128位16字节但多个分组之间怎么关联就是“模式”的事了。ECB模式每个分组独立加密相互不影响。优点是简单、能并行计算缺点也致命——相同明文块会产生相同密文块有概率性泄漏信息。现在安全性要求高的场景都不推荐ECB但为什么Hutool的默认还是ECB因为Java原生Cipher.getInstance(AES)默认就是它Hutool保持了这个兼容性。如果你只在系统内部用、且数据没有明显的重复模式比如随机生成的TokenECB勉强能用如果加密的是JSON、XML这种结构重复明显的文本建议老老实实换CBC。CBC模式每个分组先和上一个分组的密文做异或再加密。这样相同的明文块在不同位置也产生不同的密文块。它需要一个初始向量IV第一个分组没有“上一个密文”就用IV顶替。CBC的加密是串行的性能比ECB略低但安全性好很多是目前应用最广的模式之一。GCM模式属于AEAD模式加密的同时生成认证标签能同时保证机密性、完整性还天然防篡改。现在很多新系统的接口加密、或者TLS里的数据加密都在用GCM。它的好处是省掉了额外做HMAC的活儿一个方案解决两个问题。选型建议其实就一句话没有强烈的兼容性要求优先选CBC或GCM如果允许我用GCM我就不会选CBC因为认证标签真的能帮你挡掉一堆“密文被人改了”的麻烦。2.3 填充方式PKCS5Padding和PKCS7Padding的选择AES加密是按16字节分组进行的但你要加密的数据长度不可能刚好都是16的倍数所以最后一块需要填充。Java原生只提供了PKCS5Padding但大家心里都清楚AES的分组是16字节严格来说应该叫PKCS7PaddingJava里之所以叫PKCS5是因为JDK早期把这两个概念混用了。Hutool的做法是二者都支持你传Padding.PKCS5Padding或Padding.PKCS7Padding都行底层效果一致都是缺几字节就补几字节填充的值就是缺的字节数本身。还有一点值得注意如果你用Hutool默认的SecureUtil.aes()但它内部用的其实是AES/ECB/PKCS5Padding所以你在联调文档里写加密方式时最好写清楚是AES/ECB/PKCS5Padding而不是含含糊糊一个“AES加密”。跨语言实现时这个字符串是对方唯一关心的事。2.4 IV参数为什么CBC模式下IV这么重要IV在最简单层面可以理解为“给加密过程加盐”。相同明文、相同密钥只要IV不同加密出的密文就不同。使用IV有几个硬规矩IV长度必须和分组长度一致AES就是16字节IV不需要保密可以随密文一起传输但它不能被重复使用——同一个密钥下每次加密IV要变在实际系统中IV通常随机生成然后拼在密文前面一起发给对方Hutool的默认SecureUtil.aes()在CBC模式下会自动使用固定IV还是随机IV这里要说清楚Hutool对默认构造的处理偏向“你能用”并不保证每次IV随机所以在生产环境里不要依赖它的默认行为而是要显式传IV进去并且设计好IV的生成与传递方案。3. 5分钟跑通Hutool AES加解密完整实操先说好这一节我直接按“最终能用”的标准来写每一步都是我在项目里实际验证过的。你跟着操作五分钟之内能跑出一个可用的加密工具类。3.1 环境准备与依赖引入Hutool的依赖很简单就一个包dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.25/version /dependency如果你只想引入加密模块不想把整个工具包都拖进来也可以拆分成dependency groupIdcn.hutool/groupId artifactIdhutool-crypto/artifactId version5.8.25/version /dependency第二种子依赖方式需要手写hutool-core的引入吗不需要Hutool的模块化做得挺好hutool-crypto内部会自动带上hutool-core你只管用就行。JDK版本的话1.8以上都能跑没额外要求。3.2 最简用法随机密钥一把梭这个用法适合你只是想快速验证功能、或者不要求跨系统联调的场景import cn.hutool.crypto.SecureUtil; import cn.hutool.crypto.symmetric.AES; public class QuickAesDemo { public static void main(String[] args) { AES aes SecureUtil.aes(); String plainText hello hutool aes; String encryptHex aes.encryptHex(plainText); String encryptBase64 aes.encryptBase64(plainText); String decryptFromHex aes.decryptStr(encryptHex); String decryptFromBase64 aes.decryptStr(encryptBase64); System.out.println(Hex加密结果: encryptHex); System.out.println(Hex解密结果: decryptFromHex); System.out.println(Base64加密结果: encryptBase64); System.out.println(Base64解密结果: decryptFromBase64); System.out.println(密钥: aes.getSecretKey()); } }跑完后你会看到encryptHex出来的是64位十六进制字符encryptBase64出来的是44位Base64字符串解密后都变回hello hutool aes。这两种输出格式有什么差别适用范围不同而已。十六进制在日志、URL参数里比较好读Base64字符串更紧凑但里面可能含有、/、这类需要URL编码的字符。你放到HTTP请求参数里尽量用Hex或者对Base64做一次URL编码不然大概率踩到参数被截断的坑。3.3 自定义密钥真正的业务姿势随机密钥一把梭的问题在于你没法把密钥告诉别人。你加密的数据发给另一个服务对方手里也得有这把密钥才能解密。所以实际开发中密钥一定是双方提前约定、或者通过配置中心分发的固定值。自定义密钥的核心代码import cn.hutool.crypto.SecureUtil; import cn.hutool.crypto.symmetric.AES; import java.nio.charset.StandardCharsets; public class CustomKeyAesDemo { public static void main(String[] args) { // 16字节 - AES-128 String key 1234567890abcdef; // 24字节 - AES-192 // String key 1234567890abcdef12345678; // 32字节 - AES-256 // String key 1234567890abcdef1234567890abcdef; AES aes SecureUtil.aes(key.getBytes(StandardCharsets.UTF_8)); String plainText {\name\:\张三\,\age\:18}; String encryptData aes.encryptBase64(plainText); String decryptData aes.decryptStr(encryptData); System.out.println(密文: encryptData); System.out.println(明文: decryptData); } }这里有个最常见的翻车点密钥字节数不对。你写String key abc然后key.getBytes()拿到的只有3个字节AES初始化直接抛InvalidKeyException。注意Hutool在密钥长度校验上做了一定容错有些版本里它不是直接拒绝而是通过SecureUtil.aes(key)自动补全但这个行为很危险——补全后生成的密钥和你预期的密钥完全不是同一个加解密两边对不上。所以我建议不要依赖工具的自动补全密钥长度必须自己掌控。16字节就是128位24字节就是192位32字节就是256位少了补0或者补到指定长度都行但一定要和对方约定一致。3.4 指定CBC模式与IV一个靠谱的通用模板要说“生产环境直接能用的模板”我推荐用下面这个。它固定使用AES/CBC/PKCS7PaddingIV显式传入密钥来源外部化。import cn.hutool.core.util.CharsetUtil; import cn.hutool.crypto.Mode; import cn.hutool.crypto.Padding; import cn.hutool.crypto.symmetric.AES; import cn.hutool.core.util.HexUtil; import java.nio.charset.StandardCharsets; public class AesCbcWithIvDemo { /** * 加密 * * param data 明文 * param key 密钥, 支持 16/24/32 字节 * param iv 初始化向量, 固定16字节 * param useBase64 true输出Base64false输出Hex */ public static String encrypt(String data, String key, String iv, boolean useBase64) { AES aes new AES(Mode.CBC, Padding.PKCS7Padding, key.getBytes(StandardCharsets.UTF_8), iv.getBytes(StandardCharsets.UTF_8)); return useBase64 ? aes.encryptBase64(data) : aes.encryptHex(data); } /** * 解密 */ public static String decrypt(String data, String key, String iv, boolean isBase64) { AES aes new AES(Mode.CBC, Padding.PKCS7Padding, key.getBytes(StandardCharsets.UTF_8), iv.getBytes(StandardCharsets.UTF_8)); return isBase64 ? aes.decryptStr(data, CharsetUtil.CHARSET_UTF_8) : aes.decryptStr(HexUtil.decodeHex(data)); } public static void main(String[] args) { String key abcdef0123456789abcdef0123456789; // 32字节 String iv 0123456789abcdef; // 16字节 String plainText Hutool AES/CBC/PKCS7Padding 加密测试; String cipherBase64 encrypt(plainText, key, iv, true); String cipherHex encrypt(plainText, key, iv, false); System.out.println(Base64密文: cipherBase64); System.out.println(Hex密文: cipherHex); System.out.println(Base64解密: decrypt(cipherBase64, key, iv, true)); System.out.println(Hex解密: decrypt(cipherHex, key, iv, false)); } }这里面有几个细节值得说明new AES(Mode.CBC, Padding.PKCS7Padding, keyBytes, ivBytes)这个构造是Hutool AES类里比较标准的初始化方式参数顺序别写反前两个是模式和填充后两个是密钥和IV。解密时如果是Base64传入直接decryptStr就行如果是Hex传入你要先HexUtil.decodeHex转成字节数组否则Hutool会把这段Hex字符串当作普通字符串去解密结果必然报错。严格来说PKCS7Padding从JDK原生只支持PKCS5Padding但Hutool内部通过Bouncy Castle做了补充支持所以这里传PKCS7Padding是OK的。但要注意一点——如果你们后续要脱离Hutool、回到原生JCE去解密Hutool加密的数据原生这边用AES/CBC/PKCS5Padding也能解两种填充算法在AES的场景下效果一样。3.5 解密时的一键智能识别有时候你无法确定对方传来的密文到底是Base64还是Hex尤其接口层面两方各写各的很容易格式不统一。Hutool的AES类提供了一个叫decryptStr(String)的方法它内部会自动判断输入的字符串是Hex还是Base64省去手工判断的麻烦。实际测试下来这个方法判断逻辑是能按HexUtil解析成标准Hex字符串就按Hex解否则按Base64解。日常够用但严谨的开发里不要过度依赖这个“自动识别”因为密文如果恰好同时满足Hex和Base64的字符集就可能产生歧义。接口文档里明确格式才是最稳的做法。4. 踩过的坑与排查实录这节算是“花钱买教训”的合集。AES本身不难但细节坑一个接一个我把实际项目中踩过的、帮别人排查过的高频问题都列出来按遇到概率排序。4.1 密钥长度又是上一把钥匙的坑上面其实提过一次这里再展开一下。最经典的错误就是String key password; AES aes SecureUtil.aes(key.getBytes());password只有8个字节肯定不满足16字节要求。不同版本的Hutool行为略有差异有些版本会抛异常提示InvalidKeyException: Invalid AES key length有些版本内部会自动做MD5或者哈希生成一个固定长度密钥第二种行为非常隐蔽。你本地的加密、解密、测试全都能通过直到哪天你把密钥复制到另外一个服务里发现解密出来是乱码——因为两边对同一个原始字符串做的密钥派生方式不同。我的建议是写一个工具方法集中做密钥规范化private static byte[] normalizeKey(String key, int length) { byte[] keyBytes key.getBytes(StandardCharsets.UTF_8); if (keyBytes.length length) { return keyBytes; } // 长度不够就补0长度超出就截断具体策略由双方约定 byte[] normalized new byte[length]; System.arraycopy(keyBytes, 0, normalized, 0, Math.min(keyBytes.length, length)); return normalized; }密钥规范化策略一旦定下来甲乙双方都按这个规则处理就不会出现“本地加解密正常、对接就挂”的诡异问题。4.2 初始化向量写死导致的安全隐患有不少项目图省事把IV写成一个固定字符串放到配置文件里。省事是真省事但安全性大打折扣——因为固定的IV配合固定的密钥CBC模式下相同明文永远产生相同密文等于把ECB模式的毛病又绕回来了。还有一种更麻烦的场景两个系统的IV规则对不上。比如你这边IV是16字节的字符串对方那边IV是32字节的字符串直接对解密抛InvalidAlgorithmParameterException: Wrong IV length。排查半天发现不是算法问题就是IV长度不匹配。正确做法有两种CBC模式下每次加密随机生成IV把IV拼在密文前面比如前16字节是IV后面是密文解密时取前16字节做IV。如果为了简化处理固定IV也可以但密钥必须足够随机且不易泄露同时每次加密内容加上时间戳、随机数等扰动因素避免同样的明文重复出现。我个人在实际项目里更倾向第一种虽然多传了16字节但安全性提升是实打实的。4.3 Base64字符串放进URL被截断Hutool默认的encryptBase64输出可能包含、/、这三个特殊字符。当你把密文放到HTTP GET请求的Query参数里时如果不做URL编码会被解析成空格服务端拿到密文一解就报错。解决方式有几种换encryptHex输出Hex字符串完全避开URL特殊字符问题用URLEncoder.encode(cipherText, UTF-8)编码后再传用Java 8以后的Base64.getUrlEncoder()变体生成URL安全的Base64字符串第三种做法更优雅但Hutool默认的Base64输出是标准Base64所以你要真用这种方案得在拿到encryptBase64结果后再做一次替换处理把换成-把/换成_去掉末尾的。当然如果对端能用标准Base64解码最简单还是方案一。4.4 跨语言联调对齐的细节Hutool加密的数据用Java外的语言解密通常会遇到下面这些坑字符集问题加密时明文转字节数组用的编码不一致两边字符串变成了不同的字节解密出来自然乱码。Java侧我统一用StandardCharsets.UTF_8对方也要保证UTF-8。填充算法叫法不同Java传PKCS5PaddingPython那边是PKCS7两边其实能对齐但前提是双方都明白这个等价关系别一看名字不同就觉得算法不匹配。输出编码格式标识不清一个方用Hex另一个方用Base64联调的时候鸡同鸭讲。文档里一定要写清“密文编码Hex”或者“密文编码Base64”。4.5 解密报错的各种Exception含义速查我整理过一份速查排查问题的时候对着看非常管用。异常类型常见原因解决思路InvalidKeyException密钥长度不是16/24/32字节检查密钥字节数规范化密钥InvalidAlgorithmParameterExceptionIV长度不是16字节检查IV长度CBC/GCM必须16字节BadPaddingException密钥不对、密文被篡改、格式不对用测试数据逐步排查确认密钥、IV、输出格式IllegalBlockSizeException输入的密文不是合法的AES块长度确认Base64/Hex是否正确解码不能直接把字符串塞给解密AEADBadTagExceptionGCM模式下认证标签校验失败密文在传输中被改了或者密钥/IV对不上这个表格我建议你截图存一份。实际项目里遇到解密报错90%都能在上面找到对应解法。5. 生产落地从Demo到可用系统的几个关键动作Demo跑通只是第一步。把加密能力真正落到项目里还有几件事要提前想清楚。5.1 密钥管理策略从第一天就要定我见过最揪心的场景项目上线三个月要对接新服务发现当初的密钥写死在代码里而且没人知道这个密钥是怎么生成的、存到了哪里。所以密钥管理这块越早设计越省事。按复杂度从低到高排序有这几种方案配置文件管理密钥写到application.yml里通过环境变量注入。适合小项目、内网系统但密钥会随着配置一起分发泄露风险高。配置中心管理用配置中心统一管理密钥按环境隔离。应用启动时拉取密钥可以实现不重启就轮换密钥适合大多数中大型项目。KMS/密码机管理密钥由专业密钥管理系统保管应用通过API获取明文密钥或者直接在KMS内部完成加解密运算。适合金融、政务等高安全要求场景代价是引入额外的系统依赖和运维成本。大部分普通互联网项目到配置中心这步就够了。密钥轮换这件事也别忽略真出安全事件时能救你一命。5.2 加密工具类封装的正确姿势虽然Hutool已经把门槛降得很低但我不建议业务代码里到处直接new AES()。比较好的做法是做一个统一静态工具类把密钥来源、模式配置、异常转换都收敛到一处。import cn.hutool.crypto.Mode; import cn.hutool.crypto.Padding; import cn.hutool.crypto.symmetric.AES; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; Component public class AesService { Value(${app.crypto.key:abcdef0123456789abcdef0123456789}) private String key; Value(${app.crypto.iv:0123456789abcdef}) private String iv; private AES aes; private AES getAes() { if (aes null) { synchronized (this) { if (aes null) { aes new AES(Mode.CBC, Padding.PKCS7Padding, key.getBytes(java.nio.charset.StandardCharsets.UTF_8), iv.getBytes(java.nio.charset.StandardCharsets.UTF_8)); } } } return aes; } public String encrypt(String plainText) { return getAes().encryptBase64(plainText); } public String decrypt(String cipherText) { return getAes().decryptStr(cipherText); } }注意AES对象是不是线程安全的Hutool的AES内部持有Cipher而Cipher不是线程安全的。所以你直接用单例AES做并发加解密是有风险的。上面这个例子虽然写了单例但我在实际项目里更推荐的做法是每次调用都创建一个新的AES实例反正创建成本极低。要封装单例就得用ThreadLocalAES或者每次copy避免并发环境下出现加密结果错乱这类诡异问题。5.3 数据签名与加密结合还有一个很容易被忽略的点AES只保证机密性不保证完整性。攻击者虽然解不开你的密文但他可以篡改密文的某一段让解密结果变成一坨乱码或者被截断的残缺数据某些业务系统可能因此产生异常行为。所以对安全性要求高的接口常见的做法是“加密签名”组合先用AES加密数据再对密文或原文做一次HMAC/SHA签名接收方先验证签名再解密。这样密文被篡改签名校验就会失败直接拒绝处理不会走到解密那一步。Hutool也提供了SM4、Hmac等工具类来实现这类组合逻辑。核心思路是加密解决“别人看不懂”签名解决“别人改不了”两者各有分工别混为一谈。6. 用GCM模式实现带认证的现代加密方案前文提到GCM更好这里单独给一套完整可用的GCM代码因为很多人在Hutool里用GCM会遇到一些配置上的小障碍。Hutool的AES类对GCM的封装主要有两种方式通过SecureUtil.aes()默认配置无法直接指定GCM需要手动传入Mode.GCMGCM模式下需要配置GCMParameterSpecHutool的AES构造没有直接暴露这个参数所以更推荐用Cipher配合Hutool的辅助方法来写实际操作中我一般会用原生Cipher实现GCM但复用Hutool的HexUtil和SecureUtil来做编码与密钥生成import cn.hutool.core.util.HexUtil; import cn.hutool.crypto.SecureUtil; import javax.crypto.Cipher; import javax.crypto.spec.GCMParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.SecureRandom; import java.util.Arrays; import java.util.Base64; public class AesGcmDemo { private static final int GCM_IV_LENGTH 12; private static final int GCM_TAG_LENGTH 16; public static String encrypt(String plainText, String key) throws Exception { byte[] keyBytes normalizeKey(key, 32); byte[] iv new byte[GCM_IV_LENGTH]; new SecureRandom().nextBytes(iv); Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); SecretKeySpec keySpec new SecretKeySpec(keyBytes, AES); GCMParameterSpec gcmSpec new GCMParameterSpec(GCM_TAG_LENGTH * 8, iv); cipher.init(Cipher.ENCRYPT_MODE, keySpec, gcmSpec); byte[] cipherBytes cipher.doFinal(plainText.getBytes(StandardCharsets.UTF_8)); // 返回: IV 密文 的 Base64 byte[] result new byte[iv.length cipherBytes.length]; System.arraycopy(iv, 0, result, 0, iv.length); System.arraycopy(cipherBytes, 0, result, iv.length, cipherBytes.length); return Base64.getEncoder().encodeToString(result); } public static String decrypt(String encryptData, String key) throws Exception { byte[] bytes Base64.getDecoder().decode(encryptData); byte[] iv Arrays.copyOfRange(bytes, 0, GCM_IV_LENGTH); byte[] cipherBytes Arrays.copyOfRange(bytes, GCM_IV_LENGTH, bytes.length); Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); SecretKeySpec keySpec new SecretKeySpec(normalizeKey(key, 32), AES); GCMParameterSpec gcmSpec new GCMParameterSpec(GCM_TAG_LENGTH * 8, iv); cipher.init(Cipher.DECRYPT_MODE, keySpec, gcmSpec); byte[] plainBytes cipher.doFinal(cipherBytes); return new String(plainBytes, StandardCharsets.UTF_8); } private static byte[] normalizeKey(String key, int length) { byte[] keyBytes key.getBytes(StandardCharsets.UTF_8); byte[] normalized new byte[length]; System.arraycopy(keyBytes, 0, normalized, 0, Math.min(keyBytes.length, length)); return normalized; } public static void main(String[] args) throws Exception { String key abcdef0123456789abcdef0123456789; String plainText GCM模式加密测试; String cipherData encrypt(plainText, key); System.out.println(密文: cipherData); System.out.println(解密: decrypt(cipherData, key)); } }这套GCM方案有几个特点值得说NoPadding是因为GCM自身带有CTR模式的流式加密特性不需要分组填充IV长度用了12字节这是GCM的推荐长度比CBC的16字节短但GCM内部会把IV扩展为完整计数器用于认证密文末尾包含了16字节的认证标签doFinal后整体输出已经是“密文标签”所以解密时你会看到输出的字节数比明文多16字节我踩过一次比较有意思的坑GCM模式下解密时如果GCMParameterSpec里tag长度传的和密文自带标签长度不一致会抛AEADBadTagException。加密时用了128位tag解密时只给96位直接报错。所以GCM的tag长度一定要两边约定一致不然排查起来很容易忽略。如果你不想在项目里混用原生Cipher和Hutool就用前面CBC那套模板也行。只是从安全性角度新系统如果没历史包袱我强烈建议直接上GCM——CBC加解密之后还得再想方案解决完整性校验GCM一步到位。7. 一个绕不开的话题加密性能与大数据量处理有人可能会问Hutool的AES工具类加密大文件或者批量数据时会不会卡成狗这个问题得分情况看。AES是对称加密加解密速度非常快几MB级别的数据在现代硬件上根本感觉不到延迟。但如果你的业务涉及几百MB甚至GB级文件的加密用Hutool一把梭的方式就不可行了——因为encryptBase64这类方法内部是一次性把数据读入内存大文件会直接OOM。处理大文件的正确姿势是流式加密。Java的CipherInputStream/CipherOutputStream配合AES模式可以边读边加密内存占用恒定。Hutool对这块没有做太多封装所以建议直接用原生API配合一个简单的流式工具方法。import javax.crypto.Cipher; import javax.crypto.CipherInputStream; import javax.crypto.CipherOutputStream; import javax.crypto.spec.SecretKeySpec; import java.io.*; public class AesFileDemo { public static void encryptFile(File src, File dest, String key) throws Exception { Cipher cipher Cipher.getInstance(AES/ECB/PKCS5Padding); SecretKeySpec keySpec new SecretKeySpec(normalizeKey(key, 16), AES); cipher.init(Cipher.ENCRYPT_MODE, keySpec); try (InputStream in new FileInputStream(src); OutputStream out new CipherOutputStream(new FileOutputStream(dest), cipher)) { byte[] buffer new byte[8192]; int len; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); } } } private static byte[] normalizeKey(String key, int length) { byte[] keyBytes key.getBytes(java.nio.charset.StandardCharsets.UTF_8); byte[] normalized new byte[length]; System.arraycopy(keyBytes, 0, normalized, 0, Math.min(keyBytes.length, length)); return normalized; } }这个代码保留了大文件的处理能力同时在密钥处理上复用前面的规范化思想。小业务系统处理个几十MB文件完全够用再大的文件就得考虑分片加密或者对象存储服务端加密了。还有一个性能关注点是加解密本身不是瓶颈密文传输和解码才是。Base64会带来约33%的体积膨胀Hex是100%的膨胀。如果对性能特别敏感比如每秒加解密几十万次的高并发接口可以考虑用二进制密文直接走HTTP Body传输不要转字符串。但代价是日志和排查麻烦这个取舍要看具体业务场景。8. 一些实用建议关于用好Hutool AES这件事代码层面的东西讲得差不多了最后说几个我长期实践下来觉得特别有用的经验和习惯。8.1 测试数据的固定化写单元测试的时候最好用一个编译期固定的密钥和IV并且在测试里写死期望的密文结果。这样做的意义是以后某次升级了Hutool版本、或者换了JDK跑一遍测试就能发现加解密行为是否被影响。加密这块最怕“悄悄变掉”固定测试向量能提前暴露问题。8.2 密文日志脱敏这是很多团队容易忽略的。接口日志里打印了密文看起来似乎无伤大雅因为反正AES解不开。但如果日志系统被拖库攻击者拿着密文和配置泄露的密钥一拼敏感数据就全裸奔了。所以日志里应该打密文的前几位长度比如cipherText3f8a...(48 chars)而不是完整密文。8.3 版本升级时多看release notesHutool的API相对稳定但一些底层细节可能会变。比如早期版本里SecureUtil.aes()对密钥长度的容错行为不同版本之间就有差异。升级依赖的时候如果项目里用了加密能力建议翻一下hutool-crypto模块的变更记录确保没有破坏性改动。8.4 加密≠安全别把AES当成万能神最后也是最重要的一点认知AES加密只是安全方案里的一个环节不是全部。你还需要考虑密钥存储安全、传输通道安全至少要有TLS、日志脱敏、访问控制、审计等一整套措施。把AES用对只是保证“算法层面没拖后腿”但整个系统的安全性是一个体系工程。回到Hutool本身我个人的评价是它是目前Java生态里少有的“把加密工具做得让业务开发能直接用”的库。AES这类对称加密用Hutool和用原生JCE代码量差距肉眼可见但安全性没有任何妥协——底层还是标准的JCE实现算法参数都是标准的。这也是为什么我在团队内部一直推荐大家优先考虑Hutool的原因。如果有人问我“5分钟搞定Java AES加密”是不是噱头我会说如果只是把加密解密跑通五分钟都不用但要在真实项目里用得靠谱、踩的坑少那我上面写的内容值得你花一整个下午过一遍。密码学这行当从来都是“会用”容易“用对”难。希望你读完这篇不只是会调那三个API而是真的理解了背后那几组参数意味着什么。