规范说明：AES工具类使用规范及注意事项

AES工具类使用规范及注意事项本文档针对项目中AesUtilsAES加解密工具类、AesKeyGenerator密钥生成工具的使用场景、操作规范、注意事项进行明确说明确保开发人员正确使用避免因使用不当导致加密失败、数据泄露、系统异常等问题保障系统数据安全及功能稳定性。一、工具类适用场景AesUtils用于项目中敏感数据的加解密操作包括但不限于用户手机号、身份证号、密码辅助加密建议密码优先使用加密算法、核心业务配置等敏感信息的加密存储与解密展示。AesKeyGenerator仅用于生成符合AES-256-CBC规范的密钥32位和偏移量16位仅在项目初始化、密钥更新时使用禁止在业务代码中频繁调用生成密钥。二、核心使用规范1. 配置规范密钥aes.key和偏移量aes.iv必须通过AesKeyGenerator生成严禁手动编写、修改密钥/偏移量避免密钥泄露或不符合长度要求。配置文件application.yml中aes相关配置需单独配置严禁与其他配置混淆密钥和偏移量需保密生产环境中禁止明文暴露建议通过配置中心加密存储。密钥和偏移量一旦确定并投入使用禁止随意修改若需更新密钥需先完成历史加密数据的解密迁移再替换配置避免数据无法解密。2. AesUtils调用规范调用方式直接通过类名静态调用无需实例化示例AesUtils.encrypt(#34;明文内容#34;)、AesUtils.decrypt(#34;密文内容#34;)。加密规范待加密数据为null或空字符串时工具类返回空字符串无需额外做空值判断非敏感数据禁止使用该工具类加密避免不必要的性能损耗。解密规范解密数据为null或空字符串时工具类会抛出BusinessException调用方需捕获该异常并做合理处理如提示用户“解密数据异常”严禁直接抛出未处理。编码规范加密和解密均使用UTF-8编码禁止自行修改编码格式避免出现乱码、解密失败问题。3. AesKeyGenerator使用规范运行方式直接运行该类的main方法即可生成符合要求的密钥和偏移量生成后直接复制到application.yml中对应配置项无需修改格式。生成频率仅在项目初始化、密钥泄露、密钥过期时生成一次生成后需妥善保存密钥备份避免丢失导致历史数据无法解密。安全规范生成的密钥和偏移量禁止截图、明文传输、随意存放建议仅告知项目负责人和核心开发人员。三、关键注意事项工具类依赖Spring环境内部通过ApplicationContextHolder获取配置但本身无Component注解无需手动注入直接静态调用即可若脱离Spring环境使用会导致初始化失败需提前确认运行环境。加密算法固定为AES-256-CBC-PKCS5Padding严禁修改算法、模式或填充方式否则会导致加解密不兼容历史数据无法解密。密钥长度必须为32位、偏移量必须为16位工具类初始化时会自动校验若配置不符合要求会抛出IllegalStateException需检查配置后重启项目。禁止修改AesUtils、AesKeyGenerator的核心逻辑如加密解密流程、密钥校验、静态代码块若需优化需经过项目负责人确认避免引入bug。单元测试必须覆盖加密、解密、空值处理、异常处理等场景每次修改工具类后需重新执行单元测试确保功能正常。四、异常处理规范初始化异常工具类初始化时静态代码块若配置缺失、密钥/偏移量长度不符会抛出RuntimeException导致项目启动失败需优先检查application.yml中aes配置。加密异常加密过程中出现异常如数据格式异常、算法不支持会抛出BusinessException调用方需捕获异常记录日志并给用户友好提示避免直接暴露异常详情。解密异常解密过程中出现异常如密文篡改、密钥不匹配、密文格式错误会抛出BusinessException调用方需捕获异常排查密文有效性、密钥一致性禁止忽略异常。五、维护规范定期检查密钥安全性建议每6-12个月更新一次密钥更新时需做好历史数据迁移和备份。定期检查工具类使用情况清理无效调用如非敏感数据加密优化性能。若项目升级Spring版本需重新测试AesUtils功能确保上下文获取、配置读取正常无兼容性问题。工具类相关文档本规范、工具类注释需与代码同步更新确保文档与实际功能一致。六、禁忌事项禁止将AesUtils用于非敏感数据的加解密避免浪费系统资源。禁止手动修改密钥、偏移量的长度或内容禁止使用非AesKeyGenerator生成的密钥/偏移量。禁止在日志中打印明文、密钥、偏移量、密文等敏感信息避免信息泄露。禁止将AesKeyGenerator的main方法保留在生产环境代码中可在打包时排除或注释掉main方法避免误操作生成新密钥。禁止在多线程环境中频繁调用AesUtils的加解密方法若有大量加解密需求需做线程安全处理避免性能瓶颈。