企业官网建设流程全解析

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。

这个类继承自FrameworkServlet，FrameworkServlet又继承自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负责把请求映射到Handler，HandlerAdapter负责真正执行Handler，HandlerExceptionResolver负责异常处理，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阶段决定是否放行，如果某个拦截器返回false，doDispatch会直接return，并且逆序触发已经通过拦截器的afterCompletion方法。

我实际调试时，很多"请求没进Controller"的问题，最后都发现是拦截器把请求拦住了。常见症状是：浏览器F12能看到请求有响应，但业务日志里一点痕迹都没有。这时别先怀疑Controller，先看控制台有没有"preHandle returned false"相关的日志，或者直接断点打到HandlerExecutionChain.applyPreHandle上，一目了然。

postHandle的执行时机也有讲究，它在Controller执行之后、视图渲染之前。但是，如果Controller上用了@ResponseBody，真正的响应体在HandlerAdapter内部已经写给了response，postHandle再去修改模型，其实已经晚了。很多人以为可以在这里往响应体里追加内容，实际上做不到。要改响应体，应该用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和POST，RequestMappingHandlerMapping会精确区分方法类型；如果有多个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只支持HandlerMethod，SimpleControllerHandlerAdapter支持继承了Controller接口的Bean，HttpRequestHandlerAdapter支持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/json，Spring就不知道用哪个转换器，于是报错。返回值的逻辑类似，方法上标@ResponseBody后，RequestResponseBodyMethodProcessor会用内容协商机制选择转换器，把返回值序列化成JSON等格式写回。

常见解析器与注解对应关系，我整理成一张表，方便对照：

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注解和ResponseStatusException；DefaultHandlerExceptionResolver处理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.servlet=TRACE

这样请求进来后，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开发那些零散的知识点全部串了起来。