SpringBoot+Vue+MyBatis+MySQL评分管理系统设计与全栈实战解析

说实话，这几年我手里过了一遍又一遍的全栈管理系统项目里，“健美操评分系统”这类赛事评分加信息管理的组合，是最容易被低估、又最有代表性的。看起来只是个打分界面加成绩表，实际上它把赛事管理、队伍报名、多裁判打分、去极值合分、排名展示这些环节全串在了一起，技术栈又恰好是国内中小型Web项目最常见的SpringBoot+Vue+MyBatis+MySQL组合。如果你手头正好有一份这样的项目源码，想弄懂它是怎么设计的、怎么跑起来的、怎么改造成自己的东西，那这篇就是给你写的。

这套系统能做的事情很直接：比赛前管理员建赛事、录队伍、分配裁判；比赛过程中裁判登录后给每支队伍逐项打分；比赛结束后系统自动去掉最高最低分、按规则加权汇总，生成排名榜单。适合看的读者也很明确，一是正在做毕设想找项目练手的计算机专业学生，二是刚学完SSM和Vue想搞懂一个完整全栈项目如何协同工作的新手，三是接到类似“评分系统”“赛事管理系统”需求需要快速套模板的开发者。

1. 项目整体设计与思路拆解

1.1 题目背后的真实需求

很多人拿到这类源码第一反应是问“健美操评分和别的评分有什么区别”，我的答案是业务规则不同，但系统骨架高度相似。评分系统最大的难点从来不是写个打分页面，而是把人类的规则翻译成数据库字段和计算逻辑。

健美操比赛的评分通常分几个维度，常见的是艺术分、完成分、难度分，每个维度满分可能都是10分，最后总分按权重合并。而每支队伍可能面对5个甚至7个裁判，裁判打分有主观性，所以规则里通常有一条硬性要求：去掉一个最高分、去掉一个最低分，剩下的裁判分数取平均作为该维度得分，最后再按权重合成总分。这个“去极值合分”的动作如果靠人工算，一场比赛几十支队伍、上百个打分记录，非常容易出错，系统要解决的核心痛点就在这里。

围绕这个核心，系统还需要回答一连串管理问题：参赛队伍信息从哪里录入？裁判账号由谁分配？同一裁判能不能给同一支队伍重复打分？成绩发布之后教练在哪里看排名？管理员能不能对打错的分进行修正？把这些需求理清之后，功能模块基本就出来了。

1.2 技术选型为什么是这四件套

SpringBoot+Vue+MyBatis+MySQL这个组合，可以说是当下国内中小型管理系统最“稳”的一套方案，稳的意思是学习成本低、资料多、招人容易、踩坑方案全网都有。

拿后端来说，把SpringBoot和传统SSM放在一起比较就能看出来，SpringBoot把SpringMVC、Tomcat、Jackson等组件的配置自动完成了，你不需要写一堆XML配置文件，动辄几十个依赖的版本冲突问题也被Spring Boot的依赖管理统一缓解。做评分系统这种业务不算复杂的项目，启动类一写，Controller、Service、Mapper三层一搭，开发效率非常高。

前端选Vue而不是React，核心原因是Vue的模板语法对“从后端拿数据、把数据渲染到表格里”这件事更直观。评分管理系统的页面大多是表单、表格、下拉框这类中后台界面，Vue全家桶加上Element UI一类的组件库基本开箱即用。而React的上手曲线稍微陡一些，对新手不够友好。

MyBatis和JPA之争也很有意思。JPA确实开发快，但对SQL的控制力弱，遇到多表关联、复杂查询时经常需要在注解里拼JPQL。评分系统里有一类典型需求叫“按赛事查每支队伍的有效均分”，这种SQL用MyBatis写在XML里一目了然，后期优化也知道去哪改。

MySQL就更不用说了，开源免费、生态庞大，5.7和8.0版本在中小型系统里性能都绰绰有余。整套选型思路其实就是：在保证可维护性的前提下，选资料最丰富、最不容易卡住人的技术栈。

1.3 系统模块设计与角色边界

这套系统里有三类角色比较典型，管理员、裁判、普通浏览者，角色直接决定菜单和权限。

