校园文件管理系统源码解析：Spring Boot上传分片与权限避坑指南

简介：桃源校园文件管理系统是一套基于ASP.NET Web Forms的校园网文件管理源码，面向学校信息化管理人员，常用于搭建文件存储备份、发送共享、内容发布及教学课件资源管理平台，也适合.NET开发者学习完整的Web项目结构。系统源自桃源企业文件管理系统V2.4，在通用文件处理能力之上强化了文件发布和内容管理，更贴合校园班级、教研室等使用场景。资源包14.17MB，共1933个文件，以gif/png/jpg等界面图片素材、aspx页面、css样式和js脚本为主，另含dll程序集与sql数据库脚本，前台页面与后台逻辑均包含在内，具备部署运行的基本条件。已有273人浏览学习。通过源码可重点研读用户登录与注册、用户控件复用、后台文件操作处理等模块的实现方式，整体目录层次清晰，适合作为校园网文件管理系统的二次开发基础或相关课程设计参考。

1. 校园文件管理系统源代码：它到底在解决什么

期末周的一个晚上，某高校 A 同学想把老师发的 2GB 课堂录像转发给全班，微信传不了、U 盘落在宿舍、邮箱更不用说，最后只能晚上十一点跑回教室现场拷贝。这套名为桃源校园文件管理系统的源代码，解决的就是这种每天都在发生的校园文件问题：把零散在 QQ 群、微信记录和网盘之间的文件，收回到一套自建的 Web 系统里统一管理。它不是一个泛泛的网盘仿写项目，而是围绕校园身份、班级共享、课程资料沉淀设计的应用，适合正在找完整项目做课程设计的学生，也适合想在校园服务器上搭私有文件服务的开发者。接下来的每一章，我会从源码可复现的角度，把它能做什么、怎么做、坑在哪讲清楚。

2. 从目录结构到数据模型：先看懂源码的骨架

2.1 读懂工程布局：前后端分离下各目录在干什么

如果要快速判断一套文件管理源码是否值得投入，我会先看它的目录结构而不是先跑起来。一套典型的校园文件管理系统源码，走的是前后端分离路线，后端负责存储与权限，前端负责交互，两层通过 REST 接口通信。常见的目录布局大致是这样：

toyuan-file/ ├── backend/ # Spring Boot 后端工程 │ ├── src/main/java/com/toyuan/file/ │ │ ├── controller/ # HTTP 接口层，只做参数接收与结果封装 │ │ ├── service/ # 业务层：上传、下载、分享、权限判断 │ │ ├── mapper/ # 数据访问接口 │ │ ├── entity/ # 数据库表对应的实体类 │ │ └── common/ # 统一响应、异常处理、工具类 │ ├── src/main/resources/ │ │ ├── application.yml # 数据源、文件存储路径、上传限制 │ │ └── mapper/ # MyBatis XML 文件（SQL 语句） ├── frontend/ # Vue 前端工程 │ ├── src/ │ │ ├── api/ # axios 请求封装，所有接口的统一出口 │ │ ├── views/ # 页面组件：文件列表、上传、回收站等 │ │ ├── components/ # 通用组件：上传组件、文件图标等 │ │ └── router/ # 前端路由，配合登录鉴权守卫 └── sql/ └── init.sql # 建库建表脚本

这段结构里我关心的只有三处。第一是sql/init.sql，它决定了数据模型，直接反映系统能做什么；第二是service层，业务判断全在这里，权限漏洞也大多藏在这里；第三是frontend/src/api，一套靠谱的前端会把所有接口集中封装，而不是把请求散落在各个 vue 文件里。

顺着这个工程布局，后端接口的职责划分通常一目了然。我把一套文件系统必备的接口清单整理如下，对照这份清单去检查源码，缺失的模块一眼就能看出来：

2.2 建表脚本里藏着设计思路：五张表撑起核心业务

打开init.sql，一般能看到围绕用户、文件、分享、日志这四类核心对象建的表。下面这份建表脚本是这类源码最常见的骨架，它覆盖了校园场景几乎全部需求：账号体系、文件元数据、分享链接、操作审计、存储配置。

