SpringMVC快速入门之启动配置流程

SpringMVC作为主流的Web MVC框架，其启动配置是入门的核心。不同于传统的XML配置，现代SpringMVC开发更推荐基于Java配置类的方式，这种方式更灵活且易于维护。本文我将从Servlet容器初始化、SpringMVC环境加载到核心配置类设置，完整解析SpringMVC的启动配置流程，带你快速搭建可运行的SpringMVC应用。

一、SpringMVC启动的核心流程

SpringMVC的启动本质是在Servlet容器中初始化SpringMVC环境，核心流程包括：

1. Servlet容器启动（如Tomcat）：加载Web应用的初始化类；
2. Spring容器初始化：创建SpringMVC的IoC容器，加载配置类和Bean；
3. DispatcherServlet初始化：注册核心组件（处理器映射器、适配器等），接管请求处理；
4. 应用就绪：接收并处理客户端请求。

传统方式通过web.xml配置启动，而现代方式（Servlet 3.0+）可通过Java类完全替代XML，本文将重点讲解基于Java配置的启动方式。

二、环境准备与依赖配置

2.1 开发环境

• JDK：1.8+
• Servlet容器：Tomcat 9.0+（支持Servlet 3.1）
• 构建工具：Maven
• Spring版本：Spring 5.3.x

2.2 Maven依赖配置

创建pom.xml，添加核心依赖（SpringMVC、Servlet API等）：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.example</groupId><artifactId>springmvc-quickstart</artifactId><version>1.0-SNAPSHOT</version><packaging>war</packaging><properties><spring.version>5.3.20</spring.version><servlet.api.version>4.0.1</servlet.api.version></properties><dependencies><!-- SpringMVC核心 --><dependency><groupId>org.springframework</groupId><artifactId>spring-webmvc</artifactId><version>${spring.version}</version></dependency><!-- Servlet API（提供Servlet相关类） --><dependency><groupId>javax.servlet</groupId><artifactId>javax.servlet-api</artifactId><version>${servlet.api.version}</version><scope>provided</scope> <!-- 运行时由容器提供，打包不包含 --></dependency><!-- JSTL（可选，用于JSP页面） --><dependency><groupId>javax.servlet.jsp.jstl</groupId><artifactId>javax.servlet.jsp.jstl-api</artifactId><version>1.2.2</version></dependency></dependencies><!-- 配置Maven编译和打包 --><build><plugins><!-- 编译Java 1.8 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.8.1</version><configuration><source>1.8</source><target>1.8</target></configuration></plugin><!-- 配置Tomcat插件（方便本地运行） --><plugin><groupId>org.apache.tomcat.maven</groupId><artifactId>tomcat9-maven-plugin</artifactId><version>3.0.0</version><configuration><port>8080</port> <!-- 端口 --><path>/</path> <!-- 上下文路径 --></configuration></plugin></plugins></build>
</project>

依赖说明：

• spring-webmvc：包含SpringMVC核心类（如DispatcherServlet）；
• javax.servlet-api：提供Servlet规范相关类（如ServletContext）；
• Tomcat插件：无需本地安装Tomcat，通过mvn tomcat9:run启动应用。

三、初始化Servlet容器：WebApplicationInitializer

Servlet 3.0+支持通过WebApplicationInitializer接口替代web.xml，实现Servlet容器的初始化配置。这个接口的onStartup方法会在容器启动时被调用，用于注册DispatcherServlet和配置过滤器。

3.1 实现WebApplicationInitializer

创建MyWebAppInitializer类，继承AbstractAnnotationConfigDispatcherServletInitializer（Spring提供的抽象类，简化配置）：

