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

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

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

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

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

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

1. 包结构是否合理？
   假设你的主启动类为：

   package com.example.myapp;
   @SpringBootApplication
   public class MyAppApplication { ... }

   那么 GeneralExceptionHandler 必须位于 com.example.myapp 或其任意子包下（如 com.example.myapp.advice），否则将被忽略。

   

   红墨

   一站式小红书图文生成器

   下载

2. 若必须跨包，显式配置扫描路径：
   在启动类上补充 @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