1. 起因：教学资源乱成一锅粥，才决定动手做这个库

先交代一下背景。我们这边是搞创客教育的团队，课程横跨图形化编程、开源硬件、3D建模几个方向，老师和助教加起来十几号人，积累的教案、课件、代码示例、电路图、视频素材少说也有几千份。听起来资源很多是好事，但乱起来真要命。有人把课件传在群里，有人把视频放在网盘，有人把教案发在自己电脑里，还有人把学生作品截个图随手扔在共享目录。临到上课前十分钟，满世界找素材是常态；新来的助教想了解某节课的历史资料，问了一圈也凑不齐。

我最初的想法很简单，把散落的文件归拢起来，做一个统一入口。但做了一段时间之后发现，光有文件管理还不够，需要一套真正贴合教学场景的“资源库”：

• 老师上传资料时，最好能按课程、年级、课时分类；
• 搜索要快，按关键词几秒钟内能找到某一节课的配套素材；
• 资源要有审核流程，避免有人直接把未经校对的内容共享给学生；
• 学生端最好也能访问部分资源，比如课堂演示视频、作业要求。

就这样，"小码创客教育教学资源库"这个项目立项了。技术选型上，我结合团队现有人员的技术栈和对稳定性的要求，最终确定后端用 SSM（Spring + Spring MVC + MyBatis），前端用 Vue。项目本身不复杂，但麻雀虽小五脏俱全，从资源上传、在线预览、标签检索，到用户权限、审核流程、课程关联，整个过程走下来，有很多细节值得展开聊聊。

这篇文章就是把这个项目的完整过程做一个复盘，包括为什么选这套技术栈、核心功能模块怎么设计、前后端联调时踩过的坑、上线之后遇到的实际问题。如果你是做教育类系统、内容管理类系统，或者想拿一个完整的SSM+Vue项目做练手，这篇应该能给你一些参考。

2. 技术选型的真实考量：为什么是SSM+Vue，而不是其他组合

2.1 后端框架选型：SSM在这个场景下反而合适

先说明一点，这个项目立项的时候，Spring Boot 已经非常成熟了。如果从零开始完全不受约束，我大概率会选 Spring Boot。但真实情况是，团队里几位核心开发对 Spring MVC + XML 配置的方式非常熟悉，手头还有几个维护了很多年的老项目都是这套体系，新系统上线之后也需要这些同事来接。与其让他们重新学一套注解体系和自动配置逻辑，不如保持技术栈一致性。

另外，资源库这个项目的复杂度并没有想象中高。系统主要做的就是对教学资源的增删改查、文件上传下载、用户鉴权、审核流转，这些操作 SSM 完全可以胜任，而且 MyBatis 在手写复杂 SQL 时优势很明显。举个例子，按课程名、资源类型、上传时间、标签多条件组合查询，这种逻辑我用 MyBatis 的动态 SQL 写起来非常顺手，用 JPA 反而要花不少时间调方法命名。

选型时也考虑过微服务。我的结论是，一个内部教学资源库，用户量撑死了几百号人，搞一套注册中心、网关、配置中心纯属给自己找麻烦。单体应用 + 合理的模块分包，部署维护成本低得多。

2.2 前端框架选型：Vue + Element UI 的开发效率确实高

前端选 Vue 的原因也很直接：生态成熟、上手快，组件库丰富。尤其 Element UI 这类组件库，表格、表单、上传、弹窗都是现成的，做后台管理系统效率极高。资源库这类系统，80% 的界面都是“左侧菜单 + 顶部操作栏 + 中间表格/卡片列表”，用 Vue + Element UI 基本上就是搭积木。

有一个点值得说说，就是前端我用的是 Vue CLI 手搭的项目，而不是直接拿现成的后台管理模板。原因是我希望项目的依赖尽量精简，模板里夹杂了一堆用不上的图表库、地图组件、mock 数据，体积大不说，出问题都不好定位。自己搭的话，核心依赖就这几样：

实际开发下来，这套组合非常顺手。可能有人觉得 Vue 2 已经过时了，但这个项目是团队内部使用的系统，功能稳定、浏览器兼容性好是第一位的，Vue 2 完全可以满足要求，没必要为了追新而追新。

