SpringBoot+MyBatis+Vue教学资源库权限存储部署实战

教学资源库管理系统这类项目，我在开发中接触过不少，最早也被“企业级”三个字吸引过。实际情况是，市面上很多标榜“企业级”的源码，跑通容易，真要部署上线、二次开发，坑一个接一个。权限往死里简单，文件直接扔本地，接口返回格式五花八门，前端页面刷新就 404。真正能落地、能扛住学校或企业内几百上千人同时使用的教学资源库，必须把权限模型、文件存储、统一返回、分页查询、前后端联调、部署配置这几件事都做扎实。

这篇内容我会按一个实际项目的生命周期，从技术选型、数据库建模，到 SpringBoot 后端实现、Vue 前端联调，再到文件存储、故障排查和上线部署，把每一个关键点都拆开讲。适合两类人看：一是拿它做毕业设计、课程设计的学生，二是公司内部需要快速搭一套资源管理平台的开发。照着梳理完，你至少能把这个系统从源码变成一个真正可维护、可扩展的产品，而不是一个“能跑的 demo”。

1. 方案选型与技术栈拆解：为什么非要是这套组合

1.1 后端基石：SpringBoot 版本与 JDK 版本的配合

现在下载源码，第一件事就是看 SpringBoot 版本。很多人在这一步就开始踩坑：项目用的是 SpringBoot 2.7，你本机装的是 JDK 17，好，勉强能跑；项目用的是 SpringBoot 3.x，你却还在用 JDK 8，连启动都启动不了。SpringBoot 3.0 开始强制要求 JDK 17 以上，而市面上大量教学资源类项目仍然基于 SpringBoot 2.x，配套的是 JDK 8 或 11。

如果你拿到的是 SpringBoot 2.7.x 的源码，我的建议是不要随便升级到 3.x。因为 MyBatis 相关的 starter、pagehelper 分页插件、部分第三方工具在 3.x 体系下要做适配，升级后轻则报依赖冲突，重则 Jackson 序列化行为变化导致接口结果异常。企业项目里“能稳定跑就不要乱动版本”是铁律，学习阶段更没必要为了追新给自己找麻烦。

1.2 前端框架：Vue 2 还是 Vue 3

教学资源库的前端，最常看到的是两种组合：Vue 2 + Element UI，或者 Vue 3 + Element Plus。老项目尤其是前几年写完的源码，九成是 Vue 2。

Vue 2 虽然官方已进入维护末期，但生态极其成熟，坑基本都被踩平了。Vue 3 + Element Plus 的好处是组合式 API 写起来更清爽，TypeScript 支持更好，新项目我更推荐，但前提是你对 Vue 3 的响应式原理和 Composition API 有基本了解。如果你只是拿源码改改页面、跑通流程，Vue 2 也完全够用，不要因为版本旧就急着重构，重构的成本往往比你想的高得多。

1.3 持久层选型：MyBatis 到底赢在哪

标题里明确写了 MyBatis，这个选型很符合国内企业现状。相比 JPA，MyBatis 最大的优势是 SQL 完全自己掌控，排查问题直接看 XML 里的语句就行，不用去猜 Hibernate 生成了什么。教学资源库这种系统，资源列表大概率要按分类、标签、标题、时间做多条件组合查询，SQL 复杂多变，MyBatis 的 <if>、<foreach> 动态 SQL 处理这种场景非常顺手。

有人会问，MyBatis-Plus 不是更好用吗？确实，MyBatis-Plus 内置了通用 CRUD、分页插件、代码生成器，开发效率高一截。但源码项目的价值就在于让你看到 MyBatis 原生 XML 的写法、参数映射、ResultMap 的定义，这些基础打牢了，以后不管用不用 Plus 都能快速上手。面试的时候，面试官也更愿意问你对 MyBatis 缓存、插件机制、TypeHandler 的理解，而不是问你有没有用过 MyBatis-Plus。

1.4 数据库：MySQL 8.0 的优势与配置

MySQL 是这套架构里最不需要犹豫的部分。能用 8.0 就别用 5.7，因为 8.0 默认字符集是 utf8mb4，对中文和 emoji 的支持更省心；窗口函数、JSON 字段类型在做一些统计报表时也非常方便。有一点要注意，MySQL 8.0 的驱动包名是 com.mysql.cj.jdbc.Driver，连接 URL 需要显式指定时区，比如 serverTimezone=Asia/Shanghai，否则连接池初始化时就会报时区错误。

