1. 项目概述为什么我们需要在NBSaaS-Boot中集成AES加解密如果你正在用NBSaaS-Boot这类快速开发框架搭建一个对外提供API的服务尤其是涉及用户敏感信息或金融交易数据的场景那么数据在传输过程中的安全性就是你绕不开的一道坎。直接明文传输用户名、密码、身份证号、手机号这无异于在互联网上“裸奔”。虽然HTTPSSSL/TLS已经为传输链路提供了加密保障但在某些安全等级要求更高的场景下我们还需要对传输的业务数据本身进行二次加密这就是所谓的“端到端加密”或“应用层加密”。AES高级加密标准作为目前全球公认最安全、最主流的对称加密算法自然成了实现这一需求的首选。它的速度快、安全性高且被各种语言和平台广泛支持。但问题来了难道我们要在每个Controller接口里都手动写一遍加密解密的逻辑吗这显然违背了NBSaaS-Boot这类框架“快速开发”的初衷代码会变得臃肿且难以维护。所以我们今天要聊的就是如何利用NBSaaS-Boot一个基于Spring Boot的快速开发脚手架的特性以最优雅、侵入性最低的方式实现请求Body的自动AES解密和响应Body的自动AES加密。目标很简单让业务开发者像写普通接口一样开发加解密过程对开发者透明由框架在“背后”自动完成。这不仅能大幅提升开发效率更能统一安全规范避免因开发者水平不一导致的安全漏洞。2. 核心方案设计拦截器与消息转换器的双剑合璧要实现请求和响应的自动处理我们不能去改每一个业务方法而是要在HTTP请求到达Controller之前以及Controller返回结果之后这两个关键节点进行拦截和转换。在Spring Boot也就是NBSaaS-Boot的底层的世界里我们有两大神器拦截器Interceptor和消息转换器HttpMessageConverter。2.1 方案选型与权衡面对这个需求通常有几种思路Filter过滤器在Servlet层面最早接触到请求但处理的是原始的ServletRequest和ServletResponse流操作起来比较底层和繁琐特别是要读取和替换整个请求体/响应体时。AOP切面可以环绕Controller方法但更侧重于方法调用本身对于HTTP报文体的处理不如专门为HTTP设计的组件直接。拦截器Interceptor在DispatcherServlet之后、Controller之前执行可以获取到Spring MVC已经部分处理过的请求信息但对于请求体的读取一旦在拦截器里读取了后续Controller就可能读不到数据需要小心处理。消息转换器HttpMessageConverter这是Spring MVC用于将HTTP请求体转换成Java对象RequestBody以及将Java对象转换成HTTP响应体ResponseBody的核心组件。在这里动手脚是最符合“自动编解码”理念的。经过权衡我们选择以自定义消息转换器为主拦截器为辅的方案自定义消息转换器核心角色。我们编写一个DecryptHttpMessageConverter在读取请求时进行AES解密再交给Jackson等转换器反序列化为对象在写入响应时先将对象序列化再进行AES加密。这样所有标注了RequestBody和ResponseBody的接口都能自动生效。拦截器辅助角色。主要用于处理一些边缘情况比如在请求头Header中传递加密密钥或偏移量IV消息转换器需要能拿到这些信息。对某些特定路径如健康检查接口/actuator/health放行不进行加解密。统一处理加解密过程中的异常并返回格式统一的错误响应。这个方案的优点是集中、高效、透明。业务代码完全无感知加解密逻辑在一处维护并且能充分利用Spring MVC现有的消息处理机制。2.2 技术栈与依赖确认在NBSaaS-Boot项目中我们通常已经集成了Spring Boot Web Starter。我们需要确保以下依赖并额外引入AES加解密所需的库!-- Spring Boot Web (NBSaaS-Boot应已包含) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 用于Base64编解码 (Spring Core自带但显式声明或使用JDK8的java.util.Base64亦可) -- !-- JDK 1.8及以上已内置无需额外依赖 -- !-- 用于JSON序列化/反序列化 (Spring Boot默认使用Jackson通常已通过spring-boot-starter-web引入) -- !-- 确保Jackson Databind存在 -- dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency对于AES加解密Java标准库javax.crypto已经提供了强大的支持我们不需要引入第三方加密库如Bouncy Castle除非有特殊的算法模式需求。这保证了方案的轻量和标准性。3. 核心组件实现打造自动加解密的“心脏”接下来我们进入实战环节一步步构建核心组件。3.1 定义加解密配置与参数载体首先我们需要一个地方来统一管理加解密的参数比如AES密钥、偏移量IV、工作模式、填充方式等。通常我们会将这些配置放在application.yml中并通过一个配置类来加载。application.yml 配置nbsaas: crypto: aes: enabled: true # 是否启用全局加解密 key: 1234567890123456 # AES-128密钥必须是16/24/32字节对应128/192/256位 iv: 1234567890123456 # CBC模式需要的偏移量通常16字节 mode: CBC # 加密模式推荐CBC padding: PKCS5Padding # 填充方式 charset: UTF-8 # 字符集 # 可选配置不需要加解密的API路径 exclude-paths: - /actuator/** - /v3/api-docs/** - /swagger-resources/**对应的配置类AesCryptoPropertiesimport lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; Data Component ConfigurationProperties(prefix nbsaas.crypto.aes) public class AesCryptoProperties { /** * 是否启用AES加解密 */ private Boolean enabled false; /** * AES密钥长度需为16/24/32字节 */ private String key; /** * 偏移向量IVCBC模式必需长度通常为16字节 */ private String iv; /** * 加密模式如 CBC, ECB */ private String mode CBC; /** * 填充方案如 PKCS5Padding, NoPadding */ private String padding PKCS5Padding; /** * 字符编码 */ private String charset UTF-8; /** * 排除路径支持Ant风格 */ private String[] excludePaths; }同时我们创建一个线程安全的上下文对象CryptoContext用于在单次请求处理过程中传递加解密参数比如从拦截器传递给消息转换器。public class CryptoContext { private static final ThreadLocalBoolean DECRYPT_REQUIRED ThreadLocal.withInitial(() - false); private static final ThreadLocalBoolean ENCRYPT_REQUIRED ThreadLocal.withInitial(() - false); private static final ThreadLocalString CLIENT_KEY new ThreadLocal(); private static final ThreadLocalString CLIENT_IV new ThreadLocal(); public static void setDecryptRequired(boolean required) { DECRYPT_REQUIRED.set(required); } public static boolean isDecryptRequired() { return DECRYPT_REQUIRED.get() ! null DECRYPT_REQUIRED.get(); } public static void setEncryptRequired(boolean required) { ENCRYPT_REQUIRED.set(required); } public static boolean isEncryptRequired() { return ENCRYPT_REQUIRED.get() ! null ENCRYPT_REQUIRED.get(); } public static void setClientKey(String key) { CLIENT_KEY.set(key); } public static String getClientKey() { return CLIENT_KEY.get(); } public static void setClientIv(String iv) { CLIENT_IV.set(iv); } public static String getClientIv() { return CLIENT_IV.get(); } // 请求处理完成后必须清理防止内存泄漏 public static void clear() { DECRYPT_REQUIRED.remove(); ENCRYPT_REQUIRED.remove(); CLIENT_KEY.remove(); CLIENT_IV.remove(); } }3.2 实现AES加解密工具类这是整个功能的技术核心。我们将AES加解密的细节封装在一个工具类中确保线程安全Cipher非线程安全每次需新建和异常处理。import lombok.extern.slf4j.Slf4j; import org.springframework.util.Base64Utils; import javax.crypto.Cipher; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; Slf4j public class AesCryptoUtils { /** * AES加密 * param content 明文 * param key 密钥 * param iv 偏移量CBC模式必需 * param mode 模式如 AES/CBC/PKCS5Padding * return Base64编码的密文 */ public static String encrypt(String content, String key, String iv, String mode) { try { // 1. 根据密钥字符串生成SecretKeySpec SecretKeySpec keySpec new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), AES); // 2. 根据模式创建Cipher实例 Cipher cipher Cipher.getInstance(mode); // 3. 判断是否为CBC等需要IV的模式 if (mode.contains(CBC) || mode.contains(CFB) || mode.contains(OFB)) { IvParameterSpec ivSpec new IvParameterSpec(iv.getBytes(StandardCharsets.UTF_8)); cipher.init(Cipher.ENCRYPT_MODE, keySpec, ivSpec); } else { // ECB模式不需要IV cipher.init(Cipher.ENCRYPT_MODE, keySpec); } // 4. 执行加密 byte[] encryptedBytes cipher.doFinal(content.getBytes(StandardCharsets.UTF_8)); // 5. 返回Base64字符串便于网络传输 return Base64Utils.encodeToString(encryptedBytes); } catch (Exception e) { log.error(AES加密失败模式{} 密钥长度{}, mode, key.length(), e); throw new RuntimeException(数据加密失败, e); // 抛出自定义业务异常更佳 } } /** * AES解密 * param content Base64编码的密文 * param key 密钥 * param iv 偏移量 * param mode 模式 * return 明文 */ public static String decrypt(String content, String key, String iv, String mode) { try { SecretKeySpec keySpec new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), AES); Cipher cipher Cipher.getInstance(mode); if (mode.contains(CBC) || mode.contains(CFB) || mode.contains(OFB)) { IvParameterSpec ivSpec new IvParameterSpec(iv.getBytes(StandardCharsets.UTF_8)); cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec); } else { cipher.init(Cipher.DECRYPT_MODE, keySpec); } // 先将Base64字符串解码为字节数组 byte[] encryptedBytes Base64Utils.decodeFromString(content); byte[] decryptedBytes cipher.doFinal(encryptedBytes); return new String(decryptedBytes, StandardCharsets.UTF_8); } catch (Exception e) { log.error(AES解密失败模式{} 密文{}, mode, content, e); throw new RuntimeException(数据解密失败, e); } } /** * 构建完整的算法字符串例如 AES/CBC/PKCS5Padding */ public static String buildAlgorithm(String mode, String padding) { return AES/ mode / padding; } }关键点解析算法字符串Cipher.getInstance(“AES/CBC/PKCS5Padding”)是标准格式第一部分是算法第二部分是模式第三部分是填充。必须与前端或客户端保持一致。IV的重要性在CBC模式下一个固定且可预测的IV会带来安全风险。生产环境中可以考虑每次加密随机生成一个IV并将其与密文一起传输通常放在密文头部。这里为了简化使用了配置的固定IV。对于更高安全要求强烈建议使用随机IV。Base64编码加密后是二进制字节直接转字符串会乱码。Base64编码将其转换为ASCII字符便于在JSON等文本协议中传输。异常处理加解密可能因密钥错误、数据被篡改、模式不匹配等原因失败。我们将其捕获并转换为运行时异常后续由全局异常处理器统一处理返回给客户端明确的错误信息如“解密失败”而不是堆栈信息。3.3 实现核心自定义消息转换器这是实现自动化的关键。我们需要继承AbstractHttpMessageConverter并重写其读写方法。import com.fasterxml.jackson.databind.ObjectMapper; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.http.HttpInputMessage; import org.springframework.http.HttpOutputMessage; import org.springframework.http.MediaType; import org.springframework.http.converter.AbstractHttpMessageConverter; import org.springframework.http.converter.HttpMessageNotReadableException; import org.springframework.http.converter.HttpMessageNotWritableException; import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter; import org.springframework.util.StreamUtils; import java.io.IOException; import java.nio.charset.StandardCharsets; Slf4j RequiredArgsConstructor public class CryptoHttpMessageConverter extends AbstractHttpMessageConverterObject { private final ObjectMapper objectMapper; private final AesCryptoProperties aesProperties; private final MappingJackson2HttpMessageConverter jacksonConverter; // 声明本转换器只处理 application/json 媒体类型 public CryptoHttpMessageConverter(ObjectMapper objectMapper, AesCryptoProperties aesProperties) { super(MediaType.APPLICATION_JSON); this.objectMapper objectMapper; this.aesProperties aesProperties; this.jacksonConverter new MappingJackson2HttpMessageConverter(objectMapper); } // 判断本转换器是否能处理指定的类这里我们处理所有类型 Override protected boolean supports(Class? clazz) { return true; } // 读取HTTP请求体解密 - 反序列化为Java对象 Override protected Object readInternal(Class? clazz, HttpInputMessage inputMessage) throws IOException, HttpMessageNotReadableException { // 1. 检查当前请求是否需要解密 if (!CryptoContext.isDecryptRequired()) { // 不需要解密直接交给Jackson处理 return jacksonConverter.read(clazz, inputMessage); } // 2. 读取加密的请求体字符串 String encryptedBody StreamUtils.copyToString(inputMessage.getBody(), StandardCharsets.UTF_8); log.debug(接收到加密请求体{}, encryptedBody); // 3. 获取解密参数优先使用请求头中的动态参数其次使用配置文件中的静态参数 String key CryptoContext.getClientKey() ! null ? CryptoContext.getClientKey() : aesProperties.getKey(); String iv CryptoContext.getClientIv() ! null ? CryptoContext.getClientIv() : aesProperties.getIv(); String algorithm AesCryptoUtils.buildAlgorithm(aesProperties.getMode(), aesProperties.getPadding()); // 4. 执行AES解密 String decryptedBody; try { decryptedBody AesCryptoUtils.decrypt(encryptedBody, key, iv, algorithm); log.debug(解密后请求体{}, decryptedBody); } catch (Exception e) { throw new HttpMessageNotReadableException(请求体解密失败, e, inputMessage); } // 5. 将解密后的JSON字符串反序列化为目标对象 try { return objectMapper.readValue(decryptedBody, clazz); } catch (IOException e) { throw new HttpMessageNotReadableException(JSON反序列化失败, e, inputMessage); } } // 写入HTTP响应体序列化Java对象 - 加密 Override protected void writeInternal(Object object, HttpOutputMessage outputMessage) throws IOException, HttpMessageNotWritableException { // 1. 检查当前响应是否需要加密 if (!CryptoContext.isEncryptRequired()) { // 不需要加密直接交给Jackson处理 jacksonConverter.write(object, MediaType.APPLICATION_JSON, outputMessage); return; } // 2. 将Java对象序列化为JSON字符串 String originalJson objectMapper.writeValueAsString(object); log.debug(原始响应JSON{}, originalJson); // 3. 获取加密参数 String key CryptoContext.getClientKey() ! null ? CryptoContext.getClientKey() : aesProperties.getKey(); String iv CryptoContext.getClientIv() ! null ? CryptoContext.getClientIv() : aesProperties.getIv(); String algorithm AesCryptoUtils.buildAlgorithm(aesProperties.getMode(), aesProperties.getPadding()); // 4. 执行AES加密 String encryptedBody; try { encryptedBody AesCryptoUtils.encrypt(originalJson, key, iv, algorithm); log.debug(加密后响应体{}, encryptedBody); } catch (Exception e) { throw new HttpMessageNotWritableException(响应体加密失败, e); } // 5. 将加密后的字符串写入响应流 outputMessage.getBody().write(encryptedBody.getBytes(StandardCharsets.UTF_8)); } }实操心得性能考虑加解密是CPU密集型操作。如果接口QPS很高需要关注性能。我们的工具类每次创建新的Cipher实例对于超高并发场景可以考虑使用ThreadLocal缓存Cipher实例但要注意线程安全和正确初始化。日志级别加解密前后的数据体日志务必使用DEBUG级别避免在生产环境日志中输出敏感数据。灵活控制通过CryptoContext我们可以实现基于请求的精细控制。例如管理后台的接口可能不需要加密而客户端接口需要。这可以通过拦截器根据请求路径或头信息来动态设置CryptoContext中的标志位。3.4 配置拦截器与注册转换器最后我们需要将上述组件装配到Spring MVC中。1. 实现拦截器CryptoInterceptor这个拦截器负责判断当前请求是否需要加解密并设置CryptoContext。import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.util.AntPathMatcher; import org.springframework.util.PathMatcher; import org.springframework.web.servlet.HandlerInterceptor; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; Slf4j RequiredArgsConstructor public class CryptoInterceptor implements HandlerInterceptor { private final AesCryptoProperties aesProperties; private final PathMatcher pathMatcher new AntPathMatcher(); Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 每次请求开始前先清空上下文避免污染 CryptoContext.clear(); String requestUri request.getRequestURI(); // 1. 检查全局开关和排除路径 if (!aesProperties.getEnabled()) { log.debug(全局AES加解密未启用路径{}, requestUri); return true; } if (isExcludedPath(requestUri)) { log.debug(路径在排除列表中跳过加解密路径{}, requestUri); return true; } // 2. 判断是否需要解密通常通过请求头标识例如 X-Encrypt-Request: true String encryptHeader request.getHeader(X-Encrypt-Request); boolean needDecrypt true.equalsIgnoreCase(encryptHeader); CryptoContext.setDecryptRequired(needDecrypt); // 3. 判断是否需要加密响应通常通过请求头标识例如 X-Encrypt-Response: true String decryptHeader request.getHeader(X-Encrypt-Response); boolean needEncrypt true.equalsIgnoreCase(decryptHeader); // 通常请求和响应是配套的这里简化逻辑如果需要解密请求则默认加密响应 CryptoContext.setEncryptRequired(needEncrypt || needDecrypt); // 4. 可选从请求头获取动态的密钥和IV实现密钥协商或轮转 String clientKey request.getHeader(X-Client-Key); String clientIv request.getHeader(X-Client-IV); if (clientKey ! null !clientKey.isEmpty()) { CryptoContext.setClientKey(clientKey); } if (clientIv ! null !clientIv.isEmpty()) { CryptoContext.setClientIv(clientIv); } log.debug(请求路径{} 需解密{} 需加密{}, requestUri, needDecrypt, needEncrypt); return true; } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception { // 请求完成后务必清理ThreadLocal防止内存泄漏 CryptoContext.clear(); } private boolean isExcludedPath(String requestUri) { if (aesProperties.getExcludePaths() null) { return false; } for (String pattern : aesProperties.getExcludePaths()) { if (pathMatcher.match(pattern, requestUri)) { return true; } } return false; } }2. 创建配置类WebMvcCryptoConfig这个配置类负责将拦截器和消息转换器注册到Spring MVC。import com.fasterxml.jackson.databind.ObjectMapper; import lombok.RequiredArgsConstructor; import org.springframework.context.annotation.Configuration; import org.springframework.http.converter.HttpMessageConverter; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import java.util.List; Configuration RequiredArgsConstructor public class WebMvcCryptoConfig implements WebMvcConfigurer { private final AesCryptoProperties aesProperties; private final ObjectMapper objectMapper; Override public void addInterceptors(InterceptorRegistry registry) { // 注册拦截器拦截所有路径 registry.addInterceptor(new CryptoInterceptor(aesProperties)) .addPathPatterns(/**); } Override public void configureMessageConverters(ListHttpMessageConverter? converters) { // 创建自定义的消息转换器 CryptoHttpMessageConverter cryptoConverter new CryptoHttpMessageConverter(objectMapper, aesProperties); // 将其添加到转换器列表的最前面使其拥有最高优先级 converters.add(0, cryptoConverter); } }注意事项转换器顺序converters.add(0, cryptoConverter)将我们的转换器放在列表首位这样Spring MVC在处理application/json类型时会优先使用我们的转换器。如果我们的转换器判断不需要处理通过CryptoContext它会委托给默认的Jackson转换器。拦截器路径addPathPatterns(“/**”)拦截所有请求。具体的排除逻辑已经在拦截器内部的isExcludedPath方法中实现了。ObjectMapper这里注入了Spring Boot默认配置的ObjectMapper确保JSON序列化/反序列化行为如日期格式、空值处理与项目其他部分保持一致。4. 完整流程测试与问题排查组件都实现后我们通过一个完整的测试流程来验证功能并梳理可能遇到的问题。4.1 测试用例设计与验证假设我们有一个简单的用户查询接口。1. 定义ControllerRestController RequestMapping(/api/user) public class UserController { PostMapping(/info) public ApiResponseUserInfo getUserInfo(RequestBody UserQuery query) { // 业务逻辑根据query查询用户... UserInfo user userService.getUserById(query.getUserId()); return ApiResponse.success(user); } } // 请求体对象 Data public class UserQuery { private String userId; } // 响应体对象 Data public class UserInfo { private String name; private String phone; // 敏感信息需要加密 private String email; } // 统一响应封装 Data public class ApiResponseT { private Integer code; private String msg; private T data; }2. 模拟加密请求我们使用一个在线AES加密工具如开篇提到的SSLeye工具或写一段Java代码来模拟客户端加密过程。明文请求JSON{userId: 1001}使用密钥1234567890123456(16字节)使用IV1234567890123456(16字节)模式/填充AES/CBC/PKCS5Padding加密后Base64输出 假设得到“U2FsdGVkX1qlR8Z6Y...一串密文”3. 发送请求使用Postman或curl发送请求关键是要带上约定的请求头。POST /api/user/info HTTP/1.1 Host: localhost:8080 Content-Type: application/json X-Encrypt-Request: true # 如果使用动态密钥还需加上 # X-Client-Key: dynamic_key_here # X-Client-IV: dynamic_iv_here U2FsdGVkX1qlR8Z6Y...加密后的请求体4. 验证结果服务端日志应能看到拦截器打印的调试日志以及消息转换器中解密后的明文{userId: 1001}。ControllergetUserInfo方法接收到的UserQuery对象应该是正常的userId为1001。响应服务端返回的响应体也应该是一串Base64密文。客户端拿到后需要用相同的密钥和IV进行解密才能得到{code:0, msg:success, data:{name:张三,phone:138****1234,email:zhangsanexample.com}}这样的明文。4.2 常见问题与排查技巧实录在实际集成中你几乎一定会遇到下面这些问题。这里我把踩过的坑和解决方法记录下来。问题1请求体无法反序列化报错“JSON parse error”或“Required request body is missing”。排查首先检查日志看自定义的CryptoHttpMessageConverter的readInternal方法是否被调用。如果没有说明转换器未生效或优先级不够。解决确认WebMvcCryptoConfig配置类已被Spring扫描到有Configuration注解且在组件扫描路径下。确认configureMessageConverters方法中自定义转换器被添加到了列表前面converters.add(0, ...)。在readInternal方法开始处打日志确认流程是否进入。检查CryptoContext.isDecryptRequired()的值是否为true。如果为false请求会被交给默认的Jackson转换器而Jackson无法解析加密后的字符串它不是合法JSON所以会报错。这通常是因为拦截器没有正确设置DECRYPT_REQUIRED标志或者请求头X-Encrypt-Request未设置或值不为true。问题2加解密失败抛出“InvalidKeyException”或“BadPaddingException”。排查这是最经典的加解密问题根本原因是前后端参数不一致。解决请严格按照以下清单进行核对可以使用在线工具如SSLeye进行交叉验证参数项可能值核对要点密钥 (Key)16/24/32字节字符串长度必须严格对应AES-128/192/256。前后端字符串必须完全一致包括字符编码通常UTF-8。偏移量 (IV)通常16字节字符串仅CBC/CFB/OFB模式需要。ECB模式不需要IV。前后端必须一致。加密模式CBC, ECB, CFB等前后端Cipher.getInstance()中的模式字符串必须完全一致例如都是AES/CBC/PKCS5Padding。填充方式PKCS5Padding, NoPadding等同上必须一致。Java的PKCS5Padding实际上对应PKCS7Padding。数据编码Base64, Hex加密后是二进制传输前如何编码解密前如何解码必须一致。我们方案用的是Base64。字符集UTF-8, GBK等在将字符串如密钥、IV、明文转换成字节数组(.getBytes())时使用的字符集必须一致。我们工具类固定使用了StandardCharsets.UTF_8。问题3启用加密后Swagger/Actuator等内部接口访问异常。排查这些接口的请求和响应不是加密格式但被我们的拦截器/转换器处理了。解决这就是我们在配置中设计exclude-paths和拦截器中isExcludedPath方法的目的。确保application.yml中正确配置了排除路径例如/actuator/**,/v3/api-docs/**,/swagger-ui/**等。使用Ant风格路径匹配。问题4性能瓶颈在高并发下接口响应变慢。排查使用APM工具如SkyWalking, Arthas定位耗时环节很可能是加解密操作。优化缓存Cipher实例Cipher的初始化(init)相对耗时。可以使用ThreadLocalCipher为每个线程缓存加密和解密用的Cipher实例。但要注意Cipher不是线程安全的必须每个线程独享且每次使用前需要重新init因为每次的密钥/IV/模式可能不同在我们的动态密钥场景下尤其如此。如果密钥固定缓存才有较大收益。异步或批处理对于非实时性要求极高的场景可以考虑将加解密操作放到异步线程或队列中处理但这会改变响应模型。硬件加速确保JVM运行在支持AES-NI指令集的CPU上现代JDK会利用此指令集大幅提升AES运算速度。按需加密并非所有数据都需要加密。可以通过注解如EncryptField标记实体类中的敏感字段只在序列化时加密这些字段减少加密数据量。问题5如何实现更安全的动态密钥管理固定密钥写在配置文件里始终有泄露风险。更安全的做法是每次会话使用不同的密钥。方案一推荐RSA非对称加密交换AES密钥服务端持有RSA私钥将公钥下发给客户端。客户端每次请求前随机生成一个AES会话密钥Session Key和IV。客户端用RSA公钥加密这个AES会话密钥放在请求头如X-Session-Key中传给服务端。服务端用RSA私钥解密得到AES会话密钥存入CryptoContext用于本次请求/响应的加解密。该会话密钥可以有一定有效期用于多次请求过期后重新生成。方案二基于密钥派生函数KDF使用一个根密钥Master Key和每次请求的随机数Nonce通过HMAC或HKDF等算法派生出本次请求使用的AES密钥。服务端和客户端遵循相同算法即可同步无需传输密钥本身。5. 进阶优化与生产环境考量基础功能跑通后我们可以从健壮性、可观测性和安全性方面进行优化。5.1 统一异常处理与响应封装加解密过程可能失败我们需要给客户端返回友好的错误信息而不是500内部错误栈。RestControllerAdvice public class GlobalExceptionHandler { ExceptionHandler({HttpMessageNotReadableException.class}) public ApiResponse? handleDecryptException(HttpMessageNotReadableException e) { // 判断异常根源是否是解密失败 Throwable cause e.getCause(); if (cause ! null cause.getMessage() ! null cause.getMessage().contains(解密)) { return ApiResponse.fail(4001, 请求数据解密失败请检查加密参数或格式); } return ApiResponse.fail(4000, 请求数据格式错误); } ExceptionHandler({HttpMessageNotWritableException.class}) public ApiResponse? handleEncryptException(HttpMessageNotWritableException e) { if (e.getCause() ! null e.getCause().getMessage() ! null e.getCause().getMessage().contains(加密)) { return ApiResponse.fail(5001, 响应数据加密失败); } return ApiResponse.fail(5000, 服务器内部错误); } ExceptionHandler({RuntimeException.class}) public ApiResponse? handleRuntimeException(RuntimeException e) { // 处理AesCryptoUtils中抛出的运行时异常 if (e.getMessage() ! null (e.getMessage().contains(加密) || e.getMessage().contains(解密))) { return ApiResponse.fail(4002, 数据加解密处理异常); } return ApiResponse.fail(5000, 服务器内部错误); } }5.2 监控、日志与审计监控指标使用Micrometer等工具对加解密操作的耗时、成功率进行监控设置告警阈值。结构化日志在拦截器和消息转换器中记录关键信息如请求ID、是否加解密、耗时、密钥标识不记录完整密钥等便于链路追踪和问题排查。审计日志对于特别敏感的操作可以考虑记录“谁在什么时间请求了哪个加密接口”但注意不要记录加密后的具体数据内容。5.3 密钥安全管理绝对不要将生产环境的密钥硬编码在代码或配置文件中提交到Git。使用配置中心将密钥存储在Apollo、Nacos等配置中心并开启加密存储功能。使用KMS服务如果云上部署使用阿里云KMS、AWS KMS等密钥管理服务在应用启动时动态获取密钥。硬件安全模块HSM金融级安全要求使用HSM进行密钥存储和加解密运算。5.4 与现有NBSaaS-Boot生态的融合NBSaaS-Boot通常有自己的统一响应体、异常处理、权限校验等组件。我们的加解密方案应该与其无缝融合。响应体包装器确保我们的CryptoHttpMessageConverter在加密前处理的是已经被NBSaaS-Boot的ResponseBodyAdvice包装好的统一响应对象如ApiResponse。权限校验顺序在拦截器链中加解密拦截器应该在权限校验拦截器之前。因为权限校验可能需要读取请求体中的参数如userId如果请求体还未解密校验将失败。我们的方案由于在消息转换器中解密顺序是合理的。注解式开关可以进一步优化提供类似EncryptApi的注解标注在Controller类或方法上更精细地控制哪些接口需要加解密而不是完全依赖请求头。整个实现过程本质上是在Spring MVC的请求处理管道中巧妙地插入了一个“解码-编码”层。它没有改变业务开发者的编程模型却为数据传输增加了一层坚实的安全保障。这种“非侵入式”的架构思想在构建可维护、可扩展的中间件时非常值得借鉴。当你下次需要为API增加签名校验、流量染色、数据脱敏等全局功能时不妨也想想是否能在过滤器、拦截器或消息转换器这个层面优雅地解决。
Spring Boot中基于拦截器与消息转换器的AES自动加解密方案
发布时间：2026/7/6 9:05:28
1. 项目概述为什么我们需要在NBSaaS-Boot中集成AES加解密如果你正在用NBSaaS-Boot这类快速开发框架搭建一个对外提供API的服务尤其是涉及用户敏感信息或金融交易数据的场景那么数据在传输过程中的安全性就是你绕不开的一道坎。直接明文传输用户名、密码、身份证号、手机号这无异于在互联网上“裸奔”。虽然HTTPSSSL/TLS已经为传输链路提供了加密保障但在某些安全等级要求更高的场景下我们还需要对传输的业务数据本身进行二次加密这就是所谓的“端到端加密”或“应用层加密”。AES高级加密标准作为目前全球公认最安全、最主流的对称加密算法自然成了实现这一需求的首选。它的速度快、安全性高且被各种语言和平台广泛支持。但问题来了难道我们要在每个Controller接口里都手动写一遍加密解密的逻辑吗这显然违背了NBSaaS-Boot这类框架“快速开发”的初衷代码会变得臃肿且难以维护。所以我们今天要聊的就是如何利用NBSaaS-Boot一个基于Spring Boot的快速开发脚手架的特性以最优雅、侵入性最低的方式实现请求Body的自动AES解密和响应Body的自动AES加密。目标很简单让业务开发者像写普通接口一样开发加解密过程对开发者透明由框架在“背后”自动完成。这不仅能大幅提升开发效率更能统一安全规范避免因开发者水平不一导致的安全漏洞。2. 核心方案设计拦截器与消息转换器的双剑合璧要实现请求和响应的自动处理我们不能去改每一个业务方法而是要在HTTP请求到达Controller之前以及Controller返回结果之后这两个关键节点进行拦截和转换。在Spring Boot也就是NBSaaS-Boot的底层的世界里我们有两大神器拦截器Interceptor和消息转换器HttpMessageConverter。2.1 方案选型与权衡面对这个需求通常有几种思路Filter过滤器在Servlet层面最早接触到请求但处理的是原始的ServletRequest和ServletResponse流操作起来比较底层和繁琐特别是要读取和替换整个请求体/响应体时。AOP切面可以环绕Controller方法但更侧重于方法调用本身对于HTTP报文体的处理不如专门为HTTP设计的组件直接。拦截器Interceptor在DispatcherServlet之后、Controller之前执行可以获取到Spring MVC已经部分处理过的请求信息但对于请求体的读取一旦在拦截器里读取了后续Controller就可能读不到数据需要小心处理。消息转换器HttpMessageConverter这是Spring MVC用于将HTTP请求体转换成Java对象RequestBody以及将Java对象转换成HTTP响应体ResponseBody的核心组件。在这里动手脚是最符合“自动编解码”理念的。经过权衡我们选择以自定义消息转换器为主拦截器为辅的方案自定义消息转换器核心角色。我们编写一个DecryptHttpMessageConverter在读取请求时进行AES解密再交给Jackson等转换器反序列化为对象在写入响应时先将对象序列化再进行AES加密。这样所有标注了RequestBody和ResponseBody的接口都能自动生效。拦截器辅助角色。主要用于处理一些边缘情况比如在请求头Header中传递加密密钥或偏移量IV消息转换器需要能拿到这些信息。对某些特定路径如健康检查接口/actuator/health放行不进行加解密。统一处理加解密过程中的异常并返回格式统一的错误响应。这个方案的优点是集中、高效、透明。业务代码完全无感知加解密逻辑在一处维护并且能充分利用Spring MVC现有的消息处理机制。2.2 技术栈与依赖确认在NBSaaS-Boot项目中我们通常已经集成了Spring Boot Web Starter。我们需要确保以下依赖并额外引入AES加解密所需的库!-- Spring Boot Web (NBSaaS-Boot应已包含) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 用于Base64编解码 (Spring Core自带但显式声明或使用JDK8的java.util.Base64亦可) -- !-- JDK 1.8及以上已内置无需额外依赖 -- !-- 用于JSON序列化/反序列化 (Spring Boot默认使用Jackson通常已通过spring-boot-starter-web引入) -- !-- 确保Jackson Databind存在 -- dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency对于AES加解密Java标准库javax.crypto已经提供了强大的支持我们不需要引入第三方加密库如Bouncy Castle除非有特殊的算法模式需求。这保证了方案的轻量和标准性。3. 核心组件实现打造自动加解密的“心脏”接下来我们进入实战环节一步步构建核心组件。3.1 定义加解密配置与参数载体首先我们需要一个地方来统一管理加解密的参数比如AES密钥、偏移量IV、工作模式、填充方式等。通常我们会将这些配置放在application.yml中并通过一个配置类来加载。application.yml 配置nbsaas: crypto: aes: enabled: true # 是否启用全局加解密 key: 1234567890123456 # AES-128密钥必须是16/24/32字节对应128/192/256位 iv: 1234567890123456 # CBC模式需要的偏移量通常16字节 mode: CBC # 加密模式推荐CBC padding: PKCS5Padding # 填充方式 charset: UTF-8 # 字符集 # 可选配置不需要加解密的API路径 exclude-paths: - /actuator/** - /v3/api-docs/** - /swagger-resources/**对应的配置类AesCryptoPropertiesimport lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; Data Component ConfigurationProperties(prefix nbsaas.crypto.aes) public class AesCryptoProperties { /** * 是否启用AES加解密 */ private Boolean enabled false; /** * AES密钥长度需为16/24/32字节 */ private String key; /** * 偏移向量IVCBC模式必需长度通常为16字节 */ private String iv; /** * 加密模式如 CBC, ECB */ private String mode CBC; /** * 填充方案如 PKCS5Padding, NoPadding */ private String padding PKCS5Padding; /** * 字符编码 */ private String charset UTF-8; /** * 排除路径支持Ant风格 */ private String[] excludePaths; }同时我们创建一个线程安全的上下文对象CryptoContext用于在单次请求处理过程中传递加解密参数比如从拦截器传递给消息转换器。public class CryptoContext { private static final ThreadLocalBoolean DECRYPT_REQUIRED ThreadLocal.withInitial(() - false); private static final ThreadLocalBoolean ENCRYPT_REQUIRED ThreadLocal.withInitial(() - false); private static final ThreadLocalString CLIENT_KEY new ThreadLocal(); private static final ThreadLocalString CLIENT_IV new ThreadLocal(); public static void setDecryptRequired(boolean required) { DECRYPT_REQUIRED.set(required); } public static boolean isDecryptRequired() { return DECRYPT_REQUIRED.get() ! null DECRYPT_REQUIRED.get(); } public static void setEncryptRequired(boolean required) { ENCRYPT_REQUIRED.set(required); } public static boolean isEncryptRequired() { return ENCRYPT_REQUIRED.get() ! null ENCRYPT_REQUIRED.get(); } public static void setClientKey(String key) { CLIENT_KEY.set(key); } public static String getClientKey() { return CLIENT_KEY.get(); } public static void setClientIv(String iv) { CLIENT_IV.set(iv); } public static String getClientIv() { return CLIENT_IV.get(); } // 请求处理完成后必须清理防止内存泄漏 public static void clear() { DECRYPT_REQUIRED.remove(); ENCRYPT_REQUIRED.remove(); CLIENT_KEY.remove(); CLIENT_IV.remove(); } }3.2 实现AES加解密工具类这是整个功能的技术核心。我们将AES加解密的细节封装在一个工具类中确保线程安全Cipher非线程安全每次需新建和异常处理。import lombok.extern.slf4j.Slf4j; import org.springframework.util.Base64Utils; import javax.crypto.Cipher; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; Slf4j public class AesCryptoUtils { /** * AES加密 * param content 明文 * param key 密钥 * param iv 偏移量CBC模式必需 * param mode 模式如 AES/CBC/PKCS5Padding * return Base64编码的密文 */ public static String encrypt(String content, String key, String iv, String mode) { try { // 1. 根据密钥字符串生成SecretKeySpec SecretKeySpec keySpec new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), AES); // 2. 根据模式创建Cipher实例 Cipher cipher Cipher.getInstance(mode); // 3. 判断是否为CBC等需要IV的模式 if (mode.contains(CBC) || mode.contains(CFB) || mode.contains(OFB)) { IvParameterSpec ivSpec new IvParameterSpec(iv.getBytes(StandardCharsets.UTF_8)); cipher.init(Cipher.ENCRYPT_MODE, keySpec, ivSpec); } else { // ECB模式不需要IV cipher.init(Cipher.ENCRYPT_MODE, keySpec); } // 4. 执行加密 byte[] encryptedBytes cipher.doFinal(content.getBytes(StandardCharsets.UTF_8)); // 5. 返回Base64字符串便于网络传输 return Base64Utils.encodeToString(encryptedBytes); } catch (Exception e) { log.error(AES加密失败模式{} 密钥长度{}, mode, key.length(), e); throw new RuntimeException(数据加密失败, e); // 抛出自定义业务异常更佳 } } /** * AES解密 * param content Base64编码的密文 * param key 密钥 * param iv 偏移量 * param mode 模式 * return 明文 */ public static String decrypt(String content, String key, String iv, String mode) { try { SecretKeySpec keySpec new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), AES); Cipher cipher Cipher.getInstance(mode); if (mode.contains(CBC) || mode.contains(CFB) || mode.contains(OFB)) { IvParameterSpec ivSpec new IvParameterSpec(iv.getBytes(StandardCharsets.UTF_8)); cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec); } else { cipher.init(Cipher.DECRYPT_MODE, keySpec); } // 先将Base64字符串解码为字节数组 byte[] encryptedBytes Base64Utils.decodeFromString(content); byte[] decryptedBytes cipher.doFinal(encryptedBytes); return new String(decryptedBytes, StandardCharsets.UTF_8); } catch (Exception e) { log.error(AES解密失败模式{} 密文{}, mode, content, e); throw new RuntimeException(数据解密失败, e); } } /** * 构建完整的算法字符串例如 AES/CBC/PKCS5Padding */ public static String buildAlgorithm(String mode, String padding) { return AES/ mode / padding; } }关键点解析算法字符串Cipher.getInstance(“AES/CBC/PKCS5Padding”)是标准格式第一部分是算法第二部分是模式第三部分是填充。必须与前端或客户端保持一致。IV的重要性在CBC模式下一个固定且可预测的IV会带来安全风险。生产环境中可以考虑每次加密随机生成一个IV并将其与密文一起传输通常放在密文头部。这里为了简化使用了配置的固定IV。对于更高安全要求强烈建议使用随机IV。Base64编码加密后是二进制字节直接转字符串会乱码。Base64编码将其转换为ASCII字符便于在JSON等文本协议中传输。异常处理加解密可能因密钥错误、数据被篡改、模式不匹配等原因失败。我们将其捕获并转换为运行时异常后续由全局异常处理器统一处理返回给客户端明确的错误信息如“解密失败”而不是堆栈信息。3.3 实现核心自定义消息转换器这是实现自动化的关键。我们需要继承AbstractHttpMessageConverter并重写其读写方法。import com.fasterxml.jackson.databind.ObjectMapper; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.http.HttpInputMessage; import org.springframework.http.HttpOutputMessage; import org.springframework.http.MediaType; import org.springframework.http.converter.AbstractHttpMessageConverter; import org.springframework.http.converter.HttpMessageNotReadableException; import org.springframework.http.converter.HttpMessageNotWritableException; import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter; import org.springframework.util.StreamUtils; import java.io.IOException; import java.nio.charset.StandardCharsets; Slf4j RequiredArgsConstructor public class CryptoHttpMessageConverter extends AbstractHttpMessageConverterObject { private final ObjectMapper objectMapper; private final AesCryptoProperties aesProperties; private final MappingJackson2HttpMessageConverter jacksonConverter; // 声明本转换器只处理 application/json 媒体类型 public CryptoHttpMessageConverter(ObjectMapper objectMapper, AesCryptoProperties aesProperties) { super(MediaType.APPLICATION_JSON); this.objectMapper objectMapper; this.aesProperties aesProperties; this.jacksonConverter new MappingJackson2HttpMessageConverter(objectMapper); } // 判断本转换器是否能处理指定的类这里我们处理所有类型 Override protected boolean supports(Class? clazz) { return true; } // 读取HTTP请求体解密 - 反序列化为Java对象 Override protected Object readInternal(Class? clazz, HttpInputMessage inputMessage) throws IOException, HttpMessageNotReadableException { // 1. 检查当前请求是否需要解密 if (!CryptoContext.isDecryptRequired()) { // 不需要解密直接交给Jackson处理 return jacksonConverter.read(clazz, inputMessage); } // 2. 读取加密的请求体字符串 String encryptedBody StreamUtils.copyToString(inputMessage.getBody(), StandardCharsets.UTF_8); log.debug(接收到加密请求体{}, encryptedBody); // 3. 获取解密参数优先使用请求头中的动态参数其次使用配置文件中的静态参数 String key CryptoContext.getClientKey() ! null ? CryptoContext.getClientKey() : aesProperties.getKey(); String iv CryptoContext.getClientIv() ! null ? CryptoContext.getClientIv() : aesProperties.getIv(); String algorithm AesCryptoUtils.buildAlgorithm(aesProperties.getMode(), aesProperties.getPadding()); // 4. 执行AES解密 String decryptedBody; try { decryptedBody AesCryptoUtils.decrypt(encryptedBody, key, iv, algorithm); log.debug(解密后请求体{}, decryptedBody); } catch (Exception e) { throw new HttpMessageNotReadableException(请求体解密失败, e, inputMessage); } // 5. 将解密后的JSON字符串反序列化为目标对象 try { return objectMapper.readValue(decryptedBody, clazz); } catch (IOException e) { throw new HttpMessageNotReadableException(JSON反序列化失败, e, inputMessage); } } // 写入HTTP响应体序列化Java对象 - 加密 Override protected void writeInternal(Object object, HttpOutputMessage outputMessage) throws IOException, HttpMessageNotWritableException { // 1. 检查当前响应是否需要加密 if (!CryptoContext.isEncryptRequired()) { // 不需要加密直接交给Jackson处理 jacksonConverter.write(object, MediaType.APPLICATION_JSON, outputMessage); return; } // 2. 将Java对象序列化为JSON字符串 String originalJson objectMapper.writeValueAsString(object); log.debug(原始响应JSON{}, originalJson); // 3. 获取加密参数 String key CryptoContext.getClientKey() ! null ? CryptoContext.getClientKey() : aesProperties.getKey(); String iv CryptoContext.getClientIv() ! null ? CryptoContext.getClientIv() : aesProperties.getIv(); String algorithm AesCryptoUtils.buildAlgorithm(aesProperties.getMode(), aesProperties.getPadding()); // 4. 执行AES加密 String encryptedBody; try { encryptedBody AesCryptoUtils.encrypt(originalJson, key, iv, algorithm); log.debug(加密后响应体{}, encryptedBody); } catch (Exception e) { throw new HttpMessageNotWritableException(响应体加密失败, e); } // 5. 将加密后的字符串写入响应流 outputMessage.getBody().write(encryptedBody.getBytes(StandardCharsets.UTF_8)); } }实操心得性能考虑加解密是CPU密集型操作。如果接口QPS很高需要关注性能。我们的工具类每次创建新的Cipher实例对于超高并发场景可以考虑使用ThreadLocal缓存Cipher实例但要注意线程安全和正确初始化。日志级别加解密前后的数据体日志务必使用DEBUG级别避免在生产环境日志中输出敏感数据。灵活控制通过CryptoContext我们可以实现基于请求的精细控制。例如管理后台的接口可能不需要加密而客户端接口需要。这可以通过拦截器根据请求路径或头信息来动态设置CryptoContext中的标志位。3.4 配置拦截器与注册转换器最后我们需要将上述组件装配到Spring MVC中。1. 实现拦截器CryptoInterceptor这个拦截器负责判断当前请求是否需要加解密并设置CryptoContext。import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.util.AntPathMatcher; import org.springframework.util.PathMatcher; import org.springframework.web.servlet.HandlerInterceptor; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; Slf4j RequiredArgsConstructor public class CryptoInterceptor implements HandlerInterceptor { private final AesCryptoProperties aesProperties; private final PathMatcher pathMatcher new AntPathMatcher(); Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 每次请求开始前先清空上下文避免污染 CryptoContext.clear(); String requestUri request.getRequestURI(); // 1. 检查全局开关和排除路径 if (!aesProperties.getEnabled()) { log.debug(全局AES加解密未启用路径{}, requestUri); return true; } if (isExcludedPath(requestUri)) { log.debug(路径在排除列表中跳过加解密路径{}, requestUri); return true; } // 2. 判断是否需要解密通常通过请求头标识例如 X-Encrypt-Request: true String encryptHeader request.getHeader(X-Encrypt-Request); boolean needDecrypt true.equalsIgnoreCase(encryptHeader); CryptoContext.setDecryptRequired(needDecrypt); // 3. 判断是否需要加密响应通常通过请求头标识例如 X-Encrypt-Response: true String decryptHeader request.getHeader(X-Encrypt-Response); boolean needEncrypt true.equalsIgnoreCase(decryptHeader); // 通常请求和响应是配套的这里简化逻辑如果需要解密请求则默认加密响应 CryptoContext.setEncryptRequired(needEncrypt || needDecrypt); // 4. 可选从请求头获取动态的密钥和IV实现密钥协商或轮转 String clientKey request.getHeader(X-Client-Key); String clientIv request.getHeader(X-Client-IV); if (clientKey ! null !clientKey.isEmpty()) { CryptoContext.setClientKey(clientKey); } if (clientIv ! null !clientIv.isEmpty()) { CryptoContext.setClientIv(clientIv); } log.debug(请求路径{} 需解密{} 需加密{}, requestUri, needDecrypt, needEncrypt); return true; } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception { // 请求完成后务必清理ThreadLocal防止内存泄漏 CryptoContext.clear(); } private boolean isExcludedPath(String requestUri) { if (aesProperties.getExcludePaths() null) { return false; } for (String pattern : aesProperties.getExcludePaths()) { if (pathMatcher.match(pattern, requestUri)) { return true; } } return false; } }2. 创建配置类WebMvcCryptoConfig这个配置类负责将拦截器和消息转换器注册到Spring MVC。import com.fasterxml.jackson.databind.ObjectMapper; import lombok.RequiredArgsConstructor; import org.springframework.context.annotation.Configuration; import org.springframework.http.converter.HttpMessageConverter; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import java.util.List; Configuration RequiredArgsConstructor public class WebMvcCryptoConfig implements WebMvcConfigurer { private final AesCryptoProperties aesProperties; private final ObjectMapper objectMapper; Override public void addInterceptors(InterceptorRegistry registry) { // 注册拦截器拦截所有路径 registry.addInterceptor(new CryptoInterceptor(aesProperties)) .addPathPatterns(/**); } Override public void configureMessageConverters(ListHttpMessageConverter? converters) { // 创建自定义的消息转换器 CryptoHttpMessageConverter cryptoConverter new CryptoHttpMessageConverter(objectMapper, aesProperties); // 将其添加到转换器列表的最前面使其拥有最高优先级 converters.add(0, cryptoConverter); } }注意事项转换器顺序converters.add(0, cryptoConverter)将我们的转换器放在列表首位这样Spring MVC在处理application/json类型时会优先使用我们的转换器。如果我们的转换器判断不需要处理通过CryptoContext它会委托给默认的Jackson转换器。拦截器路径addPathPatterns(“/**”)拦截所有请求。具体的排除逻辑已经在拦截器内部的isExcludedPath方法中实现了。ObjectMapper这里注入了Spring Boot默认配置的ObjectMapper确保JSON序列化/反序列化行为如日期格式、空值处理与项目其他部分保持一致。4. 完整流程测试与问题排查组件都实现后我们通过一个完整的测试流程来验证功能并梳理可能遇到的问题。4.1 测试用例设计与验证假设我们有一个简单的用户查询接口。1. 定义ControllerRestController RequestMapping(/api/user) public class UserController { PostMapping(/info) public ApiResponseUserInfo getUserInfo(RequestBody UserQuery query) { // 业务逻辑根据query查询用户... UserInfo user userService.getUserById(query.getUserId()); return ApiResponse.success(user); } } // 请求体对象 Data public class UserQuery { private String userId; } // 响应体对象 Data public class UserInfo { private String name; private String phone; // 敏感信息需要加密 private String email; } // 统一响应封装 Data public class ApiResponseT { private Integer code; private String msg; private T data; }2. 模拟加密请求我们使用一个在线AES加密工具如开篇提到的SSLeye工具或写一段Java代码来模拟客户端加密过程。明文请求JSON{userId: 1001}使用密钥1234567890123456(16字节)使用IV1234567890123456(16字节)模式/填充AES/CBC/PKCS5Padding加密后Base64输出 假设得到“U2FsdGVkX1qlR8Z6Y...一串密文”3. 发送请求使用Postman或curl发送请求关键是要带上约定的请求头。POST /api/user/info HTTP/1.1 Host: localhost:8080 Content-Type: application/json X-Encrypt-Request: true # 如果使用动态密钥还需加上 # X-Client-Key: dynamic_key_here # X-Client-IV: dynamic_iv_here U2FsdGVkX1qlR8Z6Y...加密后的请求体4. 验证结果服务端日志应能看到拦截器打印的调试日志以及消息转换器中解密后的明文{userId: 1001}。ControllergetUserInfo方法接收到的UserQuery对象应该是正常的userId为1001。响应服务端返回的响应体也应该是一串Base64密文。客户端拿到后需要用相同的密钥和IV进行解密才能得到{code:0, msg:success, data:{name:张三,phone:138****1234,email:zhangsanexample.com}}这样的明文。4.2 常见问题与排查技巧实录在实际集成中你几乎一定会遇到下面这些问题。这里我把踩过的坑和解决方法记录下来。问题1请求体无法反序列化报错“JSON parse error”或“Required request body is missing”。排查首先检查日志看自定义的CryptoHttpMessageConverter的readInternal方法是否被调用。如果没有说明转换器未生效或优先级不够。解决确认WebMvcCryptoConfig配置类已被Spring扫描到有Configuration注解且在组件扫描路径下。确认configureMessageConverters方法中自定义转换器被添加到了列表前面converters.add(0, ...)。在readInternal方法开始处打日志确认流程是否进入。检查CryptoContext.isDecryptRequired()的值是否为true。如果为false请求会被交给默认的Jackson转换器而Jackson无法解析加密后的字符串它不是合法JSON所以会报错。这通常是因为拦截器没有正确设置DECRYPT_REQUIRED标志或者请求头X-Encrypt-Request未设置或值不为true。问题2加解密失败抛出“InvalidKeyException”或“BadPaddingException”。排查这是最经典的加解密问题根本原因是前后端参数不一致。解决请严格按照以下清单进行核对可以使用在线工具如SSLeye进行交叉验证参数项可能值核对要点密钥 (Key)16/24/32字节字符串长度必须严格对应AES-128/192/256。前后端字符串必须完全一致包括字符编码通常UTF-8。偏移量 (IV)通常16字节字符串仅CBC/CFB/OFB模式需要。ECB模式不需要IV。前后端必须一致。加密模式CBC, ECB, CFB等前后端Cipher.getInstance()中的模式字符串必须完全一致例如都是AES/CBC/PKCS5Padding。填充方式PKCS5Padding, NoPadding等同上必须一致。Java的PKCS5Padding实际上对应PKCS7Padding。数据编码Base64, Hex加密后是二进制传输前如何编码解密前如何解码必须一致。我们方案用的是Base64。字符集UTF-8, GBK等在将字符串如密钥、IV、明文转换成字节数组(.getBytes())时使用的字符集必须一致。我们工具类固定使用了StandardCharsets.UTF_8。问题3启用加密后Swagger/Actuator等内部接口访问异常。排查这些接口的请求和响应不是加密格式但被我们的拦截器/转换器处理了。解决这就是我们在配置中设计exclude-paths和拦截器中isExcludedPath方法的目的。确保application.yml中正确配置了排除路径例如/actuator/**,/v3/api-docs/**,/swagger-ui/**等。使用Ant风格路径匹配。问题4性能瓶颈在高并发下接口响应变慢。排查使用APM工具如SkyWalking, Arthas定位耗时环节很可能是加解密操作。优化缓存Cipher实例Cipher的初始化(init)相对耗时。可以使用ThreadLocalCipher为每个线程缓存加密和解密用的Cipher实例。但要注意Cipher不是线程安全的必须每个线程独享且每次使用前需要重新init因为每次的密钥/IV/模式可能不同在我们的动态密钥场景下尤其如此。如果密钥固定缓存才有较大收益。异步或批处理对于非实时性要求极高的场景可以考虑将加解密操作放到异步线程或队列中处理但这会改变响应模型。硬件加速确保JVM运行在支持AES-NI指令集的CPU上现代JDK会利用此指令集大幅提升AES运算速度。按需加密并非所有数据都需要加密。可以通过注解如EncryptField标记实体类中的敏感字段只在序列化时加密这些字段减少加密数据量。问题5如何实现更安全的动态密钥管理固定密钥写在配置文件里始终有泄露风险。更安全的做法是每次会话使用不同的密钥。方案一推荐RSA非对称加密交换AES密钥服务端持有RSA私钥将公钥下发给客户端。客户端每次请求前随机生成一个AES会话密钥Session Key和IV。客户端用RSA公钥加密这个AES会话密钥放在请求头如X-Session-Key中传给服务端。服务端用RSA私钥解密得到AES会话密钥存入CryptoContext用于本次请求/响应的加解密。该会话密钥可以有一定有效期用于多次请求过期后重新生成。方案二基于密钥派生函数KDF使用一个根密钥Master Key和每次请求的随机数Nonce通过HMAC或HKDF等算法派生出本次请求使用的AES密钥。服务端和客户端遵循相同算法即可同步无需传输密钥本身。5. 进阶优化与生产环境考量基础功能跑通后我们可以从健壮性、可观测性和安全性方面进行优化。5.1 统一异常处理与响应封装加解密过程可能失败我们需要给客户端返回友好的错误信息而不是500内部错误栈。RestControllerAdvice public class GlobalExceptionHandler { ExceptionHandler({HttpMessageNotReadableException.class}) public ApiResponse? handleDecryptException(HttpMessageNotReadableException e) { // 判断异常根源是否是解密失败 Throwable cause e.getCause(); if (cause ! null cause.getMessage() ! null cause.getMessage().contains(解密)) { return ApiResponse.fail(4001, 请求数据解密失败请检查加密参数或格式); } return ApiResponse.fail(4000, 请求数据格式错误); } ExceptionHandler({HttpMessageNotWritableException.class}) public ApiResponse? handleEncryptException(HttpMessageNotWritableException e) { if (e.getCause() ! null e.getCause().getMessage() ! null e.getCause().getMessage().contains(加密)) { return ApiResponse.fail(5001, 响应数据加密失败); } return ApiResponse.fail(5000, 服务器内部错误); } ExceptionHandler({RuntimeException.class}) public ApiResponse? handleRuntimeException(RuntimeException e) { // 处理AesCryptoUtils中抛出的运行时异常 if (e.getMessage() ! null (e.getMessage().contains(加密) || e.getMessage().contains(解密))) { return ApiResponse.fail(4002, 数据加解密处理异常); } return ApiResponse.fail(5000, 服务器内部错误); } }5.2 监控、日志与审计监控指标使用Micrometer等工具对加解密操作的耗时、成功率进行监控设置告警阈值。结构化日志在拦截器和消息转换器中记录关键信息如请求ID、是否加解密、耗时、密钥标识不记录完整密钥等便于链路追踪和问题排查。审计日志对于特别敏感的操作可以考虑记录“谁在什么时间请求了哪个加密接口”但注意不要记录加密后的具体数据内容。5.3 密钥安全管理绝对不要将生产环境的密钥硬编码在代码或配置文件中提交到Git。使用配置中心将密钥存储在Apollo、Nacos等配置中心并开启加密存储功能。使用KMS服务如果云上部署使用阿里云KMS、AWS KMS等密钥管理服务在应用启动时动态获取密钥。硬件安全模块HSM金融级安全要求使用HSM进行密钥存储和加解密运算。5.4 与现有NBSaaS-Boot生态的融合NBSaaS-Boot通常有自己的统一响应体、异常处理、权限校验等组件。我们的加解密方案应该与其无缝融合。响应体包装器确保我们的CryptoHttpMessageConverter在加密前处理的是已经被NBSaaS-Boot的ResponseBodyAdvice包装好的统一响应对象如ApiResponse。权限校验顺序在拦截器链中加解密拦截器应该在权限校验拦截器之前。因为权限校验可能需要读取请求体中的参数如userId如果请求体还未解密校验将失败。我们的方案由于在消息转换器中解密顺序是合理的。注解式开关可以进一步优化提供类似EncryptApi的注解标注在Controller类或方法上更精细地控制哪些接口需要加解密而不是完全依赖请求头。整个实现过程本质上是在Spring MVC的请求处理管道中巧妙地插入了一个“解码-编码”层。它没有改变业务开发者的编程模型却为数据传输增加了一层坚实的安全保障。这种“非侵入式”的架构思想在构建可维护、可扩展的中间件时非常值得借鉴。当你下次需要为API增加签名校验、流量染色、数据脱敏等全局功能时不妨也想想是否能在过滤器、拦截器或消息转换器这个层面优雅地解决。
