告别手写拦截器：基于 RequestBodyAdvice 打造零侵入 Spring Boot 接口加解密与防篡改架构

在现代企业级应用与金融级开放平台的交互场景中，仅依靠底层的 HTTPS 传输加密往往无法完全满足多方审计与端到端零信任（Zero Trust）的安全合规要求。网络传输过程中的代理节点脱敏、抓包分析以及防篡改校验，常常迫使我们在应用层（HTTP Body）再套上一层坚固的加解密锁扣。

然而，翻看不少团队的工程代码，针对接口参数的加解密实现依然停留在极度原始的“侵入式泥潭”中：要么在每一个 Controller 方法里手动接收密文字符串再调用工具类解密；要么通过 Filter 强行读取 HttpServletRequest 流，导致框架后续反序列化因“流不可逆重复读取”直接抛出 IOException 崩溃。

本文将深入拆解 Spring MVC 框架的核心拦截扩展点，基于 RequestBodyAdvice 与 ResponseBodyAdvice，配合注解驱动与“RSA + AES-GCM”混合加密机制，打造一套对业务代码零侵入、高可用、可渐进式演进的生产级接口安全架构。

一、方案选型与架构哲学：为什么 Filter 和 Interceptor 都不合格？

在 Spring MVC 的请求处理流水线中，许多开发者在接到“接口入参加密”需求时的第一反应往往是写一个 Filter 或 HandlerInterceptor。但在实际工程落地中，这两种方式都存在致命的架构硬伤：

拦截组件类型	介入时机	优缺点对比与工程硬伤	推荐应用场景
Servlet Filter	容器顶层，进入 DispatcherServlet 之前	无法感知当前请求命中哪一个具体的 Controller 方法及方法上的自定义注解；若读取输入流必须自行包装 `HttpServletRequestWrapper` 缓存字节数组，容易造成内存开销	全局编码转换、跨域 CORS、链路 TraceId 注入
HandlerInterceptor	请求路由完成，执行 Controller 方法前	只能拦截请求参数（如 QueryParam），无法直接无损拦截并改写 HTTP 原始 Body 内容；无法参与 Jackson 的对象映射反序列化	登录态校验、权限 RBAC 鉴权、接口限流防刷
RequestBodyAdvice	HTTP 消息转换器（HttpMessageConverter）读取前后	天然与 Spring MVC 反序列化管线融合；可在原始流被解析为 Java DTO 之前精准解密，支持类/方法级注解细粒度路由，对业务层完全透明	HTTP 报文体统一解密、报文验签、脱敏转换

Mermaid Diagram

如上图所示，RequestBodyAdvice 的核心优势在于它卡位在 HTTP 原始字节流与 Jackson 实体反序列化之间。业务 Controller 接收到的依然是经过强类型校验的普通 Java DTO，完全感知不到底层密码学套件的流转细节。

二、端到端混合加密体系：RSA 密钥协商 + AES-GCM 高效传输

如果在每一次接口请求中都对长达数 KB 的业务 JSON 全量使用非对称加密（如 RSA），不仅会给服务端 CPU 带来沉重的计算负担，更可能导致高并发场景下的接口吞吐断崖式下跌。因此，工业界通行的最佳实践是采用混合加密体系：

客户端                                                    服务端 (Spring Boot)
  |                                                           |
  |--- 1. 生成一次性临时 AES-256 Key -------------------------->|
  |--- 2. 使用临时 AES Key 加密业务 JSON (AES-GCM) ------------->|
  |--- 3. 使用服务端公布的 RSA Public Key 加密 AES Key -------->|
  |--- 4. 打包发送统一安全报文: { encryptKey, cipherData, sign }->|
  |                                                           |
  |                                 5. RSA Private Key 解密获得临时 AES Key
  |                                 6. 校验签名防篡改 (HMAC-SHA256)
  |                                 7. AES Key 解密 cipherData 获得原始 JSON

1. 为什么强制要求 GCM 模式？

在对称加密选型上，严禁使用已被证明存在Padding Oracle攻击隐患的 AES/CBC/PKCS5Padding，必须全面升级为 AES/GCM/NoPadding。GCM 模式自带 GMAC 消息认证码，能够在解密的同时一体化完成报文完整性防篡改校验，兼具极高的吞吐与金融级防护能力。

三、透明解密实战：实现 RequestBodyAdvice 与防坑指南

通过实现 RequestBodyAdvice 接口，我们需要重写四个核心方法。其中最关键的是 supports 动态判定与 beforeBodyRead 流重塑：

