Java 领域 Spring MVC 配置全解析，让你不再迷茫

Java 领域 Spring MVC 配置全解析，让你不再迷茫

关键词：Spring MVC、DispatcherServlet、配置文件、视图解析器、Java配置、XML配置、请求处理流程

摘要：本文以“餐厅服务流程”为类比，用通俗易懂的语言全面解析Spring MVC的核心配置原理。从基础概念到实战操作，覆盖XML和Java两种配置方式，结合代码示例和流程图，帮你彻底理解DispatcherServlet、HandlerMapping、视图解析器等关键组件的作用，告别配置迷茫。

---

背景介绍

目的和范围

Spring MVC是Java领域最主流的Web开发框架之一，但新手常被各种配置（XML/Java）、组件协作流程搞得晕头转向。本文将用“餐厅服务”类比Spring MVC的请求处理流程，详细讲解核心配置项的作用和原理，覆盖从环境搭建到实战开发的全流程。

预期读者

• 刚接触Spring MVC的Java开发者
• 能写出基础Controller但不懂配置原理的初级程序员
• 想系统掌握Spring MVC底层机制的中级开发者

文档结构概述

本文从“餐厅服务”故事引入，逐步解析Spring MVC核心概念→配置原理（XML/Java）→实战案例→常见问题，最后总结配置的底层逻辑，帮你建立系统认知。

术语表

核心术语定义

• DispatcherServlet：Spring MVC的“总调度台”，负责接收所有请求并分配处理任务（类比餐厅前台）。
• HandlerMapping：“任务分配表”，告诉DispatcherServlet哪个“服务员”（Controller方法）处理当前请求（类比餐厅的顾客-服务员对应表）。
• ViewResolver：“视图查找器”，根据Controller返回的视图名（如"success"）找到具体的页面文件（如/WEB-INF/views/success.jsp）。
• ModelAndView：“菜和菜单”，Controller处理后的结果数据（Model）和要展示的页面（View）的组合。

缩略词列表

• MVC：Model-View-Controller（模型-视图-控制器）
• IoC：Inversion of Control（控制反转）
• DI：Dependency Injection（依赖注入）

---

核心概念与联系

故事引入：用“餐厅服务”理解Spring MVC请求流程

假设你开了一家“Spring餐厅”，顾客（HTTP请求）进门后：

1. 前台接待（DispatcherServlet）：所有顾客先到前台登记，前台根据顾客类型（请求URL）查“任务分配表”（HandlerMapping）。
2. 服务员服务（Controller）：前台找到对应的服务员（Controller方法），服务员根据顾客需求（请求参数）去后厨（业务逻辑）准备菜品（处理数据）。
3. 上菜（View）：服务员把做好的菜（Model数据）和菜单（视图名）交给前台，前台查“菜单-厨房对应表”（ViewResolver），找到具体的厨房（视图文件），最后把菜端给顾客（返回响应）。

这个流程就是Spring MVC处理请求的核心逻辑！

核心概念解释（像给小学生讲故事）

1. DispatcherServlet：前台接待员
想象餐厅有个超级前台，所有顾客必须先找她。她的工作是“分配任务”——不管顾客是来吃饭、结账还是投诉，前台都会根据规则（配置）把顾客交给对应的服务员。
在Spring MVC中，DispatcherServlet是所有请求的入口，它的职责是协调后续组件完成请求处理。

2. HandlerMapping：任务分配表
前台怎么知道该把顾客交给哪个服务员？靠墙上贴的“任务分配表”——比如“穿红衣服的顾客找A服务员，穿蓝衣服的找B服务员”。
在Spring MVC中，HandlerMapping定义了“请求URL与Controller方法的对应关系”，常见的实现是RequestMappingHandlerMapping（对应@RequestMapping注解）。

3. Controller：服务员+厨师
服务员既需要和顾客沟通（接收请求参数），又需要去后厨做菜（调用Service处理业务）。最后还要告诉前台：“这桌的菜是鱼香肉丝，要去3号厨房（视图）端”。
在Spring MVC中，Controller是标注了@Controller的类，里面的方法用@RequestMapping标注，负责处理具体请求并返回ModelAndView。

4. ViewResolver：菜单-厨房对应表
前台拿到服务员给的菜单名（如“鱼香肉丝”）后，需要知道去哪个厨房找这道菜——比如“鱼香肉丝在川菜厨房（/WEB-INF/views/），用jsp盘子装”。
在Spring MVC中，ViewResolver根据视图名（如"success"）拼接完整路径（如"/WEB-INF/views/success.jsp"），并选择视图技术（JSP/Thymeleaf等）。

