：從JWT鑒權(quán)到部署實(shí)戰(zhàn))
做競賽管理系統(tǒng)這個(gè)選題我一直覺得是前后端分離項(xiàng)目里性價(jià)比最高的一類。業(yè)務(wù)模型清晰、角色邊界明確、數(shù)據(jù)流轉(zhuǎn)完整從用戶到權(quán)限再到文件上傳、狀態(tài)流轉(zhuǎn)、統(tǒng)計(jì)報(bào)表全都能覆蓋到。尤其對于正在做畢業(yè)設(shè)計(jì)或者想系統(tǒng)練手全棧的同學(xué)來說一套基于SpringBoot Vue的大學(xué)生競賽管理系統(tǒng)幾乎把企業(yè)級開發(fā)里最常見的那些坑都踩了一遍JWT鑒權(quán)怎么做、文件上傳怎么接、跨域怎么配、前端打包怎么塞進(jìn)后端、路由守衛(wèi)怎么攔截。這篇文章就把我這套系統(tǒng)的完整思路、核心代碼、表設(shè)計(jì)和部署經(jīng)驗(yàn)一次性講清楚照著做你也能從零搭出一套能跑、能答辯、能演示的完整項(xiàng)目。1. 整體設(shè)計(jì)與技術(shù)選型先把業(yè)務(wù)想明白再動手1.1 角色劃分與核心業(yè)務(wù)流程競賽管理系統(tǒng)這個(gè)業(yè)務(wù)本質(zhì)上就是“賽事全流程管理”。從管理員發(fā)布競賽到學(xué)生報(bào)名、上傳作品再到評委打分、成績公示、證書下載一條線走完。傳統(tǒng)的紙筆流程最大的問題是信息不透明學(xué)生不知道報(bào)名是否成功、評委之間分?jǐn)?shù)互相看不到、管理員統(tǒng)計(jì)成績?nèi)縀xcel。系統(tǒng)把這些環(huán)節(jié)數(shù)字化之后每步操作都有狀態(tài)記錄和時(shí)間戳權(quán)責(zé)清晰審計(jì)也方便。我在設(shè)計(jì)角色時(shí)劃分了三種學(xué)生瀏覽競賽列表、查看詳情、報(bào)名參賽、上傳作品、查看自己的成績和證書。評委/教師對分配到名下的作品打分、填寫評語、查看已評和待評列表。管理員用戶管理、競賽信息發(fā)布與狀態(tài)控制、報(bào)名審核、評委分配、成績統(tǒng)計(jì)與導(dǎo)出。這三種角色的權(quán)限邊界要非常明確。學(xué)生不能看到評委打分頁評委不能修改競賽信息管理員不參與打分。權(quán)限控制如果做不好后續(xù)所有功能都會出現(xiàn)越權(quán)訪問的漏洞。1.2 技術(shù)棧選型的三個(gè)理由這套系統(tǒng)我選擇的是SpringBoot 2.7.x Vue 3 Element Plus MySQL 8 MyBatis Plus。選這套組合不是跟風(fēng)而是有幾個(gè)實(shí)際考量。第一個(gè)考量是SpringBoot版本。2.7.x是目前兼容性最穩(wěn)的版本JDK 8和JDK 11都能跑各種第三方starter基本都能找到對應(yīng)版本。SpringBoot 3.0之后強(qiáng)制要求JDK 17很多學(xué)生本機(jī)的JDK版本還是8一上來就報(bào)各種版本兼容錯(cuò)誤光環(huán)境問題就能卡一整天。當(dāng)然如果你本機(jī)已經(jīng)是JDK 17直接用3.x也沒問題只是要注意javax命名空間改成jakartaMyBatis Plus和相關(guān)依賴也要用適配版本。第二個(gè)考量是前端框架版本。Vue 3 Vite Element Plus是當(dāng)前的主流組合Vite的啟動速度比Webpack快一個(gè)量級開發(fā)體驗(yàn)好很多。組件庫用Element Plus界面風(fēng)格統(tǒng)一表格、表單、彈窗、上傳組件都是現(xiàn)成的不用從零寫UI。如果你更熟悉Vue 2 Element UI思路完全一樣只是API細(xì)節(jié)略有差異不影響整體架構(gòu)。第三個(gè)考量是持久層框架。MyBatis Plus在單表CRUD場景下幾乎不用寫SQL自帶分頁插件和條件構(gòu)造器開發(fā)效率非常高。競賽管理系統(tǒng)里大部分查詢都是單表?xiàng)l件查詢比如“查詢某個(gè)競賽下所有報(bào)名記錄”“查詢當(dāng)前用戶的所有作品”用LambdaQueryWrapper幾行代碼就搞定了沒必要手寫復(fù)雜的XML映射。1.3 數(shù)據(jù)庫表設(shè)計(jì)的六個(gè)核心表數(shù)據(jù)庫是整個(gè)系統(tǒng)的地基我踩過最深的坑就是表設(shè)計(jì)太隨意改表結(jié)構(gòu)比改代碼痛苦十倍。競賽系統(tǒng)核心表我設(shè)計(jì)如下前后端聯(lián)調(diào)階段的“接口字段和數(shù)據(jù)庫字段對不上”問題源頭就在這里。表名核心字段說明sys_userid, username, password, nickname, role, avatar, college, major, student_no, phone, email, status, create_time用戶表role區(qū)分admin/teacher/studentcontestid, title, description, category, cover, max_team_members, registration_start_time, registration_end_time, contest_start_time, contest_end_time, status, create_time競賽表status字段控制生命周期contest_registrationid, contest_id, user_id, team_name, team_members, contact_phone, status, create_time報(bào)名表status分為待審核/已通過/已拒絕work_submissionid, contest_id, user_id, registration_id, title, description, file_url, cover_url, submit_time, status作品表一個(gè)報(bào)名對應(yīng)一個(gè)作品contest_scoreid, work_id, reviewer_id, score, comment, create_time評分表同一作品多個(gè)評委打分后取平均noticeid, title, content, type, owner_id, publish_time新聞公告表前臺輪播和消息通知用重點(diǎn)說一下競賽的status字段。我用了數(shù)字字典0表示草稿、1表示報(bào)名中、2表示評審中、3表示已結(jié)束。前端根據(jù)這個(gè)值控制按鈕的可用狀態(tài)后端在報(bào)名接口也校驗(yàn)當(dāng)前時(shí)間是否在報(bào)名窗口內(nèi)雙重保險(xiǎn)避免有人繞過前端直接調(diào)接口。另外一個(gè)關(guān)鍵設(shè)計(jì)是work_submission里的registration_id它把報(bào)名表和作品表關(guān)聯(lián)起來。這樣查詢“某學(xué)生報(bào)名了哪些競賽”和“某競賽收了哪些作品”都非常方便。前期表設(shè)計(jì)時(shí)把外鍵關(guān)系理清后面寫查詢就是順?biāo)浦鄣氖隆?. 后端核心模塊從登錄鑒權(quán)到文件上傳的完整閉環(huán)2.1 統(tǒng)一響應(yīng)體與全局異常處理前后端分離項(xiàng)目接口返回格式必須統(tǒng)一。我封裝了一個(gè)Result類所有接口返回{code, message, data}的結(jié)構(gòu)。code為200表示成功401表示未登錄403表示無權(quán)限500表示業(yè)務(wù)異常。這個(gè)封裝看起來簡單但能讓前端攔截器的處理邏輯變得非常整潔。Data public class ResultT { private Integer code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMessage(操作成功); result.setData(data); return result; } public static T ResultT error(Integer code, String message) { ResultT result new Result(); result.setCode(code); result.setMessage(message); return result; } }有了統(tǒng)一響應(yīng)體還需要一個(gè)全局異常處理器把業(yè)務(wù)異常和系統(tǒng)異常分開處理。我是用RestControllerAdvice注解實(shí)現(xiàn)的捕獲自定義的BusinessException拋出的異常時(shí)返回對應(yīng)的錯(cuò)誤碼和提示語捕獲Exception時(shí)統(tǒng)一返回500和“系統(tǒng)異常請稍后重試”避免把堆棧信息直接暴露給前端。這里有個(gè)開發(fā)習(xí)慣值得養(yǎng)成不要把try-catch寫在每個(gè)Controller里而是讓業(yè)務(wù)層拋出異常由全局處理器統(tǒng)一處理。代碼會干凈很多也不容易漏掉異常分支。2.2 Spring Security JWT登錄鑒權(quán)實(shí)戰(zhàn)登錄鑒權(quán)是這類系統(tǒng)的重中之重。我用的是JWT無狀態(tài)方案用戶登錄成功后后端簽發(fā)一個(gè)包含用戶ID、用戶名、角色信息的Token前端請求時(shí)放在請求頭的Authorization字段里后端攔截器解析Token并校驗(yàn)身份。這樣做的好處是服務(wù)端不需要存儲Session水平擴(kuò)展時(shí)不需要做Session共享對部署和將來合入網(wǎng)關(guān)都很友好。JWT工具類核心代碼如下注意設(shè)置過期時(shí)間和密鑰Component public class JwtUtils { private static final String SECRET your-secret-key-your-secret-key; private static final long EXPIRATION 1000 * 60 * 60 * 24 * 7L; public String generateToken(Integer userId, String username, String role) { return Jwts.builder() .setSubject(username) .claim(userId, userId) .claim(role, role) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() EXPIRATION)) .signWith(SignatureAlgorithm.HS256, SECRET) .compact(); } public Claims parseToken(String token) { return Jwts.parser() .setSigningKey(SECRET) .parseClaimsJws(token) .getBody(); } }Security配置類是這個(gè)模塊中最容易出錯(cuò)的地方。需要放行登錄接口、驗(yàn)證碼接口和靜態(tài)資源路徑其余接口全部走JWT過濾器。放行哪些路徑看似簡單但如果你把接口路徑寫錯(cuò)或者放行多了后面調(diào)接口時(shí)就會出現(xiàn)“明明登錄成功了卻一直401”的詭異問題。Configuration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Override protected void configure(HttpSecurity http) throws Exception { http.csrf().disable() .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() .authorizeRequests() .antMatchers(/api/auth/login, /api/upload/**, /files/**).permitAll() .antMatchers(/api/admin/**).hasRole(admin) .antMatchers(/api/teacher/**).hasRole(teacher) .anyRequest().authenticated() .and() .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class); } }角色和路徑的匹配規(guī)則要提前規(guī)劃。我在實(shí)際開發(fā)中把接口路徑做了約定/api/student/**學(xué)生接口、/api/teacher/**評委接口、/api/admin/**管理接口、/api/common/**公共接口。前端的API請求也遵循這個(gè)約定后端的鑒權(quán)配置就非常清晰。2.3 競賽報(bào)名與作品提交狀態(tài)機(jī)與并發(fā)控制報(bào)名和作品提交是競賽系統(tǒng)的核心業(yè)務(wù)操作這兩個(gè)接口在并發(fā)場景下特別容易出現(xiàn)臟數(shù)據(jù)。比如同一個(gè)學(xué)生重復(fù)提交報(bào)名或者報(bào)名截止時(shí)間剛過但請求還在路上。我處理的思路是雙保險(xiǎn)數(shù)據(jù)庫層面加唯一索引代碼層面做業(yè)務(wù)校驗(yàn)。報(bào)名表上加UNIQUE KEY uk_contest_user (contest_id, user_id)這樣即使兩個(gè)并發(fā)請求同時(shí)通過代碼校驗(yàn)數(shù)據(jù)庫也會攔截重復(fù)插入返回DuplicateKeyException。代碼里再判斷當(dāng)前時(shí)間是否在報(bào)名窗口期、競賽狀態(tài)是否為“報(bào)名中”雙重保障確保數(shù)據(jù)正確。作品提交的邏輯稍微復(fù)雜一點(diǎn)。學(xué)生在報(bào)名審核通過后才能上傳作品上傳后可以修改截止時(shí)間后鎖定。我設(shè)計(jì)了works表的status字段0表示未提交、1表示已提交待評審、2表示已退回修改。評委退回作品后學(xué)生重新上傳狀態(tài)回到1進(jìn)入評審隊(duì)列。這個(gè)狀態(tài)機(jī)設(shè)計(jì)是整個(gè)系統(tǒng)業(yè)務(wù)邏輯里最容易寫亂的地方。我強(qiáng)烈建議先在紙上畫出狀態(tài)流轉(zhuǎn)圖待審核-已通過-已提交-已退回-已提交每個(gè)狀態(tài)觸發(fā)什么事件、誰觸發(fā)、產(chǎn)生什么結(jié)果搞清楚再寫代碼。不然代碼越寫越亂改一個(gè)狀態(tài)還要連帶著改三四處邏輯。2.4 文件上傳與靜態(tài)資源映射競賽作品通常是PDF、壓縮包或者圖片文件上傳功能必不可少。SpringBoot的文件上傳配置很簡潔spring: servlet: multipart: max-file-size: 100MB max-request-size: 200MB文件上傳的Controller稍微有點(diǎn)講究需要做文件類型白名單校驗(yàn)、文件名重命名防路徑穿越、按日期歸檔存儲。我的實(shí)現(xiàn)邏輯是接收MultipartFile校驗(yàn)后綴名是否在允許列表里用UUID重新生成文件名存儲到uploads/yyyy/MM/dd/目錄下返回?cái)?shù)據(jù)庫里的相對路徑。相對路徑加上域名前綴就是完整的訪問URL。前端上傳PDF后需要預(yù)覽這里有一個(gè)很實(shí)用的技巧如果瀏覽器可以直接打開PDF用iframe嵌; 但要注意Element Plus的upload組件默認(rèn)會走form-data提交后端返回的JSON需要放在response里而不是自定義header里否則回顯會有兼容問題。這個(gè)我后面在前端章節(jié)再展開講。3. 前端Vue實(shí)踐從腳手架到核心交互3.1 項(xiàng)目結(jié)構(gòu)與路由設(shè)計(jì)前端項(xiàng)目我用Vite腳手架創(chuàng)建推薦的目錄結(jié)構(gòu)如下src/ api/ # 接口請求封裝 auth.js contest.js work.js assets/ # 靜態(tài)資源 components/ # 公共組件 CommonTable.vue FileUpload.vue router/ # 路由配置 index.js store/ # Pinia狀態(tài)管理 user.js views/ admin/ # 管理端頁面 student/ # 學(xué)生端頁面 teacher/ # 評委端頁面 Login.vue Home.vue路由設(shè)計(jì)上我用了動態(tài)路由和路由守衛(wèi)結(jié)合的方式。靜態(tài)路由只有登錄頁和首頁其他頁面根據(jù)用戶角色動態(tài)生成。這樣做的好處是角色菜單天然分離學(xué)生登錄后看不到評委頁面同時(shí)也減少了首屏加載的路由數(shù)量。路由守衛(wèi)是必須寫的不然用戶手動改URL就能跳到?jīng)]權(quán)限的頁面router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.path /login) { next() } else if (!token) { next(/login) } else { const userStore useUserStore() if (!userStore.userInfo) { userStore.fetchUserInfo().then(() { next() }).catch(() { next(/login) }) } else { next() } } })3.2 Axios請求封裝與Token刷新邏輯Axios封裝這項(xiàng)工作看似簡單但卻是前后端聯(lián)調(diào)時(shí)體驗(yàn)好不好的決定性因素。我的封裝思路是創(chuàng)建axios實(shí)例設(shè)置baseURL為/api請求攔截器里從localStorage取Token并放入Authorization頭響應(yīng)攔截器里統(tǒng)一處理HTTP狀態(tài)碼和業(yè)務(wù)狀態(tài)碼。const service axios.create({ baseURL: /api, timeout: 10000 }) 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) { return res } if (res.code 401) { localStorage.removeItem(token) window.location.href /login } return Promise.reject(new Error(res.message)) }, error { return Promise.reject(error) } )特別是401的處理很多新手容易漏掉。Token過期后如果只是彈個(gè)“請重新登錄”的提示用戶就卡在頁面上不知道該怎么辦。跳轉(zhuǎn)到登錄頁并清空本地存儲是最直觀的處理方式。3.3 核心頁面交互競賽列表、詳情與倒計(jì)時(shí)競賽列表頁是學(xué)生接觸系統(tǒng)的第一屏交互友好度直接影響使用體驗(yàn)。我用卡片形式展示競賽信息每個(gè)卡片包含封面圖、標(biāo)題、競賽類別、報(bào)名截止時(shí)間、當(dāng)前狀態(tài)標(biāo)簽。點(diǎn)擊卡片跳轉(zhuǎn)到詳情頁路由傳遞競賽ID參數(shù)。這里最考驗(yàn)細(xì)節(jié)的是競賽狀態(tài)與按鈕的聯(lián)動。報(bào)名按鈕要依據(jù)后端返回的status字段和當(dāng)前時(shí)間動態(tài)計(jì)算status為1且當(dāng)前時(shí)間在報(bào)名窗口內(nèi)顯示“立即報(bào)名”不在窗口內(nèi)顯示“報(bào)名未開始”或“已截止”status為2顯示“評審中”status為3顯示“已結(jié)束”。這些狀態(tài)計(jì)算我放在前端寫了一個(gè)工具函數(shù)export function getContestStatus(contest) { const now Date.now() const start new Date(contest.registrationStartTime).getTime() const end new Date(contest.registrationEndTime).getTime() if (contest.status 0) return { text: 未發(fā)布, type: info } if (contest.status 1 now start) return { text: 報(bào)名未開始, type: warning } if (contest.status 1 now start now end) return { text: 報(bào)名中, type: success } if (contest.status 1 now end) return { text: 報(bào)名已截止, type: danger } if (contest.status 2) return { text: 評審中, type: warning } if (contest.status 3) return { text: 已結(jié)束, type: info } }詳情頁我同時(shí)展示了競賽介紹、時(shí)間線、賽事流程說明。倒計(jì)時(shí)組件用setInterval實(shí)現(xiàn)每秒鐘更新剩余時(shí)間頁面銷毀時(shí)記得清除定時(shí)器。這個(gè)組件雖小但踩過的坑是路由切換后定時(shí)器沒清掉導(dǎo)致組件銷毀后還在執(zhí)行setState控制臺報(bào)一堆警告。3.4 文件上傳組件與PDF預(yù)覽系統(tǒng)最核心的上傳場景是作品提交以PDF為主。Element Plus的el-upload組件提供了拖拽上傳和進(jìn)度顯示但默認(rèn)行為是選擇文件后立即上傳。我配置了:auto-uploadfalse用戶選擇文件后先展示在文件列表里點(diǎn)擊“確認(rèn)提交”才真正發(fā)起上傳避免誤選后無法撤銷。上傳成功后預(yù)覽PDF我用了兩種方案兼容不同場景。如果瀏覽器原生支持PDF預(yù)覽直接新窗口打開文件URL就行。為了更好的展示體驗(yàn)我在前端頁面內(nèi)嵌了iframe將PDF文件URL作為src實(shí)測Chrome和Edge都能正常顯示。如果需要更精細(xì)的控制比如指定頁碼、縮放可以使用pdf.js或者vue-pdf組件不過對于競賽管理系統(tǒng)的場景iframe方案已經(jīng)足夠還省了一個(gè)大依賴。用戶的頭像預(yù)覽也是一樣的邏輯文件上傳后返回相對路徑前端拼接成完整URL用于img標(biāo)簽的src。這里注意一個(gè)問題開發(fā)環(huán)境下后端接口在8080端口前端在5173端口圖片URL如果是相對路徑瀏覽器會去5173端口找就404了。解決辦法是用Vite的代理配置把/api和/files都代理到后端地址。4. 環(huán)境搭建、聯(lián)調(diào)與部署實(shí)戰(zhàn)4.1 本地環(huán)境準(zhǔn)備與依賴配置開始寫代碼之前先把環(huán)境搞定不然后面踩的坑都是環(huán)境的鍋。我建議本地環(huán)境如下JDK 8 或 11對應(yīng)SpringBoot 2.7.xMaven 3.6配置阿里云鏡像源否則依賴下載慢到懷疑人生Node 16Vite 4要求Node 14.18我推薦Node 16長期支持版MySQL 8.0字符集全部設(shè)置為utf8mb4否則中文亂碼Maven的pom.xml核心依賴清單如下注意MyBatis Plus和SpringBoot的版本兼容關(guān)系parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.7/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt/artifactId version0.9.1/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies4.2 前后端聯(lián)調(diào)跨域問題與接口規(guī)范前后端分離項(xiàng)目跨域問題幾乎必然遇到。開發(fā)環(huán)境最省事的方案是Vite代理在vite.config.js里配置export default defineConfig({ server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true }, /files: { target: http://localhost:8080, changeOrigin: true } } } })配置了代理之后前端代碼里所有請求都寫相對路徑/api/xxx由Vite轉(zhuǎn)發(fā)到8080端口。這種方式比后端配置CORS要優(yōu)雅得多因?yàn)樯a(chǎn)環(huán)境前端已經(jīng)打包進(jìn)后端工程本身就是同源的不存在跨域。如果后端非要用CORS我推薦寫一個(gè)WebMvcConfigurer配置類而不是加CrossOrigin注解。CORS配置類寫法如下注意要同時(shí)配置allowedOriginPatterns和allowedMethods否則預(yù)檢請求會失敗Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }聯(lián)調(diào)階段另一個(gè)高頻問題是時(shí)間格式不一致。后端實(shí)體類LocalDateTime序列化后默認(rèn)是一長串?dāng)?shù)組前端無法直接渲染。需要在application.yml里配置Jackson的日期格式spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT84.3 Vue項(xiàng)目打包放進(jìn)SpringBoot開發(fā)完成后部署最直接的方式是把Vue打包生成的dist目錄塞進(jìn)SpringBoot的靜態(tài)資源目錄。這個(gè)過程看似簡單但有兩個(gè)坑特別常見。第一步是修改Vite的base配置默認(rèn)是/打包后資源路徑是絕對路徑部署到服務(wù)器子路徑時(shí)會找不到靜態(tài)資源。我建議改成相對路徑export default defineConfig({ base: ./, build: { outDir: dist, assetsDir: static } })第二步是路由模式。如果前端路由用了history模式刷新頁面時(shí)后端沒有對應(yīng)的路由處理器就會出現(xiàn)404。最簡單的方案是后端加一個(gè)轉(zhuǎn)發(fā)規(guī)則未匹配到的路徑全部轉(zhuǎn)發(fā)到index.html。如果不想動后端前端路由改用hash模式URL多一個(gè)#號但刷新永遠(yuǎn)正常。個(gè)人推薦hash模式省心。把dist下的文件復(fù)制到SpringBoot的src/main/resources/static目錄然后啟動后端訪問http://localhost:8080/就是完整系統(tǒng)。這樣整個(gè)應(yīng)用只有一個(gè)Jar包部署到服務(wù)器只需要Java環(huán)境不用單獨(dú)裝Nginx。4.4 常見報(bào)錯(cuò)排查速查表寫這套系統(tǒng)的過程中我把遇到過的高頻報(bào)錯(cuò)整理成了一個(gè)速查表對照排查能省大量時(shí)間。現(xiàn)象可能原因解決方案前端請求后端404代理沒配或路徑拼錯(cuò)檢查vite.config.js代理配置和API路徑前綴登錄后調(diào)用接口返回403Security配置放行路徑不完整檢查JWT過濾器注冊順序和路徑匹配規(guī)則文件上傳報(bào)錯(cuò)超過大小限制后端multipart配置未生效檢查yaml配置中max-file-size和max-request-size中文亂碼數(shù)據(jù)庫字符集不是utf8mb4建庫時(shí)指定utf8mb4連接串加characterEncodingutf8刷新頁面404前端history路由沒配轉(zhuǎn)發(fā)用hash模式或后端加轉(zhuǎn)發(fā)規(guī)則Token過期后接口一直報(bào)錯(cuò)前端沒做401統(tǒng)一處理在響應(yīng)攔截器里統(tǒng)一跳轉(zhuǎn)登錄頁Vue啟動報(bào)Node版本不兼容Node版本過低升級到Node 16或降低Vite版本還有幾個(gè)容易忽略的小問題。SpringBoot啟動時(shí)如果端口被占用控制臺會直接報(bào)端口綁定失敗搜索哪個(gè)進(jìn)程占了8080端口殺掉或者改端口。MyBatis Plus分頁插件需要單獨(dú)配置PaginationInterceptor不配置的話分頁不生效默認(rèn)只查一條。另外前端打包時(shí)如果報(bào)內(nèi)存溢出需要在package.json里配置build: vite build --max-old-space-size4096或者Node設(shè)置的NODE_OPTIONS變量。最后聊一點(diǎn)管理后臺的統(tǒng)計(jì)報(bào)表功能。競賽系統(tǒng)的管理者非常關(guān)注每個(gè)競賽的報(bào)名人數(shù)、作品提交率、各學(xué)院參與人數(shù)分布。這些統(tǒng)計(jì)我用ECharts做曲線圖和餅圖后端提供一個(gè)聚合查詢接口用MyBatis Plus的groupBy統(tǒng)計(jì)每個(gè)學(xué)院的人數(shù)。ECharts的引入方式很簡單npm安裝然后在需要用的組件里局部引入按需注冊圖表類型避免全量打包導(dǎo)致體積過大。還有評委打分環(huán)節(jié)的設(shè)計(jì)也要多說兩句。傳統(tǒng)做法是管理員給每個(gè)評委手動分配作品但作品數(shù)量一多就非常繁瑣。我的做法是先把作品按類別分組評委可以主動認(rèn)領(lǐng)作品也可以由管理員批量分配。打分維度我拆成了創(chuàng)新性、完整性、實(shí)用性三個(gè)子項(xiàng)每個(gè)子項(xiàng)記分總分自動匯總再取多個(gè)評委的平均分作為最終成績。設(shè)置一個(gè)“成績公示”開關(guān)控制學(xué)生是否能在前臺看到自己的分?jǐn)?shù)避免未出結(jié)果前分?jǐn)?shù)泄露。這個(gè)項(xiàng)目后續(xù)可以考慮擴(kuò)展的方向一個(gè)是接入消息通知模塊報(bào)名成功和成績公布時(shí)給用戶發(fā)送站內(nèi)信或者郵件另一個(gè)是增加數(shù)據(jù)可視化大屏頁面把全校的競賽參與情況用圖表形式展示出來這個(gè)對答辯演示的加分效果是很明顯的。再一個(gè)就是引入Redis緩存首頁的競賽列表和熱門賽事情報(bào)減少M(fèi)ySQL的查詢壓力。我個(gè)人在實(shí)際維護(hù)這套系統(tǒng)的感受是業(yè)務(wù)功能本身不難難點(diǎn)都在細(xì)節(jié)的邊界處理和數(shù)據(jù)狀態(tài)的流轉(zhuǎn)上。狀態(tài)機(jī)的設(shè)計(jì)、權(quán)限控制的粒度、文件上傳的健壯性、部署路徑的兼容性這四塊做好系統(tǒng)基本上就穩(wěn)了。你在照著實(shí)現(xiàn)的時(shí)候如果遇到某個(gè)接口調(diào)不通或者某個(gè)狀態(tài)不對先從數(shù)據(jù)表看一眼數(shù)據(jù)是不是臟了再往代碼里排查絕大多數(shù)問題都是數(shù)據(jù)狀態(tài)不符合預(yù)期導(dǎo)致的。 基于SpringBoot和Vue的競賽管理系統(tǒng)：從JWT鑒權(quán)到部署實(shí)戰(zhàn)
做競賽管理系統(tǒng)這個(gè)選題我一直覺得是前后端分離項(xiàng)目里性價(jià)比最高的一類。業(yè)務(wù)模型清晰、角色邊界明確、數(shù)據(jù)流轉(zhuǎn)完整從用戶到權(quán)限再到文件上傳、狀態(tài)流轉(zhuǎn)、統(tǒng)計(jì)報(bào)表全都能覆蓋到。尤其對于正在做畢業(yè)設(shè)計(jì)或者想系統(tǒng)練手全棧的同學(xué)來說一套基于SpringBoot Vue的大學(xué)生競賽管理系統(tǒng)幾乎把企業(yè)級開發(fā)里最常見的那些坑都踩了一遍JWT鑒權(quán)怎么做、文件上傳怎么接、跨域怎么配、前端打包怎么塞進(jìn)后端、路由守衛(wèi)怎么攔截。這篇文章就把我這套系統(tǒng)的完整思路、核心代碼、表設(shè)計(jì)和部署經(jīng)驗(yàn)一次性講清楚照著做你也能從零搭出一套能跑、能答辯、能演示的完整項(xiàng)目。1. 整體設(shè)計(jì)與技術(shù)選型先把業(yè)務(wù)想明白再動手1.1 角色劃分與核心業(yè)務(wù)流程競賽管理系統(tǒng)這個(gè)業(yè)務(wù)本質(zhì)上就是“賽事全流程管理”。從管理員發(fā)布競賽到學(xué)生報(bào)名、上傳作品再到評委打分、成績公示、證書下載一條線走完。傳統(tǒng)的紙筆流程最大的問題是信息不透明學(xué)生不知道報(bào)名是否成功、評委之間分?jǐn)?shù)互相看不到、管理員統(tǒng)計(jì)成績?nèi)縀xcel。系統(tǒng)把這些環(huán)節(jié)數(shù)字化之后每步操作都有狀態(tài)記錄和時(shí)間戳權(quán)責(zé)清晰審計(jì)也方便。我在設(shè)計(jì)角色時(shí)劃分了三種學(xué)生瀏覽競賽列表、查看詳情、報(bào)名參賽、上傳作品、查看自己的成績和證書。評委/教師對分配到名下的作品打分、填寫評語、查看已評和待評列表。管理員用戶管理、競賽信息發(fā)布與狀態(tài)控制、報(bào)名審核、評委分配、成績統(tǒng)計(jì)與導(dǎo)出。這三種角色的權(quán)限邊界要非常明確。學(xué)生不能看到評委打分頁評委不能修改競賽信息管理員不參與打分。權(quán)限控制如果做不好后續(xù)所有功能都會出現(xiàn)越權(quán)訪問的漏洞。1.2 技術(shù)棧選型的三個(gè)理由這套系統(tǒng)我選擇的是SpringBoot 2.7.x Vue 3 Element Plus MySQL 8 MyBatis Plus。選這套組合不是跟風(fēng)而是有幾個(gè)實(shí)際考量。第一個(gè)考量是SpringBoot版本。2.7.x是目前兼容性最穩(wěn)的版本JDK 8和JDK 11都能跑各種第三方starter基本都能找到對應(yīng)版本。SpringBoot 3.0之后強(qiáng)制要求JDK 17很多學(xué)生本機(jī)的JDK版本還是8一上來就報(bào)各種版本兼容錯(cuò)誤光環(huán)境問題就能卡一整天。當(dāng)然如果你本機(jī)已經(jīng)是JDK 17直接用3.x也沒問題只是要注意javax命名空間改成jakartaMyBatis Plus和相關(guān)依賴也要用適配版本。第二個(gè)考量是前端框架版本。Vue 3 Vite Element Plus是當(dāng)前的主流組合Vite的啟動速度比Webpack快一個(gè)量級開發(fā)體驗(yàn)好很多。組件庫用Element Plus界面風(fēng)格統(tǒng)一表格、表單、彈窗、上傳組件都是現(xiàn)成的不用從零寫UI。如果你更熟悉Vue 2 Element UI思路完全一樣只是API細(xì)節(jié)略有差異不影響整體架構(gòu)。第三個(gè)考量是持久層框架。MyBatis Plus在單表CRUD場景下幾乎不用寫SQL自帶分頁插件和條件構(gòu)造器開發(fā)效率非常高。競賽管理系統(tǒng)里大部分查詢都是單表?xiàng)l件查詢比如“查詢某個(gè)競賽下所有報(bào)名記錄”“查詢當(dāng)前用戶的所有作品”用LambdaQueryWrapper幾行代碼就搞定了沒必要手寫復(fù)雜的XML映射。1.3 數(shù)據(jù)庫表設(shè)計(jì)的六個(gè)核心表數(shù)據(jù)庫是整個(gè)系統(tǒng)的地基我踩過最深的坑就是表設(shè)計(jì)太隨意改表結(jié)構(gòu)比改代碼痛苦十倍。競賽系統(tǒng)核心表我設(shè)計(jì)如下前后端聯(lián)調(diào)階段的“接口字段和數(shù)據(jù)庫字段對不上”問題源頭就在這里。表名核心字段說明sys_userid, username, password, nickname, role, avatar, college, major, student_no, phone, email, status, create_time用戶表role區(qū)分admin/teacher/studentcontestid, title, description, category, cover, max_team_members, registration_start_time, registration_end_time, contest_start_time, contest_end_time, status, create_time競賽表status字段控制生命周期contest_registrationid, contest_id, user_id, team_name, team_members, contact_phone, status, create_time報(bào)名表status分為待審核/已通過/已拒絕work_submissionid, contest_id, user_id, registration_id, title, description, file_url, cover_url, submit_time, status作品表一個(gè)報(bào)名對應(yīng)一個(gè)作品contest_scoreid, work_id, reviewer_id, score, comment, create_time評分表同一作品多個(gè)評委打分后取平均noticeid, title, content, type, owner_id, publish_time新聞公告表前臺輪播和消息通知用重點(diǎn)說一下競賽的status字段。我用了數(shù)字字典0表示草稿、1表示報(bào)名中、2表示評審中、3表示已結(jié)束。前端根據(jù)這個(gè)值控制按鈕的可用狀態(tài)后端在報(bào)名接口也校驗(yàn)當(dāng)前時(shí)間是否在報(bào)名窗口內(nèi)雙重保險(xiǎn)避免有人繞過前端直接調(diào)接口。另外一個(gè)關(guān)鍵設(shè)計(jì)是work_submission里的registration_id它把報(bào)名表和作品表關(guān)聯(lián)起來。這樣查詢“某學(xué)生報(bào)名了哪些競賽”和“某競賽收了哪些作品”都非常方便。前期表設(shè)計(jì)時(shí)把外鍵關(guān)系理清后面寫查詢就是順?biāo)浦鄣氖隆?. 后端核心模塊從登錄鑒權(quán)到文件上傳的完整閉環(huán)2.1 統(tǒng)一響應(yīng)體與全局異常處理前后端分離項(xiàng)目接口返回格式必須統(tǒng)一。我封裝了一個(gè)Result類所有接口返回{code, message, data}的結(jié)構(gòu)。code為200表示成功401表示未登錄403表示無權(quán)限500表示業(yè)務(wù)異常。這個(gè)封裝看起來簡單但能讓前端攔截器的處理邏輯變得非常整潔。Data public class ResultT { private Integer code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMessage(操作成功); result.setData(data); return result; } public static T ResultT error(Integer code, String message) { ResultT result new Result(); result.setCode(code); result.setMessage(message); return result; } }有了統(tǒng)一響應(yīng)體還需要一個(gè)全局異常處理器把業(yè)務(wù)異常和系統(tǒng)異常分開處理。我是用RestControllerAdvice注解實(shí)現(xiàn)的捕獲自定義的BusinessException拋出的異常時(shí)返回對應(yīng)的錯(cuò)誤碼和提示語捕獲Exception時(shí)統(tǒng)一返回500和“系統(tǒng)異常請稍后重試”避免把堆棧信息直接暴露給前端。這里有個(gè)開發(fā)習(xí)慣值得養(yǎng)成不要把try-catch寫在每個(gè)Controller里而是讓業(yè)務(wù)層拋出異常由全局處理器統(tǒng)一處理。代碼會干凈很多也不容易漏掉異常分支。2.2 Spring Security JWT登錄鑒權(quán)實(shí)戰(zhàn)登錄鑒權(quán)是這類系統(tǒng)的重中之重。我用的是JWT無狀態(tài)方案用戶登錄成功后后端簽發(fā)一個(gè)包含用戶ID、用戶名、角色信息的Token前端請求時(shí)放在請求頭的Authorization字段里后端攔截器解析Token并校驗(yàn)身份。這樣做的好處是服務(wù)端不需要存儲Session水平擴(kuò)展時(shí)不需要做Session共享對部署和將來合入網(wǎng)關(guān)都很友好。JWT工具類核心代碼如下注意設(shè)置過期時(shí)間和密鑰Component public class JwtUtils { private static final String SECRET your-secret-key-your-secret-key; private static final long EXPIRATION 1000 * 60 * 60 * 24 * 7L; public String generateToken(Integer userId, String username, String role) { return Jwts.builder() .setSubject(username) .claim(userId, userId) .claim(role, role) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() EXPIRATION)) .signWith(SignatureAlgorithm.HS256, SECRET) .compact(); } public Claims parseToken(String token) { return Jwts.parser() .setSigningKey(SECRET) .parseClaimsJws(token) .getBody(); } }Security配置類是這個(gè)模塊中最容易出錯(cuò)的地方。需要放行登錄接口、驗(yàn)證碼接口和靜態(tài)資源路徑其余接口全部走JWT過濾器。放行哪些路徑看似簡單但如果你把接口路徑寫錯(cuò)或者放行多了后面調(diào)接口時(shí)就會出現(xiàn)“明明登錄成功了卻一直401”的詭異問題。Configuration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Override protected void configure(HttpSecurity http) throws Exception { http.csrf().disable() .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() .authorizeRequests() .antMatchers(/api/auth/login, /api/upload/**, /files/**).permitAll() .antMatchers(/api/admin/**).hasRole(admin) .antMatchers(/api/teacher/**).hasRole(teacher) .anyRequest().authenticated() .and() .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class); } }角色和路徑的匹配規(guī)則要提前規(guī)劃。我在實(shí)際開發(fā)中把接口路徑做了約定/api/student/**學(xué)生接口、/api/teacher/**評委接口、/api/admin/**管理接口、/api/common/**公共接口。前端的API請求也遵循這個(gè)約定后端的鑒權(quán)配置就非常清晰。2.3 競賽報(bào)名與作品提交狀態(tài)機(jī)與并發(fā)控制報(bào)名和作品提交是競賽系統(tǒng)的核心業(yè)務(wù)操作這兩個(gè)接口在并發(fā)場景下特別容易出現(xiàn)臟數(shù)據(jù)。比如同一個(gè)學(xué)生重復(fù)提交報(bào)名或者報(bào)名截止時(shí)間剛過但請求還在路上。我處理的思路是雙保險(xiǎn)數(shù)據(jù)庫層面加唯一索引代碼層面做業(yè)務(wù)校驗(yàn)。報(bào)名表上加UNIQUE KEY uk_contest_user (contest_id, user_id)這樣即使兩個(gè)并發(fā)請求同時(shí)通過代碼校驗(yàn)數(shù)據(jù)庫也會攔截重復(fù)插入返回DuplicateKeyException。代碼里再判斷當(dāng)前時(shí)間是否在報(bào)名窗口期、競賽狀態(tài)是否為“報(bào)名中”雙重保障確保數(shù)據(jù)正確。作品提交的邏輯稍微復(fù)雜一點(diǎn)。學(xué)生在報(bào)名審核通過后才能上傳作品上傳后可以修改截止時(shí)間后鎖定。我設(shè)計(jì)了works表的status字段0表示未提交、1表示已提交待評審、2表示已退回修改。評委退回作品后學(xué)生重新上傳狀態(tài)回到1進(jìn)入評審隊(duì)列。這個(gè)狀態(tài)機(jī)設(shè)計(jì)是整個(gè)系統(tǒng)業(yè)務(wù)邏輯里最容易寫亂的地方。我強(qiáng)烈建議先在紙上畫出狀態(tài)流轉(zhuǎn)圖待審核-已通過-已提交-已退回-已提交每個(gè)狀態(tài)觸發(fā)什么事件、誰觸發(fā)、產(chǎn)生什么結(jié)果搞清楚再寫代碼。不然代碼越寫越亂改一個(gè)狀態(tài)還要連帶著改三四處邏輯。2.4 文件上傳與靜態(tài)資源映射競賽作品通常是PDF、壓縮包或者圖片文件上傳功能必不可少。SpringBoot的文件上傳配置很簡潔spring: servlet: multipart: max-file-size: 100MB max-request-size: 200MB文件上傳的Controller稍微有點(diǎn)講究需要做文件類型白名單校驗(yàn)、文件名重命名防路徑穿越、按日期歸檔存儲。我的實(shí)現(xiàn)邏輯是接收MultipartFile校驗(yàn)后綴名是否在允許列表里用UUID重新生成文件名存儲到uploads/yyyy/MM/dd/目錄下返回?cái)?shù)據(jù)庫里的相對路徑。相對路徑加上域名前綴就是完整的訪問URL。前端上傳PDF后需要預(yù)覽這里有一個(gè)很實(shí)用的技巧如果瀏覽器可以直接打開PDF用iframe嵌; 但要注意Element Plus的upload組件默認(rèn)會走form-data提交后端返回的JSON需要放在response里而不是自定義header里否則回顯會有兼容問題。這個(gè)我后面在前端章節(jié)再展開講。3. 前端Vue實(shí)踐從腳手架到核心交互3.1 項(xiàng)目結(jié)構(gòu)與路由設(shè)計(jì)前端項(xiàng)目我用Vite腳手架創(chuàng)建推薦的目錄結(jié)構(gòu)如下src/ api/ # 接口請求封裝 auth.js contest.js work.js assets/ # 靜態(tài)資源 components/ # 公共組件 CommonTable.vue FileUpload.vue router/ # 路由配置 index.js store/ # Pinia狀態(tài)管理 user.js views/ admin/ # 管理端頁面 student/ # 學(xué)生端頁面 teacher/ # 評委端頁面 Login.vue Home.vue路由設(shè)計(jì)上我用了動態(tài)路由和路由守衛(wèi)結(jié)合的方式。靜態(tài)路由只有登錄頁和首頁其他頁面根據(jù)用戶角色動態(tài)生成。這樣做的好處是角色菜單天然分離學(xué)生登錄后看不到評委頁面同時(shí)也減少了首屏加載的路由數(shù)量。路由守衛(wèi)是必須寫的不然用戶手動改URL就能跳到?jīng)]權(quán)限的頁面router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.path /login) { next() } else if (!token) { next(/login) } else { const userStore useUserStore() if (!userStore.userInfo) { userStore.fetchUserInfo().then(() { next() }).catch(() { next(/login) }) } else { next() } } })3.2 Axios請求封裝與Token刷新邏輯Axios封裝這項(xiàng)工作看似簡單但卻是前后端聯(lián)調(diào)時(shí)體驗(yàn)好不好的決定性因素。我的封裝思路是創(chuàng)建axios實(shí)例設(shè)置baseURL為/api請求攔截器里從localStorage取Token并放入Authorization頭響應(yīng)攔截器里統(tǒng)一處理HTTP狀態(tài)碼和業(yè)務(wù)狀態(tài)碼。const service axios.create({ baseURL: /api, timeout: 10000 }) 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) { return res } if (res.code 401) { localStorage.removeItem(token) window.location.href /login } return Promise.reject(new Error(res.message)) }, error { return Promise.reject(error) } )特別是401的處理很多新手容易漏掉。Token過期后如果只是彈個(gè)“請重新登錄”的提示用戶就卡在頁面上不知道該怎么辦。跳轉(zhuǎn)到登錄頁并清空本地存儲是最直觀的處理方式。3.3 核心頁面交互競賽列表、詳情與倒計(jì)時(shí)競賽列表頁是學(xué)生接觸系統(tǒng)的第一屏交互友好度直接影響使用體驗(yàn)。我用卡片形式展示競賽信息每個(gè)卡片包含封面圖、標(biāo)題、競賽類別、報(bào)名截止時(shí)間、當(dāng)前狀態(tài)標(biāo)簽。點(diǎn)擊卡片跳轉(zhuǎn)到詳情頁路由傳遞競賽ID參數(shù)。這里最考驗(yàn)細(xì)節(jié)的是競賽狀態(tài)與按鈕的聯(lián)動。報(bào)名按鈕要依據(jù)后端返回的status字段和當(dāng)前時(shí)間動態(tài)計(jì)算status為1且當(dāng)前時(shí)間在報(bào)名窗口內(nèi)顯示“立即報(bào)名”不在窗口內(nèi)顯示“報(bào)名未開始”或“已截止”status為2顯示“評審中”status為3顯示“已結(jié)束”。這些狀態(tài)計(jì)算我放在前端寫了一個(gè)工具函數(shù)export function getContestStatus(contest) { const now Date.now() const start new Date(contest.registrationStartTime).getTime() const end new Date(contest.registrationEndTime).getTime() if (contest.status 0) return { text: 未發(fā)布, type: info } if (contest.status 1 now start) return { text: 報(bào)名未開始, type: warning } if (contest.status 1 now start now end) return { text: 報(bào)名中, type: success } if (contest.status 1 now end) return { text: 報(bào)名已截止, type: danger } if (contest.status 2) return { text: 評審中, type: warning } if (contest.status 3) return { text: 已結(jié)束, type: info } }詳情頁我同時(shí)展示了競賽介紹、時(shí)間線、賽事流程說明。倒計(jì)時(shí)組件用setInterval實(shí)現(xiàn)每秒鐘更新剩余時(shí)間頁面銷毀時(shí)記得清除定時(shí)器。這個(gè)組件雖小但踩過的坑是路由切換后定時(shí)器沒清掉導(dǎo)致組件銷毀后還在執(zhí)行setState控制臺報(bào)一堆警告。3.4 文件上傳組件與PDF預(yù)覽系統(tǒng)最核心的上傳場景是作品提交以PDF為主。Element Plus的el-upload組件提供了拖拽上傳和進(jìn)度顯示但默認(rèn)行為是選擇文件后立即上傳。我配置了:auto-uploadfalse用戶選擇文件后先展示在文件列表里點(diǎn)擊“確認(rèn)提交”才真正發(fā)起上傳避免誤選后無法撤銷。上傳成功后預(yù)覽PDF我用了兩種方案兼容不同場景。如果瀏覽器原生支持PDF預(yù)覽直接新窗口打開文件URL就行。為了更好的展示體驗(yàn)我在前端頁面內(nèi)嵌了iframe將PDF文件URL作為src實(shí)測Chrome和Edge都能正常顯示。如果需要更精細(xì)的控制比如指定頁碼、縮放可以使用pdf.js或者vue-pdf組件不過對于競賽管理系統(tǒng)的場景iframe方案已經(jīng)足夠還省了一個(gè)大依賴。用戶的頭像預(yù)覽也是一樣的邏輯文件上傳后返回相對路徑前端拼接成完整URL用于img標(biāo)簽的src。這里注意一個(gè)問題開發(fā)環(huán)境下后端接口在8080端口前端在5173端口圖片URL如果是相對路徑瀏覽器會去5173端口找就404了。解決辦法是用Vite的代理配置把/api和/files都代理到后端地址。4. 環(huán)境搭建、聯(lián)調(diào)與部署實(shí)戰(zhàn)4.1 本地環(huán)境準(zhǔn)備與依賴配置開始寫代碼之前先把環(huán)境搞定不然后面踩的坑都是環(huán)境的鍋。我建議本地環(huán)境如下JDK 8 或 11對應(yīng)SpringBoot 2.7.xMaven 3.6配置阿里云鏡像源否則依賴下載慢到懷疑人生Node 16Vite 4要求Node 14.18我推薦Node 16長期支持版MySQL 8.0字符集全部設(shè)置為utf8mb4否則中文亂碼Maven的pom.xml核心依賴清單如下注意MyBatis Plus和SpringBoot的版本兼容關(guān)系parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.7/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt/artifactId version0.9.1/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies4.2 前后端聯(lián)調(diào)跨域問題與接口規(guī)范前后端分離項(xiàng)目跨域問題幾乎必然遇到。開發(fā)環(huán)境最省事的方案是Vite代理在vite.config.js里配置export default defineConfig({ server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true }, /files: { target: http://localhost:8080, changeOrigin: true } } } })配置了代理之后前端代碼里所有請求都寫相對路徑/api/xxx由Vite轉(zhuǎn)發(fā)到8080端口。這種方式比后端配置CORS要優(yōu)雅得多因?yàn)樯a(chǎn)環(huán)境前端已經(jīng)打包進(jìn)后端工程本身就是同源的不存在跨域。如果后端非要用CORS我推薦寫一個(gè)WebMvcConfigurer配置類而不是加CrossOrigin注解。CORS配置類寫法如下注意要同時(shí)配置allowedOriginPatterns和allowedMethods否則預(yù)檢請求會失敗Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }聯(lián)調(diào)階段另一個(gè)高頻問題是時(shí)間格式不一致。后端實(shí)體類LocalDateTime序列化后默認(rèn)是一長串?dāng)?shù)組前端無法直接渲染。需要在application.yml里配置Jackson的日期格式spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT84.3 Vue項(xiàng)目打包放進(jìn)SpringBoot開發(fā)完成后部署最直接的方式是把Vue打包生成的dist目錄塞進(jìn)SpringBoot的靜態(tài)資源目錄。這個(gè)過程看似簡單但有兩個(gè)坑特別常見。第一步是修改Vite的base配置默認(rèn)是/打包后資源路徑是絕對路徑部署到服務(wù)器子路徑時(shí)會找不到靜態(tài)資源。我建議改成相對路徑export default defineConfig({ base: ./, build: { outDir: dist, assetsDir: static } })第二步是路由模式。如果前端路由用了history模式刷新頁面時(shí)后端沒有對應(yīng)的路由處理器就會出現(xiàn)404。最簡單的方案是后端加一個(gè)轉(zhuǎn)發(fā)規(guī)則未匹配到的路徑全部轉(zhuǎn)發(fā)到index.html。如果不想動后端前端路由改用hash模式URL多一個(gè)#號但刷新永遠(yuǎn)正常。個(gè)人推薦hash模式省心。把dist下的文件復(fù)制到SpringBoot的src/main/resources/static目錄然后啟動后端訪問http://localhost:8080/就是完整系統(tǒng)。這樣整個(gè)應(yīng)用只有一個(gè)Jar包部署到服務(wù)器只需要Java環(huán)境不用單獨(dú)裝Nginx。4.4 常見報(bào)錯(cuò)排查速查表寫這套系統(tǒng)的過程中我把遇到過的高頻報(bào)錯(cuò)整理成了一個(gè)速查表對照排查能省大量時(shí)間。現(xiàn)象可能原因解決方案前端請求后端404代理沒配或路徑拼錯(cuò)檢查vite.config.js代理配置和API路徑前綴登錄后調(diào)用接口返回403Security配置放行路徑不完整檢查JWT過濾器注冊順序和路徑匹配規(guī)則文件上傳報(bào)錯(cuò)超過大小限制后端multipart配置未生效檢查yaml配置中max-file-size和max-request-size中文亂碼數(shù)據(jù)庫字符集不是utf8mb4建庫時(shí)指定utf8mb4連接串加characterEncodingutf8刷新頁面404前端history路由沒配轉(zhuǎn)發(fā)用hash模式或后端加轉(zhuǎn)發(fā)規(guī)則Token過期后接口一直報(bào)錯(cuò)前端沒做401統(tǒng)一處理在響應(yīng)攔截器里統(tǒng)一跳轉(zhuǎn)登錄頁Vue啟動報(bào)Node版本不兼容Node版本過低升級到Node 16或降低Vite版本還有幾個(gè)容易忽略的小問題。SpringBoot啟動時(shí)如果端口被占用控制臺會直接報(bào)端口綁定失敗搜索哪個(gè)進(jìn)程占了8080端口殺掉或者改端口。MyBatis Plus分頁插件需要單獨(dú)配置PaginationInterceptor不配置的話分頁不生效默認(rèn)只查一條。另外前端打包時(shí)如果報(bào)內(nèi)存溢出需要在package.json里配置build: vite build --max-old-space-size4096或者Node設(shè)置的NODE_OPTIONS變量。最后聊一點(diǎn)管理后臺的統(tǒng)計(jì)報(bào)表功能。競賽系統(tǒng)的管理者非常關(guān)注每個(gè)競賽的報(bào)名人數(shù)、作品提交率、各學(xué)院參與人數(shù)分布。這些統(tǒng)計(jì)我用ECharts做曲線圖和餅圖后端提供一個(gè)聚合查詢接口用MyBatis Plus的groupBy統(tǒng)計(jì)每個(gè)學(xué)院的人數(shù)。ECharts的引入方式很簡單npm安裝然后在需要用的組件里局部引入按需注冊圖表類型避免全量打包導(dǎo)致體積過大。還有評委打分環(huán)節(jié)的設(shè)計(jì)也要多說兩句。傳統(tǒng)做法是管理員給每個(gè)評委手動分配作品但作品數(shù)量一多就非常繁瑣。我的做法是先把作品按類別分組評委可以主動認(rèn)領(lǐng)作品也可以由管理員批量分配。打分維度我拆成了創(chuàng)新性、完整性、實(shí)用性三個(gè)子項(xiàng)每個(gè)子項(xiàng)記分總分自動匯總再取多個(gè)評委的平均分作為最終成績。設(shè)置一個(gè)“成績公示”開關(guān)控制學(xué)生是否能在前臺看到自己的分?jǐn)?shù)避免未出結(jié)果前分?jǐn)?shù)泄露。這個(gè)項(xiàng)目后續(xù)可以考慮擴(kuò)展的方向一個(gè)是接入消息通知模塊報(bào)名成功和成績公布時(shí)給用戶發(fā)送站內(nèi)信或者郵件另一個(gè)是增加數(shù)據(jù)可視化大屏頁面把全校的競賽參與情況用圖表形式展示出來這個(gè)對答辯演示的加分效果是很明顯的。再一個(gè)就是引入Redis緩存首頁的競賽列表和熱門賽事情報(bào)減少M(fèi)ySQL的查詢壓力。我個(gè)人在實(shí)際維護(hù)這套系統(tǒng)的感受是業(yè)務(wù)功能本身不難難點(diǎn)都在細(xì)節(jié)的邊界處理和數(shù)據(jù)狀態(tài)的流轉(zhuǎn)上。狀態(tài)機(jī)的設(shè)計(jì)、權(quán)限控制的粒度、文件上傳的健壯性、部署路徑的兼容性這四塊做好系統(tǒng)基本上就穩(wěn)了。你在照著實(shí)現(xiàn)的時(shí)候如果遇到某個(gè)接口調(diào)不通或者某個(gè)狀態(tài)不對先從數(shù)據(jù)表看一眼數(shù)據(jù)是不是臟了再往代碼里排查絕大多數(shù)問題都是數(shù)據(jù)狀態(tài)不符合預(yù)期導(dǎo)致的。