IntelliJ IDEA快速搭建SpringMVC入门项目指南

1. 项目概述

作为一名Java开发者，第一次接触SpringMVC框架时总会遇到各种配置问题。记得我刚开始学习时，光是搭建一个最简单的Hello World程序就花了整整一天时间。本文将带你从零开始，在IntelliJ IDEA中快速搭建一个SpringMVC入门项目，避开那些新手常踩的坑。

这个入门程序虽然简单，但包含了SpringMVC最核心的配置要素：DispatcherServlet配置、视图解析器设置、控制器编写和JSP页面渲染。通过这个案例，你不仅能快速上手SpringMVC开发，还能理解MVC模式在Spring框架中的具体实现方式。

2. 环境准备与项目创建

2.1 开发工具选择

我强烈推荐使用IntelliJ IDEA Ultimate版进行Spring开发，社区版虽然免费但缺少对Spring框架的原生支持。最新版本的IDEA（2023.2+）已经内置了Spring Initializr，可以快速生成项目骨架。

注意：如果你使用的是社区版，需要手动添加Spring插件。在File > Settings > Plugins中搜索"Spring Boot"并安装。

2.2 创建Maven项目

1. 打开IDEA，选择"New Project"
2. 左侧选择"Maven"，不要勾选"Create from archetype"
3. 输入GroupId（如com.example）和ArtifactId（如springmvc-demo）
4. 点击Finish完成创建

创建完成后，我们需要手动添加Spring MVC依赖。打开pom.xml文件，在节点内添加以下内容：

xml复制<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>5.3.23</version>
</dependency>
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>4.0.1</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>javax.servlet.jsp</groupId>
    <artifactId>javax.servlet.jsp-api</artifactId>
    <version>2.3.3</version>
    <scope>provided</scope>
</dependency>

2.3 配置Web应用支持

由于我们创建的是普通Maven项目，需要手动添加Web支持：

1. 右键项目 > Add Framework Support
2. 勾选"Web Application"
3. 确保版本选择4.0（对应Servlet 3.1规范）
4. 点击OK

这会在src/main下创建webapp目录，其中包含WEB-INF/web.xml文件。这是传统的Java Web应用配置方式，虽然Spring Boot已经很少使用这种方式，但对于理解SpringMVC原理很有帮助。

3. SpringMVC核心配置

3.1 配置DispatcherServlet

DispatcherServlet是SpringMVC的核心，所有请求都会先经过它。我们需要在web.xml中配置：

xml复制<servlet>
    <servlet-name>dispatcher</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/spring-mvc.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>dispatcher</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

这里有几个关键点：

• contextConfigLocation参数指定了Spring配置文件路径
• url-pattern设置为"/"表示拦截所有请求
• load-on-startup设置为1确保容器启动时就初始化

3.2 创建Spring配置文件

在WEB-INF目录下创建spring-mvc.xml文件，添加基本配置：

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.controller"/>

    <!-- 视图解析器 -->
    <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="prefix" value="/WEB-INF/views/"/>
        <property name="suffix" value=".jsp"/>
    </bean>
</beans>

这个配置做了三件事：

1. 启用SpringMVC注解驱动
2. 设置组件扫描包路径
3. 配置视图解析器，指定JSP文件位置

经验之谈：在实际项目中，我建议将配置文件拆分为多个，比如单独的数据源配置、安全配置等。但对于入门项目，一个配置文件更简单明了。

4. 编写控制器和视图

4.1 创建控制器类

在src/main/java下创建com.example.controller包，然后新建HelloController.java：

java复制package com.example.controller;

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

@Controller
public class HelloController {

    @GetMapping("/hello")
    public String sayHello(Model model) {
        model.addAttribute("message", "Hello, Spring MVC!");
        return "hello";
    }
}

这个简单的控制器：

• 使用@Controller注解标记为Spring组件
• @GetMapping映射/hello路径的GET请求
• 通过Model对象向视图传递数据
• 返回"hello"表示渲染hello.jsp视图

4.2 创建JSP视图

在webapp/WEB-INF下创建views目录，然后新建hello.jsp：

jsp复制<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<head>
    <title>Spring MVC Demo</title>
</head>
<body>
    <h1>${message}</h1>
</body>
</html>

这个JSP页面非常简单，只是显示控制器传递过来的message属性。注意我们使用了EL表达式${message}来获取模型数据。

4.3 配置Tomcat服务器

现在我们需要配置一个Servlet容器来运行应用：

1. 点击IDEA右上角的"Add Configuration"
2. 点击"+" > Tomcat Server > Local
3. 在"Deployment"标签页，点击"+" > Artifact
4. 选择"springmvc-demo:war exploded"
5. 设置Application context为"/"（也可以保留默认）
6. 点击OK保存配置

避坑指南：确保选择的是"war exploded"而不是普通的war，这样修改代码后可以热部署，无需重新启动服务器。

5. 运行与测试

5.1 启动服务器

点击IDEA右上角的绿色运行按钮启动Tomcat。如果一切正常，你将在控制台看到Spring初始化日志，最后显示"Initialization completed in X ms"。

5.2 访问应用

打开浏览器，访问http://localhost:8080/hello（如果你的Application context不是"/"，需要加上相应前缀，如http://localhost:8080/your-context/hello）

你应该能看到页面显示"Hello, Spring MVC!"，这说明你的第一个SpringMVC程序运行成功了！

5.3 常见问题排查

1. 404错误：

   • 检查URL是否正确
   • 确认控制器@RequestMapping路径匹配
   • 查看Tomcat控制台是否有启动错误

2. 500错误：

   • 查看完整堆栈信息
   • 常见原因：缺少依赖、JSP路径错误、视图名称不匹配

3. JSP不渲染：

   • 检查视图解析器配置
   • 确认JSP文件在正确位置（WEB-INF/views/）
   • 确保返回的视图名称不带.jsp后缀

6. 项目结构优化建议

虽然我们的入门项目已经可以运行，但从工程化角度还有一些改进空间：

1. 日志配置：
   添加Logback或Log4j2依赖，在resources目录下添加日志配置文件

2. 静态资源处理：
   在spring-mvc.xml中添加：

   xml复制<mvc:resources mapping="/resources/**" location="/resources/"/>
   

   这样可以把JS/CSS/images放在webapp/resources目录下

3. 异常处理：
   创建@ControllerAdvice类统一处理异常

4. 多环境配置：
   使用Spring的Profile功能区分dev/test/prod环境

5. 测试支持：
   添加spring-test依赖，编写单元测试和集成测试

7. 从XML配置转向注解配置

现代Spring开发更推荐使用Java配置而非XML。我们可以创建一个配置类替代spring-mvc.xml：

java复制@Configuration
@EnableWebMvc
@ComponentScan("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;
    }
    
    @Override
    public void configureDefaultServletHandling(
            DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }
}

然后在web.xml中改为：

xml复制<servlet>
    <servlet-name>dispatcher</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextClass</param-name>
        <param-value>org.springframework.web.context.support.AnnotationConfigWebApplicationContext</param-value>
    </init-param>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>com.example.config.WebConfig</param-value>
    </init-param>
</servlet>

这种配置方式更加类型安全，也便于维护。不过对于初学者，理解XML配置有助于掌握SpringMVC的工作原理。