管理员负责的事最多：创建赛事、设置赛事状态（未开始、进行中、已结束）、维护参赛队伍信息、创建裁判账号并绑定到赛事、查看最终成绩、对异常分数进行修正。裁判的职责非常收敛，就是“选队伍、打分、提交”，系统要确保他只能打一次，而且只能打自己负责的赛事。普通用户或者访客更简单，按赛事查看实时排名和成绩单，不需要登录也能看。

模块设计上，我是强烈建议按“赛事维度”组织所有功能，因为评分系统所有数据都依附于某一场赛事。如果一开始把表结构设计成没有赛事外键的松散结构，后面做“历史赛事对比”“导出某届比赛成绩单”时就会到处补代码。想让代码干净，核心原则是：用户表管账号和角色，赛事表管比赛生命周期，队伍表挂在赛事下面，评分表同时关联队伍和裁判，排名不落表而是通过SQL实时算。

2. 核心业务与数据库设计

2.1 评分规则如何落到字段

设计数据库之前，先要把评分规则完全量化。我在这里用一个示例规则做说明，真实项目里的具体权重和去极值方式一定以主办方规则为准，但落库思路是一样的。

假设每项满分10分，三位裁判分别打出如下原始分：9.2、9.5、9.0；去掉最高9.5和最低9.0后，剩下的9.2就是该维度得分。如果裁判人数更多，比如7个人，去掉一个最高和一个最低，剩余5人取平均。这个规则不只用于某一个维度，艺术分、完成分、难度分都要分别这样处理后，再乘上各自的权重系数，得到总分。

落到代码里，这个逻辑应该放在Service层而不是Controller层，因为Controller只负责接收请求，真正的业务规则要集中在Service中，方便复用和测试。而这个逻辑最忌讳写在前端JavaScript里，因为前端任何人都可以篡改分数计算，最终成绩必须以服务端计算为准。这个原则在实际项目中踩过太多次，记住了能帮你省很多事。

2.2 数据库表结构设计细节

针对这套系统，五张核心表基本够用：用户表、赛事表、参赛队伍表、裁判分配表、评分表，另外可以加一张成绩汇总表用于报表导出，或者直接用视图解决。下面是一张表设计概览：

评分表是整个系统的关键，它的唯一索引设计尤为重要。通常裁判给一支队伍只允许提交一次分数，那么唯一索引可以建立在(team_id, judge_id)上，如果比赛是多人分组、多轮次，就把event_id加进索引。这样即便后端漏写了判重逻辑，数据库这一层也能兜底。

需要注意score表里的维度字段尽量用decimal类型，比如decimal(3,1)，既支持9.5这样的小数，又不会出现9.55这种超出规则精度的数据。创建时间和修改时间建议由数据库自动维护，default值设为CURRENT_TIMESTAMP，避免每写一条SQL都要手动填时间。

2.3 前后端交互的数据结构约定

前后端分离开发最怕各写各的，尤其是接口返回格式不统一，前端每次都要判断一堆乱七八糟的结构。这套系统里统一接口返回格式是第一个要定的约定。

我习惯定义Result类，里面三个字段：code、message、data。成功时code为200，业务异常时code为500，未登录或权限不足时code为401或403。前端axios拦截器拿到响应后只判断code，不是200就全局弹出错误提示，这样所有页面都有统一反馈。

分页参数也建议做个规范，后端接收pageNum和pageSize两个参数，返回结构固定为PageResult，包含total、list、pageNum、pageSize字段。前端表格组件直接绑定这两个字段即可。时间和金额是两类最容易出格式问题的字段，时间统一传时间戳或者yyyy-MM-dd HH:mm:ss格式的字符串，防止不同浏览器对时间解析不一致。

3. 实操过程与核心环节实现

3.1 环境要求与启动顺序

先把项目跑起来比什么都重要。这套系统典型的环境要求是：JDK 8以上、Maven 3.6以上、Node.js 14以上、MySQL 5.7或8.0，Vue项目如果用的Vite，Node版本建议16以上。

启动顺序我建议按“数据库→后端→前端”走。第一步创建数据库，把项目里带的SQL脚本导入，通常命名为aerobic_score.sql或类似的文件名。导入前注意MySQL的字符集要设置为utf8mb4，不然遇到生僻汉字或特殊符号会乱码。第二步打开后端的application.yml文件，把数据库地址、用户名、密码改成自己本机的，这一步漏改是初学者报错最多的地方。第三步在后端目录执行mvn spring-boot:run，看到Tomcat started on port 8080就说明后端起来了。第四步打开前端目录，依次执行npm install和npm run serve，等编译完成提示Local访问地址即可。

