巩玺把“语言考试信息报名系统”从需求到上线完整过了一遍，技术栈就是SpringBoot2+Vue3+MyBatis-Plus+MySQL8.0这一套。报名系统听起来简单，无非是几张列表页、一个报名按钮、一个后台管理，但真正跑起来要解决的问题一点都不少：场次怎么排、考位怎么扣、重复提交怎么防、考生级别怎么审核、报表怎么导出、前后端权限怎么对得上。这套源码连同部署文档我已经一起整理了，下面把整个项目从设计、开发到部署、排错的过程拆开来说，踩过的坑都会点到。适合两类人看：一类是刚学完SpringBoot和Vue、想拿一个完整项目练手的同学，另一类是公司要临时接报名类需求、想快速落地又少走弯路的开发者。
1. 项目整体设计与技术选型思路
1.1 为什么选SpringBoot2+Vue3而不是其他组合
选这套组合，首先考虑的是交付稳定性。SpringBoot2目前仍然是企业里存量最多的版本，第三方组件适配资料丰富，很多项目组现有的中间件、监控平台都对它很熟，接手成本最低。团队里如果还有一批人守着Spring Boot 1.5的老项目，切换过来也几乎没学习障碍。
Vue3这边我当时对比过Vue2，最终还是定了Vue3。原因很实际：组合式API把逻辑聚合能力提升了一个量级。报名系统的表单校验、倒计时、步骤条、列表筛选这些逻辑一旦复杂起来，Options API里会散落在data、methods、computed、watch各个角落，而composables可以按业务维度把相关状态和方法收在一个函数里。页面里引用三个组合函数，代码立刻清爽。
ORM选型上，我认真比较过Spring Data JPA和MyBatis-Plus。JPA在单表CRUD和实体关联上确实省事，但报名系统有大量动态条件列表查询、多表关联统计、XML里写复杂SQL的场景，MyBatis-Plus的QueryWrapper和自定义Mapper XML混合写法明显更顺手。JPA的懒加载和N+1问题在这种报表型页面上也很容易翻车，MyBatis-Plus至少能明确看到每条SQL在做什么。
1.2 报名系统的核心业务模块拆解
考试报名信息系统的核心用户其实只有两类：管理员和考生，但权限边界必须分清楚。管理员这边负责场次管理、语种维护、报名记录审核、考位余量查看、报名数据导出。考生这边负责注册登录、浏览可报名场次、提交报名、取消报名、查看审核状态。不要小看这个看起来简单的模型，它把“资源管理+预约申请+审核流程”这三个最常见的后台业务全部覆盖了。
所以我在拆模块时完全按资源领域划分：用户模块、场次模块、报名模块、审核模块、统计导出模块。用户模块管账号、角色、资料；场次模块管考试时间、地点、语种、考位总数；报名模块管报名记录的增删查和状态流转；审核模块管资格核验与状态回写；统计导出模块管报名人数汇总和Excel导出。这样划分的好处是将来扩展特别方便，比如给场次模块加一个价格字段和支付回调，整个系统就能变成收费考试报名平台；把场次换成课程，就变成了选课系统。
1.3 前后端分离的项目结构
项目工程上分成server和web两个目录。server是Maven多模块结构，按common、entity、mapper、service、controller分层；web是用Vite创建的Vue3工程，按api、views、components、router、store、utils组织。重点说两个细节：
第一，前后端分离不等于微服务。这个项目就是两个工程、一套HTTP约定，开发时由Vite代理转发到后端端口，部署时由Nginx统一入口反向代理到SpringBoot，能省掉大量跨域和网络配置的麻烦。
第二，entity和VO不要混用。数据库实体类只放持久层字段，返回给前端的对象单独建VO类，字段按页面需要裁剪。比如用户表里存了密码哈希，VO里绝对不能出现这个字段；报名列表页面需要显示考生姓名、场次名称，就在VO里冗余这两个展示字段，不要每次让前端自己联表。接口返回值统一用Result
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 数据库设计与后端接口实现
2.1 MySQL8.0的表结构设计思路
MySQL8.0安装后第一件事就是确认字符集。不要用默认的latin1或utf8mb3，报名表里可能出现考生姓名、考试语种、特殊备注这种含emoji或生僻字的场景，必须用utf8mb4。Linux下修改my.cnf，加上character-set-server=utf8mb4和collation-server=utf8mb4_general_ci，重启后确认character_set_server和collation_server都变了再建库。光改client端编码没用，服务端默认字符集不对，存储还是会出问题。
建表核心是四张表：sys_user用户表、sys_role角色表、exam_session考试场次表、exam_registration报名记录表。公共字段统一是id、create_time、update_time、deleted，配合MyBatis-Plus的逻辑删除。考试场次表要存考试名称、考试语种、开始时间、结束时间、总考位数、已报名人数、报名截止时间、考试地点，其中总考位和已报名人数都是int类型，状态用tinyint。报名记录表要存用户ID、场次ID、报名状态、身份证号、联系电话、审核备注，并在user_id和exam_session_id上建联合唯一索引。
关于设计上的取舍，我想多说一句：别怕冗余，怕的是无脑冗余。报名列表页面几乎每一次都要显示考生姓名和场次名称，如果只存ID，列表查询就得join两张表。我在报名记录表里直接冗余了考生姓名、场次名称、考试语种三个字段，虽然违反了严格第三范式，但换来了列表查询少两次join，数据量上来以后性能优势非常明显。冗余字段通过管理员操作和报名提交时的接口统一维护，不要太担心不一致。
2.2 MyBatis-Plus在实战中的正确用法
MyBatis-Plus最容易被用歪的地方是条件构造器满天飞。我定了一个规矩：controller只接收参数，不写任何业务条件；service层统一用LambdaQueryWrapper拼条件，字段名全部用Lambda形式，比如wrapper.like(ExamRegistration::getCandidateName, keyword)，避免手写字符串字段名拼错，重构字段时也能提前暴露错误。
分页必须用内置的分页插件，单独建一个MybatisPlusConfig类，注入PaginationInnerInterceptor，并且指定数据库类型为MYSQL。没有这个拦截器，分页查询里的Page参数是不生效的，这个坑很多人第一次用MP都会踩。插件配置好以后，service里传一个Page对象，返回的IPage里有records、total、current、size，直接放进统一的PageResult里返回给前端。
不过我的原则是能写XML的复杂查询就不要硬用Wrapper。报名记录的分页列表要关联用户表显示联系方式、关联场次表显示考试时间，这种多表查询我直接在Mapper XML里写resultMap和动态SQL。XML里的SQL用<where>和<if>标签控制条件，可读性比一长串Wrapper强得多，出问题时也能直接复制到Navicat里单独跑。MP更适合单表CRUD和简单条件查询。
2.3 报名接口的防重与幂等处理
这是整个系统里我最想强调的部分。考生点击报名按钮的瞬间，后端必须同时校验三件事：场次存在且状态为可报名、当前时间没超过报名截止时间、剩余考位数大于0。三个条件都满足才能往下走，但只做这层校验远远不够，因为两个并发请求可能同时通过了校验。
第一个保障是数据库唯一索引：uk_user_session(user_id, exam_session_id)。不管代码怎么并发，数据库层面保证同一个考生对同一个场次只能有一条报名记录。第二个保障是扣减考位用原子SQL，不要先select再update：
sql复制UPDATE exam_session
SET registered_count = registered_count + 1
WHERE id = #{sessionId}
AND registered_count < total_seats
这条SQL的影响行数如果等于1，说明扣位成功；等于0，说明考位已经满了，直接抛业务异常返回“考位不足”。这里用受影响行数判断，比先查出来再在Java里比较安全很多，因为select和update之间永远有并发窗口。
接口层我还加了一个提交令牌机制。后端在用户进入报名页时下发一个一次性token，提交报名时带着token一起发，后端消费后立刻失效。这个机制主要是挡用户双击和前端重复提交，不是用来替代数据库层的防重，两层各管一段：token管用户操作，唯一索引和原子SQL管并发安全。
2.4 报名列表查询与导出实现
报名列表的筛选条件一般有考试场次、报名状态、关键词、报名时间段四个维度。我把查询条件抽象成一个Query对象，service里根据对象里的非空字段动态拼条件。列表页默认按创建时间倒序，但管理员经常想看报名人数最多的场次，所以场次列表接口额外提供了按报名人数排序的字段。
导出功能我单独写了一个接口，不走前端分页查询逻辑。直接用原生SQL一次性查出全量数据，放到一个工作簿里输出。数据量不太大的时候，POI的SXSSFWorkbook就够用；如果单场报名超过几万条，建议改成异步导出：先把Excel写到服务器临时目录，再返回下载地址。导出文件名里加上时间戳，避免浏览器缓存同名文件，这个细节很容易被忽略但很实用。
3. 前端Vue3实现与联调细节
3.1 Vue3组合式API怎么组织代码
Vue3引入组合式API以后，最容易出现的问题就是所有代码全堆在setup里，变成一个超级大函数。我的习惯是分三层：views下面的页面组件只负责模板和事件绑定，数据请求统一收在src/api模块里，可复用业务逻辑抽到src/composables里。比如composables/useRegistration.js里放了报名表单的校验规则、剩余考位计算、倒计时、提交状态管理，页面组件里只写了这十几行：
javascript复制const { form, loading, countdown, register, validateForm } = useRegistration()
这样代码逻辑清楚，而且useRegistration可以随时被另一个页面复用。computed的使用要谨慎，报名页面的“当前剩余考位”和“按钮是否可点”这类同步派生的状态用computed非常合适，但涉及异步接口返回的数据一定要用ref包裹，因为computed不会自动依赖异步更新的数据源，容易拿到旧值。
3.2 Axios封装与登录态管理
Axios封装我想强调三点：baseURL不写死，用Vite的环境变量；请求拦截器统一加token；响应拦截器统一处理业务错误码。响应拦截器里遇到401跳登录页、遇到其他code弹错误消息，再返回一个被reject的Promise让页面catch。业务代码里尽量只关心data，不重复处理错误提示。
Token存储方式我前后改过两版。最初只放localStorage，每次请求从localStorage读，性能没问题但代码很啰嗦；后来改成Pinia内存态加localStorage双写，刷新页面后用localStorage回填，这样既避免每次读Storage，又不丢登录态。为了兼容这个机制，登出时两个地方都要清，遗漏任何一个都会留下半个登录态。
路由权限控制放在前端路由守卫里。登录接口返回后，把用户角色信息存进Pinia，路由表的meta里写好requiresAuth和`role，beforeEach里先校验是否登录，再校验角色匹配。管理员路由和考生路由分开配置，管理员进考生页面没问题，考生进管理页面会被弹回401页。这里要注意，前端路由守卫只是体验控制，真正的数据安全必须在后端做，如果后端接口没有做权限校验，前端就算把管理按钮藏起来，别人直接调接口还是能操作。
3.3 报名流程页面的交互细节
报名的完整流程我分成了三步：选场次、填资料、确认提交，页面顶部放一个步骤条，用户随时能看清自己在哪一步。第一步展示可报名场次列表，已经满员的场次按钮置灰并显示“已满”；第二步填写身份证、手机号、姓名；第三步做信息确认，提交后按钮进入loading状态并禁用。
表单校验全部展开写，不要在提交时才提示。身份证号输入框写一个简易校验函数，18位、末位可能是X，校验通过后自动提取出生日期填进生日字段，这个小体验用户反馈很好。手机号用正则^1[3-9]\d{9}$做即时校验。整个填资料流程保持所有字段在ref里统一管理，切到下一步之前做一次整体validate，不通过就定位到第一个错误项。
提交成功以后要注意清理状态。我遇到过的问题是用户提交成功后退回上一页，表单数据还在，再点一次就重复提交了。后来在提交成功回调里把整个表单对象重置，并清掉缓存里的草稿参数。列表页的筛选条件我同步到了URL的query参数上，刷新或者分享链接都不会丢筛选状态，这个做法成本低、收益明显。
3.4 联调阶段的一些小问题
联调最让人头大的是接口路径不一致。后端Controller的RequestMapping写的是/api/exam，前端axios请求如果习惯性多写了一个/api，就会变成/api/api/exam，这种问题前后端各查半天，最后才发现是路径拼接重复。解决方式是前端在api模块里统一维护一个常量前缀，所有请求都通过封装方法发起，不允许页面里直接拼URL。
还有一个印象很深的坑：Vue3里给自定义组件直接绑v-model，如果props名为modelValue但没有定义modelValue的更新事件，控制台会警告而且数据不更新。正确做法是定义一个computed，get里return props.modelValue，set里emit('update:modelValue', value)。这个问题新人踩得非常多，因为我一开始也是从Vue2的习惯直接复制过来的。
后端返回的时间字段是LocalDateTime序列化后的格式，默认看起来是2024-01-15T08:30:00，前端展示要重新格式化，体验很突兀。我在Jackson配置里统一加了时间格式化模式，这样后端输出的JSON就是2024-01-15 08:30:00，前端可以直接展示。这个问题不看接口文档根本发现不了，一开始以为前端代码写错了，后来才发现是后端序列化没配置。
4. 部署上线与环境搭建实战
4.1 MySQL8.0的安装与初始化
MySQL8.0在Linux上安装我用的是APT和YUM方式，这里多说两句。安装完成后第一步是拿临时密码登录，然后马上修改root密码。8.0默认的密码策略要求比较高，开发环境设置弱密码会一直报错，得先调整validate_password策略：
sql复制SET GLOBAL validate_password.policy = LOW;
SET GLOBAL validate_password.length = 6;
不过生产环境不建议这么做，开发机随便，线上还是老老实实用强密码。库建好后，我用Navicat连接测试了一次，发现连不上先检查三处：3306端口是否被防火墙拦截、MySQL是否有权限让远程主机访问、账号认证插件是不是caching_sha2_password且客户端版本太老不支持。
建库语句我固定写成：
sql复制CREATE DATABASE exam_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
初始化数据分成schema.sql和data.sql两个文件。schema只建表，data插入管理员账号、角色、默认场次。项目文档里的部署说明会明确告诉新人先执行哪个、再执行哪个，顺序反了会出现外键失败或者找不到表。
4.2 后端Jar包的打包与启动
后端部署我推荐一个最省心的方案：直接用Maven打成jar包，然后用systemd托管进程。这样进程崩溃了能自动重启，服务器重启也能自启动，比裸java -jar挂在后台靠谱得多。
写一个exam-server.service文件，核心配置就是ExecStart指向java命令和jar路径，关键是加上-Xms256m -Xmx512m堆内存参数，避免默认堆设置过大导致小服务器内存被打满。Jar包里面内置了Tomcat，所以SpringBoot应用会监听8080端口。启动前用lsof -i:8080或ss -tlnp | grep 8080确认端口没被占用，这个步骤很多人忘记，启动报端口被占后又要排查半天。
日志就交给SpringBoot自带的logback，我配了一个按天滚动且只保留30天的策略，日志文件路径和数据目录分开，避免后续磁盘被日志打满。启动后不要急着看接口，先看日志里有没有“Started ExamApplication”这一行，没看到就说明启动过程还有异常，再用tail -f logs/exam-server.log跟踪实时输出。
4.3 前端打包与Nginx反向代理配置
前端打包命令是npm run build，产物会输出到dist目录。把dist里的静态文件上传到Nginx的html/exam-web目录，然后配置一个server块：
nginx复制server {
listen 80;
server_name exam.example.com;
root /var/www/exam-web;
index index.html;
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location / {
try_files $uri $uri/ /index.html;
}
}
注意proxy_pass结尾不能带斜杠，带了的话/api/exam/list会被转成/exam/list，后端接口路径就全对不上了，这是我碰到过频率最高的Nginx配置坑。Vue3是History路由，所以还要配try_files把未知路径重写到index.html，否则用户直接刷新某个子路由页面会得到404。
4.4 上线后的基础检查清单
部署完成以后，我会按一个固定顺序做冒烟测试，不跳过任何一项。第一步，访问首页确认静态资源能加载；第二步，登录管理员账号新建一个测试场次；第三步，切到考生端注册一个账号并报名；第四步，回到管理端审核并导出Excel；第五步，检查数据库表里已报名人数是否被正确更新。这五步走完，基本能覆盖主链路。
还要看看后端错误日志里有没有SQL异常和空指针。有些接口第一次访问没问题，第二次开始出问题，多半是缓存或全局变量被污染了，这种问题日志最能说明情况。我习惯上线后立刻抓一次线程栈确认没有死锁或连接池泄漏，SpringBoot的Actuator里提供了health和threaddump端点，配合Kibana或者简单的grep命令就能完成。
5. 项目复盘与后续扩展方向
5.1 这个项目最值得复用的设计
回头看整个项目，我最满意的不是某张页面做得多好看，而是“防重复报名”和“考位扣减”那两层设计。很多时候业务方说的“报名系统”背后藏着很多隐性问题：同一个考生能不能多个场次都报名？满员后是排队还是拒绝？取消报名后考位能不能回收？这些问题没有在数据库层面想清楚，代码写一半就会返工。
如果让我再做一个类似系统，第一版我会这样定：用户表、场次表、报名表三个核心表必须有，报名表必须用唯一索引防重，场次表必须有已报名人数和总人数两个字段，扣减必须原子操作。只要这四个骨架立住，后面不管加支付、加审核、加日历展示，都不会动摇核心数据的一致性。
5.2 可以往哪些方向继续扩展
这个系统已经有的基础框架完全可以横向扩展。给场次表加一个price字段，再加一个支付回调接口和订单表，就变成了一个收费考试报名平台。把报名状态从简单的待审核、通过、拒绝扩展成待支付、已支付、已取消、已退款，就是标准的票务系统。增加一个“准考证下载”模块，把考生信息和场次信息生成PDF，就覆盖了大部分语言考试机构的日常流程。
管理端还能继续加仪表盘页面，展示报名趋势、各语种分布、场次上座率。这些统计SQL在现有表结构上基本就是几条group by查询，前端用ECharts或者AntV画图就够了。数据库层面如果以后报名量单场超过十万，可以为报名记录表增加按月分区的计划任务，查询时按场次ID和状态建复合索引基本就能顶住。
5.3 给接手这个源码的同学几点建议
文档里我放了部署说明、接口文档、初始化SQL，但我建议不要急着跑起来，先花半天时间把四张核心表的关系理清楚，再看一遍报名接口的service实现。这比先看页面代码重要得多。开发环境启动时，前端记得配好.env.development里的代理地址，后端记得改application.yml里的数据库密码，这两个配置是最容易漏的。
排查问题时养成一个习惯：报错信息永远是第一位的。前端控制台报错先看Network里实际返回的HTTP状态码，后端日志先看Exception堆栈的第一行。很多人遇到问题第一反应是断点调试，其实先看日志和接口返回能解决60%的问题。记住一个原则：前端看不懂的错误，十有八九是后端返回的数据结构不符合预期；后端看不懂的报错，十有八九是SQL或者连接配置问题，按这个思路排查会快很多。
5.4 一点真实的开发体会
这个系统开发过程中最深的体会是，报名系统的核心不在“报名”这个动作，而在“报名状态的准确性和唯一性”。考试报名系统最害怕的事就是两个用户抢最后一个考位，结果两个人都报上了，或者同一个人重复生成了两条报名记录。这一类数据一致性问题，靠前端按钮禁用解决不了，靠Java的synchronized也解决不了，唯一可靠的办法就是把防重交给数据库的唯一索引，把扣减交给原子SQL，把兜底交给事务回滚。
最后再分享一个很实际的小技巧：开发阶段的数据库和测试数据库一定不要用同一个。我自己吃过一次亏，开发时写的一条测试数据把测试环境的报名统计搞乱了，后来排查了半天才找到原因。现在我在三个环境各建一个独立的exam_db数据库，连接串用不同端口区分，本地用3307，测试用3308，线上用3306，彻底从源头隔离。这个习惯在任何项目中都值得坚持。