2. 数据库模型设计：教学资源如何组织才能撑住扩展

2.1 RBAC 权限模型：用户、角色、菜单解耦

企业级系统最重要的不是界面多好看，而是权限不能乱。教学资源库一般涉及学生、教师、管理员三类基本身份，如果权限写死在用户表里，后面想调整某个角色的菜单权限，改动量会非常大。标准做法是经典的 RBAC 模型，拆成五张表：

• sys_user：用户表，存账号、密码、昵称、状态、创建时间
• sys_role：角色表，存角色编码、角色名称，比如 TEACHER、STUDENT、ADMIN
• sys_menu：菜单/权限表，既存左侧导航菜单，也存按钮权限标识
• sys_user_role：用户角色关联表
• sys_role_menu：角色菜单关联表

sys_menu 表里一般会有一个 perms 字段，比如 resource:upload、resource:delete，后端接口做权限校验时检查的就是这个标识。前端拿到菜单之后，根据 menu_type 判断是目录、菜单还是按钮，动态渲染路由和操作按钮。这是整个系统往后扩展的根基，千万不能省。

2.2 资源核心表：分类、元数据、上下行日志

资源库的本体是资源表，设计上要往“可扩展”方向靠。我建议至少包含这几类信息：

围绕资源表，还需要配套三个日志或辅助表：收藏表 t_favorite、评论表 t_comment、下载记录表 t_download_log。下载记录表尤其重要，一方面可以统计资源热度，另一方面如果资源存在版权纠纷，你能追溯是谁在什么时候下载过哪个资源，企业级系统这个审计能力必须有。

2.3 索引优化与慢查询排查

数据量小的时候，任何 SQL 都很快，但资源库一旦积累到几十万条记录，分页查询就会开始明显变慢。设计索引时有几条基本原则：

• 外键字段必须加索引，比如 category_id、uploader_id，这能避免多表关联时全表扫描。
• 高频检索字段加索引，比如资源状态 status 和上传时间 create_time 可以建联合索引 idx_status_create_time(status, create_time)，满足“按状态倒序取最新”的列表页。
• 标题和标签字段不要迷信普通索引，LIKE '%关键词%' 这种模糊查询普通索引用不上。量级小可以接受，量大就要考虑 MySQL 全文索引或者引入 Elasticsearch，但那是后期方案。

一个很实用的排查习惯：在 MyBatis 的 XML 里先 EXPLAIN SELECT ... 看一下 type 字段是不是 ALL 或者 index，如果是，说明索引没有命中，赶紧优化 SQL 或者补索引。这一步做到位，资源库接口在数据量翻倍后依然能保持流畅。

3. 后端核心实现：SpringBoot 与 MyBatis 的关键点拆解

3.1 分层结构与统一返回体

拿到源码先看包结构。一个合格的 SpringBoot 项目，目录一定是清晰分层的：

• controller：只做参数接收和结果返回，不写业务逻辑
• service：业务逻辑，事务控制在这一层
• mapper：MyBatis 接口，只定义方法
• entity / dto / vo：实体对象、入参对象、出参对象
• config：配置类，比如拦截器、跨域、MyBatis
• utils：工具类，比如 JWT 工具、文件工具

很多源码把业务逻辑直接堆在 controller 里，这种写法写个小接口没问题，但一旦要对下载次数做事务更新、对上传做权限校验，代码就乱成一锅粥。后端所有接口的返回结构最好统一，比如：

java复制public class Result<T> {
    private Integer code;
    private String msg;
    private T data;
    // getter/setter 省略
    public static <T> Result<T> ok(T data) { ... }
    public static <T> Result<T> fail(Integer code, String msg) { ... }
}

前端拿到响应之后，只判断 code 是不是 200，再决定渲染数据还是弹错误提示。配合全局异常处理器 @RestControllerAdvice，业务方法里只管抛异常，不用每个接口都写 try-catch，代码干净一大截。

3.2 JWT 认证与权限拦截

