外观
14 - DispatcherServlet 调度全流程:一次请求如何找到 Controller
适用版本:Spring Framework 6.x、Spring MVC 6.x。
前置阅读:01 - 从 refresh() 读懂 Spring和02 - 一个 @Component 如何变成 BeanDefinition。本文从请求已经到达 Servlet 容器开始,不替代网络、网关和 TLS 排障。
摘要
Controller(控制器)中有一个方法,不代表任意请求都能调用它。请求先要进入正确的 Servlet,再满足路径、HTTP 方法和媒体类型等映射条件,之后才会准备参数并执行业务方法。404、405、415 等状态提示的失败方向不同,不能都归因于“Controller 没注册”。
本文以普通同步请求为基本模型,围绕 DispatcherServlet#doDispatch() 的调度职责,解释请求如何找到处理器、如何调用它,以及在哪一层排查失败。异步分派和流式响应的特殊流程见25 - Spring MVC 异步请求与流式响应。
1. 场景:方法存在,为什么请求仍是 404
下面是映射声明示意;Order、CreateOrder 和方法体用占位内容表示,不能直接编译运行:
java
@RestController
@RequestMapping("/orders")
class OrderController {
@PostMapping(consumes = "application/json")
Order create(@RequestBody CreateOrder request) { return ...; }
}这个方法声明接受 POST /orders,并通过 consumes 限定请求体的媒体类型为 application/json。媒体类型描述内容格式,由请求头 Content-Type 表达。
调用 GET /api/orders 时,需要先弄清 /api 的含义:它可能是网关转发时移除的前缀,也可能是应用的 Context Path(上下文路径,即应用在容器中的路径前缀)。Servlet 映射则决定容器把哪类请求交给 DispatcherServlet。这些配置没有厘清,就不能只凭地址判断 Controller 路径是否匹配。
如果请求已进入 MVC,且路径匹配到该方法的候选映射,但 HTTP 方法是 GET,常见结果是 405,而不是 404;如果路径本身不匹配,则应沿 404 的方向排查。先区分“请求没到应用”“没进入 DispatcherServlet”“映射条件不满足”,再分析具体状态码。
2. 核心调度链
DispatcherServlet 是 Front Controller(前端控制器):作为 Spring MVC 的统一调度入口,它把查找和执行委托给专门组件。先记住三个角色:
- Handler(处理器):实际处理请求的对象;注解控制器中通常表示为
HandlerMethod,它关联控制器对象与具体方法。 - HandlerMapping(处理器映射):根据请求条件查找处理器。
- HandlerAdapter(处理器适配器):按处理器的类型组织调用,避免调度入口依赖某一种处理器实现。
下面展示注解控制器正常处理请求的主线,省略异常和异步分支:
图表将在阅读到此处时加载…
其中 HandlerExecutionChain(处理器执行链)包含选中的处理器和适用的拦截器。ReturnValueHandler(返回值处理器)解释方法返回值;返回对象并不等于响应已经写完。
实际请求链还应区分 Servlet 与 Spring MVC 两层:
text
Servlet Container
→ Filter Chain(含可能存在的 Spring Security Filter Chain)
→ DispatcherServlet
→ HandlerMapping
→ HandlerInterceptor
→ HandlerAdapter
→ ControllerFilter(Servlet 过滤器)在 DispatcherServlet 外围执行,可以阻止请求进入 MVC。Interceptor(MVC 拦截器)在处理器已选出后,围绕处理器调用执行,因此能接触到选中的处理器信息。AOP(面向切面编程)则通常围绕容器 Bean 的方法调用添加行为。三者都能做鉴权、日志或限流,但执行位置不同,排障时应确认请求停在哪个入口。
3. HandlerMapping:谁处理这个请求
注解控制器主要由 RequestMappingHandlerMapping 管理。启动时,它识别 Controller 方法上的映射声明,将路径、HTTP 方法、参数、请求头及媒体类型等条件注册起来。请求到达后,再用实际请求与这些条件比较。
这些条件各有用途:params 限定请求参数,headers 限定请求头,consumes 限定可接收的请求媒体类型,produces 限定可生成的响应媒体类型。客户端通过 Accept 请求头表达可接受的响应格式。因此,路径相同也不代表映射相同。
相同映射条件注册到多个方法时,通常会在启动阶段报告歧义,因为框架无法唯一确定对应方法。运行时则根据请求条件选择最匹配的 HandlerMethod;排查时既要看方法是否已注册,也要看请求满足哪些条件。
基本映射规则清楚后,再检查版本和路径策略。PathPatternParser 用于解析路径模式,AntPathMatcher 是另一种路径匹配实现。Spring 6 的路径模式、尾斜杠匹配、URL 解码和路径参数处理与旧版配置可能不同,Spring Boot 的 MVC 配置也可能影响匹配策略。升级后出现路径行为变化时,应核对目标 Spring/Boot 小版本和实际 PathPatternParser 配置,不要直接套用旧配置下的结论。
4. HandlerAdapter:怎样调用它
找到处理器只回答了“谁处理”,还没有回答“怎样调用”。DispatcherServlet 不假设所有处理器都是 Controller 方法,而是通过支持该处理器类型的 HandlerAdapter 执行它。
注解控制器通常由 RequestMappingHandlerAdapter 处理。适配器组织参数解析、数据绑定、方法调用和返回值处理:先把路径变量、查询参数、请求体等转换成方法参数,再调用方法,最后处理返回结果。数据绑定指把外部输入转换并填入目标对象。参数准备失败时,即使映射成功,业务方法也可能尚未执行。
5. 拦截器执行顺序
对普通同步请求,可以先按三个回调理解拦截器:preHandle 在处理器执行前决定是否继续,postHandle 在处理器正常执行后提供后置处理,afterCompletion 用于请求处理完成后的清理。
视图渲染与响应体写出的位置不同:
text
视图流程:preHandle -> HandlerAdapter 调用 Controller -> postHandle -> 视图渲染 -> afterCompletion
响应体流程:preHandle -> HandlerAdapter 调用 Controller 并处理/写出响应体 -> postHandle -> afterCompletion因此,不应把 postHandle 当成所有接口写响应之前的统一修改点。返回值如何写成 JSON,见16 - 返回值、JSON 与统一异常处理。
若 preHandle 返回 false,后续处理器不执行;该返回值本身不能说明客户端最终收到哪个状态码,还要检查拦截器是否写了响应。发生异常时,postHandle 未必执行,afterCompletion 的回调范围则与哪些拦截器的 preHandle 已成功完成有关。异常发生位置和异步分派会影响完整顺序,不能把正常流程直接套到所有请求。
如果请求在 Filter 中被拒绝,MVC Interceptor 和 @ControllerAdvice(集中提供控制器异常处理等能力的组件)通常没有机会处理它。Spring Security 的认证、授权和异常转换也主要发生在 Filter Chain。看到 401/403 时,应先确认响应由网关、Security Filter 还是 Controller 产生。
6. 最小映射示例
下面是读取订单的控制器片段,省略 Spring Web 注解的导入。它需要注册到启用 Spring MVC 的应用中;@PathVariable long id 未显式指定变量名,需确保编译产物包含参数名元数据:
java
@RestController
@RequestMapping("/orders")
class OrderController {
@GetMapping("/{id}")
OrderView get(@PathVariable long id) {
return new OrderView(id, "CREATED");
}
record OrderView(long id, String status) { }
}在没有额外路径前缀、请求未被过滤器或拦截器阻止的条件下,GET /orders/42 预期匹配 get 方法。路径中的 42 随后转换为 long id,方法返回 OrderView。JSON 写出还依赖支持该返回类型的消息转换器。
后续两篇讨论创建订单,使用的是另一条 POST 请求,对应第 1 节的创建映射,而不是上面的 GET 方法:
http
POST /orders?notify=true
Content-Type: application/json
Accept: application/json
{"productCode":"P-100","quantity":2}对于这条请求,映射阶段先检查 POST、/orders 和 JSON 媒体类型等条件;查询参数 notify=true 是否参与映射,取决于方法是否声明相应的 params 条件。匹配成功后,参数如何生成见15 - Controller 参数解析与数据绑定,返回对象如何写成 JSON 见16 - 返回值、JSON 与统一异常处理。
7. 404、405、415、406 的方向不同
| 状态 | 常见含义 | 优先检查 |
|---|---|---|
| 404 | 路径或 Handler 不匹配 | Context Path、Servlet Path、映射路径 |
| 405 | HTTP Method 不支持 | GET/POST/PUT 等 |
| 415 | 请求媒体类型不支持 | Content-Type、consumes、Converter |
| 406 | 无法生成可接受响应 | Accept、produces、Converter |
| 400 | 请求已匹配但参数不可读或校验失败 | 参数来源、JSON、类型转换、校验 |
| 500 | Handler 执行或响应处理失败 | 业务异常、序列化、异常解析 |
表中的 Converter 指 HttpMessageConverter(HTTP 消息转换器),负责把请求体读成对象或把对象写入响应体。415、406 既可能与映射的媒体类型条件有关,也可能与后续转换器能力有关,不能只看路径是否匹配。
这些状态是排查线索,不能单独证明失败位置。统一异常处理、错误页和网关都可能改写状态码,必须结合应用访问日志、选中的处理器及异常类型确认实际链路。
8. 容易踩的坑
下面几类误判尤其容易让排查走偏:
- 把源代码当成注册结果:Controller 不在扫描范围时,方法虽然存在,运行中的映射表却没有它。
- 只确认“有 Handler”,不确认类型:静态资源处理或其他
HandlerMapping可能匹配请求;应确认选中的是否为目标 Controller 方法,并检查映射组件的顺序。 - 把提前终止当成映射失败:Filter 或拦截器可能直接写响应,也可能终止处理;Controller 未执行不能证明它未注册。
- 忽略环境差异:网关前缀、上下文路径、Servlet 映射和路径匹配策略都属于实际请求条件,不能仅凭本地能访问就推断线上地址正确。
9. 排障清单
- 请求是否到达当前实例?
- DispatcherServlet 映射路径是什么?
- 运行中的映射表是否存在目标 Handler?使用 Spring Boot Actuator(运行状态与管理端点组件)时,可查看已启用并暴露的
mappings端点;开放端点前需做好鉴权。 - Path、Method、Params、Headers、Consumes、Produces 哪项不匹配?
- Filter 或 Interceptor 是否提前终止请求?
- 异常是否被网关或统一错误页改写?
- 响应由 Filter、Security、DispatcherServlet 还是 Controller 写出?
- 目标版本使用的路径匹配策略和 URL 解码规则是什么?
10. 最小验证方法
MockMvc 是 Spring MVC 的模拟请求测试工具,可以在不启动真实 HTTP 服务的情况下测试映射、参数和响应。下面是测试方法中的片段,需要已有的 mockMvc 测试实例、相应导入和注册好的 POST 订单接口;第 6 节的 GET 控制器不能满足此断言:
java
mockMvc.perform(post("/orders")
.queryParam("notify", "true")
.contentType(MediaType.APPLICATION_JSON)
.accept(MediaType.APPLICATION_JSON)
.content("""
{"productCode":"P-100","quantity":2}
"""))
.andExpect(status().isOk());在创建接口接受这份 JSON、相关依赖齐全且正常返回 200 的前提下,预期结果是 isOk() 断言通过。这个断言只检查状态码:若要证明请求调用了目标方法,还应检查匹配的处理器;要证明响应正确,则应继续检查响应头和响应体。
MockMvc 不等于真实网关和网络链路,Filter 覆盖范围也取决于测试配置。若问题涉及 Servlet 容器映射、真实 Filter 顺序、编码、压缩或连接中断,应补充随机端口集成测试或实际 HTTP 请求,验证真实容器与部署链路。
11. 总结
Spring MVC 找 Controller 不是只匹配 URL,而是匹配一组完整请求条件,再由 HandlerAdapter 执行。
- DispatcherServlet 负责调度,不直接承担所有解析工作。
- HandlerMapping 决定“谁处理”,HandlerAdapter 决定“如何调用”。
- 排查接口问题要先区分网络、Servlet、映射和方法执行四个层次。
阅读导航
- Controller 如何注册:02 - 一个 @Component 如何变成 BeanDefinition
- 参数如何生成:15 - Controller 参数解析与数据绑定
- 返回值与异常如何写出:16 - 返回值、JSON 与统一异常处理
- 异步分派与流式写出:25 - Spring MVC 异步请求与流式响应
- 网关错误与上游改写:网络 15 - 反向代理与网关错误
- 超时与重试边界:网络 17 - 网络超时与重试
- 跨层排障入口:20 - Spring 线上问题排查手册