ContentCachingRequestWrapper 实战：解决请求体“只能读一次”的官方方案

ContentCachingRequestWrapper 是 Spring Framework（Spring 框架）官方原生提供的一个类，属于 spring-web 模块。

它的全限定名是：org.springframework.web.util.ContentCachingRequestWrapper。

只要你使用了 Spring Boot（引入了 spring-boot-starter-web），这个类就已经在你的项目依赖中了，不需要额外引入任何第三方包，直接 import 即可使用。

为什么 Spring 官方要提供这个类？（核心痛点）

要理解它的作用，我们需要了解 HTTP 请求底层的一个致命限制：InputStream（输入流）只能被读取一次。

在 Spring MVC 的处理流程中：

客户端发来一个 POST 请求（带有 JSON Body）。

Spring 内部的 DispatcherServlet 会调用 request.getInputStream() 读取请求体，然后利用 Jackson 把 JSON 反序列化成你 Controller 里的 Java 对象。

此时，流已经被消费（读完）了。

如果你在 Filter 或 Interceptor 里，试图通过 request.getInputStream() 去读取请求体来记录日志，你会发现要么读不到内容，要么导致后续 Controller 接收不到参数（因为流已被你提前读取完毕）。

ContentCachingRequestWrapper 是如何解决这个问题的？

它的设计模式是经典的装饰器模式（Decorator Pattern）。它把原始的 HttpServletRequest 包裹了起来，并在内存中开辟了一个字节数组（ByteArrayOutputStream）作为"缓存"。

它的工作机制如下：

当 Spring MVC 内部去读取请求流时，ContentCachingRequestWrapper 会拦截这个读取动作。

它在把数据传递给 Spring MVC 的同时，同步地把读到的字节拷贝一份，存到自己的内部缓存数组中。

等整个请求处理完毕后，你可以通过调用 getContentAsByteArray() 方法，从缓存中安全地读取完整的请求体。

⚠️ 实战中的"致命"避坑点

虽然它很好用，但在生产环境中使用它有一个极其容易踩的坑：它只缓存"已经被读取过"的内容。

这意味着，如果你在 Filter 的 doFilter 之前就立刻去调用 getContentAsByteArray()，你拿到的将是空数组！因为此时 Spring MVC 还没来得及去读流。

这就是为什么我在之前的代码示例中，把记录日志的逻辑放在了 finally 块中：

java 复制代码

@Component
@Order(1)
public class RequestLoggingFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) 
            throws ServletException, IOException {
        
        // 包装请求，使其可以多次读取 Body
        ContentCachingRequestWrapper wrappedRequest = new ContentCachingRequestWrapper(request);
        
        try {
            filterChain.doFilter(wrappedRequest, response);
        } finally {
            // 仅在需要时（如 DEBUG 级别或特定接口）才打印
            if (log.isDebugEnabled()) {
                byte[] buf = wrappedRequest.getContentAsByteArray();
                if (buf.length > 0) {
                    String body = new String(buf, StandardCharsets.UTF_8);
                    // 安全截断，防止日志炸弹
                    if (body.length() > 2000) {
                        body = body.substring(0, 2000) + "...(truncated)";
                    }
                    log.debug("上游请求体: {}", body);
                }
            }
        }
    }
}

总结：它是 Spring 官方为了解决"请求体流只能读一次"的底层缺陷而提供的官方解决方案，非常适合用来做全局的请求/响应日志记录。