教学资源库如果允许学生登录下载资源，登录态安全就绕不开。最常见的方案是 JWT，用户登录成功后生成一个 token，前端每次请求放到 Authorization 请求头里，后端用拦截器校验。

自定义拦截器是 SpringBoot 项目里最简单可靠的实现：

java复制public class JwtInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String token = request.getHeader("Authorization");
        // 校验 token，失败则返回 401
        return true;
    }
}

之后在配置类里注册拦截器，并设置 /api/login、/api/register 这些路径不拦截。

权限校验的粒度，我的实践经验是用注解加 AOP。定义一个 @RequiresPermission("resource:upload") 注解，在切面里获取当前用户角色和权限标识，如果缺少权限就抛出业务异常。这样权限逻辑集中管理，接口上只需要一行注解，可读性极高。

3.3 MyBatis 分页、缓存与 TypeHandler 实战

资源列表页的分页，手写 LIMIT offset, size 是最容易出问题的：先查 total，再查当前页，两个 SQL 没有事务保护，数据一变页码就错。更省心的方式是使用 PageHelper。

java复制PageHelper.startPage(pageNum, pageSize);
List<ResourceVO> list = resourceMapper.selectPage();
PageInfo<ResourceVO> pageInfo = new PageInfo<>(list);

PageInfo 里已经封装好了总记录数、总页数、当前页大小等字段，前端表格直接能绑定。这里有一个非常经典的坑：PageHelper.startPage() 必须紧接着你想分页的那条 select 语句，如果中间夹杂了其它 Mapper 查询，分页插件就会作用到错误的 SQL 上，查出来的数据莫名其妙变少。在 mapper 里把查询逻辑写简单一点，分页问题可以少一半。

MyBatis 缓存这块，很多源码默认开着二级缓存，文件大、更新频繁的资源表反而容易缓存不一致。建议在 application.yml 里显式设置：

yaml复制mybatis:
  configuration:
    map-underscore-to-camel-case: true
    cache-enabled: false

数据库字段的下划线风格自动映射到 Java 驼峰属性，省去大量 resultMap 手写工作量。至于 TypeHandler，自定义枚举转换是很多面试官爱问的点。资源类型用 tinyint 存，Java 端希望用枚举操作，可以写一个 handler 继承 BaseTypeHandler<ResourceType>，在 XML 或者配置中注册后，Mapper 接口里直接声明枚举参数就能自动转换。这块属于加分项，源码里未必都有，但懂了这个机制，MyBatis 源码面试基本能答得上来。

3.4 文件上传与下载的实现细节

教学资源库里视频动不动上百兆，文件上传参数必须提前调大：

yaml复制spring:
  servlet:
    multipart:
      max-file-size: 1024MB
      max-request-size: 2048MB

后端接收 MultipartFile 后，不要直接用原始文件名存储。原因有两个：一是中文文件名在部分服务器上会乱码，二是文件名一旦带特殊字符，下载时 Content-Disposition 头会处理得很痛苦。我的做法是用 UUID.randomUUID() 生成新文件名，原始文件名存数据库，下载时再拼回去。上传接口通常还要做类型白名单校验，比如视频只允许 mp4、mkv、m3u8 等格式，不能因为前端传了 exe 就傻傻收下来。

4. Vue 前端工程化：与后端联调时那些坑

4.1 开发环境搭建与代理转发

前端跑不起来，大部分是环境问题。Node.js 版本太高、npm 依赖装不上、node-sass 编译失败，这三个问题能卡住一半的新手。建议安装 Node 14 LTS 或 16 LTS，npm 源切换成国内的镜像源，能省下很多等待时间。

开发环境最核心的配置是代理转发。Vue 项目启动默认在 8081 端口，后端接口在 8080，浏览器直接跨域。在 vue.config.js 里配置 devServer：

javascript复制devServer: {
  port: 8081,
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
      pathRewrite: { '^/api': '' }
    }
  }
}

前端请求 /api/resource/list，开发环境代理到 http://localhost:8080/resource/list。这样浏览器看到的请求都是同源的，跨域问题在根源上被解决了。

4.2 axios 拦截器与 token 处理

Vue 项目里建议对 axios 做二次封装。请求拦截器统一加 token，响应拦截器统一处理业务码和 401 跳转：

