Spring Boot拦截器中获取requestBody的最佳实践

1. 为什么需要获取requestBody？

在Spring Boot开发中，拦截器(Interceptor)是处理HTTP请求的重要组件。但很多开发者都遇到过这样的困境：在拦截器的preHandle方法中，无法直接获取到请求体(requestBody)的内容。这主要是因为ServletRequest的输入流(InputStream)只能被读取一次，如果在Controller中已经读取了requestBody，拦截器就无法再次获取。

重要提示：ServletRequest的输入流设计为只能被读取一次，这是出于性能和资源管理的考虑。一旦流被读取，就无法回滚或重置。

这个限制在实际开发中会带来诸多不便。比如：

• 需要在拦截器中对请求体进行签名验证
• 需要记录完整的请求日志
• 需要对请求参数进行统一预处理
• 需要实现基于请求内容的权限控制

2. 传统方案的局限性

2.1 直接读取InputStream的问题

最常见的错误做法是直接在拦截器中尝试读取输入流：

public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { BufferedReader reader = request.getReader(); String body = reader.lines().collect(Collectors.joining()); // 处理body... }

这种方法会导致：

1. Controller中无法再获取请求体（流已被消费）
2. 如果请求体很大，可能造成内存溢出
3. 无法处理multipart/form-data类型的请求

2.2 使用Filter包装请求的缺陷

另一种常见方案是使用Filter提前读取并缓存请求体：

public class CachingRequestBodyFilter implements Filter { @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException { CachedBodyHttpServletRequest wrappedRequest = new CachedBodyHttpServletRequest((HttpServletRequest) request); chain.doFilter(wrappedRequest, response); } }

虽然这种方法可行，但存在以下问题：

1. 增加了额外的内存开销（需要缓存整个请求体）
2. 对于文件上传等大请求不适用
3. 需要维护自定义的RequestWrapper类

3. 最佳实践方案

3.1 使用ContentCachingRequestWrapper

Spring提供了ContentCachingRequestWrapper类，这是官方推荐的解决方案：

public class RequestLoggingInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { if (request instanceof ContentCachingRequestWrapper) { return true; // 已经包装过 } // 将原始请求包装为可缓存请求 ContentCachingRequestWrapper wrapper = new ContentCachingRequestWrapper(request); request.setAttribute("cachedRequest", wrapper); return true; } @Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { ContentCachingRequestWrapper wrapper = (ContentCachingRequestWrapper) request.getAttribute("cachedRequest"); byte[] content = wrapper.getContentAsByteArray(); if (content.length > 0) { String body = new String(content, wrapper.getCharacterEncoding()); // 处理请求体内容... } } }

关键点说明：

1. 在preHandle中将原始请求包装为ContentCachingRequestWrapper
2. 在afterCompletion中获取缓存的请求体内容
3. 请求体被自动缓存为byte数组，不会影响原始请求处理

3.2 配置拦截器注册

需要在Spring配置中注册拦截器并确保包装器生效：

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new RequestLoggingInterceptor()) .addPathPatterns("/api/**"); } @Bean public FilterRegistrationBean<ContentCachingRequestFilter> contentCachingRequestFilter() { FilterRegistrationBean<ContentCachingRequestFilter> registration = new FilterRegistrationBean<>(); registration.setFilter(new ContentCachingRequestFilter()); registration.addUrlPatterns("/api/*"); return registration; } }

3.3 自定义Filter实现

对于更复杂的需求，可以实现自定义Filter：

