SpringMVC 快速开始指南

cheniy2025/9/17大约 6 分钟

SpringMVC 快速开始指南

学习目标

通过本教程，您将学会：

创建 SpringMVC 项目
配置 SpringMVC 环境
编写第一个控制器
理解项目结构和配置文件

项目创建

1. 使用 Maven 创建项目

创建一个标准的 Maven Web 项目：

mvn archetype:generate -DgroupId=com.example.springmvc \
    -DartifactId=springmvc-demo \
    -DarchetypeArtifactId=maven-archetype-webapp \
    -DinteractiveMode=false

2. 项目结构

创建完成后的项目结构：

springmvc-demo/
├── pom.xml
└── src/
    └── main/
        ├── java/
        │   └── com/
        │       └── example/
        │           └── springmvc/
        │               ├── config/
        │               ├── controller/
        │               └── service/
        ├── resources/
        │   └── spring/
        └── webapp/
            ├── WEB-INF/
            │   ├── views/
            │   └── web.xml
            └── static/
                ├── css/
                ├── js/
                └── images/

依赖配置

Maven 依赖

在 pom.xml 中添加必要的依赖：

完整的 pom.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.springmvc</groupId>
    <artifactId>springmvc-demo</artifactId>
    <version>1.0.0</version>
    <packaging>war</packaging>
    
    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <spring.version>5.3.21</spring.version>
    </properties>
    
    <dependencies>
        <!-- SpringMVC 核心依赖 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
            <version>${spring.version}</version>
        </dependency>
        
        <!-- Spring Context 支持 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
            <version>${spring.version}</version>
        </dependency>
        
        <!-- Servlet API -->
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>4.0.1</version>
            <scope>provided</scope>
        </dependency>
        
        <!-- JSP API -->
        <dependency>
            <groupId>javax.servlet.jsp</groupId>
            <artifactId>jsp-api</artifactId>
            <version>2.2</version>
            <scope>provided</scope>
        </dependency>
        
        <!-- JSTL 标签库 -->
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>jstl</artifactId>
            <version>1.2</version>
        </dependency>
        
        <!-- Jackson JSON 处理 -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.13.3</version>
        </dependency>
        
        <!-- Lombok 简化代码 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.24</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <!-- Maven 编译插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>8</source>
                    <target>8</target>
                </configuration>
            </plugin>
            
            <!-- Tomcat 插件 -->
            <plugin>
                <groupId>org.apache.tomcat.maven</groupId>
                <artifactId>tomcat7-maven-plugin</artifactId>
                <version>2.2</version>
                <configuration>
                    <port>8080</port>
                    <path>/</path>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

配置文件

1. web.xml 配置

配置 DispatcherServlet 和字符编码过滤器：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee 
         http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">
    
    <display-name>SpringMVC Demo</display-name>
    
    <!-- 字符编码过滤器 -->
    <filter>
        <filter-name>characterEncodingFilter</filter-name>
        <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
        <init-param>
            <param-name>encoding</param-name>
            <param-value>UTF-8</param-value>
        </init-param>
        <init-param>
            <param-name>forceEncoding</param-name>
            <param-value>true</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>characterEncodingFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
    
    <!-- SpringMVC 前端控制器 -->
    <servlet>
        <servlet-name>dispatcherServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>classpath:spring/spring-mvc.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>dispatcherServlet</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>
    
    <!-- 欢迎页面 -->
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>
    
</web-app>

2. SpringMVC 配置文件

创建 src/main/resources/spring/spring-mvc.xml：

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.springframework.org/schema/context
           http://www.springframework.org/schema/context/spring-context.xsd
           http://www.springframework.org/schema/mvc
           http://www.springframework.org/schema/mvc/spring-mvc.xsd">
    
    <!-- 启用注解驱动 -->
    <mvc:annotation-driven/>
    
    <!-- 组件扫描 -->
    <context:component-scan base-package="com.example.springmvc.controller"/>
    
    <!-- 静态资源处理 -->
    <mvc:resources mapping="/static/**" location="/static/"/>
    
    <!-- 视图解析器 -->
    <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="prefix" value="/WEB-INF/views/"/>
        <property name="suffix" value=".jsp"/>
    </bean>
    
</beans>

第一个控制器

创建 HelloController

package com.example.springmvc.controller;

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

/**
 * Hello World 控制器
 */
@Controller
public class HelloController {
    
    /**
     * 处理根路径请求
     */
    @GetMapping("/")
    public String index() {
        return "index";
    }
    
    /**
     * 处理 hello 请求
     */
    @GetMapping("/hello")
    public String hello(@RequestParam(value = "name", defaultValue = "World") String name, 
                       Model model) {
        model.addAttribute("message", "Hello, " + name + "!");
        model.addAttribute("timestamp", System.currentTimeMillis());
        return "hello";
    }
    