还有一点要注意，前后端端口要分开，后端默认8080，前端Vue默认8081或者5173，别用一个端口。如果改了后端端口，前端的接口请求地址也要对应改。

3.2 后端核心代码解析

后端目录结构是标准的三层分包：controller、service、mapper、entity加上config。Controller层的代码非常薄，只做参数接收和结果封装，业务逻辑全部下沉到Service。

先看统一返回体：

public class Result<T> { private Integer code; private String message; private T data; public static <T> Result<T> ok(T data) { Result<T> result = new Result<>(); result.setCode(200); result.setMessage("success"); result.setData(data); return result; } public static <T> Result<T> error(String message) { Result<T> result = new Result<>(); result.setCode(500); result.setMessage(message); return result; } }

这一段代码虽然简单，却是整个前后端协作的基石。所有Controller方法最后都返回Result类型，前端逻辑就能统一处理。

Service层的评分计算是核心中的核心，里面有一个去掉最高最低分的实现：

@Override public Double calcEffectiveScore(List<Double> rawScores) { if (rawScores == null || rawScores.size() < 3) { throw new BusinessException("有效裁判人数不足，无法计算"); } List<Double> sorted = rawScores.stream().sorted().collect(Collectors.toList()); sorted.remove(0); sorted.remove(sorted.size() - 1); double avg = sorted.stream().mapToDouble(Double::doubleValue).average().orElse(0); return BigDecimal.valueOf(avg).setScale(2, RoundingMode.HALF_UP).doubleValue(); }

这个方法有几个容易忽略的细节。第一是必须先排序再移除首尾元素，如果不排序直接remove(0)和remove(size-1)，一个数组越界，一个移除错了元素。第二是判空要放在最前面，否则空列表直接抛异常。第三是保留两位小数用RoundingMode.HALF_UP，进行四舍五入，避免浮点数精度问题。

Mapper层用MyBatis的XML写SQL，评分表插入建议写成MySQL的INSERT ON DUPLICATE KEY UPDATE形式，和数据库唯一索引配合后可以实现“重复打分自动覆盖更新”：

<insert id="insertOrUpdate" parameterType="Score"> INSERT INTO score(event_id, team_id, judge_id, artistry, completion, difficulty) VALUES(#{eventId}, #{teamId}, #{judgeId}, #{artistry}, #{completion}, #{difficulty}) ON DUPLICATE KEY UPDATE artistry = VALUES(artistry), completion = VALUES(completion), difficulty = VALUES(difficulty) </insert>

注意这个写法依赖(team_id, judge_id)的唯一索引，没有索引这个功能不生效。有了这段代码，裁判重复提交时不用先查一遍再决定插入还是更新，数据库自动处理，性能和代码简洁度都提升不少。

3.3 前端核心代码解析

Vue项目的目录结构一般是api、router、views、components、utils这几个。api目录用来统一管理所有请求，router目录定义路由和菜单权限，views目录按页面模块放视图组件。

axios封装这一步特别重要，我用一个request.js文件处理公共逻辑：

import axios from 'axios' import { ElMessage } from 'element-plus' const request = axios.create({ baseURL: '/api', timeout: 10000 }) request.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers.Authorization = token } return config }) request.interceptors.response.use( response => { const res = response.data if (res.code !== 200) { ElMessage.error(res.message) return Promise.reject(new Error(res.message)) } return res.data }, error => { ElMessage.error('网络请求失败') return Promise.reject(error) } ) export default request

这里的baseURL写成/api不是后端完整地址，是因为开发环境用了Vite的proxy代理，生产环境用Nginx转发。这种写法让前端代码里不出现具体IP和端口，换环境只需要改代理配置。

打分页面的表单绑定很直接，每支队伍一行，三个维度分数用数字输入框：

<el-table :data="teamList"> <el-table-column prop="teamName" label="参赛队伍" /> <el-table-column label="艺术分"> <template #default="{ row }"> <el-input-number v-model="row.artistry" :min="0" :max="10" :step="0.1" /> </template> </el-table-column> <el-table-column label="完成分"> <template #default="{ row }"> <el-input-number v-model="row.completion" :min="0" :max="10" :step="0.1" /> </template> </el-table-column> </el-table>

