拿到这套基于SpringBoot和Vue的实验报告管理系统源码时，我第一反应是典型的教学管理类全栈项目。但真正动手把它从代码仓库变成能跑通、能交付的完整系统，才发现里面涉及的坑远比想象中多。这篇文章不打算写泛泛的架构科普，而是记录我从零开始部署这套源码、逐行读代码、把前后端串起来的全过程。不管你是准备拿这套系统做课程设计，还是刚接手类似的开源项目，里面关于环境选型、数据库初始化、权限拦截、文件上传、部署打包的细节，都能直接对齐到你自己的项目里。
1. 项目整体设计与思路拆解
1.1 这套系统到底解决了什么问题
实验报告管理系统最常见的业务背景是：某高校或培训机构的实验课程，需要学生在线提交实验报告，教师在线批改打分，管理员统一管理课程和用户。纸质报告时代最头疼的问题有两个：一个是报告流转慢，学生交完不知道进度，老师收齐需要半个月；另一个是存档难，纸质报告翻找、归档、统计分数都是体力活。这套系统把整个流程搬到线上后，学生端可以实时看到报告状态，教师端可以批量打分，管理员能按课程、按班级导出成绩，效率提升非常明显。
从标题可以看出，项目的技术栈是SpringBoot和Vue。前者负责后端接口和数据持久化，后者负责用户交互界面。这里有一个关键认知：为什么选这种组合，而不是用JSP或者纯Servlet？因为前后端分离之后，后端只需要专心提供JSON接口，前端页面交互、组件复用、状态管理都交给Vue，团队分工清楚，后期扩展移动端也容易。而且SpringBoot自带的Starter机制，配置一个Web项目只需要寥寥几行依赖，开发效率非常高。
1.2 角色权限和业务流程的主线
我通读了源码中的权限设计，核心角色有三个：学生、教师、管理员。学生登录后可以查看自己的实验任务、在线填写报告、提交附件；教师可以创建实验任务、查看某个班级的提交情况、批改报告并打分；管理员则管理用户、课程、学期等基础数据。三条角色线在功能上互有交集，所以源码中基于拦截器做了三类接口的鉴权。
我特别要提醒的是，业务主线的设计直接决定数据库表结构。这套系统的核心流程是：管理员创建课程和班级，教师安排实验任务，学生提交报告，教师批改，系统统计成绩。理解了这条链路，再看代码就完全不乱了。
1.3 为何这套系统的技术选型适合教学场景
如果从零手写一个SpringMVC加模板渲染的系统，也能实现上述功能。但为什么很多教学场景都选择SpringBoot加Vue？核心原因有三点：第一，SpringBoot极大降低了装配成本，不需要繁琐的XML配置，打包成JAR后一键启动，部署门槛低；第二，Vue组件的开发体验对小团队友好，特别是做后台管理界面，表格、表单、弹窗这套组合特别成熟；第三，这类项目通常需要学生或开发者二次开发，前后端分离结构更容易定位和修改问题——前端问题去控制台看Network，后端问题去日志看异常，排查路径非常清晰。
这套源码选择了MyBatis Plus作为持久层框架，也是同样的逻辑：简单、够用、学习曲线平缓。
2. 核心模块与数据库设计拆解
2.1 用户模块和登录态的设计细节
登录模块是几乎每个全栈项目都要重点读的部分，因为它是前后端交互的第一道关卡。这套项目的登录流程是：前端把用户名和密码POST到后端登录接口，后端校验完用户表后，生成一个Token返回给前端；前端把Token存在本地，后续每个请求都在请求头中携带它；后端通过拦截器解析Token，判断当前请求是否合法。
我读代码时发现一个很实用的细节：Token里除了存用户ID，还存了角色标识，这样拦截器在鉴权时不需要频繁查数据库。这种做法在并发量不高的教学场景中性能足够，而且逻辑简单。对登录接口，源码统一返回了一个Result对象，包含了状态码、消息和数据，前端只需要判断状态码是200还是401，就能统一处理所有接口返回，而不需要在每个方法里单独处理异常。
2.2 报告提交与批改闭环
实验报告的核心数据表我梳理出来是这样的：实验任务表存了任务名称、所属课程、班级、截止时间；报告表存了提交人、所属任务、正文内容、附件路径、批改状态、分数和评语。提交报告时，学生填写富文本正文，上传附件（通常是实验截图或者PDF），后端先把文件保存到本地磁盘，同时把存储路径写入报告表，再把报告状态设置为已提交。
教师批改时，可以直接在线查看报告内容，录入分数和评语，然后系统把状态改为已批改。这里有一个很容易踩空的地方：如果学生在教师批改之后再次提交，报告状态必须变回待批改，否则教师看到的永远是老版本。源码中处理了这一点，提交时会把状态重置为待批改，分数和评语也被重置。
2.3 关系型表设计的关键字段
摘几个核心表的字段给大家参考：
| 表名 | 核心字段 | 说明 |
|---|---|---|
| user | id, username, password, role, real_name | 统一用户表 |
| course | id, course_name, teacher_id, semester | 课程表 |
| experiment_task | id, course_id, title, content, deadline | 实验任务表 |
| report | id, task_id, student_id, content, file_path, status, score | 报告表 |
这里的user表是角色合并设计，而不是学生表教师表分开建。我估计很多刚起步的开发者会疑惑为什么不拆开。合并的好处是登录接口不用区分路径，一个登录入口通吃三种角色；代价则是“学生”和“教师”的业务字段只能堆在同一张表里。在教学管理系统里，这个取舍是合理的，逻辑也更好扩展。
3. 部署环境准备与初始化
3.1 后端运行环境版本选择
部署一套SpringBoot项目，环境变量的细节决定成败。我使用的环境是JDK 1.8、Maven 3.6、MySQL 5.7。如果使用JDK 11或者JDK 17也不是不行，但要注意SpringBoot版本对应的兼容性，部分老版本SpringBoot在JDK 17下会出现反射相关异常。如果没有特殊原因，建议直接沿用官方文档给出的JDK和SpringBoot版本，不要盲目升级。
MySQL版本同样需要注意5.7和8.0的驱动差异。我在本地用的是MySQL 5.7，在配置数据源时驱动类写的是com.mysql.jdbc.Driver；如果换成8.0版本，需要改写成com.mysql.cj.jdbc.Driver，否则启动会直接报告驱动加载失败。
3.2 Node.js与前端环境
前端是Vue 2项目，Node版本建议12到14之间。Node 16及以上版本在npm install旧项目时，经常因为node-sass编译失败而卡住。如果遇到这个报错，可以使用node-sass替换为dart-sass的方案调整，或者直接用项目自带的package-lock.json安装依赖。
npm镜像这个问题也顺手提一下，国内网络环境直接安装依赖很慢，我习惯配置淘宝镜像源，安装速度会明显提升，而且基本不会出现SSL连接超时的问题。
3.3 初始化数据库的正确顺序
拿到源码后，我最先做的事情不是看代码，而是找到sql目录里的初始化脚本。一个常见的错误是直接把脚本整个复制到Navicat执行，如果表之间有关联外键或者脚本里包含删除重建语句，执行顺序就会变得非常重要。实际做法应该是：
- 先在MySQL中创建一个空数据库，字符集选utf8mb4，排序规则选utf8mb4_general_ci，避免中文乱码。
- 手动选择对应数据库，然后执行sql脚本，观察是否有报错。
- 开启MySQL日志开关，重点检查执行到哪一句时中断。
初始化完成后，我习惯先用SQL查询确认核心表已经创建成功，比如查询user表中是否存在初始管理员账号。如果脚本包含初始数据插入语句，管理员账号通常直接被写死在SQL里，登录密码可能是MD5加密后的值，直接使用初始账号登录最省事。
4. 源码本地启动与联调实操
4.1 后端启动前必须改的三个配置
在启动SpringBoot之前，必须确认application.yml或application.properties中的配置是否正确。需要改的地方往往是三个：数据源地址和账号密码、文件上传路径、端口号。
我这次启动时踩了一个小坑：pom.xml里引入了多个依赖，但配置文件中漏了MyBatis Plus的mapper扫描路径，导致所有和数据库相关的接口都报找不到映射语句。修改方式是在启动类上添加@MapperScan注解，或者在mapper接口上加@Mapper注解，二选一即可。另外，application.yml里如果配置了mapper-locations，要保证路径和实际的XML目录一致，否则也会出现绑定异常。
文件上传路径这个配置常被忽略，但它很重要。如果路径写的是相对路径，当项目以后台的JAR包方式部署在不同目录时，上传的文件就会落在不同的物理位置。我一般在配置中写一个绝对路径，比如/usr/local/upload，开发环境则直接写到项目的upload目录下，方便调试。
4.2 前端启动与API地址对接
前端项目通过npm install安装依赖，然后npm run serve启动。启动后浏览器访问localhost:8080，页面能打开，但登录会失败，这是新手最容易迷惑的一步。
问题基本都出在API地址和端口上。后端的默认端口一般是8080或8081，我在开发时把后端改成了8081，前端就需要去config目录下的index.js里修改代理配置，把target指向localhost:8081。项目里有代理配置的，直接改proxy即可；如果前端请求写的是完整域名地址，就需要找到request.js里的baseURL统一修改。
前端和后端的联调有一个快速定位技巧：登录时打开浏览器开发工具，切到Network面板，观察登录请求是否发出。如果请求是红色失败状态，看状态码是404、500还是401。404说明路径拼接不对，500说明后端接口异常，401说明没有权限或Token没带上。
4.3 本地功能验证清单
系统启动成功后，我不会直接认为万事大吉，而是按一条业务主线去走通它，这样能最大程度发现隐藏问题。我的验证清单是：
- 管理员登录，创建两个用户：一个学生、一个教师。
- 管理员创建课程，并把学生和教师加入课程。
- 教师创建实验任务，设定截止时间。
- 学生登录后，能看到实验任务并提交一篇报告，附带上传一张图片。
- 教师登录后，能看到学生的提交记录，完成打分。
- 学生端查看分数，管理员端查看统计结果。
任何一步出现异常，都能直接锁定到某一个模块。比如第四步上传失败，大概率是路径权限或上传大小限制的问题，不用在登录模块反复排查。
4.4 数据库脚本补充的重要提示
这里我想分享一个数据库层面的经验：即使初始化脚本能完整执行，也建议补一条半路修复方案。因为很多同学在自己录入测试数据时，会出现外键关联错误导致无法插入。最稳妥的方式是把强外键约束去掉，改为逻辑外键，也就是表结构里保留关联字段，但物理上不建外键约束。这项调整能避免后续测试数据录入时的很多痛苦，而且实际影响不大，毕竟业务量不大时，逻辑外键完全够用。
5. 代码讲解：几个值得细读的安全与性能点
5.1 登录与权限拦截器
我细读了后端的登录拦截逻辑，很有参考价值。登录成功后，系统用工具类生成了一个带有效期的Token，并把它放进Redis或者存到本地的事务管理框架中。每次请求进来时，拦截器会取出请求头中的Token并验证签名。如果签名不存在或过期，直接返回未认证状态。
一个细节是：拦截器只拦截需要认证的接口路径，而登录接口本身必须放行。否则会出现一个逻辑死循环——用户根本没有Token，却要求他先有Token才能访问登录接口。源码中使用了一个路径匹配列表，把这个层级的关系处理清楚了。前端路由守卫也做了类似处理：没有Token的请求一律跳到登录页，同时白名单放行了登录路径。
5.2 MyBatis Plus的分页处理
报表和实验任务列表都会用到分页，很多开发者习惯自己写LIMIT语句，但MyBatis Plus内置了分页插件，用起来会方便很多。我在读代码时看到，源码的分页查询是先配置一个分页插件，然后在查询方法中直接传入页码和条数。要注意的是，没有配置分页插件时，分页参数会被忽略，这时候无论传什么页面参数，SQL执行的都只是普通查询，很容易出现“分页失效”的假象。
所以如果后期你基于源码二次开发，遇到列表接口分页不生效，优先检查配置类中是否注入了MyBatis Plus的分页插件，这是我自己在这个项目上踩过的比较隐蔽的坑。
5.3 文件上传与路径安全
报告附件上传是这个系统的重要一环。源码里封装了文件上传的公共方法，主要逻辑是校验文件大小、生成新文件名、保存到指定目录。文件名生成方式很有讲究，源码使用了时间戳加随机数的方式拼接，基本杜绝了重名覆盖问题。这里有个安全细节容易被忽略：用户上传的文件名如果原样保留，包含中文和空格，轻则访问时URL编码出错，重则可能被特殊处理。稳妥做法是后端统一用UUID或时间戳重命名，尽量不依赖用户提交的原始文件名。
此外，文件下载接口必须做权限验证，不能把上传目录配置成静态资源直接暴露出去了。如果配置成静态资源目录，任何知道文件路径的人都可以绕过登录直接访问附件，这在提交实验报告的系统中属于权限绕过漏洞，务必避免。
6. 部署打包与服务器上线实践
6.1 后端Maven打包与启动脚本
部署到服务器时，后端需要打成可执行的JAR包。在项目根目录执行mvn clean package命令，完成后到target目录下找到以jar结尾的文件，通过java -jar命令启动即可。
但要注意，打包时配置文件是否被一起打进去是常见问题。如果你的数据库密码写的是本地密码，打包部署到服务器后就会连接不上。我的做法是把配置文件外置，服务器上单独放置一份application-prod.yml，在启动命令中通过--spring.profiles.active指定使用哪个环境配置，这样本地和线上配置互不干扰。
后台运行方面，直接java -jar运行，窗口一关进程就没了。我是用nohup配合&让进程后台运行，并把日志打到独立文件中，方便后续排查问题。进程占用端口后要连续启动，可能会出现端口被占用的报错，这时候用netstat命令查到对应PID杀掉即可。
6.2 前端项目打包与Nginx配置
前端在部署前需要先执行npm run build，生成dist静态目录。这个目录里的文件不依赖Node环境，只需要任意一个Web服务器托管即可。最常见的方案是Nginx托管，但配置上有两个注意点：
第一个是代理转发。前端请求/api/xxx这类接口路径时，Nginx需要把请求反向代理到后端的实际地址。我之前见过一个部署失败案例，前端页面能打开，但登录一直报跨域，原因是Nginx配置里没有把接口请求转发，浏览器直接向后端地址发起了跨域请求。代理配置是这样的形态：当路径匹配到API前缀时，通过proxy_pass指令转向后端服务。需要注意proxy_pass末尾是否带/，这个细节非常影响路径拼接结果，带不带是完全不同的效果。
第二个是前端路由history模式的刷新404问题。Vue Router如果使用history模式，部署到Nginx后直接刷新当前页面会出现404，因为服务器上根本找不到这个路径对应的物理文件。解决方法是在Nginx配置中加入fallback配置，让所有找不到的资源都回退到index.html。这类问题在本地开发时不会遇到，因为开发服务器已经做了处理，只有部署到正式环境才会暴露。
6.3 跨域配置的正确解法
开发环境联调时，跨域问题可能通过代理或前端配置解决，但线上环境如果前后端域名不同，跨域要由后端解决。SpringBoot中可以用@CrossOrigin注解，也可以在WebMvcConfigurer里配置统一的跨域映射。常用的写法是允许所有来源、所有请求头、所有方法，并且在跨域配置中开放自定义请求头的权限。
如果配置了自定义Token请求头，跨域预检请求中必须显式允许这个头，否则浏览器会拦截真正的POST请求。我调试这类问题的方法就是观察请求类型，如果出现OPTIONS请求被拦截，基本就是跨域头配置不全。这里是很多开发者最容易忽略、也最耗费时间的点。
7. 常见问题与排查技巧实录
7.1 后端能启动但接口全部401
刚启动项目时，接口返回401是整个系统中极易遇到的现象。不要先怀疑数据库，先检查Token的生成密钥和拦截器校验密钥是否一致。有些项目把密钥放在配置文件中，如果你在配置文件中改动了密钥，但前端存储的还是旧Token，自然校验不通过。此时清除浏览器本地存储，重新登录一次，问题通常就解决了。
7.2 图片上传成功但访问不了
上传成功但前端展示不了图片，这类问题八成出在访问路径上。上传目录是哪个物理路径，前端访问时拼接的URL就需要能映射到这个路径。如果后端配置了静态资源映射，路径写错就会404。排查方法是直接用浏览器访问文件地址，看返回是404还是二进制数据，只要访问路径和物理存储路径能对上，问题立刻定位。
如果是在服务器上部署，还要检查磁盘目录的读写权限。一个小组件目录权限不足，上传接口也会报IOException，这类问题不看服务端日志很难发现。
7.3 数据库连接失败与时区问题
数据库连接失败要分三种情况看：数据库服务没有启动、账号密码错误、网络不通。启动前先用命令行工具测试一下连接，能连上再启动后端，这样最省时间。
时区问题也是高频报错。MySQL连接串中如果不加serverTimezone参数，在部分版本驱动下面会直接报时区异常。解决办法是在JDBC连接串末尾加上serverTimezone=Asia/Shanghai和useUnicode=true、characterEncoding=utf8，保证中文不乱码。
7.4 npm install安装依赖失败
前端依赖安装失败是与环境版本最相关的顽固问题。一个有效策略是删除node_modules目录和package-lock.json，重新安装。如果还是失败，降低Node版本重新安装。如果项目依赖中存在node-sass，优先把package.json中依赖项改为sass和dart-sass，再重新安装。
这是一套典型的教学类全栈项目，我在部署和阅读源码的过程中，把前后端联调、权限控制、文件存储、服务器部署这几个环节都完整走了一遍。踩过的坑不多，但都有代表性，从数据库时区到Node版本，再到跨域头和路由刷新404，每一个都是真实生产环境会遇到的问题。对于准备拿这套系统做课程设计或者二次开发的同学，我建议不要过早动手改代码，先把它完整跑通，再对照业务主链读一遍关键模块的代码，这个顺序带来的理解效率远比直接找代码问题要高得多。
我自己的经验是，给这类系统做扩展也不用急于引入太多依赖，先在这个基础项目里把日志、统一异常处理、参数校验这些工程化细节补上，等业务复杂到一定阶段，再考虑引入更多中间件和服务拆分。把基础打扎实了，后续的每一步才走得更稳。
