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

AA-代码批发V哥2025-07-23 11:55

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 复制代码 
<?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提供的抽象类，简化配置）：

java 复制代码 
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请求中文乱码）：

java 复制代码 
@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）

java 复制代码 
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：

java 复制代码 
/**
 * 配置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方法放行：

java 复制代码 
/**
 * 配置静态资源映射（放行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

java 复制代码 
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：

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：

css 复制代码 
h1 {
    color: blue;
}

六、启动应用并验证

6.1 启动Tomcat

通过Maven命令启动Tomcat插件：

bash 复制代码 
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组件工作。

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

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

相关推荐
夜斗小神社2 小时前
【黑马SpringCloud微服务开发与实战】（五）微服务保护
spring·spring cloud·微服务
LUCIAZZZ4 小时前
TTL+日志的MDC实现简易链路追踪
java·大数据·spring boot·spring·操作系统·计算机系统
丶小鱼丶4 小时前
Spring之【Bean工厂后置处理器】
java·spring
Java初学者小白5 小时前
秋招Day17 - Spring - 事务
java·数据库·spring
CodeWolf6 小时前
如何自定义一个起步依赖starter
spring boot·spring
过期动态10 小时前
MySQL中的多表查询和笛卡尔积问题
java·数据库·mysql·spring·tomcat·mybatis
麦兜*12 小时前
【Spring Boot】Spring Boot循环依赖破解：@Lazy与Setter注入的取舍指南（流程图修复版）
java·spring boot·python·spring·spring cloud·系统架构·流程图
雪碧聊技术12 小时前
spring注解
java·后端·spring
小刘|15 小时前
Spring 核心知识点梳理 1
java·后端·spring
热门推荐
01全球最强模型Grok4，国内已可免费使用！（附教程）02【2025.7.18】更新vscode后所有.vue文件template标签后报红的临时解决办法，Vue - Official 插件3.0.2导致03这次领先Cursor！体验了Trae 2.0 SOLO 模式，超酷！04Cursor Claude 模型无法使用的解决方法05Claude Code用不了？来试下Qwen3-Coder加持的Qwen Code吧06我亲历了2025年最荒谬的前端灾难：一支触控笔"干掉"了全球CSS预处理器07KGG转MP3工具|非KGM文件|解密音频08Cursor限制国内用户使用Claude模型？附简单解决方案！09赛博保姆出列！Gemini CLI & Claude Code + Kimi 手把手教程10Cursor区域封禁（Model not avilable）解决方案指南