Spring Boot 处理 Starter 异常的关键是确保其穿透至 MVC 异常处理链：异常类需在主应用类路径可见，必须实际抛出至调用链，且主应用需配置有效的 @RestControllerAdvice 或 /error 转发机制。
Spring Boot 处理自定义 Starter 中抛出的底层框架异常，关键不在于“Starter 本身捕获异常”，而在于**异常能否穿透到 Spring MVC 的统一异常处理链路中，并被正确识别和响应**。Starter 本质是自动装配组件，它不直接参与 Web 层异常拦截；真正起作用的是你项目里已配置的全局异常处理器（如 @RestControllerAdvice）和 Spring Boot 内置的错误机制。
确保异常能被上层捕获的三个前提
自定义 Starter 抛出的异常要被项目正常处理，必须满足：
-
异常类型需在项目类路径下可见：Starter 中定义的异常类（如
MyServiceException）必须被主应用依赖并加载；建议将异常类放在 starter 的-common或-api模块中，避免仅存在于 autoconfigure 模块导致类加载失败。 -
异常必须实际抛出到 Controller 或 Service 调用链中：Starter 内部调用第三方 SDK（如 MinIO、XX 支付网关）时，若只做日志记录或静默吞掉异常（
try-catch + log），上层永远收不到；应主动包装并 re-throw，例如：throw new MyServiceException("上传文件失败", e); -
主应用已启用并正确配置全局异常处理器：不能只依赖 Starter 自带的
@ControllerAdvice（它可能因包扫描范围未覆盖而失效），推荐在主应用的com.example.app包下定义自己的GlobalExceptionHandler，并明确处理 Starter 异常类型。
两种主流处理方式及适用场景
方式一：用 @RestControllerAdvice 直接拦截 Starter 异常（推荐用于 REST API）
在主应用中编写处理器，支持 JSON 响应格式：
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(MyServiceException.class)
public ResponseEntity<Result> handleMyServiceException(MyServiceException e) {
return ResponseEntity.status(400).body(Result.fail(e.getCode(), e.getMessage()));
}
@ExceptionHandler(HttpClientErrorException.class)
public ResponseEntity<Result> handleHttpClientError(HttpClientErrorException e) {
return ResponseEntity.status(e.getStatusCode().value())
.body(Result.fail("HTTP_CALL_FAILED", e.getLocalizedMessage()));
}
}
优点：响应结构统一、适配微服务调用；缺点：对浏览器访问返回纯 JSON，不友好。
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
方式二：转发至 /error 并复用 Spring Boot 默认错误页（适合混合访问场景）
当 Starter 异常需要区分客户端类型（浏览器 → HTML，App → JSON）时，可让异常处理器转发到内置 /error：
@ExceptionHandler(MyServiceException.class)
public String handleMyServiceException(MyServiceException e, HttpServletRequest request) {
request.setAttribute("javax.servlet.error.status_code", 500);
request.setAttribute("javax.servlet.error.message", e.getMessage());
return "forward:/error";
}
再配合自定义错误页面（如 resources/public/error/500.html）或实现 ErrorController，即可实现自适应渲染。
避免常见陷阱
以下情况会导致 Starter 异常“消失”或处理失败：
-
Starter 中使用了 @Async 方法但未配置异常传播：异步方法内抛出异常默认被
ThreadPoolTaskExecutor吞掉，需通过setWaitForTasksToCompleteOnShutdown(true)或自定义AsyncUncaughtExceptionHandler捕获。 -
异常被 Starter 内部的 RetryTemplate 或 CircuitBreaker 拦截：如使用 Resilience4j，需检查
ignoreExceptions配置是否误将业务异常加入忽略列表。 -
spring.factories 中未正确声明自动配置类：若 Starter 的
MyAutoConfiguration没在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports（Spring Boot 3.2+）中注册，其内部@Bean和异常类可能未加载，间接导致异常无法识别。
本质上，Starter 只负责“抛”，项目负责“接”。只要异常类型可达、调用链畅通、处理器存在且生效，Spring Boot 就能按标准流程处理——无需为 Starter 单独设计一套异常体系。
