Spring Boot NoHandlerFoundException自定义响应失效报异常映射歧义

核心报错根因 #

程序抛出java.lang.IllegalStateException: Ambiguous @ExceptionHandler method mapped的本质原因是异常处理映射冲突：

• 当前全局异常类GlobalExceptionHandlingController继承了Spring MVC内置的ResponseEntityExceptionHandler，该父类本身已经内置了针对NoHandlerFoundException的处理方法，方法上已经标注了对应的@ExceptionHandler映射规则
• 开发者在子类中新增了一个额外的、标注了@ExceptionHandler(NoHandlerFoundException.class)的同名处理方法，没有匹配父类方法的重写规则，导致Spring容器扫描到同一个异常类存在两个可匹配的处理逻辑，无法确定该调用哪个方法，最终触发歧义报错。

分步修复操作 #

1. 解决异常映射冲突 #

有两种可选的实现方式，任选其一即可：

• 方式一：保留继承ResponseEntityExceptionHandler的逻辑，正确重写父类方法

  • 移除自定义方法上的@ExceptionHandler(NoHandlerFoundException.class)注解——该注解会让Spring把这个方法当成独立的新增映射，和父类的内置处理方法形成重复
  • 匹配父类方法的完整签名，通过@Override注解确保是正确的方法重写，而非新增方法
    示例正确代码：

  @ControllerAdvice
  public class GlobalExceptionHandlingController extends ResponseEntityExceptionHandler {
  
      @Override
      protected ResponseEntity<Object> handleNoHandlerFoundException(
              NoHandlerFoundException ex,
              HttpHeaders headers,
              HttpStatus status,
              WebRequest request) {
          
          HashMap<String, String> responseBody = new HashMap<>();
          // 用异常对象携带的请求URI获取实际访问路径，替代原代码无法获取完整路径的request.getContextPath()
          responseBody.put("path", ex.getRequestURI());
          responseBody.put("message", "Invalid Endpoint");
          // 按照需求返回405 METHOD_NOT_ALLOWED状态码，替代默认的404
          return new ResponseEntity<>(responseBody, HttpStatus.METHOD_NOT_ALLOWED);
      }
  }
  

  注：如果需要完全匹配需求中的提示文本，只需将responseBody中message对应的value改为"invalid endpoint"即可。

• 方式二：移除ResponseEntityExceptionHandler的继承关系

  • 直接去掉类上的extends ResponseEntityExceptionHandler声明，此时不存在父类的内置映射逻辑，自定义方法上的@ExceptionHandler(NoHandlerFoundException.class)注解可以正常生效，不会触发歧义报错，代码逻辑和原实现保持一致即可。

2. 核对配置项有效性 #

确保之前在application.properties中配置的规则可以正常触发NoHandlerFoundException：

• 确认配置spring.mvc.throw-exception-if-no-handler-found=true已正确添加，确保无对应处理器的请求会抛出异常而非返回默认404
• 确认静态资源映射已关闭：老版本Spring Boot使用spring.resources.add-mappings=false，Spring Boot 2.4+版本需使用spring.web.resources.add-mappings=false，避免静态资源映射拦截请求，导致异常无法触发
• 确认服务端错误白页已关闭server.error.whitelabel.enabled=false，避免默认错误页拦截自定义响应

3. 效果验证 #

完成修复后可通过以下场景验证逻辑：

• 访问正确接口http://localhost:8080/api/trains，业务逻辑正常响应
• 访问无效路径（如/api/trai、/api/train、/api），将返回符合预期的响应：HTTP状态码405，响应体携带message:"invalid endpoint"的自定义内容，无默认404错误提示。

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