2.3 文件存储与数据库设计的前置考虑

资源库的核心资产就是各类教学文件。我做的第一个决策是：文件本体用本地磁盘存储，数据库只存文件元数据。原因很简单，团队规模决定了我们不可能专门维护一套对象存储服务，而本地磁盘挂载一个独立的目录，操作起来最简单直接。

这里也考虑过用 FastDFS или MinIO，但如果单机部署，这些组件的运维成本完全没必要投入。我在服务器上单独分了一个/data/resources目录，按日期和资源类型做二级目录存储，后面我会讲这个目录规则的具体设计。

数据库方面，MySQL 5.7，之所以没用 MySQL 8.0，是因为服务器上已经装好了 5.7，而且生产环境稳定运行过很长时间，没必要为这个项目冒险升级。表结构设计在后文会详细拆解。

3. 核心功能模块拆解：一个教学资源库具体要做什么

3.1 功能地图：六大核心模块

结合一线教学的实际使用场景，我把资源库划分成了六个核心模块：

这个模块划分是在实际使用中一步步迭代出来的。最开始我设想的是做一个“资源超市”，谁都能上传谁都能下载，但发现不行，没有审核机制会导致资源质量参差不齐。后来加入了审核环节，又发现如果只是素材文件而没有跟课程关联，老师在备课时还是不知道这节课该用什么资源，于是又加了课程关联。

3.2 数据库设计：核心表结构与设计思路

数据库设计是整个项目的基石，我花了不少时间梳理表结构。核心表一共有这么几张：

用户表user

角色这里没有设计成用户-角色-权限三张表，因为我们的角色只有三种，权限矩阵很固定，用一张表加一个角色字段就够了。过度设计反而会增加理解成本。

资源表resource

分类表category

课程表course

这里要重点说一下目录设计。前面提到文件存储在/data/resources下，我使用的规则是/data/resources/课程名/资源类型/日期_文件名。比如：

/data/resources/Scratch进阶/课件/20230508_第一课循环结构.pptx /data/resources/scratch进阶/代码/20230508_追光小车.sb3 /data/resources/Microbit入门/教案/20230506_心跳爱心.md

这样做的好处是，即使数据库不小心损坏了，系统管理员在服务器上按目录结构也能找到对应文件。文件路径里拼接文件名之前，一定要过滤掉用户传入文件名中的特殊字符，否则路径穿越漏洞很容易被利用。

3.3 用户角色与权限边界

三种角色对应的权限边界，我用人话梳理一下：

• 管理员：可以审核任何人的资源；可以管理所有分类和课程；可以查看全站数据统计；可以禁用账号；可以删除任意资源。
• 教师：可以上传资源、编辑自己的资源、申请资源关联课程；可以查看所有已经审核通过的资源并下载。
• 学生：只能在资源广场中查看已审核通过的资源；可以下载部分开放下载的资源（比如课堂演示文稿、作业要求）；不能上传。

权限在后端通过 Spring MVC 的拦截器实现。前端只是做菜单展示控制，真正要卡的还是后端接口，这个细节在后文会展开。

4. 后端实现细节：SSM 里的核心代码与配置

4.1 统一响应体与全局异常处理

前后端联调时最容易扯皮的就是数据格式不一致。后端同学今天返回一个{code: 200, data: null}，明天返回一个{success: true, msg: "ok"}，前端同学迟早要崩溃。所以我在项目一开始就定了一个统一的响应封装：

