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

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

• • 一、SpringMVC启动的核心流程
  • 二、环境准备与依赖配置
  • • [2.1 开发环境](#2.1 开发环境)
    • [2.2 Maven依赖配置](#2.2 Maven依赖配置)
  • 三、初始化Servlet容器：WebApplicationInitializer
  • • [3.1 实现WebApplicationInitializer](#3.1 实现WebApplicationInitializer)
    • [3.2 配置编码过滤器（解决中文乱码）](#3.2 配置编码过滤器（解决中文乱码）)
  • 四、配置SpringMVC环境：SpringMvcConfig
  • • [4.1 基础配置（@Configuration + @EnableWebMvc）](#4.1 基础配置（@Configuration + @EnableWebMvc）)
    • [4.2 配置视图解析器（JSP视图）](#4.2 配置视图解析器（JSP视图）)
    • [4.3 配置静态资源处理](#4.3 配置静态资源处理)
  • 五、编写第一个Controller验证配置
  • • [5.1 创建Controller](#5.1 创建Controller)
    • [5.2 创建JSP视图](#5.2 创建JSP视图)
  • 六、启动应用并验证
  • • [6.1 启动Tomcat](#6.1 启动Tomcat)
    • [6.2 访问测试](#6.2 访问测试)
  • 七、常见问题与排查
  • • [7.1 启动失败：找不到Controller](#7.1 启动失败：找不到Controller)
    • [7.2 静态资源404（CSS/JS无法加载）](#7.2 静态资源404（CSS/JS无法加载）)
    • [7.3 中文乱码（POST请求参数）](#7.3 中文乱码（POST请求参数）)
  • 总结：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）
     * 若无需分层，可返回空数组
     */
    @Override
    protected Class<?>[] getRootConfigClasses() {
        return new Class[0]; // 本文简化为单容器，根容器为空
    }

    /**
     * 配置SpringMVC容器的配置类（Web层Bean，如Controller、视图解析器）
     */
    @Override
    protected Class<?>[] getServletConfigClasses() {
        return new Class[]{SpringMvcConfig.class}; // 指定SpringMVC配置类
    }

    /**
     * 配置DispatcherServlet的映射路径（拦截哪些请求）
     */
    @Override
    protected 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-8
    return 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组件工作。

若这篇内容帮到你，动动手指支持下！关注不迷路，干货持续输出！

ヾ(´∀ ˋ)ﾉヾ(´∀ ˋ)ﾉヾ(´∀ ˋ)ﾉヾ(´∀ ˋ)ﾉヾ(´∀ ˋ)ﾉ