5. ModelAndView：菜和菜单
服务员做完菜后，需要告诉前台两个信息：“这桌的菜有土豆丝（Model数据）”和“菜单名是晚餐（视图名）”。前台根据这两个信息才能正确上菜。
在Spring MVC中，ModelAndView包含模型数据（Model）和视图名（View Name），是Controller返回给DispatcherServlet的“处理结果”。

核心概念之间的关系（用小学生能理解的比喻）

• DispatcherServlet和HandlerMapping：前台（DispatcherServlet）必须查任务分配表（HandlerMapping）才能找到服务员（Controller），就像你必须查字典（HandlerMapping）才能认识生字（请求）。
• Controller和ViewResolver：服务员（Controller）给前台的菜单名（视图名），必须通过菜单-厨房表（ViewResolver）才能找到具体厨房（视图文件），就像你给朋友写“去奶茶店”，朋友需要知道“奶茶店在XX路”（ViewResolver拼接路径）。
• DispatcherServlet和ViewResolver：前台（DispatcherServlet）拿到菜单名后，必须用菜单-厨房表（ViewResolver）才能正确上菜，就像快递员（DispatcherServlet）拿到地址（视图名）后，必须用地址簿（ViewResolver）找到具体门牌号。

核心概念原理和架构的文本示意图

Spring MVC请求处理全流程：
用户请求 → DispatcherServlet → HandlerMapping（找Controller方法） → Controller（处理请求） → 返回ModelAndView → ViewResolver（找视图） → 视图渲染 → 返回响应

Mermaid 流程图

graph TD
    A[用户发送请求] --> B[DispatcherServlet接收请求]
    B --> C{HandlerMapping查找处理者}
    C --> D[找到对应Controller方法]
    D --> E[Controller处理请求并返回ModelAndView]
    E --> F{ViewResolver解析视图}
    F --> G[找到具体视图文件（如JSP）]
    G --> H[视图渲染（填充Model数据）]
    H --> I[返回响应给用户]

---

核心配置原理 & 具体操作步骤

Spring MVC的配置主要解决两个问题：

1. 注册DispatcherServlet：让Web容器（如Tomcat）知道所有请求由它处理。
2. 配置核心组件：如HandlerMapping、ViewResolver、静态资源处理等。

配置方式有两种：XML配置（传统方式）和Java配置（Spring 3.0+推荐），下面分别讲解。

一、XML配置（传统方式）

1. 注册DispatcherServlet（在web.xml中配置）

Web容器（Tomcat）启动时会读取web.xml，这里需要告诉它：“所有以/开头的请求都交给DispatcherServlet处理”。
示例web.xml配置：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         version="3.1">
    <!-- 1. 配置DispatcherServlet -->
    <servlet>
        <servlet-name>springmvc</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <!-- 指定Spring MVC配置文件位置，默认是/WEB-INF/[servlet-name]-servlet.xml -->
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>/WEB-INF/spring-mvc.xml</param-value>
        </init-param>
        <!-- 启动时加载（优先级0-9，数字越小越早加载） -->
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!-- 2. 配置DispatcherServlet的URL映射 -->
    <servlet-mapping>
        <servlet-name>springmvc</servlet-name>
        <!-- / 表示匹配所有请求（但不包括.jsp，因为.jsp由JspServlet处理） -->
        <url-pattern>/</url-pattern>
    </servlet-mapping>
</web-app>

2. 配置核心组件（在spring-mvc.xml中配置）

spring-mvc.xml是Spring MVC的核心配置文件，需要配置组件扫描、视图解析器、静态资源处理等。

（1）组件扫描：找到Controller
Spring需要扫描项目中的@Controller类，才能让HandlerMapping找到对应的方法。

<!-- 扫描com.example.controller包下的所有类，注册为Bean -->
<context:component-scan base-package="com.example.controller"/>

（2）开启注解驱动：支持@RequetMapping等注解
mvc:annotation-driven会自动注册RequestMappingHandlerMapping（处理@RequestMapping）、RequestMappingHandlerAdapter（调用Controller方法）等关键组件。

<mvc:annotation-driven/>

（3）配置视图解析器：拼接视图路径
最常用的是InternalResourceViewResolver，用于JSP视图。

<bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <!-- 视图前缀：视图名前拼接的路径 -->
    <property name="prefix" value="/WEB-INF/views/"/>
    <!-- 视图后缀：视图名后拼接的后缀 -->
    <property name="suffix" value=".jsp"/>
</bean>

效果：若Controller返回视图名"success"，则实际访问/WEB-INF/views/success.jsp。

