Spring Boot中异常统一处理@RestControllerAdvice不生效原因解析 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

Spring Boot 异常统一处理 @RestControllerAdvice 不生效原因解析

大家好，今天我们来聊聊 Spring Boot 中使用 @RestControllerAdvice 进行全局异常处理时，可能遇到的不生效问题，以及如何排查和解决这些问题。

1. @RestControllerAdvice 的基本概念和作用

首先，我们需要明确 @RestControllerAdvice 的作用。简单来说，它是一个组件注解，结合 @ExceptionHandler，用于定义全局的异常处理逻辑。它能够拦截所有带有 @RestController 注解的 Controller 中抛出的异常，并根据异常类型执行相应的处理方法。

工作原理如下：

拦截异常： 当 Controller 中抛出异常时，Spring MVC 会查找合适的异常处理器。
匹配异常处理器： @RestControllerAdvice 定义的类中的 @ExceptionHandler 方法会与抛出的异常类型进行匹配。
执行处理方法： 如果找到匹配的 @ExceptionHandler 方法，则执行该方法，并将异常对象作为参数传入。
返回结果： @ExceptionHandler 方法的返回值会被作为响应返回给客户端。

示例代码：

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(value = {NullPointerException.class})
    public ResponseEntity<String> handleNullPointerException(NullPointerException ex) {
        // 记录日志
        System.err.println("NullPointerException 发生: " + ex.getMessage());
        return new ResponseEntity<>("空指针异常，请检查代码！", HttpStatus.INTERNAL_SERVER_ERROR);
    }

    @ExceptionHandler(value = {IllegalArgumentException.class})
    public ResponseEntity<String> handleIllegalArgumentException(IllegalArgumentException ex) {
        // 记录日志
        System.err.println("IllegalArgumentException 发生: " + ex.getMessage());
        return new ResponseEntity<>("参数不合法异常，请检查参数！", HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(value = {Exception.class})
    public ResponseEntity<String> handleException(Exception ex) {
        // 记录日志
        System.err.println("未知异常发生: " + ex.getMessage());
        return new ResponseEntity<>("服务器内部错误，请稍后再试！", HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

在这个例子中，GlobalExceptionHandler 类使用 @RestControllerAdvice 注解，表示它是一个全局异常处理器。它定义了三个 @ExceptionHandler 方法，分别处理 NullPointerException、IllegalArgumentException 和 Exception 类型的异常。当 Controller 中抛出这些异常时，对应的处理方法会被执行，并将异常信息返回给客户端。

2. @RestControllerAdvice 不生效的常见原因

虽然 @RestControllerAdvice 使用起来很简单，但在实际开发中，我们可能会遇到它不生效的情况。下面列举了一些常见的原因：

原因	描述	解决方案
2.1 包扫描问题	Spring Boot 无法扫描到 `@RestControllerAdvice` 注解的类，导致它没有被注册为 Bean。	确保 `@RestControllerAdvice` 类所在的包在 Spring Boot 的扫描范围内。可以通过以下方式解决： 1. 将 `@RestControllerAdvice` 类放在 Spring Boot 应用主类所在的包或其子包中。 2. 使用 `@ComponentScan` 注解显式指定要扫描的包。
2.2 异常被 Controller 内部捕获	Controller 内部使用了 `try-catch` 语句捕获了异常，并进行了处理，导致异常没有传播到 `@RestControllerAdvice`。	确保 Controller 中没有过度捕获异常。如果需要捕获异常，可以在 `catch` 块中重新抛出异常，或者使用 `throw new RuntimeException(ex)` 将异常转换为运行时异常。
2.3 `@ExceptionHandler` 方法参数不匹配	`@ExceptionHandler` 方法的参数类型与抛出的异常类型不匹配，导致 Spring MVC 无法找到合适的异常处理器。	检查 `@ExceptionHandler` 方法的参数类型是否与抛出的异常类型一致。可以使用异常的父类作为参数类型，例如 `Exception` 或 `Throwable`。
2.4 `@RestControllerAdvice` 类未被 Spring 管理	即使 `@RestControllerAdvice` 类在扫描范围内，但由于某些原因，它没有被 Spring 容器管理，例如没有添加 `@Component`、`@Service` 等注解。	确保 `@RestControllerAdvice` 类被 Spring 容器管理。可以使用 `@Component`、`@Service` 或 `@ControllerAdvice` 注解将其声明为 Bean。虽然 `@RestControllerAdvice` 本身就是个 `@Component`，但是最好还是显式声明，避免一些潜在的问题。
2.5 AOP 拦截器问题	AOP 拦截器可能会在异常传播的过程中将其捕获并处理，导致异常没有到达 `@RestControllerAdvice`。	检查项目中是否定义了 AOP 拦截器，并确保它们不会过度捕获异常。如果需要使用 AOP 拦截器处理异常，应该在 `@RestControllerAdvice` 之前执行。可以调整 AOP 拦截器的优先级，使其在 `@RestControllerAdvice` 之前执行。
2.6 异常被更早的 HandlerExceptionResolver 处理	Spring MVC 中有多个 `HandlerExceptionResolver`，它们按照一定的顺序执行。如果异常被更早的 `HandlerExceptionResolver` 处理了，就不会到达 `@RestControllerAdvice`。	检查项目中是否定义了自定义的 `HandlerExceptionResolver`。如果是，确保它的优先级低于 `ExceptionHandlerExceptionResolver`，后者负责处理 `@ExceptionHandler` 注解的方法。可以通过实现 `Ordered` 接口或使用 `@Order` 注解来设置 `HandlerExceptionResolver` 的优先级。
2.7 使用了 `ResponseEntityExceptionHandler`	`ResponseEntityExceptionHandler` 是 Spring MVC 提供的一个便捷类，用于处理一些常见的 Spring MVC 异常。如果你的 `@RestControllerAdvice` 继承了 `ResponseEntityExceptionHandler`，并且重写了其方法，可能会导致自定义的异常处理逻辑不生效。	避免直接继承 `ResponseEntityExceptionHandler`，除非你完全理解其工作原理。如果需要自定义异常处理逻辑，可以考虑使用 `@ExceptionHandler` 注解，或者自定义 `HandlerExceptionResolver`。
2.8 事务回滚导致异常被吞噬	在事务方法中抛出异常时，如果配置了事务回滚，可能会导致异常被事务管理器吞噬，从而无法被 `@RestControllerAdvice` 捕获。	确保事务配置正确，并且事务回滚不会吞噬异常。可以尝试将 `@Transactional` 注解放在 Controller 层，而不是 Service 层，或者在 Service 层捕获异常并重新抛出。
2.9 异步方法中的异常处理	在异步方法（使用 `@Async` 注解）中抛出的异常，不会被 `@RestControllerAdvice` 直接捕获。	需要使用 `AsyncUncaughtExceptionHandler` 来处理异步方法中的异常。可以实现 `AsyncConfigurer` 接口，并重写 `getAsyncUncaughtExceptionHandler()` 方法，返回自定义的 `AsyncUncaughtExceptionHandler` 实例。

3. 详细代码示例及问题分析

下面我们通过几个具体的代码示例来演示上述问题，并给出相应的解决方案。

3.1 包扫描问题

问题代码：

// com.example.demo.controller
@RestController
public class MyController {

    @GetMapping("/test")
    public String test() {
        throw new NullPointerException("测试空指针异常");
    }
}

// com.example.exception
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(value = {NullPointerException.class})
    public ResponseEntity<String> handleNullPointerException(NullPointerException ex) {
        System.err.println("NullPointerException 发生: " + ex.getMessage());
        return new ResponseEntity<>("空指针异常，请检查代码！", HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

在这个例子中，MyController 和 GlobalExceptionHandler 位于不同的包中。如果 Spring Boot 应用主类所在的包是 com.example.demo，那么 com.example.exception 包就不会被扫描到，导致 GlobalExceptionHandler 不生效。

解决方案：

将 GlobalExceptionHandler 移动到 com.example.demo 包或其子包中。
在 Spring Boot 应用主类上使用 @ComponentScan 注解显式指定要扫描的包：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.demo", "com.example.exception"})
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

3.2 异常被 Controller 内部捕获

问题代码：

@RestController
public class MyController {

    @GetMapping("/test")
    public String test() {
        try {
            throw new NullPointerException("测试空指针异常");
        } catch (NullPointerException e) {
            System.err.println("Controller 内部捕获到异常: " + e.getMessage());
            return "Controller 内部处理了异常";
        }
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(value = {NullPointerException.class})
    public ResponseEntity<String> handleNullPointerException(NullPointerException ex) {
        System.err.println("NullPointerException 发生: " + ex.getMessage());
        return new ResponseEntity<>("空指针异常，请检查代码！", HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

在这个例子中，MyController 内部使用了 try-catch 语句捕获了 NullPointerException，并进行了处理。因此，异常没有传播到 GlobalExceptionHandler。

解决方案：

在 catch 块中重新抛出异常：

@RestController
public class MyController {

    @GetMapping("/test")
    public String test() {
        try {
            throw new NullPointerException("测试空指针异常");
        } catch (NullPointerException e) {
            System.err.println("Controller 内部捕获到异常: " + e.getMessage());
            throw e; // 重新抛出异常
        }
    }
}

将异常转换为运行时异常并抛出：

@RestController
public class MyController {

    @GetMapping("/test")
    public String test() {
        try {
            throw new NullPointerException("测试空指针异常");
        } catch (NullPointerException e) {
            System.err.println("Controller 内部捕获到异常: " + e.getMessage());
            throw new RuntimeException(e); // 转换为运行时异常并抛出
        }
    }
}

3.3 @ExceptionHandler 方法参数不匹配

问题代码：

@RestController
public class MyController {

    @GetMapping("/test")
    public String test() {
        throw new NullPointerException("测试空指针异常");
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(value = {IllegalArgumentException.class})
    public ResponseEntity<String> handleNullPointerException(NullPointerException ex) { // 参数类型不匹配
        System.err.println("NullPointerException 发生: " + ex.getMessage());
        return new ResponseEntity<>("空指针异常，请检查代码！", HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

在这个例子中，@ExceptionHandler 方法的参数类型是 IllegalArgumentException，而抛出的异常类型是 NullPointerException，两者不匹配。

解决方案：

修改 @ExceptionHandler 方法的参数类型为 NullPointerException 或其父类 Exception：

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(value = {NullPointerException.class})
    public ResponseEntity<String> handleNullPointerException(NullPointerException ex) {
        System.err.println("NullPointerException 发生: " + ex.getMessage());
        return new ResponseEntity<>("空指针异常，请检查代码！", HttpStatus.INTERNAL_SERVER_ERROR);
    }

    // 或者
    @ExceptionHandler(value = {Exception.class})
    public ResponseEntity<String> handleException(Exception ex) {
        System.err.println("Exception 发生: " + ex.getMessage());
        return new ResponseEntity<>("服务器内部错误！", HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

4. 其他排查技巧

日志： 在 @ExceptionHandler 方法中添加详细的日志，可以帮助你了解异常是否被捕获，以及异常处理逻辑是否正确执行。
调试： 使用调试器可以单步执行代码，查看异常传播的过程，以及 @ExceptionHandler 方法的调用情况。
Spring Boot Actuator： Spring Boot Actuator 提供了 /actuator/mappings 端点，可以查看 Spring MVC 的请求映射信息，包括异常处理器的映射。
检查依赖冲突： 确保项目中没有依赖冲突，特别是 Spring MVC 相关的依赖。
升级 Spring Boot 版本： 如果你使用的是较旧的 Spring Boot 版本，可以尝试升级到最新版本，以修复可能存在的 Bug。

5. 总结

@RestControllerAdvice 不生效的原因有很多，需要仔细排查。一般来说，可以按照以下步骤进行排查：

检查包扫描： 确保 @RestControllerAdvice 类所在的包在 Spring Boot 的扫描范围内。
检查异常捕获： 确保 Controller 中没有过度捕获异常。
检查参数匹配： 确保 @ExceptionHandler 方法的参数类型与抛出的异常类型一致。
检查 Bean 管理： 确保 @RestControllerAdvice 类被 Spring 容器管理。
检查 AOP 拦截器： 确保 AOP 拦截器不会过度捕获异常。
检查 HandlerExceptionResolver： 确保自定义的 HandlerExceptionResolver 的优先级低于 ExceptionHandlerExceptionResolver。
检查事务配置： 确保事务回滚不会吞噬异常。
检查异步方法： 使用 AsyncUncaughtExceptionHandler 处理异步方法中的异常。

通过以上步骤，你应该能够找到 @RestControllerAdvice 不生效的原因，并采取相应的解决方案。

异常处理是提高系统稳定性和用户体验的重要手段，希望今天的分享能够帮助大家更好地理解和使用 @RestControllerAdvice。

Spring Boot 异常统一处理 @RestControllerAdvice 不生效原因解析

发表回复 取消回复

发表回复取消回复