SpringMVC入门程序全拆解：从请求流转到配置实战

第一次接触SpringMVC的入门程序很多人下意识会把它当成一个“页面跳转Demo”跑通了就丢在一边。但说句实在话这个入门小项目恰恰是整个SpringMVC框架最值得反复咀嚼的部分。一个最普通的请求从浏览器发出去之后要先被DispatcherServlet接住再由HandlerMapping找到对应的Controller方法方法处理完返回一个视图名最后视图解析器把它拼成一个真实的JSP路径。这中间每一步错位都会导致404或者500。如果你刚学完Servlet准备往SpringMVC过渡以及平时直接上手SpringBoot、却想回头把Web层请求流转机制补明白这篇文章就是给你准备的。我会按照真实的项目实战流程从设计思路、核心配置、实操搭建到问题排查把一个入门项目彻底拆开来讲。1. 项目实战前的整体设计思路1.1 为什么选择SpringMVC作为Web层框架在没接触SpringMVC之前写Servlet大概是这样的必须继承HttpServlet重写doGet/doPost手动从request里getParameter拿参数再手动做类型转换处理完数据后转发或者重定向。代码一多每个Servlet都是一个“参数中转站”业务逻辑和Web层耦合得非常严重。而SpringMVC解决的核心问题就是把开发人员的注意力从“处理HTTP细节”拉回到“写业务方法”上。它基于前端控制器模式所有请求统一交给DispatcherServlet再由它分发给具体的Controller方法。有人可能会问为什么不直接用Struts2我个人的感受是SpringMVC的方法级映射比类级映射更直观而且它跟Spring的IoC容器是同一个体系写起来不用做多余的集成工作。再加上SpringMVC支持注解驱动、RESTful风格、参数自动绑定非常适合做管理后台和接口服务。并不是说别的框架不能用而是从学习成本和维护成本来看SpringMVC是Java Web开发里很稳妥的一站式选择。选型这件事关键不在“哪个框架更好”而在于“为什么需要这个框架”。SpringMVC最核心的价值是帮你把请求、参数、响应、视图这些琐碎的Web概念变成一个个普通的方法签名和方法返回值。你只要关注方法里怎么处理数据剩下的交给框架完成。这样的设计思路在入门程序里体现得最完整。1.2 入门程序的功能定位这个入门程序不能只做一个“Hello World”那样学不到东西。我当时设计的案例是页面上有一个文本框用户输入一个名字点击提交之后SpringMVC接收参数并把这个名字带到后端的欢迎页面显示出来。功能虽然简单但涉及的粒度很完整包括页面的提交、请求映射、参数绑定、Model传值、视图解析、JSP渲染。为什么要用表单而不直接访问一个带参数的URL因为表单提交可以直观地展示POST请求的处理方式也方便后续讲解中文字符乱码问题。你还可以通过这个案例分别测试POST和GET两种请求方式的差异。一个入门项目如果能把“用户输入数据 - 服务器接收处理 - 返回结果页”这条链路走明白后面再接触注解开发、JSON交互就有了基础。在设计项目文件夹时我建议尽量按照标准Maven工程结构来建即使你是新手也不要图省事用IDE自带的简易Web工程模板。标准结构的好处是后期扩展不用大改目录而且团队协作时大家的上手成本更低。1.3 开发环境与工具选型先说一下版本组合稳定优先。我常用的组合是JDK 1.8、Maven 3.6、Spring 5.3.x、Tomcat 8.5或9IDE用你熟悉的版本即可。这套组合没有太激进的新特性教程也多遇到问题容易搜到答案。依赖方面核心只需要两个spring-webmvc和javax.servlet-api。spring-webmvc本身会带一部分Spring核心依赖Maven会帮你传递引入。javax.servlet-api作用域必须设置为provided因为它只在编译时使用运行时会由Tomcat提供避免了容器内Servlet版本冲突。关于Tomcat和Spring的兼容性Spring 5.3.x对Servlet 3.1支持得很好Tomcat 8.5对应Servlet 3.1Tomcat 9对应Servlet 4.0都没问题。如果你还在用Tomcat 7建议升一下否则有些注解和异步特性用不了。开发过程中如果你的IDE部署比较慢建议给Tomcat多分点内存这个后面在坑点部分会提到。2. 核心配置与关键组件解析2.1 web.xml中的DispatcherServlet配置传统SpringMVC项目依然需要web.xml因为Servlet容器启动时必须知道SpringMVC的控制中心入口在哪。DispatcherServlet就是一个标准Servlet它在web.xml里的配置也很直白web-app xmlnshttp://xmlns.jcp.org/xml/ns/javaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd version4.0 servlet servlet-namespringmvc/servlet-name servlet-classorg.springframework.web.servlet.DispatcherServlet/servlet-class init-param param-namecontextConfigLocation/param-name param-valueclasspath:springmvc.xml/param-value /init-param load-on-startup1/load-on-startup /servlet servlet-mapping servlet-namespringmvc/servlet-name url-pattern//url-pattern /servlet-mapping /web-app这里每个节点都值得琢磨。contextConfigLocation告诉DispatcherServlet加载哪个Spring配置文件如果不配置框架会默认去找/WEB-INF/springmvc-servlet.xml新手容易因为默认路径对不上而一脸懵所以最好显式配置成classpath:springmvc.xml。load-on-startup设成1表示Tomcat启动时立刻初始化这个Servlet而不是等第一个请求进来再初始化这样可以把启动阶段的问题提前暴露出来也让首次访问更快。url-pattern为什么是/而不是/*我记得第一次写的时候用了/*结果所有JSP页面都被DispatcherServlet拦下来了成了一个典型的“模型二”灾难现场。/会拦截除JSP之外的请求把静态资源和JSP交给容器默认处理而/*会把hello.jsp这种请求也当作Controller路径去匹配匹配不到就直接404。所以入门阶段请老老实实用/。2.2 SpringMVC配置文件详解接下来是核心配置文件springmvc.xml我习惯放在src/main/resources下面。一个最小可用的配置长这样?xml version1.0 encodingUTF-8? beans xmlnshttp://www.springframework.org/schema/beans xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:contexthttp://www.springframework.org/schema/context xmlns:mvchttp://www.springframework.org/schema/mvc xsi:schemaLocationhttp://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd context:component-scan base-packagecom.example.controller/ mvc:annotation-driven/ bean classorg.springframework.web.servlet.view.InternalResourceViewResolver property nameprefix value/WEB-INF/views// property namesuffix value.jsp/ /bean /beanscomponent-scan用来扫描Controller只有被扫描进来的类里面的Controller和RequestMapping才会生效。mvc:annotation-driven这行极其重要它的作用是注册RequestMappingHandlerMapping和RequestMappingHandlerAdapter简单说就是让注解映射、参数绑定、返回JSON这些功能真正跑起来。我见过好几个人把配置文件写完之后页面一直报404控制台提示某个andler不存在就是因为少了这行。视图解析器InternalResourceViewResolver负责把Controller返回的字符串逻辑视图名拼接成物理视图路径。比如return hello最后解析出来就是/WEB-INF/views/hello.jsp。这里要注意一个细节prefix路径最前面必须带/而且结尾要有/。少写一个斜杠要么找不到文件要么拼出来的地址不对劲。如果把JSP放在WEB-INF下面外部浏览器是没法直接访问的只有通过SpringMVC的转发才能渲染这对安全性有一定帮助。如果你在页面里引用了CSS或JS文件还要在配置里加一个默认Servlet处理器mvc:default-servlet-handler/让静态资源请求绕过DispatcherServlet。否则你会发现页面样式全部丢了网络请求全是404。2.3 控制器的编写规范入门程序的Controller不需要太花哨但基本规范要懂。先看代码package com.example.controller; import org.springframework.stereotype.Controller; import org.springframework.ui.Model; import org.springframework.web.bind.annotation.RequestMapping; Controller RequestMapping(/hello) public class HelloController { RequestMapping(/show) public String show(String username, Model model) { model.addAttribute(username, username); return hello; } }类上加了Controller让Spring容器把他识别为一个Web层的Bean同时具备处理请求的能力。类级别的RequestMapping(/hello)是模块前缀方法级别的RequestMapping(/show)是具体访问路径。组合起来外部访问的URL应该是http://localhost:8080/你的项目名/hello/show。方法参数里直接写String username框架会自动从请求参数中取同名参数并赋值。这就是SpringMVC的参数绑定背后靠的是反射和类型转换器不需要手动getParameter(username)。Model对象用来往视图传数据相当于把数据放进request域JSP里可以通过EL表达式取出来。为什么这里用Controller而不是RestController因为我们的目标是返回一个视图页面。RestController是Controller和ResponseBody的组合所有返回值都会直接写进响应体适合返回JSON字符串不适合渲染JSP。入门阶段先把Controller用明白后面做接口再切换。关于返回值类型除了返回String还可以返回ModelAndView不过我觉得String配合Model更容易理解“视图名”这个概念。方法上标注的RequestMapping如果不指定请求方式那么GET和POST都能访问。如果你想限定可以写成RequestMapping(value /show, method RequestMethod.POST)但入门案例建议先不限定方便用不同方式测试。3. 实操过程从零搭建一个完整入门程序3.1 创建项目与目录结构我建议用Maven创建一个war包项目目录结构如下src/main/java/com/example/controller/HelloController.java src/main/resources/springmvc.xml src/main/webapp/WEB-INF/web.xml src/main/webapp/WEB-INF/views/hello.jsp src/main/webapp/index.jsppom.xml里至少需要四类配置项目坐标、打包方式、依赖和Tomcat插件。依赖部分参考这样dependencies dependency groupIdorg.springframework/groupId artifactIdspring-webmvc/artifactId version5.3.20/version /dependency dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version4.0.1/version scopeprovided/scope /dependency dependency groupIdjavax.servlet/groupId artifactIdjstl/artifactId version1.2/version /dependency /dependencies这里为什么要把JSP页面放到WEB-INF/views下面如果放在webapp根目录用户可以直接通过URL访问到页面但这不符合MVC的视图隔离思想。放到WEB-INF后用户只访问Controller地址由Controller决定渲染哪个视图这样更容易控制页面的展示逻辑和访问权限。另外提醒一句如果你用IDEA创建的是普通Java工程记得在项目结构里把webapp目录标记成Web资源目录并添加Web Facet否则Tomcat部署之后访问不到页面。这个小细节经常让新手卡半天页面代码写了却始终404一定要重视。3.2 编写页面与控制器index.jsp作为首页提供一个表单提交到hello/show% page contentTypetext/html;charsetUTF-8 languagejava % html head titleSpringMVC入门/title /head body h2SpringMVC入门程序/h2 form action${pageContext.request.contextPath}/hello/show methodpost label姓名input typetext nameusername/label input typesubmit value提交 /form /body /html注意${pageContext.request.contextPath}的作用是动态拼上项目上下文路径。如果你直接写action/hello/show而发布后的应用名是springmvc-demo那么这个表单就会提交到http://localhost:8080/hello/show少了项目名必然404。用EL表达式拼上下文路径才是保险写法。Controller方法接收参数后通过Model把数据传给视图。如果用户什么都没填直接提交username会是nullJSP页面会显示“null”。为了避免这种尴尬可以用RequestParam指定默认值public String show(RequestParam(value username, defaultValue 访客) String username, Model model)RequestParam还能帮你做校验比如required true时请求缺参数直接报400。入门阶段知道有这层控制就行后面再深入。接着写hello.jsp% page contentTypetext/html;charsetUTF-8 languagejava % html head title欢迎页/title /head body h2你好${username}/h2 a href${pageContext.request.contextPath}/index.jsp返回/a /body /html这里有一个中文字符乱码的经典坑。如果你是POST提交并且没有配置编码过滤器Controller拿到手的username大概率是乱码JSP页面上也会跟着乱码。解决办法是在web.xml里加一个Spring提供的编码过滤器filter filter-namecharacterEncodingFilter/filter-name filter-classorg.springframework.web.filter.CharacterEncodingFilter/filter-class init-param param-nameencoding/param-name param-valueUTF-8/param-value /init-param /filter filter-mapping filter-namecharacterEncodingFilter/filter-name url-pattern/*/url-pattern /filter-mapping这个过滤器实际上就是设置request.setCharacterEncoding(UTF-8)。不写它的话现代Tomcat 8对GET请求的UTF-8处理还算正常但POST请求会根据默认编码ISO-8859-1解析中文就废了。3.3 启动调试与访问流程把应用部署到Tomcat后启动控制台一般会看到Spring容器的加载日志以及映射信息。Spring会打出类似Mapped {[/hello/show],methods[GET/POST]}这样的日志说明Controller方法已经成功注册。接下来在浏览器访问http://localhost:8080/springmvc-demo/index.jsp输入名字提交或者直接访问http://localhost:8080/springmvc-demo/hello/show?usernameTom你就会看到欢迎页面。整个请求流转可以整理成下面这张表步骤责任组件实际动作1. 接收请求DispatcherServlet拦截/hello/show请求2. 查找处理器HandlerMapping匹配HelloController.show方法3. 执行方法Controller参数绑定、添加Model数据、返回hello4. 视图解析ViewResolver把hello解析成/WEB-INF/views/hello.jsp5. 视图渲染JSP渲染HTML返回给浏览器调试这个流程最快的办法是在HelloController.show方法第一行打个断点然后在DispatcherServlet里再打一个断点分两次观察。你会看到请求先进DispatcherServlet处理完映射关系后进入你的Controller方法等返回后又会回到DispatcherServlet继续执行视图解析。我建议新手用DEBUG模式跑一遍跟着断点把调用栈展开几次。第一次展开会觉得繁琐但多看几遍就能形成肌肉记忆以后不管用注解开发还是纯Java配置遇到请求问题都能第一时间定位到哪一步断了。4. 常见问题与排查技巧实录4.1 常见异常集合写SpringMVC入门程序最容易见的异常无非那么几种。先整理一个速查表后面再逐个说细节现象可能原因解决方向访问任何路径都404web.xml的url-pattern有误或项目没部署成功检查部署结构和请求路径页面404控制台有映射日志请求路径拼错或视图文件不存在核对前缀、后缀和文件名500ClassNotFoundException: DispatcherServletspring-webmvc依赖缺失或没有打包进war检查Maven依赖400Required String parameter username is not present请求参数缺nameRequestParam必填检查表单控件name属性中文乱码缺少CharacterEncodingFilter配置UTF-8过滤器静态资源CSS、JS全404/拦截了静态资源请求加default-servlet-handler其中HTTP 404最迷惑人。它不是完全没反应比如URL打错了返回的404和视图文件找不到返回的404虽然状态码一样但排查路径不同。前者要看Tomcat控制台有没有日志、有没有映射信息后者要看/WEB-INF/views/下面是不是真的存在那个JSP文件。4.2 排查思路与调试技巧我自己的排查习惯固定成三步很管用。第一步看浏览器Network。确认请求URL是不是完全正确上下文路径、方法名、参数名有没有写错。请求状态码是404、405还是500直接决定下一步方向。如果是405十有八九是请求方式不匹配你表单写POST但方法限定为GET。第二步看IDEA控制台日志。SpringMVC启动成功后日志里会有明确的映射信息。如果你没看到Mapped {[/hello/show]...}说明Controller没有被扫描到。这时候去检查component-scan的包路径是不是写错了或者Controller类上没有加Controller。如果日志里出现异常堆栈从最下面的Caused by看那才是根因。第三步开DEBUG断点跟着请求走。入门项目就这么几个类断点直接打在DispatcherServlet.doService或者Controller方法上配合前后端请求基本能看出是哪一层出了问题。说句实在话与其在那里猜不如断点看一眼效率高得多。日志级别也要学会开。在src/main/resources下面放一个log4j2.xml或logback.xml把SpringWeb包的日志级别调到DEBUG你能看到请求每次进出的完整链路。等到你熟练掌握之后再关掉DEBUG避免刷屏。4.3 开发中容易踩的坑我见过很多新手在入门项目上反复折腾踩的坑高度雷同。第一个坑就是忘写mvc:annotation-driven然后某些注解功能不生效报了错也不知道去哪里找。这个标签从Spring 3.0开始就是标配缺少它等于告诉Spring注解映射我不需要你可以手动配一堆HandlerMapping。第二个坑是视图解析器的前缀写错。比如/WEB-INF/views少了末尾斜杠或者前面的/丢了导致跳转时路径变成WEB-INF/views/hello.jsp从根目录找肯定找不到。这个错误很小但极容易看漏。第三个坑跟Tomcat部署有关。有时候改了Java代码IDE没有自动编译Tomcat还在跑旧版本。我遇到过满怀信心地访问新页面结果一直404最后发现是忘了rebuild。解决方法是养成每次启动前先clean一下项目的习惯或者直接重启Tomcat验证。第四个坑是上下文路径引起的问题。如果你用IDEA部署时写的Application context是/springmvc-demo那么URL前缀必须带这个路径。很多教程里代码写的是不带上下文的路径你照抄后发现404不代表框架有问题只是缺少上下文前缀。使用${pageContext.request.contextPath}就能从根上规避。第五个坑是JSP文件的编码。页面文件本身如果不是UTF-8保存即使代码里写了charsetUTF-8也会乱。所以最好先在IDE设置里把默认文件编码改成UTF-8再写代码而不是等乱码了才去折腾。5. 进阶扩展建议5.1 从入门到进阶的路线入门程序跑通之后接下来该学什么很多人喜欢直接冲SpringBoot但我个人觉得如果把SpringMVC再往深走几步后续会顺畅很多。可以先从参数的多样式接收开始比如PathVariable做RESTful风格URLRequestBody做JSON接收ResponseBody做JSON返回这些都是接口开发绕不开的能力。然后可以研究返回值类型和响应状态。比如返回ResponseEntity可以自定义响应体和状态码返回void配合HttpServletResponse直接写数据异常处理用ControllerAdvice和ExceptionHandler统一处理。这些内容从表面看都是独立知识点但本质上都是围绕“DispatcherServlet怎么处理返回值”展开的。接着建议把RESTful风格设计能力补上。比如用GetMapping、PostMapping替代原来的RequestMapping结合PathVariable实现干净的URL。这一步学完之后你再打开一个SpringBoot项目看到RestController接口就不会觉得神秘了。5.2 参数绑定与JSON交互入门程序的参数绑定是从request自动拆包的到了JSON交互思路要反过来。前端通过AJAX提交一个JSON字符串后端要靠RequestBody把JSON自动反序列化成Java对象。举个例子你定义一个User类public class User { private String name; private Integer age; // 省略getter/setter }Controller里这样写RestController public class UserController { PostMapping(/user) public User getUser(RequestBody User user) { return user; } }返回的User对象会被自动序列化成JSON。这里要求Spring容器里必须有MappingJackson2HttpMessageConverter而在Spring MVC里只要配置了mvc:annotation-driven并引入了Jackson依赖这个转换器会自动注册。依赖如下dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.9.8/version /dependency建议你从入门程序延伸出一个AJAX小案例让页面发送JSON数据到ControllerController处理后返回一个JSON对象页面用JavaScript渲染到某个标签里。做一遍你对“请求处理、数据转换、响应组装”三个环节的理解会彻底巩固。做这个练习时还要注意POST请求的Content-Type必须设成application/json;charsetUTF-8如果你还按表单的application/x-www-form-urlencoded提交后端RequestBody会解析不到内容得到的对象全是null。这一点是很多新手踩完坑才记住的。我个人在实际带项目时的体会是SpringMVC入门程序不只是一个HelloWorld它是一个帮助你建立“请求流转全景图”的最好素材。把这张图印在脑子里往后你学SpringBoot也好学云原生框架也好哪怕换一门语言做Web开发思路都是通的。最后再分享一个小技巧写完这个程序后刻意改错几个地方比如把Controller去掉、把mvc:annotation-driven注释掉、把视图后缀改成.html然后逐个观察报错现象。这个过程会让你比跑通一百遍HelloWorld还管用。