1. 所有请求的汇聚点DispatcherServlet在SpringMVC中的真正职责做了这么多年Java服务端开发我对SpringMVC的印象总结起来就是一句话它把一次HTTP请求变成了一次有秩序的分发过程而DispatcherServlet就是这个过程的指挥官。很多刚接触框架的同事会觉得加个RestController、写个方法就能出结果根本不用关心DispatcherServlet。可一旦遇到404、参数解析不对、视图找不到、异常被吞掉这类问题绕来绕去最后都会回到这个核心类上。它不像业务代码那样天天改但恰恰是整个SpringMVC的枢纽。我最早读DispatcherServlet源码是因为一个诡异问题同一个应用里配了两套接口前缀一套正常工作另一套的所有请求都404而且Controller方法明明被Spring扫描到了。后来追到初始化逻辑才发现根因是DispatcherServlet没有正确创建子容器导致HandlerMapping根本看不到那一批Controller。从那次开始我意识到DispatcherServlet不是一个普通的Servlet它承担了三层职责启动时创建并刷新WebApplicationContext请求到来时协调HandlerMapping、HandlerAdapter、ViewResolver等组件完成处理异常发生时统一交给HandlerExceptionResolver兜底。站在架构角度看DispatcherServlet是典型的前端控制器模式实现。Servlet容器把所有匹配到的请求交给它它自己不干具体业务而是把任务拆给一组策略组件。这样做的最大好处是后续加新的Handler类型、新的参数解析器、新的视图解析器都不需要改Servlet层的代码。我们日常开发的Controller方法其实只是整个链条中的一小段真正的大管家始终是DispatcherServlet。这个类继承自FrameworkServletFrameworkServlet又继承自HttpServletBean最底层是HttpServlet。整套设计有一个很容易被忽略的细节HttpServlet的标准service方法只会把GET、POST、PUT、DELETE分发到对应doXxx方法并不认识PATCH。所以FrameworkServlet重写了service方法把PATCH也纳入了处理范围。这种边界细节只有真正读到这里才会注意到。这篇文章适合正在啃SpringMVC源码的开发者、被各类Web层诡异问题困扰的排查者也适合那些想搞明白为什么Controller方法能拿到参数、能返回JSON的同学。我会顺着初始化、请求分发、适配器、视图解析、异常处理这条主线往下讲不空谈理论尽量落在能复现、能调试、能排查问题的实际操作上。2. 启动期暗战从Servlet容器到WebApplicationContext的初始化链路2.1 三层Servlet类的初始化分工DispatcherServlet的初始化不是一步完成的而是由父类一层层接力。先是HttpServletBean的init方法它把web.xml或者编程式Servlet注册里配置的init-param值绑定到当前servlet实例的属性上。比如contextConfigLocation这个参数就是在这个阶段被读取的。如果你用Spring Boot看不到web.xml但依然可以通过配置DispatcherServletRegistrationBean或者属性文件影响这一层。接下来是FrameworkServlet.initServletBean方法它负责创建WebApplicationContext。这里有个关键点如果应用里配置了ContextLoaderListener它会在Servlet容器启动时先创建一个根WebApplicationContext用来放Service、Repository这类业务底层组件而DispatcherServlet会再创建一个子WebApplicationContext用来放Controller、HandlerMapping、ViewResolver这些Web层组件。子容器能看到父容器中的Bean反之不行。这也是很多人踩坑的地方——把Controller写进了根容器配置文件结果DispatcherServlet的HandlerMapping怎么都找不到它。最后才是DispatcherServlet自身。它在FrameworkServlet创建好容器、执行刷新之后会进入onRefresh方法真正的核心策略初始化都放在这里。这个onRefresh在servlet生命周期内只会执行一次所以DispatcherServlet的九大组件初始化是一次性完成的。启动阶段如果报了错基本都能在这里找到线索。2.2 initStrategies一次批量装配九大组件我最早读这段代码时被惊艳到原来所有策略初始化就是这样一个方法批量搞定protected void initStrategies(ApplicationContext context) { initMultipartResolver(context); initLocaleResolver(context); initThemeResolver(context); initHandlerMappings(context); initHandlerAdapters(context); initHandlerExceptionResolvers(context); initRequestToViewNameTranslator(context); initViewResolvers(context); initFlashMapManager(context); }九个组件各司其职MultipartResolver处理文件上传LocaleResolver处理国际化区域ThemeResolver处理主题HandlerMapping负责把请求映射到HandlerHandlerAdapter负责真正执行HandlerHandlerExceptionResolver负责异常处理RequestToViewNameTranslator在Controller没指定视图名时推导默认视图名ViewResolver负责把视图名解析成View对象FlashMapManager处理重定向时的临时数据传递。以HandlerMapping的初始化为例DispatcherServlet的逻辑是先从当前容器里找有没有自定义的HandlerMapping类型的Bean有就用一个都找不到时再读取默认策略文件DispatcherServlet.properties实例化内置的BeanNameUrlHandlerMapping和RequestMappingHandlerMapping。如果容器里已经存在自定义HandlerMapping默认的就不会再注册。这意味着一旦使用EnableWebMvc或者WebMvcConfigurer去扩展MVC配置Spring Boot和SpringMVC会自动帮你重新组装HandlerMapping链确保自定义配置能叠加进去。2.3 最容易踩的初始化配置坑说到配置有几个坑几乎所有人都会遇到。第一个是contextConfigLocation指向错误。很多人习惯把Controller、Service全放在同一个XML里让DispatcherServlet加载同时又有ContextLoaderListener去加载另一个包含Service的XML。结果Service被创建两份事务和AOP出现灵异现象。推荐做法始终是根容器放业务层和持久层子容器放Web层组件。第二个是HandlerMapping的顺序问题。SpringMVC允许配置多个HandlerMapping每个有order属性。如果某个HandlerMapping的order值太小而且它对所有URL都能匹配后面的精确匹配就没机会执行表现就是访问接口总进错Controller。这个要看启动日志里各个HandlerMapping的注册顺序排查时优先看order。第三个是用Spring Boot时的自动配置叠加问题。Boot通过DispatcherServletAutoConfiguration自动注册DispatcherServlet和DispatcherServletRegistrationBean默认映射路径是/。如果我们又自己手动定义了一个DispatcherServletBean极有可能出现两个DispatcherServlet同时存在的局面。症状往往是初始化日志打两遍部分映射丢失。纯看代码时不容易想到是这种低级问题但实际排查里真不少见。我建议团队里新人对这块保持敬畏别急着改配置先搞懂当前应用里究竟有哪些Spring容器每个容器各自负责加载什么再动手。容器边界就是这里最重要的边界。3. 一次请求的完整巡演doDispatch方法逐行拆解3.1 从service到doService请求如何进入SpringMVC请求打到DispatcherServlet后入口是HttpServlet的service方法FrameworkServlet重写了它。一个重要细节是它把所有请求方法都统一收拢到processRequest方法由processRequest再调用doService。这么做的好处是可以把当前请求的Locale上下文和RequestAttributes上下文先设置好再进入真正的分发逻辑。你可以把这一层理解为前置舞台布置。doService虽然名字叫service但它只做了一件事把WebApplicationContext、LocaleResolver、ThemeResolver这些对象塞到request属性里然后调用doDispatch。之所以放在request属性里是为了让后续各层组件无需依赖servlet容器的上下文环境直接从request属性中取用即可。这样也方便别的地方复用SpringMVC的分发能力。doService里还有一个不太起眼但很实用的处理FlashMap。它会把上一次请求中保存的重定向属性从session里恢复出来同时把当前请求中需要给下一次重定向使用的属性保存进去。如果你用过RedirectAttributes底层就是在这一环被DispatcherServlet串起来的。3.2 doDispatch的主干一次请求的九步走doDispatch可以说是SpringMVC里最值得反复阅读的方法。我简化后它的核心脉络是这样protected void doDispatch(HttpServletRequest request, HttpServletResponse response) throws Exception { HttpServletRequest processedRequest request; HandlerExecutionChain mappedHandler null; boolean multipartRequestParsed false; try { ModelAndView mv null; Exception dispatchException null; try { // 第一步处理文件上传请求 processedRequest checkMultipart(request); multipartRequestParsed (processedRequest ! request); // 第二步找到能处理当前请求的Handler通常就是HandlerMethod mappedHandler getHandler(processedRequest); if (mappedHandler null) { noHandlerFound(processedRequest, response); return; } // 第三步找到能执行这个Handler的适配器 HandlerAdapter ha getHandlerAdapter(mappedHandler.getHandler()); // 第四步执行拦截器preHandle if (!mappedHandler.applyPreHandle(processedRequest, response)) { return; } // 第五步真正调用Controller方法 mv ha.handle(processedRequest, response, mappedHandler.getHandler()); // 第六步如果Controller没指定视图名用默认视图名补齐 applyDefaultViewName(processedRequest, mv); // 第七步执行拦截器postHandle mappedHandler.applyPostHandle(processedRequest, response, mv); } catch (Exception ex) { dispatchException ex; } catch (Throwable err) { dispatchException new NestedServletException(Handler dispatch failed, err); } // 第八步处理返回结果或统一处理异常 processDispatchResult(processedRequest, response, mappedHandler, mv, dispatchException); } catch (Exception ex) { triggerAfterCompletion(processedRequest, response, mappedHandler, ex); } finally { // 异步请求或清理multipart临时文件 } }这段代码最值得学习的是整个分发流程把异常也当成了一种正常分支。Controller方法抛异常后并不会直接冒泡到Servlet容器而是先被捕获由processDispatchResult中的异常解析器统一处理。这也是为什么我们能用ExceptionHandler优雅地返回错误页或者错误JSON。理解了这一点再去看异常处理体系会清晰很多。3.3 HandlerExecutionChain拦截器包裹下的执行链getHandler返回的不是一个孤零零的对象而是HandlerExecutionChain。这个执行链里包含真正的handler与零到多个拦截器。拦截器在preHandle阶段决定是否放行如果某个拦截器返回falsedoDispatch会直接return并且逆序触发已经通过拦截器的afterCompletion方法。我实际调试时很多请求没进Controller的问题最后都发现是拦截器把请求拦住了。常见症状是浏览器F12能看到请求有响应但业务日志里一点痕迹都没有。这时别先怀疑Controller先看控制台有没有preHandle returned false相关的日志或者直接断点打到HandlerExecutionChain.applyPreHandle上一目了然。postHandle的执行时机也有讲究它在Controller执行之后、视图渲染之前。但是如果Controller上用了ResponseBody真正的响应体在HandlerAdapter内部已经写给了responsepostHandle再去修改模型其实已经晚了。很多人以为可以在这里往响应体里追加内容实际上做不到。要改响应体应该用ResponseBodyAdvice。4. HandlerMapping与HandlerAdapter路由和执行的桥梁是如何选择的4.1 getHandler是如何命中Controller方法的doDispatch里的第一步getHandler本质上是遍历所有HandlerMapping调用它们的getHandler方法返回第一个非空结果。在SpringMVC里我们平时最常用的RequestMappingHandlerMapping会扫描所有被Controller标记的Bean解析其中的RequestMapping注解并把这个注解信息连同方法、Bean的引用一起注册到MappingRegistry中。这里会有一个比较核心的数据结构RequestMappingInfo。一个方法上的RequestMapping注解会被组合成请求路径、HTTP方法、请求参数条件、请求头条件、Content-Type条件、Accept条件等一整套匹配规则。当请求进入时RequestMappingHandlerMapping根据当前请求的路径、方法、Header等信息去匹配已注册的RequestMappingInfo找到最合适的那一个HandlerMethod。如果同一个路径同时支持GET和POSTRequestMappingHandlerMapping会精确区分方法类型如果有多个Controller方法命中同一条路径它还会按条件优先级排序。这里最常见的问题是路径变量与正则的匹配规则比如/path/{id:.}这种写法不同Spring版本对后缀匹配的策略不同升级框架后行为会发生变化排查时要特别留意。4.2 适配器模式为什么不让DispatcherServlet直接调用Controller很多人会有疑问既然HandlerMapping已经找到了HandlerMethod为什么不直接反射调用非要再经一层HandlerAdapter因为DispatcherServlet的目标是通用的它不仅要兼容我们熟悉的注解Controller还要兼容实现了Controller接口的旧式Controller、HttpRequestHandler以及后续可能出现的其他Handler形态。DispatcherServlet只认HandlerAdapter的接口再让适配器去处理不同类型的Handler。HandlerAdapter接口里有个support方法。doDispatch拿到handler后会遍历当前所有HandlerAdapter找到support返回true的那个。RequestMappingHandlerAdapter只支持HandlerMethodSimpleControllerHandlerAdapter支持继承了Controller接口的BeanHttpRequestHandlerAdapter支持HttpRequestHandler。这种设计让核心分发逻辑保持稳定扩展新的Handler类型时不用动DispatcherServlet本身。我在给团队做分享时常说读SpringMVC源码先读doDispatch再读HandlerAdapter基本就能把框架的骨架钩出来。适配器不是多余的中间层它是整个框架保持开放性的关键。4.3 参数解析与返回值处理器的真实执行点RequestMappingHandlerAdapter内部维护两个关键列表HandlerMethodArgumentResolver和HandlerMethodReturnValueHandler。Controller方法执行前Spring会通过InvocableHandlerMethod逐个解析参数执行后又通过ServletInvocableHandlerMethod调用返回值处理器决定是直接写响应体还是继续走ModelAndView。比如PathVariable注解的参数由PathVariableMethodArgumentResolver处理RequestParam注解的参数由RequestParamMethodArgumentResolver处理RequestBody注解的参数则由RequestResponseBodyMethodProcessor处理它会读取请求Content-Type并从容器中所有的HttpMessageConverter里找到能处理该类型和该内容的转换器把请求体转换成目标对象。这里有个排查经验当遇到Required request body is missing或者参数值为null时先看Content-Type有没有设对。比如前端明明用JSON传参但忘了设置application/jsonSpring就不知道用哪个转换器于是报错。返回值的逻辑类似方法上标ResponseBody后RequestResponseBodyMethodProcessor会用内容协商机制选择转换器把返回值序列化成JSON等格式写回。常见解析器与注解对应关系我整理成一张表方便对照参数解析器主要支持场景RequestParamMethodArgumentResolverRequestParam、普通简单类型参数PathVariableMethodArgumentResolverPathVariable路径变量RequestHeaderMethodArgumentResolverRequestHeader请求头RequestResponseBodyMethodProcessorRequestBody请求体、ResponseBody返回值ModelAttributeMethodProcessorModelAttribute表单绑定、复杂对象参数5. ModelAndView的最后一公里视图解析与渲染细节5.1 没有ResponseBody时结果去哪里了当Controller方法返回一个字符串逻辑视图名或ModelAndView时doDispatch会走到processDispatchResult。这里面有个分支如果ModelAndView里面的viewName不为空DispatcherServlet会遍历所有ViewResolver调用resolveViewName去解析出真正的View对象。最常用的InternalResourceViewResolver逻辑很直白把viewName拼上前缀和后缀得到一个内部资源路径。比如配置了prefix为/WEB-INF/views/suffix为.jsp那么逻辑视图名hello最终被解析为/WEB-INF/views/hello.jsp。它返回的View对象是InternalResourceView渲染阶段实际上就是一次服务端转发。如果Controller没有指定视图名SpringMVC也不会直接报错而是用RequestToViewNameTranslator从请求路径去推导默认逻辑视图名。比如访问/hello默认视图名会被推导为hello。这个推导行为搞懂以后就不会再疑惑我明明没有返回视图为什么页面打开的是那个JSP。5.2 redirect与forward前缀背后的处理逻辑在ViewResolver的实现中UrlBasedViewResolver支持一种特殊约定视图名以redirect:开头说明要返回重定向视图以forward:开头说明要显式执行服务器端转发。这个前缀不会拼进prefix与suffix而是被单独识别成RedirectView或InternalResourceView。重定向时Model中的数据会作为URL参数拼接也会被放进FlashMap供下一次请求使用。正因如此RedirectAttributes才能在重定向后依然拿到上一次请求中保存的值。要说这里最容易出的问题就是前后端联调时重定向带参丢失往往是因为没有使用RedirectAttributes而是直接把对象放进了Model导致参数被拼成了冗长的查询串甚至被丢弃。另一个常见问题是配置了多个ViewResolver时order排序不对。比如某个模板框架的ViewResolver排在InternalResourceViewResolver前面且对所有视图名都能返回一个默认View这时候明明只想转发JSP却跑到了模板渲染逻辑里。遇到这种问题建议先在启动日志里把ViewResolver列表打印出来再一个一个调整order。视图解析这块我最大的心得是搞清楚什么时候会走视图解析、什么时候直接写响应体是理解SpringMVC的关键分水岭。标了ResponseBody或RestController的方法返回值由消息转换器直接写出完全不进ViewResolver只有返回逻辑视图名或ModelAndView时视图解析链才登场。这个区分能帮你省掉大量排查时间。6. 失败请求也不慌异常解析器的分工与触发位置6.1 processDispatchResult中的异常兜底doDispatch把Controller方法抛出的异常捕获后会传给processDispatchResult。processDispatchResult的第一步不是直接渲染而是检查dispatchException是否为null。一旦非空它调用processHandlerException这个方法的任务是遍历所有HandlerExceptionResolver找到能处理当前异常的那个解析器让它返回一个ModelAndView。如果异常解析器返回了ModelAndView这个视图会继续走正常的视图渲染流程。也就是说你写的ExceptionHandler方法返回错误页的逻辑视图名最终还是会经过ViewResolver解析和正常请求没有任何区别。如果所有异常解析器都无法处理异常会被包装成ServletException继续向外抛由Servlet容器最终兜底通常是返回500错误页。这套机制最大的价值是业务代码不需要到处try-catch应用层异常可以统一聚拢到异常解析链中。但它也是异常被悄悄吞掉的高发区。排查时一定要先确认是否有某个宽泛的ExceptionHandler把Exception一网打尽导致真实错误信息被包装成固定提示。6.2 ExceptionHandler与ControllerAdvice在链路中的实际位置SpringMVC默认注册了三个重要的异常解析器ExceptionHandlerExceptionResolver专门处理ExceptionHandler注解与ControllerAdvice里的全局异常方法ResponseStatusExceptionResolver负责ResponseStatus注解和ResponseStatusExceptionDefaultHandlerExceptionResolver处理SpringMVC自己抛出的标准异常比如请求方法不支持、参数类型不匹配等。ExceptionHandlerExceptionResolver的匹配逻辑是先看当前Controller内部有没有声明ExceptionHandler方法再看全局ControllerAdvice。局部优先于全局。一个很实用的技巧是在ControllerAdvice中可以通过Order控制多个全局通知类的优先级order值越小优先级越高。我还想强调一个细节ExceptionHandler方法能接收的参数有限常见的有异常对象本身、HttpServletRequest、WebRequest、HttpServletResponse、Model等。如果你想在异常处理器里拿到更多上下文记得把需要的参数直接写进方法签名Spring会按类型自动注入。这个方法里返回String、ModelAndView、ResponseEntity都支持取决于你需要的返回风格。Spring Boot环境还有一个异常第二跳如果DispatcherServlet的异常解析器没有处理掉异常请求会转发到容器的错误页Boot在默认情况下会把它交给/error路径由BasicErrorController处理最终返回我们常用的错误JSON或错误页面。所以有些时候你在ExceptionHandler里没拦住异常但看到的是一个很标准的错误JSON其实是走到了Boot的错误处理兜底逻辑。7. 徒手抓问题我常用的DispatcherServlet排错与调试技巧7.1 善用启动日志和TRACE级别的请求日志排查DispatcherServlet问题我永远先看启动日志。请求路径的映射信息、初始化信息都会打印出来比如Mapping {[/hello]} onto public java.lang.String sample.controller.IndexController.hello() Initializing Spring DispatcherServlet dispatcherServlet Completed 200 OK看到这些日志至少说明DispatcherServlet已经初始化成功了。如果请求发出后服务端没有对应日志就要先怀疑请求是否被Servlet容器截走或者DispatcherServlet映射路径不对。Spring Boot项目如果直接访问接口遇到404但又没有任何MVC日志大概率是DispatcherServlet的路由没覆盖到那个路径。还可以把SpringMVC日志调成TRACE级别。在application.properties里加一行logging.level.org.springframework.web.servletTRACE这样请求进来后DispatcherServlet的分发过程会输出非常详细的日志包括找到哪个Handler、用了哪个HandlerAdapter、返回了什么ModelAndView、解析到哪个View。排查诡异问题时这一招比断点来得更快尤其适合线上环境无法随意断点的场景。7.2 三个高价值断点位置如果TRACE日志还不够我就会组里叫人开本地调试。最有价值的断点有三个第一个是DispatcherServlet.doDispatch方法的第一行确认请求确实进了SpringMVC第二个是RequestMappingHandlerMapping里处理HandlerMethod映射缓存的地方能直接看到当前容器里到底注册了多少个映射、路径是什么第三个是ServletInvocableHandlerMethod.invokeAndHand方法等在这里可以看到参数解析完成后的真实参数值再进入Controller。常规流程里看404就抓doDispatch和HandlerMapping看500就抓processDispatchResult和异常解析器。断点顺序照着doDispatch的主线来基本不会迷路。还有一个技巧直接在IDEA里给HandlerExecutionChain.applyPreHandle打条件断点条件设为request.getRequestURI().contains(hello)只拦截你想看的请求避免被健康检查请求干扰。7.3 两个值得写进团队文档的典型案例第一个案例是一个项目里出现了两个DispatcherServlet。有段时间新同事在配置类里手动注册了一个DispatcherServlet又忘了关掉Boot的自动配置。结果启动日志里出现两次初始化其中一个servlet的HandlerMapping只加载了部分Controller访问特定模块的接口就404。排查办法很简单列出所有DispatcherServlet类型Bean只保留一个。第二个案例是Controller在根容器HandlerMapping在子容器。某个老项目改造时把Controller扫描放进了ContextLoaderListener的配置里DispatcherServlet的子容器又设置了useDefaultServletContext之类的参数。Controller类明明能被Spring管理但RequestMappingHandlerMapping始终看不到它因为HandlerMapping基于子容器做Bean扫描子容器看不到父容器中注册的这些Bean。修正方法就是把Controller扫描配置移到DispatcherServlet对应的配置文件中。我把排查经验总结成几条规律404优先查HandlerMapping有没有映射、拦截器有没有放行参数问题优先查ArgumentResolver与HttpMessageConverter视图问题优先查ViewResolver链和返回值类型异常被吞优先查宽泛的ExceptionHandler。顺着这个顺序走绝大部分问题都能在半小时内定位到具体环节。最后想分享的一点体会翻DispatcherServlet源码这件事最爽的地方不是背下来某一行逻辑而是你会突然理解SpringMVC所有看似魔法的能力其实都发生在一个非常清晰的分发主线上。Controller只是这条线上一个小小的执行节点HandlerMapping负责找它HandlerAdapter负责启动它参数解析器准备入参消息转换器切分响应异常解析器收拾烂摊子ViewResolver把逻辑视图变成真实页面。每一个环节都可以被替换或扩展这就是框架的生命力来源。我个人还有个习惯每次新项目启动时我都会先看一眼启动日志中打印的Mapped信息顺手数一数HandlerMapping数量。这等于给DispatcherServlet做了一次快速体检。如果你也想吃透这套机制强烈建议从doDispatch这个方法的断点出发把每个分支都踩一遍再多看几个版本的差异。你会发现SpringMVC的源码读起来并不枯燥它更像一张清晰的地图把Web开发那些零散的知识点全部串了起来。
1. 所有请求的汇聚点DispatcherServlet在SpringMVC中的真正职责做了这么多年Java服务端开发我对SpringMVC的印象总结起来就是一句话它把一次HTTP请求变成了一次有秩序的分发过程而DispatcherServlet就是这个过程的指挥官。很多刚接触框架的同事会觉得加个RestController、写个方法就能出结果根本不用关心DispatcherServlet。可一旦遇到404、参数解析不对、视图找不到、异常被吞掉这类问题绕来绕去最后都会回到这个核心类上。它不像业务代码那样天天改但恰恰是整个SpringMVC的枢纽。我最早读DispatcherServlet源码是因为一个诡异问题同一个应用里配了两套接口前缀一套正常工作另一套的所有请求都404而且Controller方法明明被Spring扫描到了。后来追到初始化逻辑才发现根因是DispatcherServlet没有正确创建子容器导致HandlerMapping根本看不到那一批Controller。从那次开始我意识到DispatcherServlet不是一个普通的Servlet它承担了三层职责启动时创建并刷新WebApplicationContext请求到来时协调HandlerMapping、HandlerAdapter、ViewResolver等组件完成处理异常发生时统一交给HandlerExceptionResolver兜底。站在架构角度看DispatcherServlet是典型的前端控制器模式实现。Servlet容器把所有匹配到的请求交给它它自己不干具体业务而是把任务拆给一组策略组件。这样做的最大好处是后续加新的Handler类型、新的参数解析器、新的视图解析器都不需要改Servlet层的代码。我们日常开发的Controller方法其实只是整个链条中的一小段真正的大管家始终是DispatcherServlet。这个类继承自FrameworkServletFrameworkServlet又继承自HttpServletBean最底层是HttpServlet。整套设计有一个很容易被忽略的细节HttpServlet的标准service方法只会把GET、POST、PUT、DELETE分发到对应doXxx方法并不认识PATCH。所以FrameworkServlet重写了service方法把PATCH也纳入了处理范围。这种边界细节只有真正读到这里才会注意到。这篇文章适合正在啃SpringMVC源码的开发者、被各类Web层诡异问题困扰的排查者也适合那些想搞明白为什么Controller方法能拿到参数、能返回JSON的同学。我会顺着初始化、请求分发、适配器、视图解析、异常处理这条主线往下讲不空谈理论尽量落在能复现、能调试、能排查问题的实际操作上。2. 启动期暗战从Servlet容器到WebApplicationContext的初始化链路2.1 三层Servlet类的初始化分工DispatcherServlet的初始化不是一步完成的而是由父类一层层接力。先是HttpServletBean的init方法它把web.xml或者编程式Servlet注册里配置的init-param值绑定到当前servlet实例的属性上。比如contextConfigLocation这个参数就是在这个阶段被读取的。如果你用Spring Boot看不到web.xml但依然可以通过配置DispatcherServletRegistrationBean或者属性文件影响这一层。接下来是FrameworkServlet.initServletBean方法它负责创建WebApplicationContext。这里有个关键点如果应用里配置了ContextLoaderListener它会在Servlet容器启动时先创建一个根WebApplicationContext用来放Service、Repository这类业务底层组件而DispatcherServlet会再创建一个子WebApplicationContext用来放Controller、HandlerMapping、ViewResolver这些Web层组件。子容器能看到父容器中的Bean反之不行。这也是很多人踩坑的地方——把Controller写进了根容器配置文件结果DispatcherServlet的HandlerMapping怎么都找不到它。最后才是DispatcherServlet自身。它在FrameworkServlet创建好容器、执行刷新之后会进入onRefresh方法真正的核心策略初始化都放在这里。这个onRefresh在servlet生命周期内只会执行一次所以DispatcherServlet的九大组件初始化是一次性完成的。启动阶段如果报了错基本都能在这里找到线索。2.2 initStrategies一次批量装配九大组件我最早读这段代码时被惊艳到原来所有策略初始化就是这样一个方法批量搞定protected void initStrategies(ApplicationContext context) { initMultipartResolver(context); initLocaleResolver(context); initThemeResolver(context); initHandlerMappings(context); initHandlerAdapters(context); initHandlerExceptionResolvers(context); initRequestToViewNameTranslator(context); initViewResolvers(context); initFlashMapManager(context); }九个组件各司其职MultipartResolver处理文件上传LocaleResolver处理国际化区域ThemeResolver处理主题HandlerMapping负责把请求映射到HandlerHandlerAdapter负责真正执行HandlerHandlerExceptionResolver负责异常处理RequestToViewNameTranslator在Controller没指定视图名时推导默认视图名ViewResolver负责把视图名解析成View对象FlashMapManager处理重定向时的临时数据传递。以HandlerMapping的初始化为例DispatcherServlet的逻辑是先从当前容器里找有没有自定义的HandlerMapping类型的Bean有就用一个都找不到时再读取默认策略文件DispatcherServlet.properties实例化内置的BeanNameUrlHandlerMapping和RequestMappingHandlerMapping。如果容器里已经存在自定义HandlerMapping默认的就不会再注册。这意味着一旦使用EnableWebMvc或者WebMvcConfigurer去扩展MVC配置Spring Boot和SpringMVC会自动帮你重新组装HandlerMapping链确保自定义配置能叠加进去。2.3 最容易踩的初始化配置坑说到配置有几个坑几乎所有人都会遇到。第一个是contextConfigLocation指向错误。很多人习惯把Controller、Service全放在同一个XML里让DispatcherServlet加载同时又有ContextLoaderListener去加载另一个包含Service的XML。结果Service被创建两份事务和AOP出现灵异现象。推荐做法始终是根容器放业务层和持久层子容器放Web层组件。第二个是HandlerMapping的顺序问题。SpringMVC允许配置多个HandlerMapping每个有order属性。如果某个HandlerMapping的order值太小而且它对所有URL都能匹配后面的精确匹配就没机会执行表现就是访问接口总进错Controller。这个要看启动日志里各个HandlerMapping的注册顺序排查时优先看order。第三个是用Spring Boot时的自动配置叠加问题。Boot通过DispatcherServletAutoConfiguration自动注册DispatcherServlet和DispatcherServletRegistrationBean默认映射路径是/。如果我们又自己手动定义了一个DispatcherServletBean极有可能出现两个DispatcherServlet同时存在的局面。症状往往是初始化日志打两遍部分映射丢失。纯看代码时不容易想到是这种低级问题但实际排查里真不少见。我建议团队里新人对这块保持敬畏别急着改配置先搞懂当前应用里究竟有哪些Spring容器每个容器各自负责加载什么再动手。容器边界就是这里最重要的边界。3. 一次请求的完整巡演doDispatch方法逐行拆解3.1 从service到doService请求如何进入SpringMVC请求打到DispatcherServlet后入口是HttpServlet的service方法FrameworkServlet重写了它。一个重要细节是它把所有请求方法都统一收拢到processRequest方法由processRequest再调用doService。这么做的好处是可以把当前请求的Locale上下文和RequestAttributes上下文先设置好再进入真正的分发逻辑。你可以把这一层理解为前置舞台布置。doService虽然名字叫service但它只做了一件事把WebApplicationContext、LocaleResolver、ThemeResolver这些对象塞到request属性里然后调用doDispatch。之所以放在request属性里是为了让后续各层组件无需依赖servlet容器的上下文环境直接从request属性中取用即可。这样也方便别的地方复用SpringMVC的分发能力。doService里还有一个不太起眼但很实用的处理FlashMap。它会把上一次请求中保存的重定向属性从session里恢复出来同时把当前请求中需要给下一次重定向使用的属性保存进去。如果你用过RedirectAttributes底层就是在这一环被DispatcherServlet串起来的。3.2 doDispatch的主干一次请求的九步走doDispatch可以说是SpringMVC里最值得反复阅读的方法。我简化后它的核心脉络是这样protected void doDispatch(HttpServletRequest request, HttpServletResponse response) throws Exception { HttpServletRequest processedRequest request; HandlerExecutionChain mappedHandler null; boolean multipartRequestParsed false; try { ModelAndView mv null; Exception dispatchException null; try { // 第一步处理文件上传请求 processedRequest checkMultipart(request); multipartRequestParsed (processedRequest ! request); // 第二步找到能处理当前请求的Handler通常就是HandlerMethod mappedHandler getHandler(processedRequest); if (mappedHandler null) { noHandlerFound(processedRequest, response); return; } // 第三步找到能执行这个Handler的适配器 HandlerAdapter ha getHandlerAdapter(mappedHandler.getHandler()); // 第四步执行拦截器preHandle if (!mappedHandler.applyPreHandle(processedRequest, response)) { return; } // 第五步真正调用Controller方法 mv ha.handle(processedRequest, response, mappedHandler.getHandler()); // 第六步如果Controller没指定视图名用默认视图名补齐 applyDefaultViewName(processedRequest, mv); // 第七步执行拦截器postHandle mappedHandler.applyPostHandle(processedRequest, response, mv); } catch (Exception ex) { dispatchException ex; } catch (Throwable err) { dispatchException new NestedServletException(Handler dispatch failed, err); } // 第八步处理返回结果或统一处理异常 processDispatchResult(processedRequest, response, mappedHandler, mv, dispatchException); } catch (Exception ex) { triggerAfterCompletion(processedRequest, response, mappedHandler, ex); } finally { // 异步请求或清理multipart临时文件 } }这段代码最值得学习的是整个分发流程把异常也当成了一种正常分支。Controller方法抛异常后并不会直接冒泡到Servlet容器而是先被捕获由processDispatchResult中的异常解析器统一处理。这也是为什么我们能用ExceptionHandler优雅地返回错误页或者错误JSON。理解了这一点再去看异常处理体系会清晰很多。3.3 HandlerExecutionChain拦截器包裹下的执行链getHandler返回的不是一个孤零零的对象而是HandlerExecutionChain。这个执行链里包含真正的handler与零到多个拦截器。拦截器在preHandle阶段决定是否放行如果某个拦截器返回falsedoDispatch会直接return并且逆序触发已经通过拦截器的afterCompletion方法。我实际调试时很多请求没进Controller的问题最后都发现是拦截器把请求拦住了。常见症状是浏览器F12能看到请求有响应但业务日志里一点痕迹都没有。这时别先怀疑Controller先看控制台有没有preHandle returned false相关的日志或者直接断点打到HandlerExecutionChain.applyPreHandle上一目了然。postHandle的执行时机也有讲究它在Controller执行之后、视图渲染之前。但是如果Controller上用了ResponseBody真正的响应体在HandlerAdapter内部已经写给了responsepostHandle再去修改模型其实已经晚了。很多人以为可以在这里往响应体里追加内容实际上做不到。要改响应体应该用ResponseBodyAdvice。4. HandlerMapping与HandlerAdapter路由和执行的桥梁是如何选择的4.1 getHandler是如何命中Controller方法的doDispatch里的第一步getHandler本质上是遍历所有HandlerMapping调用它们的getHandler方法返回第一个非空结果。在SpringMVC里我们平时最常用的RequestMappingHandlerMapping会扫描所有被Controller标记的Bean解析其中的RequestMapping注解并把这个注解信息连同方法、Bean的引用一起注册到MappingRegistry中。这里会有一个比较核心的数据结构RequestMappingInfo。一个方法上的RequestMapping注解会被组合成请求路径、HTTP方法、请求参数条件、请求头条件、Content-Type条件、Accept条件等一整套匹配规则。当请求进入时RequestMappingHandlerMapping根据当前请求的路径、方法、Header等信息去匹配已注册的RequestMappingInfo找到最合适的那一个HandlerMethod。如果同一个路径同时支持GET和POSTRequestMappingHandlerMapping会精确区分方法类型如果有多个Controller方法命中同一条路径它还会按条件优先级排序。这里最常见的问题是路径变量与正则的匹配规则比如/path/{id:.}这种写法不同Spring版本对后缀匹配的策略不同升级框架后行为会发生变化排查时要特别留意。4.2 适配器模式为什么不让DispatcherServlet直接调用Controller很多人会有疑问既然HandlerMapping已经找到了HandlerMethod为什么不直接反射调用非要再经一层HandlerAdapter因为DispatcherServlet的目标是通用的它不仅要兼容我们熟悉的注解Controller还要兼容实现了Controller接口的旧式Controller、HttpRequestHandler以及后续可能出现的其他Handler形态。DispatcherServlet只认HandlerAdapter的接口再让适配器去处理不同类型的Handler。HandlerAdapter接口里有个support方法。doDispatch拿到handler后会遍历当前所有HandlerAdapter找到support返回true的那个。RequestMappingHandlerAdapter只支持HandlerMethodSimpleControllerHandlerAdapter支持继承了Controller接口的BeanHttpRequestHandlerAdapter支持HttpRequestHandler。这种设计让核心分发逻辑保持稳定扩展新的Handler类型时不用动DispatcherServlet本身。我在给团队做分享时常说读SpringMVC源码先读doDispatch再读HandlerAdapter基本就能把框架的骨架钩出来。适配器不是多余的中间层它是整个框架保持开放性的关键。4.3 参数解析与返回值处理器的真实执行点RequestMappingHandlerAdapter内部维护两个关键列表HandlerMethodArgumentResolver和HandlerMethodReturnValueHandler。Controller方法执行前Spring会通过InvocableHandlerMethod逐个解析参数执行后又通过ServletInvocableHandlerMethod调用返回值处理器决定是直接写响应体还是继续走ModelAndView。比如PathVariable注解的参数由PathVariableMethodArgumentResolver处理RequestParam注解的参数由RequestParamMethodArgumentResolver处理RequestBody注解的参数则由RequestResponseBodyMethodProcessor处理它会读取请求Content-Type并从容器中所有的HttpMessageConverter里找到能处理该类型和该内容的转换器把请求体转换成目标对象。这里有个排查经验当遇到Required request body is missing或者参数值为null时先看Content-Type有没有设对。比如前端明明用JSON传参但忘了设置application/jsonSpring就不知道用哪个转换器于是报错。返回值的逻辑类似方法上标ResponseBody后RequestResponseBodyMethodProcessor会用内容协商机制选择转换器把返回值序列化成JSON等格式写回。常见解析器与注解对应关系我整理成一张表方便对照参数解析器主要支持场景RequestParamMethodArgumentResolverRequestParam、普通简单类型参数PathVariableMethodArgumentResolverPathVariable路径变量RequestHeaderMethodArgumentResolverRequestHeader请求头RequestResponseBodyMethodProcessorRequestBody请求体、ResponseBody返回值ModelAttributeMethodProcessorModelAttribute表单绑定、复杂对象参数5. ModelAndView的最后一公里视图解析与渲染细节5.1 没有ResponseBody时结果去哪里了当Controller方法返回一个字符串逻辑视图名或ModelAndView时doDispatch会走到processDispatchResult。这里面有个分支如果ModelAndView里面的viewName不为空DispatcherServlet会遍历所有ViewResolver调用resolveViewName去解析出真正的View对象。最常用的InternalResourceViewResolver逻辑很直白把viewName拼上前缀和后缀得到一个内部资源路径。比如配置了prefix为/WEB-INF/views/suffix为.jsp那么逻辑视图名hello最终被解析为/WEB-INF/views/hello.jsp。它返回的View对象是InternalResourceView渲染阶段实际上就是一次服务端转发。如果Controller没有指定视图名SpringMVC也不会直接报错而是用RequestToViewNameTranslator从请求路径去推导默认逻辑视图名。比如访问/hello默认视图名会被推导为hello。这个推导行为搞懂以后就不会再疑惑我明明没有返回视图为什么页面打开的是那个JSP。5.2 redirect与forward前缀背后的处理逻辑在ViewResolver的实现中UrlBasedViewResolver支持一种特殊约定视图名以redirect:开头说明要返回重定向视图以forward:开头说明要显式执行服务器端转发。这个前缀不会拼进prefix与suffix而是被单独识别成RedirectView或InternalResourceView。重定向时Model中的数据会作为URL参数拼接也会被放进FlashMap供下一次请求使用。正因如此RedirectAttributes才能在重定向后依然拿到上一次请求中保存的值。要说这里最容易出的问题就是前后端联调时重定向带参丢失往往是因为没有使用RedirectAttributes而是直接把对象放进了Model导致参数被拼成了冗长的查询串甚至被丢弃。另一个常见问题是配置了多个ViewResolver时order排序不对。比如某个模板框架的ViewResolver排在InternalResourceViewResolver前面且对所有视图名都能返回一个默认View这时候明明只想转发JSP却跑到了模板渲染逻辑里。遇到这种问题建议先在启动日志里把ViewResolver列表打印出来再一个一个调整order。视图解析这块我最大的心得是搞清楚什么时候会走视图解析、什么时候直接写响应体是理解SpringMVC的关键分水岭。标了ResponseBody或RestController的方法返回值由消息转换器直接写出完全不进ViewResolver只有返回逻辑视图名或ModelAndView时视图解析链才登场。这个区分能帮你省掉大量排查时间。6. 失败请求也不慌异常解析器的分工与触发位置6.1 processDispatchResult中的异常兜底doDispatch把Controller方法抛出的异常捕获后会传给processDispatchResult。processDispatchResult的第一步不是直接渲染而是检查dispatchException是否为null。一旦非空它调用processHandlerException这个方法的任务是遍历所有HandlerExceptionResolver找到能处理当前异常的那个解析器让它返回一个ModelAndView。如果异常解析器返回了ModelAndView这个视图会继续走正常的视图渲染流程。也就是说你写的ExceptionHandler方法返回错误页的逻辑视图名最终还是会经过ViewResolver解析和正常请求没有任何区别。如果所有异常解析器都无法处理异常会被包装成ServletException继续向外抛由Servlet容器最终兜底通常是返回500错误页。这套机制最大的价值是业务代码不需要到处try-catch应用层异常可以统一聚拢到异常解析链中。但它也是异常被悄悄吞掉的高发区。排查时一定要先确认是否有某个宽泛的ExceptionHandler把Exception一网打尽导致真实错误信息被包装成固定提示。6.2 ExceptionHandler与ControllerAdvice在链路中的实际位置SpringMVC默认注册了三个重要的异常解析器ExceptionHandlerExceptionResolver专门处理ExceptionHandler注解与ControllerAdvice里的全局异常方法ResponseStatusExceptionResolver负责ResponseStatus注解和ResponseStatusExceptionDefaultHandlerExceptionResolver处理SpringMVC自己抛出的标准异常比如请求方法不支持、参数类型不匹配等。ExceptionHandlerExceptionResolver的匹配逻辑是先看当前Controller内部有没有声明ExceptionHandler方法再看全局ControllerAdvice。局部优先于全局。一个很实用的技巧是在ControllerAdvice中可以通过Order控制多个全局通知类的优先级order值越小优先级越高。我还想强调一个细节ExceptionHandler方法能接收的参数有限常见的有异常对象本身、HttpServletRequest、WebRequest、HttpServletResponse、Model等。如果你想在异常处理器里拿到更多上下文记得把需要的参数直接写进方法签名Spring会按类型自动注入。这个方法里返回String、ModelAndView、ResponseEntity都支持取决于你需要的返回风格。Spring Boot环境还有一个异常第二跳如果DispatcherServlet的异常解析器没有处理掉异常请求会转发到容器的错误页Boot在默认情况下会把它交给/error路径由BasicErrorController处理最终返回我们常用的错误JSON或错误页面。所以有些时候你在ExceptionHandler里没拦住异常但看到的是一个很标准的错误JSON其实是走到了Boot的错误处理兜底逻辑。7. 徒手抓问题我常用的DispatcherServlet排错与调试技巧7.1 善用启动日志和TRACE级别的请求日志排查DispatcherServlet问题我永远先看启动日志。请求路径的映射信息、初始化信息都会打印出来比如Mapping {[/hello]} onto public java.lang.String sample.controller.IndexController.hello() Initializing Spring DispatcherServlet dispatcherServlet Completed 200 OK看到这些日志至少说明DispatcherServlet已经初始化成功了。如果请求发出后服务端没有对应日志就要先怀疑请求是否被Servlet容器截走或者DispatcherServlet映射路径不对。Spring Boot项目如果直接访问接口遇到404但又没有任何MVC日志大概率是DispatcherServlet的路由没覆盖到那个路径。还可以把SpringMVC日志调成TRACE级别。在application.properties里加一行logging.level.org.springframework.web.servletTRACE这样请求进来后DispatcherServlet的分发过程会输出非常详细的日志包括找到哪个Handler、用了哪个HandlerAdapter、返回了什么ModelAndView、解析到哪个View。排查诡异问题时这一招比断点来得更快尤其适合线上环境无法随意断点的场景。7.2 三个高价值断点位置如果TRACE日志还不够我就会组里叫人开本地调试。最有价值的断点有三个第一个是DispatcherServlet.doDispatch方法的第一行确认请求确实进了SpringMVC第二个是RequestMappingHandlerMapping里处理HandlerMethod映射缓存的地方能直接看到当前容器里到底注册了多少个映射、路径是什么第三个是ServletInvocableHandlerMethod.invokeAndHand方法等在这里可以看到参数解析完成后的真实参数值再进入Controller。常规流程里看404就抓doDispatch和HandlerMapping看500就抓processDispatchResult和异常解析器。断点顺序照着doDispatch的主线来基本不会迷路。还有一个技巧直接在IDEA里给HandlerExecutionChain.applyPreHandle打条件断点条件设为request.getRequestURI().contains(hello)只拦截你想看的请求避免被健康检查请求干扰。7.3 两个值得写进团队文档的典型案例第一个案例是一个项目里出现了两个DispatcherServlet。有段时间新同事在配置类里手动注册了一个DispatcherServlet又忘了关掉Boot的自动配置。结果启动日志里出现两次初始化其中一个servlet的HandlerMapping只加载了部分Controller访问特定模块的接口就404。排查办法很简单列出所有DispatcherServlet类型Bean只保留一个。第二个案例是Controller在根容器HandlerMapping在子容器。某个老项目改造时把Controller扫描放进了ContextLoaderListener的配置里DispatcherServlet的子容器又设置了useDefaultServletContext之类的参数。Controller类明明能被Spring管理但RequestMappingHandlerMapping始终看不到它因为HandlerMapping基于子容器做Bean扫描子容器看不到父容器中注册的这些Bean。修正方法就是把Controller扫描配置移到DispatcherServlet对应的配置文件中。我把排查经验总结成几条规律404优先查HandlerMapping有没有映射、拦截器有没有放行参数问题优先查ArgumentResolver与HttpMessageConverter视图问题优先查ViewResolver链和返回值类型异常被吞优先查宽泛的ExceptionHandler。顺着这个顺序走绝大部分问题都能在半小时内定位到具体环节。最后想分享的一点体会翻DispatcherServlet源码这件事最爽的地方不是背下来某一行逻辑而是你会突然理解SpringMVC所有看似魔法的能力其实都发生在一个非常清晰的分发主线上。Controller只是这条线上一个小小的执行节点HandlerMapping负责找它HandlerAdapter负责启动它参数解析器准备入参消息转换器切分响应异常解析器收拾烂摊子ViewResolver把逻辑视图变成真实页面。每一个环节都可以被替换或扩展这就是框架的生命力来源。我个人还有个习惯每次新项目启动时我都会先看一眼启动日志中打印的Mapped信息顺手数一数HandlerMapping数量。这等于给DispatcherServlet做了一次快速体检。如果你也想吃透这套机制强烈建议从doDispatch这个方法的断点出发把每个分支都踩一遍再多看几个版本的差异。你会发现SpringMVC的源码读起来并不枯燥它更像一张清晰的地图把Web开发那些零散的知识点全部串了起来。