v-model绑定行对象字段，用户改分数时数据即时同步，点提交后把整个表格数组一次性传给后端。

前端也可以做一个实时预览计算，方便裁判提交前心里有数：

calcPreview(scores) { const list = [...scores].sort((a, b) => a - b) list.shift() list.pop() const total = list.reduce((sum, n) => sum + n, 0) return (total / list.length).toFixed(2) }

这个预览只是给用户看的，后端会重新计算最终成绩，前端的展示不需要成为权威结果。

3.4 评分计算逻辑的权重合成

维度分数算完后，总分合成是另一个容易出坑的地方。假设规则是总分等于艺术分乘0.2加上完成分乘0.5加上难度分乘0.3，那么合成代码要放在事务里统一计算。

@Transactional(rollbackFor = Exception.class) public void publishEventScores(Long eventId) { List<Team> teams = teamMapper.selectByEventId(eventId); for (Team team : teams) { ScoreAggregate agg = scoreMapper.getEffectiveScores(eventId, team.getId()); double total = BigDecimal.valueOf(agg.getArtistry()) .multiply(BigDecimal.valueOf(0.2)) .add(BigDecimal.valueOf(agg.getCompletion()).multiply(BigDecimal.valueOf(0.5))) .add(BigDecimal.valueOf(agg.getDifficulty()).multiply(BigDecimal.valueOf(0.3))) .setScale(2, RoundingMode.HALF_UP) .doubleValue(); teamMapper.updateScore(team.getId(), total); } }

加@Transactional的意义在于：如果计算到第三支队伍时报错，前两支队伍的成绩不应该部分更新，否则赛事成绩会处于一个“一半新一半旧”的脏状态。类似的场景还有管理员修改某位裁判的分数后，该队伍总分必须同步重算，不能只改评分表不改排名数据。

这里的getEffectiveScores对应的SQL是评分系统里最核心的一条，它的逻辑是“按队伍分组，每个维度去掉最高最低再取平均”。MyBatis里可以写成：

<select id="getEffectiveScores" resultType="ScoreAggregate"> SELECT AVG(artistry) AS artistry, AVG(completion) AS completion, AVG(difficulty) AS difficulty FROM ( SELECT artistry, completion, difficulty FROM score WHERE event_id = #{eventId} AND team_id = #{teamId} ORDER BY artistry DESC LIMIT 99999 ) </select>

上面这个只是简化示例，真正去掉最高最低要写窗口函数或子查询分组过滤，MySQL 8.0支持窗口函数后可以用ROW_NUMBER()实现。实际项目里建议先查全部明细再在Java里过滤，虽然多一次数据库交互，但代码更清晰可控，评分记录量级下性能完全没有压力。

4. 常见问题与排查技巧实录

4.1 数据库连接与驱动版本

评分系统接到新机器上第一个卡点基本都在数据库连接。如果是MySQL 8.0，驱动类名要写成com.mysql.cj.jdbc.Driver，而不是旧版com.mysql.jdbc.Driver，两个驱动在8.x里都能用但会出现警告。

时区问题紧随其后，报错The server time zone value is unrecognized是最典型的情况，需要在连接URL后面加参数：

url: jdbc:mysql://localhost:3306/aerobic?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true

allowPublicKeyRetrieval=true很多新手不知道，这个不加在MySQL 8.0下会报Public Key Retrieval is not allowed，尤其用Navicat连不上时更容易在这里翻车。严格来说生产环境不建议一直开着allowPublicKeyRetrieval，但本地开发测试开起来最省事。

4.2 MyBatis映射与Mapper绑定

MyBatis最常见的报错是Invalid bound statement，意思是接口方法找不到对应的SQL语句。原因基本有三种：XML文件没有放在和Mapper接口同包同名目录下；XML里的namespace写错；配置里没有加mapper-locations指向XML目录。三个问题逐个排除基本都能解决。

数据库字段下划线和Java实体驼峰不一致也是高频问题。数据库字段arts_score，实体属性artsScore，如果MyBatis配置没打开驼峰映射，查询结果全是null。在application.yml里加一行配置即可：

mybatis: configuration: map-underscore-to-camel-case: true

这行配置加上后，arts_score自动映射到artsScore，省去写resultMap的工作量。

4.3 Vue跨域与接口404

前端访问后端接口报“Access to XMLHttpRequest has been blocked by CORS policy”，多半是跨域配置不到位。开发阶段最简单的方式是配置Vue项目的代理。Vite项目在vite.config.js里写：

server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }

