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