做一个西式点心的视频小程序时最容易被低估的模块往往不是推荐算法、不是 AI 对话而是文件处理。视频上传、封面生成、头像裁剪、字幕导入、AI 分析素材暂存每一个功能都绕不开同一个底层问题文件怎么存、怎么校验、怎么命名、怎么清理。很多项目做到后面出现磁盘被占满、文件名乱码、上传了非法格式、Linux 环境下路径拼接出错问题根源都出在“文件工具类”这个不起眼的地基上。本文是“基于 SpringBoot Vue Uniapp LangChain4j SpringAI 的智能视频推荐小程序”系列教程的第八讲聚焦文件工具类的完整实现。前面几讲解决了项目骨架、小程序端框架、AI 对话与视频推荐链路这一讲补上基础设施里最关键的一块拼图。读完后你会得到一套可以直接落地到 SpringBoot 项目中的文件处理工具类包括扩展名白名单校验、大小限制、UUID 命名、日期分目录、视频封面抽取和定时清理策略。同时我会把 LangChain4j 和 SpringAI 在文件场景中的关联位置讲清楚——AI 要理解一个视频第一步永远是正确读取它的文件。1. 智能视频推荐小程序为什么需要一个文件工具类先说一个容易踩坑的事实很多教程里所谓的“文件上传”就是把MultipartFile.transferTo()一写然后返回一个 URL。这种做法在本地 Demo 里看起来没问题一旦进入真实项目立刻暴露出三个问题。第一个问题是文件内容不可控。没有任何校验用户传了一个 5GB 的视频或者一个 .exe 文件后端照单全收。存储空间被浪费安全性也没有保障。第二个问题是文件名不可控。用户上传的文件名可能包含中文、空格、特殊字符如果直接拿原始文件名存到磁盘轻则出现 URL 访问乱码重则在 Linux 服务器上导致路径解析异常。第三个问题是资源不可控。视频推荐小程序的特点是文件数量大、单文件体积大。如果没有按业务类型和日期分目录没有统一的删除和清理机制运维阶段会非常痛苦。所以这个项目的文件工具类不是简单封装几个static方法而是要做四件事校验扩展名白名单 文件大小上限。存储统一根目录按业务类型和日期分目录UUID 重命名。处理提供视频封面抽取、临时文件清理等业务方法。对接让 Controller、Service、AI 分析模块都能通过一套 API 操作文件而不是各自为政。这套设计做完后续接 LangChain4j 做视频内容理解时AI 模块只需要调用fileStorageService.getFile(fileId)拿到文件路径再交给 LLM 处理即可不需要关心文件是从哪儿来、存在哪里。2. 文件工具类涉及的核心概念与边界在开始写代码之前先把几个容易混淆的概念理清。2.1 本地存储、OSS 与 MinIO本项目默认使用本地磁盘存储也就是把文件保存在 SpringBoot 应用所在的服务器目录下。这样做的原因是小程序开发阶段的用户量有限本地存储足够支撑功能演示和联调。如果后续上线视频文件建议迁移到 MinIO 或 OSS。文件工具类的接口设计要预留切换空间比如FileStorageService接口中只暴露save、load、delete三个方法底层是本地磁盘还是对象存储对调用方完全透明。2.2 MultipartFile 与 FileSpringBoot 接收小程序端上传的文件时参数类型是org.springframework.web.multipart.MultipartFile。它代表一个内存或临时磁盘中的上传文件我们需要把它转存到指定目录。这里有一个常见误区很多人以为transferTo()之后就万事大吉。其实transferTo()对目标路径有要求如果目标目录不存在或者目标磁盘空间不足会抛出 IOException。稳健的做法是先创建目录再执行保存。2.3 扩展名校验白名单与 MIME 类型扩展名判断是文件安全的第一道防线。常见的错误写法是直接判断filename.endsWith(.jpg)这样遇到photo.jpg.exe就失效。更稳健的方式是取最后一个点后面的字符串转成小写再判断是否在白名单中。MIME 类型同样可以被伪造不建议作为唯一判断标准。本项目的做法是扩展名白名单 文件大小限制 前端预览辅助校验同时在后端解析视频文件时进行真实格式探测。2.4 UUID 文件名与日期分目录文件保存路径建议采用如下格式{basePath}/{bizType}/{yyyyMMdd}/{uuid}.{ext}其中bizType业务类型比如avatar、video、cover。yyyyMMdd上传日期避免单个目录文件过多方便按日期清理。uuid唯一文件名防止重名冲突也避免用户原始文件名里的中文、特殊字符进入磁盘路径。3. 环境准备与前置条件本讲代码基于以下环境版本请以你自己项目的实际版本为准这里展示的是通用实现思路。技术栈说明JDK17项目使用 SpringBoot 3.x所以 JDK 版本不能太低Spring Boot3.x集成 SpringAI 时需要使用与 Boot 3 匹配的版本Maven负责依赖管理MySQL业务数据存储FFmpeg用于视频封面抽取属于可选的本地命令行工具Uniapp / Vue小程序端和后台管理端本讲只涉及调用后端上传接口在pom.xml中除了 SpringBoot Web 依赖还需要引入参数校验和文件存储配置所需的依赖。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-configuration-processor/artifactId optionaltrue/optional /dependencyspring-boot-configuration-processor用于让自定义配置类在 IDE 中获得提示不是运行时的必须依赖但在团队协作时体验更好。如果你计划让 AI 模块直接读取视频文件做内容理解建议同时确认spring-ai或langchain4j相关依赖已经加入。本讲不会展开 AI 调用细节但会给出文件工具类如何为它们服务的示例。4. 文件存储配置与统一配置类首先在application.yml中增加文件存储配置。file: storage: base-path: /data/video-recommend/files max-size: 104857600 allowed-extensions: - jpg - jpeg - png - mp4 - avi - mov cover: temp-path: /data/video-recommend/temp配置项说明配置说明file.storage.base-path文件上传根目录file.storage.max-size单文件最大字节数示例为 100MBfile.storage.allowed-extensions允许的扩展名列表file.cover.temp-path视频封面抽取的临时文件目录然后创建配置读取类。// 文件路径src/main/java/com/example/videorecommend/config/FileStorageProperties.java package com.example.videorecommend.config; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; import java.util.List; Component ConfigurationProperties(prefix file.storage) public class FileStorageProperties { /** * 文件上传根目录 */ private String basePath; /** * 单文件最大字节数 */ private long maxSize; /** * 允许的扩展名 */ private ListString allowedExtensions; public String getBasePath() { return basePath; } public void setBasePath(String basePath) { this.basePath basePath; } public long getMaxSize() { return maxSize; } public void setMaxSize(long maxSize) { this.maxSize maxSize; } public ListString getAllowedExtensions() { return allowedExtensions; } public void setAllowedExtensions(ListString allowedExtensions) { this.allowedExtensions allowedExtensions; } }使用ConfigurationProperties而不是Value的好处是配置项多了之后代码更整洁并且在 IDEA 中能看到配置提示。注意类中的属性名要和配置前缀匹配。5. 文件工具类核心实现这是本讲的重点。我会把文件工具类拆成三个部分校验工具、存储服务、视频处理扩展。5.1 扩展名与大小校验工具先写一个纯静态工具类负责最基本的校验逻辑。这个类可以脱离 Spring 环境测试方便单元测试。// 文件路径src/main/java/com/example/videorecommend/util/FileValidateUtils.java package com.example.videorecommend.util; import com.example.videorecommend.common.exception.BusinessException; import org.springframework.web.multipart.MultipartFile; import java.util.List; import java.util.Locale; public class FileValidateUtils { private FileValidateUtils() { } /** * 获取文件扩展名转小写 */ public static String getExtension(String filename) { if (filename null || filename.lastIndexOf(.) 0) { return ; } return filename.substring(filename.lastIndexOf(.) 1) .toLowerCase(Locale.ROOT); } /** * 校验扩展名是否在白名单中 */ public static boolean isAllowedExtension(String filename, ListString allowed) { String ext getExtension(filename); if (ext.isEmpty()) { return false; } return allowed.stream().anyMatch(ext::equalsIgnoreCase); } /** * 校验文件大小是否超过限制 */ public static boolean isAllowedSize(MultipartFile file, long maxSize) { return file.getSize() 0 file.getSize() maxSize; } /** * 综合校验不通过时抛出业务异常 */ public static void validate(MultipartFile file, ListString allowed, long maxSize) { if (file null || file.isEmpty()) { throw new BusinessException(上传文件不能为空); } if (!isAllowedExtension(file.getOriginalFilename(), allowed)) { throw new BusinessException(文件类型不支持仅支持 allowed); } if (!isAllowedSize(file, maxSize)) { throw new BusinessException(文件大小超出限制最大 maxSize 字节); } } }这里BusinessException是项目自定义异常也可以替换成你自己的异常类甚至直接使用IllegalArgumentException。关键在于文件校验失败不要静默返回而要抛出清晰异常由全局异常处理器统一转成 JSON 响应给前端。5.2 文件存储服务下一层是FileStorageService。它负责真正的磁盘读写、路径规划和删除操作。为什么不能把保存逻辑也放在静态工具类里因为保存需要读取配置根目录、允许扩展名静态方法不方便注入配置也难以在测试中替换。所以项目里更推荐纯逻辑放静态工具类涉及 IO 和配置放 Spring Service。// 文件路径src/main/java/com/example/videorecommend/service/FileStorageService.java package com.example.videorecommend.service; import com.example.videorecommend.config.FileStorageProperties; import com.example.videorecommend.util.FileValidateUtils; import org.springframework.stereotype.Service; import org.springframework.web.multipart.MultipartFile; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.time.LocalDate; import java.time.format.DateTimeFormatter; import java.util.UUID; Service public class FileStorageService { private final FileStorageProperties fileStorageProperties; public FileStorageService(FileStorageProperties fileStorageProperties) { this.fileStorageProperties fileStorageProperties; } /** * 保存文件返回相对路径 * * param file 上传文件 * param bizType 业务类型比如 avatar / video / cover */ public String saveFile(MultipartFile file, String bizType) { FileValidateUtils.validate( file, fileStorageProperties.getAllowedExtensions(), fileStorageProperties.getMaxSize() ); String ext FileValidateUtils.getExtension(file.getOriginalFilename()); String datePath LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE); String uuid UUID.randomUUID().toString().replace(-, ); String filename uuid . ext; // 相对路径bizType/yyyyMMdd/uuid.ext String relativePath bizType / datePath / filename; Path targetDir Paths.get(fileStorageProperties.getBasePath(), bizType, datePath); Path targetFile Paths.get(fileStorageProperties.getBasePath(), relativePath); try { Files.createDirectories(targetDir); file.transferTo(targetFile); } catch (IOException e) { throw new RuntimeException(文件保存失败, e); } return relativePath; } /** * 根据相对路径删除文件 */ public boolean deleteFile(String relativePath) { if (relativePath null || relativePath.isBlank()) { return false; } Path filePath Paths.get(fileStorageProperties.getBasePath(), relativePath); try { return Files.deleteIfExists(filePath); } catch (IOException e) { return false; } } /** * 获取文件的完整访问 URL本地静态资源映射后的地址 */ public String buildFileUrl(String relativePath) { return /files/ relativePath; } }关键点DateTimeFormatter.BASIC_ISO_DATE会生成20250601格式的日期目录比带横杠的格式更适合目录命名。UUID.randomUUID().toString().replace(-, )生成 32 位无横杠字符串避免文件名过长。file.transferTo(targetFile)在targetDir创建完成后调用确保目标目录存在。返回值是相对路径这样未来切换 OSS 时buildFileUrl只需改成拼接 OSS 域名业务层不用大改。5.3 静态资源映射为了让上传后的文件可以通过 URL 访问需要配置 SpringBoot 的静态资源映射把/files/**映射到本地根目录。// 文件路径src/main/java/com/example/videorecommend/config/WebMvcConfig.java package com.example.videorecommend.config; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; Configuration public class WebMvcConfig implements WebMvcConfigurer { private final FileStorageProperties fileStorageProperties; public WebMvcConfig(FileStorageProperties fileStorageProperties) { this.fileStorageProperties fileStorageProperties; } Override public void addResourceHandlers(ResourceHandlerRegistry registry) { String basePath fileStorageProperties.getBasePath(); String location basePath.endsWith(/) ? file:/// basePath : file:/// basePath /; registry.addResourceHandler(/files/**) .addResourceLocations(location); } }这里有一点需要特别注意Windows 和 Linux 的路径写法不同。Windows 下file:///D:/data/video-recommend/files/Linux 下file:///data/video-recommend/files/。项目上线后往往部署在 Linux所以不要把D:这类路径写死在代码里一定要从配置读取。6. 视频封面抽取与 AI 模块的衔接智能视频推荐小程序里视频封面是推荐流展示的关键。用户上传视频后系统需要自动抽取一帧作为封面。这个动作本质上也是一类文件操作值得纳入文件工具类的扩展能力。本项目的实现方式是调用本地 FFmpeg 命令从视频第 1 秒抽取一帧画面生成封面图片。// 文件路径src/main/java/com/example/videorecommend/util/VideoProcessUtils.java package com.example.videorecommend.util; import java.io.IOException; import java.nio.file.Path; public class VideoProcessUtils { private VideoProcessUtils() { } /** * 使用 FFmpeg 抽取视频指定时间的某一帧 * * param videoPath 视频完整路径 * param coverPath 输出的封面图片路径 * param time 抽取时间点格式如 00:00:01 */ public static boolean extractFrame(String videoPath, String coverPath, String time) { ProcessBuilder processBuilder new ProcessBuilder( ffmpeg, -i, videoPath, -ss, time, -vframes, 1, -y, coverPath ); processBuilder.redirectErrorStream(true); try { Process process processBuilder.start(); int exitCode process.waitFor(); return exitCode 0; } catch (IOException | InterruptedException e) { Thread.currentThread().interrupt(); return false; } } }在FileStorageService中增加一个组合方法保存视频后立即抽取封面并把封面文件也纳入统一存储路径。public String saveVideoAndGenerateCover(MultipartFile videoFile) { // 1. 保存视频 String videoRelativePath saveFile(videoFile, video); // 2. 构造完整路径 Path videoFullPath Paths.get(fileStorageProperties.getBasePath(), videoRelativePath); // 3. 生成封面相对路径 String ext jpg; String datePath LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE); String uuid UUID.randomUUID().toString().replace(-, ); String coverRelativePath cover/ datePath / uuid . ext; Path coverFullPath Paths.get(fileStorageProperties.getBasePath(), coverRelativePath); Path coverDir coverFullPath.getParent(); try { if (coverDir ! null) { Files.createDirectories(coverDir); } boolean success VideoProcessUtils.extractFrame( videoFullPath.toString(), coverFullPath.toString(), 00:00:01 ); if (success) { return coverRelativePath; } } catch (IOException e) { throw new RuntimeException(视频封面生成失败, e); } // 4. 抽取失败时返回 null由业务层决定后续逻辑 return null; }这段代码把“上传视频 生成封面”组合成了一个完整业务动作数据库里可以同时保存视频路径和封面路径。接下来回到 AI 模块。LangChain4j 和 SpringAI 要做视频内容理解或者给视频生成推荐标签首先需要一个可读的输入来源。本项目目前的做法是先把视频抽帧成图片再把图片作为多模态输入交给 AI 模型。也就是说文件工具类抽出的封面帧同时也是 AI 视觉模型的输入素材。// 伪代码示例AI 模块读取封面交给 LangChain4j 做图像理解 String coverFullPath /data/video-recommend/files/ coverRelativePath; ImageUrl imageUrl ImageUrl.builder() .url(coverFullPath) .build(); String description langChainService.describeImage(imageUrl);实际接入时你需要根据所用模型支持的输入格式调整。核心思路是不要让 AI 模块直接操作磁盘文件而是由文件工具类统一产出图片、文本或字幕文件AI 模块只消费这些产出物。这样文件路径变化、存储切换都不会影响 AI 调用代码。7. 控制器层与前端上传接口对接工具类最终要通过 Controller 暴露给前端小程序调用。// 文件路径src/main/java/com/example/videorecommend/controller/FileController.java package com.example.videorecommend.controller; import com.example.videorecommend.common.ApiResponse; import com.example.videorecommend.service.FileStorageService; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import org.springframework.web.multipart.MultipartFile; import java.util.HashMap; import java.util.Map; RestController RequestMapping(/api/file) public class FileController { private final FileStorageService fileStorageService; public FileController(FileStorageService fileStorageService) { this.fileStorageService fileStorageService; } /** * 上传视频并生成封面 */ PostMapping(/upload/video) public ApiResponseMapString, Object uploadVideo(RequestParam(file) MultipartFile file) { String videoPath fileStorageService.saveFile(file, video); String coverPath fileStorageService.saveVideoAndGenerateCover(file); MapString, Object data new HashMap(); data.put(videoUrl, fileStorageService.buildFileUrl(videoPath)); data.put(coverUrl, coverPath null ? : fileStorageService.buildFileUrl(coverPath)); return ApiResponse.success(data); } /** * 上传头像 */ PostMapping(/upload/avatar) public ApiResponseString uploadAvatar(RequestParam(file) MultipartFile file) { String avatarPath fileStorageService.saveFile(file, avatar); return ApiResponse.success(fileStorageService.buildFileUrl(avatarPath)); } }前端 Uniapp 小程序端通过uni.uploadFile上传文件代码大致如下uni.chooseVideo({ count: 1, sourceType: [album, camera], success: (res) { uni.uploadFile({ url: https://你的后端域名/api/file/upload/video, filePath: res.tempFilePath, name: file, success: (uploadRes) { const result JSON.parse(uploadRes.data); console.log(视频地址, result.data.videoUrl); console.log(封面地址, result.data.coverUrl); } }); } });注意name字段必须和后端RequestParam(file)的参数名保持一致否则后端接收不到文件。Vue 管理后台中用el-upload或者普通input[typefile]上传逻辑类似只需要把FormData中的 key 也设为file。8. 运行结果与验证启动 SpringBoot 项目后用 Postman 或者 curl 模拟一次文件上传。curl -X POST http://localhost:8080/api/file/upload/avatar \ -F file/Users/test/avatar.jpg预期返回{ code: 200, message: success, data: /files/avatar/20250601/3f1a9b0c2d6e4f5a8b7c9d0e1f2a3b4c.jpg }在浏览器中访问http://localhost:8080/files/avatar/20250601/3f1a9b0c2d6e4f5a8b7c9d0e1f2a3b4c.jpg如果能看到图片说明静态资源映射和文件保存都正常。验证目录结构/data/video-recommend/files └── avatar └── 20250601 ├── 3f1a9b0c2d6e4f5a8b7c9d0e1f2a3b4c.jpg └── 9e7a1b2c3d4e5f6a7b8c9d0e1f2a3b4c.jpg如果上传了一个超出允许扩展名的文件响应中应当返回异常信息例如{ code: 400, message: 文件类型不支持仅支持[jpg, jpeg, png, mp4, avi, mov], data: null }当视频上传成功但封面生成失败时先确认服务器上是否安装 FFmpeg并且ffmpeg命令是否在 PATH 中。在 Linux 上可以用which ffmpeg检查。9. 常见问题与排查思路问题现象可能原因排查方式解决方案上传文件后访问 URL 返回 404静态资源映射路径未生效查看 WebMvcConfig 是否被扫描到确认 config 包在 SpringBoot 启动类能扫描到的位置文件名变成乱码原始文件名包含中文或特殊字符检查数据库和磁盘文件名统一使用 UUID 重命名不要保留原始文件名transferTo 报 NoSuchFileException目标目录不存在检查 basePath 目录是否创建保存前先 Files.createDirectories文件上传成功后没有权限访问Linux 目录权限不足检查 Nginx 或应用进程的运行用户使用 chmod 或为上传目录分配正确权限视频封面生成失败FFmpeg 未安装或视频编码不兼容手工执行 ffmpeg 命令看报错安装 FFmpeg或改用 JavaCV 方案上传大视频时请求超时默认的 SpringBoot 上传大小限制过低查看spring.servlet.multipart.max-file-size在 application.yml 中调大限制磁盘空间被占满文件没有定时清理检查临时文件和 deleted 记录启动定时任务定期清理过期文件针对最后一条我在项目中增加了一个简单的定时清理任务每天凌晨清理临时目录中超过 7 天的文件。这是文件工具类保持生产可用的关键一环否则测试环境会积累大量垃圾文件。// 文件路径src/main/java/com/example/videorecommend/task/FileCleanTask.java package com.example.videorecommend.task; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Component; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.time.LocalDate; import java.time.temporal.ChronoUnit; Component public class FileCleanTask { private static final Logger log LoggerFactory.getLogger(FileCleanTask.class); /** * 每天凌晨 2 点执行一次 */ Scheduled(cron 0 0 2 * * ?) public void cleanTempFiles() { Path tempRoot Paths.get(/data/video-recommend/temp); try (var stream Files.walk(tempRoot, 3)) { stream.filter(Files::isRegularFile) .filter(path - { try { LocalDate fileDate LocalDate.parse( path.getParent().getFileName().toString() ); return ChronoUnit.DAYS.between(fileDate, LocalDate.now()) 7; } catch (Exception e) { return true; } }) .forEach(path - { try { Files.deleteIfExists(path); log.info(清理临时文件{}, path); } catch (IOException e) { log.warn(清理临时文件失败{}, path, e); } }); } catch (IOException e) { log.error(扫描临时目录失败, e); } } }注意定时任务类需要配合EnableScheduling才能生效。可以在启动类上添加该注解。简单的实现是遍历临时目录根据日期目录名判断过期时间删除超过 7 天的文件。这个任务仅清理临时目录不能清理正式上传目录避免误删用户数据。10. 最佳实践与工程建议文件工具类写完后项目中的使用体验会明显改善。经过这段代码落地以下几条建议非常值得保留到团队规范中。第一所有文件访问都通过 Service 层禁止在业务代码里直接拼接磁盘路径。典型的坏味道是 Controller 里出现Paths.get(/data/xxx/ userId / filename)。这种代码一旦出现两次路径规则就失控了。统一收敛到FileStorageService后续加权限、加缓存、换 OSS 都容易很多。第二保存文件前先做扩展名校验但也不要完全相信扩展名。视频推荐小程序的上传入口可能被脚本攻击白名单只能挡住一半。更稳妥的做法是保存后用 FFmpeg 或 JavaCV 做真实格式探测确认文件确实是视频再写入数据库。这样会多花一点资源但安全性值得。第三数据库只存相对路径不存绝对路径。如果数据库里存的是/data/video-recommend/files/avatar/20250601/uuid.jpg未来迁移到对象存储或更换应用服务器所有历史数据都要更新。如果只存avatar/20250601/uuid.jpg加一层buildFileUrl做拼接迁移成本可以忽略。第四给不同业务类型的文件设置不同的目录并规划好生命周期。头像、封面这类小文件保留时间长视频原文件体积大可能要考虑转码后删除原文件临时素材文件则定期清理。目录设计越早规划后续运维越省心。第五应对外部访问权限。视频推荐小程序的封面和头像通常是公开访问的但部分上传文件可能是用户私密内容。在 Controller 层做访问控制或者把私有文件放在静态资源映射之外通过认证接口下载。本项目目前对封面、头像使用公开 URL私密文件不在本讲范围内。第六注意上传大小限制。SpringBoot 默认上传大小是 1MB对于视频项目来说远远不够一定要在application.yml中调整。spring: servlet: multipart: max-file-size: 200MB max-request-size: 220MBmax-file-size是单文件限制max-request-size是单次请求的总大小。如果前端一次上传多个文件两个参数都要合理设置。11. 总结与下一步实践建议本讲的篇幅虽然集中在“文件工具类”但它解决的是智能视频推荐小程序从开发到上线整个链路中非常基础的问题。回到开头那个判断文件处理模块写得好的项目和写得稀烂的项目差距在前几周还不明显一旦开始联调、测试、部署稳定性的差距会瞬间拉开。这一讲真正讲清了几件事文件工具类的定位不是“上传工具”而是统一管理校验、存储、路径、清理、AI 素材产出的基础设施。校验逻辑和存储逻辑分离纯静态工具类负责判断Spring Service 负责 IO 和配置。UUID 重命名 日期分目录 相对路径存储是本地存储阶段最稳妥的组合方式。视频封面抽取通过 FFmpeg 命令实现抽取结果同时也是 LangChain4j / SpringAI 多模态输入的一部分。定时清理临时文件是生产环境必不可少的补充机制。下一步建议你做三件事把上面的FileStorageService、VideoProcessUtils和FileValidateUtils复制到自己的项目中根据实际情况调整BusinessException类型和配置项。配置一个测试用的上传接口用 curl 上传一张图片、一段小视频确认磁盘目录、URL 访问、异常提示都符合预期。如果你的项目已经接入了 LangChain4j 或 SpringAI试着把生成的封面图片作为多模态输入传给模型验证整个“文件 - 图片 - AI 理解”的链路能否跑通。下一讲可以继续围绕视频推荐的核心流程展开比如视频标签生成、用户向量检索或者推荐列表的组装。每一步都会用到文件工具类产出的素材。先把文件地基打牢后面的功能才走得稳。