SpringBoot异常未捕获排查方法

编程并不是一个机械性的工作，而是需要有思考，有创新的工作，语法是固定的，但解决问题的思路则是依靠人的思维，这就需要我们坚持学习和更新自己的知识。今天golang学习网就整理分享《Spring Boot 全局异常未捕获排查指南》，文章讲解的知识点主要包括，如果你对文章方面的知识点感兴趣，就不要错过golang学习网，在这可以对大家的知识积累有所帮助，助力开发能力的提升。

本文详解为何 `@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