@ControllerAdvice
public class DecryptRequestBodyAdvice implements RequestBodyAdvice {

    @Autowired
    private SecurityCryptoService cryptoService;

    @Override
    public boolean supports(MethodParameter methodParameter, Type targetType,
                            Class<? extends HttpMessageConverter<?>> converterType) {
        // 类或方法带有 @Decrypt 注解才触发解密拦截
        return methodParameter.hasMethodAnnotation(Decrypt.class) ||
               methodParameter.getDeclaringClass().isAnnotationPresent(Decrypt.class);
    }

    @Override
    public HttpInputMessage beforeBodyRead(HttpInputMessage inputMessage, MethodParameter parameter,
                                          Type targetType, Class<? extends HttpMessageConverter<?>> converterType) throws IOException {
        InputStream rawStream = inputMessage.getBody();
        byte[] rawBytes = rawStream.readAllBytes();
        if (rawBytes.length == 0) {
            return inputMessage;
        }

        String rawJson = new String(rawBytes, StandardCharsets.UTF_8);
        // 解析标准安全外壳报文
        EncryptedRequestPacket packet = JsonUtils.parse(rawJson, EncryptedRequestPacket.class);

        // 1. RSA 私钥解密出协商的临时 AES Key
        byte[] aesKey = cryptoService.rsaDecrypt(packet.getEncryptKey());

        // 2. 校验时间戳与防重放 Nonce
        cryptoService.verifyNonceAndTimestamp(packet.getTimestamp(), packet.getNonce());

        // 3. AES-GCM 解密业务负载
        String plainJson = cryptoService.aesGcmDecrypt(packet.getCipherData(), aesKey);

        // 4. 重塑输入流交由 Jackson 完成对象绑定
        ByteArrayInputStream decryptedStream = new ByteArrayInputStream(plainJson.getBytes(StandardCharsets.UTF_8));
        return new DecryptedHttpInputMessage(inputMessage.getHeaders(), decryptedStream);
    }

    @Override
    public Object afterBodyRead(Object body, HttpInputMessage inputMessage, MethodParameter parameter,
                                Type targetType, Class<? extends HttpMessageConverter<?>> converterType) {
        return body;
    }

    @Override
    public Object handleEmptyBody(Object body, HttpInputMessage inputMessage, MethodParameter parameter,
                                  Type targetType, Class<? extends HttpMessageConverter<?>> converterType) {
        return body;
    }
}

踩坑预警：包装类重塑与 Headers 保留

在 beforeBodyRead 返回自定义的 HttpInputMessage 时，务必将原 inputMessage.getHeaders() 原样保留或透传。若遗漏请求头中的 Content-Type: application/json，下游的 MappingJackson2HttpMessageConverter 将直接跳过反序列化，导致方法入参全部绑定为 null！

四、响应无感加密：ResponseBodyAdvice 与统一返回实体兼容

当 Controller 方法处理完毕返回普通的 Java POJO 时，ResponseBodyAdvice 可以在数据被写入网络输出流之前进行最终截胡：

@ControllerAdvice
public class EncryptResponseBodyAdvice implements ResponseBodyAdvice<Object> {

    @Autowired
    private SecurityCryptoService cryptoService;

    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return returnType.hasMethodAnnotation(Encrypt.class) ||
               returnType.getDeclaringClass().isAnnotationPresent(Encrypt.class);
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
                                  Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                  ServerHttpRequest request, ServerHttpResponse response) {
        if (body == null) {
            return null;
        }

        // 序列化为原始 JSON
        String plainJson = (body instanceof String) ? (String) body : JsonUtils.toJson(body);

        // 获取本次会话协商好的 AES Key（可通过 ThreadLocal 或 RequestAttribute 传递）
        byte[] sessionAesKey = SecurityContextHolder.getAesKey();

        // 执行 AES-GCM 加密并封装为统一外壳
        String cipherData = cryptoService.aesGcmEncrypt(plainJson, sessionAesKey);
        EncryptedResponsePacket packet = new EncryptedResponsePacket();
        packet.setCipherData(cipherData);
        packet.setTimestamp(System.currentTimeMillis());

        return packet;
    }
}

⚠️ 字符串类型转换陷阱（StringHttpMessageConverter）：当 Controller 方法的返回值本身就是 String 类型时，Spring MVC 会优先调用 StringHttpMessageConverter。如果在 Advice 中返回了非 String 对象（如 EncryptedResponsePacket），会导致抛出 ClassCastException。解决方案是判断当前返回值是否为 String，若为 String 则需在 Advice 内部手动转换为序列化后的 JSON 字符串返回。