-- 用户表：存放账号、BCrypt 加密后的密码与角色 CREATE TABLE sys_user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL UNIQUE, password VARCHAR(100) NOT NULL, real_name VARCHAR(50) DEFAULT '', role TINYINT NOT NULL DEFAULT 2 COMMENT '1:管理员 2:教师 3:学生', status TINYINT NOT NULL DEFAULT 1 COMMENT '1:正常 0:禁用', create_time DATETIME DEFAULT CURRENT_TIMESTAMP ); -- 文件信息表：描述文件元信息，不负责二进制内容 CREATE TABLE file_info ( id BIGINT PRIMARY KEY AUTO_INCREMENT, file_name VARCHAR(255) NOT NULL, file_size BIGINT NOT NULL, file_type VARCHAR(20) NOT NULL COMMENT '文档/图片/视频/压缩包', file_ext VARCHAR(20) DEFAULT '', storage_path VARCHAR(500) NOT NULL COMMENT '磁盘上的相对存储路径', md5 CHAR(32) DEFAULT '', owner_id BIGINT NOT NULL COMMENT '上传者，关联 sys_user', visibility TINYINT NOT NULL DEFAULT 1 COMMENT '1:私有 2:共享 3:公开', status TINYINT NOT NULL DEFAULT 1 COMMENT '1:正常 0:回收站 -1:已删除', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_owner (owner_id), INDEX idx_md5 (md5) ); -- 分享表：把文件分享给指定人或生成公开链接 CREATE TABLE file_share ( id BIGINT PRIMARY KEY AUTO_INCREMENT, file_id BIGINT NOT NULL, share_code VARCHAR(32) NOT NULL COMMENT '提取码', share_range TINYINT NOT NULL DEFAULT 1 COMMENT '1:指定用户 2:指定角色 3:公开链接', expire_time DATETIME DEFAULT NULL COMMENT 'NULL 表示永不过期', create_by BIGINT NOT NULL, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_share_code (share_code) ); -- 操作日志表：审计用途，校园场景经常被忽略但很重要 CREATE TABLE file_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_id BIGINT NOT NULL, action VARCHAR(20) NOT NULL COMMENT 'upload/download/delete/share', file_id BIGINT DEFAULT NULL, detail VARCHAR(500) DEFAULT '', ip VARCHAR(64) DEFAULT '', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_user (user_id), INDEX idx_time (create_time) ); -- 存储配置表：把存储目录做成可配置，而不是写死在代码里 CREATE TABLE storage_config ( id BIGINT PRIMARY KEY AUTO_INCREMENT, config_key VARCHAR(50) NOT NULL UNIQUE, config_value VARCHAR(500) NOT NULL, remark VARCHAR(200) DEFAULT '' );

这套表结构有一个明显特点：file_info只保存文件的元信息和storage_path，真正的二进制内容写在磁盘上，而不是存进数据库的 BLOB 字段。这样做的理由是，数据库只承担索引和查询职责，文件读写交给文件系统，上传下载性能才能跟上，备份时也能把数据库和数据目录分开处理。需要注意visibility字段是权限判断的核心，第 4 章的翻车点基本都集中在它身上。

另一个容易被忽略的点是file_share表里的share_code。它用唯一索引约束，前端页面通过这个 8 位提取码访问分享文件，如果源码里没有这张表，说明分享功能是假的或者根本没实现，拿到手后要花不少功夫补。我一般会让这个字段由后端生成，而不是前端传入，因为前端传入的提取码往往碰撞率高，还容易被遍历。

2.3 存储层选型：本地磁盘、MinIO 还是对象存储

我见过不少照抄网盘系统的源码，上来就接云对象存储，校园内网环境根本连不上外网，最后上线当场翻车。这里的关键是先确认部署环境再决定存储层。如果是在学校机房的一台服务器上跑，最稳的方案是本地磁盘加绝对路径配置；如果实验室有条件跑容器化服务，MinIO 是更好的选择，它提供 S3 兼容接口，以后要迁移到任何对象存储都不用改业务代码。

# application.yml 文件存储相关配置 storage: type: local # local / minio local: root-path: /data/toyuan-files # 必须配绝对路径，不要用 ./files minio: endpoint: http://192.168.1.100:9000 access-key: minioadmin secret-key: minioadmin bucket: campus-files upload: max-size: 2000MB # 单文件最大 2GB，覆盖课程录像场景 allowed-ext: doc,docx,pdf,ppt,pptx,xls,xlsx,jpg,png,zip,rar,mp4

这里有两个参数值得强调。root-path用绝对路径/data/toyuan-files而不是./files，原因在避坑章节会专门展开，简单说就是相对路径在不同启动目录下会被解析到完全不同的位置，程序重启后文件可能凭空消失。allowed-ext则从入口挡住了最常见的安全问题，只允许业务需要的文件类型，而不是用黑名单去过滤危险扩展名。

