Spring Boot 全局异常处理器未捕获自定义异常的排查与正确配置指南_网络技术

Spring Boot 全局异常处理器未捕获自定义异常的排查与正确配置指南

发布时间 - 2025-12-31 00:00:00 点击率：次

本文详解为何 `@controlleradvice` 无法捕获自定义 `apiexception`，重点指出包扫描范围缺失这一常见原因，并提供完整、可落地的配置方案与最佳实践。

在 Spring Boot 应用中，使用 @ControllerAdvice + @ExceptionHandler 实现全局异常统一处理是标准做法。但许多开发者会遇到“自定义异常未被拦截”的问题——如你所见，ApiException 明确声明了 @ExceptionHandler(ApiException.class)，却始终未触发。根本原因通常并非逻辑错误，而是 Spring 容器未能成功注册该异常处理器类。

✅ 正确配置的关键：确保组件可被扫描

@ControllerAdvice 是一个 @Component 衍生注解，其生效前提是该类必须被 Spring 的组件扫描机制（@ComponentScan）发现。默认情况下，Spring Boot 主启动类上的 @SpringBootApplication 仅扫描其所在包及子包下的组件。

因此，请严格检查以下两点：

包结构是否合理？
假设你的主启动类为：
```
package com.example.myapp;
@SpringBootApplication
public class MyAppApplication { ... }
```
那么 GeneralExceptionHandler 必须位于 com.example.myapp 或其任意子包下（如 com.example.myapp.advice），否则将被忽略。

若必须跨包，显式配置扫描路径：
在启动类上补充 @ComponentScan：

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.myapp", "com.example.common.exception"})
public class MyAppApplication { ... }

⚠️ 其他易忽略的细节

移除 static 修饰符：@ExceptionHandler 方法不能是 static —— 这是硬性限制！你的代码中 public static ResponseEntity

@ExceptionHandler(ApiException.class)
public ResponseEntity