package com.example.config;import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;/*** 替代web.xml，初始化Servlet容器*/
public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {/*** 配置根容器的配置类（非Web层Bean，如Service、Dao）* 若无需分层，可返回空数组*/@Overrideprotected Class<?>[] getRootConfigClasses() {return new Class[0]; // 本文简化为单容器，根容器为空}/*** 配置SpringMVC容器的配置类（Web层Bean，如Controller、视图解析器）*/@Overrideprotected Class<?>[] getServletConfigClasses() {return new Class[]{SpringMvcConfig.class}; // 指定SpringMVC配置类}/*** 配置DispatcherServlet的映射路径（拦截哪些请求）*/@Overrideprotected String[] getServletMappings() {return new String[]{"/"}; // 拦截所有请求（除.jsp）}
}

核心作用：

• getServletConfigClasses：指定SpringMVC的配置类（SpringMvcConfig），用于创建SpringMVC容器；
• getServletMappings：设置DispatcherServlet的映射路径为/，即所有请求都由SpringMVC处理；
• 该类会自动注册DispatcherServlet到Servlet容器，无需手动配置。

3.2 配置编码过滤器（解决中文乱码）

AbstractAnnotationConfigDispatcherServletInitializer可重写getServletFilters方法注册过滤器，最关键的是配置编码过滤器（解决POST请求中文乱码）：

@Override
protected Filter[] getServletFilters() {// 创建编码过滤器CharacterEncodingFilter encodingFilter = new CharacterEncodingFilter();encodingFilter.setEncoding("UTF-8");encodingFilter.setForceEncoding(true); // 强制响应编码为UTF-8return new Filter[]{encodingFilter};
}

作用：

• 所有请求经过该过滤器后，请求和响应的编码都会被设置为UTF-8；
• 必须配置，否则POST请求的中文参数会出现乱码。

四、配置SpringMVC环境：SpringMvcConfig

SpringMvcConfig是SpringMVC的核心配置类，用于配置组件扫描、视图解析器、静态资源处理等Web层相关Bean，替代传统的spring-mvc.xml。

4.1 基础配置（@Configuration + @EnableWebMvc）

package com.example.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.view.InternalResourceViewResolver;/*** SpringMVC核心配置类*/
@Configuration // 标记为配置类
@EnableWebMvc // 开启SpringMVC注解驱动（替代<mvc:annotation-driven>）
@ComponentScan("com.example.controller") // 扫描Controller所在包
public class SpringMvcConfig implements WebMvcConfigurer {// 其他配置将在这里添加...
}

核心注解：

• @Configuration：标记该类为Spring配置类；
• @EnableWebMvc：开启SpringMVC的注解支持（如@RequestMapping、@Controller），自动注册处理器映射器和适配器；
• @ComponentScan：扫描com.example.controller包下的@Controller注解类，注册为SpringBean。

4.2 配置视图解析器（JSP视图）

视图解析器用于将逻辑视图名（如"index"）解析为物理视图路径（如/WEB-INF/views/index.jsp），配置InternalResourceViewResolver：

/*** 配置JSP视图解析器*/
@Bean
public InternalResourceViewResolver viewResolver() {InternalResourceViewResolver resolver = new InternalResourceViewResolver();resolver.setPrefix("/WEB-INF/views/"); // 视图前缀（JSP存放目录）resolver.setSuffix(".jsp"); // 视图后缀resolver.setViewClass(JstlView.class); // 支持JSTL表达式return resolver;
}

配置说明：

• 若返回逻辑视图名"index"，视图解析器会拼接为/WEB-INF/views/index.jsp；
• JSP文件需放在src/main/webapp/WEB-INF/views/目录（需手动创建）。

4.3 配置静态资源处理

静态资源（CSS、JS、图片等）默认会被DispatcherServlet拦截，需通过WebMvcConfigurer的addResourceHandlers方法放行：

/*** 配置静态资源映射（放行CSS、JS、图片等）*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {// 访问路径：/static/** → 映射到实际路径：/static/registry.addResourceHandler("/static/**").addResourceLocations("/static/");
}

使用说明：

• 在src/main/webapp/目录下创建static文件夹，存放静态资源（如static/css/style.css）；
• 前端页面通过/static/css/style.css访问该资源，SpringMVC会正确映射到实际文件。

五、编写第一个Controller验证配置

配置完成后，编写一个简单的Controller测试是否生效。

5.1 创建Controller

package com.example.controller;import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;/*** 第一个Controller*/
@Controller // 标记为控制器
public class HelloController {/*** 处理GET请求：/hello*/@GetMapping("/hello")public String hello(Model model) {// 向视图传递数据model.addAttribute("message", "Hello SpringMVC!");// 返回逻辑视图名（由视图解析器解析为JSP）return "hello";}
}

5.2 创建JSP视图

在src/main/webapp/WEB-INF/views/目录下创建hello.jsp：

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<head><title>SpringMVC入门</title><!-- 引入静态资源（测试静态资源配置） --><link rel="stylesheet" href="/static/css/style.css">
</head>
<body><h1>${message}</h1> <!-- 显示Controller传递的message -->
</body>
</html>

创建静态资源src/main/webapp/static/css/style.css：

h1 {color: blue;
}

六、启动应用并验证

6.1 启动Tomcat

通过Maven命令启动Tomcat插件：

mvn tomcat9:run

启动成功后，控制台会显示：

[INFO] tomcat9-maven-plugin starting...
[INFO] Server startup in [xxx] milliseconds

6.2 访问测试

打开浏览器，访问http://localhost:8080/hello：

• 页面显示Hello SpringMVC!（蓝色文字，说明CSS生效）；
• 若能正常显示，说明SpringMVC启动配置成功。

七、常见问题与排查

7.1 启动失败：找不到Controller

错误信息：No mapping found for HTTP request with URI [/hello]

排查步骤：

1. 检查@ComponentScan的包路径是否正确（需包含Controller所在包，如com.example.controller）；
2. 确认@Controller和@GetMapping注解是否正确添加；
3. 检查SpringMvcConfig是否被MyWebAppInitializer的getServletConfigClasses正确引用。

7.2 静态资源404（CSS/JS无法加载）

错误信息：Failed to load resource: the server responded with a status of 404

排查步骤：

1. 确认addResourceHandlers配置是否正确（/static/**映射到/static/）；
2. 检查静态资源实际路径是否正确（如static/css/style.css是否存在）；
3. 前端引用路径是否正确（如href="/static/css/style.css"，注意开头的/）。

7.3 中文乱码（POST请求参数）

问题：表单提交的中文参数显示为乱码。

排查步骤：

1. 检查getServletFilters是否配置了CharacterEncodingFilter，且setForceEncoding(true)；
2. 确认过滤器是否被正确注册（MyWebAppInitializer的getServletFilters方法是否返回过滤器）；
3. 若使用Tomcat 8.0+，GET请求中文乱码需在Tomcat的server.xml中配置URIEncoding="UTF-8"（POST乱码由过滤器解决）。

总结：SpringMVC启动配置核心要点

SpringMVC基于Java的启动配置核心是“三个核心组件”：

1. MyWebAppInitializer：替代web.xml，注册DispatcherServlet和过滤器，指定SpringMVC配置类；
2. SpringMvcConfig：SpringMVC的核心配置，负责扫描Controller、配置视图解析器和静态资源；
3. DispatcherServlet：由MyWebAppInitializer自动注册，作为请求入口，协调SpringMVC组件工作。

若这篇内容帮到你，动动手指支持下！关注不迷路，干货持续输出！
ヾ(´∀ ˋ)ﾉヾ(´∀ ˋ)ﾉヾ(´∀ ˋ)ﾉヾ(´∀ ˋ)ﾉヾ(´∀ ˋ)ﾉ