一个数学老师说要出一套期中考试卷，从前几天就在后台选题、排版、调格式，直到考试前一天晚上才定稿。我就是在那个时候意识到，一个能自动组卷的web系统，并不是把题目堆在一起那么简单。它要把题库、知识点、难度系数、题型分布、重复规避全部串起来，还要让教研员能一键生成可打印的PDF。这个基于SpringBoot+Vue的数学题库组卷系统，就是围绕这些真实场景做的。如果你正想找一份能跑起来、能部署、能讲解代码的Java全栈练手项目，或者你本身就在做在线教育相关的业务，这篇东西能给你省不少事。下面我会把它的设计思路、核心代码、部署过程和我踩过的一些坑，一次性讲透。
1. 项目拆解：数学题库组卷系统到底在解决什么问题
1.1 组卷系统的业务痛点与核心流程
先聊需求。数学组卷这个场景里，最麻烦的不是“存题目”，而是“按规则抽题”。一份正规的数学试卷有固定结构：选择题、填空题、计算题、解答题，每个大题下可能还有具体知识点要求。比如高一期中考试，要求“函数单调性”出2道选择、1道填空、1道解答，难度系数控制在0.65左右。如果靠人工翻题库，眼睛都能看花。更烦的是组完卷还要检查有没有重复题、有没有超出大纲、各章节分值是否均衡。这些重复劳动，正是系统要解决的核心问题。
所以这个系统的主流程围绕四件事展开：题库维护、知识点管理、组卷策略配置、试卷生成与导出。题库维护是最基础的，需要支持批量导入题目，题目至少要包含题干、答案、解析、知识点标签、题型、难度等级。知识点管理要按教材章节和知识点分层，比如“必修一集合”下面再挂“子集”“交集”“补集”等小点。组卷策略配置是核心，用户选择考试年级、教材版本、总分值、各题型题量、难度区间，系统根据这些条件到题库里抽取题目。最后生成试卷预览，支持调整题目顺序、替换题目，再导出成Word或PDF。整个链路看起来很常规，真正实现时细节特别多。
1.2 技术选型：为什么是SpringBoot+Vue而不是其他组合
有人问，为什么非要SpringBoot+Vue，用Python的Flask加React不行吗？行是行，但在校招简历、课程设计和很多企业内部系统中，SpringBoot+Vue就是事实标准。学校或教育机构的服务器大多还是Windows Server或者Linux，部署一个SpringBoot的Jar包非常省心，自带Tomcat，不需要额外装Apache。前端选Vue是因为它的生态成熟，Element UI组件库直接能把后台管理的布局、表格、表单搞定，开发效率比手动写jQuery高好几个档次。加上Vue的双向绑定，在组卷的参数配置表单里改一个数字，预览区马上刷新，交互体验很直观。
另外一个重要原因是JWT鉴权和RBAC权限模型在SpringBoot里的实现太方便了。SpringSecurity加一个注解就能控制接口权限，配合Redis可以把用户会话集中管理。Vue侧用Vue Router的守卫判断路由访问权限，配合Axios拦截器统一携带Token，整套鉴权链路闭合。这种组合对“快速交付一个后台管理类系统”来说，是经过大量项目验证的稳妥方案。如果你只是写个demo，也可以用Mock.js造假数据，但那只能应付演示，经不起真实用户的使用。
2. 系统核心模块设计与数据库建模
2.1 题库管理：题目模型、知识点标签与难度系数
题目表是整个系统的主心骨。在建表之前，我建议先理清两个关系：题目与知识点的关系，题目与试卷的关系。题目和知识点是多对多关系，一道题可能同时考“二次函数”和“不等式”，所以不能直接在题目表里塞一个“知识点”字段，而是要单独建一个question_knowledge关联表。题目和试卷的关系也要用中间表，因为同一道题可以出现在多张试卷里，而且在不同试卷里它的题号、分值可能不同。
下面是题目表的精简结构，字段不多，但每个都很关键：
CREATE TABLE question ( id BIGINT PRIMARY KEY AUTO_INCREMENT, type TINYINT COMMENT '题型：1单选 2多选 3填空 4解答', difficulty DECIMAL(2,1) COMMENT '难度系数', stem TEXT COMMENT '题干', options TEXT COMMENT '选项，JSON格式', answer TEXT COMMENT '参考答案', analysis TEXT COMMENT '解析', creator_id BIGINT COMMENT '录入人', audit_status TINYINT DEFAULT 0 COMMENT '审核状态', create_time DATETIME, update_time DATETIME );difficulty字段取0到1之间的小数，0.3说明题目很简单，0.8说明难度很高。很多新手在存难度时喜欢用“简单、中等、困难”这种字符串，系统里比对和统计会很别扭。建议直接用数字，查询时用BETWEEN 0.6 AND 0.75，前端再映射成文字展示。options用JSON存，是为了兼容选择题选项个数不固定的情况，有的题3个选项，有的5个，冗余地设计成option1~option5反而死板。
2.2 组卷算法：手工组卷与智能随机抽题的实现思路
组卷能力是系统的核心竞争力。这里我做了两种模式：一种纯手工，一个题目一个题目从题库挑选添加；另一种按规则自动抽取，也做了一套“先手工定框架、再自动填充”的混合模式。
手工模式相对简单，前端用一个题库检索列表，支持按知识点、题型、难度筛选，勾选后加到右侧试卷篮子。后端每次操作只维护”试卷题目明细表”，不会频繁操作主表。混合模式就不一样了，用户先配置一份“试卷蓝图”，比如：
{ "title": "高一数学期中测试", "totalScore": 150, "sections": [ {"type": 1, "questionCount": 8, "eachScore": 5, "difficultyRange": [0.5, 0.7], "knowledgePoints": ["集合", "函数"]}, {"type": 4, "questionCount": 3, "eachScore": 12, "difficultyRange": [0.4, 0.8], "knowledgePoints": ["函数单调性", "指数函数"]} ] }后端拿到这个蓝图后，按题型和知识点分组去题库查询。因为这里涉及难度区间和知识点筛选，不能简单地用SELECT * FROM question WHERE type=1 LIMIT 8。还要考虑到同一个知识点下不能抽太多重复的题，我当时的做法是：
- 对每个题干做MD5哈希存入题库表，生成试卷时检查题目哈希是否重复。
- 抽题采用“分知识点配额”，比如选择题8道，其中集合4道，函数4道，按配额去各个知识点池子内随机抽取。
- 抽完后如果某配额不足，就用相邻知识点或降低难度约束来补位，并标记提醒。
SQL层面，随机抽题尽量用ORDER BY RAND()，但题库数据量超过十万条后，ORDER BY RAND()在MySQL里会全表扫描加临时排序，性能很难看。工程上可以用“主键随机区间抽样”，即先在应用层生成M个随机ID范围，再用WHERE id IN (...)取题，等数据大了再换ES。这是实际业务里很重要的一个性能决策。
2.3 试卷管理与导出：PDF/Word生成的坑
生成试卷不是拼字符串那么简单。正反打印、选择题选项对齐、数学公式渲染、答案解析分离，每一项都容易翻车。
系统里我采用了两套导出方案。一套是后端用Apache POI生成Word文档，匹配一个定制的docx模板。另一套是前端把试卷内容渲染到页面，用户可以直接用浏览器“打印为PDF”。后者很适合校内使用，不需要额外装Office组件。数学公式是最难搞的，在Web端用MathJax渲染LaTeX，保存时直接存LaTeX源码，到了Word里还得让POI识别这些公式。老实说，POI对复杂嵌套数学公式的支持还是有限，所以我最终选择了折中方案：在线预览用MathJax，自动排版导出用纯文本的“题号+题干+选项+答案”格式，教研员拿到Word后再用自带的公式编辑器微调。这个方案虽然不那么“全自动”，但在真实教育机构里反而是最实用的。
还有页码和题号问题。多题型的试卷，题号必须连续，比如选择题1~8，填空题9~15，解答题16~18。类型之间题号不能断开，也不能每个大题从1开始。实现时不能只在每道题上存一个内部ID，要在“试卷题目明细表”里增加sort_no字段，每次增减题目后重新跑一次编号逻辑。这个细节如果漏了，导出的试卷就是乱的。
3. 后端SpringBoot关键代码讲解与配置
3.1 项目结构、依赖与统一返回体
拿到一份源码，第一件事是看目录结构。我这个项目是按四层结构分的：controller、service、mapper、entity。很多培训项目喜欢把包名写成com.example.demo，复制改改也能用，但团队协作时包名不统一特别伤。建议直接按业务域命名，比如com.school.mathbank.controller，一眼能看出权限归属。
pom.xml里的核心依赖就这几样：spring-boot-starter-web、mybatis-plus-boot-starter、mysql-connector、jjwt、spring-boot-starter-data-redis。MyBatis-Plus别小看，它在写单表CRUD时能帮你省掉一半的XML文件。不过组卷SQL比较复杂，我还是保留了一些自定义Mapper方法，把抽题逻辑写在XML里，方便调整。
统一返回体非常关键。如果没有统一封装，Controller到处返回Map，前端判断状态码得写一堆if-else。我是用了一个Result<T>类，字段包含code、message、data，成功时code为200，业务异常时用401、403、500。异常处理交给全局@RestControllerAdvice，把参数校验异常、业务异常、未知异常分开处理。这样前端Axios就可以只用一段拦截器代码搞定所有后端的成功和失败提示。
3.2 鉴权与拦截器：JWT+Redis为什么能省很多事情
管理系统的权限，我用了Spring Security做基础框架，但考虑到和Vue前端分离，没有启用它的Session登录，而是走JWT验证。登录接口校验用户名密码后，生成Token并返回前端。Token里只放userId和userName，不要把密码和角色权限都塞进去，权限还是从数据库实时查更好，避免用户角色变了Token里还留着旧权限。
生成Token的代码很常见，但有几个容易被忽略的设置。一是过期时间，课堂项目喜欢设成24小时，但真实场景建议2小时，配合Redis存储Token，做到“记住我”时再自动续期。二是签名密钥，硬编码在代码里是明文泄漏风险，应该放到application.yml的环境变量引用里。
拦截器只需要一个OncePerRequestFilter，从Header里取Authorization，解析出userId后放到ThreadLocal，供后续业务查询当前用户。对需要权限的接口，加上@PreAuthorize注解，比如管理员才能审核题目。Vue前端拿到401状态码时，跳转登录页并清空本地Token。这个链路清晰，出问题也好排查。
3.3 随机组卷的SQL与算法落地
智能抽题最后落到Mapper层，我用的是动态SQL。直接看这段Mapper的片段：
<select id="selectRandomQuestion" resultType="Question"> SELECT * FROM question <where> type = #{type} AND audit_status = 1 <if test="minDifficulty != null"> AND difficulty >= #{minDifficulty} </if> <if test="maxDifficulty != null"> AND difficulty <= #{maxDifficulty} </if> <if test="knowledgePointIds != null and knowledgePointIds.size() > 0"> AND id IN ( SELECT qk.question_id FROM question_knowledge qk WHERE qk.knowledge_id IN <foreach collection="knowledgePointIds" item="id" open="(" separator="," close=")"> #{id} </foreach> ) </if> AND id >= FLOOR(RAND() * (SELECT MAX(id) FROM question)) - 200 </where> ORDER BY id ASC LIMIT #{count} </select>注意我抽题时加了一个id >= FLOOR(RAND()*MAX(id))-200的条件，这是让随机范围尽量落在靠近某些行的地方，减少全表排序。它不能保证严格随机均匀，但对组卷场景足够用了。真要更均匀，可以把题目ID按区间切分，比如分10个区间，每个区间随机取几个，再合到一起。这属于抽题算法的优化细节，后文再展开。
抽到题之后，Service层要执行“重复检查”。我建了一张paper_question_temp临时表，在生成正式试卷前先把本次候选题目存进去，按question_hash做唯一校验。如果有重复，就换一批候选题再抽。这个步骤看上去笨，却是保证试卷质量的关键。
4. 前端Vue核心页面与交互细节
4.1 路由、状态管理与权限控制
前端用的是Vue 2.6加Element UI，没有太重装Vuex，只在登录后拉取用户信息和动态菜单，存到Vuex里。动态菜单是核心功能：不同角色登录后，侧边栏看到的项目不一样。管理员有题库审核、知识点管理、用户管理；普通老师只有组卷中心和我的试卷。
路由权限我推荐这么实现：router.beforeEach里判断本地有没有Token，没有就去登录页。有Token但访问的是动态路由里的地址，就从后端权限列表里匹配，匹配不到就跳401页面。注意，不能只做前端隐藏菜单就算权限控制，后端接口必须也校验权限，否则用户直接在浏览器地址栏输入路由地址就能绕过。这一点我在代码讲解时一定强调。
Element UI的el-menu用router模式，菜单的index对应路由路径，点击就能自动跳转。但菜单列表和权限列表有嵌套关系，如果后端返回的权限数组是扁平结构，前端要自己构建成树形菜单。我公共了一个buildMenuTree的工具函数，按pid递归，搞定之后侧边栏就能动态刷新了。
4.2 组卷页面的动态表单与拖拽排序
组卷配置页面是这个项目里最复杂的一个前端页面，因为它不仅要收参数，还要实时反馈可选题数量和试卷预览。页面结构分左中右三栏：左边是题库筛选条件，中间是试卷结构配置表，右边是预览区。
筛选条件区用el-form绑一个筛选对象，点击“搜索”后调用后端接口获取符合条件题目的数量。这个数量反馈很重要，不然用户配置了“选择题8道，难度小于0.5”，结果题库里只有5道，最后生成时就会报错。试卷结构配置表用el-table展示一个个Section，每一行都有题型的下拉、题数、分值、难度区间、知识点选择，支持增加行、删除行。这个表格其实是“动态表单”，每一项都要绑定v-model，而且修改任何一项后，都要重新向后端请求一次“可组卷性检查”，让用户知道当前的配置能不能组出完整试卷。
预览区我用了一个简单粗暴的做法：不渲染真实的试题内容，只显示题目编号、题号、知识点和题型预览，避免把整张卷子的公式全部拉下来导致页面卡顿。用户觉得配置满意了，再点“生成完整试卷”，进入真正的预览页。
拖拽排序是另一个亮点。因为实际出卷时，老师经常会调整解答题的位置，比如把压轴题放到最后。前端我用vuedraggable库，把试卷题目列表封装成可拖拽组件。拖拽完成之后，前端重新计算所有题目的solution order，然后再保存到后端。要注意的是，拖拽排序不能只改前端展示顺序，后端明细表里的sort_no必须一起更新，不然刷新页面排序就丢了。
4.3 题目录入的富文本与数学公式处理
题目录入页面的难度在数学公式上。普通textarea肯定不行，因为数学公式有分式、根号、上标下标、求和符号，必须用公式编辑器。系统里选用的是vue-quill-editor作为富文本，同时集成MathQuill或MathJax处理公式。
我的方案比较轻量：在富文本工具栏上加了一个“插入公式”按钮，点击后弹窗打开MathQuill编辑器，用户在可视化区域写公式，生成LaTeX字符串，然后插入到富文本内容里。渲染时用MathJax把LaTeX转成HTML。这个流程最常见的坑是：富文本编辑器会把LaTeX按HTML格式转义，导致\frac{1}{2}被存成奇怪代码。解决方法是自定义富文本增量格式，把公式内容包裹在一个自定义节点里，保存时保留源码，提取纯文本时用正则还原。
题库批量导入功能我也做了。提供Excel模板，列包含题干、选项、答案、解析、知识点、题型、难度。但Excel里的公式和特殊字符一定要检查，比如<、>、&这些符号在XML里会被解析器当标签处理，导入时需要先做HTML实体转义。我在这里试过直接用EasyExcel解析，但公式单元格的样式很难还原，最后都是统一转换成纯文本再入库。如果你的题目里有大量图片，建议先上传图片到OSS，再把图片URL嵌入到题干字段，不要直接塞base64，不然数据库会爆炸。
5. 部署流程与踩坑实录
5.1 环境准备：JDK、Node、Nginx的版本搭配
在本地跑通项目和在服务器上跑通项目是两种完全不同的体验。我第一次把这份源码部署到云服务器时，按照记忆直接装了个最新版JDK，结果项目启动直接报错。原因很简单：SpringBoot 2.7用的是JDK 8编译，换到JDK 17后，javax.servlet改成jakarta.servlet，一大堆类找不到。所以部署前最好用项目pom.xml里指定的JDK版本，不要自作聪明升级。常见搭配是：
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| JDK | 1.8 或 11 | SpringBoot 2.x 默认支持 |
| Maven | 3.6+ | 打包用，也可用IDE内置 |
| Node | 14 或 16 | Vue 2项目对Node版本有要求 |
| Nginx | 1.20+ | 做前端静态资源和反向代理 |
| MySQL | 5.7/8.0 | 注意驱动版本 |
Node版本太新也会出问题。Vue 2项目用Node 18以上打包时，可能因为OpenSSL依赖报错，我遇到的就是error:0308010C:digital envelope routines::unsupported。原因很经典，解决方法是设置环境变量NODE_OPTIONS=--openssl-legacy-provider，或者在package.json里配置scripts。换成Node 16后没有丝毫问题。
5.2 打包与部署：前端构建到Nginx，后端Jar包启动
后端部署没什么神秘，就是在项目根目录执行：
mvn clean package -DskipTests java -jar target/math-bank-server.jar --spring.profiles.active=prod生产环境的数据库连接、Redis地址写在application-prod.yml里，用环境变量覆盖。这里我遇到过一个大坑：打包后Jar包可以在本机运行，但放到服务器上连不上MySQL。排查好久发现是Linux服务器防火墙放行了3306端口，但MySQL配置里bind-address默认是127.0.0.1，只允许本机连接。要把MySQL的bind-address改成0.0.0.0，或者直接用内网IP连接。代码层面连接数据库的URL里也要加useSSL=false&serverTimezone=Asia/Shanghai，不然时区报错。
前端打包是：
npm install npm run build:prod打包后生成dist目录，把这个目录整个上传到服务器Nginx的html路径下。然后配置Nginx反向代理到后端端口。我的Nginx配置大概是这样的：
server { listen 80; server_name example.com; root /var/www/html/dist; 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; } }重点在location /api/的转发和try_files的配置。Vue是单页应用，如果用户直接刷新/paper/preview这个路由，Nginx会把请求发给后端去找对应的Controller，但后端没有这个路由，就会返回404。加了try_files $uri $uri/ /index.html后，所有不存在的路径都回退到index.html，由前端路由接管。
5.3 常见问题排查：跨域、端口占用、数据库连接失败
部署过程中最常碰到的就是跨域。前端地址是http://ip:80，后端接口是http://ip:8080，浏览器直接请求就会被CORS拦住。我在后端加了一个CorsFilter配置，允许所有来源、所有请求头、所有方法。如果是生产环境，更推荐用Nginx代理方式来避免跨域，因为浏览器看到的域名只有一个，就不存在跨域问题了。
端口占用也是高频问题。后端Jar包启动报Port 8080 was already in use，用lsof -i:8080找到占用进程，再kill -9。更稳妥的做法是不要用固定端口，让运维在启动时通过--server.port=8081指定，这样一台服务器可以跑多个项目实例。
数据库连接失败还有一个隐蔽原因是数据库字符集。SQL文件里如果建表时没有指定字符集为utf8mb4，插入题目里的数学符号、中文、甚至emoji可能报错Incorrect string value。我先在数据库建库时写上：
CREATE DATABASE math_bank DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;然后启动前检查show variables like '%character%'。这个步骤虽然基础，但每次都要注意。
还有一个被忽略的问题：前端调接口时拿到的是后端返回的JSON中文乱码。这个一般不是编码问题，而是SpringBoot的server.servlet.encoding.enabled没有开启，或者响应体没有设置charset=UTF-8。用SpringBoot 2.x默认已经处理了，但你要是自己写了HttpServletResponse输出字符串，就必须手动加response.setContentType("application/json;charset=UTF-8")。很多课程作业源码在这里翻车。
5.4 我建议你在源码基础上做的三个改造
如果只是为了交作业或者跑demo，拿到源码后建议先跑通，再动手改。但我个人经验是，光跑通没意义，面试官一问就露馅。你至少要自己改三处地方：第一，把后端写死的上传文件路径和OSS配置改成本地存储或MinIO，顺便学一下对象存储的对接；第二，把自动组卷的ORDER BY RAND()改成基于知识点分桶抽题，并在Service层打印审计日志，统计每次抽题耗时；第三，给前端增加一个“导出题目汇总表”的功能，用后端Excel导出，把本次试卷的答案和解析单独导出成教师版。这三个改造，覆盖了文件存储、性能优化、复杂报表，比一开始就想着加花哨的“在线考试倒计时”有用得多。
还有一个容易被忽略的：代码里的SQL文件很可能不包含初始管理员密码的明文，而是MD5或BCrypt加密过的。你要先去application.yml里查看sql.init配置，通常data.sql中预置了一条INSERT INTO sys_user语句。如果密码是BCrypt加密的，可以在本地写一个测试类来生成加密串，再替换掉。不改这个，你连管理后台都登不进去。
关于“源码文档”和“代码讲解”，我的习惯是：先让同事跑通部署文档，运行过程中遇到问题就更新文档，而不是等代码全部写完再补。因为部署文档是给人看的，你自己觉得步骤清晰没用，别人按着走一遍才作数。代码讲解时也是先讲流程图，再贴核心代码，不要一行行往下念，那样没人听得下去。重点讲三块：MyBatis-Plus的分页条件构造器、JWT的拦截逻辑、组卷算法里为什么要先查数量再抽ID。能把这三块讲明白，这个项目你就真正吃透了。
最后说一个和“数学题库组卷”不太相关但很实用的经验：遇到Bug，不要急着改代码，先看日志。SpringBoot项目启动日志一级级往下翻，看到Caused by这一行才是根因。前端页面空白，打开浏览器开发者工具看Console的红字和Network请求的响应码。部署类问题，八成是环境和文档不一致。把这篇里提到的坑都避开，你的部署过程应该能一次通过。如果还有问题，多半是版本差异或配置文件漏项，顺着报错信息往源头查，很快就能定位。