public class Result<T> { private Integer code; // 200成功，400参数错误，401未登录，403无权限，500系统异常 private String message; private T data; public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.code = 200; result.message = "success"; result.data = data; return result; } public static <T> Result<T> error(Integer code, String message) { Result<T> result = new Result<>(); result.code = code; result.message = message; return result; } }

配套的全局异常处理做一个@ControllerAdvice，把业务异常和系统异常统一拦截，前端只需要判断code是否为 200 即可进入正常流程。

4.2 登录认证与接口鉴权：拦截器的正确写法

用户登录成功后，后端生成一个 UUID 作为 token，存到 Redis 并设置过期时间（这里 Redis 只做 token 存储，不承担业务数据缓存）。前端每次请求在Authorization头中携带 token，后端拦截器统一校验。

public class LoginInterceptor implements HandlerInterceptor { @Autowired private RedisTemplate<String, String> redisTemplate; @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws IOException { // 放行登录接口 if (request.getRequestURI().contains("/user/login")) { return true; } String token = request.getHeader("Authorization"); if (StringUtils.isEmpty(token)) { writeUnauthorized(response); return false; } String username = redisTemplate.opsForValue().get(token); if (StringUtils.isEmpty(username)) { writeUnauthorized(response); return false; } // 将用户名存入Request作用域，供Controller直接使用 request.setAttribute("username", username); return true; } }

这里有一个很容易踩的坑：如果写了拦截器但忘了在 Spring MVC 配置中注册，那么一切校验都不会生效。我刚开始就是这个坑，排查了很久才发现spring-mvc.xml里的<mvc:interceptors>配置根本没把拦截器加进去。

另一个坑是放行规则。前端静态资源（比如课件预览时需要用到的 PDF 文件）本来不需要登录也能访问，如果拦截器拦了所有路径，会导致预览组件拿不到文件。我在拦截器里做了两件事：放行/api/login、放行/resources/**（文件访问路径），其他接口全部要 token。

对于需要特定角色的接口，我没有再写第二个拦截器，而是在 Controller 方法上自定义了一个@RequireRole(value = {"admin"})注解，用一个 AOP 切面去判断当前用户的角色。这样做的好处是权限控制在代码上清晰可见，不用翻配置文件。

4.3 文件上传的实现细节与防坑指南

文件上传用 MultipartFile 接收，这块逻辑本身不复杂，但有几个细节极其关键。

@RequestMapping("/upload") public Result<String> upload(@RequestParam("file") MultipartFile file, @RequestParam("courseName") String courseName, @RequestParam("resourceType") Integer type) { // 1. 校验文件大小，超出限制直接拒绝 if (file.getSize() > 200 * 1024 * 1024) { return Result.error(400, "文件大小不能超过200MB"); } // 2. 获取原始文件名并清理特殊字符 String originalFilename = file.getOriginalFilename(); String safeFilename = originalFilename.replaceAll("[\\\\/:*?\"<>|]", "_"); // 3. 按日期归档目录 String dateStr = new SimpleDateFormat("yyyyMMdd").format(new Date()); String resourceTypeDir = getTypeDir(type); String dirPath = "/data/resources/" + courseName + "/" + resourceTypeDir + "/" + dateStr; File destDir = new File(dirPath); if (!destDir.exists()) { destDir.mkdirs(); } // 4. 重命名文件名，避免重名覆盖 String ext = safeFilename.substring(safeFilename.lastIndexOf(".")); String newFilename = UUID.randomUUID().toString().replace("-", "") + ext; File dest = new File(dirPath + "/" + newFilename); file.transferTo(dest); // 5. 数据库记录元数据 // ...省略 return Result.success(dest.getAbsolutePath()); }

第一个教训是transferTo 方法的目标目录必须先存在，否则会抛 IOException。我之前以为它会自动创建不存在的目录，结果并不是这样。

第二个教训是不要直接用用户上传的文件名保存到磁盘。一来可能导致文件重名互相覆盖，二来文件名里的特殊字符可能带来安全隐患。统一用 UUID 重命名，原始文件名作为 metadata 存进数据库，展示层从数据库读取。

第三个教训是视频类的大文件上传。直接用 MultipartFile 接收，Tomcat 默认的单次请求大小限制会拦住。我遇到的报错是The request was rejected because its size exceeds the configured maximum。最后在配置文件里调大限制：

<bean id="multipartResolver" class="org.springframework.web.multipart.commons.CommonsMultipartResolver"> <property name="maxUploadSize" value="209715200"/> <property name="maxInMemorySize" value="1048576"/> </bean>

同时也要调 Tomcat 的maxPostSize，否则换了配置也白搭。

大文件如果超过 500MB，单次请求上传的体验非常差，断点续传、分片上传这些才是正解。但目前团队的应用场景里，视频素材大多控制在 200MB 以内，直接上传还扛得住。需要说明的是，这个方案适用于内部网络环境，如果带宽有限，仍然建议做分片上传。

5. 业务逻辑中的“硬核”部分：审核流转、多条件检索、资源预览

5.1 资源审核：一个简单却严谨的状态机

资源的审核流程是一个典型的状态流转场景，我专门设计了状态枚举：

public enum ResourceStatus { PENDING(0, "待审核"), APPROVED(1, "已通过"), REJECTED(2, "已拒绝"); private final int code; private final String description; ResourceStatus(int code, String description) { this.code = code; this.description = description; } }

状态流转规则很明确：待审核才能被审核为通过或拒绝；已通过要修改需要重新进入待审核；已拒绝的可以修改后重新提交。我没有引入复杂的状态机框架，而是在 Service 层用 if 判断规则，反而清晰可靠：

public void review(Integer resourceId, Integer status, String reviewComment) { Resource resource = resourceMapper.selectByPrimaryKey(resourceId); if (resource == null) { throw new BusinessException("资源不存在"); } if (resource.getStatus() != ResourceStatus.PENDING.getCode()) { throw new BusinessException("只有待审核的资源可以进行审核操作"); } // 更新状态和审核意见 resource.setStatus(status); resource.setReviewComment(reviewComment); resource.setReviewTime(new Date()); resourceMapper.updateByPrimaryKeySelective(resource); }

这里有个设计决策值得说明：拒绝的时候必须填写审核意见，通过则可以不填。审核意见会推送给上传资源的老师，老师根据意见修改后重新提交。这个闭环流程在真实使用时非常有效，比我最初设想的“只给一个通过/不通过按钮”要好得多。

5.2 多条件检索：MyBatis 动态 SQL 全场最佳

资源检索是整个系统中使用频率最高的功能，没有之一。老师打开资源库，默认看到的是一张资源列表，然后通过筛选条件缩小范围。筛选条件组合起来五花八门：有的按课程过滤，有的按资源类型过滤，有的输入一个关键词，有的同时选课程加类型加标签。

这种多条件组合查询，MyBatis 的动态 SQL 处理起来非常顺手：

<select id="searchResources" resultType="ResourceVO"> SELECT r.*, c.name AS category_name, u.real_name AS uploader_name FROM resource r LEFT JOIN category c ON r.category_id = c.id LEFT JOIN user u ON r.uploader_id = u.id <where> <if test="status != null"> AND r.status = #{status} </if> <if test="courseId != null and courseId != 0"> AND r.course_id = #{courseId} </if> <if test="type != null and type != 0"> AND r.type = #{type} </if> <if test="keyword != null and keyword != ''"> AND (r.title LIKE CONCAT('%', #{keyword}, '%') OR r.tags LIKE CONCAT('%', #{keyword}, '%') OR r.description LIKE CONCAT('%', #{keyword}, '%')) </if> </where> ORDER BY r.create_time DESC </select>

注意一个问题：学生端只能看到通过的资源，所以服务端默认强制加上status = 1的条件，前端传什么条件都不覆盖服务端设置的默认值。这个校验一定要放在 Service 层，而不是依赖前端的控件隐藏，否则学生直接改请求参数就能看到未通过审核的内容。

关于 LIKE 搜索的性能，资源量到了一定规模后，全表 LIKE 肯定是慢的。目前 MySQL 索引对前缀模糊查询有效，但%关键词%这种中缀匹配是没法走索引的。我的做法是控制匹配字段的范围，标题、标签、简介三个字段足够覆盖绝大多数搜索场景，同时加上上传时间范围筛选，减少查询范围。之前试过用 MySQL 的 FULLTEXT（ngram 分词）来做中文全文索引，效果不错，但在 MySQL 5.7 上对中文分词的配置和维护比较繁琐，后面再考虑。

5.3 资源预览：几个轻量方案的真实体验

资源在线预览有很多种方案，我按资源类型做了区分：

• PPT/PDF 类：转成图片或者直接用 PDF.js 在网页端预览。如果是课件 PPT，我实际采用的是用 LibreOffice 转 PDF 再嵌入浏览器预览的方式。命令行操作很简单：

libreoffice --headless --convert-to pdf --outdir /data/convert/ /data/resources/xxx.pptx

• 视频类：直接用 HTML5 的<video>标签播放。要注意服务器返回视频响应时，需要正确设置Content-Type，否则浏览器可能无法识别视频格式。更重要的是，HTML5 video 默认是持续请求整个文件的，如果文件很大，需要支持 HTTP Range 请求才能拖动进度条。Spring 框架返回资源文件时默认支持 Range 请求，这个点倒是没有额外处理。

• 代码类：用 code-prettify 插件在网页端高亮显示，文本内容直接读取文件返回前端即可。

图片类最简单，直接<img>标签展示。

在线预览最大的问题不是技术，而是权限。如果资源文件路径直接暴露，知道 URL 的人就能直接访问，绕过整个鉴权系统。这里我做了两层保障：第一，文件的静态资源目录设置了不经过拦截器的放行路径；第二，放行路径对应的目录只放转换后的预览文件，原始文件全部存放在未开放目录/data/private/里，需要下载时走带 token 校验的下载接口。

这个设计经过实际测试是可靠的，但要注意权限控制粒度只能做到“登录用户可见就能预览”，做不到“只能预览某一课的资源”这种细粒度。对于内部资源库，这个粒度已经足够了。

6. 前端实现思路与前后端联调心得

6.1 权限路由与菜单控制

前端路由按角色做动态配置。用户登录后，后端返回当前用户角色，前端根据角色决定哪些菜单可见、哪些路由可访问。路由配置里我用了一个简单方案，在 router 的beforeEach钩子里做判断：

router.beforeEach((to, from, next) => { const token = localStorage.getItem('token'); if (!token && to.path !== '/login') { return next('/login'); } if (token && to.path === '/login') { return next('/'); } const role = store.getters.role; if (to.meta.roles && to.meta.roles.indexOf(role) === -1) { return next('/403'); } next(); });

当然这只是控制页面入口，真正的数据安全还是靠后端接口的鉴权。前端控制路由只是为了让普通用户看不到“审核管理”这个入口，减少无效请求。

6.2 axios 封装与 token 统一处理

我用 axios 实例统一封装了 HTTP 请求：

import axios from 'axios'; const service = axios.create({ baseURL: '/api', timeout: 15000 }); service.interceptors.request.use(config => { const token = localStorage.getItem('token'); if (token) { config.headers['Authorization'] = token; } return config; }); service.interceptors.response.use( response => { const res = response.data; if (res.code === 200) { return res; } if (res.code === 401) { localStorage.removeItem('token'); window.location.href = '/login'; } return Promise.reject(new Error(res.message)); }, error => { ElMessage.error('网络异常，请稍后重试'); return Promise.reject(error); } );

这里有一个细节：请求后端的地址配置了/api前缀，同时通过前端 devServer 的 proxy 把/api转发到后端端口：

devServer: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }

这样前端编码的时候直接用相对路径，不用关心后端部署的 IP 和端口，后续上线到服务器只要改 nginx 的代理配置就行，前端代码不用动。

6.3 文件上传组件与进度条

Element UI 自带的el-upload组件已经封装了上传能力，我选择自定义上传方式，方便控制上传时的额外参数：

<el-upload action="#" :http-request="handleUpload" :before-upload="beforeUpload" :file-list="fileList"> <el-button>选择文件</el-button> </el-upload>

对应的 JS 部分：

handleUpload(options) { const formData = new FormData(); formData.append('file', options.file); formData.append('courseName', this.courseName); formData.append('resourceType', this.resourceType); service.post('/resource/upload', formData, { onUploadProgress: (e) => { if (e.total) { const percent = Math.round(e.loaded / e.total * 100); options.onProgress({ percent }); } } }).then(res => { if (res.code === 200) { ElMessage.success('上传成功'); options.onSuccess(res); } else { ElMessage.error(res.message); options.onError(res); } }).catch(() => { options.onError(new Error('上传失败')); }); }

上传时还有两个注意点：一个是上传过程要锁定提交按钮，防止用户重复点击导致同一文件重复上传；另一个是上传之后立刻刷新路径回显，让用户直观感受到文件已经传好并进入了待审核状态。

7. 从部署到实际使用：性能调优与踩坑记录

7.1 部署架构

最终部署在一台 4核8G 的云服务器上，单机跑 Nginx + Tomcat + MySQL + Redis。Nginx 负责前端静态文件服务和反向代理：

server { listen 80; server_name resource.example.com; location / { root /opt/frontend/dist; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }

前端用 Nginx 托管，后端接口用反向代理转发，避免跨域问题。这个方案在我实际部署中非常稳定，比之前直接用 Tomcat 托管前端静态文件要省事很多。

7.2 上线初期最严重的两个问题

第一个问题是视频预览时的内存飙升。有老师反馈上传了一个近 150MB 的 mp4，播放的时候访问速度很慢，服务器内存还飚了起来。排查之后发现，Nginx 代理转发视频文件时，默认读取到内存再转发，大文件会导致内存快速膨胀。修复方式是直接不代理视频文件的访问路径，视频存放在单独的文件服务器路径下，独立走一个静态目录：

location /static/video/ { alias /data/resources/; directio 4m; output_buffers 1 128k; }

加上directio让 Nginx 直接绕过内存缓冲读取磁盘文件，性能立刻改观。

第二个问题是历史文件迁移时目录规则不统一。最初我只按资源类型归档，后来加了课程维度之后，老文件就挂在根目录下，新文件按课程分类放。结果检索时数据都有，去磁盘上找文件时却要两边翻。后来干脆写了一个迁移脚本，把所有老文件按新规则复制到对应课程目录，再删除旧文件，彻底统一了目录。

7.3 数据库层面的几个小坑

• 大字段的description在资源列表面临性能问题。列表接口一开始连 description 也查出来返回，页面渲染时数据量大，接口响应慢了不少。后来把列表接口的 SQL 改为不查 description，只有点击资源详情时才查全字段，列表接口的速度明显提升。
• 下载量统计我用了一个简单办法：排行榜接口和列表接口都查download_count排序。随着数据量增大，这个字段可以考虑做成一个单独的日统计表，但目前的访问频率完全够用。
• 一个经典的 MySQL 坑：datetime字段查询时用了字符串比较，导致索引失效。后来全部改用 JDBC 参数传递Date对象，避免隐式类型转换。

8. 复盘与扩展：这个资库库未来还能做什么

说实话，这个项目最大的收获不是代码量有多少，而是让我理解了”教学资源管理”和”普通文件管理”的本质差异。普通文件管理只要解决存取问题，教学资源库的核心不是“存”而是“用”——让正确的人、在正确的场景、快速找到正确的资源，并且能沉淀出使用数据反哺教学。

目前系统里一个明显的短板是推荐功能。现在只是基于标签和分类的规则匹配，还没有针对资源下载、浏览行为做个性化推荐的学习。如果后续要扩展，有两个方向：

一是结合学生的学习数据做智能推荐。比如学生在某个课程节点频繁下载某类资源，系统可以推送相似的补充材料。这个方向技术上不难做，核心是行为埋点数据要积累够。

二是资源版权与版本管理。教学资源更新迭代非常快，同一个课件可能一学期改好几版。目前系统是直接覆盖旧文件，没有版本记录。下一步可以考虑引入版本管理逻辑，保留历史版本，这样即使新版有问题也可以快速回退。

另外对上传文件的格式校验还可以加强。现在只做了扩展名白名单校验，但某些文件重命名后扩展名可能被伪造，下一步要针对文件头做魔数校验，确保上传的文件格式是真实的而非改个后缀名冒充的。

最后说几句真实的体会

整个项目从最开始的信息整理到上线稳定运行，前后大概花了两个月的时间，其中大部分时间都花在了业务细节打磨上。做这种内部系统，最大的心得就是一定要贴近实际使用场景——你觉得自己设计了一个完美的审核流程，真实使用时老师们可能更关心的是“能不能一键关联到我的课程”；你觉得资源分类越细越好，实际用户更喜欢直接用搜索而不是去翻分类。上线之后多跟使用者聊聊，你才能知道系统哪里真的好用、哪里纯粹是工程师思维的一厢情愿。

如果这个项目能给正在做类似系统的同学一个参考，我建议你把精力优先放在检索速度和上传体验上，这是资源库最基本的体验底线。审核、权限这些功能可以后面迭代，但上传卡顿和搜索慢，一次就能让用户失去信任。