存储选型的判断依据可以压成一张对比表，方便在课程设计和真实项目之间做决定：

3. 把核心链路跑起来：从普通上传到分片秒传

3.1 单文件上传的最小实现：三层协作怎么走

先看最基础的单文件上传，它是整个系统的地基。后端分成三层：Controller 接参数、Service 做业务、Mapper 落数据库。一个最小可用的上传接口长这样：

@RestController @RequestMapping("/api/file") public class FileController { @PostMapping("/upload") public Result<Long> upload(@RequestParam("file") MultipartFile file, @RequestParam("visibility") Integer visibility, HttpSession session) { Long userId = (Long) session.getAttribute("userId"); if (userId == null) { return Result.error("未登录"); } String originalName = file.getOriginalFilename(); String ext = getExtension(originalName); // 扩展名校验，白名单方式 if (!allowedExtSet.contains(ext.toLowerCase())) { return Result.error("不支持的文件类型: " + ext); } return fileService.upload(file, originalName, ext, visibility, userId); } private String getExtension(String name) { int idx = name == null ? -1 : name.lastIndexOf('.'); return idx >= 0 ? name.substring(idx + 1) : ""; } }

Controller 层只做三件事：拿用户身份、做文件类型初筛、把业务交给 Service。注意这里登录状态从HttpSession取，而不是让前端把 userId 传过来，前者是后端能控制的，后者不可信。

@Service public class FileServiceImpl implements FileService { @Override public Long upload(MultipartFile file, String originalName, String ext, Integer visibility, Long userId) { // 生成存储名，UUID 避免文件名冲突和路径穿越 String storedName = UUID.randomUUID().toString().replace("-", "") + "." + ext; String datePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd")); String relativePath = datePath + "/" + storedName; File target = new File(storageRoot, relativePath); if (!target.getParentFile().exists()) { target.getParentFile().mkdirs(); } try { file.transferTo(target); } catch (IOException e) { throw new BizException("文件写入磁盘失败"); } // 计算 MD5，供后续秒传与去重 String md5; try (InputStream in = file.getInputStream()) { md5 = DigestUtils.md5DigestAsHex(in); } catch (IOException e) { throw new BizException("文件校验失败"); } FileInfo info = new FileInfo(); info.setFileName(originalName); info.setFileSize(file.getSize()); info.setFileExt(ext); info.setStoragePath(relativePath); info.setMd5(md5); info.setOwnerId(userId); info.setVisibility(visibility); fileMapper.insert(info); return info.getId(); } }

这段代码有三个关键决策。第一，存储名用 UUID 而不是原始文件名，可以避免同年同月同日生的人上传同名文件互相覆盖；第二，日期目录按年/月/日分层，后续做定期清理和数据迁移都以目录为粒度，比摊平在单层目录里好维护得多；第三，file.transferTo后立刻计算 MD5，这个值不只在秒传用，也是后面校验分片合并是否损坏的依据。

3.2 大文件分片上传：前端切片、后端合并的协作细节

校园文件普遍很大，一节录像动辄 1GB 起步，普通的 POST 上传很容易把网关内存打满，也会在传输中途失败后导致全部重传。业界最常见的做法是前端分片、后端合并，分片大小按网络条件调，内网可以放到 10MB，外网建议 2-5MB。

// 前端分片上传逻辑 const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB 一片 const file = document.getElementById('fileInput').files[0]; const totalChunks = Math.ceil(file.size / CHUNK_SIZE); const fileMd5 = await calculateFileMd5(file); // 先计算完整文件 MD5，用于合并后校验 for (let i = 0; i < totalChunks; i++) { const start = i * CHUNK_SIZE; const end = Math.min(file.size, start + CHUNK_SIZE); const chunk = file.slice(start, end); const formData = new FormData(); formData.append('file', chunk); formData.append('chunkIndex', i); formData.append('totalChunks', totalChunks); formData.append('fileMd5', fileMd5); // 每个分片独立请求，失败只重传当前分片 await axios.post('/api/file/chunk', formData); } // 全部分片传完后，通知后端合并 await axios.post('/api/file/chunk/merge', { fileMd5, originalName: file.name, totalChunks: totalChunks });

前端代码里值得注意的点是await axios.post让每个分片串行上传，虽然速度不如并发快，但大幅降低了服务器压力，也方便记录进度。如果源码里用的是并发上传，务必检查是否有重试队列，否则任何一个分片失败，整个合并都会前功尽弃。

后端合并的核心逻辑是按索引顺序把临时分片拼成目标文件。这里最怕的不是性能，而是顺序错乱：

@PostMapping("/chunk/merge") public Result<Long> merge(@RequestBody MergeRequest req, HttpSession session) { String tempDir = storageRoot + "/temp/" + req.getFileMd5(); File outFile = new File(storageRoot + "/files/" + UUID.randomUUID().toString() + "_" + req.getOriginalName()); // 按 chunkIndex 排序，不要依赖文件名排序 List<File> chunkFiles = new ArrayList<>(); File[] files = new File(tempDir).listFiles(); if (files == null) { throw new BizException("分片不存在，请重新上传"); } for (File f : files) { int idx = Integer.parseInt(f.getName()); chunkFiles.add(f); } chunkFiles.sort(Comparator.comparingInt(f -> Integer.parseInt(f.getName()))); try (FileOutputStream fos = new FileOutputStream(outFile)) { byte[] buf = new byte[8192]; for (File chunk : chunkFiles) { try (FileInputStream fis = new FileInputStream(chunk)) { int len; while ((len = fis.read(buf)) != -1) { fos.write(buf, 0, len); } } } } catch (IOException e) { throw new BizException("合并失败"); } // 合并完成后校验 MD5，与前端计算的 fileMd5 比对 String mergedMd5 = md5OfFile(outFile); if (!mergedMd5.equals(req.getFileMd5())) { outFile.delete(); deleteQuietly(new File(tempDir)); throw new BizException("文件校验失败，请重新上传"); } deleteQuietly(new File(tempDir)); // 落库，逻辑与普通上传一致 FileInfo info = new FileInfo(); info.setFileName(req.getOriginalName()); info.setStoragePath("files/" + outFile.getName()); info.setMd5(mergedMd5); info.setFileSize(outFile.length()); info.setOwnerId((Long) session.getAttribute("userId")); fileMapper.insert(info); return Result.ok(info.getId()); }

合并后校验 MD5 这一步不要省，它能兜住分片在传输过程中被截断或篡改的情况。如果源码里合并完直接返回成功而不校验，建议你自己补上，这个校验成本极低但能省下大量下载后才发现的文件损坏问题。

3.3 秒传的真相：MD5 去重不是玄学，是内网刚需

秒传在校园场景里特别实用，同一份课件一个班 40 个人都传一遍，会给服务器造成 40 倍浪费。秒传的实现不复杂：上传前先算整个文件的 MD5，带着 MD5 请求后端查file_info表，如果已存在相同 MD5 且源文件还是正常状态，后端直接返回已有文件的 ID，前端跳过实际上传。

@PostMapping("/upload/check") public Result<UploadCheckVO> check(@RequestParam("md5") String md5, @RequestParam("size") Long size) { FileInfo exist = fileMapper.selectByMd5(md5); if (exist != null && exist.getStatus() == 1 && exist.getFileSize().equals(size)) { return Result.ok(new UploadCheckVO(true, exist.getId())); } return Result.ok(new UploadCheckVO(false, null)); }

判断命中时一定要加上fileSize相等这个条件。MD5 碰撞概率虽低，但不同文件大小相同且 MD5 相同的情况不是零，加上大小校验等于双保险。另外注意，秒传命中后前端页面应定位到已有文件，而不是重新生成一条记录，否则回收站清理时会把共享给全班的那份文件一起删掉。

4. 权限、分享与越权：校园场景最容易翻车的地方

4.1 文件可见性模型：私有、共享、公开的判定顺序

我把visibility的判定逻辑单独拎出来讲，是因为几乎每个基于这套源码二次开发的人都会在这里改错。正确的判定顺序应该是：公开直接放行，本人直接放行，剩下的再判断是否在共享范围内，最后默认拒绝。顺序反了，就会出现"公开文件所有人都能看，但文件主人反而被自己挡在门外"的怪现象。

public boolean canAccess(Long userId, FileInfo file) { if (file == null) { return false; } // 公开文件，任何登录用户可读 if (file.getVisibility() == 3) { return true; } // 文件归属人永远可访问 if (userId.equals(file.getOwnerId())) { return true; } // 共享范围判断，例如课程共享给某角色或某分组 if (file.getVisibility() == 2) { return shareScopeService.isFileSharedToUser(file.getId(), userId); } // 私有文件，默认拒绝 return false; }

共享范围判断里最容易漏的是课程结课后自动撤销，如果源码只有添加共享没有撤销逻辑，学生毕业后依然能访问课程文件，这在真实校园里是实实在在的合规风险。检查源码时重点看isFileSharedToUser的 SQL，一般的实现是关联角色表或分组表，如果它直接返回 true，那这个功能就是摆设。

4.2 分享链接与提取码：参数怎么设才不被薅

分享模块的设计很直观：文件主人创建一个分享记录，系统生成提取码和过期时间，拿到链接的人输入提取码查看文件。以下是创建分享的常见实现：

@PostMapping("/share") public Result<ShareVO> createShare(@RequestParam Long fileId, @RequestParam Integer shareRange, @RequestParam(required = false) Integer expireDays, HttpSession session) { Long userId = (Long) session.getAttribute("userId"); FileInfo file = fileMapper.selectById(fileId); // 关键：分享前必须校验操作者是不是文件主人 if (file == null || !file.getOwnerId().equals(userId)) { throw new BizException("只能分享自己名下的文件"); } String code = generateShareCode(8); // 8 位随机提取码 FileShare share = new FileShare(); share.setFileId(fileId); share.setShareCode(code); share.setShareRange(shareRange); if (expireDays != null && expireDays > 0) { share.setExpireTime(LocalDateTime.now().plusDays(expireDays)); } shareMapper.insert(share); return Result.ok(new ShareVO(code, share.getExpireTime())); }

分享参数设置不复杂，但需要结合校园使用习惯来定默认值。课程资料分享一般 7 天就够，跨校交流可以放宽到 30 天，永久链接容易让文件在系统里积累大量无效记录。我的习惯是生成 8 位纯数字提取码，6 位太短容易被暴力遍历，10 位以上又不方便口口相传。

4.3 越权与路径穿越：下载接口最容易成为突破口

文件系统的下载接口是黑客视角下最诱人的目标，因为它直接操作磁盘文件。最常见的漏洞有两个：一是下载接口只凭前端传入的 fileId 查库，不做权限判断；二是文件路径直接拼接用户可控的文件名。这两类漏洞都很好修复，但不少源码就是没补。

@GetMapping("/download/{id}") public ResponseEntity<Resource> download(@PathVariable Long id, HttpSession session) { Long userId = (Long) session.getAttribute("userId"); FileInfo file = fileMapper.selectById(id); // 补上权限判断，而不是直接返回文件 if (!canAccess(userId, file)) { throw new BizException("无权访问该文件"); } // 只使用数据库中的 storage_path，忽略任何前端传参 Path realPath = Paths.get(storageRoot, file.getStoragePath()).normalize(); Path rootPath = Paths.get(storageRoot).normalize(); if (!realPath.startsWith(rootPath)) { throw new BizException("非法文件路径"); } File target = realPath.toFile(); if (!target.exists()) { throw new BizException("文件不存在或已被清理"); } // 文件名做 URL 编码，避免中文下载乱码 String encodedName = URLEncoder.encode(file.getFileName(), StandardCharsets.UTF_8); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=UTF-8''" + encodedName) .body(new FileSystemResource(target)); }

这段代码里的normalize()不是可有可无，它会把../之类的路径跳转解析掉，防止用户通过畸形的 storage_path 访问服务器上的任意文件。常见做法是下载之前再做一次startsWith校验，双保险。我强烈建议在源码里全局搜索getOriginalFilename()的使用点，如果它被拼进了文件路径，那基本可以判定存在路径穿越风险。

5. 源码倒入本地后的避坑检查：现象、原因、解决

5.1 上传路径配置不对，文件全写进系统临时目录

现象：程序能正常上传，文件也显示上传成功，但服务重启后列表里的文件全部消失，或者打开文件时提示文件不存在。

原因：application.yml里把root-path配成了相对路径./files，不同启动方式解析出的工作目录不一样，用 IDE 启动和用命令行启动解析到的位置可能完全两个地方；更隐蔽的是配置了${user.home}/files，在 Linux 下解析到/root/files，在 Windows 下解析到用户目录，服务重启清理临时文件时数据跟着没了。

解决：统一改成绝对路径，例如/data/toyuan-files。启动时增加一个目录可写检查，系统起不来总比文件丢了再排查好。

# 启动前手动验证存储目录权限 mkdir -p /data/toyuan-files chown -R $(whoami) /data/toyuan-files test -w /data/toyuan-files && echo "目录可写" || echo "目录不可写"

5.2 中文文件名乱码与路径穿越

现象：上传"课程提纲.pdf"后，下载时文件名变成一串无法识别的乱码；更严重的是，用../../etc/passwd这类字符串作为文件名上传后，下载接口居然返回了服务器上的其他文件。

原因：乱码是 Spring Boot 的 response header 默认按 ISO-8859-1 编码，中文字符被错误解码；路径穿越则是代码里直接用原始文件名拼路径，没有走 UUID 存储名和路径规范化。

解决：下载时对文件名做URLEncoder.encode后再放入Content-Disposition；存储路径永远用后端生成的UUID.ext，原始文件名只作为元数据存在数据库里。这个坑一旦踩过，你会深刻理解为什么存储名不能信任任何来自用户输入的东西。

5.3 分片合并后文件损坏：MD5 校验是后悔药

现象：大视频合并后播放到中间突然花屏，压缩包打开提示"文件已损坏"，但报错的文件在单个分片状态下看起来都正常。

原因：合并时没有按chunkIndex排序，前端某一分片在网络抖动后重试，重试的分片被追加到了错误位置；也可能是某个分片实际上传失败，前端却误判为成功，后端合并时用空数据块顶替了位置。

解决：后端合并前对分片做索引排序，合并完整文件后重新计算 MD5，与前端上传前计算的 MD5 比对，不一致直接删除合并结果并返回错误信息。这里有一个血泪经验：永远不要相信前端上报的"上传成功"，后端必须以自己的 MD5 校验结果为准。

5.4 数据库连不上导致启动失败：一半是配置问题，一半是版本问题

现象：后端一启动就报Access denied for user 'root'@'localhost'，或者卡在连接 MySQL 的超时日志上半天无响应。

原因：init.sql里建的库名和application.yml里spring.datasource.url不一致；本地 MySQL 密码和源码里写死的密码不同；MySQL 8 的默认认证插件是caching_sha2_password，而源码驱动版本太老不识别。

解决：先手工导入init.sql，再核对jdbc:mysql://localhost:3306/你的库名、用户名、密码三项。如果本地是 MySQL 8，把驱动换成对应新版本，并在 JDBC 连接串里补上serverTimezone=Asia/Shanghai&useSSL=false，这一条能避开大半启动期翻车。

5.5 前端字段和后端字段对不上：接口报 400 的最常见原因

现象：前端选择文件后点上传，立刻报 400，后端日志里写着Required request part 'file' is not present。

原因：前端FormData.append用的 key 是files或file0，后端@RequestParam("file")对不上；或者前端用了某些组件库的自动上传模式，实际发送的是 JSON 而不是 multipart 表单。

解决：前后端约定字段名，凡是文件接口统一用file。检查前端上传配置里是否手动设置了Content-Type: application/json，multipart 请求必须让浏览器自动带上 boundary。我们项目组的规定是，后端接口里@RequestParam的每个字段名都要写进接口文档，前端直接对照文档敲字，不搞口头约定。

6. 拿到源码后别急着交差：在线预览与全文检索还能这么加

源码跑通只是第一关，把它变成真正能用的系统才是目标。我接手这类校园文件系统时，通常先把两个进阶能力补上：在线预览和全文检索，它们直接决定师生愿不愿意用。

在线预览的做法按文件类型拆开处理。PDF 用 pdf.js 渲染，成本最低，兼容性最好；Office 文档用 LibreOffice headless 模式转成 PDF 再走同一条预览链路，转换命令在服务器上用一行就能跑通。图片不需要做任何处理，浏览器原生支持。这样组合的好处是只需要一台带办公套件的服务器，不需要额外付费组件。

全文检索我先泼一盆冷水：不要一上来就上 Elasticsearch，那对校园单机部署是大炮打蚊子。先把 Lucene 引进来，文件上传时抽取文本内容，PDF 用 PDFBox，Word 用 POI，把标题、扩展名、抽取内容写进索引。校园场景一天的检索量最多几十万次，Lucene 的单机能力足够。

验证进阶功能可以用一个笨但有效的方法：拿一门真实课程的资料做闭环测试。20 份 PDF、10 份 Word、几段视频全部传进去，然后分别用文件名、内容关键字、分享链接三种方式找文件，任何一步卡住都能立刻暴露问题在哪个环节。

我现在的习惯是，拿到任何一套文件系统源码，先不急着改界面，而是把存储路径、数据库配置、上传上限三个配置项一次性核完再启动。这套顺序帮我避开了绝大多数启动期的玄学分叉问题，也让后续排查问题时能直接排除掉环境因素。希望帮到你。

本文还有配套的精品资源，点击获取