javascript复制service.interceptors.request.use(config => {
  const token = localStorage.getItem('token')
  if (token) {
    config.headers['Authorization'] = 'Bearer ' + token
  }
  return config
})

service.interceptors.response.use(res => {
  if (res.data.code === 401) {
    router.push('/login')
  }
  return res.data
})

这里有个实际教训：token 存 localStorage 会面临 XSS 风险，存 cookie 又会遇到 CSRF 风险。中小型系统咱们权衡下来用 localStorage 居多，但代码中要避免使用 v-html 渲染不受信任的内容，防止脚本注入拿 token。

4.3 动态路由与导航守卫

教学资源库的菜单是权限相关的，管理员看到的菜单不一致。因此路由不能全在前端写死，建议在后端登录接口返回菜单列表，前端遍历后用 router.addRoute() 动态注册。页面刷新后动态路由会丢失，处理方式是在全局前置守卫里判断状态，若已有用户信息但路由表为空，就重新拉取菜单并放行。

这个逻辑写明白之后，前端按钮级权限也可以照同样的思路做，后端返回的 perms 数组存储到 Vuex/Pinia，页面里用自定义指令 v-permission 控制按钮显隐。只要后端权限设计不乱，前端这套联动是非常顺畅的。

4.4 资源上传、预览与视频播放

上传组件用 Element Plus 的 el-upload，配合后端返回的 URL 回显。需要注意，上传前要校验文件大小和格式，视频文件超过 1GB 时，单次上传很容易超时。如果资源库明确要支持大视频上传，可以分片上传，把文件切成几 MB 一片逐片提交，后端收到所有分片后合并。这个功能实现起来不复杂，但体验提升非常明显。

预览和播放是另一个高频坑点。PDF 预览用 <iframe> 包裹即可，图片直接用 <img>。视频如果是网页插播 m3u8 直播流或者 HLS 切片，原生 <video> 标签支持并不好，需要引入 hls.js 或 vue-video-player。在接入这类视频的时候，建议先用 VLC 或浏览器的开发者工具确认视频地址能直接访问，再去调播放器，因为大部分播放问题其实是文件访问权限或者跨域 CORS 导致的，根本不是播放器的问题。

4.5 生产构建与资源路径

前端打包后要放到 Nginx 或者和 SpringBoot 一起部署，资源路径一定要处理干净。在 vue.config.js 里设置 publicPath: './' 可以避免服务器子目录部署时白屏。如果你把前端放到域名根目录，可以不用改；但放到二级路径就必须写对，比如 /admin/。又一个典型场景：Vue Router 使用 history 模式刷新页面会 404，因为 Nginx 找不到对应的物理路径，必须在 Nginx 配置里加 try_files。

5. 文件存储与资源安全：本地磁盘还是 MinIO

5.1 本地存储：开发够用，生产扩容难

早期的资源库源码绝大多数用本地磁盘存文件，数据库存 D:/upload/xxx.mp4 这种绝对路径。这个方案在开发环境完全没问题，上线后麻烦就来了：磁盘不够了要扩，得停机加盘；Nginx 要单独配一个 /files/ 的 alias 映射到磁盘目录；更麻烦的是，如果以后系统要部署到多台服务器做负载均衡，文件落在某一台机器的磁盘上，其它机器读不到，又要搞共享存储。所以本地存储只适合演示、个人部署和毕设答辩，真正企业化生产还是要考虑对象存储。

5.2 MinIO 接入与预签名 URL

MinIO 是目前最流行的开源对象存储方案，兼容 S3 协议，社区活跃，中文文档全，而且一个重要优势是可以私有化部署，适合学校和企业内网环境。SpringBoot 集成 MinIO 的核心思路是：上传时用服务端直传，下载时生成预签名 URL，让浏览器直接访问。

java复制// 生成预签名下载地址，默认过期时间 5 分钟
String url = minioClient.getPresignedObjectUrl(
    GetPresignedObjectUrlArgs.builder()
        .method(Method.GET)
        .bucket(bucketName)
        .object(objectName)
        .expiry(60)
        .build());

这里有一条红线：MinIO 的 accessKey 和 secretKey 绝对不能出现在前端代码里。前端拿到签名 URL 就够了，密钥只存在后端配置文件。预签名 URL 的好处是下载链接会过期，即使被分享出去，也不会永久有效，这能在一定程度上防止资源被批量盗取。

