简介本资源是一个面向Java Web初学者的SpringMVC入门实践项目聚焦MVC架构核心原理与基础环境搭建帮助开发者快速掌握控制器配置、请求映射、视图解析等关键流程。压缩包共22个文件含5个XML配置文件如web.xml、pom.xml及Eclipse项目元数据、4个JSP视图页含hello.jsp等演示页面、2个Java源码文件含Controller标注的处理器类以及编译生成的class文件和IDE相关配置.classpath、.project、.jsdtscope等整体仅11KB轻量易导入。已有269人学习下载适合作为课堂实验、自学练手或Spring框架前置实践素材。资源结构清晰完整呈现标准SpringMVC工程目录src/main/java、WebContent/WEB-INF、JSP视图层附带可直接运行的Hello, World!示例涵盖DispatcherServlet配置、注解驱动开发、ModelAndView返回机制等核心知识点开箱即用便于理解框架各组件协同工作逻辑。1. SpringMVC项目不是“又一个框架教程”而是你绕不开的Web请求黑匣子拆解现场你写完一个Controller加了RequestMapping启动Tomcat浏览器一刷——404。查日志没报错路径拼得像模像样/user/list明明写了却总跳到默认首页。这不是玄学是SpringMVC的请求生命周期在你眼皮底下悄悄跳过了至少3个关键拦截点。这个资源包不是教你怎么写Hello World而是一套可直接运行、带完整调试断点、含真实HTTP请求链路追踪的SpringMVC最小可验证项目MVP覆盖从DispatcherServlet初始化、HandlerMapping匹配、HandlerAdapter执行到ViewResolver渲染的全链路。它不依赖Spring Boot自动配置所有核心组件显式声明、可打断点、可替换——适合正在被“为什么进不来Controller”“Model数据怎么就丢了”“重定向后参数全没了”反复暴击的Java Web开发者也适合想真正看懂Spring MVC底层调度逻辑的中级工程师。项目结构干净无冗余依赖JDK 8、IDEA Tomcat 9 即可开箱复现。2. 从web.xml到DispatcherServlet手撕SpringMVC启动入口与核心容器加载链SpringMVC不是凭空启动的。它的生命起点是web.xml里那个被很多人复制粘贴却从未细读的servlet配置。本节带你逐行还原真实项目中DispatcherServlet如何接管HTTP请求并验证Spring容器与Web容器的双上下文关系。2.1 web.xml中的三重注册Servlet、Listener与ContextLoaderListener的作用边界SpringMVC项目启动时有两个Spring容器在并行工作根应用上下文Root ApplicationContext和Web应用上下文WebApplicationContext。前者由ContextLoaderListener加载存放Service、DAO等非Web层Bean后者由DispatcherServlet加载专管Controller、HandlerMapping等Web相关Bean。二者是父子关系Web上下文能访问根上下文的Bean反之不行。!-- web.xml -- context-param param-namecontextConfigLocation/param-name param-valueclasspath:spring-root.xml/param-value /context-param listener listener-classorg.springframework.web.context.ContextLoaderListener/listener-class /listener servlet servlet-namedispatcher/servlet-name servlet-classorg.springframework.web.servlet.DispatcherServlet/servlet-class init-param param-namecontextConfigLocation/param-name param-valueclasspath:spring-mvc.xml/param-value /init-param load-on-startup1/load-on-startup /servlet servlet-mapping servlet-namedispatcher/servlet-name url-pattern//url-pattern /servlet-mapping提示load-on-startup1/load-on-startup表示容器启动时立即初始化DispatcherServlet避免首次请求才加载导致延迟。若设为0或省略则按需加载但调试时你会错过Servlet初始化阶段的日志。contextConfigLocation参数决定了配置文件位置。注意ContextLoaderListener加载的是spring-root.xml根上下文而DispatcherServlet加载的是spring-mvc.xmlWeb上下文。这是分离业务逻辑与Web层的关键设计也是很多“Service注入失败”的根源——如果你把Service定义在spring-mvc.xml里而Controller在同一个文件中看似能注入实则破坏了分层原则若Service定义在spring-root.xmlController在spring-mvc.xml就必须确保spring-mvc.xml中未重复定义同名Bean否则Web上下文会覆盖根上下文的BeanSpring默认行为。2.2 DispatcherServlet初始化流程四步走清空你的“启动黑盒”DispatcherServlet继承自HttpServlet其初始化发生在init()方法中。Spring对其做了深度封装核心初始化动作如下载入WebApplicationContext根据contextConfigLocation定位XML配置创建XmlWebApplicationContext实例初始化九大组件包括HandlerMapping如BeanNameUrlHandlerMapping、RequestMappingHandlerMapping、HandlerAdapter如RequestMappingHandlerAdapter、ViewResolver如InternalResourceViewResolver等发布ServletWebServerInitializedEvent事件Spring 5.3打印启动日志形如FrameworkServlet dispatcher: initialization completed in 327 ms。你可以通过在spring-mvc.xml中开启DEBUG日志亲眼看到每一步!-- logback-spring.xml 或 log4j2.xml -- logger nameorg.springframework.web.servlet levelDEBUG/ logger nameorg.springframework.web.servlet.DispatcherServlet levelTRACE/启动后控制台将输出类似Initializing Servlet dispatcher Completed initialization in 289 ms Mapped [/{id}] onto public java.lang.String com.example.controller.UserController.detail(java.lang.Long)这行Mapped [...] onto ...就是RequestMappingHandlerMapping完成URL到Controller方法映射的关键证据。没有它你的RequestMapping就是一张废纸。2.3 验证双上下文用代码证明“根容器看不见ControllerWeb容器看得见Service”在任意Controller中添加以下方法用于验证上下文隔离性Controller public class DebugController { Autowired private ApplicationContext webContext; // 当前DispatcherServlet的WebApplicationContext RequestMapping(/debug/context) ResponseBody public String checkContext() { // 获取根上下文父上下文 ApplicationContext rootContext webContext.getParent(); // 检查Service是否在根上下文中存在 boolean hasUserService rootContext.containsBean(userService); // 检查Controller是否在Web上下文中存在应为true boolean hasThisController webContext.containsBean(debugController); // 检查Controller是否在根上下文中存在应为false boolean hasInRoot rootContext.containsBean(debugController); return String.format( Root ctx has userService: %s\n Web ctx has debugController: %s\n Root ctx has debugController: %s, hasUserService, hasThisController, hasInRoot ); } }访问/debug/context返回结果应为Root ctx has userService: true Web ctx has debugController: true Root ctx has debugController: false这组布尔值就是SpringMVC分层架构最硬的实证。很多团队踩坑在于把所有Bean都扔进spring-mvc.xml导致事务失效Transactional在Service上但Service被Web上下文管理事务代理无法生效、循环依赖、测试困难等问题。3. HandlerMapping与HandlerAdapterURL如何精准命中Controller方法当请求到达DispatcherServlet第一关是HandlerMapping——它不执行逻辑只做“地址簿查询”。第二关是HandlerAdapter——它不关心URL只负责“让目标方法跑起来”。二者解耦正是SpringMVC高扩展性的基石。3.1 RequestMappingHandlerMappingRequestMapping的幕后解析器SpringMVC默认启用RequestMappingHandlerMapping取代旧版DefaultAnnotationHandlerMapping它扫描所有Controller类提取RequestMapping及其派生注解GetMapping,PostMapping等构建成HandlerMethod对象含Class、Method、参数类型、注解元数据并缓存。关键配置在spring-mvc.xml中mvc:annotation-driven / !-- 等价于显式声明 -- bean classorg.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping property nameorder value0/ property nameinterceptors list ref beanlogInterceptor/ /list /property /beanmvc:annotation-driven /是快捷方式它不仅注册RequestMappingHandlerMapping还同时注册RequestMappingHandlerAdapter、ExceptionHandlerExceptionResolver、ConversionService等。但为了调试清晰建议初期显式声明便于打点跟踪。order0表示该HandlerMapping优先级最高。若你自定义了其他HandlerMapping如基于数据库路由的动态映射可通过设置order1使其排在后面。3.2 RequestMappingHandlerAdapter把HTTP请求参数转成Java方法参数的翻译官HandlerAdapter是适配器模式的典型应用。RequestMappingHandlerAdapter负责将原始HttpServletRequest和HttpServletResponse结合RequestParam、PathVariable、RequestBody等注解转换为Controller方法所需的Java对象。其核心能力由一组ArgumentResolver参数解析器和ReturnValueHandler返回值处理器支撑。例如注解对应 ArgumentResolver说明RequestParamRequestParamMethodArgumentResolver解析查询参数、表单字段PathVariablePathVariableMethodArgumentResolver解析URL路径变量RequestBodyRequestResponseBodyMethodProcessor解析JSON/XML请求体依赖HttpMessageConverterModelAttributeModelAttributeMethodProcessor绑定表单到Java Bean你可以在spring-mvc.xml中自定义这些组件bean classorg.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter property nameargumentResolvers list !-- 自定义参数解析器优先级最高 -- bean classcom.example.resolver.LoginUserArgumentResolver/ !-- 保留默认解析器 -- ref beanrequestParamResolver/ /list /property property namemessageConverters list bean classorg.springframework.http.converter.json.MappingJackson2HttpMessageConverter property namesupportedMediaTypes valueapplication/json;charsetUTF-8/ /bean /list /property /bean注意messageConverters顺序很重要。Spring会按顺序尝试每个HttpMessageConverter直到有一个能处理当前Content-Type。若JSON converter在XML converter之后且请求头为application/json则可能因XML converter先匹配失败而抛出HttpMediaTypeNotSupportedException。3.3 手动触发HandlerMapping匹配用JUnit验证URL映射是否生效光看日志不够直观。我们写一个单元测试模拟DispatcherServlet内部逻辑验证URL是否真能匹配到目标方法RunWith(SpringJUnit4ClassRunner.class) ContextConfiguration(locations {classpath:spring-mvc.xml}) public class HandlerMappingTest { Autowired private RequestMappingHandlerMapping handlerMapping; Test public void testUrlMapping() throws Exception { // 构造一个MockHttpServletRequest模拟GET /user/123 MockHttpServletRequest request new MockHttpServletRequest(GET, /user/123); request.setParameter(name, zhangsan); request.addParameter(age, 25); // DispatcherServlet调用此方法获取HandlerExecutionChain HandlerExecutionChain chain handlerMapping.getHandler(request); assertNotNull(Handler not found for /user/123, chain); assertNotNull(Handler is null, chain.getHandler()); // 验证Handler是否为HandlerMethod类型 assertTrue(chain.getHandler() instanceof HandlerMethod); HandlerMethod handlerMethod (HandlerMethod) chain.getHandler(); // 断言Controller类和方法名 assertEquals(UserController, handlerMethod.getBeanType().getSimpleName()); assertEquals(detail, handlerMethod.getMethod().getName()); // 断言PathVariable参数已解析 MapString, String uriTemplateVars (MapString, String) ReflectionTestUtils.getField(chain, uriTemplateVars); assertNotNull(uriTemplateVars); assertEquals(123, uriTemplateVars.get(id)); } }这个测试强制你直面HandlerExecutionChain对象——它不仅是Handler目标方法还包含HandlerInterceptor链。如果测试失败说明你的RequestMapping(/user/{id})写错了位置或PathVariable(id)没加或mvc:annotation-driven /没启用。这是比重启Tomcat更高效的排错方式。4. 视图解析与Model传递为什么return user/list能跳转到/user/list.jspreturn user/list这行代码背后是ViewResolver在工作。它不关心Controller返回什么字符串只负责把逻辑视图名logical view name转成物理视图physical view比如user/list→/WEB-INF/jsp/user/list.jsp。而Model数据的传递则依赖Model或ModelMap接口的实现类在DispatcherServlet.doDispatch()中被注入到ModelAndView对象里。4.1 InternalResourceViewResolverJSP时代的标准答案对于传统JSP项目InternalResourceViewResolver是最常用视图解析器。它通过前缀prefix和后缀suffix拼接出真实路径bean classorg.springframework.web.servlet.view.InternalResourceViewResolver property nameviewClass valueorg.springframework.web.servlet.view.JstlView/ property nameprefix value/WEB-INF/jsp// property namesuffix value.jsp/ property nameorder value1/ /beanviewClassJstlView启用JSTL标签支持如c:if、fmt:formatDate若不用JSTL可设为InternalResourceView。order1确保它在其他ViewResolver如BeanNameViewResolver之后执行。关键点prefix和suffix是硬编码路径必须与实际Web目录结构严格一致。常见错误是prefix/jsp/少/WEB-INF导致JSP被外部直接访问造成源码泄露风险。4.2 Model数据如何从Controller流到JSP页面Controller方法签名中Model、ModelMap、MapString, Object、ModelAndView均可接收模型数据。它们最终都被统一包装为ExtendedModelMap再由DispatcherServlet注入到ModelAndView中。Controller public class UserController { RequestMapping(/user/list) public String listUsers(Model model) { ListUser users userService.findAll(); model.addAttribute(users, users); // keyusers, valueusers model.addAttribute(title, 用户列表); // 可链式调用 return user/list; // 逻辑视图名 } }在/WEB-INF/jsp/user/list.jsp中通过EL表达式取值% page contentTypetext/html;charsetUTF-8 % html body h2${title}/h2 c:forEach items${users} varu pID: ${u.id}, Name: ${u.name}/p /c:forEach /body /html注意${users}能取到是因为InternalResourceViewResolver创建的JstlView在renderMergedOutputModel()中将Model中的key-value对通过request.setAttribute(key, value)全部塞进了HttpServletRequest作用域。因此JSP中${xxx}本质是request.getAttribute(xxx)。这也是为什么redirect:前缀会丢失Model——重定向是两次HTTP请求第一次的request在响应后即销毁第二次请求的request是全新的。4.3 Redirect与Forward的本质区别一次请求 vs 两次请求这是新手最容易混淆的概念。SpringMVC中return redirect:/user/success→ 发送HTTP 302响应浏览器发起新请求原Model丢失return forward:/user/detail→ 服务器端内部跳转同一请求Model仍有效。验证方式在Controller中添加日志RequestMapping(/user/redirect) public String redirectDemo(Model model) { model.addAttribute(msg, This will be LOST); System.out.println(Before redirect: model.asMap()); // {msgThis will be LOST} return redirect:/user/success; } RequestMapping(/user/success) public String successPage(Model model) { System.out.println(In success: model.asMap()); // {} return success; }若需重定向时传参必须用RedirectAttributespublic String redirectDemo(RedirectAttributes attrs) { attrs.addFlashAttribute(msg, This will survive redirect); return redirect:/user/success; }addFlashAttribute()将数据存入FlashMap由FlashMapManager在重定向后的第一次请求中恢复到Model。这是SpringMVC提供的“后悔药”但仅限一次请求有效。5. 避坑指南五个血泪经验总结的SpringMVC高频翻车现场SpringMVC看似简单但每个环节都有隐藏陷阱。以下是我在多个项目中亲手踩过、调试数小时才定位的5个典型问题按“现象→原因→解决”结构整理拒绝模糊描述。5.1 现象Controller方法正常执行但返回JSON时浏览器显示下载弹窗而非渲染JSON原因ResponseBody方法返回对象但MappingJackson2HttpMessageConverter未注册或Content-Type未正确设置。常见于手动配置mvc:annotation-driven /被注释或messageConverters中缺少JSON converter。解决检查spring-mvc.xml中是否启用mvc:annotation-driven /若手动配置RequestMappingHandlerAdapter确保messageConverters列表包含MappingJackson2HttpMessageConverter且其supportedMediaTypes包含application/json;charsetUTF-8。同时确认Controller方法上有ResponseBody或类上加RestController。5.2 现象PathVariable(id) Long id参数始终为nullURL却是/user/123原因PathVariable默认按参数名匹配但编译后Java字节码中参数名丢失未加-parameters编译选项导致Spring无法识别id对应URL中的{id}。解决在pom.xml中为maven-compiler-plugin添加compilerArgsarg-parameters/arg/compilerArgs或显式指定PathVariable(id)强制绑定或改用PathVariable Long idSpring 4.3支持前提是编译参数开启。5.3 现象Valid校验不生效BindingResult始终为空且无任何错误日志原因BindingResult必须紧跟在被校验对象之后顺序不能错。例如public String save(Valid User user, Model model, BindingResult result)是正确的若写成public String save(Valid User user, BindingResult result, Model model)则result将无法捕获错误。解决严格遵守Valid对象与BindingResult相邻且BindingResult在后。同时确认spring-mvc.xml中启用了mvc:annotation-driven /它会自动注册Validator和DataBinder。5.4 现象静态资源CSS/JS/IMG404但Controller请求正常原因servlet-mapping配置为url-pattern//url-pattern导致所有请求包括/static/css/app.css都被DispatcherServlet拦截而DispatcherServlet找不到对应Handler返回404。解决在spring-mvc.xml中添加资源处理配置mvc:resources mapping/static/** location/static/ / !-- 或显式配置 -- bean classorg.springframework.web.servlet.resource.ResourceHttpRequestHandler property namelocations value/static/ / /bean并在web.xml中确保DispatcherServlet的url-pattern不拦截静态资源路径通常用/即可mvc:resources会自动排除。5.5 现象Transactional在Service方法上但数据库操作无事务回滚无效原因Service Bean被定义在spring-mvc.xmlWeb上下文中而tx:annotation-driven /配置在spring-root.xml根上下文中导致事务切面无法代理Web上下文中的Bean。解决将tx:annotation-driven /移到spring-root.xml并将所有Service、DAO、DataSource等Bean定义在spring-root.xml中确保spring-mvc.xml中只定义Controller、HandlerMapping等Web专属Bean。这是分层架构的铁律不可妥协。6. 进阶技巧用Filter ThreadLocal实现全链路请求ID透传与日志染色在真实项目中一个HTTP请求可能横跨多个Controller、Service、DAO甚至远程调用。若想在日志中快速定位某次请求的完整执行轨迹必须给每次请求打上唯一ID并让整个调用链共享。SpringMVC本身不提供此能力但我们可以用标准Servlet Filter ThreadLocal轻量实现且完全兼容现有代码。6.1 编写TraceIdFilter在请求入口生成并注入TraceIDComponent public class TraceIdFilter implements Filter { private static final String TRACE_ID_HEADER X-Trace-ID; Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; String traceId httpRequest.getHeader(TRACE_ID_HEADER); if (traceId null || traceId.trim().isEmpty()) { traceId UUID.randomUUID().toString().replace(-, ); } // 将traceId绑定到当前线程 MDC.put(traceId, traceId); try { chain.doFilter(request, response); } finally { // 清理ThreadLocal防止线程复用导致ID污染 MDC.remove(traceId); } } }注意MDCMapped Diagnostic Context是Logback/Log4j2提供的线程级日志上下文MDC.put(traceId, traceId)后所有该线程内打印的日志都会自动带上traceIdxxx字段。MDC.remove()必须放在finally块中否则Tomcat线程池复用时旧traceId会污染新请求。6.2 在web.xml中注册Filter确保早于DispatcherServlet执行filter filter-nametraceIdFilter/filter-name filter-classcom.example.filter.TraceIdFilter/filter-class /filter filter-mapping filter-nametraceIdFilter/filter-name url-pattern/*/url-pattern dispatcherREQUEST/dispatcher /filter-mappingdispatcherREQUEST/dispatcher确保只对直接HTTP请求生效不拦截forward或include。url-pattern/*/url-pattern必须覆盖所有路径包括静态资源但静态资源Filter会短路不影响性能。6.3 日志格式改造让traceId成为每行日志的固定前缀修改logback-spring.xml中的patternappender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{HH:mm:ss.SSS} [%thread] [%X{traceId:-NA}] %-5level %logger{36} - %msg%n/pattern /encoder /appender%X{traceId:-NA}表示取MDC中key为traceId的值若不存在则显示NA。效果如下14:22:31.456 [http-nio-8080-exec-2] [a1b2c3d4e5f67890] INFO c.e.c.UserController - Entering listUsers 14:22:31.458 [http-nio-8080-exec-2] [a1b2c3d4e5f67890] DEBUG c.e.s.UserService - Fetching users from DB现在只要拿到任意一行日志里的traceId就能用grep a1b2c3d4e5f67890搜出本次请求的全部日志无论它经过多少Controller、Service、DAO甚至跨线程需配合MDC.getCopyOfContextMap()传递。6.4 Controller中主动记录traceId用于前端调试与问题反馈在Controller中你可以把traceId返回给前端方便用户报障时提供Controller public class BaseController { ModelAttribute public void addTraceId(Model model) { String traceId MDC.get(traceId); model.addAttribute(traceId, traceId); } } Controller public class UserController extends BaseController { RequestMapping(/user/list) public String list(Model model) { // 此时model中已有traceId return user/list; } }这样/user/list.jsp中可直接显示div stylefont-size:12px;color:#999TraceID: ${traceId}/div用户截图报障时这个ID就是你日志检索的黄金钥匙。从那以后我每次搭建新SpringMVC项目第一件事就是加TraceIdFilter和MDC日志格式。它不改变任何业务逻辑却让线上问题排查效率提升3倍以上——因为不再需要靠时间戳猜哪几行日志属于同一次请求。希望帮到你。本文还有配套的精品资源点击获取