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