5.3 资源安全、防盗链与大小限制

文件能访问不代表着安全，还要防盗链。MinIO 支持桶策略，也可以限制 Referer 头，只允许你自己的域名引用视频和图片。另一个常见做法是，不让直链访问，而是走后端鉴权后再返回签名 URL，即“接口返回地址，CDN 加速转发”。

教学资源库还有一个特殊性：版权。上传文档课件时建议自动提取页数、文件大小、文件类型，存成附件元数据；如果是敏感资源，还可以做下载水印，比如给视频叠加访问者学号或工号。这些功能不是必备，但做了会让整套系统的“企业级”含金量明显上一个档次。

6. 常见故障排查与避坑速查

再补充一个我实际踩过很多次的坑：后端接口联调时，如果出现中文乱码，先看两条，一是有没有在 JDBC URL 里带 characterEncoding=utf8mb4，二是数据库建库时的默认字符集是不是 utf8mb4。很多时候问题根本不在前端而在数据库连接。还有一次排查了很久，发现是过滤器里 request.getParameter() 和 request.getInputStream() 同时调用导致输入流被读空，上传文件接口一直拿不到参数。这类问题很隐蔽，遇到上传接口异常，一定要先去确认是否有多重读取 request 的地方。

7. 打包部署与上线运维要点

7.1 后端打包与前端构建

后端是 Maven 项目，标准打包命令：

bash复制mvn clean package -DskipTests
java -jar target/resource-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

生产环境的数据库密码、MinIO 密钥一定要放外置配置，不要把硬编码的密码提交到 Git。推荐用 application-prod.yml 区分环境，启动时通过参数指定。

前端构建最省心的方式是把资源托管到 Nginx，后端只服务接口。执行 npm run build 生成 dist 目录，然后：把 dist 里面的文件传到服务器的 /var/www/html 下，Nginx 直接指到那里。

7.2 Nginx 核心配置

nginx复制server {
    listen 80;
    server_name resource.example.com;

    client_max_body_size 2g;

    root /var/www/html/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /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 /files/ {
        alias /data/resource-files/;
        expires 7d;
        add_header Cache-Control "public";
    }
}

proxy_pass 末尾带不带 /，效果完全不同。如果写成 http://127.0.0.1:8080，那么 /api/resource/list 会被完整转发到后端；如果写成 http://127.0.0.1:8080/，那么 /api/ 前缀会被剥掉，转发为 /resource/list。这两种方式都能用，但前后端接口设计必须匹配，否则就是 404。

7.3 数据库的日常备份

资源库的价值很大程度在积累的数据上，数据丢了等于白干。日常备份用 mysqldump 就够了：

bash复制mysqldump -h127.0.0.1 -uroot -p --default-character-set=utf8mb4 resource_db > /backup/resource_$(date +%F).sql

建议配合定时任务，每天凌晨备份一次，保留最近 7 天，重要数据另外做异地备份。文件方面的备份则看存储方案，本地存储要定期同步到其它磁盘或对象存储，MinIO 本身支持多节点，配置副本数来应对磁盘损坏。

7.4 日志与监控

后端用 nohup 启动时，日志重定向到文件：

bash复制nohup java -jar resource.jar > logs/app.log 2>&1 &

日志里最容易忽视的，是慢 SQL 的追踪。MyBatis 可以在配置里开启慢查询打印，再配合 MySQL 的 slow query log，把执行时间超过 1 秒的 SQL 捞出来，你会很惊讶地发现，很多“系统变慢”的根源就藏在某几条没走索引的查询里。

最后再分享一点个人体会。像教学资源库这样的项目，技术栈本身并不难，难的是把各种细节都照顾到：数据库里多一张日志表，上线后审计就有据可查；后端多一个统一返回体，联调阶段前端就能少问几十句“这个接口到底返回什么”；文件存储方案早一点定下来，就少一次上线后的痛苦迁移。如果你打磨这套系统的目标只是跑通，那上面一大半内容都可以暂时不看；但如果你想让这份源码真正成为一块能拿得出手的项目经验，把权限、存储、部署三件事想透，价值会比多写几个 CRUD 接口大得多。