最近在整理一個(gè)用 SpringBoot Vue 做的學(xué)生證管理系統(tǒng)。這個(gè)名字聽(tīng)起來(lái)像是個(gè)普通的課程設(shè)計(jì)但真正動(dòng)手做一輪就會(huì)發(fā)現(xiàn)它把前后端分離開(kāi)發(fā)里最典型的問(wèn)題幾乎全踩了一遍多角色權(quán)限、審批流狀態(tài)管理、并發(fā)防重復(fù)、文件上傳、跨域處理、打包部署一樣都沒(méi)落下。項(xiàng)目的業(yè)務(wù)背景其實(shí)很常見(jiàn)——高校里學(xué)生證的辦理、掛失、補(bǔ)辦長(zhǎng)期依賴(lài)紙質(zhì)流程學(xué)生找輔導(dǎo)員簽字再跑學(xué)院蓋章最后到教務(wù)處排隊(duì)登記運(yùn)氣不好一個(gè)證要辦兩周。我做的這個(gè)系統(tǒng)把流程搬到了線(xiàn)上學(xué)生提交辦證或補(bǔ)辦申請(qǐng)輔導(dǎo)員線(xiàn)上審核管理員制證發(fā)放全程留痕進(jìn)度實(shí)時(shí)可查。這篇文章會(huì)按我從 0 到 1 的實(shí)際開(kāi)發(fā)順序來(lái)寫(xiě)需求拆解與技術(shù)選型、后端接口設(shè)計(jì)、前端頁(yè)面落地、高頻踩坑與排查方法、部署擴(kuò)展。不管你是拿它當(dāng)畢業(yè)設(shè)計(jì)還是想學(xué)前后端分離項(xiàng)目怎么從零起步里面都有可以直接抄作業(yè)的東西。1. 項(xiàng)目整體設(shè)計(jì)與需求拆解1.1 先說(shuō)需求不是“管理”兩個(gè)字那么簡(jiǎn)單很多初學(xué)者拿到這種題目第一反應(yīng)就是建一張學(xué)生表、一張學(xué)生證表然后開(kāi)始寫(xiě)增刪改查。真這么做做到一半就會(huì)卡住——因?yàn)椤皩W(xué)生證管理”背后至少疊著四個(gè)核心業(yè)務(wù)場(chǎng)景新生入學(xué)批量辦證幾十上百個(gè)學(xué)生同時(shí)需要辦證不能讓人逐個(gè)手工錄入要考慮批量導(dǎo)入、批量生成申請(qǐng)單。日常零星辦證轉(zhuǎn)校生、遺留學(xué)生、新生漏辦等情況走單個(gè)申請(qǐng)流程。掛失補(bǔ)辦學(xué)生證丟了先掛失作廢舊證再提交補(bǔ)辦申請(qǐng)這時(shí)可能要記錄繳費(fèi)狀態(tài)。畢業(yè)注銷(xiāo)畢業(yè)離校后批量停用保證系統(tǒng)里的證件狀態(tài)和實(shí)際一致。每個(gè)場(chǎng)景對(duì)應(yīng)的操作人不一樣。我把角色拆成了四類(lèi)學(xué)生提交申請(qǐng)、查看進(jìn)度、輔導(dǎo)員審核本班學(xué)生申請(qǐng)、學(xué)院管理員制證、注銷(xiāo)、系統(tǒng)管理員用戶(hù)管理、數(shù)據(jù)統(tǒng)計(jì)、參數(shù)配置。這里有個(gè)重要經(jīng)驗(yàn)需求階段一定要把“證件狀態(tài)”和“申請(qǐng)狀態(tài)”分開(kāi)建模。前者描述學(xué)生當(dāng)前持有的實(shí)體證是什么狀況比如正常、已掛失、已注銷(xiāo)后者描述某個(gè)申請(qǐng)流程走到了哪一步比如待審核、已通過(guò)、已駁回。我之前見(jiàn)過(guò)有人把這兩種狀態(tài)混在一張表的一個(gè)字段里結(jié)果申請(qǐng)被駁回后學(xué)生證狀態(tài)不知道怎么回滾日志都救不回來(lái)。1.2 技術(shù)選型SpringBoot Vue 不是唯一解但確實(shí)是最穩(wěn)的組合后端選 SpringBoot核心理由是它把 Spring 框架那一大堆配置自動(dòng)裝配掉了。你引入spring-boot-starter-web就能直接寫(xiě) Controller引入spring-boot-starter-data-redis就能直接注入 RedisTemplate不用自己拼 XML 配置文件。對(duì)這類(lèi)中小型業(yè)務(wù)系統(tǒng)來(lái)說(shuō)開(kāi)發(fā)效率是第一位的SpringBoot 默認(rèn)約定優(yōu)于配置的思路非常契合。官網(wǎng)用一句話(huà)解釋自動(dòng)裝配通過(guò)EnableAutoConfiguration啟動(dòng)時(shí)讀取META-INF/spring.factories里的配置類(lèi)按條件裝配 Bean。你可以不深入源碼但至少要理解這一點(diǎn)否則遇到“明明引入了依賴(lài)但 Bean 沒(méi)注入”的問(wèn)題會(huì)一臉懵。版本上我強(qiáng)烈建議用SpringBoot 2.7.x JDK 8/11不要一上來(lái)就追 3.x。3.0 開(kāi)始強(qiáng)制 JDK 17而且把javax.*遷移到了jakarta.*很多老版本的 MyBatis-Plus、Swagger、Activiti 直接不兼容網(wǎng)上搜“springboot版本太高”的求助帖一大片。對(duì)業(yè)務(wù)系統(tǒng)來(lái)說(shuō)穩(wěn)定的生態(tài)比追新更重要。前端選 Vue 的理由更直觀組件化開(kāi)發(fā)和響應(yīng)式數(shù)據(jù)綁定頁(yè)面復(fù)用率極高。同一個(gè)審核列表頁(yè)學(xué)生端、輔導(dǎo)員端、管理員端只是接口和字段略有不同組件稍作抽象就能三端共用。至于選 Vue 2 還是 Vue 3我的建議是直接學(xué) Vue 3 Element Plus。Vue 3 的組合式 API 寫(xiě)業(yè)務(wù)邏輯更集中而且 2024 年之后 Element Plus 的組件成熟度已經(jīng)很高了。其他配套選型模塊選型理由ORMMyBatis-Plus單表 CRUD 零 SQL復(fù)雜查詢(xún)走自定義 XML數(shù)據(jù)庫(kù)MySQL 8.0成本低、生態(tài)好InnoDB 支持事務(wù)緩存Redis驗(yàn)證碼存儲(chǔ)、Token 黑名單、并發(fā)鎖鑒權(quán)JWT 攔截器前后端分離下天然合適服務(wù)端無(wú)狀態(tài)UIElement Plus表格、表單、步驟條、時(shí)間線(xiàn)組件開(kāi)箱即用1.3 工程結(jié)構(gòu)規(guī)劃前后端分離的目錄怎么擺前后端分離不等于簡(jiǎn)單開(kāi)兩個(gè)文件夾。后端我采用常見(jiàn)的分層包結(jié)構(gòu)student-card-server ├── src/main/java/com/example/studentcard │ ├── controller # 接口層 │ ├── service # 業(yè)務(wù)邏輯層 │ ├── mapper # MyBatis-Plus 的 Mapper 接口 │ ├── entity # 數(shù)據(jù)庫(kù)實(shí)體 │ ├── dto # 請(qǐng)求響應(yīng)對(duì)象 │ ├── common # 全局異常、統(tǒng)一返回結(jié)果 │ └── config # 跨域、攔截器、Redis 配置前端用 Vue 官方腳手架創(chuàng)建后按業(yè)務(wù)拆目錄student-card-web ├── src │ ├── api # 接口請(qǐng)求封裝 │ ├── router # 路由配置 │ ├── store # Pinia 狀態(tài)管理 │ ├── views # 頁(yè)面級(jí)組件 │ │ ├── student # 學(xué)生端頁(yè)面 │ │ ├── counselor # 輔導(dǎo)員端頁(yè)面 │ │ └── admin # 管理員端頁(yè)面 │ ├── components # 公共組件 │ └── utils # 工具函數(shù)這個(gè)結(jié)構(gòu)的好處是職責(zé)單一后端按“層”劃分前端按“角色”劃分。小團(tuán)隊(duì)協(xié)作時(shí)每個(gè)人負(fù)責(zé)自己熟悉的目錄合并沖突的概率會(huì)低很多。2. 后端 SpringBoot 核心實(shí)現(xiàn)把“辦證”變成一組狀態(tài)流轉(zhuǎn)2.1 數(shù)據(jù)庫(kù)設(shè)計(jì)六張表把業(yè)務(wù)串起來(lái)數(shù)據(jù)庫(kù)設(shè)計(jì)是整個(gè)項(xiàng)目的地基我見(jiàn)過(guò)太多人一上來(lái)就建表結(jié)果字段重復(fù)、關(guān)聯(lián)混亂。按上面的業(yè)務(wù)拆解我最終用了六張核心表sys_user用戶(hù)表統(tǒng)一存學(xué)生、輔導(dǎo)員、管理員的賬號(hào)、密碼BCrypt 加密、角色標(biāo)識(shí)。student_info學(xué)生信息表存學(xué)號(hào)、姓名、學(xué)院、班級(jí)、入學(xué)年份與 sys_user 一對(duì)一。student_card學(xué)生證主表一條記錄對(duì)應(yīng)該學(xué)生當(dāng)前持有的實(shí)體證字段包括證件編號(hào)、發(fā)證日期、狀態(tài)。card_apply申請(qǐng)表辦證、補(bǔ)辦、注銷(xiāo)都走這張表通過(guò) apply_type 區(qū)分通過(guò) status 記錄流程進(jìn)度。card_loss_report掛失記錄表記錄掛失時(shí)間、掛失原因、原證件編號(hào)。operation_log操作日志表記錄誰(shuí)在什么時(shí)間對(duì)哪個(gè)申請(qǐng)做了什么操作便于審計(jì)。我給你看下最關(guān)鍵的 student_card 和 card_apply 的簡(jiǎn)化結(jié)構(gòu)CREATE TABLE student_card ( id BIGINT PRIMARY KEY AUTO_INCREMENT, student_id BIGINT NOT NULL COMMENT 關(guān)聯(lián) student_info.id, card_no VARCHAR(32) NOT NULL COMMENT 證件編號(hào), status TINYINT NOT NULL DEFAULT 1 COMMENT 1正常 2已掛失 3已注銷(xiāo) 4補(bǔ)辦中, issued_at DATETIME COMMENT 發(fā)證時(shí)間, expired_at DATETIME COMMENT 有效期截止, remark VARCHAR(255), UNIQUE KEY uk_student_active (student_id, status) );CREATE TABLE card_apply ( id BIGINT PRIMARY KEY AUTO_INCREMENT, apply_no VARCHAR(32) NOT NULL COMMENT 申請(qǐng)單號(hào), student_id BIGINT NOT NULL, apply_type TINYINT NOT NULL COMMENT 1辦證 2補(bǔ)辦 3注銷(xiāo), status TINYINT NOT NULL COMMENT 0待審核 1通過(guò) 2駁回 3已完成, reason VARCHAR(255), proof_url VARCHAR(255) COMMENT 繳費(fèi)憑證/證明材料路徑, created_at DATETIME, updated_at DATETIME );這里有兩個(gè)設(shè)計(jì)細(xì)節(jié)值得說(shuō)第一狀態(tài)字段我用TINYINT存儲(chǔ)后面加上狀態(tài)枚舉對(duì)應(yīng)。有些人喜歡直接存“正?！薄皰焓А边@種中文看著直觀但后期做條件查詢(xún)和統(tǒng)計(jì)時(shí)會(huì)非常痛苦索引效率也低。我的習(xí)慣是代碼里定義枚舉類(lèi)DataTransfer 層轉(zhuǎn)換成前端可讀的文本標(biāo)簽。第二student_card表加了一個(gè)業(yè)務(wù)上的唯一約束(student_id, status)的變體輔助防止并發(fā)補(bǔ)辦——這個(gè)問(wèn)題后面第 4 章詳細(xì)展開(kāi)這里先留個(gè)伏筆。2.2 登錄鑒權(quán)JWT 替代 Session 后怎么維持登錄狀態(tài)前后端分離項(xiàng)目不能依賴(lài) Servlet 容器自帶的 Session因?yàn)榍岸擞蛎秃蠖擞蛎赡芏疾灰粯覥ookie 跨域攜帶很麻煩。我用的方案是JWT Redis用戶(hù)登錄成功后端生成 JWT簽名密鑰放在配置文件中payload 里存 userId、username、role。Token 返回前端前端每次請(qǐng)求在請(qǐng)求頭帶Authorization: Bearer token。后端攔截器攔截所有/api/**請(qǐng)求解析 Token、校驗(yàn)簽名和過(guò)期時(shí)間把當(dāng)前用戶(hù)信息放到ThreadLocal中。不直接把用戶(hù)角色寫(xiě)死在 Token 里是因?yàn)橛脩?hù)角色被修改后需要立刻生效光靠 Token 里的舊信息判斷權(quán)限會(huì)出漏洞。我采取的折中方案Token 里存 userId每次請(qǐng)求放行前從 Redis 拉一下最新的角色雖然多一次內(nèi)存查詢(xún)但安全性高很多。核心攔截器的主要邏輯就這三步Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String token request.getHeader(Authorization); if (token null || !token.startsWith(Bearer )) { throw new AuthException(未登錄或登錄已過(guò)期); } Claims claims JwtUtil.parseToken(token.replace(Bearer , )); String redisKey login:token: claims.get(userId); if (!redisKey.equals(redisTemplate.opsForValue().get(redisKey))) { throw new AuthException(Token已失效請(qǐng)重新登錄); } UserContext.set(claims); return true; }注意攔截器里拋異常是不夠的還要配合全局異常處理器返回 JSON 格式的 401。否則前端拿到的是默認(rèn)的 HTML 錯(cuò)誤頁(yè)面攔截器里判斷響應(yīng)狀態(tài)就不好用了。2.3 核心業(yè)務(wù)接口辦證、掛失、補(bǔ)辦的狀態(tài)機(jī)實(shí)現(xiàn)這個(gè)系統(tǒng)的核心不是 CRUD而是狀態(tài)機(jī)流轉(zhuǎn)。業(yè)務(wù)規(guī)則是這樣的學(xué)生提交辦證申請(qǐng) → 輔導(dǎo)員審核通過(guò) → 管理員制證 → 標(biāo)記完成同時(shí)生成一條 student_card 記錄。學(xué)生掛失 → 原 student_card 狀態(tài)改為“已掛失”生成一條掛失記錄。學(xué)生補(bǔ)辦 → 先提交補(bǔ)辦申請(qǐng) → 審核通過(guò) → 原卡狀態(tài)改為“已注銷(xiāo)”再生成一張新卡。最容易寫(xiě)亂的地方是補(bǔ)辦。很多人寫(xiě)代碼時(shí)會(huì)直接把舊的 student_card 更新一下?tīng)顟B(tài)就結(jié)束了但補(bǔ)辦本質(zhì)上是“舊證作廢 新證生成”兩個(gè)動(dòng)作必須放在一個(gè)事務(wù)里Transactional(rollbackFor Exception.class) public void reissueCard(ReissueRequest request) { StudentCard oldCard cardMapper.selectByStudentId(request.getStudentId()); // 校驗(yàn)當(dāng)前證件狀態(tài)必須為“已掛失”或“正?！狈駝t不讓補(bǔ)辦 if (oldCard null || !CardStatus.LOST.equals(oldCard.getStatus())) { throw new BizException(當(dāng)前沒(méi)有可補(bǔ)辦的證件); } // 校驗(yàn)是否存在進(jìn)行中的補(bǔ)辦申請(qǐng) Integer pendingCount applyMapper.countPendingApply(request.getStudentId()); if (pendingCount 0) { throw new BizException(已有補(bǔ)辦申請(qǐng)?jiān)谔幚碇?; } // 舊證注銷(xiāo) oldCard.setStatus(CardStatus.INVALID); cardMapper.updateById(oldCard); // 生成新證 StudentCard newCard new StudentCard(); newCard.setStudentId(request.getStudentId()); newCard.setCardNo(generateCardNo(request.getStudentId())); newCard.setStatus(CardStatus.NORMAL); cardMapper.insert(newCard); // 更新申請(qǐng)狀態(tài)為已完成 applyMapper.updateStatus(request.getApplyId(), ApplyStatus.COMPLETED); }關(guān)鍵在于“校驗(yàn)已有進(jìn)行中的補(bǔ)辦申請(qǐng)”和“事務(wù)包裹兩個(gè)寫(xiě)操作”。沒(méi)有這兩步學(xué)生連點(diǎn)兩次“補(bǔ)辦”就會(huì)生成兩張有效證件這在現(xiàn)實(shí)中是絕對(duì)不允許的。2.4 文件上傳與全局異常處理前端拿到錯(cuò)誤提示很重要學(xué)生申請(qǐng)補(bǔ)辦往往要上傳繳費(fèi)憑證或丟失證明管理員端也可能需要上傳批量導(dǎo)入的 Excel 模板。我實(shí)現(xiàn)了兩個(gè)上傳接口單文件上傳和批量導(dǎo)入。文件存儲(chǔ)先放在本地服務(wù)器固定目錄路徑記錄到數(shù)據(jù)庫(kù)上線(xiàn)時(shí)再換成 MinIO后面擴(kuò)展章節(jié)會(huì)講。上傳這里最容易忽略的是大小限制和類(lèi)型校驗(yàn)。SpringBoot 默認(rèn)單文件最大 1MB實(shí)盤(pán)上傳超過(guò)直接被拒絕且返回的異常不好看。我在配置文件里顯式放開(kāi)并在業(yè)務(wù)層做類(lèi)型白名單校驗(yàn)spring: servlet: multipart: max-file-size: 10MB max-request-size: 20MB全局異常處理是后端體驗(yàn)的分水嶺。我用RestControllerAdvice統(tǒng)一處理業(yè)務(wù)異常和系統(tǒng)性異常保證接口出問(wèn)題時(shí)前端能拿到結(jié)構(gòu)一致的 JSON{ code: 500, message: 文件大小超出限制最大支持10MB, data: null }同時(shí)定義一個(gè)公共 Result 類(lèi)統(tǒng)一正常返回結(jié)構(gòu)。這樣前端 axios 攔截器只需要判斷 code 字段就可以統(tǒng)一彈出提示不需要每個(gè)接口單獨(dú)處理錯(cuò)誤分支。3. 前端 Vue 實(shí)現(xiàn)要點(diǎn)從腳手架到跑通完整流程3.1 工程搭建與依賴(lài)版本別在安裝這一步卡住我用 Vite 創(chuàng)建 Vue 3 工程npm create vuelatest student-card-web選擇包含 Vue Router 和 Pinia后續(xù)需要的依賴(lài)再手動(dòng)裝npm install element-plus axios piniaElement Plus 建議全量引入對(duì)內(nèi)部管理系統(tǒng)來(lái)說(shuō)按需引入省的那點(diǎn)包體積意義不大反而增加配置復(fù)雜度。同時(shí)安裝element-plus/icons-vue用于圖標(biāo)。vite.config.js里做兩件事配置路徑別名配置開(kāi)發(fā)環(huán)境代理。import { fileURLToPath, URL } from node:url export default defineConfig({ resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } }, server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })開(kāi)發(fā)環(huán)境下前端請(qǐng)求/api/user/login會(huì)被 Vite 代理到后端http://localhost:8080/api/user/login這樣瀏覽器端不存在跨域問(wèn)題。生產(chǎn)環(huán)境則交給 Nginx 處理這點(diǎn)第 5 章會(huì)展開(kāi)。3.2 路由守衛(wèi)與角色權(quán)限三種角色怎么控制頁(yè)面訪(fǎng)問(wèn)路由設(shè)計(jì)我采用“靜態(tài)基礎(chǔ)路由 動(dòng)態(tài)路由”組合。登錄頁(yè)、首頁(yè)屬于靜態(tài)路由所有角色可訪(fǎng)問(wèn)學(xué)生端、輔導(dǎo)員端、管理員端的頁(yè)面通過(guò)動(dòng)態(tài)路由按角色注冊(cè)。const asyncRoutes { student: [ { path: /student/apply, component: () import(/views/student/Apply.vue) } ], counselor: [ { path: /counselor/audit, component: () import(/views/counselor/Audit.vue) } ], admin: [ { path: /admin/card-list, component: () import(/views/admin/CardList.vue) } ] }配合全局前置守衛(wèi)每次路由跳轉(zhuǎn)前做三件事判斷有沒(méi)有 Token沒(méi)有 Token 一律跳登錄頁(yè)有 Token 就根據(jù)當(dāng)前用戶(hù)角色把對(duì)應(yīng)動(dòng)態(tài)路由加進(jìn)來(lái)注意用next({ ...to, replace: true })防止重復(fù)添加。調(diào)試這個(gè)問(wèn)題時(shí)Vue Devtools 是救命工具。它可以直觀看到當(dāng)前路由表、Vuex/Pinia 里存的用戶(hù)信息、組件 props 傳遞鏈。裝好插件后定位“為什么這個(gè)頁(yè)面沒(méi)權(quán)限訪(fǎng)問(wèn)”基本是分鐘級(jí)的事。3.3 axios 封裝請(qǐng)求攔截里統(tǒng)一處理 Token 和 401不封裝 axios 的后果是每個(gè)接口都要重復(fù)寫(xiě)請(qǐng)求頭、重復(fù)處理錯(cuò)誤代碼變得又臭又長(zhǎng)。我在src/utils/request.js里統(tǒng)一封裝import axios from axios import { ElMessage } from element-plus import router from /router const service axios.create({ baseURL: /api, timeout: 15000 }) service.interceptors.request.use(config { const token localStorage.getItem(token) 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 || 請(qǐng)求失敗) return Promise.reject(new Error(res.message)) } return res.data }, error { if (error.response error.response.status 401) { localStorage.clear() router.push(/login) } ElMessage.error(error.message || 網(wǎng)絡(luò)異常) return Promise.reject(error) } )這里有個(gè)容易被忽視的點(diǎn)后端正常返回業(yè)務(wù)錯(cuò)誤時(shí) HTTP 狀態(tài)碼也是 200只有 JSON 里的 code 非 200。所以我封裝的響應(yīng)攔截器中先判斷res.code再?zèng)Q定是否提示錯(cuò)誤。真正 HTTP 層面的 401、403 則走第二個(gè)回調(diào)。兩種錯(cuò)誤分開(kāi)處理前端交互才不會(huì)出現(xiàn)“明明提示了錯(cuò)誤還跳去別的頁(yè)面”這種詭異行為。3.4 核心頁(yè)面與交互細(xì)節(jié)狀態(tài)展示、步驟條、審核時(shí)間線(xiàn)前端頁(yè)面不需要炫技但要貼合業(yè)務(wù)流程。三個(gè)核心頁(yè)面是最花時(shí)間的學(xué)生端的辦證申請(qǐng)頁(yè)表單學(xué)號(hào)、姓名自動(dòng)帶出申請(qǐng)類(lèi)型選擇原因說(shuō)明材料上傳加上 Element Plus 步驟條展示當(dāng)前進(jìn)度。步驟條我分為四步提交申請(qǐng) → 輔導(dǎo)員審核 → 管理員制證 → 完成。每步對(duì)應(yīng) card_apply 的一個(gè)狀態(tài)。輔導(dǎo)員端的審核列表頁(yè)用el-table展示本班學(xué)生申請(qǐng)關(guān)鍵列有申請(qǐng)人、申請(qǐng)類(lèi)型、申請(qǐng)時(shí)間、狀態(tài)。狀態(tài)用el-tag渲染不同顏色待審核是警告色通過(guò)是成功色駁回是危險(xiǎn)色。這個(gè)細(xì)節(jié)看似小但對(duì)審核效率提升明顯掃一眼就能知道哪些是待處理的。管理員端的證卡管理頁(yè)搜索、篩選、分頁(yè)是標(biāo)配。分頁(yè)參數(shù)我用page和pageSize后端用 MP 的 Page 對(duì)象直接接收邏輯非常清爽。批量操作批量制證、批量注銷(xiāo)也是在這一頁(yè)實(shí)現(xiàn)前端把選中行的 id 數(shù)組傳后端后端循環(huán)處理并記錄操作日志。4. 開(kāi)發(fā)中高頻踩坑與排查實(shí)錄4.1 時(shí)間格式不一致MySQL 與 Jackson 的時(shí)區(qū)博弈第一個(gè)我問(wèn)遍所有人幾乎都會(huì)遇到的坑數(shù)據(jù)庫(kù)存的時(shí)間比實(shí)際少了 8 個(gè)小時(shí)或者前端顯示的日期總是“2024-01-01T00:00:00.00000:00”這種帶 T 的 UTC 格式。根源有兩個(gè)MySQL 連接串里的serverTimezone沒(méi)設(shè)對(duì)JDBC 驅(qū)動(dòng)和 MySQL 服務(wù)器之間時(shí)區(qū)認(rèn)知不一致。Jackson 序列化 LocalDateTime 時(shí)默認(rèn)輸出 ISO 格式。我最終的配置方案spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8數(shù)據(jù)庫(kù)連接串加上jdbc:mysql://localhost:3306/student_card?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf8同時(shí)前端拿到時(shí)間字符串后統(tǒng)一格式化不要直接 new Date 再拼接容易因?yàn)闉g覽器時(shí)區(qū)差異顯示錯(cuò)一天。4.2 刷新后 404 與登錄失效兩個(gè)典型場(chǎng)景排查前端我用的是 Vue Router 的 history 模式好處是 URL 好看壞處是直接訪(fǎng)問(wèn)/student/apply這個(gè)地址時(shí)服務(wù)器上根本沒(méi)有這個(gè)物理文件如果 Nginx 沒(méi)配置兜底會(huì)返回 404。解決方法是 Nginx 配置加上try_fileslocation / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; }另一個(gè)坑是刷新后登錄狀態(tài)丟失。刷新頁(yè)面不代表 Token 消失但路由守衛(wèi)在初始化時(shí)拿不到用戶(hù)信息就會(huì)誤判為未登錄而跳轉(zhuǎn)。我的做法是登錄成功后把用戶(hù)信息和 Token 都存到 localStoragePinia 里初始化狀態(tài)時(shí)先讀 localStorage保證刷新后能立即恢復(fù)登錄態(tài)。4.3 并發(fā)補(bǔ)辦怎么防重復(fù)從數(shù)據(jù)庫(kù)到接口的層層堵漏第 2 章提過(guò)補(bǔ)辦并發(fā)問(wèn)題這里展開(kāi)講排查過(guò)程。我當(dāng)時(shí)用 JMeter 并發(fā) 200 個(gè)線(xiàn)程同時(shí)提交同一個(gè)學(xué)生的補(bǔ)辦申請(qǐng)壓測(cè)后發(fā)現(xiàn)生成了多張有效證件。排查步驟如下第一步看代碼邏輯。發(fā)現(xiàn)少了“校驗(yàn)進(jìn)行中申請(qǐng)”這一步補(bǔ)上后業(yè)務(wù)層能擋住一部分但并發(fā)窗口仍然存在——兩個(gè)請(qǐng)求同時(shí)通過(guò)校驗(yàn)同時(shí)進(jìn)入事務(wù)。第二步加數(shù)據(jù)庫(kù)約束。在 card_apply 表上對(duì)student_id status加唯一索引保證同一時(shí)間只能有一條進(jìn)行中的申請(qǐng)。但 MyBatis-Plus 插入沖突時(shí)拋的是 DuplicateKeyException需要捕獲轉(zhuǎn)換成友好提示。第三步加 Redis 分布式鎖。以lock:reissue:{studentId}為 keysetnx 加過(guò)期時(shí)間獲取鎖失敗直接提示“操作太頻繁”。三個(gè)機(jī)制疊加之后再壓測(cè)就穩(wěn)定了。這個(gè)排查過(guò)程告訴我防并發(fā)從來(lái)不是靠單層解決業(yè)務(wù)判斷擋正常操作索引兜底極端情況鎖再壓住并發(fā)窗口。4.4 SpringBoot 版本升級(jí)兼容性新版本引發(fā)的連鎖踩坑有個(gè)朋友把項(xiàng)目從 2.x 升級(jí)到 SpringBoot 3.2結(jié)果啟動(dòng)直接報(bào)錯(cuò)原因就是 3.x 把javax.sql遷到了jakarta.sql很多中間件和工具類(lèi)直接找不到類(lèi)。當(dāng)時(shí)項(xiàng)目里還用了 springfox-swagger 2.x、舊版 MyBatis-Plus全部不兼容。如果你確實(shí)想用 SpringBoot 3.x建議做三件事確認(rèn) JDK 17把 swagger 換成 springdoc-openapiMyBatis-Plus 升到 3.5.3 以上并使用mybatis-plus-spring-boot3-starter。但我個(gè)人的建議是業(yè)務(wù)項(xiàng)目別當(dāng)小白鼠穩(wěn)定優(yōu)先。另外構(gòu)建工具我用 Maven 而不用 Gradle原因是團(tuán)隊(duì)里大多數(shù)人熟悉 Maven依賴(lài)沖突排查手段清晰。如果你只用 IDEA 創(chuàng)建項(xiàng)目直接選 Spring Initializr 可以省去不少配置麻煩。5. 部署上線(xiàn)與后續(xù)擴(kuò)展5.1 前后端分離部署從本地到服務(wù)器的一鍵思路開(kāi)發(fā)完成后的部署流程我建議按下面這樣走后端執(zhí)行mvn clean package得到student-card-server.jar。服務(wù)器裝 JDK 11、MySQL、Redis、Nginx。上傳 jar 后執(zhí)行nohup java -jar student-card-server.jar --spring.profiles.activeprod app.log 21 。前端執(zhí)行npm run build把生成的dist目錄傳到 Nginx 的 HTML 根目錄。Nginx 的完整配置里兩個(gè)核心段缺一不可靜態(tài)資源兜底和 API 反向代理。server { listen 80; server_name your-domain.com; 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; } location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } }第一次部署后務(wù)必檢查三件事后端日志有沒(méi)有數(shù)據(jù)庫(kù)連接池報(bào)錯(cuò)前端能不能正常登錄并調(diào)通接口如果服務(wù)器開(kāi)放了 HTTPS把 Nginx 的 80 端口配置改成 443 并用 certbot 自動(dòng)申請(qǐng)證書(shū)否則流量都是明文。5.2 還可以往哪些方向擴(kuò)展這個(gè)系統(tǒng)的骨架具備很強(qiáng)的通用性稍作改造就能復(fù)用到其他場(chǎng)景文件存儲(chǔ)升級(jí) MinIO現(xiàn)在文件存在本地磁盤(pán)將來(lái)學(xué)生人數(shù)多了可以把上傳接口改成客戶(hù)端直傳 MinIO 或服務(wù)端簽名上傳靜態(tài)資源走獨(dú)立域名減輕應(yīng)用服務(wù)器壓力。引入工作流引擎現(xiàn)在審批流是單級(jí)審核如果學(xué)院多層級(jí)審批可以整合 Flowable 或 Activiti把申請(qǐng)流程配置化。消息通知審核通過(guò)后自動(dòng)通知學(xué)生可以接入企業(yè)微信或郵件服務(wù)也可以引入 ActiveMQ 做異步解耦避免接口響應(yīng)時(shí)間過(guò)長(zhǎng)。電子學(xué)生證小程序或 H5 展示二維碼閘機(jī)掃碼驗(yàn)證這個(gè)就是另一個(gè)完整項(xiàng)目了但底層的證卡狀態(tài)管理可以直接復(fù)用。像這類(lèi)系統(tǒng)最大的復(fù)用價(jià)值是“證卡狀態(tài)機(jī)”和“角色權(quán)限模型”。以后無(wú)論做一卡通管理、圖書(shū)證系統(tǒng)還是會(huì)員卡系統(tǒng)核心邏輯都大同小異。我在實(shí)際開(kāi)發(fā)中最大的體會(huì)是別小看這種“管理系統(tǒng)”它逼著你在數(shù)據(jù)表設(shè)計(jì)和狀態(tài)流轉(zhuǎn)上多花心思。前期把需求梳理清楚、把狀態(tài)機(jī)畫(huà)明白后面寫(xiě)代碼就是體力活反過(guò)來(lái)如果急著上手寫(xiě)接口后面大概率要返工。最后分享一個(gè)小技巧所有接口在寫(xiě)完后都手動(dòng)模擬一遍“正常流程 異常流程 并發(fā)流程”跑測(cè)試尤其要測(cè)異常流程——駁回、撤銷(xiāo)、過(guò)期、重復(fù)提交——這些才是生產(chǎn)環(huán)境真正會(huì)出問(wèn)題的地方。框架怎么選、頁(yè)面怎么寫(xiě)大家都能學(xué)會(huì)拉開(kāi)差距的往往就是這些細(xì)節(jié)。