1. 從零到一為什么需要一個Spring MVC項目如果你剛接觸Java Web開發(fā)或者從其他IDE比如Eclipse轉(zhuǎn)過來可能會覺得在IDEA里新建一個項目是件挺簡單的事。但說實話我見過太多新手包括一些有經(jīng)驗的開發(fā)者在第一步就踩了坑。他們要么創(chuàng)建了一個“假”的Spring MVC項目結構混亂依賴缺失要么配置了半天Tomcat一啟動就報404。這背后的原因往往不是技術有多難而是對“項目”這個概念的理解以及IDEA這個工具的工作邏輯沒摸透。所以這篇內(nèi)容我們不只講“點擊哪里”更要講清楚“為什么這么點”。Spring MVC是一個經(jīng)典的、基于Servlet的Web框架它的核心是DispatcherServlet前端控制器。一個標準的Spring MVC項目本質(zhì)上是一個配置了特定Servlet和Spring容器的Web應用。在IDEA里創(chuàng)建它意味著我們需要一個符合Servlet規(guī)范的Web項目結構并正確引入Spring MVC的核心依賴最后配置好DispatcherServlet。聽起來步驟不少但IDEA通過項目模板Project Template和模塊Module的概念把這些步驟封裝了起來。我們的任務就是理解并正確使用這些封裝而不是被它們迷惑。接下來我會帶你完整走一遍流程從項目類型選擇、依賴管理、目錄結構解讀到最終的運行和調(diào)試。我會重點解釋每個選擇背后的考量以及那些官方文檔不會寫的、容易出錯的細節(jié)。比如為什么我推薦用Maven而不是Gradle作為起步web.xml和注解配置該怎么選lib目錄下的jar包到底從哪來這些看似基礎的問題恰恰是項目能否順利跑起來的關鍵。2. 項目創(chuàng)建的十字路口Maven、Gradle與項目模板的抉擇打開IDEA點擊“New Project”你會面臨第一個關鍵選擇項目類型。這里常見的選項有Maven、Gradle以及老式的“Java Enterprise”它可能會引導你使用應用服務器提供的模板。對于Spring MVC新手我強烈建議選擇Maven作為構建工具。原因有三第一Maven的pom.xml配置文件結構清晰依賴聲明一目了然是學習依賴管理的最佳教材第二網(wǎng)絡上的Spring MVC教程和解決方案絕大多數(shù)基于Maven遇到問題更容易搜索到答案第三IDEA對Maven的支持已經(jīng)非常成熟和穩(wěn)定能減少很多工具層面的干擾。注意雖然Gradle更現(xiàn)代、構建速度更快但其基于Groovy或Kotlin DSL的構建腳本對新手來說學習曲線更陡。先掌握Maven以后再遷移到Gradle會容易得多。在Maven項目中IDEA通常會提供一個“archetype”原型列表。這里不要選擇任何Spring相關的archetype比如spring-boot-starter。我們要創(chuàng)建的是傳統(tǒng)的、非Spring Boot的Spring MVC項目所以直接使用最基礎的maven-archetype-webapp即可。這個原型會生成一個最基礎的Web應用骨架包含標準的src/main/webapp目錄和web.xml文件這正是我們需要的起點。如果找不到這個原型或者你想從絕對空白開始也可以直接創(chuàng)建一個“Maven”項目不選擇任何原型。創(chuàng)建完成后手動創(chuàng)建Web應用所需的目錄結構。但使用maven-archetype-webapp能省去不少手動配置的麻煩。關鍵步驟與參數(shù)解析GroupId ArtifactId: 這是Maven坐標。GroupId通常用公司或組織域名的反寫如com.exampleArtifactId是項目名如springmvc-demo。這會影響你的包名和最終生成的jar/war文件名。Version: 保持默認的1.0-SNAPSHOT即可。項目位置: 選擇一個干凈的目錄。避免路徑中包含中文或特殊字符這是所有Java項目的通用準則可以避免很多潛在的編碼和路徑解析問題。點擊“Finish”后IDEA會開始創(chuàng)建項目并下載Maven wrapper如果勾選了相關選項。首次創(chuàng)建可能會慢一些因為需要從遠程倉庫下載Maven核心插件。3. 核心依賴注入pom.xml的精準配置藝術項目創(chuàng)建好后打開根目錄下的pom.xml文件。這是整個項目的“心臟”所有依賴和構建配置都在這里。一個典型的、用于學習目的的Spring MVC項目需要以下核心依賴properties spring.version5.3.23/spring.version !-- 建議選擇一個穩(wěn)定的5.3.x版本 -- servlet-api.version4.0.1/servlet-api.version junit.version5.9.1/junit.version /properties dependencies !-- Spring MVC 核心 -- dependency groupIdorg.springframework/groupId artifactIdspring-webmvc/artifactId version${spring.version}/version /dependency !-- Servlet API (provided scope因為Tomcat會提供) -- dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version${servlet-api.version}/version scopeprovided/scope /dependency !-- JSP API (provided scope) -- dependency groupIdjavax.servlet.jsp/groupId artifactIdjavax.servlet.jsp-api/artifactId version2.3.3/version scopeprovided/scope /dependency !-- JSTL 標簽庫用于在JSP中簡化邏輯 -- dependency groupIdjavax.servlet/groupId artifactIdjstl/artifactId version1.2/version /dependency !-- 日志門面Spring默認使用commons-logging這里用SLF4JLogback更佳 -- dependency groupIdorg.slf4j/groupId artifactIdslf4j-api/artifactId version1.7.36/version /dependency dependency groupIdch.qos.logback/groupId artifactIdlogback-classic/artifactId version1.2.11/version /dependency !-- 單元測試 -- dependency groupIdorg.junit.jupiter/groupId artifactIdjunit-jupiter/artifactId version${junit.version}/version scopetest/scope /dependency !-- 為了讓Spring TestContext能運行需要此依賴 -- dependency groupIdorg.springframework/groupId artifactIdspring-test/artifactId version${spring.version}/version scopetest/scope /dependency /dependencies為什么這么配置版本管理使用properties統(tǒng)一管理版本號便于后續(xù)升級。Spring 5.3.x是一個長期支持且非常穩(wěn)定的分支適合學習。spring-webmvc這個依賴是核心它本身會傳遞性引入spring-context,spring-aop,spring-beans,spring-core,spring-web等所有必要的Spring模塊。你不需要單獨引入它們。provided作用域Servlet和JSP的API在項目運行時由Tomcat這類Servlet容器提供。標記為provided意味著Maven只在編譯和測試時使用這些依賴打包成WAR時不會包含進去避免與容器中的庫沖突。JSTL雖然現(xiàn)代項目可能更多使用Thymeleaf等模板引擎但JSPJSTL仍是理解Spring MVC視圖層最直接的方式。它允許你在JSP中使用類似c:forEach的標簽避免在頁面中編寫大量的Java腳本片段。日志Spring內(nèi)部使用commons-logging作為日志門面但它會自動適配當前類路徑上的具體日志實現(xiàn)如Logback。我們直接配置好SLF4J和Logback就能看到Spring內(nèi)部的詳細日志對于調(diào)試至關重要。保存pom.xml后IDEA右上角通常會彈出提示問你是否要導入更改Enable Auto-Import。務必點擊“Enable Auto-Import”這樣IDEA會在后臺自動下載這些依賴庫。你可以在右側(cè)邊欄的“Maven”工具窗口中查看下載進度和依賴樹。4. 目錄結構的重塑從Maven標準到可運行的Web應用使用maven-archetype-webapp生成的項目目錄結構可能不完全符合我們的習慣尤其是源代碼目錄。我們需要手動調(diào)整和完善。標準且推薦的目錄結構如下springmvc-demo (項目根目錄) ├── pom.xml ├── src │ ├── main │ │ ├── java -- 手動創(chuàng)建存放Java源代碼 │ │ │ └── com │ │ │ └── example │ │ │ └── controller │ │ │ └── HelloController.java │ │ ├── resources -- 手動創(chuàng)建存放配置文件 │ │ │ ├── spring │ │ │ │ └── spring-mvc.xml │ │ │ └── logback.xml │ │ └── webapp -- 原型已創(chuàng)建Web應用根目錄 │ │ ├── WEB-INF │ │ │ ├── web.xml -- 部署描述符 │ │ │ └── views -- 手動創(chuàng)建存放JSP視圖 │ │ │ └── hello.jsp │ │ └── index.jsp │ └── test -- 測試代碼目錄 │ ├── java │ └── resources手動創(chuàng)建與配置要點在src/main下右鍵新建目錄Directory分別創(chuàng)建java和resources目錄。關鍵一步將這兩個新建的目錄標記為源代碼根和資源根。右鍵點擊src/main/java目錄 - “Mark Directory as” - “Sources Root”。同樣右鍵點擊src/main/resources- “Mark Directory as” - “Resources Root”。這樣IDEA才會識別這些目錄下的文件并進行編譯和資源處理。在webapp/WEB-INF下創(chuàng)建views目錄用于存放我們的JSP文件。將視圖放在WEB-INF下是一種安全實踐因為WEB-INF下的文件不能直接被客戶端瀏覽器訪問必須通過控制器(Controller)轉(zhuǎn)發(fā)這符合MVC模式。5. 配置文件的交響曲web.xml與Spring MVC配置詳解接下來是配置的核心部分涉及兩個主要文件web.xml和Spring的配置文件如spring-mvc.xml。這里我們采用基于web.xml的配置結合注解驅(qū)動的方式這是理解Spring MVC工作原理最清晰的方式。5.1 配置web.xml前端控制器的入口web.xml是Servlet規(guī)范的部署描述符我們需要在這里聲明和配置Spring MVC的核心——DispatcherServlet。?xml version1.0 encodingUTF-8? web-app xmlnshttp://xmlns.jcp.org/xml/ns/javaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd version4.0 !-- 1. 配置Spring的上下文監(jiān)聽器用于加載根應用上下文非Web層Bean如Service, Dao -- !-- 本例為簡化將所有配置都放在DispatcherServlet中故可省略ContextLoaderListener -- !-- listener.../listener -- !-- 2. 配置字符編碼過濾器解決POST請求中文亂碼問題 -- filter filter-namecharacterEncodingFilter/filter-name filter-classorg.springframework.web.filter.CharacterEncodingFilter/filter-class init-param param-nameencoding/param-name param-valueUTF-8/param-value /init-param init-param param-nameforceEncoding/param-name param-valuetrue/param-value /init-param /filter filter-mapping filter-namecharacterEncodingFilter/filter-name url-pattern/*/url-pattern /filter-mapping !-- 3. 配置Spring MVC的核心控制器DispatcherServlet -- servlet servlet-namedispatcherServlet/servlet-name servlet-classorg.springframework.web.servlet.DispatcherServlet/servlet-class !-- 指定Spring MVC配置文件的位置和名稱 -- init-param param-namecontextConfigLocation/param-name param-valueclasspath:spring/spring-mvc.xml/param-value /init-param !-- 設置容器啟動時立即加載此Servlet而不是第一次請求時 -- load-on-startup1/load-on-startup /servlet !-- 4. 將DispatcherServlet映射到所有請求/ -- servlet-mapping servlet-namedispatcherServlet/servlet-name url-pattern//url-pattern /servlet-mapping /web-app關鍵解析CharacterEncodingFilter這是一個非常實用且容易被忽略的過濾器。它確保了請求request和響應response的編碼都設置為UTF-8從根本上杜絕了中文亂碼問題。forceEncoding參數(shù)確保即使請求頭已指定編碼也強制使用我們設置的UTF-8。DispatcherServletload-on-startup1讓它在Web容器Tomcat啟動時就初始化并加載其對應的Spring IoC容器WebApplicationContext。contextConfigLocation參數(shù)指向我們即將創(chuàng)建的Spring MVC配置文件。如果不指定默認會去/WEB-INF/下找名為servlet-name-servlet.xml的文件即dispatcherServlet-servlet.xml。url-pattern//url-pattern這個映射非常關鍵。它表示DispatcherServlet將處理所有到達應用的請求除了像.jsp這樣的由Servlet容器默認處理的請求。注意這里不是/*/*會匹配包括.jsp在內(nèi)的所有路徑可能導致一些意外行為。使用/是Spring MVC的推薦做法。5.2 配置spring-mvc.xmlSpring MVC的大腦在src/main/resources/spring/目錄下創(chuàng)建spring-mvc.xml。?xml version1.0 encodingUTF-8? beans xmlnshttp://www.springframework.org/schema/beans xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:contexthttp://www.springframework.org/schema/context xmlns:mvchttp://www.springframework.org/schema/mvc xsi:schemaLocationhttp://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/context https://www.springframework.org/schema/context/spring-context.xsd http://www.springframework.org/schema/mvc https://www.springframework.org/schema/mvc/spring-mvc.xsd !-- 1. 自動掃描指定包下的組件Controller, Service等并注冊為Bean -- context:component-scan base-packagecom.example.controller/ !-- 2. 開啟注解驅(qū)動替代傳統(tǒng)的處理器映射器和適配器配置 -- !-- 它會自動注冊RequestMappingHandlerMapping、RequestMappingHandlerAdapter等 -- mvc:annotation-driven/ !-- 3. 配置靜態(tài)資源處理。將對/css/**, /js/**, /images/**的請求映射到對應目錄 -- !-- 不經(jīng)過DispatcherServlet由容器默認Servlet處理提升性能 -- mvc:resources mapping/static/** location/static// !-- 4. 配置視圖解析器ViewResolver -- bean classorg.springframework.web.servlet.view.InternalResourceViewResolver !-- 前綴視圖文件所在的目錄 -- property nameprefix value/WEB-INF/views// !-- 后綴視圖文件的擴展名 -- property namesuffix value.jsp/ /bean !-- 5. 配置文件上傳解析器如果需要的話 -- !-- bean idmultipartResolver classorg.springframework.web.multipart.commons.CommonsMultipartResolver.../bean -- /beans為什么這么配置context:component-scan這是Spring“約定優(yōu)于配置”理念的體現(xiàn)。它讓Spring自動去com.example.controller包及其子包下掃描帶有Controller、Service、Repository、Component等注解的類并將它們實例化、管理起來。無需在XML中手動聲明每一個Bean。mvc:annotation-driven這是Spring MVC注解驅(qū)動模式的核心開關。打開它Spring MVC就會自動配置好處理RequestMapping、RequestBody、ResponseBody等注解所必需的組件。沒有它你的Controller注解將不起作用。mvc:resources這是一個性能優(yōu)化點。對于CSS、JavaScript、圖片等靜態(tài)資源不應該經(jīng)過復雜的Spring MVC調(diào)度而應該由Web容器直接返回。此配置告訴DispatcherServlet“凡是匹配/static/**路徑的請求直接去/static/目錄下找文件我不處理了?！盜nternalResourceViewResolver視圖解析器。當控制器方法返回一個邏輯視圖名如hello時解析器會將其解析為具體的物理視圖路徑/WEB-INF/views/hello.jsp。這樣控制器就無需關心視圖的具體位置和類型。6. 編寫第一個控制器與視圖讓Hello World跑起來現(xiàn)在骨架和神經(jīng)都已就位是時候添加血肉了。我們來創(chuàng)建一個最簡單的控制器和視圖。6.1 創(chuàng)建控制器HelloController.java在src/main/java/com/example/controller包下創(chuàng)建類HelloController.java。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.RequestParam; Controller // 標記這是一個Spring MVC控制器 public class HelloController { // 處理GET請求路徑為 /hello GetMapping(/hello) public String sayHello(RequestParam(value name, required false, defaultValue World) String name, Model model) { // 向模型中添加數(shù)據(jù)鍵為“userName”值為傳入的name參數(shù) model.addAttribute(userName, name); // 返回邏輯視圖名視圖解析器會將其解析為 /WEB-INF/views/hello.jsp return hello; } }代碼解讀Controller聲明這是一個控制器會被context:component-scan掃描到。GetMapping(“/hello”)一個組合注解等價于RequestMapping(value “/hello”, method RequestMethod.GET)。它將該方法映射到處理GET /hello請求。RequestParam用于獲取請求參數(shù)。value“name”指定參數(shù)名requiredfalse表示非必傳defaultValue提供默認值。Model一個接口用于控制器向視圖傳遞數(shù)據(jù)。這里我們添加了一個屬性userName。返回值“hello”這是一個邏輯視圖名由InternalResourceViewResolver解析為/WEB-INF/views/hello.jsp。6.2 創(chuàng)建視圖hello.jsp在src/main/webapp/WEB-INF/views/目錄下創(chuàng)建hello.jsp。% page contentTypetext/html;charsetUTF-8 languagejava % % taglib prefixc urihttp://java.sun.com/jsp/jstl/core % html head titleSpring MVC Demo/title /head body h1Hello, c:out value${userName}/!/h1 pThis is your first Spring MVC page./p /body /html視圖要點% page ... %設置頁面編碼為UTF-8。% taglib ... %引入JSTL核心標簽庫這樣我們才能使用c:out等標簽。${userName}這是EL表達式Expression Language用于從請求屬性、會話屬性等作用域中獲取數(shù)據(jù)。它對應控制器中model.addAttribute(“userName”, name)設置的屬性。c:out value“${userName}”/使用JSTL標簽輸出內(nèi)容。c:out默認會對內(nèi)容進行XML/HTML轉(zhuǎn)義是一種防止XSS攻擊的好習慣。7. 配置與運行Tomcat集成與項目部署代碼寫完了怎么運行我們需要一個Servlet容器這里以Tomcat為例。7.1 在IDEA中配置Tomcat點擊IDEA右上角的“Add Configuration...”。點擊“”號選擇“Tomcat Server” - “Local”。在“Server”標簽頁點擊“Configure...”指定你的Tomcat安裝目錄需要提前下載Tomcat 9.x或更高版本。在“Deployment”標簽頁點擊“” - “Artifact”選擇你的項目生成的War包通常名為springmvc-demo:war exploded。務必選擇帶exploded的版本這代表“展開的War”支持熱部署修改代碼和JSP后無需重啟Tomcat即可生效僅限部分更新。在“Application context”處可以設置訪問路徑例如設置為/demo那么應用訪問地址就是http://localhost:8080/demo。如果留空或設置為/則直接訪問http://localhost:8080/。7.2 啟動與訪問點擊綠色的運行或調(diào)試按鈕IDEA會啟動Tomcat并部署你的應用。觀察控制臺日志如果沒有報錯看到類似“Initializing Spring DispatcherServlet ‘dispatcherServlet’”和“Completed initialization in XXX ms”的日志說明Spring MVC上下文已成功啟動。打開瀏覽器訪問http://localhost:8080/[你的應用上下文]/hello。例如如果你設置了上下文為/demo就訪問http://localhost:8080/demo/hello。你應該能看到頁面顯示“Hello, World!”。嘗試在URL后加上參數(shù)http://localhost:8080/demo/hello?nameSpring頁面會顯示“Hello, Spring!”。8. 深度排錯與進階配置指南項目跑起來了但真正的挑戰(zhàn)往往在后面。這里分享幾個我踩過的坑和對應的解決方案。8.1 常見啟動失敗問題排查問題啟動Tomcat時報ClassNotFoundException或NoClassDefFoundError通常是javax.servlet相關的類。原因與解決檢查pom.xml中Servlet API的依賴是否設置了scopeprovided/scope。如果沒有Maven會將其打包進WAR可能與Tomcat自帶的Servlet庫沖突。確保作用域正確。問題訪問URL報404錯誤但Tomcat啟動日志正常。排查鏈檢查應用上下文路徑確認瀏覽器訪問的URL中的路徑與IDEA中Tomcat配置的“Application context”一致。檢查控制器映射確認GetMapping(“/hello”)中的路徑是否正確是否包含了不必要的上下文。檢查web.xml中的url-pattern確認是/而不是/*。檢查視圖解析器前綴后綴確認InternalResourceViewResolver配置的prefix和suffix能正確拼接出JSP文件的物理路徑?？梢試L試在控制器方法中直接返回完整的JSP路徑如“/WEB-INF/views/hello.jsp”來繞過視圖解析器測試是否是解析器配置問題。查看Tomcat日志IDEA的Run或Debug控制臺會輸出Tomcat的訪問日志查看是否有對應的請求記錄和可能的錯誤信息。8.2 日志配置與查看清晰的日志是調(diào)試的生命線。我們在pom.xml中引入了Logback現(xiàn)在在src/main/resources下創(chuàng)建logback.xml來配置它。?xml version1.0 encodingUTF-8? configuration !-- 控制臺輸出 -- appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n/pattern /encoder /appender !-- 將Spring框架的日志級別設為INFO或WARN避免過多DEBUG日志 -- logger nameorg.springframework levelINFO/ !-- 將我們自己的應用包設為DEBUG級別便于調(diào)試 -- logger namecom.example levelDEBUG/ root levelINFO appender-ref refCONSOLE / /root /configuration啟動項目時你會在控制臺看到格式化的日志輸出。通過調(diào)整不同包的日志級別可以精準定位問題。8.3 徹底告別JSP轉(zhuǎn)向Thymeleaf模板引擎雖然JSP是入門的好選擇但它在現(xiàn)代Spring Boot項目中已不是首選。Thymeleaf語法更自然原生支持HTML不依賴Servlet容器功能也更強大。遷移到Thymeleaf非常簡單修改pom.xml添加Thymeleaf依賴dependency groupIdorg.thymeleaf/groupId artifactIdthymeleaf-spring5/artifactId version3.1.1.RELEASE/version /dependency修改spring-mvc.xml替換視圖解析器bean idtemplateResolver classorg.thymeleaf.spring5.templateresolver.SpringResourceTemplateResolver property nameprefix value/WEB-INF/views// property namesuffix value.html/ property nametemplateMode valueHTML/ property namecharacterEncoding valueUTF-8/ property namecacheable valuefalse/ !-- 開發(fā)時設為false生產(chǎn)環(huán)境設為true -- /bean bean idtemplateEngine classorg.thymeleaf.spring5.SpringTemplateEngine property nametemplateResolver reftemplateResolver/ /bean bean classorg.thymeleaf.spring5.view.ThymeleafViewResolver property nametemplateEngine reftemplateEngine/ property namecharacterEncoding valueUTF-8/ /bean將hello.jsp重命名為hello.html并使用Thymeleaf語法!DOCTYPE html html xmlns:thhttp://www.thymeleaf.org head meta charsetUTF-8 titleSpring MVC Demo/title /head body h1Hello, span th:text${userName}World/span!/h1 pThis is your first Spring MVC page with Thymeleaf./p /body /html控制器代碼完全無需修改。Thymeleaf的th:text屬性會動態(tài)替換標簽體內(nèi)的文本。8.4 關于web.xml與純注解配置我們上面使用了web.xml。但Servlet 3.0規(guī)范支持用Java代碼實現(xiàn)WebApplicationInitializer接口完全替代web.xml。Spring提供了便捷的抽象類AbstractAnnotationConfigDispatcherServletInitializer。使用純注解配置更簡潔也是Spring Boot的默認方式。但對于初學者從web.xml開始能更直觀地理解Servlet和Filter的配置流程之后再學習純注解配置會更容易理解其背后的原理。