ResponseBodyAdvice 是 Spring MVC 提供的一个强大接口，允许你在响应体被写入 HTTP 响应之前对其进行全局处理。
下面我将全面介绍它的工作原理、使用场景和最佳实践。
基本概念
接口定义
public interface ResponseBodyAdvice<T> {
boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType);
@Nullable
T beforeBodyWrite(@Nullable T body, MethodParameter returnType,
MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType,
ServerHttpRequest request, ServerHttpResponse response);
}
核心方法
supports()
决定是否对该方法的返回值应用 advice
参数：
returnType: 控制器方法的返回类型信息converterType: 将用于序列化响应体的消息转换器类型
beforeBodyWrite()
在消息转换器写入响应体之前对其进行处理
参数：
body: 控制器返回的原始响应体其他参数与
supports()相同request/response: 当前请求和响应对象
典型应用场景
1. 统一响应封装
最常见的用途是将所有控制器的返回值包装成统一格式：
@RestControllerAdvice
public class UnifiedResponseAdvice implements ResponseBodyAdvice<Object> {
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
return true;
}
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType,
MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType,
ServerHttpRequest request, ServerHttpResponse response) {
if (body instanceof ApiResponse) {
return body;
}
return ApiResponse.success(body);
}
}
2. 响应数据脱敏
对敏感数据进行自动处理：
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType,
MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType,
ServerHttpRequest request, ServerHttpResponse response) {
if (body instanceof UserInfo) {
UserInfo user = (UserInfo) body;
user.setIdCard(desensitize(user.getIdCard()));
}
return body;
}
3. 响应数据缓存
缓存特定响应：
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType,
MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType,
ServerHttpRequest request, ServerHttpResponse response) {
if (request.getURI().getPath().contains("/api/cacheable")) {
cacheManager.put(generateCacheKey(request), body);
}
return body;
}
高级用法与最佳实践
1. 精确控制应用范围
通过 supports() 方法精确控制哪些方法需要处理：
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
// 只处理标注了@ResponseWrap注解的方法
return returnType.hasMethodAnnotation(ResponseWrap.class);
// 或者排除特定包下的控制器
// return !returnType.getDeclaringClass().getPackage().getName().startsWith("org.springdoc");
}
2. 处理特殊情况
处理String类型返回值
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType,
MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType,
ServerHttpRequest request, ServerHttpResponse response) {
if (body instanceof String) {
response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
return objectMapper.writeValueAsString(ApiResponse.success(body));
}
// 其他处理...
}
处理文件下载等非JSON响应
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
// 排除文件下载等场景
return !ResourceHttpMessageConverter.class.isAssignableFrom(converterType);
}
3. 性能优化
@RestControllerAdvice
public class CustomResponseAdvice implements ResponseBodyAdvice<Object> {
// 重用ObjectMapper实例
private static final ObjectMapper objectMapper = new ObjectMapper();
// 预定义的成功响应
private static final ApiResponse<?> EMPTY_SUCCESS = ApiResponse.success(null);
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType,
MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType,
ServerHttpRequest request, ServerHttpResponse response) {
if (body == null) {
return EMPTY_SUCCESS;
}
// 其他处理...
}
}
常见问题解决方案
1. 与Swagger的兼容性问题
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
// 排除Swagger相关的控制器
return !returnType.getDeclaringClass().getPackage().getName().startsWith("springfox.documentation");
}
2. 循环引用问题
当包装的对象存在循环引用时，需要在ObjectMapper中配置：
objectMapper.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false); objectMapper.configure(SerializationFeature.FAIL_ON_SELF_REFERENCES, false);
3. 异常处理
虽然ResponseBodyAdvice不处理异常，但可以与@ExceptionHandler配合使用：
@ExceptionHandler(Exception.class)
public ApiResponse<?> handleException(Exception e) {
return ApiResponse.failure(e.getMessage());
}
完整示例
@RestControllerAdvice
public class GlobalResponseAdvice implements ResponseBodyAdvice<Object> {
private final ObjectMapper objectMapper;
public GlobalResponseAdvice(ObjectMapper objectMapper) {
this.objectMapper = objectMapper;
}
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
// 排除Swagger和Actuator端点
return !(returnType.getDeclaringClass().getName().contains("springfox") ||
returnType.getDeclaringClass().getName().contains("org.springframework.boot.actuate"));
}
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType,
MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType,
ServerHttpRequest request, ServerHttpResponse response) {
// 非JSON响应不处理
if (!selectedContentType.includes(MediaType.APPLICATION_JSON)) {
return body;
}
// 已经是包装类型不处理
if (body instanceof ApiResponse) {
return body;
}
// 处理String类型返回值
if (body instanceof String) {
try {
response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
return objectMapper.writeValueAsString(ApiResponse.success(body));
} catch (JsonProcessingException e) {
throw new RuntimeException("JSON序列化失败", e);
}
}
// 空值处理
if (body == null) {
return ApiResponse.success();
}
// 默认包装
return ApiResponse.success(body);
}
@Data
@NoArgsConstructor
@AllArgsConstructor
public static class ApiResponse<T> {
private int code;
private String message;
private T data;
private long timestamp = System.currentTimeMillis();
public static <T> ApiResponse<T> success() {
return new ApiResponse<>(200, "success", null);
}
public static <T> ApiResponse<T> success(T data) {
return new ApiResponse<>(200, "success", data);
}
}
}
通过合理使用ResponseBodyAdvice，你可以实现响应处理的集中管理，使代码更加整洁和一致。