public class ContentCachingRequestFilter extends OncePerRequestFilter { @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { ContentCachingRequestWrapper wrappedRequest = new ContentCachingRequestWrapper(request); // 提前触发缓存 wrappedRequest.getParameterMap(); filterChain.doFilter(wrappedRequest, response); } }

这个Filter会：

1. 自动包装所有匹配的请求
2. 提前触发参数解析和缓存
3. 确保拦截器能获取到完整的请求内容

4. 性能优化与注意事项

4.1 内存管理策略

对于大请求体，需要特别注意内存使用：

1. 设置最大缓存大小：

ContentCachingRequestWrapper wrapper = new ContentCachingRequestWrapper(request, 1024 * 1024); // 1MB限制

2. 对于文件上传等场景，建议跳过请求体处理：

if (request.getContentType() != null && request.getContentType().contains("multipart/form-data")) { return true; // 跳过文件上传请求 }

4.2 字符编码处理

正确处理字符编码非常重要：

String body = new String(content, Optional.ofNullable(wrapper.getCharacterEncoding()) .orElse(StandardCharsets.UTF_8.name()));

4.3 性能对比测试

我们对几种方案进行了性能测试（1000次请求平均耗时）：

结论：ContentCachingRequestWrapper在性能和内存占用上取得了较好的平衡。

5. 实际应用场景

5.1 请求日志记录

完整记录请求和响应：

@Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { ContentCachingRequestWrapper requestWrapper = WebUtils.getNativeRequest(request, ContentCachingRequestWrapper.class); ContentCachingResponseWrapper responseWrapper = WebUtils.getNativeResponse(response, ContentCachingResponseWrapper.class); if (requestWrapper != null) { String requestBody = getRequestBody(requestWrapper); log.info("Request URL: {}, Method: {}, Body: {}", requestWrapper.getRequestURI(), requestWrapper.getMethod(), requestBody); } if (responseWrapper != null) { String responseBody = getResponseBody(responseWrapper); log.info("Response Status: {}, Body: {}", responseWrapper.getStatus(), responseBody); responseWrapper.copyBodyToResponse(); // 必须调用 } }

5.2 签名验证

实现API签名验证：

@Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { ContentCachingRequestWrapper wrapper = WebUtils.getNativeRequest(request, ContentCachingRequestWrapper.class); if (wrapper == null) { wrapper = new ContentCachingRequestWrapper(request); request.setAttribute("cachedRequest", wrapper); } String requestBody = getRequestBody(wrapper); String sign = request.getHeader("X-Signature"); if (!verifySignature(requestBody, sign)) { response.sendError(HttpStatus.UNAUTHORIZED.value(), "Invalid signature"); return false; } return true; }

5.3 参数预处理

统一处理请求参数：

@Override public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) { ContentCachingRequestWrapper wrapper = WebUtils.getNativeRequest(request, ContentCachingRequestWrapper.class); String body = getRequestBody(wrapper); // 对敏感信息进行脱敏 String processedBody = processSensitiveData(body); // 将处理后的body放回request属性 request.setAttribute("processedBody", processedBody); }

6. 常见问题与解决方案

6.1 获取不到请求体内容

可能原因：

1. 请求已经被其他组件读取过
2. 没有正确包装请求
3. 在preHandle中尝试读取（此时body尚未缓存）

解决方案：

1. 确保在Filter链的最开始包装请求
2. 在afterCompletion中读取内容
3. 检查请求是否已被其他拦截器处理

6.2 中文乱码问题

处理方法：

// 明确指定编码 String body = new String(wrapper.getContentAsByteArray(), Optional.ofNullable(wrapper.getCharacterEncoding()) .orElse(StandardCharsets.UTF_8.name()));

6.3 大文件上传内存溢出

应对策略：

1. 排除multipart请求：

if (request.getContentType() != null && request.getContentType().startsWith("multipart/")) { return true; }

2. 设置合理的缓存大小限制
3. 对于大文件，考虑使用临时文件缓存

6.4 Spring Boot版本差异

不同版本行为差异：

• Spring Boot 2.x: 需要手动包装请求
• Spring Boot 3.x: 部分场景下自动包装

兼容性处理：

if (!(request instanceof ContentCachingRequestWrapper)) { request = new ContentCachingRequestWrapper(request); }

7. 高级技巧与扩展

7.1 与Validation结合

在拦截器中进行预验证：

@Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { ContentCachingRequestWrapper wrapper = wrapRequest(request); String body = getRequestBody(wrapper); // 使用Jackson解析JSON ObjectMapper mapper = new ObjectMapper(); try { MyRequestDTO dto = mapper.readValue(body, MyRequestDTO.class); // 手动触发校验 ValidatorFactory factory = Validation.buildDefaultValidatorFactory(); Validator validator = factory.getValidator(); Set<ConstraintViolation<MyRequestDTO>> violations = validator.validate(dto); if (!violations.isEmpty()) { // 返回校验错误 sendValidationError(response, violations); return false; } } catch (JsonProcessingException e) { response.sendError(HttpStatus.BAD_REQUEST.value(), "Invalid JSON format"); return false; } return true; }

7.2 异步请求处理

对于异步请求的特殊处理：

@Override public void afterConcurrentHandlingStarted(HttpServletRequest request, HttpServletResponse response, Object handler) { // 异步请求时会被调用 ContentCachingRequestWrapper wrapper = WebUtils.getNativeRequest(request, ContentCachingRequestWrapper.class); if (wrapper != null) { wrapper.copyBodyToResponse(); // 确保内容可用 } }

7.3 与Swagger/Knife4j集成

不影响API文档的解决方案：

@Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 排除Swagger相关请求 String uri = request.getRequestURI(); if (uri.contains("swagger") || uri.contains("api-docs") || uri.contains("webjars")) { return true; } // 正常处理逻辑... }

7.4 性能监控集成

实现请求耗时监控：

@Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { request.setAttribute("startTime", System.currentTimeMillis()); return true; } @Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { Long startTime = (Long) request.getAttribute("startTime"); long duration = System.currentTimeMillis() - startTime; ContentCachingRequestWrapper wrapper = WebUtils.getNativeRequest(request, ContentCachingRequestWrapper.class); String requestBody = wrapper != null ? getRequestBody(wrapper) : ""; metricsService.recordRequest( request.getMethod(), request.getRequestURI(), requestBody, duration, response.getStatus() ); }

8. 完整示例代码

8.1 拦截器实现

@Slf4j public class RequestResponseLoggingInterceptor implements HandlerInterceptor { private final ObjectMapper objectMapper = new ObjectMapper(); @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { if (!(request instanceof ContentCachingRequestWrapper)) { ContentCachingRequestWrapper wrapper = new ContentCachingRequestWrapper(request); request.setAttribute("cachedRequest", wrapper); } return true; } @Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { try { logRequest(request); logResponse(response); } catch (Exception e) { log.warn("Failed to log request/response", e); } } private void logRequest(HttpServletRequest request) throws IOException { ContentCachingRequestWrapper wrapper = WebUtils.getNativeRequest(request, ContentCachingRequestWrapper.class); if (wrapper == null) return; Map<String, Object> requestLog = new LinkedHashMap<>(); requestLog.put("method", wrapper.getMethod()); requestLog.put("uri", wrapper.getRequestURI()); requestLog.put("query", wrapper.getQueryString()); Map<String, String> headers = Collections.list(wrapper.getHeaderNames()) .stream() .collect(Collectors.toMap( Function.identity(), h -> String.join("|", Collections.list(wrapper.getHeaders(h))) )); requestLog.put("headers", headers); String requestBody = getRequestBody(wrapper); if (StringUtils.hasText(requestBody)) { try { requestLog.put("body", objectMapper.readValue(requestBody, Object.class)); } catch (JsonProcessingException e) { requestLog.put("body", requestBody); } } log.info("Request: {}", objectMapper.writeValueAsString(requestLog)); } private void logResponse(HttpServletResponse response) throws IOException { if (!(response instanceof ContentCachingResponseWrapper)) return; ContentCachingResponseWrapper wrapper = (ContentCachingResponseWrapper) response; wrapper.copyBodyToResponse(); // 必须调用 Map<String, Object> responseLog = new LinkedHashMap<>(); responseLog.put("status", wrapper.getStatus()); Map<String, String> headers = wrapper.getHeaderNames() .stream() .collect(Collectors.toMap( Function.identity(), h -> String.join("|", wrapper.getHeaders(h)) )); responseLog.put("headers", headers); String responseBody = getResponseBody(wrapper); if (StringUtils.hasText(responseBody)) { try { responseLog.put("body", objectMapper.readValue(responseBody, Object.class)); } catch (JsonProcessingException e) { responseLog.put("body", responseBody); } } log.info("Response: {}", objectMapper.writeValueAsString(responseLog)); } private String getRequestBody(ContentCachingRequestWrapper wrapper) { byte[] content = wrapper.getContentAsByteArray(); if (content.length > 0) { return new String(content, Optional.ofNullable(wrapper.getCharacterEncoding()) .orElse(StandardCharsets.UTF_8.name())); } return ""; } private String getResponseBody(ContentCachingResponseWrapper wrapper) { byte[] content = wrapper.getContentAsByteArray(); if (content.length > 0) { return new String(content, Optional.ofNullable(wrapper.getCharacterEncoding()) .orElse(StandardCharsets.UTF_8.name())); } return ""; } }

8.2 Spring配置

@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new RequestResponseLoggingInterceptor()) .addPathPatterns("/api/**") .excludePathPatterns("/swagger*/**", "/webjars/**", "/v3/api-docs/**"); } @Bean public FilterRegistrationBean<ContentCachingFilter> contentCachingFilter() { FilterRegistrationBean<ContentCachingFilter> registration = new FilterRegistrationBean<>(); registration.setFilter(new ContentCachingFilter()); registration.addUrlPatterns("/api/*"); registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 1); return registration; } } class ContentCachingFilter extends OncePerRequestFilter { @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { ContentCachingRequestWrapper requestWrapper = new ContentCachingRequestWrapper(request); ContentCachingResponseWrapper responseWrapper = new ContentCachingResponseWrapper(response); try { filterChain.doFilter(requestWrapper, responseWrapper); } finally { responseWrapper.copyBodyToResponse(); } } }

8.3 自定义RequestWrapper

对于特殊需求，可以扩展ContentCachingRequestWrapper：

public class EnhancedCachingRequestWrapper extends ContentCachingRequestWrapper { private byte[] cachedBody; private Map<String, String[]> parameterMap; public EnhancedCachingRequestWrapper(HttpServletRequest request) { super(request); } @Override public String getParameter(String name) { if (this.parameterMap == null) { this.parameterMap = new HashMap<>(super.getParameterMap()); cacheRequestBody(); } String[] values = this.parameterMap.get(name); return values != null && values.length > 0 ? values[0] : null; } @Override public Map<String, String[]> getParameterMap() { if (this.parameterMap == null) { this.parameterMap = new HashMap<>(super.getParameterMap()); cacheRequestBody(); } return Collections.unmodifiableMap(this.parameterMap); } private void cacheRequestBody() { if (super.getContentAsByteArray().length == 0) { return; } try { String body = new String(super.getContentAsByteArray(), getCharacterEncoding()); if (body.startsWith("{") || body.startsWith("[")) { // JSON格式 ObjectMapper mapper = new ObjectMapper(); Map<String, Object> jsonMap = mapper.readValue(body, new TypeReference<Map<String, Object>>() {}); jsonMap.forEach((key, value) -> { if (value != null) { String[] values = value instanceof Collection ? ((Collection<?>) value).stream().map(Object::toString).toArray(String[]::new) : new String[]{value.toString()}; this.parameterMap.put(key, values); } }); } } catch (IOException e) { // 忽略解析错误 } } }

9. 测试策略

9.1 单元测试示例

@SpringBootTest @AutoConfigureMockMvc class RequestLoggingInterceptorTest { @Autowired private MockMvc mockMvc; @Test void shouldLogRequestAndResponse() throws Exception { mockMvc.perform(post("/api/test") .contentType(MediaType.APPLICATION_JSON) .content("{\"name\":\"test\",\"value\":123}")) .andExpect(status().isOk()); // 验证日志输出 // 实际项目中可以使用MemoryAppender等工具捕获日志进行断言 } @Test void shouldHandleGetRequestWithoutBody() throws Exception { mockMvc.perform(get("/api/test") .param("name", "test") .param("value", "123")) .andExpect(status().isOk()); } @Test void shouldSkipSwaggerUrls() throws Exception { mockMvc.perform(get("/swagger-ui/index.html")) .andExpect(status().isOk()); // 验证拦截器没有处理Swagger请求 } }

9.2 性能测试建议

使用JMeter或类似工具进行性能测试：

1. 测试不同大小请求体的处理时间
2. 测试并发请求下的内存使用情况
3. 对比开启和关闭拦截器时的吞吐量差异

关键指标：

• 平均响应时间
• 99线响应时间
• 内存占用峰值
• 错误率

10. 生产环境建议

10.1 日志记录优化

在生产环境中：

1. 对敏感信息进行脱敏处理
2. 控制日志级别，避免过度记录
3. 对大型请求体进行截断记录

示例脱敏处理：

private String maskSensitiveData(String body) { try { JsonNode root = objectMapper.readTree(body); if (root.has("password")) { ((ObjectNode) root).put("password", "******"); } if (root.has("creditCard")) { ((ObjectNode) root).put("creditCard", maskCreditCard(root.get("creditCard").asText())); } return objectMapper.writeValueAsString(root); } catch (IOException e) { return body; // 解析失败返回原始body } }

10.2 异常处理增强

完善异常处理逻辑：

@Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { try { // 正常处理逻辑... } catch (Exception e) { log.error("Failed to process request/response logging", e); // 不影响主流程 } }

10.3 动态配置

通过配置中心实现动态控制：

@RefreshScope @Configuration public class InterceptorConfig { @Value("${logging.interceptor.enabled:true}") private boolean enabled; @Value("${logging.interceptor.maxBodySize:1024}") private int maxBodySize; @Bean public HandlerInterceptor requestLoggingInterceptor() { return new RequestLoggingInterceptor(enabled, maxBodySize); } }

10.4 监控与告警

集成监控系统：

1. 记录拦截器处理耗时
2. 监控异常情况
3. 设置大请求体告警

@Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { long startTime = (Long) request.getAttribute("startTime"); long duration = System.currentTimeMillis() - startTime; metrics.record("interceptor.time", duration); if (duration > 1000) { alertService.notifySlowRequest(request.getRequestURI(), duration); } }

在实际项目中，我通常会根据具体需求对拦截器进行定制。比如在金融项目中，我们会增加严格的签名验证和参数校验；在日志分析系统中，我们会优化大请求体的处理方式。关键是要理解业务需求，选择最适合的技术方案。