做内容管理的这些年我发现一个很普遍的痛点图片、视频、PPT、音频散落在各人电脑、聊天记录和共享盘里要用的时候找不到找到了又是旧版。后来我花时间基于SpringBootVueMyBatisMySQL搭了一套web多媒体素材管理系统把上传、分类、标签检索、预览、下载这些环节串成一条线中间踩了不少坑也沉淀了不少经验。这篇文章不打算写成标准的需求文档而是把整个系统的落地过程拆开讲——数据库表怎么设计、文件到底存哪里、视频预览怎么做到浏览器免插件播放、联调阶段那些报错怎么排查。无论你是准备拿这个方向做课程设计还是要在团队内部搭一套素材库看完这篇再动手能省很多弯路。1. 这套系统的定位与整体技术架构1.1 多媒体素材管理系统到底在解决什么问题先搞清楚一个前提市面上做素材管理的系统很多但大多数要么太重要么太轻。重的像数字资产管理平台动不动就聊工作流和权限矩阵小团队根本用不起来轻的又只是个上传下载工具连个分类和按类型筛选都做不到。我做的这套定位很明确面向中小团队和个人开发者的轻量级素材中心核心解决三件事——集中存储、快速检索、在线预览。具体功能包括素材上传图片/视频/音频/文档、自定义分类、标签打标、多条件组合搜索类型、分类、上传时间、关键词、列表预览、在线视频播放、图片缩略图展示、下载与统计。没有任何花哨的功能但每一个都是日常用得上的。这个定位决定了后续所有技术选型——不追求复杂追求跑起来稳、改起来快。从部署角度看这套系统也足够轻。SpringBoot打一个jar包Vue打包成静态文件丢给NginxMySQL存元数据MinIO存文件本体四样东西就能跑起一整套环境。对于想要做毕业设计、个人作品集或者课题演示的同学这个体量刚好合适。1.2 为什么是SpringBootVueMyBatisMySQL这套组合技术选型这件事我见过太多人在第一步就被带偏。有人上来就要上微服务有人非要用NoSQL结果一个素材管理系统搞得比电商平台还复杂。我应该明确一点这套组合不是因为新潮而是因为匹配。SpringBoot解决的是后端开发效率。内置Tomcat、自动装配、简化配置让团队能把精力放在业务逻辑上。相比传统的SSM要写一堆XML配置SpringBoot最大的价值是默认值足够合理特殊项才需要覆盖。对中小项目来说开发速度确实快得多。Vue解决的是前端交互复杂度。素材管理天然有大量列表、筛选器、弹窗、上传组件Vue的组件化在控制这类复杂度上优势明显。而且Vue生态里现成的UI库、懒加载插件、播放器封装一抓一大把不用从零造轮子。MyBatis在ORM里不是执行效率最高的但一定是最适合这种查询条件多变场景的。素材搜索往往是多个动态条件排列组合用MyBatis的where、if、choose动态SQL可以干净地拼接SQL。这里说明一下如果你把JPA的Specification拿出来对比会发现它也能做但MyBatis对一票后端开发者来说更直觉——看得见SQL心里踏实。MySQL就更不用说了免费、普及率高、团队里随手拉一个人都能上手。素材系统的元数据量级根本到不了MySQL的瓶颈关系型数据库在这种场景下的优势——事务、索引、联表查询——反而能发挥得最充分。再加上MinIO做对象存储后面专门讲文件流和数据流分离整套架构非常清爽。1.3 前后端请求链路与目录结构先看一张执行到内存里的请求流程浏览器访问Vue打包后的页面用户在素材列表页点分类、输入关键词、触发搜索前端组装Query参数调用后端/api/material/list接口SpringBoot的Controller接收参数后交给ServiceService调用MapperMyBatis通过XML里的动态SQL查MySQL返回分页结果前端拿到数据渲染列表缩略图从MinIO或本地映射路径加载点击视频预览时播放器拉取多媒体流地址。整个链路是标准的前后端分离结构前端Vue Vue Router Element Plus或同类UI库打包后部署在Nginx后端SpringBoot按Controller/Service/Mapper三层组织数据库MySQL 8.x存素材元数据存储MinIO存图片、视频、音频、文档原始文件目录上后端按功能分包controller放接口层service放业务逻辑mapper放MyBatis的Mapper接口model放实体和DTOconfig放跨域、MinIO、MyBatis等配置类mapper/xml放动态SQL映射文件。前端按页面划分views/material放素材列表和上传页components放预览弹窗、卡片组件等公用组件router放路由配置api放axios请求封装。这个结构在新增功能时不需要复杂的思考跟着已有的模块写就行。说句实在话对素材管理这种CRUD占比很高的系统结构清晰比什么都重要。2. 数据库设计与MyBatis层的关键细节2.1 素材表结构如何设计才抗造素材管理系统的核心表是material_info我见过很多糟糕的表设计上来就存Base64图片进数据库或者把文件路径写成C:\user\xxx\aa.jpg这种绝对路径后期全是泪。这里分享一下我最终定下来的表结构CREATE TABLE material_info ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT 主键, material_no VARCHAR(32) DEFAULT NULL COMMENT 素材编号, title VARCHAR(255) NOT NULL COMMENT 素材标题, material_type TINYINT NOT NULL COMMENT 类型1图片 2视频 3音频 4文档, suffix VARCHAR(16) DEFAULT NULL COMMENT 文件后缀, file_size BIGINT DEFAULT 0 COMMENT 文件大小字节, storage_type TINYINT DEFAULT 1 COMMENT 存储位置1本地 2MinIO, bucket_name VARCHAR(64) DEFAULT NULL COMMENT MinIO桶名, object_key VARCHAR(255) DEFAULT NULL COMMENT MinIO对象键, file_url VARCHAR(512) DEFAULT NULL COMMENT 完整访问地址, thumbnail_url VARCHAR(512) DEFAULT NULL COMMENT 缩略图地址, category_id BIGINT DEFAULT NULL COMMENT 分类ID, tags VARCHAR(512) DEFAULT NULL COMMENT 逗号分隔标签, duration INT DEFAULT 0 COMMENT 音视频时长秒, width INT DEFAULT 0 COMMENT 图片宽, height INT DEFAULT 0 COMMENT 图片高, status TINYINT DEFAULT 1 COMMENT 状态0禁用 1启用, download_count INT DEFAULT 0 COMMENT 下载次数, create_by VARCHAR(64) DEFAULT NULL COMMENT 上传人, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 上传时间, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新时间, PRIMARY KEY (id), KEY idx_type_time (material_type, create_time), KEY idx_category_time (category_id, create_time) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT素材信息表;几个关键设计点我单独说明file_size用BIGINT存字节数不要用varchar存2.5MB这种字符串业务层展示时再转换否则没法做排序和统计。material_type用TINYINT数字枚举而不是字符串后端用常量或枚举类做映射。前端界面展示的是由后端转换后的中文名称数据库里只存数字查询更快也更省空间。文件地址同时保留object_key和file_url。object_key用于MinIO的API操作file_url用于直接返回给前端展示。两者别混了。标签不用单独建关联表直接逗号分隔存字符串。理由很简单标签查询一般就是LIKE匹配量级不大在素材系统里完全够用。如果你打算以后做复杂的标签聚合统计再考虑拆表。update_time务必用ON UPDATE CURRENT_TIMESTAMP自动维护别让代码手动更新省很多事。分类表就简单多了id、parent_id、category_name、sort_order。如果要做二级分类就加层级不做就把parent_id置空。这里不建议做无限极递归分类浏览型功能做两级就够层级太深反而让前端面包屑和筛选器变复杂。2.2 多条件搜索的分页SQL与动态查询素材列表页的核心接口是分页查询而且必须是多条件可选条件的组合查询。参数大致有当前页、每页条数、素材类型、分类ID、标签关键词、标题关键词、时间范围。用MyBatis写这种查询动态SQL的优势就体现出来了。核心SQL长这样select idselectPageList resultMapMaterialResultMap SELECT * FROM material_info where if testquery.materialType ! null AND material_type #{query.materialType} /if if testquery.categoryId ! null AND category_id #{query.categoryId} /if if testquery.keyword ! null and query.keyword ! AND (title LIKE CONCAT(%, #{query.keyword}, %) OR tags LIKE CONCAT(%, #{query.keyword}, %)) /if if testquery.startTime ! null AND create_time gt; #{query.startTime} /if if testquery.endTime ! null AND create_time lt; #{query.endTime} /if /where ORDER BY create_time DESC /select细节上强调两点。第一where标签会自动去掉第一个多余的AND这个特性是MyBatis专门为动态条件设计的能避免WHERE前面多个AND这种低级报错。第二时间比较用gt;和lt;因为XML中不能直接写这是很多人第一次写动态SQL就报错的地方。分页组件我用的PageHelper。用法很简单查询前执行一行PageHelper.startPage(pageNum, pageSize)紧接着的第一次MyBatis查询就会自动拼接LIMIT并且返回PageInfo对象里带total、pages、list这些现成数据。有一点要注意PageHelper.startPage后只能接一条查询语句如果中间有其它查询分页会串掉线上环境很容易栽在这。另外性能上有个优化点可以提一下素材列表页的统计数total和列表数据查询PageHelper默认会生成两条SQL——count查询和分页查询。如果你的数据量到了几十万条count查询的耗时就会上来可以考虑把count的SQL单独优化或者干脆用缓存记录各分类下的素材总数。对中小系统来说先记着有这个事不必过度设计。2.3 MyBatis配置里容易踩的坑MyBatis在SpringBoot里跑得多了有几个配置点我几乎每次都要检查一遍提出来给各位打个预防针。数据库字段命名建议全部用下划线风格如create_time实体类用驼峰风格如createTime然后在application.yml里配上mybatis: configuration: map-underscore-to-camel-case: true mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.material.entity不要小看这一行map-underscore-to-camel-case。我第一次做项目的时候没配这个结果实体的createTime映射不到create_time查出来全是null排查了半天才发现是这么个小配置。一旦配好MyBatis会自动做字段名和属性名的驼峰映射。第二个坑是XML映射文件没被打包进target/classes。SpringBoot的Maven构建默认不会把src/main/java下的XML拷到classes目录所以很多人写的mapper/*.xml一运行就报Invalid bound statement (not found)。解决办法就是在pom.xml里加一段资源声明resources resource directorysrc/main/java/directory includes include**/*.xml/include /includes /resource /resources或者更规范一点把XML统一放到src/main/resources/mapper目录下这样根本不用额外配置。我现在习惯是XML作为一个mapper/资源目录存放规整而且省心。第三个要聊的是MyBatis缓存。MyBatis默认开启一级缓存SqlSession级别和可选的二级缓存namespace级别。听起来很美但在素材管理这种多表关联实时更新的场景里缓存反而容易造成脏数据。比如一个素材更新了分类但统计分类数的查询缓存还没失效你看到的数据就是旧的。我的建议是系统里默认关闭二级缓存把缓存交给Redis来做可控性更强。你可以在application.yml里加上mybatis: configuration: cache-enabled: false不搞全局缓存查询条件复杂时直接查库配合MySQL的索引和分页性能完全够用。3. 媒体文件存储与处理从本地上传到MinIO3.1 为什么素材文件不能一股脑塞进服务器本地磁盘最初版本我把文件存到服务器本地的/data/uploads目录结果一段时间之后问题接踵而至磁盘告警、没有副本的单点风险、服务器迁移时要把几Gb甚至几Tb的文件拷来拷去痛苦得很。数据库里存的是元数据文件本体应该交给专门的对象存储服务。在方案选型时详细对比了MinIO、阿里云OSS、腾讯云COS。OSS和COS胜在托管稳定但需要联网、按量付费MinIO的优点是开源、私有化部署、S3协议兼容而且SDK用起来和云厂商的对象存储几乎一致。对上素材管理系统这种内网自用的场景MinIO天然就是最优解。如果你的服务跑在公网云服务器上同样的代码把MinIO的Endpoint换成OSS的几乎没有学习成本。热词搜索里也反复出现minio加入到springboot和springboot整合说明这已经是素材类系统的标准做法了这篇文章就干脆把这套方案完全铺开。3.2 MinIO接入SpringBoot的完整过程首先是MinIO服务的部署。最简单的方式用Docker拉一个容器docker run -d \ --name minio \ -p 9000:9000 \ -p 9001:9001 \ -e MINIO_ROOT_USERminioadmin \ -e MINIO_ROOT_PASSWORDminioadmin123 \ quay.io/minio/minio server /data --console-address :90019000是S3 API端口9001是Web控制台端口。部署完成后访问控制台创建一个bucket比如material-bucket把访问权限设置为private然后生成一对AccessKey和SecretKey。注意权限最小化原则这个Key只给系统用别暴露到前端。SpringBoot侧的整合靠minio-java依赖。pom.xml里加dependency groupIdio.minio/groupId artifactIdminio/artifactId version8.5.7/version /dependency配置项放在application.ymlminio: endpoint: http://127.0.0.1:9000 access-key: your-access-key secret-key: your-secret-key bucket-name: material-bucket file-url-expire-seconds: 300然后写一个配置类注入MinioClient以及一个MinioService工具类核心方法四个上传、获取下载地址、删除、判断对象是否存在。上传核心代码public String upload(InputStream inputStream, String fileName, String contentType) { String objectKey material/ System.currentTimeMillis() _ fileName; minioClient.putObject( PutObjectArgs.builder() .bucket(bucketName) .object(objectKey) .stream(inputStream, -1, 10 * 1024 * 1024) .contentType(contentType) .build() ); return objectKey; }objectKey的设计我建议带一层目录前缀比如material/2025/04/28/uuid_xxx.jpg后期做生命周期规则比如30天前的文件自动清理会很方便这算是个小经验。下载地址需要特别说明一下MinIO的私有bucket不能直接用/bucket/object拼URL访问必须先调用getPresignedObjectUrl生成一个带签名的临时URL。默认有效期我设300秒前端拿这个URL去加载图片或播放视频。如果是图片列表这种大量加载的场景建议后端把签名URL直接在列表查询时带出来避免前端再单独发请求换取。3.3 图片缩略图、视频转m3u8与截图处理文件存进去只是第一步多媒体素材系统绕不开的处理有三块图片缩略图、视频关键帧、视频切片转m3u8。这三个处理都建议在上传之后异步执行不要让用户等。图片缩略图可以直接用Thumbnailator上传主图之后异步生成缩略图存到同一个bucket的thumbnail/目录或者你愿意引入OSS的图片处理服务的话也行。实际经验是列表页不要直接返回原图URL否则图片一多带宽全被列表页吃了。缩略图统一宽度400px左右体积控制在几十KB列表页加载体验会提升一个量级。视频处理是重头戏需要借助服务器上的ffmpeg。项目里我写了一个VideoProcessService上传视频后在回调或异步任务中执行两条ffmpeg命令。生成关键帧截图ffmpeg -i input.mp4 -ss 00:00:02 -vframes 1 -vf scale400:-1 screenshot.jpg转m3u8切片ffmpeg -i input.mp4 -codec copy -bsf:v h264_mp4toannexb -hls_time 10 -hls_list_size 0 -hls_segment_filename segment_%05d.ts output.m3u8转m3u8的意义在于这是目前浏览器端实现免安装播放最稳的方案之一。原视频直接交给video标签播放经常出现大文件拖进度条卡顿、Safari不兼容某种编码格式的问题。转成m3u8后播放器可以通过HTTP拉取一个个小分片.ts文件实现边下边播、拖拽顺畅后端顺手把关键帧和切片文件一起传到MinIO。视频预览时前端拿到的就是一个xxx.m3u8的URL。这里有一个很关键但容易踩的坑m3u8文件是文本里面记录的是分片文件的相对路径或绝对URL。如果你用MinIO私有bucket生成签名URL给前端播放签名只签了m3u8文件本身里面的分片路径却是没有签名的播放器拉不了分片自然黑屏。这个问题折磨了我一个晚上最终方案是m3u8和它的分片文件放在同一个公开可读的bucket或者后端专门写一个代理接口统一给分片URL加签名。同学们自己实现的时候我建议先把这个标一记。4. Vue端多媒体展示从列表到预览的落地过程4.1 页面路由和组件怎么拆Vue端我从零搭的脚手架用的Vite配合Vue Router做路由管理。页面不多但每个页面内部的交互密度很高。路由大致规划/首页Dashboard展示各类素材数量统计、最近上传/material/list素材列表页核心页面支持筛选和分页/material/upload上传页支持拖拽和进度显示/material/detail/:id素材详情页展示预览面板、标签、下载信息组件层级上我把列表页拆成了四层。视图层放路由页面业务组件层是MaterialFilterBar筛选栏、MaterialTable表格或卡片列表、MaterialPagination分页器通用组件层是ImagePreviewDialog大图预览弹窗、VideoPlayerDialog视频播放弹窗、FileUrlCopyButton复制下载链接。这样拆的好处是将来如果要在详情页复用视频播放弹窗直接引组件就行不必复制粘贴代码。4.2 图片懒加载与缩略图配合素材列表少则几十条多则几百条如果一次性把全部图片URL都丢给浏览器加载页面大概率白屏很久。这里要用懒加载。最省事的做法是直接装一个懒加载指令插件比如vue-lazyload给img加上v-lazy指令就完事。但这里有个更精髓的配合后端在列表接口里已经返回了缩略图URL前端懒加载指令监听到图片进入可视区域后再去请求缩略图一屏大概就加载十几张滚动时再逐步加载速度和体验都好得多。如果不想引入插件也可以手写一个IntersectionObserver指令思路其实很简单观察img元素进入视口时把>npm install hls.js核心播放逻辑封装在VideoPlayerDialog.vue里大概逻辑如下import Hls from hls.js export default { props: { src: { type: String, required: true } }, mounted() { const video this.$refs.video if (Hls.isSupported()) { const hls new Hls() hls.loadSource(this.src) hls.attachMedia(video) hls.on(Hls.Events.MANIFEST_PARSED, () video.play()) } else if (video.canPlayType(application/vnd.apple.mpegurl)) { video.src this.src video.addEventListener(loadedmetadata, () video.play()) } } }这是我在多个项目里沿用至今的模板兼容度极高。有两点经验可以分享。第一Hls实例对象的destroy方法记得在组件beforeDestroy钩子里调用否则反复进入退出详情页会积攒多个播放实例浏览器占用CPU狂转第二如果你播放m3u8时遇到加载失败但文件确实能访问的情况多半是跨域问题MinIO的bucket需要允许你的前端域名做跨域请求Nginx里也要加对应的Access-Control-Allow-Origin头这个坑踩了才知道疼。4.4 大文件上传和进度反馈素材上传场景里视频文件动不动几个G普通的上传组件肯定扛不住。我用Element Plus的el-upload自定义了上传逻辑核心是打开http-request钩子覆盖默认行为用axios实例发出带onUploadProgress回调的请求function uploadFile(file) { const formData new FormData() formData.append(file, file) return request.post(/api/material/upload, formData, { timeout: 0, onUploadProgress: (event) { percent.value Math.round((event.loaded / event.total) * 100) } }) }几个容易被忽略的细节要在后端配合好。后端接收上传时spring.servlet.multipart.max-file-size和max-request-size必须调大默认的1MB连一张高清图都传不上去我一般配置如下spring: servlet: multipart: max-file-size: 5000MB max-request-size: 5000MB如果服务器内存有限上传大文件时要讨论是否走本地临时转发还是直接流式转发给MinIO。我在项目里用MinIO的PutObjectArgs配合InputStream实现流式直传尽量避免文件在应用服务器落盘。前端也要额外处理后端返回的素材ID可能要用于后续触发异步转码所以上传接口返回结构里要包含materialId、objectKey、thumbnailUrl这些字段方便前端跳转详情页。在预览层还有一个容易忽略的点PDF文件在浏览器里显示。热词里有人问vue image能显示pdf吗结论是可以的但手段不是img而是用iframe src/api/material/preview/xxx.pdf或者embed标签。如果要在列表里显示PDF封面后端可以调用工具把PDF首页转成图片作为缩略图。5. SpringBoot、MyBatis、MySQL联调阶段的高频问题清单5.1 MySQL连接报SSL与时区错误第一个跑项目就被问崩的往往是数据库连接。报错长这样Communications link failure The last packet sent successfully to the server was 0 milliseconds ago.另一个是高版本MySQL驱动经常出现的The server time zone value Öйú±ê׼ʱ¼ä is unrecognized...这两类问题根源都是连接串里的参数不对。MySQL 8.x驱动默认开启SSL校验而本地或内网环境通常没有配置SSL证书就会握手失败时区问题则是驱动拿不到系统时区报错信息甚至会出现乱码。解决办法就是在JDBC连接串上明确指定这两个参数jdbc:mysql://127.0.0.1:3306/material_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrueallowPublicKeyRetrievaltrue这个参数也值得一提MySQL 8.x使用caching_sha2_password认证时如果连接需要公钥检索不开启这个会报错。这三个参数组合在一起基本解决了所有明明账号密码对就是连不上的鬼问题。5.2 SpringBoot与MyBatis版本不兼容热词里有人搜springboot版本太高我太理解这种痛了。SpringBoot 3.x是目前的主流但它使用Jakarta EE规范很多老版本的MyBatis starter、pagehelper-spring-boot-starter是基于javax命名空间的直接引用会报ServletException或者ClassNotFoundException: jakarta.servlet。如果你在用SpringBoot 3.x请务必将依赖版本对应到适配版组件推荐版本Spring Boot3.2.xmybatis-spring-boot-starter3.0.3pagehelper-spring-boot-starter2.1.0minio-java8.5.xmysql-connector-j8.3.x如果你拿到的源码是基于SpringBoot 2.x的且依赖还是javax命名空间又跑在JDK 8/11上那别硬上3.x。我的建议很简单先识别项目里用的是javax还是jakarta再决定走的版本路线。版本不一致导致的AbstractMethodError、NoClassDefFoundError这类诡异报错十有八九都是这里出了问题。5.3 Mapper扫描不到与XML不生效项目跑起来后一调接口就报Invalid bound statement (not found)这几乎是MyBatis项目最高频的报错。看似是找不到SQL语句实际原因有这么几种直接对照排查第一Mapper接口和XML文件的namespace不匹配。XML里的namespace必须是Mapper接口的全限定名一个字符都不能错。这是我检查的第一顺位。mapper namespacecom.example.material.mapper.MaterialMapper第二SpringBoot没有扫描到Mapper接口。Application类上要加MapperScan(com.example.material.mapper)或者在每个Mapper接口上单独加Mapper注解。我偏好MapperScan一劳永逸。第三XML文件没在classpath里。这个在上面2.3已经讲过构建时XML没有被打包进target/classes运行时的classpath里自然找不到。检查方法很简单看target/classes/mapper目录是否存在XML。第四mapper-locations路径配置错了。确保classpath:mapper/*.xml和你实际存放XML的路径一致。很多人把XML放在src/main/java/com/xxx/mapper下那配置文件就要指向这个子目录或者直接按我的经验把XML放到src/main/resources/mapper。如果以上四点都排查完还不行最后用mvn clean彻底清理一次再重新构建Maven的增量编译偶尔会把旧的class和新的XML弄得不一致这种情况我遇到过两三次。5.4 前端跨域、文件读取404、中文乱码前后端分离后跨域问题几乎必现。Vue开发环境通过Vite的proxy代理解决最干净生产环境则让Nginx把/api前缀的请求转发到后端服务同时后端起一个全局CORS配置兜底Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(Registry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowCredentials(true) .maxAge(3600); } }文件读取404的问题根源往往不是路径拼错而是你访问的URL是未签名或未在静态资源映射范围内的MinIO私有对象。如果你的素材文件走本地存储而不是MinIO记得把/files/**映射到上传目录构建一个虚拟路径访问的配置类。生产环境强烈建议让Nginx直接映射一个磁盘目录存放本地上传的文件让后端彻底释放磁盘IO。中文乱码问题通常在两个层面出现数据库连接串里characterEncodingutf8没配置以及响应返回的JSON没有指定application/json;charsetUTF-8。前者在5.1的连接串里带上了就行后者要么检查WebMvcConfigurer里有没有配置消息转换器要么在Controller上显式给RequestMapping(produces application/json;charsetUTF-8)图省事就全局配置一下。联调期要善用浏览器开发者工具的Network面板后端报错不要只看前端控制台要翻后端日志。日志级别调到DEBUGMyBatis的SQL和执行参数就能打出来排查多条件查询的SQL拼接正不正确比瞎猜快十倍。写在最后的小提醒前前后后我做过几个素材类的系统从最简单的本地上传版到加入对象存储、视频转码、标签检索的完整版中间反复推翻过不少设计。最核心的一个体会是素材管理系统的难点从来不在CRUD本身而在文件生命周期、预览兼容性和查询性能这三件事。文件要管它的存储、缩略图、转码、签名下载预览要兼顾图片、音视频、文档的格式差异查询要在几百万条数据面前保证筛选不慢。这三个问题想清楚系统就稳了一大半。最后分享两个实战中的小技巧。一个是上传视频后一定要有异步任务接管处理不要让用户干等转码完成前端显示处理中状态就够了等处理完成再通过轮询或WebSocket刷新素材详情。另一个是在做素材清理功能时先删存储对象再删数据库记录顺序反了会导致数据库里还有记录但文件已经没了预览全部裂图。小事不小踩过才知道。希望这篇能把那些我在代码和日志里挣扎过的经验传给你让你的系统从第一行代码起就走在正确的路上。
做内容管理的这些年我发现一个很普遍的痛点图片、视频、PPT、音频散落在各人电脑、聊天记录和共享盘里要用的时候找不到找到了又是旧版。后来我花时间基于SpringBootVueMyBatisMySQL搭了一套web多媒体素材管理系统把上传、分类、标签检索、预览、下载这些环节串成一条线中间踩了不少坑也沉淀了不少经验。这篇文章不打算写成标准的需求文档而是把整个系统的落地过程拆开讲——数据库表怎么设计、文件到底存哪里、视频预览怎么做到浏览器免插件播放、联调阶段那些报错怎么排查。无论你是准备拿这个方向做课程设计还是要在团队内部搭一套素材库看完这篇再动手能省很多弯路。1. 这套系统的定位与整体技术架构1.1 多媒体素材管理系统到底在解决什么问题先搞清楚一个前提市面上做素材管理的系统很多但大多数要么太重要么太轻。重的像数字资产管理平台动不动就聊工作流和权限矩阵小团队根本用不起来轻的又只是个上传下载工具连个分类和按类型筛选都做不到。我做的这套定位很明确面向中小团队和个人开发者的轻量级素材中心核心解决三件事——集中存储、快速检索、在线预览。具体功能包括素材上传图片/视频/音频/文档、自定义分类、标签打标、多条件组合搜索类型、分类、上传时间、关键词、列表预览、在线视频播放、图片缩略图展示、下载与统计。没有任何花哨的功能但每一个都是日常用得上的。这个定位决定了后续所有技术选型——不追求复杂追求跑起来稳、改起来快。从部署角度看这套系统也足够轻。SpringBoot打一个jar包Vue打包成静态文件丢给NginxMySQL存元数据MinIO存文件本体四样东西就能跑起一整套环境。对于想要做毕业设计、个人作品集或者课题演示的同学这个体量刚好合适。1.2 为什么是SpringBootVueMyBatisMySQL这套组合技术选型这件事我见过太多人在第一步就被带偏。有人上来就要上微服务有人非要用NoSQL结果一个素材管理系统搞得比电商平台还复杂。我应该明确一点这套组合不是因为新潮而是因为匹配。SpringBoot解决的是后端开发效率。内置Tomcat、自动装配、简化配置让团队能把精力放在业务逻辑上。相比传统的SSM要写一堆XML配置SpringBoot最大的价值是默认值足够合理特殊项才需要覆盖。对中小项目来说开发速度确实快得多。Vue解决的是前端交互复杂度。素材管理天然有大量列表、筛选器、弹窗、上传组件Vue的组件化在控制这类复杂度上优势明显。而且Vue生态里现成的UI库、懒加载插件、播放器封装一抓一大把不用从零造轮子。MyBatis在ORM里不是执行效率最高的但一定是最适合这种查询条件多变场景的。素材搜索往往是多个动态条件排列组合用MyBatis的where、if、choose动态SQL可以干净地拼接SQL。这里说明一下如果你把JPA的Specification拿出来对比会发现它也能做但MyBatis对一票后端开发者来说更直觉——看得见SQL心里踏实。MySQL就更不用说了免费、普及率高、团队里随手拉一个人都能上手。素材系统的元数据量级根本到不了MySQL的瓶颈关系型数据库在这种场景下的优势——事务、索引、联表查询——反而能发挥得最充分。再加上MinIO做对象存储后面专门讲文件流和数据流分离整套架构非常清爽。1.3 前后端请求链路与目录结构先看一张执行到内存里的请求流程浏览器访问Vue打包后的页面用户在素材列表页点分类、输入关键词、触发搜索前端组装Query参数调用后端/api/material/list接口SpringBoot的Controller接收参数后交给ServiceService调用MapperMyBatis通过XML里的动态SQL查MySQL返回分页结果前端拿到数据渲染列表缩略图从MinIO或本地映射路径加载点击视频预览时播放器拉取多媒体流地址。整个链路是标准的前后端分离结构前端Vue Vue Router Element Plus或同类UI库打包后部署在Nginx后端SpringBoot按Controller/Service/Mapper三层组织数据库MySQL 8.x存素材元数据存储MinIO存图片、视频、音频、文档原始文件目录上后端按功能分包controller放接口层service放业务逻辑mapper放MyBatis的Mapper接口model放实体和DTOconfig放跨域、MinIO、MyBatis等配置类mapper/xml放动态SQL映射文件。前端按页面划分views/material放素材列表和上传页components放预览弹窗、卡片组件等公用组件router放路由配置api放axios请求封装。这个结构在新增功能时不需要复杂的思考跟着已有的模块写就行。说句实在话对素材管理这种CRUD占比很高的系统结构清晰比什么都重要。2. 数据库设计与MyBatis层的关键细节2.1 素材表结构如何设计才抗造素材管理系统的核心表是material_info我见过很多糟糕的表设计上来就存Base64图片进数据库或者把文件路径写成C:\user\xxx\aa.jpg这种绝对路径后期全是泪。这里分享一下我最终定下来的表结构CREATE TABLE material_info ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT 主键, material_no VARCHAR(32) DEFAULT NULL COMMENT 素材编号, title VARCHAR(255) NOT NULL COMMENT 素材标题, material_type TINYINT NOT NULL COMMENT 类型1图片 2视频 3音频 4文档, suffix VARCHAR(16) DEFAULT NULL COMMENT 文件后缀, file_size BIGINT DEFAULT 0 COMMENT 文件大小字节, storage_type TINYINT DEFAULT 1 COMMENT 存储位置1本地 2MinIO, bucket_name VARCHAR(64) DEFAULT NULL COMMENT MinIO桶名, object_key VARCHAR(255) DEFAULT NULL COMMENT MinIO对象键, file_url VARCHAR(512) DEFAULT NULL COMMENT 完整访问地址, thumbnail_url VARCHAR(512) DEFAULT NULL COMMENT 缩略图地址, category_id BIGINT DEFAULT NULL COMMENT 分类ID, tags VARCHAR(512) DEFAULT NULL COMMENT 逗号分隔标签, duration INT DEFAULT 0 COMMENT 音视频时长秒, width INT DEFAULT 0 COMMENT 图片宽, height INT DEFAULT 0 COMMENT 图片高, status TINYINT DEFAULT 1 COMMENT 状态0禁用 1启用, download_count INT DEFAULT 0 COMMENT 下载次数, create_by VARCHAR(64) DEFAULT NULL COMMENT 上传人, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 上传时间, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新时间, PRIMARY KEY (id), KEY idx_type_time (material_type, create_time), KEY idx_category_time (category_id, create_time) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT素材信息表;几个关键设计点我单独说明file_size用BIGINT存字节数不要用varchar存2.5MB这种字符串业务层展示时再转换否则没法做排序和统计。material_type用TINYINT数字枚举而不是字符串后端用常量或枚举类做映射。前端界面展示的是由后端转换后的中文名称数据库里只存数字查询更快也更省空间。文件地址同时保留object_key和file_url。object_key用于MinIO的API操作file_url用于直接返回给前端展示。两者别混了。标签不用单独建关联表直接逗号分隔存字符串。理由很简单标签查询一般就是LIKE匹配量级不大在素材系统里完全够用。如果你打算以后做复杂的标签聚合统计再考虑拆表。update_time务必用ON UPDATE CURRENT_TIMESTAMP自动维护别让代码手动更新省很多事。分类表就简单多了id、parent_id、category_name、sort_order。如果要做二级分类就加层级不做就把parent_id置空。这里不建议做无限极递归分类浏览型功能做两级就够层级太深反而让前端面包屑和筛选器变复杂。2.2 多条件搜索的分页SQL与动态查询素材列表页的核心接口是分页查询而且必须是多条件可选条件的组合查询。参数大致有当前页、每页条数、素材类型、分类ID、标签关键词、标题关键词、时间范围。用MyBatis写这种查询动态SQL的优势就体现出来了。核心SQL长这样select idselectPageList resultMapMaterialResultMap SELECT * FROM material_info where if testquery.materialType ! null AND material_type #{query.materialType} /if if testquery.categoryId ! null AND category_id #{query.categoryId} /if if testquery.keyword ! null and query.keyword ! AND (title LIKE CONCAT(%, #{query.keyword}, %) OR tags LIKE CONCAT(%, #{query.keyword}, %)) /if if testquery.startTime ! null AND create_time gt; #{query.startTime} /if if testquery.endTime ! null AND create_time lt; #{query.endTime} /if /where ORDER BY create_time DESC /select细节上强调两点。第一where标签会自动去掉第一个多余的AND这个特性是MyBatis专门为动态条件设计的能避免WHERE前面多个AND这种低级报错。第二时间比较用gt;和lt;因为XML中不能直接写这是很多人第一次写动态SQL就报错的地方。分页组件我用的PageHelper。用法很简单查询前执行一行PageHelper.startPage(pageNum, pageSize)紧接着的第一次MyBatis查询就会自动拼接LIMIT并且返回PageInfo对象里带total、pages、list这些现成数据。有一点要注意PageHelper.startPage后只能接一条查询语句如果中间有其它查询分页会串掉线上环境很容易栽在这。另外性能上有个优化点可以提一下素材列表页的统计数total和列表数据查询PageHelper默认会生成两条SQL——count查询和分页查询。如果你的数据量到了几十万条count查询的耗时就会上来可以考虑把count的SQL单独优化或者干脆用缓存记录各分类下的素材总数。对中小系统来说先记着有这个事不必过度设计。2.3 MyBatis配置里容易踩的坑MyBatis在SpringBoot里跑得多了有几个配置点我几乎每次都要检查一遍提出来给各位打个预防针。数据库字段命名建议全部用下划线风格如create_time实体类用驼峰风格如createTime然后在application.yml里配上mybatis: configuration: map-underscore-to-camel-case: true mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.material.entity不要小看这一行map-underscore-to-camel-case。我第一次做项目的时候没配这个结果实体的createTime映射不到create_time查出来全是null排查了半天才发现是这么个小配置。一旦配好MyBatis会自动做字段名和属性名的驼峰映射。第二个坑是XML映射文件没被打包进target/classes。SpringBoot的Maven构建默认不会把src/main/java下的XML拷到classes目录所以很多人写的mapper/*.xml一运行就报Invalid bound statement (not found)。解决办法就是在pom.xml里加一段资源声明resources resource directorysrc/main/java/directory includes include**/*.xml/include /includes /resource /resources或者更规范一点把XML统一放到src/main/resources/mapper目录下这样根本不用额外配置。我现在习惯是XML作为一个mapper/资源目录存放规整而且省心。第三个要聊的是MyBatis缓存。MyBatis默认开启一级缓存SqlSession级别和可选的二级缓存namespace级别。听起来很美但在素材管理这种多表关联实时更新的场景里缓存反而容易造成脏数据。比如一个素材更新了分类但统计分类数的查询缓存还没失效你看到的数据就是旧的。我的建议是系统里默认关闭二级缓存把缓存交给Redis来做可控性更强。你可以在application.yml里加上mybatis: configuration: cache-enabled: false不搞全局缓存查询条件复杂时直接查库配合MySQL的索引和分页性能完全够用。3. 媒体文件存储与处理从本地上传到MinIO3.1 为什么素材文件不能一股脑塞进服务器本地磁盘最初版本我把文件存到服务器本地的/data/uploads目录结果一段时间之后问题接踵而至磁盘告警、没有副本的单点风险、服务器迁移时要把几Gb甚至几Tb的文件拷来拷去痛苦得很。数据库里存的是元数据文件本体应该交给专门的对象存储服务。在方案选型时详细对比了MinIO、阿里云OSS、腾讯云COS。OSS和COS胜在托管稳定但需要联网、按量付费MinIO的优点是开源、私有化部署、S3协议兼容而且SDK用起来和云厂商的对象存储几乎一致。对上素材管理系统这种内网自用的场景MinIO天然就是最优解。如果你的服务跑在公网云服务器上同样的代码把MinIO的Endpoint换成OSS的几乎没有学习成本。热词搜索里也反复出现minio加入到springboot和springboot整合说明这已经是素材类系统的标准做法了这篇文章就干脆把这套方案完全铺开。3.2 MinIO接入SpringBoot的完整过程首先是MinIO服务的部署。最简单的方式用Docker拉一个容器docker run -d \ --name minio \ -p 9000:9000 \ -p 9001:9001 \ -e MINIO_ROOT_USERminioadmin \ -e MINIO_ROOT_PASSWORDminioadmin123 \ quay.io/minio/minio server /data --console-address :90019000是S3 API端口9001是Web控制台端口。部署完成后访问控制台创建一个bucket比如material-bucket把访问权限设置为private然后生成一对AccessKey和SecretKey。注意权限最小化原则这个Key只给系统用别暴露到前端。SpringBoot侧的整合靠minio-java依赖。pom.xml里加dependency groupIdio.minio/groupId artifactIdminio/artifactId version8.5.7/version /dependency配置项放在application.ymlminio: endpoint: http://127.0.0.1:9000 access-key: your-access-key secret-key: your-secret-key bucket-name: material-bucket file-url-expire-seconds: 300然后写一个配置类注入MinioClient以及一个MinioService工具类核心方法四个上传、获取下载地址、删除、判断对象是否存在。上传核心代码public String upload(InputStream inputStream, String fileName, String contentType) { String objectKey material/ System.currentTimeMillis() _ fileName; minioClient.putObject( PutObjectArgs.builder() .bucket(bucketName) .object(objectKey) .stream(inputStream, -1, 10 * 1024 * 1024) .contentType(contentType) .build() ); return objectKey; }objectKey的设计我建议带一层目录前缀比如material/2025/04/28/uuid_xxx.jpg后期做生命周期规则比如30天前的文件自动清理会很方便这算是个小经验。下载地址需要特别说明一下MinIO的私有bucket不能直接用/bucket/object拼URL访问必须先调用getPresignedObjectUrl生成一个带签名的临时URL。默认有效期我设300秒前端拿这个URL去加载图片或播放视频。如果是图片列表这种大量加载的场景建议后端把签名URL直接在列表查询时带出来避免前端再单独发请求换取。3.3 图片缩略图、视频转m3u8与截图处理文件存进去只是第一步多媒体素材系统绕不开的处理有三块图片缩略图、视频关键帧、视频切片转m3u8。这三个处理都建议在上传之后异步执行不要让用户等。图片缩略图可以直接用Thumbnailator上传主图之后异步生成缩略图存到同一个bucket的thumbnail/目录或者你愿意引入OSS的图片处理服务的话也行。实际经验是列表页不要直接返回原图URL否则图片一多带宽全被列表页吃了。缩略图统一宽度400px左右体积控制在几十KB列表页加载体验会提升一个量级。视频处理是重头戏需要借助服务器上的ffmpeg。项目里我写了一个VideoProcessService上传视频后在回调或异步任务中执行两条ffmpeg命令。生成关键帧截图ffmpeg -i input.mp4 -ss 00:00:02 -vframes 1 -vf scale400:-1 screenshot.jpg转m3u8切片ffmpeg -i input.mp4 -codec copy -bsf:v h264_mp4toannexb -hls_time 10 -hls_list_size 0 -hls_segment_filename segment_%05d.ts output.m3u8转m3u8的意义在于这是目前浏览器端实现免安装播放最稳的方案之一。原视频直接交给video标签播放经常出现大文件拖进度条卡顿、Safari不兼容某种编码格式的问题。转成m3u8后播放器可以通过HTTP拉取一个个小分片.ts文件实现边下边播、拖拽顺畅后端顺手把关键帧和切片文件一起传到MinIO。视频预览时前端拿到的就是一个xxx.m3u8的URL。这里有一个很关键但容易踩的坑m3u8文件是文本里面记录的是分片文件的相对路径或绝对URL。如果你用MinIO私有bucket生成签名URL给前端播放签名只签了m3u8文件本身里面的分片路径却是没有签名的播放器拉不了分片自然黑屏。这个问题折磨了我一个晚上最终方案是m3u8和它的分片文件放在同一个公开可读的bucket或者后端专门写一个代理接口统一给分片URL加签名。同学们自己实现的时候我建议先把这个标一记。4. Vue端多媒体展示从列表到预览的落地过程4.1 页面路由和组件怎么拆Vue端我从零搭的脚手架用的Vite配合Vue Router做路由管理。页面不多但每个页面内部的交互密度很高。路由大致规划/首页Dashboard展示各类素材数量统计、最近上传/material/list素材列表页核心页面支持筛选和分页/material/upload上传页支持拖拽和进度显示/material/detail/:id素材详情页展示预览面板、标签、下载信息组件层级上我把列表页拆成了四层。视图层放路由页面业务组件层是MaterialFilterBar筛选栏、MaterialTable表格或卡片列表、MaterialPagination分页器通用组件层是ImagePreviewDialog大图预览弹窗、VideoPlayerDialog视频播放弹窗、FileUrlCopyButton复制下载链接。这样拆的好处是将来如果要在详情页复用视频播放弹窗直接引组件就行不必复制粘贴代码。4.2 图片懒加载与缩略图配合素材列表少则几十条多则几百条如果一次性把全部图片URL都丢给浏览器加载页面大概率白屏很久。这里要用懒加载。最省事的做法是直接装一个懒加载指令插件比如vue-lazyload给img加上v-lazy指令就完事。但这里有个更精髓的配合后端在列表接口里已经返回了缩略图URL前端懒加载指令监听到图片进入可视区域后再去请求缩略图一屏大概就加载十几张滚动时再逐步加载速度和体验都好得多。如果不想引入插件也可以手写一个IntersectionObserver指令思路其实很简单观察img元素进入视口时把>npm install hls.js核心播放逻辑封装在VideoPlayerDialog.vue里大概逻辑如下import Hls from hls.js export default { props: { src: { type: String, required: true } }, mounted() { const video this.$refs.video if (Hls.isSupported()) { const hls new Hls() hls.loadSource(this.src) hls.attachMedia(video) hls.on(Hls.Events.MANIFEST_PARSED, () video.play()) } else if (video.canPlayType(application/vnd.apple.mpegurl)) { video.src this.src video.addEventListener(loadedmetadata, () video.play()) } } }这是我在多个项目里沿用至今的模板兼容度极高。有两点经验可以分享。第一Hls实例对象的destroy方法记得在组件beforeDestroy钩子里调用否则反复进入退出详情页会积攒多个播放实例浏览器占用CPU狂转第二如果你播放m3u8时遇到加载失败但文件确实能访问的情况多半是跨域问题MinIO的bucket需要允许你的前端域名做跨域请求Nginx里也要加对应的Access-Control-Allow-Origin头这个坑踩了才知道疼。4.4 大文件上传和进度反馈素材上传场景里视频文件动不动几个G普通的上传组件肯定扛不住。我用Element Plus的el-upload自定义了上传逻辑核心是打开http-request钩子覆盖默认行为用axios实例发出带onUploadProgress回调的请求function uploadFile(file) { const formData new FormData() formData.append(file, file) return request.post(/api/material/upload, formData, { timeout: 0, onUploadProgress: (event) { percent.value Math.round((event.loaded / event.total) * 100) } }) }几个容易被忽略的细节要在后端配合好。后端接收上传时spring.servlet.multipart.max-file-size和max-request-size必须调大默认的1MB连一张高清图都传不上去我一般配置如下spring: servlet: multipart: max-file-size: 5000MB max-request-size: 5000MB如果服务器内存有限上传大文件时要讨论是否走本地临时转发还是直接流式转发给MinIO。我在项目里用MinIO的PutObjectArgs配合InputStream实现流式直传尽量避免文件在应用服务器落盘。前端也要额外处理后端返回的素材ID可能要用于后续触发异步转码所以上传接口返回结构里要包含materialId、objectKey、thumbnailUrl这些字段方便前端跳转详情页。在预览层还有一个容易忽略的点PDF文件在浏览器里显示。热词里有人问vue image能显示pdf吗结论是可以的但手段不是img而是用iframe src/api/material/preview/xxx.pdf或者embed标签。如果要在列表里显示PDF封面后端可以调用工具把PDF首页转成图片作为缩略图。5. SpringBoot、MyBatis、MySQL联调阶段的高频问题清单5.1 MySQL连接报SSL与时区错误第一个跑项目就被问崩的往往是数据库连接。报错长这样Communications link failure The last packet sent successfully to the server was 0 milliseconds ago.另一个是高版本MySQL驱动经常出现的The server time zone value Öйú±ê׼ʱ¼ä is unrecognized...这两类问题根源都是连接串里的参数不对。MySQL 8.x驱动默认开启SSL校验而本地或内网环境通常没有配置SSL证书就会握手失败时区问题则是驱动拿不到系统时区报错信息甚至会出现乱码。解决办法就是在JDBC连接串上明确指定这两个参数jdbc:mysql://127.0.0.1:3306/material_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrueallowPublicKeyRetrievaltrue这个参数也值得一提MySQL 8.x使用caching_sha2_password认证时如果连接需要公钥检索不开启这个会报错。这三个参数组合在一起基本解决了所有明明账号密码对就是连不上的鬼问题。5.2 SpringBoot与MyBatis版本不兼容热词里有人搜springboot版本太高我太理解这种痛了。SpringBoot 3.x是目前的主流但它使用Jakarta EE规范很多老版本的MyBatis starter、pagehelper-spring-boot-starter是基于javax命名空间的直接引用会报ServletException或者ClassNotFoundException: jakarta.servlet。如果你在用SpringBoot 3.x请务必将依赖版本对应到适配版组件推荐版本Spring Boot3.2.xmybatis-spring-boot-starter3.0.3pagehelper-spring-boot-starter2.1.0minio-java8.5.xmysql-connector-j8.3.x如果你拿到的源码是基于SpringBoot 2.x的且依赖还是javax命名空间又跑在JDK 8/11上那别硬上3.x。我的建议很简单先识别项目里用的是javax还是jakarta再决定走的版本路线。版本不一致导致的AbstractMethodError、NoClassDefFoundError这类诡异报错十有八九都是这里出了问题。5.3 Mapper扫描不到与XML不生效项目跑起来后一调接口就报Invalid bound statement (not found)这几乎是MyBatis项目最高频的报错。看似是找不到SQL语句实际原因有这么几种直接对照排查第一Mapper接口和XML文件的namespace不匹配。XML里的namespace必须是Mapper接口的全限定名一个字符都不能错。这是我检查的第一顺位。mapper namespacecom.example.material.mapper.MaterialMapper第二SpringBoot没有扫描到Mapper接口。Application类上要加MapperScan(com.example.material.mapper)或者在每个Mapper接口上单独加Mapper注解。我偏好MapperScan一劳永逸。第三XML文件没在classpath里。这个在上面2.3已经讲过构建时XML没有被打包进target/classes运行时的classpath里自然找不到。检查方法很简单看target/classes/mapper目录是否存在XML。第四mapper-locations路径配置错了。确保classpath:mapper/*.xml和你实际存放XML的路径一致。很多人把XML放在src/main/java/com/xxx/mapper下那配置文件就要指向这个子目录或者直接按我的经验把XML放到src/main/resources/mapper。如果以上四点都排查完还不行最后用mvn clean彻底清理一次再重新构建Maven的增量编译偶尔会把旧的class和新的XML弄得不一致这种情况我遇到过两三次。5.4 前端跨域、文件读取404、中文乱码前后端分离后跨域问题几乎必现。Vue开发环境通过Vite的proxy代理解决最干净生产环境则让Nginx把/api前缀的请求转发到后端服务同时后端起一个全局CORS配置兜底Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(Registry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowCredentials(true) .maxAge(3600); } }文件读取404的问题根源往往不是路径拼错而是你访问的URL是未签名或未在静态资源映射范围内的MinIO私有对象。如果你的素材文件走本地存储而不是MinIO记得把/files/**映射到上传目录构建一个虚拟路径访问的配置类。生产环境强烈建议让Nginx直接映射一个磁盘目录存放本地上传的文件让后端彻底释放磁盘IO。中文乱码问题通常在两个层面出现数据库连接串里characterEncodingutf8没配置以及响应返回的JSON没有指定application/json;charsetUTF-8。前者在5.1的连接串里带上了就行后者要么检查WebMvcConfigurer里有没有配置消息转换器要么在Controller上显式给RequestMapping(produces application/json;charsetUTF-8)图省事就全局配置一下。联调期要善用浏览器开发者工具的Network面板后端报错不要只看前端控制台要翻后端日志。日志级别调到DEBUGMyBatis的SQL和执行参数就能打出来排查多条件查询的SQL拼接正不正确比瞎猜快十倍。写在最后的小提醒前前后后我做过几个素材类的系统从最简单的本地上传版到加入对象存储、视频转码、标签检索的完整版中间反复推翻过不少设计。最核心的一个体会是素材管理系统的难点从来不在CRUD本身而在文件生命周期、预览兼容性和查询性能这三件事。文件要管它的存储、缩略图、转码、签名下载预览要兼顾图片、音视频、文档的格式差异查询要在几百万条数据面前保证筛选不慢。这三个问题想清楚系统就稳了一大半。最后分享两个实战中的小技巧。一个是上传视频后一定要有异步任务接管处理不要让用户干等转码完成前端显示处理中状态就够了等处理完成再通过轮询或WebSocket刷新素材详情。另一个是在做素材清理功能时先删存储对象再删数据库记录顺序反了会导致数据库里还有记录但文件已经没了预览全部裂图。小事不小踩过才知道。希望这篇能把那些我在代码和日志里挣扎过的经验传给你让你的系统从第一行代码起就走在正确的路上。