（4）静态资源处理：避免被DispatcherServlet拦截
默认情况下，DispatcherServlet会拦截所有请求（包括.css、.js、.png），导致静态资源无法访问。需要配置静态资源处理器。

<!-- 允许访问/webapp下的静态资源（如/css/、/js/） -->
<mvc:resources mapping="/static/**" location="/static/"/>

说明：mapping="/static/**"表示所有以/static/开头的请求（如/static/css/style.css），location="/static/"表示去webapp/static/目录找资源。

（5）文件上传支持（可选）
若需要处理文件上传，需配置MultipartResolver。

<bean id="multipartResolver" 
      class="org.springframework.web.multipart.commons.CommonsMultipartResolver">
    <!-- 最大上传文件大小：5MB -->
    <property name="maxUploadSize" value="5242880"/>
</bean>

二、Java配置（Spring 3.0+推荐）

Java配置通过代码替代XML，更类型安全、易维护。核心是实现WebApplicationInitializer（替代web.xml）和@Configuration类（替代spring-mvc.xml）。

1. 注册DispatcherServlet（WebApplicationInitializer）

WebApplicationInitializer是Spring提供的接口，Web容器启动时会自动调用，用于注册Servlet。
示例代码：

import org.springframework.web.WebApplicationInitializer;
import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;
import org.springframework.web.servlet.DispatcherServlet;
import javax.servlet.ServletContext;
import javax.servlet.ServletRegistration;

public class MyWebAppInitializer implements WebApplicationInitializer {
    @Override
    public void onStartup(ServletContext servletContext) {
        // 1. 创建Spring MVC的配置上下文（替代spring-mvc.xml）
        AnnotationConfigWebApplicationContext context = 
            new AnnotationConfigWebApplicationContext();
        context.register(WebConfig.class); // 注册Java配置类

        // 2. 注册DispatcherServlet
        ServletRegistration.Dynamic dispatcher = 
            servletContext.addServlet("springmvc", new DispatcherServlet(context));
        dispatcher.setLoadOnStartup(1);
        dispatcher.addMapping("/"); // 映射所有请求
    }
}

2. 配置核心组件（@Configuration类）

创建WebConfig类，用@Configuration和@EnableWebMvc替代spring-mvc.xml。

（1）组件扫描
用@ComponentScan替代<context:component-scan>。

@Configuration
@EnableWebMvc // 开启注解驱动（替代<mvc:annotation-driven>）
@ComponentScan(basePackages = "com.example.controller")
public class WebConfig {
    // 其他配置...
}

（2）视图解析器
用@Bean方法注册视图解析器。

@Bean
public ViewResolver viewResolver() {
    InternalResourceViewResolver resolver = new InternalResourceViewResolver();
    resolver.setPrefix("/WEB-INF/views/");
    resolver.setSuffix(".jsp");
    return resolver;
}

（3）静态资源处理
重写WebMvcConfigurer的addResourceHandlers方法。

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.example.controller")
public class WebConfig implements WebMvcConfigurer {
    // 配置静态资源
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**") // 匹配路径
                .addResourceLocations("/static/"); // 资源位置
    }
}

（4）文件上传支持
用@Bean注册MultipartResolver。

@Bean
public MultipartResolver multipartResolver() {
    CommonsMultipartResolver resolver = new CommonsMultipartResolver();
    resolver.setMaxUploadSize(5242880); // 5MB
    return resolver;
}

关键配置对比（XML vs Java）

配置项	XML配置方式	Java配置方式
注册DispatcherServlet	web.xml中配置<servlet>和<servlet-mapping>	实现WebApplicationInitializer接口
组件扫描	<context:component-scan>	@ComponentScan注解
注解驱动	<mvc:annotation-driven/>	@EnableWebMvc注解
视图解析器	声明InternalResourceViewResolver的Bean	@Bean方法返回InternalResourceViewResolver
静态资源处理	<mvc:resources>标签	重写WebMvcConfigurer.addResourceHandlers

---

数学模型和公式 & 详细讲解 & 举例说明

Spring MVC的核心是“请求-处理链”模型，可以用数学函数表示：
$$响应=DispatcherServlet(请求,配置参数)$$

其中，配置参数包括：

• HandlerMapping集合： H = { H 1 , H 2 , . . . , H n } H = \{H_1, H_2, ..., H_n\} H={H1​,H2​,...,Hn​}（每个H定义URL到Controller的映射）
• ViewResolver集合： V = { V 1 , V 2 , . . . , V n } V = \{V_1, V_2, ..., V_n\} V={V1​,V2​,...,Vn​}（每个V定义视图名到视图的映射）

