@restcontrolleradvice是spring boot中用于rest接口的全局处理注解，本质为@controlleradvice与@responsebody组合，支持@exceptionhandler统一异常处理、@initbinder参数预处理、@modelattribute注入公共数据，最常用作全局异常处理器并配合apiresponse规范响应。
@RestControllerAdvice 是 Spring Boot 中专为 REST 接口设计的全局处理注解，本质是 @ControllerAdvice + @ResponseBody 的组合。它不写在具体接口类上，而是独立定义一个“全局处理器类”，统一拦截所有 @RestController（或 @Controller 配合 @ResponseBody）中抛出的异常、预处理请求参数、或注入公共模型数据。
核心用途：三类全局操作
它主要支撑三种横切逻辑，全部通过不同注解方法实现：
- @ExceptionHandler：捕获并格式化异常，比如业务异常、参数校验失败、空指针等，返回统一 JSON 错误响应；
- @InitBinder：对控制器入参做预处理，如注册日期格式化器、过滤 XSS 字符、绑定自定义类型转换器；
- @ModelAttribute：在每个请求执行前自动向 Model 注入公共数据（如当前登录用户、系统配置），但注意：该功能在纯 REST 场景中较少用，因通常不走视图渲染。
最常用写法：全局异常处理器
绝大多数项目只用它做异常统一处理。一个典型示例如下：
// 全局异常处理类@RestControllerAdvicepublic class GlobalExceptionHandler { @ExceptionHandler(BusinessException.class) public ResponseEntity<apiresponse> handleBusinessException(BusinessException e) {</apiresponse> return ResponseEntity.badRequest().body(ApiResponse.fail(e.getCode(), e.getMessage())); } @ExceptionHandler(MethodArgumentNotValidException.class) public ResponseEntity<apiresponse> handleValidation(MethodArgumentNotValidException e) {</apiresponse> String errorMsg = e.getBindingResult().getFieldErrors().get(0).getDefaultMessage(); return ResponseEntity.unprocessableEntity().body(ApiResponse.fail("VALIDATE_FAIL", errorMsg)); } @ExceptionHandler(Exception.class) public ResponseEntity<apiresponse> handleOther(Exception e) {</apiresponse> log.error("未预期异常", e); return ResponseEntity.status(500).body(ApiResponse.fail("SYSTEM_ERROR", "服务繁忙")); }}
精准控制作用范围
默认情况下，@RestControllerAdvice 对所有控制器生效。如需限制范围，可通过属性指定：
-
basePackages = "com.example.api"：只处理指定包下的控制器； -
assignableTypes = {UserController.class, OrderController.class}：仅针对特定 Controller 类； -
annotations = RestController.class：只匹配标注了@RestController的类（排除普通@Controller）。
配合统一响应体更规范
建议搭配自定义响应结构（如 ApiResponse<t></t>）使用，避免直接返回字符串或原始对象。这样前端能稳定解析 code、message、data 字段，也便于后续加 traceId、时间戳等扩展字段。所有异常分支都走同一响应模板，真正实现前后端契约一致。
