接手高校辦公室行政事務(wù)管理系統(tǒng)這類項目第一步通常不是打開集成開發(fā)環(huán)境而是先坐下來把業(yè)務(wù)捋清楚。高校辦公室每天經(jīng)手的事情看著零碎但匯總起來無非是幾大類公文收發(fā)與流轉(zhuǎn)、會議安排與紀(jì)要、用章用印申請、公務(wù)用車安排、固定資產(chǎn)登記與報修、日常值班和通知公告。標(biāo)題里這套“Java Web mvc高校辦公室行政事務(wù)管理系統(tǒng)”技術(shù)棧寫得很明確——SpringBoot2 Vue3 MyBatis-Plus MySQL8.0還帶文檔。這個組合在當(dāng)下高校信息中心的開發(fā)環(huán)境里屬于非常務(wù)實的搭配既有SpringBoot2生態(tài)的成熟穩(wěn)定又有Vue3前端工程化的開發(fā)效率適合用來承載一套標(biāo)準(zhǔn)的管理信息系統(tǒng)。這類系統(tǒng)的價值不在于技術(shù)有多新而在于把行政流程線上化之后辦公室的臺賬清楚、審批可追溯、數(shù)據(jù)能統(tǒng)計。權(quán)限模型是它的骨架工作流節(jié)點是它的脈絡(luò)Excel導(dǎo)出是辦公室老師最關(guān)心的功能之一。對開發(fā)新人或者正在做畢業(yè)設(shè)計、課程項目的同學(xué)來說這個項目是很好的練手對象麻雀雖小但五臟俱全從前端路由權(quán)限到后端接口鑒權(quán)從數(shù)據(jù)庫設(shè)計到部署上線整條鏈路都能跑通。這篇文章我就順著這套系統(tǒng)的結(jié)構(gòu)把實現(xiàn)思路、關(guān)鍵代碼、實操步驟和踩坑記錄都拆開講一遍。1. 這個系統(tǒng)在解決什么問題模塊拆解與需求定位1.1 高校辦公室的日常一堆審批流和數(shù)據(jù)臺賬我在剛開始接觸行政管理系統(tǒng)時也有一個誤判覺得這不就是一個信息增刪改查嗎真正梳理之后才發(fā)現(xiàn)辦公系統(tǒng)的核心難點在流程狀態(tài)機上。一份發(fā)文稿從擬稿人提交到科室負(fù)責(zé)人審核到分管領(lǐng)導(dǎo)簽發(fā)再到辦公室編號用印歸檔中間每一個環(huán)節(jié)的狀態(tài)、操作人、處理時間、意見都要記錄。會議室申請要經(jīng)過部門預(yù)約、管理員審核、時間沖突檢測用車申請要把用車事由、時間段、司機、車輛綁定在一起固定資產(chǎn)報修要跟蹤報修狀態(tài)和維修結(jié)果。這套系統(tǒng)把這些流程拆成了幾大業(yè)務(wù)模塊通知公告、公文管理、會議管理、用車管理、資產(chǎn)管理、值班管理、印章管理再配上一套通用的用戶角色權(quán)限體系。模塊之間不是孤立的比如用戶信息是所有業(yè)務(wù)單據(jù)的基礎(chǔ)角色權(quán)限決定了誰能發(fā)起審批、誰能通過審批通知公告又承擔(dān)了系統(tǒng)消息觸達(dá)的職責(zé)。理解這層依賴關(guān)系比單純照著表結(jié)構(gòu)建表重要得多。1.2 功能模塊的邊界怎么畫模塊拆分的核心原則是按“業(yè)務(wù)對象生命周期”來劃分而不是按頁面劃分。什么意思呢比如“會議室預(yù)約”和“會議管理”看起來可以合在一起但它們是兩個生命周期的不同階段一個是會前資源申請一個是會中信息登記和會后紀(jì)要與決議跟蹤。拆開設(shè)計狀態(tài)機更清晰邏輯更簡單。這套系統(tǒng)的模塊列表大概是這樣的系統(tǒng)管理用戶、角色、菜單、部門管理以及操作日志通知公告發(fā)布、編輯、置頂、失效PC端和移動端都能查看公文管理發(fā)文、收文、審批流轉(zhuǎn)、套紅頭、歸檔查詢會議管理會議室資源維護、預(yù)約申請、審核、會議紀(jì)要與決議跟蹤用車管理車輛信息、司機信息、用車申請、派車審核、行程記錄資產(chǎn)管理資產(chǎn)臺賬、領(lǐng)用登記、報修申請、維修記錄值班管理值班計劃排班、值班日志填寫、交接班記錄印章管理用印申請、審批、登記從開發(fā)工作量的角度看系統(tǒng)管理是一等一的大頭因為用戶、角色、菜單、部門、日志這五張表是所有模塊公用的基礎(chǔ)設(shè)施。業(yè)務(wù)模塊反而簡單因為它們的模式高度相似新增一條申請記錄、推送到審批人、審批人處理后更新狀態(tài)。所以我在設(shè)計時會把“審批操作”抽成通用能力而不是每個模塊都寫一套。1.3 為什么是這四件套選型邏輯標(biāo)題里的技術(shù)組合是SpringBoot2 Vue3 MyBatis-Plus MySQL8.0很多人會問為什么不是SpringBoot3或者MyBatis-Plus換成JPA。以我的經(jīng)驗看高校信息中心或者多數(shù)企業(yè)內(nèi)部的老項目環(huán)境Java生產(chǎn)環(huán)境普遍還是JDK8SpringBoot3強制要求JDK17遷移成本一下子拉高。SpringBoot2.7在JDK8上運行非常成熟第三方組件兼容面也廣這是務(wù)實的選擇。MyBatis-Plus相比JPA在國內(nèi)團隊里確實更吃香。JPA的實體映射雖然省事但復(fù)雜查詢的調(diào)試成本很高一旦某條關(guān)聯(lián)查詢寫歪了排查問題要繞很多彎。MyBatis-Plus保留了SQL控制力同時又用BaseMapper把單表CRUD、分頁、條件構(gòu)造器的重復(fù)代碼省掉大半對業(yè)務(wù)邏輯以單表操作和簡單關(guān)聯(lián)為主的管理系統(tǒng)來說是恰到好處的平衡。Vue3搭配Vite開發(fā)時熱更新速度快組合式API在頁面邏輯復(fù)雜時組織代碼也更有條理。MySQL8.0的窗口函數(shù)對統(tǒng)計報表很有幫助JSON字段可以直接存審批意見或者擴展屬性后期擴展不用頻繁改表。這套選型背后是一個很樸素的邏輯不追新、不炫技選團隊成員都用過的、社區(qū)資料多的、碰到問題能搜到答案的組合。大型互聯(lián)網(wǎng)項目追求極致的性能和高可用但一個高校辦公室管理系統(tǒng)穩(wěn)定、可維護、開發(fā)效率高才是第一訴求。2. 后端不是堆代碼SpringBoot2、MyBatis-Plus與MySQL8.0的落地細(xì)節(jié)2.1 工程分層和分包思路拿到一個SpringBoot2 MyBatis-Plus的項目第一步先看包結(jié)構(gòu)。一個清晰的工程分層能省掉后面大量找代碼的時間。這套系統(tǒng)的后端我建議按這樣的結(jié)構(gòu)組織com.xxx.admin ├── controller # 接口層只做參數(shù)接收和結(jié)果封裝 ├── service # 業(yè)務(wù)邏輯層事務(wù)控制在這里 │ └── impl ├── mapper # MyBatis-Plus的Mapper接口 ├── entity # 數(shù)據(jù)庫實體類 ├── dto # 請求參數(shù)的封裝對象 ├── vo # 給前端返回的視圖對象 ├── config # 配置類攔截器、跨域、靜態(tài)資源映射都在這里 ├── common # 統(tǒng)一返回體、異常處理、常量定義 ├── utils # 工具類 └── security # JWT token、登錄校驗相關(guān)的類Controller層的核心職責(zé)是參數(shù)接收和結(jié)果封裝不要在里面寫任何業(yè)務(wù)邏輯。Service層負(fù)責(zé)業(yè)務(wù)規(guī)則的編排和事務(wù)管理事務(wù)注解一般加在Impl類的方法上。Mapper層只負(fù)責(zé)數(shù)據(jù)庫操作利用MyBatis-Plus的BaseMapper接口可以省掉大部分單表SQL的XML文件。還有一個值得養(yǎng)成的習(xí)慣Entity實體類不要直接返回給前端。數(shù)據(jù)庫字段的命名是下劃線風(fēng)格前端習(xí)慣是駝峰而且有些字段比如密碼、內(nèi)部狀態(tài)碼不適合直接暴露。在Service層把Entity轉(zhuǎn)成VO再返回邏輯清晰前端也省事。如果項目里字段少用MyBatis-Plus的BeanUtil.copyProperties或Hutool的BeanUtil一行搞定拷貝。2.2 數(shù)據(jù)庫設(shè)計從RBAC權(quán)限模型到核心業(yè)務(wù)表權(quán)限模型我強烈建議直接用標(biāo)準(zhǔn)的RBAC五表套件用戶表、角色表、菜單權(quán)限表、用戶角色關(guān)聯(lián)表、角色菜單關(guān)聯(lián)表。為什么不用三表直接把角色掛在用戶身上因為高校辦公室的行政結(jié)構(gòu)里一個人往往有多個身份比如某位老師既是辦公室副主任又是某個專項工作的負(fù)責(zé)人他的權(quán)限需要疊加組合。RBAC的用戶—角色—權(quán)限三層結(jié)構(gòu)配合菜單表的層級父子關(guān)系能靈活適配這種場景。用戶表的核心字段包括id、用戶名、密碼BCrypt加密存儲、姓名、手機號、郵箱、部門id、賬號狀態(tài)、創(chuàng)建時間、更新時間。角色表比較簡單就是角色名稱、角色編碼、備注、狀態(tài)。菜單表要設(shè)計成自關(guān)聯(lián)的樹形結(jié)構(gòu)菜單id、父級菜單id、菜單名稱、路由地址、組件路徑、權(quán)限標(biāo)識、排序、菜單類型目錄/菜單/按鈕。這里的權(quán)限標(biāo)識很關(guān)鍵比如meeting:audit代表會議審核權(quán)限后端接口通過這個標(biāo)識做按鈕級別的權(quán)限控制。業(yè)務(wù)表的核心是設(shè)計好“狀態(tài)字段”。公文管理表要有狀態(tài)字段區(qū)分草稿、待審核、已簽發(fā)、已歸檔會議申請要有待審核、已通過、已駁回、已取消用車申請要有待派車、已派車、已完成。狀態(tài)字段建議用小小的整型數(shù)字表示配合一個字典表維護狀態(tài)含義避免在代碼里到處寫魔法數(shù)。審批記錄單獨建一張表記錄業(yè)務(wù)類型、業(yè)務(wù)單id、審批人、審批結(jié)果、審批意見、審批時間這樣任何一個單據(jù)的流轉(zhuǎn)歷史都能完整追溯。MySQL8.0對這套系統(tǒng)的助力在于JSON字段可以保存審批鏈路的完整上下文和表單擴展字段窗口函數(shù)可以輕松實現(xiàn)“統(tǒng)計每個人月度的辦件量”這類需求CTE表達(dá)式對組織架構(gòu)樹查詢很方便。數(shù)據(jù)庫連接參數(shù)記得加上serverTimezoneAsia/Shanghai否則插入時間會比北京時間差8個小時這個坑幾乎每個項目都會遇到一次。2.3 MyBatis-Plus“用少省多”的五個操作MyBatis-Plus這套工具用得好的話項目里80%的基礎(chǔ)數(shù)據(jù)訪問不用寫SQL。第一個必開的是分頁插件在配置類里注冊MybatisPlusInterceptor加入PaginationInnerInterceptor(DbType.MYSQL)。分頁查詢統(tǒng)一用PageT對象Service返回的也是這個對象然后轉(zhuǎn)成帶total的VO返回給前端。分頁插件在MySQL8.0下會生成LIMIT ?,?語句性能可以接受。第二個是邏輯刪除。辦公室的業(yè)務(wù)數(shù)據(jù)比如公文、資產(chǎn)臺賬物理刪除會造成審計追溯困難所以用TableLogic加邏輯刪除字段更穩(wěn)妥。實體類里加一個deleted字段標(biāo)注TableLogicMyBatis-Plus的查詢會自動追加deleted0條件。需要注意的是邏輯刪除字段如果參與唯一索引會引發(fā)“刪過的數(shù)據(jù)再插入相同業(yè)務(wù)編號”的沖突解決辦法是唯一索引改成聯(lián)合索引把deleted也塞進去。第三個是自動填充。創(chuàng)建時間、更新時間、創(chuàng)建人、更新人四個字段每次插入修改都手工set一遍很煩。用MetaObjectHandler實現(xiàn)自動填充配合實體類的TableField(fill FieldFill.INSERT)和TableField(fill FieldFill.INSERT_UPDATE)插入更新時自動賦值省心又不會忘。第四個是條件構(gòu)造器LambdaQueryWrapper。用它寫條件查詢比拼SQL字符串安全編譯期能檢查字段名。比如查詢會議列表LambdaQueryWrapperMeeting wrapper new LambdaQueryWrapper(); wrapper.eq(Meeting::getRoomId, roomId) .ge(Meeting::getStartTime, startTime) .le(Meeting::getEndTime, endTime) .eq(Meeting::getStatus, 1);我自己實際用的過程中發(fā)現(xiàn)這一步比XML寫動態(tài)SQL要高效很多也減少了SQL注入的風(fēng)險。第五個是代碼生成器。MyBatis-Plus的代碼生成器配置好數(shù)據(jù)庫連接和作者信息之后entity、mapper、service、controller甚至前端頁面框架都能一鍵生成。用代碼生成器做初版骨架然后手工調(diào)整業(yè)務(wù)邏輯比純手寫快一倍不止。2.4 登錄鑒權(quán)JWT 攔截器 自定義權(quán)限注解登錄鑒權(quán)是校園辦公系統(tǒng)中開發(fā)同學(xué)容易輕視但實際改動最頻繁的部分。我推薦用無狀態(tài)的JWT方案因為系統(tǒng)不做集群部署的時候不需要額外搭一套會話共享的中間件。用戶登錄成功后后端生成一個token串里面包含用戶id、用戶名、角色編碼集合、過期時間前端把token存到localStorage里每次請求在Authorization頭里帶上。JWT的密鑰要放在配置文件里而不是寫在代碼中過期時間建議設(shè)2小時或者4小時。真正需要考慮的點是權(quán)限控制粒度。在Controller的接口方法上標(biāo)注自定義注解RequirePermission(meeting:audit)通過Spring攔截器在請求進入Controller之前解析token并校驗權(quán)限。我這里貼一下攔截處理的核心思路Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { if (!(handler instanceof HandlerMethod)) { return true; } HandlerMethod handlerMethod (HandlerMethod) handler; // 檢查是否標(biāo)注了 RequirePermission 注解 RequirePermission permission handlerMethod.getMethodAnnotation(RequirePermission.class); if (permission null) { return true; } // 校驗通過則放行不通過則拋出權(quán)限異常由統(tǒng)一異常處理器轉(zhuǎn)成403返回 return checkPermission(permission.value()); }統(tǒng)一返回體Result的設(shè)計也很關(guān)鍵。Controller的每個接口都返回Result類型里面包含code、message、data三個字段。成功code是200業(yè)務(wù)異常code可以自定義為500或者400系列。再配一個全局異常處理器用RestControllerAdvice捕獲參數(shù)校驗異常、業(yè)務(wù)異常、未知異常統(tǒng)一轉(zhuǎn)成Result對象返回。這樣前端只需要在響應(yīng)攔截器里統(tǒng)一處理code就行不用每個接口單獨寫try-catch。密碼存儲用BCrypt加密SpringSecurity的BCryptPasswordEncoder可以直接用或者引入Hutool的加密工具類。明文密碼存儲是底線問題數(shù)據(jù)庫泄露就等于所有賬號泄露。2.5 文件上傳與Excel導(dǎo)入導(dǎo)出辦公室老師最關(guān)心的功能行政辦公系統(tǒng)里文件上傳的場景太多了公文附件、會議紀(jì)要、報修圖片、用印掃描件。本地磁盤存儲是最簡單的方案在配置里指定上傳根目錄通過WebMvcConfigurer配置一個靜態(tài)資源映射路徑把/upload/**映射到物理目錄。前端拿到返回的文件路徑拼上請求前綴直接訪問。文件上傳大小要顯式配置spring: servlet: multipart: max-file-size: 20MB max-request-size: 100MBExcel導(dǎo)出是另一個高頻需求。每個月辦公室都要導(dǎo)出用車統(tǒng)計表、會議匯總表、請假統(tǒng)計表手動復(fù)制數(shù)據(jù)做Excel又慢又容易錯。我建議用EasyExcel而不是直接用POIEasyExcel的底層雖然也是POI但做了大量封裝內(nèi)存占用低很多尤其是大數(shù)據(jù)量導(dǎo)出時優(yōu)勢非常明顯。導(dǎo)出接口的思路是先查數(shù)據(jù)列表然后定義一個帶ExcelProperty注解的導(dǎo)出VO類一行代碼把列表寫入響應(yīng)流EasyExcel.write(response.getOutputStream(), VehicleExportVO.class) .sheet(用車統(tǒng)計) .doWrite(list);導(dǎo)入的功能優(yōu)先級沒那么高但格式校驗要做先做表頭校驗再逐行校驗數(shù)據(jù)格式最后批量插入數(shù)據(jù)庫。一次性導(dǎo)入幾千行的Excel中間有幾行格式不對直接把整個事務(wù)回滾會讓用戶很崩潰更穩(wěn)妥的做法是返回導(dǎo)入結(jié)果明細(xì)正確的入庫、錯誤的告訴用戶第幾行第幾列出錯。3. 前端工程化Vue3、Vite與接口對接的完整思路3.1 工程初始化與目錄規(guī)劃Vue3項目的初始化現(xiàn)在已經(jīng)很省事了用Vite創(chuàng)建項目骨架npm create vitelatest admin-web -- --template vue組件庫我用的是Element Plus和Vue3配套最自然像Table、Form、Dialog、Tree這些組件在管理系統(tǒng)中都是高頻使用的。狀態(tài)管理用Pinia比Vuex更輕量寫起來也更直觀。路由用Vue Router 4因為需要做權(quán)限控制路由表不能寫成全靜態(tài)的要配合后端返回的菜單權(quán)限動態(tài)生成。前端的目錄規(guī)劃大概是這樣的admin-web/src ├── api # 每個模塊的接口請求封裝 ├── assets # 靜態(tài)資源 ├── components # 通用組件分頁、上傳、富文本等 ├── layout # 主布局側(cè)邊欄、頭部、標(biāo)簽頁 ├── router # 路由配置與權(quán)限守衛(wèi) ├── stores # Pinia狀態(tài)管理 ├── utils # axios實例、token處理、工具方法 ├── views # 頁面組件 ├── App.vue └── main.js這里有一個實際項目里常見的爭論是先把所有頁面路由全部靜態(tài)配好還是完全靠后端返回菜單動態(tài)生成我的做法是折中基礎(chǔ)路由如登錄頁、404頁、主布局是靜態(tài)寫死的業(yè)務(wù)模塊的路由由后端菜單表數(shù)據(jù)動態(tài)生成。這樣既保證了一開始就能打開系統(tǒng)框架又實現(xiàn)了不同角色看到不同菜單列表的效果。3.2 Axios封裝和統(tǒng)一錯誤處理整個前端項目的接口請求都經(jīng)過同一個axios實例不要在頁面里直接調(diào)用axios.request到處寫配置。封裝的核心邏輯是請求發(fā)起時在攔截器里從localStorage拿token放到Authorization頭后端返回時先看HTTP狀態(tài)碼再看統(tǒng)一返回體里的code如果code表示未登錄直接清掉本地token跳轉(zhuǎn)登錄頁。我用一段代碼說明這個封裝的過程const service axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 15000 }); service.interceptors.request.use(config { const token localStorage.getItem(adminToken); if (token) { config.headers.Authorization Bearer ${token}; } return config; }); service.interceptors.response.use( response { const res response.data; if (res.code ! 200) { ElMessage.error(res.message || 請求失敗); return Promise.reject(new Error(res.message)); } return res; }, error { if (error.response error.response.status 401) { localStorage.removeItem(adminToken); window.location.href /login; } return Promise.reject(error); } ); export default service;這個封裝的好處是全項目只有這一處處理token和錯誤后續(xù)要加上token自動刷新、登錄失效提示、防重復(fù)提交也都集中處理即可。每個業(yè)務(wù)模塊的api再基于這個service實例封裝自己的請求函數(shù)比如會議模塊就是getMeetingList、submitMeetingApply、auditMeetingApply這組函數(shù)集。接口函數(shù)統(tǒng)一以模塊名拆文件頁面組件里只import本模塊的接口函數(shù)不直接依賴service這樣后期接口路徑變了只改api目錄下的文件就夠了。3.3 動態(tài)菜單權(quán)限讓不同角色看到不同的頁面動態(tài)菜單在前端實現(xiàn)時有幾個細(xì)節(jié)要注意。登錄成功時后端除了返回token還返回當(dāng)前用戶的用戶信息、角色編碼和菜單權(quán)限列表。菜單權(quán)限列表需要有層級父菜單是目錄子菜單是具體頁面按鈕是操作權(quán)限標(biāo)記。前端把菜單數(shù)據(jù)存入Pinia主布局里的側(cè)邊欄用菜單數(shù)據(jù)渲染成多級菜單結(jié)構(gòu)再根據(jù)路由配置將菜單路徑映射到對應(yīng)的Vue組件。權(quán)限守衛(wèi)那一層主要處理兩個問題未登錄訪問路由時跳轉(zhuǎn)到登錄頁已登錄但沒有權(quán)限訪問某路由時跳轉(zhuǎn)到403頁面。用戶在頁面上要隱藏?zé)o權(quán)限的按鈕時用自定義指令v-permission判斷權(quán)限標(biāo)記或者直接在模板里用條件渲染。比如會議審核按鈕只有在權(quán)限標(biāo)記包含meeting:audit時可見el-button v-ifhasPermission(meeting:audit) clickhandleAudit審核/el-button前端做權(quán)限控制更多是用戶體驗層面的優(yōu)化真正的安全防線仍然在后端的接口鑒權(quán)上。有人會抓包直接調(diào)接口所以前后端都要有權(quán)限校驗這個認(rèn)知需要從一開始就建立起來。3.4 典型頁面的實現(xiàn)套路列表、表單、詳情三件套管理系統(tǒng)的頁面看起來很多但仔細(xì)看全是“列表 表單彈窗 詳情抽屜”三件套的組合。列表頁的通用結(jié)構(gòu)是搜索區(qū)關(guān)鍵詞、狀態(tài)、日期范圍、操作區(qū)新增、導(dǎo)出、批量刪除、表格區(qū)、分頁區(qū)。搜索區(qū)的字段不要一次性擺很多個4個左右就好下拉框選項的字典數(shù)據(jù)一般從后端接口統(tǒng)一加載。新增和編輯共用一個表單彈窗組件通過傳入的id判斷是新增還是編輯。詳情頁用抽屜組件展示完整信息包括審批歷史時間線。日期范圍選擇器傳給后端的通常是一個起止時間數(shù)組后端接收時拆成開始時間和結(jié)束時間。會議管理列表的典型接口參數(shù)就是pageNum、pageSize、keyword、status、startTime、endTime對應(yīng)后端的Page對象接收。如果列表需要導(dǎo)出Excel前端按鈕直接調(diào)導(dǎo)出接口用window.open或者axios的blob方式下載文件。我在實際開發(fā)中踩過下載文件名亂碼的坑解決方案是在響應(yīng)頭里加Content-Disposition并把文件名URL編碼處理。4. 聯(lián)調(diào)部署與問題排查從本地到服務(wù)器4.1 本地開發(fā)環(huán)境的配置后端本地跑起來要保證幾個前置條件JDK8以上SpringBoot2.7最高支持到JDK20但JDK8是最穩(wěn)的、Maven 3.6、MySQL8.0、Redis如果項目用Redis緩存字典數(shù)據(jù)的話。我習(xí)慣用Navicat管理數(shù)據(jù)庫啟動項目前先執(zhí)行項目里的sql目錄下的初始化腳本把表結(jié)構(gòu)和默認(rèn)數(shù)據(jù)建好。默認(rèn)數(shù)據(jù)里要包含admin管理員賬號和一套初始角色、菜單權(quán)限不然一上來登錄界面都打不開。啟動項目后訪問http://localhost:8080如果看到統(tǒng)一返回體格式的錯誤提示說明項目跑起來了。后端接口全部掛在一個基礎(chǔ)設(shè)施前綴下比如/api/admin/user/login這種中間層的/api是前后端約定的統(tǒng)一前綴。4.2 MySQL8.0連接與初始化數(shù)據(jù)的幾個坑MySQL8.0和MySQL5.7的連接方式有幾個明顯差異。驅(qū)動類從com.mysql.jdbc.Driver換成了com.mysql.cj.jdbc.Driver連接串上要加useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue。這里allowPublicKeyRetrieval參數(shù)尤其關(guān)鍵因為MySQL8.0默認(rèn)使用caching_sha2_password認(rèn)證插件舊驅(qū)動連接時會報Public Key Retrieval錯誤。另外一個常見坑是MySQL8.0首次連接時耗時較長多半是DNS反向解析導(dǎo)致的在MySQL配置文件的[mysqld]段加一行skip-name-resolve可以緩解。初始化數(shù)據(jù)腳本建議寫成可以重復(fù)執(zhí)行的結(jié)構(gòu)化SQL。建表語句用CREATE TABLE IF NOT EXISTS菜單數(shù)據(jù)合并成INSERT IGNORE每次重新執(zhí)行不會造成數(shù)據(jù)重復(fù)。項目文檔里附帶的數(shù)據(jù)庫設(shè)計說明應(yīng)該把每張表的字段含義、枚舉值含義都寫清楚方便接手的人快速理解表結(jié)構(gòu)。4.3 前后端打包與Nginx部署方案后端打包非常直觀用Maven執(zhí)行mvn clean package -DskipTests生成可執(zhí)行的spring-boot jar然后在服務(wù)器上執(zhí)行nohup java -jar admin-system.jar --spring.profiles.activeprod system.log 21 。我建議線上環(huán)境用prod配置文件數(shù)據(jù)源、文件上傳路徑等用application-prod.yml單獨維護避免和本地開發(fā)配置混在一起。前端npm run build生成dist目錄直接把靜態(tài)文件放到Nginx配置的根目錄。真正要配置好的是反向代理因為前端請求的接口路徑會打到后端服務(wù)上。Nginx配置有一個很常用的寫法server { listen 80; server_name admin.example.com; location / { root /opt/admin-web/dist; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }注意try_files $uri $uri/ /index.html這一行前端用的是history模式路由如果不加這個配置刷新某個子路由頁面會直接404這是因為Nginx去按請求路徑找真實文件了找不到就報404。加上這一行之后找不到文件就退回index.html由前端路由接管頁面渲染。4.4 常見問題速查表我在實際維護這類項目時整理過一份高頻問題的清單對排查問題很有參考價值現(xiàn)象可能原因解決方案前端請求跨域報錯后端未配置跨域或者代理路徑不對開發(fā)環(huán)境用Vite的proxy配置生產(chǎn)環(huán)境用Nginx反向代理同源訪問插入數(shù)據(jù)庫的時間比當(dāng)前時間少8小時JDBC連接串缺少serverTimezone參數(shù)連接串加上serverTimezoneAsia/Shanghai登錄成功后刷新頁面就退出token沒有在下一次請求中帶上檢查axios請求攔截器是否在Authorization頭塞入token上傳文件超過大小被拒絕spring.servlet.multipart.max-file-size太小調(diào)整配置文件中的maxFileSize和maxRequestSize前端路由刷新404Nginx未配置try_files回退增加try_files $uri $uri/ /index.html;修改了Mapper XML不生效未配置MyBatis-Plus的mapper-locations配置mybatis-plus.mapper-locationsclasspath*:mapper/*.xml頁面數(shù)據(jù)有緩存但數(shù)據(jù)庫已變未清理Redis緩存或MyBatis緩存檢查緩存的key和失效策略導(dǎo)出Excel亂碼或打不開響應(yīng)頭Content-Type或文件名編碼問題設(shè)置Content-Type: application/vnd.ms-excel文件名做URL編碼還有一點很多人容易忽略線上環(huán)境一定要排查端口是否被占用經(jīng)常出現(xiàn)8080被其他服務(wù)占了導(dǎo)致后端啟動失敗的情況。用lsof -i :8080看一下端口占用或者直接換個端口啟動。寫在最后這類項目真正鍛煉人的地方我個人在實際帶項目中的體會是高校辦公系統(tǒng)這類項目雖然技術(shù)難度不高但對綜合能力的鍛煉很全面。它逼迫你把一個模糊的需求域梳理成清晰的數(shù)據(jù)模型把一條條審批流抽象成穩(wěn)定的狀態(tài)機把重復(fù)性極高的頁面和接口總結(jié)出通用的套路。SpringBoot2 Vue3 MyBatis-Plus MySQL8.0這套組合本身已經(jīng)非常成熟真正的挑戰(zhàn)在于怎么把業(yè)務(wù)邏輯嵌入技術(shù)框架讓辦公室的老師用得順手讓后來接手的人看得明白。最后再分享一個實用的小技巧這類系統(tǒng)上線之前一定要把數(shù)據(jù)庫的備份腳本和恢復(fù)演練做一遍。行政數(shù)據(jù)丟了就是事故沒有備份手段的系統(tǒng)再漂亮也談不上可靠。預(yù)先配置好定時備份任務(wù)再驗證一次從備份文件恢復(fù)完整數(shù)據(jù)庫的流程這件事花的力氣不大但關(guān)鍵時候能救命。