先別急著卸載IDEA社區(qū)版。昨天一個(gè)剛學(xué)Java的讀者跟我抱怨他按照教程裝了免費(fèi)的IDEA Community Edition結(jié)果新建項(xiàng)目時(shí)怎么都找不到Spring Initializr那個(gè)熟悉的向?qū)岩勺约菏遣皇茄b了個(gè)殘缺版本。這里明確說一句社區(qū)版完全能開發(fā)Spring Boot Web項(xiàng)目而且日常夠用只是創(chuàng)建項(xiàng)目這一步需要繞個(gè)小路。這篇文章我就圍繞“IDEA社區(qū)版 Spring Boot Web項(xiàng)目 Java”這條主線把從零開始到跑通第一個(gè)接口的完整過程講清楚。版本選型、項(xiàng)目創(chuàng)建、導(dǎo)入IDEA、寫接口、踩坑排查每一步都會(huì)解釋背后的邏輯不只是給操作步驟。適合剛接觸Java Web開發(fā)的新手也適合從旗艦版轉(zhuǎn)社區(qū)版的開發(fā)者快速上手。1. 項(xiàng)目概述與準(zhǔn)備清單1.1 社區(qū)版真正缺了什么很多初學(xué)者對IDEA社區(qū)版有一個(gè)誤解覺得它“不能搞Spring Boot”。準(zhǔn)確地說社區(qū)版和旗艦版在Spring Boot開發(fā)上的差距核心就集中在項(xiàng)目創(chuàng)建階段旗艦版內(nèi)置了Spring Initializr向?qū)陆?xiàng)目時(shí)直接勾選依賴、選版本幾步搞定社區(qū)版沒有這個(gè)入口所以你翻遍New Project向?qū)б舱也坏絊pring Initializr。但除了“創(chuàng)建項(xiàng)目”這一步其他方面差距沒有想象中那么大。社區(qū)版保留了完整的Java編碼能力、Maven集成、Git版本管理、終端、調(diào)試器和常用插件體系。Community Edition下的Lombok插件、MyBatis插件也都是能正常安裝使用的。也就是說一旦項(xiàng)目創(chuàng)建出來你后續(xù)寫代碼、調(diào)接口、跑測試的日常體驗(yàn)和旗艦版不會(huì)有本質(zhì)區(qū)別。當(dāng)然旗艦版還有一些額外功能比如Spring Bean的圖形化依賴圖、JPA面板、Spring Boot運(yùn)行配置的專屬工具窗口等。但這些屬于錦上添花對于學(xué)習(xí)階段或者中小項(xiàng)目開發(fā)社區(qū)版足夠應(yīng)付。如果你的目標(biāo)是個(gè)人學(xué)習(xí)、課程作業(yè)、畢業(yè)論文或者普通的后端接口開發(fā)免費(fèi)社區(qū)版完全不丟人更不用去找那些亂七八糟的激活方案。1.2 版本選型先別急著裝最新這幾年Spring Boot的版本迭代很快網(wǎng)上教程推薦的版本也五花八門很多人一上來就裝最新版結(jié)果編譯報(bào)錯(cuò)然后開始懷疑人生。其實(shí)大部分問題都出在JDK版本和Spring Boot版本不匹配上。這里我直接給出我平時(shí)給新人推薦的組合使用場景JDK版本Spring Boot版本說明老項(xiàng)目維護(hù)、企業(yè)常見JDK 82.7.x兼容性好資料多新項(xiàng)目學(xué)習(xí)、常規(guī)開發(fā)JDK 173.2.x或3.3.x官方當(dāng)前主流嘗鮮新特性JDK 213.4.x部分新特性需要核心原則就是Spring Boot 3.x 強(qiáng)制要求 JDK 17 及以上如果本機(jī)只有 JDK 8就老老實(shí)實(shí)用 Spring Boot 2.7.x別硬上 3.x。怎么查自己的JDK版本命令行執(zhí)行java -version就能看到。如果還沒裝JDK優(yōu)先裝 JDK 17這是當(dāng)前最穩(wěn)妥的選擇向下兼容性最好。IDEA社區(qū)版的版本建議在2022.3以上越新越好去官方網(wǎng)站下載就行。Maven的話不強(qiáng)制單獨(dú)安裝因?yàn)镮DEA自帶了一個(gè)Bundled Maven新手直接用內(nèi)置的就行。不過后面我會(huì)講如果依賴下載很慢建議手動(dòng)裝一個(gè)Maven或者用自定義的settings.xml配置鏡像會(huì)舒服很多。2. 創(chuàng)建Spring Boot Web項(xiàng)目的完整流程2.1 核心思路把“向?qū)А卑岬綖g覽器里既然社區(qū)版沒有Spring Initializr入口那我們就換一條路直接用Spring官方提供的在線項(xiàng)目生成服務(wù) start.spring.io。這個(gè)網(wǎng)站在IDEA旗艦版的向?qū)Ю锉举|(zhì)上也是套了一層殼底層用的還是同一套服務(wù)所以生成的下載包結(jié)構(gòu)和IDEA向?qū)傻耐耆恢?。用生活場景打個(gè)比方旗艦版相當(dāng)于廚房里自帶一口炒鍋你在自家廚房就能炒菜社區(qū)版廚房里沒這口鍋但沒關(guān)系官方后廚早就把半成品打包好了你拿回來倒進(jìn)自己的鍋加熱一下端上桌的菜是一樣的。你真正要掌握的是在這個(gè)在線頁面上把“半成品”的配料選對然后拿回來自己處理。2.2 在start.spring.io上選好項(xiàng)目參數(shù)打開 start.spring.io 之后你會(huì)看到一個(gè)表單頁面這里面的每個(gè)參數(shù)都值得認(rèn)真選因?yàn)樗鼈冎苯記Q定項(xiàng)目的基礎(chǔ)結(jié)構(gòu)。Project選Maven。Gradle雖然也很優(yōu)秀但國內(nèi)多數(shù)教程和公司項(xiàng)目還是Maven居多有問題好搜資料。Language選Java沒懸念。Spring Boot選穩(wěn)定版本。頁面左側(cè)會(huì)列出當(dāng)前推薦版本一般選不帶SNAPSHOT后綴的穩(wěn)定版比如3.3.x。不要盲目選最新版新版本可能依賴一些新JDK特性反而增加折騰成本。Group一般寫 com.example或者用自己的域名反寫這對應(yīng)Maven的坐標(biāo)。Artifact項(xiàng)目名比如 hello-web 或者 demo對應(yīng)倉庫里的子目錄名也決定Spring Boot啟動(dòng)類的默認(rèn)名稱。Packaging選Jar。這一點(diǎn)很關(guān)鍵很多從傳統(tǒng)SSH項(xiàng)目轉(zhuǎn)過來的人習(xí)慣性想選War但Spring Boot自帶內(nèi)嵌Tomcat默認(rèn)就按可執(zhí)行Jar來運(yùn)行不用再單獨(dú)裝Tomcat服務(wù)器這是它極大的便利。Java選你本機(jī)的JDK版本如果本機(jī)是JDK 17這里就選17。頁面下方是Dependencies依賴選擇新手第一次做Web項(xiàng)目只勾一個(gè)Spring Web就夠了。Spring Web這個(gè)依賴就是把Spring MVC和內(nèi)置Tomcat打包在一起了你寫的Controller能通過HTTP接口訪問全靠它。其他依賴比如Spring Boot DevTools、MySQL Driver、MyBatis第一遍先不加跑通基礎(chǔ)流程后再往pom.xml里引入這樣問題定位會(huì)更清晰。選完之后點(diǎn)擊Generate瀏覽器會(huì)下載一個(gè)zip壓縮包。這就是項(xiàng)目的骨架。2.3 導(dǎo)入IDEA并完成首次刷新下載下來的zip要先解壓。這里有個(gè)小細(xì)節(jié)很多壓縮軟件解壓后會(huì)多套一層目錄比如你下載的是 hello-web.zip解壓出來可能是 hello-web/hello-web/ 這種嵌套結(jié)構(gòu)。只要找到里面那個(gè)同時(shí)包含pom.xml的目錄即可這才是真正的項(xiàng)目根目錄。打開IDEA社區(qū)版點(diǎn) File - Open選中項(xiàng)目根目錄或直接選中里面的pom.xml文件IDEA會(huì)識(shí)別為Maven項(xiàng)目并彈出一個(gè)信任窗口選擇Trust Project。之后IDEA會(huì)自動(dòng)開始解析pom.xml并下載依賴第一次會(huì)比較慢因?yàn)橐ブ醒雮}庫拉取Spring Boot全家桶的依賴。這里我建議提前配置Maven鏡像否則國內(nèi)網(wǎng)絡(luò)條件下首次下載依賴可能會(huì)卡到懷疑人生。在用戶目錄下的.m2文件夾里新建settings.xml寫入以下內(nèi)容?xml version1.0 encodingUTF-8? settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd localRepository你自己的本地倉庫路徑/localRepository mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共倉庫/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors /settings然后在IDEA里打開 Settings - Build, Execution, Deployment - Build Tools - Maven把User settings file指向這個(gè)文件。如果本機(jī)裝了獨(dú)立Maven也可以直接改Maven安裝目錄下的conf/settings.xml。配好鏡像后依賴下載速度會(huì)有質(zhì)的提升。依賴?yán)⊥瓿傻臉?biāo)志是IDE右下角進(jìn)度條消失同時(shí)Maven工具窗口里不再有報(bào)錯(cuò)信息。這時(shí)候打開左側(cè)的src/main/java/com/example/helloweb/HelloWebApplication.java你會(huì)看到Spring Boot標(biāo)準(zhǔn)的主類結(jié)構(gòu)。3. 從啟動(dòng)類到第一個(gè)Web接口3.1 項(xiàng)目結(jié)構(gòu)里的三個(gè)關(guān)鍵位置一個(gè)標(biāo)準(zhǔn)的Spring Boot項(xiàng)目結(jié)構(gòu)上有幾個(gè)地方必須要看懂。hello-web/ ├── pom.xml ├── src/main/java/com/example/helloweb/ │ ├── HelloWebApplication.java │ └── controller/ │ └── HelloController.java └── src/main/resources/ └── application.propertiespom.xml是Maven項(xiàng)目的核心配置文件Spring Boot的版本、所有依賴、構(gòu)建插件都在這里聲明。application.properties是Spring Boot的默認(rèn)配置文件端口、數(shù)據(jù)庫連接等核心參數(shù)以后都會(huì)寫在這里。HelloWebApplication.java就是啟動(dòng)類它的方法上有一個(gè)主入口右鍵直接運(yùn)行。啟動(dòng)類上的SpringBootApplication注解看著不起眼實(shí)際上它組合了三個(gè)功能SpringBootConfiguration聲明這是一個(gè)配置類EnableAutoConfiguration開啟自動(dòng)裝配ComponentScan開啟組件掃描。其中最容易出問題的就是組件掃描它默認(rèn)掃描當(dāng)前啟動(dòng)類所在的包以及所有子包。如果項(xiàng)目里某個(gè)包名和啟動(dòng)類不在同一個(gè)根目錄下Spring就找不到那個(gè)包里的Controller接口訪問就404。這個(gè)規(guī)則我給所有初學(xué)者都強(qiáng)調(diào)過項(xiàng)目里Controller、Service、Mapper這些組件必須放在啟動(dòng)類所在包的子包下不能和啟動(dòng)類平級亂放更不能放在啟動(dòng)類所在包的外面。3.2 寫一個(gè)最簡單的REST接口項(xiàng)目骨架跑起來之后我們來寫第一個(gè)接口。在啟動(dòng)類同級目錄下新建controller包然后在包里創(chuàng)建HelloController.javapackage com.example.helloweb.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; RestController public class HelloController { GetMapping(/hello) public String hello() { return Hello Spring Boot; } }這個(gè)代碼里有兩個(gè)注解值得說明。RestController是Spring 4之后引入的組合注解它相當(dāng)于Controller加上ResponseBody也就是說方法返回的字符串會(huì)直接以HTTP響應(yīng)的形式寫回瀏覽器不會(huì)再走視圖解析器去找JSP頁面。如果寫Controller你還需要配合模板引擎或者手動(dòng)加ResponseBody新手階段直接用RestController最省心。GetMapping(/hello)表示這個(gè)方法處理HTTP GET請求訪問路徑為/hello。如果你想順手看看JSON格式的效果可以再補(bǔ)一個(gè)接口GetMapping(/info) public java.util.MapString, String info() { return java.util.Map.of(name, hello-web, status, ok); }Spring Boot的Jackson組件會(huì)自動(dòng)把Map序列化成JSON返回給瀏覽器這也是后面寫前后端分離接口的基礎(chǔ)。3.3 啟動(dòng)項(xiàng)目與訪問驗(yàn)證回到HelloWebApplication.java找到main方法右鍵點(diǎn)擊運(yùn)行。第一次啟動(dòng)時(shí)控制臺(tái)會(huì)刷出一大堆日志不用緊張重點(diǎn)看最后幾行。看到類似下面的輸出就說明項(xiàng)目已經(jīng)成功啟動(dòng)Tomcat started on port 8080 (http) Started HelloWebApplication in 2.3 seconds (process running for 2.5)然后在瀏覽器地址欄輸入http://localhost:8080/hello頁面顯示Hello Spring Boot整個(gè)鏈路就通了。那一刻你會(huì)覺得Spring Boot的自動(dòng)配置和內(nèi)置Tomcat真的省掉了大量傳統(tǒng)開發(fā)中部署服務(wù)器的繁瑣步驟。如果你不想用8080端口或者8080被別的程序占了可以在application.properties里修改server.port8081 server.servlet.context-path/api改完端口后訪問地址就是http://localhost:8081/api/hello。context-path的意思是給所有接口統(tǒng)一加一個(gè)前綴有些團(tuán)隊(duì)規(guī)范會(huì)要求這個(gè)做前后端分離的時(shí)候也常用知道就行。如果在啟動(dòng)日志里想省掉那個(gè)巨大的Spring Boot橫幅可以加一行spring.main.banner-modeoff實(shí)測下來能讓日志少刷幾行。不過那個(gè)logo看著確實(shí)有種儀式感留著也不礙事。4. 常見問題與排查技巧實(shí)錄4.1 端口占用一啟動(dòng)就報(bào)錯(cuò)新手最常見的啟動(dòng)失敗原因之一就是端口被占用。當(dāng)你看到日志里出現(xiàn)這樣的內(nèi)容Web server failed to start. Port 8080 was already in use.說明8080端口已經(jīng)被另一個(gè)進(jìn)程占用了。處理方式有兩種。第一種最簡單直接在配置文件里把端口改掉比如改8081。第二種找出占用端口的進(jìn)程并結(jié)束它Windows下用netstat -ano | findstr 8080查看PID然后在任務(wù)管理器里結(jié)束對應(yīng)進(jìn)程macOS或Linux用lsof -i:8080查看再根據(jù)PID執(zhí)行 kill。我自己的習(xí)慣是開發(fā)一個(gè)項(xiàng)目就固定一個(gè)端口寫在筆記里不要每次都隨機(jī)改。比如用戶模塊項(xiàng)目用8090訂單模塊項(xiàng)目用8091這樣同時(shí)啟動(dòng)多個(gè)項(xiàng)目調(diào)試時(shí)不會(huì)打架。4.2 接口404組件掃描不到項(xiàng)目能啟動(dòng)但訪問/hello時(shí)出現(xiàn)Spring Boot默認(rèn)的Whitelabel Error Page或者返回404十有八九是Controller沒有被掃描到。優(yōu)先級最高的檢查點(diǎn)Controller所在的包是不是啟動(dòng)類所在包的子包。打個(gè)比方啟動(dòng)類的包是com.example.helloweb那Controller可以放在com.example.helloweb.controller或者更深的任何子包。但如果建成了com.example.controllerSpring的默認(rèn)掃描規(guī)則覆蓋不到接口就是404。還有一個(gè)容易踩的坑Controller方法上的請求路徑寫錯(cuò)了。路徑是大小寫敏感的/Hello和/hello完全不同。第一遍寫接口建議啟動(dòng)后直接用瀏覽器訪問把路徑對照好再繼續(xù)。4.3 依賴下載慢或卡在解析階段國內(nèi)開發(fā)者基本都會(huì)遇到Maven下載依賴慢的問題表現(xiàn)就是IDEA右下角一直轉(zhuǎn)圈或者M(jìn)aven工具窗口里持續(xù)報(bào)Downloading...。根據(jù)搜索結(jié)果里的高頻問題很多人還遇到“springboot版本太高”同時(shí)配著依賴?yán)幌聛淼那闆r這通常不是版本問題而是網(wǎng)絡(luò)問題。解決思路就兩條一是換鏡像源用我之前寫的settings.xml配置阿里云鏡像二是不用IDEA內(nèi)置Maven手動(dòng)安裝一個(gè)Maven在conf/settings.xml里配置鏡像然后在IDEA的Maven設(shè)置里指定這個(gè)安裝目錄。常見現(xiàn)象和處理辦法現(xiàn)象可能原因處理方式一直卡在Resolving中央倉庫訪問慢配置阿里云鏡像報(bào)PKIX path building failedSSL證書校驗(yàn)問題更新JDK或換鏡像地址報(bào)Connect reset網(wǎng)絡(luò)不穩(wěn)定換網(wǎng)絡(luò)或換鏡像后刷新依賴下到一半失敗網(wǎng)絡(luò)波動(dòng)刪除本地倉庫對應(yīng)目錄重新導(dǎo)入刷新改完配置后不要忘了在IDEA右側(cè)Maven工具窗口里點(diǎn)一下刷新按鈕重新加載項(xiàng)目依賴。4.4 Spring Boot版本太高導(dǎo)致編譯失敗有關(guān)“springboot版本太高”的搜索量一直不小多數(shù)情況是版本和JDK不匹配。如果你在編譯時(shí)報(bào)錯(cuò)信息里有invalid source release、Unsupported class file major version這些字樣基本就是JDK版本過舊帶不動(dòng)新版本Spring Boot。舉個(gè)例子本機(jī)JDK是8卻在pom.xml里把Spring Boot版本配置成了3.3.x那項(xiàng)目啟動(dòng)時(shí)就會(huì)報(bào)版本不支持的錯(cuò)誤。解決辦法是反向選擇JDK 8 對應(yīng) Spring Boot 2.7.xJDK 17 及以上再用 Spring Boot 3.x。另外還要檢查IDEA里的Project Structure確保Project SDK和Language level與pom.xml里聲明的Java版本一致。有時(shí)候pom.xml寫的Java 17但I(xiàn)DEA里Project SDK選的還是JDK 8編譯同樣過不去。養(yǎng)成習(xí)慣開啟項(xiàng)目第一件事檢查右下角或Project Structure里SDK對不對。4.5 社區(qū)版相關(guān)的一些“花式提示”用社區(qū)版開發(fā)可能會(huì)遇到幾個(gè)和IDE本身或者調(diào)試工具相關(guān)的奇怪提示新手容易慌。第一類項(xiàng)目里如果添加了Spring Boot DevTools依賴啟動(dòng)時(shí)可能看到類似“dsh web authentication required; reopen the url printed by dsh web.”這樣一段提示甚至自動(dòng)彈出一個(gè)本地調(diào)試視圖。這個(gè)提示本身并不代表項(xiàng)目啟動(dòng)失敗它是開發(fā)工具在啟用熱重啟、監(jiān)控文件變化時(shí)給出的輔助信息。判斷項(xiàng)目是否成功就看有沒有Started這行關(guān)鍵日志。如果你覺得它太干擾第一遍學(xué)習(xí)直接刪掉DevTools依賴后續(xù)再研究熱部署。第二類在IDE內(nèi)嵌瀏覽器或調(diào)試面板里看到“加載 web 視圖時(shí)出錯(cuò): error: could not register service worker”之類的提示。這通常和瀏覽器端的Service Worker注冊有關(guān)屬于本地WebView或緩存問題不影響Spring Boot后端接口的正常返回。處理方式很簡單刷新頁面、清理瀏覽器站點(diǎn)數(shù)據(jù)或者切換到自己常用的Chrome訪問接口就行。第三類引入Lombok后代碼里寫Data但getter/setter找不到。這是社區(qū)版里常見的插件坑。打開Settings - Plugins搜索Lombok并安裝然后在Settings里的Build Tools下找到Annotation Processors勾選Enable annotation processing。做完兩步后重新編譯問題基本就能解決。4.6 中文亂碼與編碼問題開發(fā)時(shí)最惱人的問題之一就是中文亂碼控制臺(tái)打印中文變亂碼或者接口返回中文亂碼。解決思路是先統(tǒng)一編碼。打開Settings - Editor - File Encodings把Global Encoding、Project Encoding、Default encoding for properties files全部設(shè)為UTF-8。然后在application.properties里顯式聲明server.servlet.encoding.charsetUTF-8 server.servlet.encoding.enabledtrue server.servlet.encoding.forcetrue這樣設(shè)置之后HTTP請求和響應(yīng)的編碼都會(huì)被強(qiáng)制為UTF-8接口返回中文基本不會(huì)再亂?？刂婆_(tái)如果還亂碼可以考慮在IDEA安裝目錄的vmoptions文件里加一行-Dfile.encodingUTF-8然后重啟IDEA。不過這個(gè)文件要小心修改改之前先備份。我個(gè)人在實(shí)際操作中的體會(huì)是多數(shù)編碼問題都是項(xiàng)目創(chuàng)建時(shí)默認(rèn)編碼沒設(shè)對導(dǎo)致源文件本身就不是UTF-8存儲(chǔ)。所以從新建項(xiàng)目一開始就統(tǒng)一UTF-8后面能省掉很多麻煩。第一次做Spring Boot Web項(xiàng)目沒必要急著往里面塞各種依賴和技術(shù)棧。先把“用社區(qū)版創(chuàng)建項(xiàng)目 - 導(dǎo)入IDEA - 寫一個(gè)接口 - 瀏覽器訪問成功”這條鏈路跑通建立正向反饋再逐步加數(shù)據(jù)庫、加MyBatis、加Redis、加攔截器。等以后項(xiàng)目多了你會(huì)發(fā)現(xiàn)start.spring.io生成的骨架里pom.xml和目錄結(jié)構(gòu)都是標(biāo)準(zhǔn)化模板完全可以攢一個(gè)自己常用的模板pom下次新建項(xiàng)目直接改坐標(biāo)能比從零配Maven快得多。