1. 项目概述作为一名Java后端开发者我经常被问到如何快速上手Spring MVC框架。今天我就用最接地气的方式带大家从零搭建一个能打招呼的Spring MVC项目。这个项目虽然简单但涵盖了Spring MVC最核心的组件和工作流程是理解这个框架的绝佳切入点。Spring MVC作为Spring框架的Web模块采用了经典的前端控制器模式。它的核心思想是将请求处理流程分解为多个职责分明的组件每个组件只关注自己的特定功能。这种设计使得整个框架既灵活又易于扩展这也是为什么它能在企业级开发中如此流行。2. 环境准备2.1 开发工具选择对于这个入门项目我推荐使用以下工具组合IDEIntelliJ IDEA社区版就够用或Eclipse构建工具Maven版本3.6JDKJava 8或11Servlet容器内嵌Tomcat通过Maven插件运行提示如果你刚开始学习Java Web开发建议直接使用IntelliJ IDEA它对Maven和Spring的支持非常友好能减少很多配置上的麻烦。2.2 项目结构规划在开始编码前我们先规划下项目的基本结构。一个标准的Maven Web项目通常包含以下目录springmvc-demo ├── src │ ├── main │ │ ├── java # Java源代码 │ │ ├── resources # 配置文件 │ │ └── webapp # Web资源 │ │ ├── WEB-INF │ │ └── index.jsp └── pom.xml # Maven配置文件3. 项目搭建3.1 创建Maven项目首先在你的IDE中创建一个新的Maven项目。选择maven-archetype-webapp作为原型这会自动生成基本的Web项目结构。3.2 配置pom.xml接下来是配置项目的核心依赖。打开pom.xml文件添加以下内容project !-- 基本项目信息 -- modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdspringmvc-demo/artifactId version1.0-SNAPSHOT/version packagingwar/packaging properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target spring.version5.3.20/spring.version /properties dependencies !-- Spring MVC核心依赖 -- dependency groupIdorg.springframework/groupId artifactIdspring-webmvc/artifactId version${spring.version}/version /dependency !-- JSP支持 -- dependency groupIdjavax.servlet/groupId artifactIdjstl/artifactId version1.2/version /dependency dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version4.0.1/version scopeprovided/scope /dependency !-- 内嵌Tomcat插件 -- dependency groupIdorg.apache.tomcat.embed/groupId artifactIdtomcat-embed-core/artifactId version9.0.62/version /dependency /dependencies build plugins !-- 用于运行项目的Tomcat插件 -- plugin groupIdorg.apache.tomcat.maven/groupId artifactIdtomcat7-maven-plugin/artifactId version2.2/version configuration port8080/port path//path /configuration /plugin /plugins /build /project注意这里我们使用了Spring 5.3.20版本这是目前比较稳定的一个版本。如果你需要与其他Spring组件如Spring Security集成建议保持所有Spring依赖的版本一致。4. 核心组件实现4.1 创建首页(index.jsp)在src/main/webapp目录下创建index.jsp文件% page contentTypetext/html;charsetUTF-8 languagejava % html head titleSpring MVC Demo/title /head body h2Spring MVC入门示例/h2 a hrefhello点击这里向师姐打招呼/a /body /html这个简单的JSP页面包含一个超链接点击后会向/hello路径发送请求。4.2 创建控制器(HelloController)在src/main/java下创建包com.example.controller然后新建HelloController类package com.example.controller; import org.springframework.stereotype.Controller; import org.springframework.ui.Model; import org.springframework.web.bind.annotation.GetMapping; Controller public class HelloController { GetMapping(/hello) public String sayHello(Model model) { // 向模型中添加属性 model.addAttribute(message, 师姐你好); // 返回视图名称 return success; } }这个控制器类有几个关键点需要注意Controller注解标识这是一个Spring MVC控制器GetMapping(/hello)映射HTTP GET请求到sayHello方法Model参数用于向视图传递数据方法返回的字符串success对应视图名称4.3 配置Spring MVC(springmvc.xml)在src/main/resources目录下创建springmvc.xml配置文件?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 https://www.springframework.org/schema/context/spring-context.xsd http://www.springframework.org/schema/mvc https://www.springframework.org/schema/mvc/spring-mvc.xsd !-- 开启注解扫描 -- context:component-scan base-packagecom.example.controller/ !-- 开启MVC注解驱动 -- mvc:annotation-driven/ !-- 配置视图解析器 -- bean classorg.springframework.web.servlet.view.InternalResourceViewResolver property nameprefix value/WEB-INF/pages// property namesuffix value.jsp/ /bean /beans这个配置文件做了三件重要的事情启用组件扫描自动发现带有Controller注解的类启用Spring MVC注解驱动配置视图解析器将逻辑视图名解析为具体的JSP文件路径4.4 配置web.xml在src/main/webapp/WEB-INF目录下创建或修改web.xml?xml version1.0 encodingUTF-8? 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 !-- 配置DispatcherServlet -- servlet servlet-namedispatcher/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 !-- 映射所有请求到DispatcherServlet -- servlet-mapping servlet-namedispatcher/servlet-name url-pattern//url-pattern /servlet-mapping /web-app这个配置的核心是声明了Spring MVC的DispatcherServlet它是整个框架的入口点负责接收所有请求并将其分发给相应的处理器。4.5 创建视图页面(success.jsp)在src/main/webapp/WEB-INF/pages目录下创建success.jsp% page contentTypetext/html;charsetUTF-8 languagejava % % taglib prefixc urihttp://java.sun.com/jsp/jstl/core % html head title打招呼/title /head body h1${message}/h1 /body /html这个JSP页面会显示控制器传递过来的message属性值。注意我们使用了JSTL的表达式语言${message}来访问模型数据。5. 运行与测试5.1 启动项目在项目根目录下执行以下Maven命令mvn tomcat7:run或者直接在IDE中配置Tomcat插件运行。启动后控制台会显示类似如下的信息[INFO] Starting Tomcat... [INFO] Starting Servlet Engine: Apache Tomcat/7.0.47 [INFO] Starting ProtocolHandler [http-bio-8080]5.2 访问应用打开浏览器访问http://localhost:8080你应该能看到首页。点击向师姐打招呼链接页面应该跳转并显示师姐你好。6. Spring MVC核心组件详解6.1 DispatcherServlet前端控制器这是Spring MVC的核心负责接收所有HTTP请求并将它们分发给适当的处理器。你可以把它想象成公司的前台接待员所有来访者请求都必须先经过它。6.2 HandlerMapping处理器映射器它负责确定哪个控制器方法应该处理当前请求。Spring提供了多种实现最常用的是基于注解的RequestMappingHandlerMapping它会查找带有RequestMapping及其变体如GetMapping的方法。6.3 HandlerAdapter处理器适配器这个组件负责实际调用处理器方法。对于注解式控制器使用的是RequestMappingHandlerAdapter。它处理方法的参数解析和返回值处理。6.4 ViewResolver视图解析器视图解析器将控制器返回的逻辑视图名解析为实际的视图实现。我们配置的InternalResourceViewResolver会将success解析为/WEB-INF/pages/success.jsp。6.5 View视图视图负责渲染模型数据。在我们的例子中JSP页面就是视图实现它使用JSTL表达式显示控制器传递的数据。7. 常见问题与解决方案7.1 404错误问题描述访问页面时出现404错误。可能原因DispatcherServlet的URL映射配置不正确控制器方法映射路径与请求路径不匹配视图文件位置不正确解决方案检查web.xml中url-pattern的配置确保控制器方法的GetMapping路径与请求路径一致确认JSP文件位于视图解析器配置的路径下7.2 500服务器错误问题描述服务器返回500错误。可能原因缺少必要的依赖JSP页面使用了未定义的变量配置文件中存在错误解决方案检查Maven依赖是否完整确保JSP中所有EL表达式对应的属性都已添加到Model中检查Spring配置文件是否有语法错误7.3 中文乱码问题问题描述页面上显示的中文变成乱码。解决方案确保所有JSP文件都设置了% page contentTypetext/html;charsetUTF-8 %在web.xml中添加字符编码过滤器filter filter-nameencodingFilter/filter-name filter-classorg.springframework.web.filter.CharacterEncodingFilter/filter-class init-param param-nameencoding/param-name param-valueUTF-8/param-value /init-param init-param param-nameforceEncoding/param-name param-valuetrue/param-value /init-param /filter filter-mapping filter-nameencodingFilter/filter-name url-pattern/*/url-pattern /filter-mapping8. 项目优化建议8.1 使用Java配置替代XML现代Spring项目更推荐使用Java配置。我们可以创建一个配置类来替代springmvc.xmlConfiguration EnableWebMvc ComponentScan(com.example.controller) public class WebConfig implements WebMvcConfigurer { Bean public ViewResolver viewResolver() { InternalResourceViewResolver resolver new InternalResourceViewResolver(); resolver.setPrefix(/WEB-INF/pages/); resolver.setSuffix(.jsp); return resolver; } }然后在web.xml中修改DispatcherServlet的配置servlet servlet-namedispatcher/servlet-name servlet-classorg.springframework.web.servlet.DispatcherServlet/servlet-class init-param param-namecontextClass/param-name param-valueorg.springframework.web.context.support.AnnotationConfigWebApplicationContext/param-value /init-param init-param param-namecontextConfigLocation/param-name param-valuecom.example.config.WebConfig/param-value /init-param /servlet8.2 添加静态资源处理默认情况下DispatcherServlet会拦截所有请求包括对静态资源如CSS、JS文件的请求。我们需要在配置中添加静态资源处理在XML配置中mvc:resources mapping/resources/** location/resources//或者在Java配置中Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/resources/**) .addResourceLocations(/resources/); }8.3 使用Thymeleaf替代JSP现代Spring项目更推荐使用Thymeleaf作为模板引擎。要使用Thymeleaf首先添加依赖dependency groupIdorg.thymeleaf/groupId artifactIdthymeleaf-spring5/artifactId version3.0.15.RELEASE/version /dependency然后配置Thymeleaf视图解析器Bean public SpringResourceTemplateResolver templateResolver() { SpringResourceTemplateResolver resolver new SpringResourceTemplateResolver(); resolver.setPrefix(/WEB-INF/views/); resolver.setSuffix(.html); resolver.setTemplateMode(HTML); return resolver; } Bean public SpringTemplateEngine templateEngine() { SpringTemplateEngine engine new SpringTemplateEngine(); engine.setTemplateResolver(templateResolver()); return engine; } Bean public ThymeleafViewResolver viewResolver() { ThymeleafViewResolver resolver new ThymeleafViewResolver(); resolver.setTemplateEngine(templateEngine()); return resolver; }9. 深入理解请求处理流程为了更好地掌握Spring MVC我们需要理解一个请求从发起到响应的完整流程请求到达用户发起HTTP请求被DispatcherServlet捕获确定处理器HandlerMapping根据请求URL找到对应的Controller方法执行拦截器如果有配置拦截器会按顺序执行preHandle方法调用处理器HandlerAdapter调用实际的Controller方法处理返回值HandlerAdapter处理方法的返回值可能是ModelAndView、String或ResponseEntity等渲染视图ViewResolver解析视图名View渲染模型数据后置处理拦截器的postHandle方法被执行完成请求最终响应发送给客户端理解这个流程对于调试和扩展Spring MVC应用非常重要。当遇到问题时你可以按照这个流程逐步排查看看是在哪个环节出现了问题。10. 实际开发中的经验分享在实际项目中使用Spring MVC多年我总结了一些有价值的经验控制器设计原则保持控制器精简只处理HTTP相关的逻辑业务逻辑应该放在Service层一个控制器最好只负责一个资源或功能领域异常处理使用ControllerAdvice全局处理异常为不同的异常类型提供友好的错误页面记录详细的错误日志测试建议使用Spring的MockMvc测试控制器编写集成测试验证完整的请求处理流程测试各种边界情况和错误场景性能优化合理使用缓存页面缓存、数据缓存启用GZIP压缩优化视图渲染性能安全考虑防止XSS攻击对输出进行编码防止CSRF攻击使用Spring Security的CSRF保护验证所有用户输入这个简单的打招呼项目虽然功能简单但它展示了Spring MVC的核心概念和工作原理。通过这个基础你可以继续探索更复杂的特性如数据绑定、表单处理、文件上传、RESTful服务等。
