ResponseBodyAdvice?是 Spring MVC 提供的一個強大接口，允許你在響應體被寫入 HTTP 響應之前對其進行全局處理。

下面我將全面介紹它的工作原理、使用場景和最佳實踐。

基本概念

接口定義

public interface ResponseBodyAdvice<T> {boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType);@NullableT beforeBodyWrite(@Nullable T body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType,ServerHttpRequest request, ServerHttpResponse response);
}

核心方法

1. supports()

   • 決定是否對該方法的返回值應用 advice

   • 參數：

     • returnType: 控制器方法的返回類型信息

     • converterType: 將用于序列化響應體的消息轉換器類型

2. beforeBodyWrite()

   • 在消息轉換器寫入響應體之前對其進行處理

   • 參數：

     • body: 控制器返回的原始響應體

     • 其他參數與?supports()?相同

     • request/response: 當前請求和響應對象

典型應用場景

1. 統一響應封裝

最常見的用途是將所有控制器的返回值包裝成統一格式：

@RestControllerAdvice
public class UnifiedResponseAdvice implements ResponseBodyAdvice<Object> {@Overridepublic boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {return true;}@Overridepublic 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);@Overridepublic 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;}@Overridepublic boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {// 排除Swagger和Actuator端點return !(returnType.getDeclaringClass().getName().contains("springfox") || returnType.getDeclaringClass().getName().contains("org.springframework.boot.actuate"));}@Overridepublic 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@AllArgsConstructorpublic 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，你可以實現響應處理的集中管理，使代碼更加整潔和一致。