@RestControllerAdvice 是 Spring Boot 中用于全局异常处理、统一返回值封装和参数校验失败响应的核心注解，本质是 @ControllerAdvice 与 @ResponseBody 的组合，专为 RESTful 接口设计，不替代拦截器或过滤器。
@RestControllerAdvice 是 Spring Boot 中用于全局异常处理和统一响应封装的核心注解，它本质是 @ControllerAdvice 与 @ResponseBody 的组合，专为 RESTful 接口设计。要实现“统一拦截”，关键不在于拦截请求本身（那是 @ControllerAdvice + @ModelAttribute 或拦截器的事），而是在于对**异常、返回值、参数绑定失败等场景进行集中、标准化的响应处理**。
统一异常处理：捕获并格式化所有未被捕获的异常
这是 @RestControllerAdvice 最常用也最核心的用途。你无需在每个 Controller 里写 try-catch，只需定义一个全局处理器：
- 用
@ExceptionHandler标注方法，指定能处理的异常类型（如IllegalArgumentException、NullPointerException或自定义业务异常） - 方法返回值会自动序列化为 JSON（因为是
@RestControllerAdvice） - 建议搭配自定义异常类（如
BusinessException）和标准响应体（如Result<T>）使用
示例：
<!-- 简化代码示意 -->@ResponseStatus(HttpStatus.BAD_REQUEST)<br> @ExceptionHandler(BusinessException.class)<br> public Result<Void> handleBusinessException(BusinessException e) {<br> return Result.fail(e.getCode(), e.getMessage());<br> }
立即学习“Java免费学习笔记（深入）”；
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
统一返回值封装：用 @ControllerAdvice + ResponseBodyAdvice 实现自动包装
如果希望所有接口返回值都自动套一层 Result.success(data)，不能只靠 @RestControllerAdvice，需配合 ResponseBodyAdvice 接口：
- 创建一个类实现
ResponseBodyAdvice<T> - 重写
supports()决定哪些 Controller 方法生效（可按注解、包名、返回类型过滤） - 重写
beforeBodyWrite()对原始返回值做包装（注意避免重复包装 String/ResponseEntity 等） - 该类需用
@ControllerAdvice（不是 RestControllerAdvice）或直接被@RestControllerAdvice扫描到
常见做法是定义一个空注解（如 @ApiResult），加在需要自动包装的 Controller 方法上，然后在 supports() 中判断是否存在该注解。
统一参数校验失败响应：覆盖默认的 MethodArgumentNotValidException 处理
当使用 @Valid 或 @Validated 校验 DTO 出错时，Spring 默认抛出 MethodArgumentNotValidException。你可以在 @RestControllerAdvice 中专门捕获它：
- 提取
BindingResult中的所有错误信息（字段名 + 错误消息） - 组装成更友好的提示（如
{"code":400,"msg":"参数校验失败","details":[{"field":"email","message":"邮箱格式不正确"}]}） - 避免暴露后端细节（如 Hibernate Validator 的默认英文提示），建议用
MessageSource做国际化
补充说明：它不替代拦截器，也不处理正常请求逻辑
@RestControllerAdvice 不适合做权限校验、日志记录、请求头预处理等——这些应交给 HandlerInterceptor、Filter 或 AOP。它的定位非常明确：只管“出问题时怎么响应”和“返回值要不要统一包一层”。想做到真正“全链路统一”，通常需要这三者协同：
– Filter（处理编码、跨域、原始请求日志）
– Interceptor（鉴权、租户识别、业务级请求日志）
– RestControllerAdvice（异常兜底 + 返回值美化）
