1. 項目定位與整體設(shè)計思路1.1 高校運(yùn)動會管理到底在管什么每年春秋兩季各高校都要辦運(yùn)動會。但真正經(jīng)歷過的人都知道一場覆蓋幾十個學(xué)院、上千名運(yùn)動員、近百個比賽項目的校級運(yùn)動會背后的事務(wù)性工作有多繁瑣運(yùn)動員報名信息要反復(fù)核對、田賽徑賽的時間場地要人工排布、檢錄表要打印幾百份、成績出來后要手工統(tǒng)計團(tuán)體總分、破紀(jì)錄要翻查歷史數(shù)據(jù)、證書要一個個手寫填寫。我做過幾個類似的信息化項目最大的感受是運(yùn)動會的業(yè)務(wù)鏈路其實非常適合系統(tǒng)化管理。它的數(shù)據(jù)邊界清晰——運(yùn)動員、項目、成績、團(tuán)體分就這四類核心實體但它的規(guī)則細(xì)節(jié)又足夠多——同分如何判定名次、一個運(yùn)動員最多報幾個單項、接力項目算不算雙倍積分、田賽和徑賽的名次錄取規(guī)則還完全不同。這些規(guī)則如果靠Excel維護(hù)每屆運(yùn)動會都要重做一遍而且極易出錯。這個項目就是做一個前后端分離的高校體育運(yùn)動會管理系統(tǒng)后端用Spring Boot提供RESTful接口前端用Vue 3 Element Plus搭建管理界面支持從運(yùn)動員報名、賽事編排、成績錄入到團(tuán)體總分自動排名、證書打印的全流程管理。它解決的痛點很明確把運(yùn)動會的組織工作從Excel 微信群 手寫紙質(zhì)表的模式遷移到一套可配置、可追溯、可復(fù)用的在線系統(tǒng)里。適合誰來參考這個項目如果你正在做類似的校園管理類系統(tǒng)考勤、選課、社團(tuán)活動報名都適用或者你的畢業(yè)設(shè)計/課程設(shè)計正好落在這個方向這篇文章里的數(shù)據(jù)建模思路、成績排名算法、文件存儲方案和前后端部署細(xì)節(jié)都可以直接抄作業(yè)。1.2 為什么選Spring Boot Vue這套組合選型這事我向來不追求花哨關(guān)鍵是穩(wěn)定和生態(tài)成熟。Spring Boot Vue這套組合在校園管理類系統(tǒng)里基本是標(biāo)準(zhǔn)答案級別理由有三第一Spring Boot的自動裝配機(jī)制極大降低了后端搭建成本。項目里用到Spring Security做登錄認(rèn)證、MyBatis-Plus操作數(shù)據(jù)庫、MinIO做文件存儲、POI做Excel導(dǎo)入導(dǎo)出這些都是Spring Boot生態(tài)里非常成熟的組件。你不需要為每個功能單獨寫一堆配置類加依賴、配application.yml、寫業(yè)務(wù)接口三步走。第二Vue 3 Element Plus的前端方案對管理后臺這類以表單和表格為核心的場景非常友好。運(yùn)動會系統(tǒng)的前端頁面本質(zhì)上就是報名表、編排表、成績單的電子化呈現(xiàn)Element Plus的表格組件自帶排序、篩選、分頁表單組件自帶校驗規(guī)則配合Vue Router做頁面跳轉(zhuǎn)、Pinia做全局狀態(tài)管理開發(fā)效率比原生jQuery時代高出一個量級。第三前后端分離帶來的部署靈活性。開發(fā)階段前端用Vite dev server跑在5173端口后端跑在8080端口通過代理轉(zhuǎn)發(fā)解決跨域部署階段既可以把前端打包成靜態(tài)文件扔到Nginx里也可以把dist目錄直接塞進(jìn)Spring Boot的resources/static打成單jar包運(yùn)行。兩種方案我都實際跑過后面第5節(jié)會詳細(xì)講。2. 核心功能拆解與數(shù)據(jù)建模2.1 六個核心業(yè)務(wù)模塊整個系統(tǒng)按運(yùn)動會業(yè)務(wù)流程拆成六個模塊每個模塊的邊界要清晰才能避免后期改代碼改到頭禿系統(tǒng)管理模塊用戶登錄、角色權(quán)限超級管理員、學(xué)院領(lǐng)隊、裁判員、普通學(xué)生、學(xué)院班級數(shù)據(jù)維護(hù)。這里我用的是Spring Security JWT的無狀態(tài)認(rèn)證前端登錄后拿到token存在localStorage里每次請求帶在Authorization頭里。運(yùn)動員管理模塊運(yùn)動員信息錄入支持Excel批量導(dǎo)入這個很重要幾百號人一個個手輸會崩潰、運(yùn)動員報名項目管理要校驗每人限報兩個單項加一個接力這類規(guī)則。賽事編排模塊比賽項目維護(hù)田賽/徑賽分類、分組、預(yù)決賽輪次、賽程時間表生成、檢錄表打印。這塊的核心是一個場地時間沖突檢測算法后面3.1節(jié)細(xì)說。成績管理模塊裁判員錄入成績、成績復(fù)核、自動排名、破紀(jì)錄標(biāo)記。徑賽要記錄秒數(shù)并精確到百分位田賽記錄米數(shù)并精確到厘米排名邏輯完全不同。團(tuán)體總分模塊按單項、接力等不同權(quán)重自動累加學(xué)院總分支持實時刷新排行榜。數(shù)據(jù)統(tǒng)計與證書模塊各學(xué)院金牌榜/總分榜、運(yùn)動員個人成績單、獲獎證書PDF批量生成。2.2 數(shù)據(jù)庫表設(shè)計的關(guān)鍵決策數(shù)據(jù)庫設(shè)計是這個項目的骨架我踩過不少坑重點說三個決策第一比賽項目表的分類字段不能只存田賽/徑賽兩個值。我一開始只用一個event_type字段區(qū)分田賽和徑賽后來發(fā)現(xiàn)很多規(guī)則判斷都需要更細(xì)的分類徑賽里100米是全程分道800米是部分分道田賽里的跳高和鉛球的錄取規(guī)則也不同。最后改成兩級分類event_type田賽/徑賽/全能加event_sub_type短跑/長跑/跳躍/投擲代碼里用枚舉統(tǒng)一管理避免魔法值滿天飛。第二成績表和排名表分離。新手容易犯的錯是把排名直接算好存進(jìn)成績表成績一修改排名就亂套。我的做法是成績表result只存原始成績數(shù)據(jù)排名ranking由排名算法運(yùn)行時生成并緩存。這樣裁判錄入的成績能回溯、能復(fù)核排名出錯了重跑一遍算法就行數(shù)據(jù)永遠(yuǎn)干凈。第三別用一張報名表硬扛所有業(yè)務(wù)。運(yùn)動員報名一個項目涉及到運(yùn)動員表、項目表、報名關(guān)系表三張表。報名關(guān)系表里要加status字段已報名/已檢錄/已參賽/棄權(quán)這個狀態(tài)流轉(zhuǎn)是業(yè)務(wù)流程的核心后面3.3節(jié)講。核心庫表清單如下表名用途關(guān)鍵字段sys_user用戶賬號username, password, rolecollege學(xué)院name, codeathlete運(yùn)動員name, gender, college_id, student_noevent比賽項目name, type, sub_type, gender, round, score_unitregistration報名關(guān)系athlete_id, event_id, status, group_noresult成績記錄registration_id, score, rank, is_broken_recordschedule賽程安排event_id, venue, start_time, group_no3. 后端Spring Boot關(guān)鍵實現(xiàn)實錄3.1 賽事編排與場地時間沖突檢測賽程編排是個典型的約束滿足問題。一個標(biāo)準(zhǔn)田徑場有跑道、跳遠(yuǎn)沙坑、鉛球區(qū)等場地同一時間段內(nèi)不同場地可以并行比賽但同一場地不能同時安排兩場比賽。人工排賽程的痛點在于幾十個項目、幾百組比賽交叉安排很容易出現(xiàn)一個場地同時被占用、或者一個運(yùn)動員同時被兩個項目檢錄的沖突。我的實現(xiàn)思路是做一個時間槽 場地鎖的分配算法。先把運(yùn)動會時間切成固定時長的時段比如上午8:00-12:00按每30分鐘一個時隙每個場地在每個時隙只有一個可占用的槽位。編排時遍歷所有比賽組對每個組做三件事根據(jù)項目預(yù)估時長計算需要占用的時隙數(shù)量找一個所有所需時隙都空閑的場地檢查該組的運(yùn)動員在所選時段內(nèi)是否有其他比賽如果有則換時段。這個算法本質(zhì)是一個貪心策略實際使用中90%的場景都能一次分配成功剩余的沖突交給人工作調(diào)整。關(guān)鍵代碼邏輯// 場地時隙占用檢查 public boolean isVenueAvailable(Long venueId, LocalDateTime startTime, int durationMinutes, ListSchedule schedules) { LocalDateTime endTime startTime.plusMinutes(durationMinutes); return schedules.stream() .filter(s - s.getVenueId().equals(venueId)) .noneMatch(s - isTimeOverlap(s.getStartTime(), s.getEndTime(), startTime, endTime)); } // 運(yùn)動員同一時段沖突檢查 public boolean isAthleteAvailable(Long athleteId, LocalDateTime startTime, int durationMinutes, ListSchedule schedules) { // 查該運(yùn)動員所有已編排項目的比賽時間做區(qū)間重疊判斷 }注意貪心算法解決不了全部約束問題所以我給管理員留了手動調(diào)度的入口。界面上用日歷組件展示各場地的占用情況管理員可以直接拖拽調(diào)整系統(tǒng)實時做沖突提示。編排這個功能自動化程度再高人工兜底永遠(yuǎn)是必須的。3.2 成績錄入、復(fù)核與自動排名算法成績模塊是整個系統(tǒng)的業(yè)務(wù)核心也是最容易出邏輯bug的地方。徑賽成績錄入徑賽按秒記成績精確到百分位。裁判錄入的是原始成績比如11.25秒系統(tǒng)按小組排名然后所有組按成績統(tǒng)一排名取前八名進(jìn)入決賽或直接錄取。這里有個細(xì)節(jié)不同分組的運(yùn)動員成績要在不同組內(nèi)排序預(yù)賽小組排名決定晉級決賽排名則全體統(tǒng)一比較。田賽成績錄入田賽每人試跳/試投若干次通常是三次取最好成績作為最終成績。這個三次取最優(yōu)的邏輯要用獨立表記錄每次試跳成績最終成績字段單獨冗余一份方便排名時直接比較。排名算法的同分處理是重災(zāi)區(qū)。徑賽同秒數(shù)極少見但田賽里成績完全相同比如都跳過1.75米的情況很常見。國際田聯(lián)規(guī)則是如果成績相同比較次優(yōu)成績再相同就比較第三次成績也相同則名次并列。我在ranking服務(wù)里實現(xiàn)了完整的成績降序、次優(yōu)成績降序、第三次成績降序三級比較器public class FieldRankComparator implements ComparatorResult { Override public int compare(Result r1, Result r2) { // 第一級最好成績 int cmp Double.compare(r2.getBestScore(), r1.getBestScore()); if (cmp ! 0) return cmp; // 第二級次優(yōu)成績 cmp Double.compare(r2.getSecondBestScore(), r1.getSecondBestScore()); if (cmp ! 0) return cmp; // 第三級第三次成績 return Double.compare(r2.getThirdBestScore(), r1.getThirdBestScore()); } }破紀(jì)錄判斷我在event表里加了record_score字段存當(dāng)前校紀(jì)錄。成績錄入時自動比對超過就彈窗提示破紀(jì)錄并標(biāo)記is_broken_record字段。歷史紀(jì)錄數(shù)據(jù)我放在了單獨的record_history表里保留每次破紀(jì)錄的運(yùn)動員、成績、時間和原紀(jì)錄對比既方便做破紀(jì)錄排行榜展示也讓數(shù)據(jù)可追溯。3.3 報名狀態(tài)機(jī)與規(guī)則校驗報名這個環(huán)節(jié)看似簡單實際上是最容易讓用戶罵娘的地方。一場運(yùn)動會幾百上千個報名數(shù)據(jù)必須做好兩件事規(guī)則校驗和狀態(tài)流轉(zhuǎn)。規(guī)則校驗我在后端做了三層數(shù)據(jù)格式層學(xué)號格式、性別匹配、手機(jī)號格式用Spring Boot自帶的Validated注解搞定業(yè)務(wù)規(guī)則層每人限報兩個單項加一個接力、同一項目不能重復(fù)報名、女生不能報男子項目這些寫在Service層里用自定義異常拋出數(shù)據(jù)完整性層學(xué)院、班級ID必須存在且匹配避免前端傳了臟數(shù)據(jù)。報名狀態(tài)我用一個狀態(tài)機(jī)管理字段status取值范圍PENDING已提交待審核、APPROVED審核通過、CHECKED_IN已檢錄、COMPETED已完賽、CANCELLED已取消。狀態(tài)流轉(zhuǎn)圖如下PENDING - APPROVED - CHECKED_IN - COMPETED PENDING - CANCELLED APPROVED - CANCELLED每次狀態(tài)變更都會寫入registration_log表記錄操作人、操作時間、從哪個狀態(tài)到哪個狀態(tài)。這個設(shè)計在運(yùn)動會當(dāng)天特別有用——領(lǐng)隊說我的運(yùn)動員檢錄了沒裁判說這個運(yùn)動員到場了沒一查日志就清清楚楚。3.4 基于MinIO的文件存儲與M3U8視頻回放這個項目的文件存儲部分我一開始圖省事直接存服務(wù)器本地磁盤后來發(fā)現(xiàn)三個問題一是比賽視頻文件大一個項目幾百M(fèi)B本地磁盤扛不住二是服務(wù)器磁盤擴(kuò)容麻煩三是視頻在線回放需要流媒體支持。最后改成了MinIO這東西和Spring Boot的整合非常順滑。MinIO是什么你可以把它理解成一個跑在自己的服務(wù)器上的迷你S3對象存儲。數(shù)據(jù)以桶bucket為單位組織每個文件是一個對象用HTTP接口訪問。和FastDFS相比MinIO的部署和客戶端SDK要簡單太多和阿里云OSS相比它不依賴外部云服務(wù)數(shù)據(jù)不出校門。Spring Boot整合MinIO的步驟很簡單加依賴minioMaven坐標(biāo)是io.minio:minio:8.5.x在application.yml里配置endpoint、accessKey、secretKey、bucket名稱寫一個MinioService封裝上傳、下載、生成臨時訪問鏈接的方法。Service public class MinioService { Value(${minio.endpoint}) private String endpoint; Value(${minio.access-key}) private String accessKey; Value(${minio.secret-key}) private String secretKey; Value(${minio.bucket}) private String bucket; private MinioClient minioClient; PostConstruct public void init() { minioClient MinioClient.builder() .endpoint(endpoint) .credentials(accessKey, secretKey) .build(); // 檢查bucket是否存在不存在則創(chuàng)建 } public String upload(MultipartFile file, String objectName) throws Exception { minioClient.putObject( PutObjectArgs.builder() .bucket(bucket) .object(objectName) .stream(file.getInputStream(), file.getSize(), -1) .contentType(file.getContentType()) .build()); return endpoint / bucket / objectName; } }M3U8視頻回放這個需求很多人忽略但實際做的時候全是坑。運(yùn)動會現(xiàn)場錄的視頻格式五花八門手機(jī)錄的是MP4攝像機(jī)錄的是MOV讓瀏覽器直接播放需要格式兼容。我的方案是后端接一個FFmpeg轉(zhuǎn)碼服務(wù)把上傳的原始視頻統(tǒng)一轉(zhuǎn)成HLSM3U8流媒體格式再配合前端hls.js播放器實現(xiàn)在線回放。vue播放m3u8免安裝這個需求在運(yùn)動會場景下就是典型應(yīng)用——評委和觀眾不需要裝任何播放器瀏覽器打開就能看。轉(zhuǎn)碼我用的是FFmpeg命令行調(diào)用寫一個異步任務(wù)執(zhí)行ffmpeg -i input.mp4 -codec copy -start_number 0 -hls_time 10 -hls_list_size 0 -f hls output.m3u8前端Vue里用hls.js加載M3U8流import Hls from hls.js; function playVideo(videoUrl) { const video document.getElementById(videoPlayer); if (Hls.isSupported()) { const hls new Hls(); hls.loadSource(videoUrl); hls.attachMedia(video); } else if (video.canPlayType(application/vnd.apple.mpegurl)) { // Safari原生支持直接設(shè)置src video.src videoUrl; } }注意M3U8是分片文件所有.ts分片要和.m3u8索引文件放在同一個目錄下如果目錄結(jié)構(gòu)變了播放器會報錯。我踩坑的經(jīng)歷是把視頻文件按每年運(yùn)動會/每個項目分目錄存到MinIO里前端拼訪問URL時路徑一定要和上傳時的objectName完全一致。除了視頻MinIO還負(fù)責(zé)存運(yùn)動會橫幅圖、獲獎證書模板、運(yùn)動員頭像等靜態(tài)資源。這么做有兩個直接好處一是Spring Boot應(yīng)用不再處理靜態(tài)文件上傳的狀態(tài)無狀態(tài)服務(wù)更容易橫向擴(kuò)展二是MinIO自帶的預(yù)簽名URL功能可以控制文件訪問權(quán)限讓過期鏈接自動失效小規(guī)模內(nèi)部系統(tǒng)用著剛剛好。4. 前端Vue實操記錄4.1 路由設(shè)計與權(quán)限控制前端用Vue Router做頁面路由模式選的是createWebHistoryHTML5 History模式原因有兩點一是URL干凈不帶#號方便分享二是部署到Spring Boot里可以做轉(zhuǎn)發(fā)配置讓刷新頁面時不白屏。路由分兩部分登錄頁和管理后臺。管理后臺是一個嵌套路由父組件Layout.vue包含側(cè)邊欄菜單和頂部導(dǎo)航條子路由對應(yīng)各個業(yè)務(wù)模塊const routes [ { path: /login, component: Login }, { path: /, component: Layout, redirect: /dashboard, children: [ { path: dashboard, name: Dashboard, component: Dashboard }, { path: athletes, name: AthleteList, component: AthleteList }, { path: events, name: EventList, component: EventList }, { path: schedules, name: ScheduleList, component: ScheduleList }, { path: results, name: ResultEntry, component: ResultEntry }, { path: rankings, name: RankingBoard, component: RankingBoard } ] } ];權(quán)限控制核心是路由守衛(wèi)。我在router.beforeEach里檢查兩件事一是token是否存在不存在就跳登錄頁二是用戶角色是否有權(quán)限訪問當(dāng)前路由。角色的權(quán)限清單存在后端登錄時隨用戶信息一起返回前端用Pinia存一份。這里有個實際開發(fā)中經(jīng)常踩的坑動態(tài)路由。一開始我把所有菜單都寫死在前端后來不同角色看到的菜單不一樣只好在路由注冊時做動態(tài)過濾。Vue Router 4提供了addRoute方法可以根據(jù)當(dāng)前用戶角色動態(tài)掛載路由。但如果處理不當(dāng)退出登錄時動態(tài)路由不會自動清除換個賬號登錄還會看到上一個賬號的菜單。解決方案是登出時重置整個路由實例或者在注冊時保存一份原始路由表每次登錄根據(jù)角色從零開始重建。4.2 成績錄入表單與實時榜單成績錄入頁面是前端做起來最順手也最需要細(xì)致考慮的部分。裁判員在田徑場的烈日下錄成績手上可能還夾著紙質(zhì)檢錄表所以頁面的交互必須做到最少點擊、最大容錯。我的做法是選擇比賽項目后頁面自動加載該項目的所有參賽運(yùn)動員列表按組別和道次排好序。成績錄入?yún)^(qū)用表格形式每行一個運(yùn)動員徑賽錄入秒數(shù)帶兩位小數(shù)的輸入框田賽錄入三次試跳成績?nèi)齻€輸入框。輸入框的校驗規(guī)則是前端先校驗格式必須是數(shù)字、范圍在合理區(qū)間后端再校驗業(yè)務(wù)規(guī)則。表單里藏著兩個提高效率的細(xì)節(jié)鍵盤回車自動跳轉(zhuǎn)下一個輸入框。給輸入框加keyup.enter事件判斷當(dāng)前行/列位置后把焦點focus到下一個框。裁判錄完一個運(yùn)動員的成績回車就到下一格手都不用離開鍵盤。這個交互細(xì)節(jié)對大批量錄入體驗的提升比任何UI美化都管用。防誤觸的保存并繼續(xù)模式。錄完一組成績后點擊保存本組就把當(dāng)前組所有成績提交如果所有成績都合法就直接展示下一組不彈成功提示。這樣零打斷的操作流一場接力賽只需要不到兩分鐘就能錄完全部成績。實時榜單頁是Vue的強(qiáng)項用setInterval每5秒向后端拉一次團(tuán)體總分排行前端計算屬性驅(qū)動排行榜渲染。分?jǐn)?shù)變化的時候加一個簡單的CSS過渡效果數(shù)字滾動觀眾席大屏投影出來效果非常好。4.3 文件預(yù)覽與視頻播放的坑這個項目的文件資源包括上傳的比賽視頻、生成的獲獎證書PDF、運(yùn)動會的橫幅圖、運(yùn)動員照片。前端展示這些文件時有三組問題是我反復(fù)踩坑后沉淀下來的PDF預(yù)覽。直接用iframe加載PDF地址能預(yù)覽但EasyExcel生成的PDF文件名帶中文時部分瀏覽器會亂碼或打不開。解決方法是encodeURI編碼文件名或者在生成時就統(tǒng)一用英文文件名展示時再映射中文名。圖片不顯示。MinIO返回的圖片URL如果是預(yù)簽名URL鏈接里帶X-Amz-*參數(shù)直接放進(jìn)img src是能顯示的。但我遇到過一個問題有些圖片URL里的號會被瀏覽器解析成空格導(dǎo)致鏈接失效。排查了半天最后發(fā)現(xiàn)是URLEncoder編碼空格符號時用了而不是%20統(tǒng)一成%20后問題解決。視頻播放延遲。M3U8格式的視頻首次加載需要先請求索引文件、再按序加載各個.ts分片如果MinIO和瀏覽器之間網(wǎng)絡(luò)狀況一般首幀會出現(xiàn)3-5秒的緩沖。優(yōu)化手段是轉(zhuǎn)碼時把hls_time參數(shù)調(diào)大比如10秒一個分片減少分片數(shù)量另外可以在頁面加載時預(yù)連接MinIO端點用link relpreconnect提前建立連接。實測下來首幀時間能縮短到1秒左右體驗已經(jīng)可接受。5. 項目打包部署實戰(zhàn)5.1 方案一前后端分開部署推薦生產(chǎn)環(huán)境推薦前后端分開部署前端build后的靜態(tài)文件交給Nginx后端Spring Boot打包成jar獨立運(yùn)行。這樣做的最大好處是動靜分離——靜態(tài)資源由Nginx直接返回Tomcat只處理API請求壓力小很多另外前端更新時不需要重啟后端服務(wù)發(fā)版更快。前端部署步驟# 1. 構(gòu)建前端 npm run build # 2. 把dist目錄下的文件上傳到服務(wù)器 /var/www/sports-meet/ # 3. 配置Nginx反向代理Nginx配置的關(guān)鍵片段server { listen 80; server_name sports.example.edu.cn; # 前端靜態(tài)資源 location / { root /var/www/sports-meet; index index.html; try_files $uri $uri/ /index.html; # 解決前端路由刷新404 } # 后端API反向代理 location /api/ { proxy_pass http://localhost: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這一行。Vue Router開了HTML5 History模式后前端路由像/athletes、/rankings在刷新時Nginx會去找對應(yīng)的物理文件找不到就返回404。加上try_files $uri $uri/ /index.html后所有找不到的路徑都回退到index.html由前端路由接管問題解決。后端部署就簡單了Spring Boot項目用Maven打包mvn clean package -DskipTests java -jar target/sports-meet-0.0.1.jar --server.port80805.2 方案二Vue打包放進(jìn)Spring Boot單jar運(yùn)行有些場景下沒有獨立的Nginx環(huán)境或者就一臺小服務(wù)器不想多維護(hù)一個服務(wù)——這時可以把Vue打包后的dist目錄直接拷貝到Spring Boot項目的src/main/resources/static下重新打包成jar后端啟動后前端頁面和應(yīng)用接口都在同一個端口提供訪問。這個方案我在一個小型內(nèi)部系統(tǒng)上實測過跑通的前提是注意三個地方前后端路由的聯(lián)動。前端Vue Router用createWebHistory模式時訪問/athletes刷新會出現(xiàn)404因為Spring Boot默認(rèn)只映射了靜態(tài)資源沒有把未知路徑轉(zhuǎn)發(fā)到index.html。解決辦法是寫一個WebMvcConfigurer把非API路徑全部轉(zhuǎn)發(fā)到/index.htmlConfiguration public class WebConfig implements WebMvcConfigurer { Override public void addViewControllers(ViewControllerRegistry registry) { registry.addViewController(/{spring:\\w}) .setViewName(forward:/index.html); registry.addViewController(/**/{spring:\\w}) .setViewName(forward:/index.html); } }靜態(tài)資源路徑要用相對路徑。Vite默認(rèn)base是/打成jar后資源路徑如果帶絕對路徑在某些嵌入場景下會找不到。實測最穩(wěn)的方式是構(gòu)建時設(shè)置base: ./讓Vue打包出來的資源全部走相對路徑這樣不管jar部署在哪個端口都沒問題。上傳文件的存儲目錄要和jar包分離。用java -jar運(yùn)行時當(dāng)前工作目錄是jar所在目錄如果文件上傳路徑寫成相對路徑每次升級jar包時很容易把上傳的老數(shù)據(jù)覆蓋掉。我是把上傳路徑配置成絕對路徑/data/sports-meet/upload在jar外面獨立管理這樣jar升級完全不影響已有文件。5.3 MySQL初始化與數(shù)據(jù)遷移數(shù)據(jù)庫部分我用MySQL 8.0項目里配了Flyway做數(shù)據(jù)庫版本管理。每次表結(jié)構(gòu)變更寫一個新的V{n}__{description}.sql遷移腳本spring.flyway.enabledtrue應(yīng)用啟動時自動執(zhí)行增量遷移。這個習(xí)慣幫我避免了好幾次測試環(huán)境加了字段、生產(chǎn)環(huán)境忘了加的慘劇。初始化數(shù)據(jù)用data.sqlFlyway的R__前綴文件可以重復(fù)執(zhí)行把學(xué)院名單、默認(rèn)管理員賬號、比賽項目模板100米、200米、跳遠(yuǎn)、鉛球等寫進(jìn)去。新一屆運(yùn)動會開賽前管理員不需要從頭配置基礎(chǔ)數(shù)據(jù)只要把報名數(shù)據(jù)導(dǎo)入就行。6. 常見問題與排查實錄6.1 開發(fā)環(huán)境的高頻坑這個項目開發(fā)過程中我記錄了不少典型問題挑幾個最有代表性的整理成表問題現(xiàn)象根本原因解決方案前端請求后端接口報跨域錯誤Vite開發(fā)服務(wù)器5173端口和后端8080端口不同源開發(fā)環(huán)境用Vite代理server.proxy轉(zhuǎn)發(fā)/api到localhost:8080生產(chǎn)環(huán)境靠Nginx天然同源上傳大視頻文件時Netty報內(nèi)存溢出MinIO客戶端寫入時未分片處理后端用FileInputStream分段流傳給MinIO不用MultipartFile一次性讀入內(nèi)存同時調(diào)大server.tomcat.max-swallow-size和spring.servlet.multipart.max-file-sizeVue打包后運(yùn)行時白屏路由模式用了history但服務(wù)器未配fallback按方案一配Nginx的try_files或按方案二走WebMvcConfigurer轉(zhuǎn)發(fā)刷新頁面返回404同上同上表格導(dǎo)出中文亂碼POI生成Excel時未設(shè)置XSSFWorkbook的字符集設(shè)置wb.setCharset或統(tǒng)一用UTF-8 BOM格式輸出CSV/ExcelSpring Boot版本和JDK版本不匹配導(dǎo)致啟動失敗Spring Boot 3.x強(qiáng)制JDK17而項目用了JDK8要么升JDK要么降級Spring Boot 2.7.x基于javax而非jakarta命名空間6.2 數(shù)據(jù)與權(quán)限類問題的獨家排查技巧并發(fā)報名沖突。運(yùn)動會報名開放當(dāng)天幾百個學(xué)生同時在線報名出現(xiàn)過同一運(yùn)動員重復(fù)報名同一項目的臟數(shù)據(jù)。排查后發(fā)現(xiàn)是前后端校驗只做了一端兩個請求同時進(jìn)來都通過了校驗。解決方式是在數(shù)據(jù)庫層面加唯一約束UNIQUE(athlete_id, event_id)從根上防止重復(fù)再用后端的select ... for update行鎖保護(hù)報名流程的并發(fā)更新。操作日志排查。系統(tǒng)上線后出現(xiàn)過一個成績被修改但查不到是誰改的問題。當(dāng)時所有成績更新操作只記錄更新后的值沒有記錄舊值。后來我在成績更新接口里強(qiáng)制附加了舊值快照日志格式是舊成績-新成績操作人操作時間。排查問題時一眼就能看到數(shù)據(jù)變化的前因后果。建議所有涉及關(guān)鍵數(shù)據(jù)的更新操作都記錄完整審計日志這個習(xí)慣關(guān)鍵時刻能救你命。JWT過期引發(fā)的會話混亂。JWT token設(shè)有2小時有效期裁判錄成績錄到一半token過期前端請求返回401但頁面沒有任何提示裁判以為系統(tǒng)卡了白錄的成績?nèi)珌G了。解決方案兩個一是在Axios攔截器里統(tǒng)一處理401響應(yīng)彈出提示并跳轉(zhuǎn)登錄頁二是給token加靜默續(xù)期機(jī)制——每次API請求返回時帶上新的token前端取下更新本地存儲讓長時間在線的裁判不會被迫中間重新登錄。成績錄入精度問題。徑賽成績手動輸入時出現(xiàn)過11.5被自動糾正為11.50但排名時發(fā)現(xiàn)11.5和11.50被當(dāng)成了不同數(shù)值。排查后才知道問題出在JSON序列化前端傳字符串11.5后端BigDecimal正常存儲但傳給Double字段做比較時丟失了精度。最終方案是所有成績字段統(tǒng)一用BigDecimal存儲比較用compareTo而不是equals問題根治。6.3 性能優(yōu)化實測運(yùn)動會當(dāng)天是系統(tǒng)壓力最大的時刻檢錄查詢、成績錄入、榜單刷新三線并發(fā)高峰期QPS可能到幾百。我做的性能優(yōu)化有三個實測有效的點數(shù)據(jù)庫層面查詢最頻繁的排名查詢和報名狀態(tài)查詢涉及的字段全部加了聯(lián)合索引比如(event_id, status)、(athlete_id, event_id)慢查詢?nèi)罩纠镌?00ms的查詢降到20ms以內(nèi)。Redis緩存團(tuán)體總分排行和項目報名人數(shù)這類讀多寫少的數(shù)據(jù)用Redis做緩存設(shè)置30秒過期。排名算法計算完成后寫入緩存前端定時輪詢的接口直接讀緩存數(shù)據(jù)庫壓力大幅下降。異步化PDF證書批量生成是典型耗時操作我改成MQ異步任務(wù)前端點生成全員證書后返回生成中提示后端線程池異步處理完成后前端能看到生成結(jié)果列表。運(yùn)動會現(xiàn)場沒有人愿意為生成1000張證書等半分鐘的頁面轉(zhuǎn)圈。最后再分享一個我做這類校園管理系統(tǒng)的心得功能做成什么樣取決于誰在用。運(yùn)動會系統(tǒng)的管理員是體育部的老師裁判是學(xué)生志愿者我一開始把界面做得功能豐富、選項很多實際使用后收到最多的反饋是太復(fù)雜了我就想錄入成績。后來我專門開了簡化模式裁判登錄后默認(rèn)直達(dá)成績錄入頁所有無關(guān)菜單都隱藏能一鍵完成的絕不兩步。系統(tǒng)最終好不好用不是看功能全不全而是看最核心的那條操作鏈路順不順。這個項目的所有設(shè)計都該圍繞這個原則來取舍。