举例：
假设请求URL是/user/123，HandlerMapping集合中有一个RequestMappingHandlerMapping，它通过正则匹配找到@RequestMapping("/user/{id}")的Controller方法。处理后返回视图名"userDetail"，ViewResolver集合中的InternalResourceViewResolver将其转换为/WEB-INF/views/userDetail.jsp。

---

项目实战：代码实际案例和详细解释说明

开发环境搭建

• JDK 8+
• Maven 3.6+
• IntelliJ IDEA（或Eclipse）
• Tomcat 9.0+（或Spring Boot内置Tomcat）

Maven依赖（pom.xml）：

<dependencies>
    <!-- Spring MVC核心 -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webmvc</artifactId>
        <version>5.3.23</version>
    </dependency>
    <!-- JSP支持（若用JSP视图） -->
    <dependency>
        <groupId>javax.servlet.jsp</groupId>
        <artifactId>javax.servlet.jsp-api</artifactId>
        <version>2.3.3</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

源代码详细实现和代码解读

步骤1：创建Controller（处理请求）

package com.example.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

@Controller
public class UserController {
    // 处理GET请求：/user/123
    @GetMapping("/user/{id}")
    public String getUser(@PathVariable("id") String userId, Model model) {
        // 模拟从数据库查询用户
        String userName = "张三（ID：" + userId + "）";
        // 将数据放入Model（相当于“菜”）
        model.addAttribute("userName", userName);
        // 返回视图名（相当于“菜单名”）
        return "userDetail"; 
    }
}

代码解读：

• @Controller：声明这是一个Spring MVC的控制器。
• @GetMapping("/user/{id}")：映射/user/123这样的GET请求，{id}是路径变量。
• @PathVariable("id")：获取路径中的id值（如123）。
• Model model：用于传递数据到视图。
• return "userDetail"：返回视图名，视图解析器会拼接为/WEB-INF/views/userDetail.jsp。

步骤2：创建视图（userDetail.jsp）

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

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<head>
    <title>用户详情</title>
</head>
<body>
    <h1>用户信息</h1>
    <p>用户名：${userName}</p> <!-- 从Model中获取数据 -->
</body>
</html>

步骤3：Java配置类（WebConfig）

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.ViewResolver;
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;

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.example.controller")
public class WebConfig implements WebMvcConfigurer {
    // 配置视图解析器
    @Bean
    public ViewResolver viewResolver() {
        InternalResourceViewResolver resolver = new InternalResourceViewResolver();
        resolver.setPrefix("/WEB-INF/views/");
        resolver.setSuffix(".jsp");
        return resolver;
    }

    // 配置静态资源（如/css/、/js/）
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**")
                .addResourceLocations("/static/");
    }
}

步骤4：注册DispatcherServlet（MyWebAppInitializer）

package com.example.config;

import org.springframework.web.WebApplicationInitializer;
import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;
import org.springframework.web.servlet.DispatcherServlet;
import javax.servlet.ServletContext;
import javax.servlet.ServletRegistration;

public class MyWebAppInitializer implements WebApplicationInitializer {
    @Override
    public void onStartup(ServletContext servletContext) {
        // 创建Spring MVC配置上下文
        AnnotationConfigWebApplicationContext context = 
            new AnnotationConfigWebApplicationContext();
        context.register(WebConfig.class);

        // 注册DispatcherServlet
        ServletRegistration.Dynamic dispatcher = 
            servletContext.addServlet("springmvc", new DispatcherServlet(context));
        dispatcher.setLoadOnStartup(1);
        dispatcher.addMapping("/");
    }
}

代码解读与分析

• 请求流程验证：启动Tomcat，访问http://localhost:8080/user/123，应看到页面显示“用户名：张三（ID：123）”。
• 关键验证点：
  • DispatcherServlet是否正确拦截请求：若返回404，检查web.xml（XML配置）或MyWebAppInitializer（Java配置）的映射是否正确。
  • Controller是否被扫描：若报“没有找到处理该请求的Handler”，检查@ComponentScan的basePackages是否包含Controller所在包。
  • 视图是否解析成功：若页面空白或报错，检查视图解析器的prefix和suffix是否正确（如是否漏掉/WEB-INF/）。

---

实际应用场景

场景1：处理表单提交（POST请求）

需求：用户提交表单（姓名、邮箱），后端保存并跳转到成功页面。

配置要点：

• Controller方法用@PostMapping注解。
• 用@RequestParam获取表单参数。
• 视图解析器正确配置（如跳转到success.jsp）。

示例Controller方法：

