SpringBoot常用注解 @RestController 和 @ControllerAdvice

最新推荐文章于 2025-10-01 10:57:31 发布

原创最新推荐文章于 2025-10-01 10:57:31 发布 · 1.2k 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #后端 #java

本文讲述了SpringBoot中的`@RestControllerAdvice`（RESTfulAPI专用）和`@ControllerAdvice`（传统WebMVC）的区别，强调了各自的使用场景和功能。

SpringBoot常用注解 @RestController 和 @ControllerAdvice

@RestControllerAdvice 和 @ControllerAdvice 都是 Spring Framework 提供的用于全局控制器增强的注解，但它们的主要区别在于它们分别用于 RESTful API 应用和传统的 Web MVC 应用。

1. @RestControllerAdvice

功能：@RestControllerAdvice 主要用于 RESTful API 应用程序，它组合了 @ControllerAdvice 和 @ResponseBody 注解，用于全局处理异常、数据绑定和全局数据预处理。它的异常处理方法返回的是带有数据的响应体，通常用于返回 JSON 格式的错误信息。
用法：使用 @RestControllerAdvice 注解的类中可以定义 @ExceptionHandler、@InitBinder 和 @ModelAttribute 方法，用于捕获全局异常、初始化数据绑定器以及在所有 @RequestMapping 方法执行之前添加全局数据模型。以下是一个简单的用法示例：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<String> handleException(Exception ex) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Internal Server Error");
    }
    // 其他方法如 @InitBinder 和 @ModelAttribute
}

@RestControllerAdvice 注解可以传递几种不同类型的参数，以便于定义全局的异常处理、数据绑定和数据模型。

BasePackages 或 Value: 用于指定需要扫描的包路径，让 @RestControllerAdvice 仅作用于指定的包下的 Controller。可以使用 basePackages 或 value 属性进行配置。示例如下：

@RestControllerAdvice(basePackages = "com.example.controllers")
public class GlobalExceptionHandler {
    // 异常处理、数据绑定和数据模型方法
}

AssignableTypes: 用于指定要适用于哪些类型或接口的控制器。这允许你只针对特定类型的 Controller 进行全局配置。示例如下：

@RestControllerAdvice(assignableTypes = {UserController.class, ProductController.class})
public class GlobalExceptionHandler {
    // 异常处理、数据绑定和数据模型方法
}

Annotations: 用于指定只对带有特定注解的 Controller 进行全局配置。例如，如果你只想针对带有 @RestController 注解的 Controller 进行配置，可以使用 annotations 属性。示例如下：

@RestControllerAdvice(annotations = RestController.class)
public class GlobalExceptionHandler {
    // 异常处理、数据绑定和数据模型方法
}

通过这些参数的灵活使用，你可以对特定的 Controller 或者一组 Controller 进行全局配置，而不是将全局配置应用于整个应用程序的所有 Controller。这有助于提高灵活性并允许更细粒度的控制。

2. @ControllerAdvice

功能：@ControllerAdvice 用于传统的 Spring MVC 应用程序，它是 Spring 提供的用于全局控制器的增强功能的注解。它可以用于处理全局异常、数据绑定和全局数据预处理。
用法：使用 @ControllerAdvice 注解的类中同样可以定义 @ExceptionHandler、@InitBinder 和 @ModelAttribute 方法。通常在非 RESTful API 的应用程序中使用，返回的视图类型可以是 HTML 页面或其他视图技术所需的内容。

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ControllerAdvice;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public String handleException(Exception ex) {
        // 返回视图名或重定向地址等
        return "errorPage";
    }
    // 其他方法如 @InitBinder 和 @ModelAttribute
}

@ControllerAdvice 注解是用于全局控制器的增强，用于处理全局异常、数据绑定以及全局数据预处理。它可以传递以下参数：

BasePackages 或 Value: 用于指定需要扫描的包路径，让 @ControllerAdvice 仅作用于指定的包下的 Controller。可以使用 basePackages 或 value 属性进行配置。示例如下：

@ControllerAdvice(basePackages = "com.example.controllers")
public class GlobalControllerAdvice {
    // 异常处理、数据绑定和数据模型方法
}

AssignableTypes: 用于指定要适用于哪些类型或接口的控制器。这允许你只针对特定类型的 Controller 进行全局配置。示例如下：

@ControllerAdvice(assignableTypes = {UserController.class, ProductController.class})
public class GlobalControllerAdvice {
    // 异常处理、数据绑定和数据模型方法
}

Annotations: 用于指定只对带有特定注解的 Controller 进行全局配置。例如，如果你只想针对带有 @Controller 注解的 Controller 进行配置，可以使用 annotations 属性。示例如下：

@ControllerAdvice(annotations = Controller.class)
public class GlobalControllerAdvice {
    // 异常处理、数据绑定和数据模型方法
}

这些参数的使用方式与 @RestControllerAdvice 类似，通过使用这些参数，你可以对特定的 Controller 或一组 Controller 进行全局配置，而不是将全局配置应用于整个应用程序的所有 Controller。这种灵活性有助于提高控制器增强的精细度和可配置性。

全局异常处理案例代码

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public BaseResponse<?> businessExceptionHandler(BusinessException e) {
        log.error("BusinessException", e);
        return ResultUtils.error(e.getCode(), e.getMessage());
    }

    @ExceptionHandler(RuntimeException.class)
    public BaseResponse<?> runtimeExceptionHandler(RuntimeException e) {
        log.error("RuntimeException", e);
        return ResultUtils.error(ErrorCode.SYSTEM_ERROR, "系统错误");
    }
}