竞赛组队这件事，被很多人低估了。我印象里有个场景特别深：校内ACM选拔赛报名截止前三天，群里全是“还缺一个后端”“有会算法的队友吗”这类刷屏消息，真正合适的人反而被信息洪流淹没。后来我带毕业设计时选了这个题目——基于Spring Boot的竞赛团队组建与管理系统，整个过程做下来最大的体会是：这玩意儿不是简单搭个CRUD，而是要同时处理“赛事生命周期、团队招募匹配、成员审批、角色权限”这四条业务线。把一个典型的管理系统做成真正能落地的小平台，里面可以挖的细节非常多。
这篇东西我会从需求拆解、技术选型、数据库设计、核心接口实现一直讲到部署上线后踩过的坑。适合正在做Spring Boot课程设计、毕业设计的同学，也适合想在校内搞一个竞赛组队小平台的开发者参考。不管你是刚接触Spring Boot四层架构，还是已经能用MyBatis-Plus写增删改查，这篇文章都会给你一些从“能跑”到“好用”的进阶思路。
1. 项目到底在解决什么问题
1.1 竞赛组队为什么不能靠微信群
很多人觉得做个组队系统多此一举，线下喊一喊不就行了。但真实场景里有两个痛点很难靠人工解决：一个是信息不对称，有人想找数据分析的队友但只在班级群说了一嘴，外专业的人根本看不到；另一个是流程不可控，团队满员后有人中途退出，该走什么流程补人，队长和赛事管理员经常扯皮。
这个问题拆开看，本质上是“赛事信息发布—团队组建—成员审核—过程管理”这条链路缺一个线上化载体。系统要做的不是替代人与人之间的沟通，而是把沟通前的那段信息匹配和流程审批标准化。这样赛事管理员能一眼看到每个赛事的报名进度，队长能公开招募也能定向邀请，学生能按技能标签筛选队伍，所有操作都有记录。
1.2 系统边界与角色划分
我最初犯过一个典型错误，就是把系统设计得特别大，恨不得把在线文档、消息聊天、日程安排全塞进去。后来被老师一句话点醒：毕设也好，校内平台也好，核心价值是把“组队”这个动作做透，而不是重新造一个办公套件。
最终我把角色收敛成三类：赛事管理员、队长（团队创建者）、普通学生（参赛者）。管理员维护赛事信息和审核团队成立申请；队长可以创建团队、发布招募令、审批加入申请；学生可以浏览赛事、报名赛事、申请加入团队、查看自己的组队状态。系统边界一旦清晰，后续所有的表结构和接口设计都顺了。
2. 技术选型：为什么是Spring Boot全家桶
2.1 Spring Boot在四层架构里的定位
选型时没有太多纠结，后端框架基本就是Spring Boot。它的价值不只是“简化配置”这四个字，而是把Spring生态里那些成熟组件像积木一样拼起来。我们习惯说的四层架构，其实是指Controller、Service、Mapper/Repository、数据库这四层，Spring Boot在整个体系里充当“胶水容器”的角色。
Controller层只负责参数接收和响应封装，Service层放业务规则，Mapper层做持久化，DTO用来隔离实体类和前端字段。这种分层让每个类的职责非常单一。比如申请加入团队这个操作，Controller只要校验当前登录用户是谁、传进来的是哪个团队ID，真正判断团队是否满员、用户是否重复申请的逻辑全部在Service层完成，方便做单元测试，也方便以后换前端不用动后端核心代码。
2.2 持久层选型：MyBatis-Plus还是JPA
持久层我推荐MyBatis-Plus，尤其适合国内这种以SQL思维为主的团队。MyBatis-Plus提供了BaseMapper的通用方法，单表CRUD基本不用手写XML，但真正复杂的多表查询和统计报表，又能回到XML里手写SQL，灵活度比JPA高很多。
JPA不是不好，它的Hibernate自动建表能力确实快，但遇到动态条件查询和关联查询优化时，要么写JPQL要么写原生SQL，调试成本反而上去了。MyBatis-Plus还有一个实际好处是代码生成器，可以从数据库表反向生成Entity、Mapper、Service、Controller，对刚开始写Spring Boot的人非常友好，能把精力集中在核心业务逻辑上。
2.3 认证与授权方案
竞赛系统有两个天然的权限痛点：一是不同角色能做的事完全不一样，二是团队内部还有队长和普通成员的区别。我用的是Spring Security + JWT的组合，没有引入太复杂的OAuth2。登录接口校验用户名密码后签发JWT，前端在请求头里带上token，后端通过拦截器解析用户身份并存入ThreadLocal。
权限控制上，基于注解的方法级校验就够用，比如管理员接口统一加@PreAuthorize("hasRole('ADMIN')")，队长操作团队资源时再校验当前用户是否是队长。这种方案实现简单、部署方便，接口文档里也能表达得很清楚，足够覆盖一个校内竞赛平台的安全需求。
2.4 前端方案与接口设计
前端我选了Vue3 + Element Plus，原因是Element Plus的表格、表单、标签输入框非常适合管理类页面。前后端分离后，接口设计就变得格外重要。我给自己定了一条原则：所有接口返回统一JSON结构，包含code、message和data三个字段。code为0代表成功，其他值对应不同错误码。
例如创建团队的接口路径是POST /api/teams，申请加入是POST /api/teams/{teamId}/applications，审批申请是PUT /api/applications/{id}/audit。路径里尽量用名词，操作通过HTTP方法表达，这样写出来的接口天然符合REST风格。为了避免不同错误场景产生歧义，我还定义了全局异常处理器，任何Service抛出的业务异常都能被转成结构化的JSON返回给前端，而不是给出一堆堆栈信息。
3. 核心功能设计与实现细节
3.1 用户管理与注册登录
用户的注册登录是最典型的Spring Boot入门模块，但细节决定体验。我除了常规的学号、姓名、密码、邮箱之外，还加了一个“技能标签”字段，允许用户勾选“后端开发/算法/UI设计/PPT答辩/数据处理”等标签，这些标签会直接参与组队推荐的匹配计算。
密码存储一定要用BCrypt加密，绝对不要存明文。注册时校验学号唯一性，邮箱格式和手机号也要做基础校验。登录成功生成JWT后，我同时把用户的基础信息和技能标签写进Redis缓存，这样查询“我是谁”和“我的标签”时不用每次查数据库。整块模块没有太多炫技的地方，但它是所有其他功能的基础。
3.2 赛事管理的完整生命周期
赛事是整个系统的主线，我设计的状态机是：草稿、报名中、组队中、进行中、已结束。管理员创建赛事时填写赛事名称、级别（国家级/省级/校级）、报名开始时间、报名截止时间、比赛时间、赛事说明等。
状态机不是摆设，它约束了很多业务操作的合法性。比如只有“报名中”和“组队中”状态的赛事，才允许学生创建团队；只有“组队中”状态的赛事，才允许队伍继续招人。实现方式不复杂，赛事的每个状态变化都走Service层封装好的方法，比如publishEvent()、startTeamPhase()、finishEvent()，这些方法内部先校验当前状态，再更新数据库并记录状态变更日志。
3.3 团队组建的核心流程
这部分是整个系统业务逻辑最重的地方。团队组建涉及三条子流程：队长创建团队、队长发布招募信息、其他学生申请加入。创建团队时，队长要指定所属赛事，填写团队名称和团队介绍。这里必须校验两个硬性条件：该赛事是否允许创建团队，以及队长当前是否已经有未解散的团队，避免一个人在同一赛事里开多个队。
招募信息其实就是给团队打标签，比如“需要两名后端开发，一名会写商业计划书”。系统维护一个“需求标签”表，每条需求关联团队ID和技能标签。学生端在浏览团队列表时，可以根据自己掌握的标签进行筛选，显示“匹配度”。这个匹配度我用了最简单的做法：把学生的标签集合和团队需求标签集合取交集，重叠数量除以团队需求总数，得到0到1之间的分数，按分数倒序展示。
申请加入流程要走审批而不是直接加入，因为组队是双向选择。学生提交申请，填写自己的项目经历和团队角色意向，队长在“申请列表”里决定通过还是拒绝。一旦通过，团队人数加一，当人数达到赛事要求的团队人数上限时，团队状态自动变为“已满员”，停止接收新申请。
3.4 通知机制与消息中心
系统如果只有审批动作，缺少触达提醒，用户很快会忘记回来。我实现了一个轻量的站内信通知模块，不依赖消息队列。每当有新的申请加入、申请通过、赛事状态变更时，System会往相关用户的消息表插入一条记录，并同时通过WebSocket给在线用户推送一个未读数量变化事件。
前端在顶栏显示未读消息数，点击后进入消息列表，已读和未读用红点区分。这个模块在技术上不复杂，但产品体验上很关键。Spring Boot实现WebSocket也不需要额外引入第三方框架，用spring-boot-starter-websocket即可，关键在于会话管理要跟用户ID绑定，而不是跟随机session绑定。
3.5 数据统计与排行榜
竞赛平台做到后面，管理端一定需要数据看板。我用统计接口+前端图表的方式实现：管理员首页展示总的赛事数量、注册学生数、组队成功数、各类竞赛级别的占比图。这部分对SQL能力是个不小的考验，典型的需求有“每个赛事创建的团队数排行榜”“热门技能标签Top10”。
热门技能标签是从需求标签表里GROUP BY后按次数倒序取前10。这个统计一旦上场，会让整个系统显得专业很多，也方便管理层了解学生更偏向哪些赛道。
4. 数据库设计与编码实战
4.1 核心表结构设计
数据库我用MySQL 8.0，字符集utf8mb4。核心表一共八张：用户表、赛事表、团队表、团队成员表、加入申请表、需求标签表、通知消息表、评审表（用于记录队伍获奖信息，给后续扩展留空间）。
以团队表和申请表的建表语句为例，团队表一定要冗余赛事ID和队长ID，并加合适的索引。申请表则要保证一个用户在一个团队下只能有一条待处理的申请，这里我建了一个唯一索引，在数据库层面兜底，防止并发请求导致同一个人提交多条重复申请。
CREATE TABLE team ( id BIGINT AUTO_INCREMENT PRIMARY KEY, event_id BIGINT NOT NULL, leader_id BIGINT NOT NULL, team_name VARCHAR(100) NOT NULL, intro VARCHAR(500), current_count INT DEFAULT 1, max_count INT DEFAULT 5, status TINYINT DEFAULT 0 COMMENT '0招募中 1已满员 2已解散', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_event_status (event_id, status) );CREATE TABLE join_application ( id BIGINT AUTO_INCREMENT PRIMARY KEY, team_id BIGINT NOT NULL, user_id BIGINT NOT NULL, reason VARCHAR(500), status TINYINT DEFAULT 0 COMMENT '0待审批 1通过 2拒绝', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, audit_time DATETIME NULL, UNIQUE KEY uk_team_user_waiting (team_id, user_id, status), INDEX idx_user_status (user_id, status) );4.2 关键查询与统计SQL
组队列表页需要按“赛事+状态+技能标签”三个维度筛选。这里最容易踩的坑是标签筛选写成JOIN后导致同一团队出现多条记录，列表分页数不准。解决办法是先用子查询把所有匹配的团队ID查出来，再回到team表分页。
统计组队成功率的核心SQL是：已满员团队数量/赛事创建团队总数。但如果直接用固定时间点统计，会存在“团队解散后再创建”的重复计算问题。我的处理方式是统计时只计算状态为“已满员”的团队，按赛事分组，然后和该赛事的团队总数做除法。这类统计查询频率高，我建了一张赛事统计汇总表，每天晚上定时任务去算，避免用户每次看页面都跑全表聚合。
4.3 核心Service代码实现示例
创建团队的接口是整个系统的业务核心，至少要处理四件事：查赛事状态、查队长已有团队、查团队名称重复、初始化团队和队长成员关系。这段代码放在Service里，用@Transactional保证多个写操作要么全成功要么全失败。
@Service @RequiredArgsConstructor public class TeamService { private final TeamMapper teamMapper; private final EventMapper eventMapper; private final TeamMemberMapper teamMemberMapper; @Transactional(rollbackFor = Exception.class) public TeamVO createTeam(TeamCreateRequest request, Long leaderId) { Event event = eventMapper.selectById(request.getEventId()); if (event == null || !event.allowCreateTeam()) { throw new BizException("当前赛事不允许创建团队"); } Long existed = teamMapper.countActiveTeamByLeader(event.getId(), leaderId); if (existed > 0) { throw new BizException("你在该赛事已有一个未解散的团队"); } Team team = new Team(); team.setEventId(event.getId()); team.setLeaderId(leaderId); team.setTeamName(request.getTeamName()); team.setMaxCount(event.getTeamMaxCount()); team.setCurrentCount(1); team.setStatus(TeamStatus.RECRUITING.getCode()); teamMapper.insert(team); TeamMember leaderMember = new TeamMember(); leaderMember.setTeamId(team.getId()); leaderMember.setUserId(leaderId); leaderMember.setRole(TeamRole.LEADER.getCode()); teamMemberMapper.insert(leaderMember); return convertToVO(team); } }这段代码的关键在@Transactional。团队表和成员表是两处独立的写操作，不加事务的话，万一成员插入失败，团队已经建出来了，数据就是脏的。rollbackFor = Exception.class一定要写，因为默认情况下Spring事务只在RuntimeException上回滚，而自定义的业务异常默认是自定义的maybe false。
4.4 Controller层与参数校验
Controller层的设计原则是“薄”，把参数校验和分组交给Spring Validation。创建团队的请求对象上，我加了@NotBlank、@Size等注解。Controller里只需要写@Validated @RequestBody TeamCreateRequest request，框架就会自动校验参数，校验失败抛出的异常由全局异常处理器统一封装。这样代码干净，前端拿到的错误提示也比较友好。
@PostMapping("/api/teams") public Result<TeamVO> createTeam(@Validated @RequestBody TeamCreateRequest request) { Long userId = CurrentUserHolder.getUserId(); return Result.success(teamService.createTeam(request, userId)); }CurrentUserHolder是一个基于ThreadLocal的工具类，在JWT拦截器里解析token后存入。它在Controller和Service层都可以取到当前登录用户的ID，不用每个方法都传一遍。这里注意一个并发坑：ThreadLocal在线程池中会串数据，所以如果以后引入异步任务，一定要显式清理ThreadLocal。
4.5 文件上传与附加参数
竞赛系统还有一个常见的需求是上传商业计划书或报名材料。Spring Boot的MultipartFile上传本身很简单，但很多人会在“上传文件的同时还要带其他参数”这里卡住。我常用的接收方式是直接在Controller里用MultipartFile和@RequestParam接收，前端用FormData同时append文件和其他字段，不需要把Base64塞进JSON，那会显著增加传输体积和内存压力。
存储路径方面，本地开发我存在服务器的一个upload目录，文件名用UUID重命名，原始文件名单独存字段。生产环境有条件的话可以上OSS，但校内毕设项目用本地存储加Nginx映射就够用。文件大小限制记得在application.yml里配置，默认1MB很多时候不够用。
5. 从开发到部署，我遇到的那些典型问题
5.1 JSON循环引用和懒加载异常
实体类直接返回前端是我从一开始就极力避免的，但还是踩过一次坑。Team实体里有List成员属性，成员又关联User，User又关联Team，Jackson序列化的时候一旦没有在@JsonIgnoreProperties上配置好，就会出现无限递归，后台报StackOverflowError。
这种情况的根治办法是使用VO/DTO对象，手工把需要展示的字段复制过去，而不是直接序列化实体。懒加载异常则是因为Service层事务结束之后，实体关联的集合变成了代理对象，再访问时会抛出LazyInitializationException。很多人用spring.jackson.serialization.FAIL_ON_EMPTY_BEANS配置掩盖这个问题，但真正解决还是要养成“在事务内组装VO”的习惯。
5.2 并发申请同一个团队
学生端在组队快满时，会有多个人同时点申请按钮。如果不做任何控制，可能出现“团队已经满员但申请仍然成功”的情况。数据库层面，我会先查团队当前人数和maxCount，但两个并发事务可能都查到相同的结果，然后都执行更新。
解决思路有两个层次：第一，在团队成员表增加一个业务唯一索引，同一个用户同一个团队只能有一条有效记录；第二，更新团队人数时使用乐观锁或条件更新，例如UPDATE team SET current_count = current_count + 1 WHERE id = #{id} AND current_count < max_count，如果更新行数为0，说明满员，事务回滚。这个方案比加锁简单，也足够应对校内小规模并发。
5.3 跨域问题与后端配置
前后端分离后第一个跑不通的问题就是CORS。Vue前端跑在8080端口，后端跑在8081，浏览器发起请求时被跨域策略拦截。我在后端配置了一个WebMvcConfigurer，添加CORS映射，允许来源于本地开发前端的请求。这属于开发环境配置，但要把allowedOriginPatterns写成具体的域名，而不是直接使用*，否则带token的请求还是会出问题。
实际部署后如果前端和后端用了Nginx反向代理，跨域问题基本就不存在了，因为浏览器看到的域名都是同一个。所以很多新手如果开发时用代理方式跑，可以不需要后端主动配置CORS，但开发环境自己配一下能省不少心烦。
5.4 Actuator未授权访问
我一度为了监控内存和线程信息，把spring-boot-starter-actuator引入项目，依赖自带了一堆监控端点，结果忘了配置权限，导致未登录用户也能访问/actuator/env接口，看到环境变量和配置项。这在真实场景里绝对是安全事故。
一劳永逸的做法是把所有端点设置成只暴露health和info，其他全部关闭。如果确实需要展示metrics，也要放在Spring Security拦截规则里，要求具有ADMIN角色才允许访问。这提醒我们引入Spring Boot组件时，默认暴露的信息可能比你想象得多，生产环境一定要检查端点权限。
5.5 Spring Boot版本升级带来的兼容问题
我开发时用的Spring Boot 3.x，后来看到4.x发布了就想尝鲜。别的不说，光是Jackson的JSON处理模块就变了，原来自定义的ObjectMapper配置和JsonMapper.Builder写法在新版本里直接被移除或者改了包名，报错报得我一脸懵。如果只是做课程设计，老老实实选一个稳定版本即可，不要频繁跨大版本升级。升级前一定先看官方迁移文档，把依赖和配置兼容问题列出来，再动代码。
5.6 Docker部署中的数据库连接问题
部署阶段我选了Docker Compose，把MySQL和Spring Boot应用各跑一个容器。最常见的坑是应用容器里配置数据库地址时写了localhost，导致连不上。Docker容器之间不能用localhost互相访问，应该使用服务名，比如jdbc:mysql://mysql:3306/contest。另外MySQL容器初始化表，可以用官方镜像自带的/docker-entrypoint-initdb.d目录放SQL脚本，第一次启动时自动建库建表，比手动执行命令靠谱得多。
如果部署在云服务器上，还需要考虑防火墙和端口映射。后端服务和前端静态资源我都用Nginx统一入口，后端接口走/api反向代理到Spring Boot端口，前端静态文件直接放在Nginx的html目录。这样打出来的包不仅体积小，部署也只是拷贝文件和重启容器的问题。
6. 项目复盘与几点实在建议
6.1 先画清楚状态机再写代码
组队系统里有大量状态流转：赛事有赛事的状态，团队有团队的状态，申请有申请的状态。如果一开始状态枚举定义不清晰，后期每个接口都要加if判断，代码会越来越乱。我在做第二轮重构时把所有状态流转集中到两个状态机类里，赛事状态和团队状态分开管理，然后给每个状态迁移写单元测试，后续增加新功能才稳下来。
6.2 接口文档在编码时同步维护
一个人开发的时候很容易懒得写接口文档，但调试前端时发现还是得靠文档回忆参数。不要直接用Postman导出就完事，我建议每个接口都在注释里写清请求参数说明、响应示例和错误码含义。如果项目里用了SpringDoc/OpenAPI，就更轻松了，注解加上去能自动生成Swagger页面，前端同学直接对着页面联调。
6.3 演示数据和场景要足够真实
系统开发完，数据库里如果只有几条测试数据，页面看起来非常单薄。我写了一个CommandLineRunner，启动时检测数据库是否为空，为空就灌入一份演示数据，包括三个赛事、十几个学生、五六支团队、若干条申请。这里注意演示数据不要用真实学号和姓名，随便编造或者使用公开的示例名字就好。这份数据在答辩和演示的时候特别有用，能向别人展示系统的完整业务流程，而不是只能对着空表说“这里可以添加”。
6.4 后续扩展的方向
如果想让这个项目继续演进，我建议优先加三个模块：一是竞赛日历和提醒，根据赛事报名截止时间自动给用户推送邮件或微信模板消息；二是组队推荐算法，把技能标签、项目经历、历史获奖情况做成向量，计算学生之间以及学生与团队之间的相似度，目前没有全面铺开；三是评审管理，让赛事管理员能录入每支队伍的最终成绩和获奖等级，形成校内竞赛人才库。这些方向都建立在现有Spring Boot架构之上，扩展性很好。
说到最后，这个项目我从零开始搭到最终交付，最耗时间的不是写代码，而是把业务规则理清楚。比如一个学生可不可以同时参加多个赛事？可不可以同时申请多个团队？同一赛事未解散团队数量究竟限制为一个还是多个？这些问题如果不提前想清楚，后面每一个都会变成代码里的隐藏分支。从我个人的经验来看，把精力先花在业务模型的梳理上，Spring Boot本身的开发效率其实是非常高的，你可以非常快速地把一个个想法变成能跑起来的接口。希望这篇复盘能给正在做竞赛管理系统或者类似信息管理项目的你一点参考，少踩几个我踩过的坑。