@PostMapping("/submit")
public String submitForm(
    @RequestParam("name") String name,
    @RequestParam("email") String email,
    Model model
) {
    // 保存到数据库...
    model.addAttribute("message", "提交成功！姓名：" + name + "，邮箱：" + email);
    return "success";
}

场景2：开发RESTful API（返回JSON）

需求：后端返回用户信息的JSON数据（如{"id":1, "name":"张三"}）。

配置要点：

• 开启@EnableWebMvc（自动注册MappingJackson2HttpMessageConverter，支持JSON转换）。
• Controller方法用@RestController（等价于@Controller+@ResponseBody）。

示例Controller：

@RestController
@RequestMapping("/api/user")
public class UserApiController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable("id") Integer id) {
        return new User(id, "张三"); // User类需有getter方法
    }
}

场景3：文件上传

需求：用户上传头像图片，后端保存到服务器。

配置要点：

• 注册CommonsMultipartResolver（或StandardServletMultipartResolver）。
• 表单enctype设置为multipart/form-data。
• Controller方法用MultipartFile接收文件。

示例Controller方法：

@PostMapping("/upload")
public String uploadFile(@RequestParam("file") MultipartFile file) {
    if (!file.isEmpty()) {
        String fileName = file.getOriginalFilename();
        // 保存文件到服务器...
        return "上传成功：" + fileName;
    }
    return "上传失败";
}

---

工具和资源推荐

• IDE：IntelliJ IDEA（对Spring支持极佳，自动提示配置项）。
• 构建工具：Maven（依赖管理更简单）或Gradle（配置更灵活）。
• 官方文档：Spring MVC Documentation（权威但略枯燥）。
• 学习资源：《Spring实战》（经典书籍，覆盖MVC配置）、B站“尚硅谷Spring教程”（视频讲解更直观）。

---

未来发展趋势与挑战

• Spring Boot简化配置：Spring Boot通过自动配置（@SpringBootApplication）和Starter依赖（如spring-boot-starter-web），自动完成DispatcherServlet、视图解析器等的配置，开发者只需关注业务逻辑。
• 响应式编程：Spring 5引入了WebFlux，支持非阻塞、异步处理请求，适合高并发场景，但配置方式与传统MVC有差异（基于Reactor库）。
• 前后端分离：现代项目更多使用RESTful API+前端框架（Vue/React），Spring MVC需配置CORS（跨域资源共享）、JSON序列化等，对配置的灵活性要求更高。

---

总结：学到了什么？

核心概念回顾

• DispatcherServlet：请求的总入口，负责协调后续组件。
• HandlerMapping：定义URL到Controller方法的映射。
• ViewResolver：将视图名转换为具体视图文件。
• Java配置 vs XML配置：Java配置更类型安全、易维护，是Spring推荐的方式。

概念关系回顾

DispatcherServlet通过HandlerMapping找到Controller→Controller处理请求并返回ModelAndView→DispatcherServlet通过ViewResolver找到视图→视图渲染后返回响应。

---

思考题：动动小脑筋

1. 如果访问/static/css/style.css返回404，可能是哪些配置错误导致的？（提示：检查<mvc:resources>或addResourceHandlers的mapping和location）
2. 如何让Spring MVC同时支持JSP和Thymeleaf两种视图？（提示：配置多个ViewResolver，设置order属性指定优先级）
3. 在Java配置中，@EnableWebMvc和WebMvcConfigurer的作用分别是什么？（提示：@EnableWebMvc开启注解驱动，WebMvcConfigurer用于自定义MVC配置）

---

附录：常见问题与解答

Q1：访问Controller返回404，可能原因？
A：

• DispatcherServlet的url-pattern配置错误（如写成*.do但访问路径无.do后缀）。
• Controller未被扫描（@ComponentScan的basePackages未包含Controller所在包）。
• @RequestMapping的路径拼写错误（如/user写成/users）。

Q2：视图名正确但页面显示空白，可能原因？
A：

• 视图解析器的prefix或suffix配置错误（如prefix漏了/WEB-INF/）。
• JSP文件路径错误（如放在src/main/resources而不是src/main/webapp）。

Q3：静态资源（CSS/JS）无法加载，如何解决？
A：

• 检查mvc:resources（XML）或addResourceHandlers（Java）的mapping和location是否匹配（如mapping="/static/**"对应location="/static/"）。
• 确保静态资源文件放在正确目录（如webapp/static/css/）。

---

扩展阅读 & 参考资料

• 《Spring Framework 5.x 官方文档》- Web MVC部分
• 《Spring实战（第5版）》- 第4章“构建Spring MVC Web应用”
• 博客：Baeldung - Spring MVC Tutorial
• 视频：尚硅谷Spring MVC教程（2022版）