后端也可以加一个CORS配置类作为双保险：

@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(Registry registry) { registry.addMapping("/**") .allowedOriginPatterns("*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowedHeaders("*") .allowCredentials(true); } }

注意allowCredentials(true)和allowedOriginPatterns("")要配合使用，如果允许携带Cookie就不能简单写allowedOrigins("")，这是很多报错 SEC7128 的来源。

如果前端页面能打开但接口全404，先检查后端Controller的@RequestMapping路径和前端baseURL路径有没有重复拼写，比如后端是/api/score，前端baseURL又写了/api，最后请求变成/api/api/score，这是很容易犯的低级错误。

4.4 端口冲突与打包含前端

后端端口8080被占用时的解决方式很简单，先查端口再换端口。Windows命令netstat -ano | findstr 8080可以找出占用进程的PID，Linux用lsof -i:8080。确定占用进程不是必要服务后，杀掉或者在后端配置里换端口。

但换端口只是第一步，前端页面里的代理target也要同步换，否则页面能开但还是请求不通。这点经常被忽略，常常排查半天发现是前后端连的端口不是同一个。

上线部署时，如果想用一个SpringBoot包解决所有问题，可以前端先执行npm run build，把dist目录里的静态文件复制到后端的src/main/resources/static下，然后重新打包。这种方式确实简单，但注意Vue路由如果用的history模式，刷新页面会出现404，解决方法是改用hash模式，或者在SpringBoot里配置forward到index.html。个人项目图省事就用hash模式，功能和体验差别不大。

4.5 成绩合算的隐藏坑

评分系统最深的坑在合算逻辑里，常见的有这么几类。

第一类是同一裁判重复打分导致数据翻倍，因为早期没加唯一索引，测试时多点了几次提交按钮，平均分被拉低。遇到这种情况先看score表里有没有(team_id, judge_id)重复记录，有就清掉然后补上唯一索引。

第二类是去极值的边界情况。如果只有两个裁判打了一条记录，去掉最高最低后数组为空，除零直接报错。所以Service里判空条件要写rawScores.size() < 3就直接抛业务异常，提示“至少需要3名裁判打分”。

第三类是加权平均的错误写法。有人在SQL里直接AVG(artistry + completion + difficulty)，这个写法会把三个维度混在一起求平均，而不是先各自求平均再加权，最终结果完全不对。正确做法一定是先按维度分别计算有效均分，再乘对应的权重系数。

第四类是精度问题。总分计算时如果用double反复乘加，容易出现8.550000000000001这种结果。稳妥做法是用BigDecimal进行乘法，中间结果保留4位小数，最后结果保留2位。这和金额计算的思路完全一致，但很多人写业务代码时不会把金融系统的精度意识带到评分系统里。

我再补一个排查合算问题的实用技巧：准备一组已知预期结果的手工数据，比如给三个裁判固定打9.0、9.5、9.2，预期有效均分9.2，加权总分按规则算好，然后写一个单元测试来验证。评分规则改一次，单元测试跑一次，比任何人工复核都靠谱。这个习惯看着麻烦，但在排名发布后发现集体算错的那一瞬间，你会庆幸当时写了这个测试。

写在后面的一点个人体会

每年看这类项目源码，我最深的感受是：评分系统的成败不在界面好不好看，而在业务边界和处理规则的严谨程度。数据库唯一索引、Service层事务、BigDecimal精度、统一返回格式，这些看似基础的点位，任何一个没做好，上线后都会变成事故。我把这些细节一点点拆出来写在这里，就是希望你能跳开“我要有个能跑的项目”这个层面，去想清楚每一行代码背后的约束条件。

如果你想把这个项目变成自己的作品，建议按这个顺序动手：先改包名和后端项目名，去掉原作者的痕迹；再登录账号走一遍管理员建赛事、裁判打分、查看排名的全流程，故意制造几个边界情况看看系统能不能扛住；然后增加数据导出功能，用EasyExcel把成绩单导出成Excel；最后把排行榜页面加上ECharts图表，展示各队伍分数趋势。做完这四步，这个项目的代码就真正长在你脑子里了，答辩或者面试时随便一个问题都能答出所以然来。