Spring Boot 2023.0.1升级后@ExceptionHandler映射冲突问题

将Spring Boot微服务从2021.0.9版本迁移至2023.0.1版本后，启动时出现异常处理冲突报错。该微服务依赖一个提供通用异常处理的共享库，两者均定义了处理Exception.class的全局异常处理器。

微服务异常处理器代码 #

import org.springframework.core.annotation.Order;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@ControllerAdvice
@Order(Integer.MAX_VALUE)
public class CommonControllerAdvice extends ResponseEntityExceptionHandler {

  private static final String LABEL = "Label";

  @ExceptionHandler(Exception.class)
  public final ResponseEntity<Object> handleHystrixBadRequestException(
    // 省略方法实现
    return null;
  }
}

共享库异常处理器代码 #

import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@ControllerAdvice
@Order(Integer.MAX_VALUE)
public class CommonControllerAdvice extends ResponseEntityExceptionHandler {
  
  @ExceptionHandler(Exception.class)
  public final ResponseEntity<Object> handleException(Exception ex) {
    // 省略方法实现
    return null;
  }
}

Error creating bean with name 'handlerExceptionResolver' defined in class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$EnableWebMvcConfiguration.class]: Failed to instantiate [org.springframework.web.servlet.HandlerExceptionResolver]: Factory method 'handlerExceptionResolver' threw exception with message: Ambiguous @ExceptionHandler method mapped for [class java.lang.Exception]: {public final org.springframework.http.ResponseEntity com.atlas.mpp.transaction.search.web.rest.SearchControllerAdvice.handleHystrixBadRequestException(java.lang.Exception), public final org.springframework.http.ResponseEntity com.error.web.handlers.CommonControllerAdvice.handleException(java.lang.Exception)}
.........
Failed to instantiate [org.springframework.web.servlet.HandlerExceptionResolver]: Factory method 'handlerExceptionResolver' threw exception with message: Ambiguous @ExceptionHandler method mapped for [class java.lang.Exception]: {public final org.springframework.http.ResponseEntity com.microservice.SearchControllerAdvice.handleHystrixBadRequestException(java.lang.Exception), public final org.springframework.http.ResponseEntity com.lib.web.handlers.CommonControllerAdvice.handleException(java.lang.Exception)}
.......
Ambiguous @ExceptionHandler method mapped for [class java.lang.Exception]: {public final org.springframework.http.ResponseEntity com.microservice.web.rest.SearchControllerAdvice.handleHystrixBadRequestException(java.lang.Exception), public final org.springframework.http.ResponseEntity com.lib.web.handlers.CommonControllerAdvice.handleException(java.lang.Exception)}

Spring Boot 2023.0.x对应的Spring Framework 6.0+版本，对全局异常处理器的冲突检测做了更严格的校验。在旧版本（2021.0.9对应Spring 5.3.x）中，同优先级（两者均设置@Order(Integer.MAX_VALUE)）的处理器处理同一异常类型时不会触发报错，但新版本会明确识别这种歧义并阻止应用启动。

• 调整优先级顺序：给两个@ControllerAdvice设置不同的@Order值，数值越小优先级越高。例如给共享库的处理器设置@Order(1)，微服务的处理器设置@Order(2)，确保优先级高的处理器先处理异常，避免歧义。
• 缩小异常处理范围：避免两个处理器都处理最宽泛的Exception.class。将微服务的处理器改为只处理特定异常（比如HystrixBadRequestException），修改@ExceptionHandler(HystrixBadRequestException.class)，共享库处理器保留通用异常处理逻辑，从根源上消除冲突。
• 合并或排除处理器：如果微服务的异常处理逻辑是共享库的补充，可将微服务的逻辑合并到共享库中；或者在微服务中排除共享库的CommonControllerAdvice，比如通过@ComponentScan(excludeFilters = @Filter(type = FilterType.ASSIGNABLE_TYPE, classes = CommonControllerAdvice.class))，只保留自身的处理器。
• 指定优先Bean：在其中一个CommonControllerAdvice类上添加@Primary注解，告知Spring在出现歧义时优先选择该Bean。注意此方式需确保业务逻辑符合预期，避免异常处理被意外覆盖。

内容的提问来源于stack exchange，提问作者Peter Penzov