每年開學(xué)季和期末季學(xué)生公寓的報(bào)修需求都會(huì)集中爆發(fā)——水龍頭漏水、空調(diào)不制冷、寢室燈管閃壞、柜門合不上各種報(bào)修單子從宿管、電話、微信群里涌進(jìn)來(lái)靠人工登記和派單很容易漏單、錯(cuò)單、響應(yīng)慢。我之前帶團(tuán)隊(duì)做過(guò)一個(gè)基于SpringBoot的學(xué)生公寓報(bào)修平臺(tái)從需求梳理、數(shù)據(jù)庫(kù)設(shè)計(jì)到前后端聯(lián)調(diào)、打包部署全部走了一遍過(guò)程中踩了不少坑也沉淀了一些比較實(shí)用的經(jīng)驗(yàn)。這篇博文就把整個(gè)項(xiàng)目的設(shè)計(jì)思路、核心模塊、數(shù)據(jù)庫(kù)表結(jié)構(gòu)、關(guān)鍵代碼實(shí)現(xiàn)以及調(diào)試部署過(guò)程詳細(xì)拆開講希望對(duì)正在做類似管理系統(tǒng)、或者用SpringBoot做畢業(yè)設(shè)計(jì)的同學(xué)有幫助。這類平臺(tái)本質(zhì)上是一個(gè)典型的多角色業(yè)務(wù)管理系統(tǒng)核心價(jià)值就是把“學(xué)生報(bào)修—管理員派單—維修工處理—學(xué)生驗(yàn)收評(píng)價(jià)”這條鏈路搬到線上讓每一步都有記錄、可追蹤、能統(tǒng)計(jì)。先說(shuō)清楚它解決了什么問(wèn)題以前報(bào)修靠紙質(zhì)登記本或者微信群接龍信息分散、狀態(tài)不透明學(xué)生不知道維修師傅什么時(shí)候來(lái)管理員也沒(méi)法快速統(tǒng)計(jì)各樓棟的維修頻率。有了平臺(tái)之后學(xué)生在線提交工單系統(tǒng)自動(dòng)按樓棟、報(bào)修類型分類管理員一鍵指派維修工手機(jī)端接單、填寫維修結(jié)果學(xué)生確認(rèn)后還能評(píng)價(jià)整套流程閉環(huán)數(shù)據(jù)也能沉淀下來(lái)做報(bào)表分析。適合誰(shuí)來(lái)參考如果你正在做SpringBoot相關(guān)的課程設(shè)計(jì)、畢業(yè)設(shè)計(jì)或者想自己動(dòng)手從零搭一個(gè)前后端分離的管理系統(tǒng)這個(gè)項(xiàng)目的完整度很合適如果你已經(jīng)在寫代碼但不太清楚權(quán)限控制、工單狀態(tài)流轉(zhuǎn)這類業(yè)務(wù)怎么落地下面這些內(nèi)容也能給你一些直接的參考。1.1 一個(gè)真實(shí)的學(xué)生公寓報(bào)修流程是什么樣在設(shè)計(jì)系統(tǒng)之前我專門去學(xué)校后勤部門蹲了幾天把線下流程摸了個(gè)清楚。真實(shí)場(chǎng)景大致是這樣的學(xué)生發(fā)現(xiàn)宿舍設(shè)施損壞先找宿管登記宿管手寫一張報(bào)修單然后電話聯(lián)系維修工。維修工有空就上門沒(méi)空就讓宿管盯著修完在單子上簽個(gè)字就算結(jié)束。這中間的痛點(diǎn)是樓棟一多報(bào)修單容易漏宿舍報(bào)修高峰期紙質(zhì)單子堆積響應(yīng)順序全靠人工判斷維修進(jìn)度學(xué)生完全不知道。所以平臺(tái)在還原線下流程的基礎(chǔ)上做了數(shù)字化改造核心流程設(shè)計(jì)成四步學(xué)生提交工單 → 管理員分配維修工 → 維修工處理并填寫結(jié)果 → 學(xué)生確認(rèn)驗(yàn)收并評(píng)價(jià)。每一步都有對(duì)應(yīng)的角色和狀態(tài)約束不允許跨狀態(tài)操作。比如維修工只能處理“待維修”狀態(tài)的工單處理完必須填寫維修耗時(shí)和材料消耗學(xué)生只能在狀態(tài)為“已完成”時(shí)進(jìn)行驗(yàn)收驗(yàn)收不通過(guò)可以退回返修。這樣設(shè)計(jì)的好處是每個(gè)環(huán)節(jié)都有責(zé)任人出現(xiàn)糾紛時(shí)能直接通過(guò)系統(tǒng)日志定位。1.2 為什么選SpringBoot而不是其他框架很多人問(wèn)做個(gè)報(bào)修平臺(tái)用SpringBoot是不是殺雞用牛刀其實(shí)不是。選SpringBoot有幾個(gè)很實(shí)在的理由第一它生態(tài)成熟MyBatis-Plus、Redis、Shiro、MinIO這些常用組件都有非常完善的和SpringBoot的整合文檔開發(fā)效率高第二它內(nèi)置Tomcat打包成jar就能直接跑部署成本低對(duì)學(xué)生項(xiàng)目和中小型系統(tǒng)來(lái)說(shuō)非常友好第三社區(qū)活躍面試和畢業(yè)答辯時(shí)也容易講清楚。另外我對(duì)比過(guò)SSHStrutsSpringHibernate和SpringMVC單體架構(gòu)SSH現(xiàn)在已經(jīng)很少有人用了配置XML太繁瑣純SpringMVC雖然更輕量但要做大量的手動(dòng)配置比如數(shù)據(jù)源、事務(wù)、json轉(zhuǎn)換等。SpringBoot通過(guò)自動(dòng)配置把這些全封裝掉了我們只需要關(guān)注業(yè)務(wù)代碼。當(dāng)然SpringBoot也有弱點(diǎn)就是自動(dòng)配置的黑盒機(jī)制出了問(wèn)題排查起來(lái)比較費(fèi)勁這個(gè)在后面“常見(jiàn)問(wèn)題”部分我會(huì)專門講。1.3 這個(gè)項(xiàng)目交付物里到底包含哪些東西標(biāo)題里提到的“程序源碼數(shù)據(jù)庫(kù)調(diào)試部署開發(fā)環(huán)境”拆開來(lái)看其實(shí)是五個(gè)層次程序是打包好的可運(yùn)行物源碼是可讀、可改的工程代碼數(shù)據(jù)庫(kù)是建庫(kù)建表的SQL腳本和初始數(shù)據(jù)調(diào)試部署是詳細(xì)的啟動(dòng)步驟和常見(jiàn)錯(cuò)誤解決辦法開發(fā)環(huán)境就是JDK、MySQL、IDEA、Maven這些工具的版本和配置要求。我建議拿到項(xiàng)目后先按順序做先導(dǎo)入源碼到IDEA再執(zhí)行SQL腳本初始化數(shù)據(jù)庫(kù)然后修改application.yml里的數(shù)據(jù)庫(kù)連接信息最后啟動(dòng)檢查控制臺(tái)日志。不要一上來(lái)就想改功能先把系統(tǒng)跑通再動(dòng)手改代碼這樣出問(wèn)題的時(shí)候你才知道是環(huán)境問(wèn)題還是業(yè)務(wù)代碼問(wèn)題。2. 整體架構(gòu)與模塊設(shè)計(jì)拆解整個(gè)平臺(tái)采用的是經(jīng)典的SSM微服務(wù)雛形不這里用的是SpringBoot單體架構(gòu)。為什么不用微服務(wù)因?yàn)閷W(xué)生公寓報(bào)修平臺(tái)的核心業(yè)務(wù)是工單流轉(zhuǎn)和人員管理并發(fā)量不大單體架構(gòu)部署簡(jiǎn)單、維護(hù)成本低、事務(wù)控制容易完全夠用。如果硬拆成微服務(wù)反而會(huì)因?yàn)榉植际绞聞?wù)、服務(wù)間調(diào)用等問(wèn)題把項(xiàng)目復(fù)雜度拉高對(duì)學(xué)習(xí)和答辯都不利。這個(gè)選擇我覺(jué)得是合理的在實(shí)際項(xiàng)目中能用單體解決的絕對(duì)不上微服務(wù)。2.1 三種角色一張圖看懂權(quán)限邊界系統(tǒng)里一共三類角色學(xué)生普通用戶、維修工、管理員。權(quán)限邊界用一句話概括學(xué)生管自己的報(bào)修單維修工管被分給自己的任務(wù)管理員管全局配置和數(shù)據(jù)統(tǒng)計(jì)。角色核心權(quán)限主要操作學(xué)生報(bào)修、查詢、評(píng)價(jià)提交報(bào)修工單、查看處理進(jìn)度、確認(rèn)驗(yàn)收、評(píng)價(jià)評(píng)分、修改個(gè)人信息維修工任務(wù)處理查看我的工單、接單/退單、填寫維修結(jié)果、上傳維修后照片管理員全站管理工單派發(fā)/改派、用戶管理、樓棟與報(bào)修類型維護(hù)、數(shù)據(jù)統(tǒng)計(jì)、公告發(fā)布三個(gè)角色共用一套登錄認(rèn)證邏輯登錄成功后返回的角色碼不同前端根據(jù)角色碼渲染不同的菜單后端在接口層級(jí)做權(quán)限攔截。這里我建議權(quán)限校驗(yàn)放在后端做前端隱藏菜單只是體驗(yàn)優(yōu)化不是安全手段。實(shí)際操作中有些同學(xué)只在前端做路由判斷后端接口不攔結(jié)果有人直接調(diào)用接口繞過(guò)了權(quán)限這是很典型的安全漏洞。2.2 報(bào)修工單的生命周期設(shè)計(jì)工單是系統(tǒng)的核心實(shí)體我把它的狀態(tài)設(shè)計(jì)成七個(gè)待派單、待接單、維修中、已完成、已驗(yàn)收、已駁回、已取消。狀態(tài)的變遷不是隨意的而是有嚴(yán)格的動(dòng)作約束學(xué)生提交后工單進(jìn)入“待派單”狀態(tài)此時(shí)只有管理員能看到并派單。管理員派單給某個(gè)維修工后狀態(tài)變?yōu)椤按訂巍本S修工可以接單狀態(tài)變?yōu)椤熬S修中”也可以申請(qǐng)退單退回給管理員。維修工處理完成并填寫結(jié)果后狀態(tài)變?yōu)椤耙淹瓿伞贝藭r(shí)學(xué)生端才會(huì)出現(xiàn)“驗(yàn)收”按鈕。學(xué)生點(diǎn)擊驗(yàn)收通過(guò)后狀態(tài)變?yōu)椤耙羊?yàn)收”流程結(jié)束如果驗(yàn)收不通過(guò)可以填駁回意見(jiàn)工單重新回到“待派單”狀態(tài)管理員可重新派單或催辦。“已取消”狀態(tài)主要用于學(xué)生提交后發(fā)現(xiàn)填錯(cuò)或自行解決了在沒(méi)有被派單之前取消。一旦派單學(xué)生就不能自行取消了得聯(lián)系管理員處理。這里有一個(gè)非常容易踩坑的地方狀態(tài)字段如果用int存代碼里每個(gè)數(shù)字代表什么含義很容易忘記特別容易改錯(cuò)。我建議用枚舉統(tǒng)一管理代碼里只允許通過(guò)枚舉轉(zhuǎn)換數(shù)據(jù)庫(kù)里存字符串枚舉名這樣可讀性和維護(hù)性都好很多。后面我貼了具體代碼可以直接參考。2.3 功能模塊劃分與接口設(shè)計(jì)整個(gè)系統(tǒng)按業(yè)務(wù)域劃分成六大模塊用戶模塊、工單模塊、報(bào)修類型模塊、樓棟管理模塊、公告模塊、統(tǒng)計(jì)報(bào)表模塊。每個(gè)模塊的接口遵循RESTful風(fēng)格返回統(tǒng)一格式的Result對(duì)象結(jié)構(gòu)為code、message、data三件套。前端先判斷code是否等于200再取data這樣后端拋異常時(shí)也能統(tǒng)一返回code500前端彈一個(gè)錯(cuò)誤提示不白屏。接口命名方面我按資源來(lái)設(shè)計(jì)比如POST /api/repair/order 提交工單GET /api/repair/order/list 查詢工單列表支持分頁(yè)和條件查詢PUT /api/repair/order/assign 管理員派單PUT /api/repair/order/processing 維修工接單/處理PUT /api/repair/order/accept 學(xué)生驗(yàn)收這種以資源加動(dòng)作為核心的命名方式前后端對(duì)接的時(shí)候非常直觀也方便寫接口文檔。開發(fā)期間我把接口文檔用Swagger生成寫接口的時(shí)候就順手加上注解省得后面還要單獨(dú)維護(hù)文檔。3. 數(shù)據(jù)庫(kù)設(shè)計(jì)與核心表結(jié)構(gòu)數(shù)據(jù)庫(kù)設(shè)計(jì)是整個(gè)項(xiàng)目的地基地基沒(méi)打好后面寫接口的時(shí)候就會(huì)各種別扭。我在設(shè)計(jì)時(shí)遵循幾個(gè)原則一是表名和字段名用清晰的英文命名二是所有業(yè)務(wù)表都要有id、create_time、update_time這三個(gè)字段三是金額、狀態(tài)這類字段用int或decimal存不要用varchar存數(shù)字否則排序和統(tǒng)計(jì)都會(huì)出問(wèn)題。3.1 核心表設(shè)計(jì)一覽系統(tǒng)核心共八張表我把最關(guān)鍵的列和說(shuō)明列出來(lái)表名說(shuō)明關(guān)鍵字段t_user用戶表id、username、password、real_name、role_id、phone、dormitory_idt_repair_order報(bào)修工單表id、order_no、student_id、dormitory_id、type_id、description、images、status、processor_id、process_time、apply_remarkt_repair_type報(bào)修類型表id、type_name、sortt_dormitory樓棟/宿舍表id、building_no、room_no、managert_repair_log工單操作日志表id、order_id、operator_id、action、remark、create_timet_announcement公告表id、title、content、publisher_id、create_timet_comment評(píng)價(jià)表id、order_id、student_id、score、content、create_timet_role角色表id、role_name、role_code3.2 工單表的設(shè)計(jì)細(xì)節(jié)t_repair_order是核心我把幾個(gè)容易出問(wèn)題的地方單獨(dú)說(shuō)一下。首先是order_no工單編號(hào)我用了“日期流水號(hào)”的生成規(guī)則格式是20250613001含義是2025年6月13日第1單。生成邏輯是查當(dāng)天最大編號(hào)加1用Redis的incr做自增計(jì)數(shù)更穩(wěn)但如果沒(méi)有Redis用查詢鎖也能實(shí)現(xiàn)只是并發(fā)高時(shí)有可能會(huì)重復(fù)需要注意加數(shù)據(jù)庫(kù)唯一索引兜底。其次是images字段存的是用戶上傳的故障照片URL多個(gè)用逗號(hào)分隔。有些同學(xué)會(huì)單獨(dú)建一張圖片表也可以但在照片數(shù)量不多的小系統(tǒng)里直接用分隔符存儲(chǔ)更簡(jiǎn)單查詢工單詳情時(shí)切分一下就能渲染。我實(shí)際開發(fā)時(shí)是把圖片傳到MinIO返回的URL直接存到images字段里包工時(shí)再把URL取出拼接成json傳給前端。第三是processor_id表示當(dāng)前負(fù)責(zé)的維修工。一個(gè)工單在流轉(zhuǎn)中可能被多次改派所以processor_id只存當(dāng)前處理人歷史流轉(zhuǎn)記錄全部記到t_repair_log里。這樣的設(shè)計(jì)讓工單表本身保持簡(jiǎn)潔同時(shí)日志表可以追溯整個(gè)處理過(guò)程審計(jì)也方便。3.3 邏輯刪除與樂(lè)觀鎖的實(shí)踐開發(fā)過(guò)程中我踩過(guò)一個(gè)很經(jīng)典的坑刪除用戶時(shí)直接delete結(jié)果把歷史工單里的學(xué)生關(guān)聯(lián)搞沒(méi)了導(dǎo)致工單統(tǒng)計(jì)的時(shí)候數(shù)據(jù)對(duì)不上。后來(lái)我給所有業(yè)務(wù)表都加了deleted字段用MyBatis-Plus的TableLogic做邏輯刪除。查詢時(shí)框架自動(dòng)拼接deleted 0刪除操作實(shí)際是update歷史數(shù)據(jù)永遠(yuǎn)保留。這個(gè)習(xí)慣我在做其他系統(tǒng)時(shí)也沿用強(qiáng)烈建議大家從一開始就加上。樂(lè)觀鎖則用在工單狀態(tài)的并發(fā)更新上。設(shè)想一個(gè)場(chǎng)景管理員在處理工單的同時(shí)維修工也點(diǎn)了接單兩個(gè)請(qǐng)求同時(shí)讀到狀態(tài)是“待接單”都執(zhí)行了update就可能出現(xiàn)狀態(tài)覆蓋。解決辦法是給t_repair_order加version字段更新時(shí)帶上WHERE version #{version}判斷影響行數(shù)如果為零說(shuō)明被別人改過(guò)了提示用戶稍后重試。MyBatis-Plus自帶Version插件開啟樂(lè)觀鎖只是幾行配置的事強(qiáng)烈推薦加上。4. 核心功能實(shí)現(xiàn)的幾個(gè)關(guān)鍵點(diǎn)這一部分我講一下開發(fā)過(guò)程中值得反復(fù)斟酌的幾個(gè)技術(shù)點(diǎn)每個(gè)都涉及到系統(tǒng)的穩(wěn)定性和用戶體驗(yàn)也是答辯時(shí)老師容易追問(wèn)的地方。4.1 工單狀態(tài)機(jī)與流轉(zhuǎn)控制狀態(tài)機(jī)是整個(gè)業(yè)務(wù)最核心的部分。我建議不要在每個(gè)接口里都寫一遍if判斷而是把狀態(tài)流轉(zhuǎn)抽出來(lái)統(tǒng)一管理。實(shí)現(xiàn)方式有輕量和重量?jī)煞N輕量方式是用枚舉加一個(gè)變更校驗(yàn)方法重量方式是引入狀態(tài)機(jī)框架比如Spring StateMachine。對(duì)報(bào)修平臺(tái)這個(gè)規(guī)模用輕量方式就夠了。我自己寫了一個(gè)RepairOrderState枚舉里面定義狀態(tài)和允許的流轉(zhuǎn)目標(biāo)然后提供一個(gè)transition方法進(jìn)入新?tīng)顟B(tài)前先校驗(yàn)當(dāng)前狀態(tài)是否允許流轉(zhuǎn)到目標(biāo)狀態(tài)不允許就拋業(yè)務(wù)異常。這樣所有狀態(tài)更新都走同一個(gè)入口不會(huì)出現(xiàn)在A接口改了狀態(tài)但沒(méi)記錄日志的情況。我把日志寫入也放在transition方法里每流轉(zhuǎn)一次就自動(dòng)往t_repair_log插一條記錄省得每個(gè)接口手動(dòng)去寫日志邏輯統(tǒng)一且不容易漏。4.2 前后端分離下的權(quán)限控制系統(tǒng)采用前后端分離架構(gòu)后端接口用JWT做無(wú)狀態(tài)認(rèn)證。登錄成功后簽發(fā)token前端存到localStorage每次請(qǐng)求在header里帶上Authorization。后端用一個(gè)攔截器統(tǒng)一解析token解析出userId和roleCode放到ThreadLocal里Controller直接取。權(quán)限校驗(yàn)我是在攔截器里根據(jù)角色碼做簡(jiǎn)單判斷哪些接口管理員才能訪問(wèn)哪些是維修工專屬。比如/admin/**開頭的接口只能管理員訪問(wèn)/worker/**只能維修工訪問(wèn)/student/**只能學(xué)生訪問(wèn)。如果接口放錯(cuò)路徑權(quán)限就崩了所以不建議用URL前綴做粗粒度權(quán)限。更合理的做法是使用RequireRole這樣的注解標(biāo)注在Controller方法上攔截器通過(guò)反射讀取注解做校驗(yàn)這樣權(quán)限和接口寫在了一起可讀性也更高。4.3 圖片上傳與MinIO接入的方式報(bào)修必然要上傳故障照片這是整個(gè)項(xiàng)目里最容易出問(wèn)題的一環(huán)。一開始我用的是本地磁盤存儲(chǔ)把上傳的文件寫到服務(wù)器的某個(gè)目錄然后返回URL看起來(lái)簡(jiǎn)單但有兩個(gè)坑一是服務(wù)器重啟后目錄丟失二是前端直接訪問(wèn)磁盤路徑會(huì)有跨域和權(quán)限問(wèn)題。后來(lái)我換成了MinIO一個(gè)開源的對(duì)象存儲(chǔ)服務(wù)部署起來(lái)就一個(gè)docker命令的事本地開發(fā)也可以直接跑。SpringBoot整合MinIO其實(shí)不復(fù)雜。先在pom.xml引入io.minio:minio依賴然后在application.yml配endpoint、accessKey、secretKey、bucketName寫一個(gè)MinioService里面封裝上傳、刪除、獲取訪問(wèn)地址這幾個(gè)方法。上傳時(shí)用UUID給文件重命名防止重名覆蓋。有一點(diǎn)需要注意MinIO的bucket要提前創(chuàng)建并設(shè)置公共讀策略否則前端拿到的URL預(yù)覽會(huì)404。這個(gè)問(wèn)題我當(dāng)時(shí)排查了很久最后發(fā)現(xiàn)是bucket的訪問(wèn)權(quán)限沒(méi)設(shè)置對(duì)。4.4 站內(nèi)信與微信通知的取舍工單狀態(tài)變了學(xué)生怎么第一時(shí)間知道最開始我只做了站內(nèi)信就是工單列表里加個(gè)未讀紅點(diǎn)后來(lái)發(fā)現(xiàn)很多學(xué)生根本不會(huì)主動(dòng)刷新網(wǎng)頁(yè)于是加了WebSocket推送。實(shí)現(xiàn)方式是用Spring的WebSocket握手時(shí)從token里解析userId后端維護(hù)一個(gè)userId到Session的映射工單狀態(tài)變更時(shí)主動(dòng)推送一條消息給對(duì)應(yīng)學(xué)生。這里有個(gè)細(xì)節(jié)WebSocket的Session不是線程安全的多線程并發(fā)推送前要加鎖否則會(huì)出現(xiàn)消息丟失或異常。WebSocket推送只是“錦上添花”實(shí)際運(yùn)行時(shí)如果學(xué)生關(guān)了網(wǎng)頁(yè)推送還是收不到。所以最終方案是站內(nèi)信保底WebSocket只做實(shí)時(shí)提醒。我建議做這類系統(tǒng)時(shí)不要過(guò)度依賴推送數(shù)據(jù)庫(kù)里的消息表才是數(shù)據(jù)本體推送只是通知手段。很多同學(xué)做這類項(xiàng)目喜歡把推送放得很重結(jié)果一重啟連接就全斷反而把系統(tǒng)復(fù)雜度拉高了。5. 開發(fā)環(huán)境搭建與調(diào)試部署實(shí)錄很多人在項(xiàng)目開發(fā)階段很順利一到部署就各種報(bào)錯(cuò)環(huán)境問(wèn)題占了很大比重。我把自己實(shí)際搭建環(huán)境、調(diào)試、部署的過(guò)程完整記錄下來(lái)包括版本選擇、配置項(xiàng)和遇到的重點(diǎn)問(wèn)題照著走基本能少踩一半坑。5.1 開發(fā)環(huán)境版本與安裝說(shuō)明我用的開發(fā)環(huán)境就是標(biāo)題里說(shuō)的“程序源碼數(shù)據(jù)庫(kù)調(diào)試部署開發(fā)環(huán)境”那一套具體版本如下工具推薦版本說(shuō)明JDK1.8 或 11SpringBoot 2.7.x 對(duì)這兩個(gè)版本支持最穩(wěn)IDEA2023.x 及以上社區(qū)版完全夠用不用買旗艦版Maven3.8.x不要用3.9.0之后的版本有些倉(cāng)庫(kù)兼容有問(wèn)題MySQL5.7 或 8.0推薦8.0注意時(shí)區(qū)和驅(qū)動(dòng)配置Redis6.x用于token緩存和工單號(hào)自增安裝順序我建議先裝JDK再裝Maven然后是MySQL最后是Redis。每次裝完都驗(yàn)證一下環(huán)境變量JDK驗(yàn)證命令java -versionMaven驗(yàn)證mvn -vMySQL驗(yàn)證mysql --version。很多的坑往往發(fā)生在環(huán)境變量沒(méi)配置好導(dǎo)致IDEA里編譯的時(shí)候能過(guò)但命令行跑jar包就跑不起來(lái)。5.2 SpringBoot核心配置與關(guān)鍵參數(shù)application.yml是SpringBoot啟動(dòng)的核心我把關(guān)鍵的配置項(xiàng)解釋一下特別標(biāo)注幾個(gè)容易出錯(cuò)的地方server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/repair_platform?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver redis: host: localhost port: 6379 database: 0 servlet: multipart: max-file-size: 10MB max-request-size: 20MB mybatis-plus: mapper-locations: classpath*:mapper/*.xml configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl有幾個(gè)參數(shù)我要特別強(qiáng)調(diào)。第一是serverTimezone如果MySQL用的8.0url里必須帶serverTimezoneAsia/Shanghai否則JDBC驅(qū)動(dòng)會(huì)報(bào)“The server time zone value”的錯(cuò)這是新手最常見(jiàn)的問(wèn)題。第二是map-underscore-to-camel-case這個(gè)開關(guān)默認(rèn)是開的可以讓數(shù)據(jù)庫(kù)字段create_time自動(dòng)映射到Java屬性的createTime省去大量TableField注解。第三是multipart上傳大小的限制如果照片原圖比較大默認(rèn)1MB的限制是不夠的我配置成了10MB實(shí)際一張手機(jī)拍的照片通常在3-5MB左右。5.3 前端資源打包后放進(jìn)SpringBoot的整合技巧實(shí)際部署時(shí)為了省一臺(tái)服務(wù)器我把前端Vue項(xiàng)目打包后的dist目錄直接放進(jìn)SpringBoot的靜態(tài)資源目錄這樣整個(gè)系統(tǒng)就是一個(gè)jar包java -jar啟動(dòng)后既能訪問(wèn)后端接口也能訪問(wèn)前端頁(yè)面非常方便。具體步驟是這樣先在前端項(xiàng)目根目錄執(zhí)行npm run build打包后生成一個(gè)dist目錄。把dist目錄里的全部文件復(fù)制到后端src/main/resources/static目錄下。然后重新用Maven打包后端生成的jar就自帶前端頁(yè)面了。前端打包后默認(rèn)的靜態(tài)資源路徑是/和后端接口的/api前綴不沖突。如果前端用了history路由模式記得要在后端加一個(gè)轉(zhuǎn)發(fā)保證刷新頁(yè)面時(shí)不會(huì)404不然單擊刷新頁(yè)面就報(bào)404非常影響體驗(yàn)。我是在SpringBoot里加了個(gè)WebMvcConfigurer把非/api的路徑全部轉(zhuǎn)發(fā)到index.html幾行代碼搞定。5.4 三種部署方式的對(duì)比與選擇部署方式我試過(guò)三種本地IDEA直接啟動(dòng)、Linux服務(wù)器jar包部署、Docker容器化部署。本地IDEA啟動(dòng)適合開發(fā)調(diào)試按ShiftF10就能跑斷點(diǎn)調(diào)試最方便。Linux服務(wù)器jar部署適合小規(guī)模正式使用把打包好的jar上傳到服務(wù)器執(zhí)行nohup java -jar xxx.jar app.log 21 日志輸出到app.log方便排查。Docker部署適合環(huán)境統(tǒng)一寫一個(gè)Dockerfile把JDK和jar打進(jìn)鏡像再用docker run啟動(dòng)換服務(wù)器的時(shí)候一條命令就能拉起環(huán)境。從穩(wěn)定性角度我最推薦Linuxjar的方式原因很簡(jiǎn)單Docker雖然好但要額外運(yùn)維鏡像倉(cāng)庫(kù)對(duì)學(xué)生項(xiàng)目來(lái)說(shuō)有點(diǎn)重。jar方式只需要一臺(tái)能跑Java的服務(wù)器就夠了出了問(wèn)題看日志也比較直觀。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄這部分我把實(shí)際開發(fā)和部署過(guò)程中遇到的高頻問(wèn)題記錄下來(lái)按照現(xiàn)象、原因、解決辦法三個(gè)維度整理成速查表方便你遇到同樣問(wèn)題的時(shí)候直接對(duì)號(hào)入座。6.1 啟動(dòng)時(shí)報(bào)數(shù)據(jù)庫(kù)連接錯(cuò)誤報(bào)錯(cuò)信息一般是“Cannot connect to MySQL server”或“Access denied for user”。大多數(shù)原因是數(shù)據(jù)庫(kù)沒(méi)有啟動(dòng)、賬號(hào)密碼不對(duì)、或者url里的host端口寫錯(cuò)。排查順序建議先手動(dòng)用命令行mysql -u root -p試試能不能連上確認(rèn)數(shù)據(jù)庫(kù)本身沒(méi)問(wèn)題再看SpringBoot配置文件的url、username、password是否一致。還有一個(gè)隱蔽原因如果你的MySQL跑在遠(yuǎn)程服務(wù)器上本地連不上可能是MySQL的bind-address默認(rèn)綁定了127.0.0.1需要改成0.0.0.0然后授權(quán)遠(yuǎn)程訪問(wèn)。這個(gè)我在自己的項(xiàng)目里遇到過(guò)本地IDEA能連部署到服務(wù)器上就連不上最后發(fā)現(xiàn)是MySQL的安全配置問(wèn)題不是SpringBoot代碼的問(wèn)題。6.2 端口被占用怎么辦jar部署時(shí)最常遇到的報(bào)錯(cuò)是“Port 8080 was already in use”。先用netstat -tlnp | grep 8080找到占用端口的進(jìn)程確認(rèn)是不是自己之前啟動(dòng)的舊進(jìn)程kill掉之后重新啟動(dòng)就好。如果你有多個(gè)項(xiàng)目要同時(shí)跑可以在application.yml里用server.port改成8081、8082等也可以啟動(dòng)時(shí)用--server.port8081覆蓋配置文件里的端口靈活一些。如果服務(wù)器上已經(jīng)有nginx或其他服務(wù)占用了80端口我一般會(huì)把SpringBoot服務(wù)跑在8080然后通過(guò)nginx反向代理到80對(duì)外提供服務(wù)。這樣既不影響現(xiàn)有服務(wù)又不用改代碼。6.3 Maven依賴沖突與下載失敗SpringBoot項(xiàng)目依賴多時(shí)不時(shí)會(huì)遇到j(luò)ar包下載失敗或者依賴沖突。下載失敗大概率是Maven倉(cāng)庫(kù)源的問(wèn)題國(guó)內(nèi)網(wǎng)絡(luò)訪問(wèn)中央倉(cāng)庫(kù)經(jīng)常超時(shí)我建議在settings.xml里把鏡像源換成阿里云鏡像基本一次解決。依賴沖突的表現(xiàn)是啟動(dòng)時(shí)報(bào)NoClassDefFoundError或者bean創(chuàng)建異常原因一般是同一個(gè)類有多個(gè)版本的jar被加載。排查依賴沖突的命令是mvn dependency:tree看依賴樹里有沒(méi)有重復(fù)的jar包。比如很多同學(xué)同時(shí)引入了spring-boot-starter-web和spring-boot-starter-actuator版本不一致時(shí)就會(huì)出現(xiàn)沖突。解決辦法是使用Maven的依賴管理機(jī)制通過(guò)dependencyManagement統(tǒng)一版本號(hào)或者用exclusion把多余的傳遞依賴去掉。我自己的習(xí)慣是在pom.xml的properties里統(tǒng)一聲明版本減少版本沖突的可能性。6.4 文件上傳后無(wú)法預(yù)覽或丟失圖片上傳后前端拿不到預(yù)覽圖這個(gè)問(wèn)題的原因是多樣的。如果是MinIO存儲(chǔ)先確認(rèn)bucket是否設(shè)置了公開讀權(quán)限如果是本地存儲(chǔ)檢查上傳文件路徑是否真的有文件以及返回的URL是否能通過(guò)瀏覽器直接訪問(wèn)。還要注意一個(gè)細(xì)節(jié)SpringBoot默認(rèn)對(duì)靜態(tài)資源的映射不包括磁盤上的其他目錄所以本地存儲(chǔ)時(shí)我建議把上傳目錄放到resources/static下的uploads文件夾或者通過(guò)自定義資源映射把磁盤路徑映射成/image/**,否則前端訪問(wèn)不了。文件丟失的問(wèn)題通常是服務(wù)器重啟后磁盤文件沒(méi)了所以我一直推薦用MinIO或者OSS把文件數(shù)據(jù)和服務(wù)本身解耦服務(wù)器掛了也不怕。這一點(diǎn)在標(biāo)題里雖然沒(méi)有直接體現(xiàn)但“minio加入到springboot”這個(gè)點(diǎn)很多人在做報(bào)修平臺(tái)時(shí)都會(huì)用到我也就順便講透。6.5 一個(gè)容易被忽略的bug事務(wù)失效在把多個(gè)寫操作放在一起的時(shí)候如果方法沒(méi)有加Transactional注解或者類沒(méi)有被Spring管理就會(huì)出現(xiàn)事務(wù)失效的情況。報(bào)修工單創(chuàng)建、日志插入、通知寫入這三個(gè)操作如果不在一個(gè)事務(wù)里日志插入失敗時(shí)工單已經(jīng)提交了數(shù)據(jù)就亂了。排查事務(wù)失效有個(gè)技巧加Transactional的方法不能是private的不能被this調(diào)用還要把異常拋出到事務(wù)邊界之外否則異常被捕獲了事務(wù)不會(huì)回滾。我實(shí)際開發(fā)時(shí)有一次工單創(chuàng)建成功后報(bào)錯(cuò)檢查發(fā)現(xiàn)日志插入方法沒(méi)有加Transactional導(dǎo)致創(chuàng)建和日志不一致加上注解并在Service入口統(tǒng)一管理事務(wù)后就好了。這個(gè)經(jīng)驗(yàn)值得記下來(lái)很多反復(fù)出現(xiàn)的“靈異bug”其實(shí)都是事務(wù)邊界的問(wèn)題。7. 常用調(diào)試技巧與個(gè)人體會(huì)最后分享幾個(gè)自己總結(jié)的調(diào)試技巧和心得。第一日志要善用但不濫用。開發(fā)時(shí)MyBatis-Plus控制臺(tái)輸出SQL日志可以看到每次執(zhí)行的完整SQL排查問(wèn)題直接看日志不要靠猜。線上部署時(shí)把日志級(jí)別調(diào)成INFO避免刷屏影響性能。第二前后端聯(lián)調(diào)時(shí)先抓包看請(qǐng)求和響應(yīng)體很多問(wèn)題一看就是參數(shù)名不對(duì)或缺失字段不用急著改代碼。第三接口測(cè)試用Postman或Apifox把常用的接口做成集合改完代碼跑一遍回歸測(cè)試比手工點(diǎn)前端頁(yè)面高效很多。我個(gè)人在實(shí)際開發(fā)后最深的感受是這類多角色系統(tǒng)的難點(diǎn)不在CRUD而在業(yè)務(wù)的完整性和數(shù)據(jù)的準(zhǔn)確性。狀態(tài)流轉(zhuǎn)約束、權(quán)限校驗(yàn)、事務(wù)邊界、字段設(shè)計(jì)的規(guī)范性這些才是真正拉開代碼質(zhì)量差距的地方。另外給正在做畢業(yè)論文/畢設(shè)的同學(xué)一個(gè)建議不要只滿足于“能跑”把狀態(tài)機(jī)設(shè)計(jì)、權(quán)限方案、文件存儲(chǔ)方案、事務(wù)控制這幾個(gè)點(diǎn)講明白答辯的時(shí)候這就是亮點(diǎn)。這個(gè)系統(tǒng)后續(xù)如果要擴(kuò)展方向也挺明確的一是把微信小程序端補(bǔ)上學(xué)生更習(xí)慣用手機(jī)報(bào)修二是增加工單超時(shí)提醒用定時(shí)任務(wù)掃描超時(shí)未接單的工單自動(dòng)提醒管理員三是數(shù)據(jù)統(tǒng)計(jì)做可視化大屏按樓棟、按類型展示維修頻次和平均響應(yīng)時(shí)長(zhǎng)后勤部門會(huì)很需要。我這邊也打算把小程序端和定時(shí)提醒做出來(lái)后面攢夠經(jīng)驗(yàn)再寫一篇分享。如果你正在調(diào)這個(gè)項(xiàng)目遇到問(wèn)題歡迎把報(bào)錯(cuò)信息發(fā)在交流區(qū)我看到都會(huì)回復(fù)。