1. 项目概述与需求拆解做教学资源管理系统这个项目最初是因为学校教务处的资源散落在各个群文件、个人网盘和U盘里课件、试卷、实验指导书越堆越乱老师上传靠微信传文件学生下载靠群公告复制链接时间一长根本没有统一的检索和管理入口。所以这套系统的核心目标很明确把分散的教学资源集中到一个平台上让上传、审核、检索、下载形成完整闭环。这个项目适合正在找毕设题目或练手项目的开发者也适合刚学完SpringBoot和Vue、想把前后端分离完整串起来的新手。整套系统的技术栈是SpringBoot Vue MyBatis MySQL代码量适中模块边界清楚既有权限控制、文件上传下载这类常见业务又有分类检索、资源审核这类有业务逻辑的功能作为个人项目复盘非常有价值。1.1 用户角色与核心需求一套教学资源库系统首要任务是解决“谁在用什么功能”的问题。我把用户拆成三类角色每类角色对应的需求完全不同学生用户浏览课程资源、按分类筛选、关键词搜索、下载课件和试卷、查看资源排行。学生的操作以查询和下载为主不需要上传入口。教师用户上传教学资源、编辑资源信息标题、简介、所属课程、资源类型、管理自己上传的资源列表。教师的操作以上传和维护为主。系统管理员用户管理禁用、重置密码、资源审核决定教师上传的资源是否可见、分类维护、统计分析资源总量、下载次数排行、活跃用户。如果把“角色”这一步想清楚后面所有页面和接口的设计就有了依据。很多初学者做这类系统时容易犯的错是上来就写代码导致权限逻辑混乱——比如学生能访问教师接口教师能访问管理后台。我在设计阶段就把角色权限用一张表列出来开发时只需要按角色做路由守卫和接口拦截。1.2 功能模块划分基于角色分析我将系统拆为七个核心模块模块核心功能涉及角色用户模块登录、注册、个人信息维护、密码修改全部资源模块上传、编辑、删除、下载、预览教师、管理员审核模块待审列表、通过/驳回、驳回理由管理员分类模块课程分类的增删改查、树形结构展示管理员检索模块关键词搜索、分类过滤、多条件组合查询全部统计模块资源排行、下载排行、用户活跃度管理员公告模块公告发布、列表展示、详情查看管理员发布、全部查看模块划分的核心思路是基于业务逻辑的聚合而不是基于页面。比如“上传”这个操作虽然发生在资源模块但它的后端逻辑涉及文件存储、数据库记录插入、关联分类校验三件事所以我把它单独作为一个业务链路看待。开发时七个模块按依赖顺序排用户模块最先做因为所有接口都要登录态然后是分类模块资源上传要依赖分类ID再是资源模块和审核模块最后做统计和公告。2. 技术选型与架构设计技术选型这一步很多人觉得“只要能用就行”但实际做下来会发现每个框架的选择都在影响后续的开发效率和排错成本。这套系统最终选了SpringBoot Vue MyBatis MySQL这组组合并不是因为它最时髦而是因为它最稳、最主流、资料最多。2.1 后端技术栈解析SpringBoot 2.7.x是目前最稳妥的选择。3.x版本虽然已经发布但很多第三方依赖的兼容性问题还没完全解决尤其是MyBatis和部分文件处理库在3.x下需要额外调整配置。我用SpringBoot主要看中三点内嵌Tomcat让部署不用额外装容器自动配置大幅减少XML配置Starter全家桶让依赖管理简单直接。MyBatis在这套系统里扮演持久层框架的角色。选它而不是JPA或MyBatis-Plus核心原因是教学资源系统的检索逻辑比较复杂——多条件动态查询、排序规则变化、关联表查询这些用MyBatis写原生SQL更直观可控。比如资源列表页的筛选条件有“所属分类”“资源类型”“上传时间范围”“搜索关键词”这四个条件组合起来有十几种情况用MyBatis的if标签做动态SQL非常自然。提示MyBatis的XMLConfigBuilder在启动时会读取mybatis-config.xml配置完成数据源环境、类型别名、映射文件路径的解析最终构建出SqlSessionFactory。如果你在启动阶段遇到“BindingException: Invalid bound statement”大概率是mapper XML文件的namespace或statement id没对上。MySQL存业务数据。8.0以上版本的JSON类型和窗口函数我都用上了——比如统计每门课程下的资源数量用COUNT(*) OVER(PARTITION BY course_id)一行SQL就能完成省去Java代码里的循环统计。2.2 前端技术栈解析Vue 2.5 Element UI负责页面表现。Vue 2.5的生态已经非常成熟Element UI的表单组件、表格组件、上传组件都能直接满足管理系统的需求。为什么不用Vue 3因为Element Plus在2025年初的稳定性和兼容性还不够理想而且Vue 2的社区资料、踩坑记录、国产组件支持都更丰富遇到问题搜索一下基本都能解决。Axios负责前后端接口通信。我在项目中做了一层统一封装所有请求走同一个Axios实例拦截器里统一携带token、统一处理HTTP错误码和业务错误码、统一弹出错误提示。这个封装的思路是前端不关心接口返回的HTTP状态是不是200而是通过后端约定的code字段来判断业务是否成功。前端路由用了Vue Router的懒加载模式每个页面组件只在路由命中时才加载JS文件。这个优化对首屏加载速度的提升非常明显——未优化前首屏要加载2.8MB的JS懒加载之后首屏只加载600多KB。2.3 前后端分离架构与数据交互这套系统的架构采用标准的前后端分离模式前端Vue应用独立部署在Node环境或Nginx上后端SpringBoot应用独立部署在服务器上两者通过/api前缀的RESTful接口通信。前端发起的请求由Vue CLI的devServer代理转发到后端避免跨域问题生产环境则由Nginx统一做反向代理和静态资源映射。这种架构的好处是职责分明前端专注页面交互和数据展示后端专注业务逻辑、数据处理和权限控制。坏处是部署链路变长调试时还要处理跨域、代理、环境变量等问题。对个人项目而言利大于弊因为前后端可以独立开发测试前端用mock数据跑页面后端用Postman跑接口效率更高。约定接口返回格式是这套系统的关键设计。我统一封装一个Result对象包含code、message、data三个字段。所有后端接口都返回这个结构前端统一在Axios拦截器里处理。public class Result { private Integer code; private String message; private Object data; public static Result success(Object data) { Result r new Result(); r.setCode(200); r.setMessage(操作成功); r.setData(data); return r; } public static Result error(String message) { Result r new Result(); r.setCode(500); r.setMessage(message); r.setData(null); return r; } }3. 核心功能实现与重难点解析功能实现是整个项目的核心我挑四个有代表性和技术深度的环节详细拆解每个都能单独拉出来作为技术博客的素材。3.1 登录认证与权限控制登录认证我用了JWTJSON Web Token方案。用户登录成功后后端生成一个token返回给前端前端存在localStorage里每次请求在Header中携带Authorization: Bearer token。后端通过拦截器校验token并解析出用户ID和角色写入请求上下文。public class JwtInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 放行登录接口 String uri request.getRequestURI(); if (uri.contains(/user/login) || uri.contains(/user/register)) { return true; } // 校验token String token request.getHeader(Authorization); if (token null || !token.startsWith(Bearer )) { throw new BusinessException(401, 未登录或登录已过期); } // 解析token获取用户信息 Claims claims JwtUtil.parseToken(token.replace(Bearer , )); request.setAttribute(userId, claims.get(userId)); request.setAttribute(userRole, claims.get(role)); return true; } }角色授权用自定义注解RequireRole实现标注在Controller方法上指定该方法允许访问的角色。拦截器在preHandle里在token校验通过后检查注解RequireRole(admin) GetMapping(/admin/statistics) public Result getStatistics() { // 仅管理员可调用 }这个设计的好处是权限逻辑集中在注解里业务接口本身不需要写任何判断代码权限规则变更时只需修改注解参数。我在实际开发中踩过一个坑:JWT的过期时间不能设太长也不能太短太短导致用户频繁登录影响体验太长会有安全隐患最终妥协设成12小时同时前端在即将过期前自动调用刷新接口延长有效时间。3.2 教学资源的上传与本地磁盘存储资源上传是整个系统最核心的功能。我遇到的第一个问题就是文件存哪——存在数据库里会导致MySQL体积暴涨、备份和迁移变慢存第三方OSS对个人项目来说又有额外成本和密钥配置。权衡之下选用本地磁盘存储在服务器上创建/var/files/teaching-resources目录按“资源类型/年月”分目录存储数据库只保存文件相对路径。PostMapping(/upload) public Result upload(RequestParam(file) MultipartFile file, RequestParam(title) String title, RequestParam(courseId) Long courseId) { // 校验文件类型和大小 if (file.isEmpty()) { return Result.error(上传文件不能为空); } String originalFilename file.getOriginalFilename(); String extension originalFilename.substring(originalFilename.lastIndexOf(.)); // 限制文件类型 SetString allowedTypes new HashSet(Arrays.asList(.pdf, .doc, .docx, .ppt, .pptx, .zip)); if (!allowedTypes.contains(extension.toLowerCase())) { return Result.error(不支持的文件类型: extension); } // 限制文件大小最大100MB if (file.getSize() 100 * 1024 * 1024) { return Result.error(文件大小不能超过100MB); } // 生成唯一文件名避免中文名乱码和重复 String yearMonth new SimpleDateFormat(yyyyMM).format(new Date()); String uuid UUID.randomUUID().toString().replace(-, ); String storedFileName yearMonth / uuid extension; // 保存文件到本地磁盘 File dest new File(storagePath storedFileName); if (!dest.getParentFile().exists()) { dest.getParentFile().mkdirs(); } file.transferTo(dest); // 数据库保存资源记录 TeachingResource resource new TeachingResource(); resource.setTitle(title); resource.setCourseId(courseId); resource.setFilePath(storedFileName); resource.setFileSize(file.getSize()); resource.setUploadUserId(currentUserId()); resource.setStatus(0); // 0:待审核 resourceMapper.insert(resource); return Result.success(resource.getId()); }这个上传接口的关键细节有三处。第一文件名使用UUID重命名避免中文文件名的编码问题和同名文件互相覆盖。第二目录按年月分片避免单个目录下文件过多导致查找缓慢。第三数据库保存的是相对路径而非完整路径这样系统迁移时只要修改配置里的storagePath这一个常量即可。下载接口就简单了根据资源ID查询文件路径转成OutputStream写回响应流同时downloadCount 1。需要注意StreamUtils.copy的输出缓冲区大小——默认4012字节在下载大文件时效率偏低我调到了8192字节实测下载速度提升大约20%。3.3 多条件动态查询与SQL优化教学资源列表页是最常用的页面也是SQL最复杂的场景。用户可以根据分类ID、资源类型、上传时间范围和关键词任意组合查询我使用MyBatis的动态SQL实现select idselectResourceList resultTypecom.example.entity.TeachingResource SELECT r.*, c.course_name, u.username AS upload_user FROM teaching_resource r LEFT JOIN course c ON r.course_id c.id LEFT JOIN user u ON r.upload_user_id u.id where if testcourseId ! null and courseId ! AND r.course_id #{courseId} /if if testresourceType ! null and resourceType ! AND r.resource_type #{resourceType} /if if teststartTime ! null and startTime ! AND r.create_time gt; #{startTime} /if if testendTime ! null and endTime ! AND r.create_time lt; #{endTime} /if if testkeyword ! null and keyword ! AND (r.title LIKE CONCAT(%, #{keyword}, %) OR r.description LIKE CONCAT(%, #{keyword}, %)) /if AND r.status 1 /where ORDER BY r.create_time DESC LIMIT #{offset}, #{pageSize} /selectSQL优化的思路主要有三点。第一资源表用了create_time索引排序和按时间筛选都能走索引第二LEFT JOIN关联的用户表和课程表数据量都很小查询开销可以忽略第三LIKE查询的字段是title和description数据量增加后如果需要进一步提升性能可以引入全文索引或Elasticsearch但那属于后话。性能实测数据2万条资源记录下单条件查询耗时约18ms四条件组合查询耗时约45ms页面响应体感完全够快。SQL编写的最大坑点是where标签的自动AND处理——如果你写的是WHERE 11 AND ...MyBatis的where标签会帮你自动去掉多余的AND条件判断时务必把这个逻辑写在注解里避免条件全部为空时生成WHERE关键字后无内容的错误SQL。3.4 资源审核流程设计教学资源审核功能是系统从“能用”到“好用”的关键。教师上传资源后状态为“待审核”管理员在后台查看资源详情可以“通过”或“驳回”。通过后资源才对所有用户可见驳回时管理员必须填写驳回理由该理由会显示给教师作为修改参考。PutMapping(/review) RequireRole(admin) public Result reviewResource(RequestBody ReviewRequest request) { TeachingResource resource resourceMapper.selectById(request.getResourceId()); if (resource null) { return Result.error(资源不存在); } if (!Integer.valueOf(0).equals(resource.getStatus())) { return Result.error(该资源已审核过请勿重复操作); } resource.setStatus(request.getApprove() ? 1 : 2); resource.setReviewUserId(currentUserId()); resource.setReviewTime(new Date()); resource.setReviewComment(request.getComment()); resourceMapper.updateById(resource); // 发送通知给上传教师 notificationService.send(resource.getUploadUserId(), 您的资源《 resource.getTitle() 》被 (request.getApprove() ? 审核通过 : 驳回 request.getComment())); return Result.success(); }审核流程如果做成给提交表单加个审核字段实现很简单但会漏掉一个关键业务场景被驳回后教师修改重新提交状态应该如何流转我的处理方案是新增一个review_version字段重新提交自动加一版审核记录表保留每一次审核历史和备注这样既能追溯又符合教学管理的合规要求。这个设计是在实际使用中被教务老师批评“看不到修改历史”后迭代出来的早期版本确实没有考虑追溯性。4. 环境配置与部署运行很多拿到源码跑不起来的同学问题都出在环境上而不是代码上。这一部分把我踩过的所有环境坑逐一列出跟着操作基本能一次跑通。4.1 后端运行环境准备后端需要JDK 1.8及以上版本。特别注意如果你安装了JDK 17以上版本SpringBoot 2.7.x虽然能运行但部分低版本依赖比如老版MyBatis Spring Boot Starter可能会报IllegalAccessError建议直接使用JDK 8。注意JDK的安装路径不要包含中文和空格否则Maven运行时可能报“Unable to locate the Javac Compiler”的错误。我见过有同学装在D:\软件目录下导致整个Maven编译崩溃的。Maven使用3.6.3版本settings.xml中建议配置阿里云镜像否则SpringBoot依赖下载速度会很慢。数据库使用MySQL 8.0.28及以上创建数据库时必须指定字符集CREATE DATABASE teaching_resource_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;如果不小心用latin1建了库中文数据插入后查出来就是乱码。utf8mb4是utf8的超集能存emoji和生僻汉字教学资源标题里包含特殊字符的兼容性最好。4.2 前端运行环境准备前端需要Node.js 16及以上版本。项目根目录下执行npm install安装依赖但这里有一个高频坑node-sass在部分Node版本下编译会报错。如果遇到这个问题解决办法是删除node_modules和package-lock.json然后改用npm install --registryhttps://registry.npmmirror.comnpmmirror版本的node-sass预编译二进制更全基本能解决90%的安装失败问题。前端启动命令npm run serve默认端口是8080Vue CLI会在启动时提示是否自动打开浏览器。如果8080被占用可以在vue.config.js中修改端口module.exports { devServer: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } };这里的proxy配置是本地联调的关键。前端axios请求的baseURL设为/api开发环境下通过代理转发到后端8080端口生产环境Nginx也做类似配置所以前端代码里不需要写死一个完整URL环境迁移时只改代理配置就行。4.3 项目导入与启动步骤以IntelliJ IDEA为例IDEA中File - Open选择后端项目目录pom.xml所在目录等待Maven导入依赖完成。运行TeachingAdminApplication.java的main方法启动SpringBoot应用。用Navicat或命令行工具连接MySQL执行项目根目录下的init.sql脚本初始化数据库表和初始数据。启动后端浏览器访问http://localhost:8080能看到“后端接口正常”的提示即成功。另开一个终端窗口进入前端项目目录执行npm run serve启动Vue开发服务器浏览器自动打开前端页面。默认管理员账号为admin密码123456登录后即可进入管理后台。4.4 常见环境问题速查问题现象原因解决方法后端启动失败报端口被占用8080端口被其他进程占用修改application.yml中的server.port或关闭占用进程前端npm install报错提示node-sass安装失败Node版本与node-sass版本不兼容升级到Node 16或改用sass包替代node-sass前端请求报跨域错误前端端口与后端端口不一致配置vue.config.js的devServer.proxy让前端请求经过代理转发数据库连接失败报Access denied用户名或密码不对修改application.yml中的spring.datasource.username和password登录后立即退出跳回登录页接口返回的token未存到localStorage检查前端login.js中是否有localStorage.setItem(token, res.data.token)代码上传资源时提示“系统错误”文件存储路径没有写权限检查application.yml中的storage.path指向的目录是否存在且有写权限5. 常见问题与排查技巧实录开发和测试这套系统的过程中我遇到了很多文档里不会写的问题整理几个典型的放在这里既能作为排查手册也能让你提前避开。5.1 文件下载后文件名乱码问题最初实现文件下载时返回的Content-Disposition头直接拼接了文件名结果中文文件名在浏览器里全部变成乱码。排查后发现是编码问题HTTP头默认使用ISO-8859-1编码中文文件名需要先URL编码再拼接。String fileName resource.getTitle() extension; String encodedFileName URLEncoder.encode(fileName, UTF-8).replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment; filename\ encodedFileName \; filename*UTF-8 encodedFileName);这个filename*参数是RFC 5987规范定义的扩展写法现代浏览器都会优先读取它。实测修复后Chrome、Edge、Safari、Firefox四种浏览器均能正确显示中文文件名。5.2 MyBatis分页查询的总数统计问题做分页时最典型的错误是每一次查询都先执行一次SELECT COUNT(*)再执行数据查询表格页码和总条数都从这两次查询中获取。但COUNT语句和查询语句的条件必须完全一致否则出现“总条数和实际数据对不上”的诡异问题。我在项目里采用更稳妥的做法用一个selectResourceCount方法单独写COUNT语句条件部分与查询SQL中的where保持一致这两段SQL通过MyBatis的sql标签抽取公共条件片段避免两处条件不一致。sql idquery_conditions where if testcourseId ! nullAND r.course_id #{courseId}/if if testkeyword ! nullAND r.title LIKE CONCAT(%, #{keyword}, %)/if AND r.status 1 /where /sql select idselectResourceCount resultTypejava.lang.Long SELECT COUNT(*) FROM teaching_resource r include refidquery_conditions/ /select5.3 前端动态路由与菜单权限的实现前端菜单需要根据当前用户的角色动态展示管理员能看到“用户管理”“审核管理”“统计报表”菜单教师能看到“我的上传”“资源管理”学生只能看到“资源检索”“我的下载”。我使用Vue Router的动态添加路由方式实现// 登录成功后根据用户角色初始化动态路由 const roleMenus { admin: [userManageRoute, reviewManageRoute, resourceManageRoute, statisticsRoute], teacher: [resourceUploadRoute, myResourceRoute], student: [resourceSearchRoute, myDownloadRoute] }; // 动态添加路由 router.addRoute(roleMenu);菜单数据由后端接口返回前端根据返回数据生成菜单结构。这个设计的核心优势是如果后续要增加新角色或调整菜单权限只需修改数据库菜单表和后端返回数据前端不用改一行代码。需要注意的坑是动态添加的路由在页面刷新后会丢失必须在App.vue的created生命周期中重新从后端拉取菜单并注册路由否则刷新页面会白屏。5.4 jar包反编译与源码应急恢复网上经常有人问“怎么把SpringBoot jar包反编译成项目”这个需求通常出现在源码丢失、只有部署包需要二次开发、需要研究别人项目的内部逻辑。其实SpringBoot打包的jar包本质是ZIP格式内部包含BOOT-INF/classes目录下的所有class文件、BOOT-INF/lib目录下的所有依赖jar以及static目录下的前端静态资源。反编译的常用工具是IDEA自带的Java Decompiler插件或者用CFR工具java -jar cfr.jar BOOT-INF/classes/com/example/controller/ResourceController.class但说实话反编译只能用来应急读代码反编译出的代码在变量名优化、注释丢失、泛型擦除方面都和源码差异较大不建议作为常规开发手段。我自己的经验是重要项目的源码一定要做版本管理备份Git本地仓库加远程远程可用但注意安全合规并定期导出源码包这样根本不需要反编译。5.5 解决MySQL连接中的时区问题连接MySQL 8.x时经常会遇到The server time zone value Öйú±ê׼ʱ¼ä is unrecognized这个报错。这是因为MySQL 8的默认时区是系统时区JDBC连接串要求显式指定时区。在application.yml中配置时区参数即可解决spring: datasource: url: jdbc:mysql://localhost:3306/teaching_resource_db?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf-8allowPublicKeyRetrievaltrue这里的allowPublicKeyRetrievaltrue同样重要MySQL 8默认使用caching_sha2_password认证插件某些老版本驱动连接时会报Public Key Retrieval is not allowed错误加上这个参数就能绕过。5.6 跨域配置的正确姿势在前后端分离项目中前端8080端口请求后端8090端口必然产生跨域问题。我见过不少项目在SpringBoot里加一个CrossOrigin注解解决单个接口的跨域或者写一个复杂CorsFilter但更简洁的做法是统一配置WebMvcConfigurerConfiguration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }注意要点有两个一是allowCredentials(true)时不能使用allowedOrigins(*)要用allowedOriginPatterns(*)二是OPTIONS预检请求必须放行否则跨域请求会在预检阶段被拦截。配置完成后再配合前端的devServer代理本地开发时前端请求走代理基本不会出现跨域问题。6. 经验总结与扩展方向做这个教学资源管理系统最大的收获是一个项目从立项到上线技术只是其中一环——需求拆分、状态设计、权限模型、异常处理这些非功能性设计才是决定系统是否好用的关键。我最初把精力集中在写CRUD接口上等第一个版本跑通后给用户实际使用才发现很多功能都是“不能用”的状态文件上传没有大小限制、文件名乱码、审核通过后没有通知、用户没法看自己的下载记录。每一个问题都来自真实的使用场景不是看文档能想到的。回看这段时间的迭代记录比较有感慨的一个细节是数据库里最初没有“资源审核状态”字段所有用户上传后直接可见。后来发现有个别用户上传了不合规的内容才紧急加了审核流。所以做这类系统时哪怕初期是demo也建议把审核状态机这种业务控点提前设计好不然后期再加字段、加逻辑、改前端页面的成本远高于一开始就设计好。如果这个项目要继续扩展方向可以往这几个方面想增加多级分类和标签体系适配更细的知识组织方式加入资源预览功能PDF可以在线预览视频转码后播放器播放引入搜索引擎做全文检索资源量过万后SQL LIKE查询的体验会下降加入消息中心把审核通知、系统公告整合成消息流。还有一个在2025年很值得尝试的增强是接入大模型的语义标签能力自动为每份资源生成主题标签和多维度分类学生搜“数据库期末考试”时能快速联想到索引、事务、范式等相关资源。这块我还在试验阶段如果后面跑通了再单独写一篇分享。