SpringBoot自定义认证异常处理技巧

本文深入剖析了 Spring Boot 中自定义 `AuthenticationException` 子类（如 `CustomAuthenticationException`）无法被 `@ExceptionHandler` 正确捕获的底层机制——根源在于 Spring 异常处理依赖严格类型匹配而非 Java 多态，即使子类继承父类，若未显式声明对应处理器，其语义化错误消息就会被覆盖或丢失；文章不仅揭示这一常见误区，更提供可落地的全局异常处理方案：通过为自定义异常单独注册 `@ExceptionHandler` 方法并直接透传 `ex.getMessage()`，确保客户端精准接收“Password is not correct”等业务级提示，同时兼顾可扩展性与调试友好性，真正让安全异常既健壮又人性化。

本文详解 Spring Boot 中自定义 `AuthenticationException` 子类（如 `CustomAuthenticationException`）未被 `@ExceptionHandler` 捕获的根本原因，并提供精准匹配的全局异常处理方案，确保客户端收到预期的、语义明确的错误提示。

在 Spring Security 应用中，开发者常通过继承 AuthenticationException 创建自定义异常（如 CustomAuthenticationException），以传递更具体的业务语义（例如 "Password is not correct"）。然而，一个常见误区是：仅注册父类 AuthenticationException 的异常处理器，却期望其能自动转发子类异常的原始消息。实际上，Spring 的 @ExceptionHandler 是基于精确类型匹配（而非向上转型隐式匹配）执行的——即使 CustomAuthenticationException 是 AuthenticationException 的子类，若未显式声明对应处理器，Spring 将跳过该异常，转而尝试匹配更通用的处理器（如默认的 ResponseEntityExceptionHandler），最终导致消息被覆盖或丢失。

要解决此问题，必须为自定义异常类型单独注册 @ExceptionHandler 方法。以下是推荐的完整实践：

✅ 正确的全局异常处理器配置

@RestControllerAdvice
public class AuthControllerAdvice extends ResponseEntityExceptionHandler {

    // ✅ 处理自定义认证异常：保留原始 message
    @ExceptionHandler(CustomAuthenticationException.class)
    public ResponseEntity