未知端点路径下@ExceptionHandler无法捕获HandlerInterceptor异常

云原生阿岚

2026-9-3

问题根因

Spring MVC的请求处理链路存在明确的阶段划分，@ControllerAdvice配合@ExceptionHandler的异常处理机制有固定的生效范围，该现象本质是不同请求场景下handler类型差异导致的异常处理链路断裂：

HandlerInterceptor.preHandle的执行时机是HandlerMapping完成请求匹配之后，不管请求路径是否存在，只要拦截器配置的路径规则命中当前请求，preHandle方法就会执行。
负责解析@ExceptionHandler的ExceptionHandlerExceptionResolver，仅对匹配到@Controller/@RequestMapping标注的接口方法（即HandlerMethod类型的handler）链路产生的异常生效，包括对应Controller执行前、执行中、执行后关联的拦截器抛出的异常。

当请求有效API路径时，HandlerMapping匹配到的handler是HandlerMethod类型，拦截器抛出的异常会被DispatcherServlet统一捕获，交给异常解析器链处理，因此@ExceptionHandler可以正常触发，返回自定义的400响应。

当请求不存在的路径时：

RequestMappingHandlerMapping匹配不到任何Controller接口方法，会返回兜底handler（通常是静态资源处理器、默认Servlet转发处理器），这类handler不属于HandlerMethod类型。
拦截器照常执行并抛出异常后，ExceptionHandlerExceptionResolver识别到当前handler不是自己支持处理的HandlerMethod类型，会直接跳过异常处理，异常会沿着调用链向上抛给底层Servlet容器。
异常提前抛出直接打断了Spring MVC原本的404处理流程——默认的404响应需要在所有handler执行完成、确认无匹配接口后才会触发，流程中断后既不会返回404，也不会走到任何@ExceptionHandler的逻辑，最终由Servlet容器返回默认的500错误响应。

可行修复方案

最常用的方案：在拦截器的参数校验逻辑前加类型判断，仅对匹配到Controller接口的请求做自定义校验，非接口请求直接放行，让框架走原本的静态资源处理、404处理逻辑：

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
    // 静态资源、不存在路径的兜底请求直接放行，不做自定义头校验
    if (!(handler instanceof HandlerMethod)) {
        return true;
    }
    String parameter = request.getHeader("parameter123");
    if (StringUtils.isEmpty(parameter)) {
        throw new IllegalArgumentException("parameter123 not specified");
    }
    // [...] 其余业务逻辑
    return true;
}

如果要求所有请求（包括不存在的路径）都必须校验指定请求头，不要在拦截器中直接抛出异常，手动设置响应状态、写入格式化响应体后直接return false截断请求流程，避免异常抛到Servlet容器层面。
如果需要全局兜底所有场景的异常，可以自定义HandlerExceptionResolver实现类注册到Spring容器，或者通过Servlet容器的错误页配置统一处理未被Spring MVC捕获的异常。

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