    /**
     * 返回 JSON 数据
     */
    @GetMapping("/api/hello")
    @ResponseBody
    public Map<String, Object> helloApi(@RequestParam(value = "name", defaultValue = "World") String name) {
        Map<String, Object> result = new HashMap<>();
        result.put("message", "Hello, " + name + "!");
        result.put("timestamp", System.currentTimeMillis());
        result.put("status", "success");
        return result;
    }
}

视图页面

1. 首页 - index.jsp

创建 src/main/webapp/WEB-INF/views/index.jsp：

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>SpringMVC Demo</title>
</head>
<body>
    <div class="container">
        <h1>🚀 欢迎使用 SpringMVC</h1>
        <p>这是您的第一个 SpringMVC 应用程序！</p>
        
        <div>
            <a href="${pageContext.request.contextPath}/hello" class="btn">Hello World</a>
            <a href="${pageContext.request.contextPath}/hello?name=SpringMVC" class="btn">Hello SpringMVC</a>
            <a href="${pageContext.request.contextPath}/api/hello" class="btn">API 测试</a>
        </div>
    </div>
</body>
</html>

2. Hello 页面 - hello.jsp

创建 src/main/webapp/WEB-INF/views/hello.jsp：

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Hello Page</title>
</head>
<body>
    <div class="message">
        ${message}
    </div>
    
    <div class="info">
        <p><strong>时间戳：</strong> ${timestamp}</p>
        <p><strong>请求时间：</strong> <script>document.write(new Date(${timestamp}));</script></p>
    </div>
    
    <a href="${pageContext.request.contextPath}/" class="back-btn">← 返回首页</a>
</body>
</html>

运行项目

1. 使用 Maven 运行

# 编译项目
mvn clean compile

# 使用 Tomcat 插件运行
mvn tomcat7:run

2. 使用 IDE 运行

IntelliJ IDEA 配置步骤

打开项目
配置 Tomcat 服务器
部署项目到 Tomcat
启动服务器

3. 访问测试

启动成功后，在浏览器中访问：

首页：http://localhost:8080/
Hello 页面：http://localhost:8080/hello
带参数：http://localhost:8080/hello?name=张三
API 接口：http://localhost:8080/api/hello

配置详解

DispatcherServlet 配置

核心配置说明

contextConfigLocation：指定 SpringMVC 配置文件位置
load-on-startup：设置为 1，表示容器启动时就加载 Servlet
url-pattern：设置为 /，拦截所有请求（除 JSP）

注解驱动配置

<!-- 启用注解驱动，自动注册以下组件：-->
<!-- 1. RequestMappingHandlerMapping -->
<!-- 2. RequestMappingHandlerAdapter -->
<!-- 3. 数据绑定和类型转换 -->
<!-- 4. 数据验证支持 -->
<!-- 5. JSON 消息转换器 -->
<mvc:annotation-driven/>

静态资源处理

<!-- 处理静态资源，避免被 DispatcherServlet 拦截 -->
<mvc:resources mapping="/static/**" location="/static/"/>
<mvc:resources mapping="/css/**" location="/static/css/"/>
<mvc:resources mapping="/js/**" location="/static/js/"/>
<mvc:resources mapping="/images/**" location="/static/images/"/>

常见问题

1. 404 错误

解决方案

可能原因：

URL 映射错误
视图文件路径错误
组件扫描包路径错误

解决方法：

检查 @RequestMapping 注解
确认 JSP 文件位置
验证 component-scan 配置

2. 中文乱码

解决方案

配置字符编码过滤器：

<filter>
    <filter-name>characterEncodingFilter</filter-name>
    <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
    <init-param>
        <param-name>forceEncoding</param-name>
        <param-value>true</param-value>
    </init-param>
</filter>

3. 静态资源访问失败

解决方案

添加静态资源映射：

<mvc:resources mapping="/static/**" location="/static/"/>

或者使用默认 Servlet：

<mvc:default-servlet-handler/>

项目增强

1. 添加日志配置

创建 src/main/resources/logback.xml：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="STDOUT"/>
    </root>
    
    <logger name="com.example.springmvc" level="DEBUG"/>
</configuration>

2. 添加实体类

package com.example.springmvc.model;

import lombok.Data;
import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    private Long id;
    private String name;
    private String email;
    private Integer age;
}

总结

通过本教程，我们成功创建了第一个 SpringMVC 项目，包括：

✅ 项目搭建：使用 Maven 创建 Web 项目
✅ 依赖配置：添加 SpringMVC 相关依赖
✅ 核心配置：配置 DispatcherServlet 和 SpringMVC
✅ 控制器开发：编写第一个 Controller
✅ 视图创建：创建 JSP 页面
✅ 项目运行：成功启动和测试

下一步学习

学习 SpringMVC 控制器与请求映射
了解数据绑定和参数处理
掌握视图解析和模板引擎

现在您已经有了一个可以运行的 SpringMVC 项目，可以在此基础上继续学习更多高级特性！