企业官网建设流程全解析

做这个 Java Web 多媒体素材管理系统，前后花了大半个月，技术栈是 SpringBoot2 + Vue3 + MyBatis-Plus + MySQL8.0。说实话，一开始我以为这就是个普通的 CRUD 管理系统，真正动手后发现，素材文件本身才是最难搞的——图片、视频、音频、文档的体积不一样，预览方式不一样，存储策略也不一样，接口设计和数据库都不能照搬传统管理系统的思路。这篇就把整个系统的设计思路、数据库怎么拆、后端核心接口怎么写、前端页面怎么组织，以及部署联调时踩过的几个典型坑，一次说清楚。适合正在做类似管理系统、准备写毕业设计，或者想系统了解前后端分离项目落地过程的同学参考。

1. 项目整体设计与技术选型思路

1.1 为什么选 SpringBoot2 + Vue3，而不是其他组合

先说 SpringBoot2。这套系统的所有后端能力——RESTful 接口、文件上传、业务处理、数据库读写——都由它承担。选它不是因为名字响，而是自动配置机制确实能省掉大量重复劳动。正常一个 Web 项目要处理依赖注入、参数校验、内置容器、数据源配置，如果用传统 SSM 那套，得自己拼装 Spring 和 Mybatis 的各种配置类；SpringBoot 直接把这一步集约化，pom.xml 里加依赖就能跑起来，开发重心可以完全放在业务代码上。

前端选 Vue3，核心原因有两个。第一，Composition API 让组件逻辑更容易复用，素材列表、上传表单、预览弹窗这些功能都能抽成独立的 hooks，不会像 Options API 那样把所有逻辑堆在 data、methods 和 computed 里，一个组件动辄上千行，后期改需求非常头疼。第二，Vue3 的响应式系统基于 Proxy 重写，对数组和对象属性的增删处理比 Vue2 的 Object.defineProperty 更彻底，比如动态给素材列表项添加一个封面字段，在 Vue2 里要调this.$set，在 Vue3 里直接赋值就生效，少了很多隐形的坑。

1.2 MyBatis-Plus 在数据访问层扮演的角色

MyBatis-Plus 不是替代 MyBatis，而是把 MyBatis 里最琐碎的那部分捡走。单表 CRUD 在传统 MyBatis 里要写 Mapper 接口、XML 文件、SQL 语句、ResultMap 映射，一套流程下来，光模板代码就能写一上午。MyBatis-Plus 内置了通用 Mapper，基础方法继承BaseMapper<T>直接就能用，业务代码只需要关注复杂查询。比如这个系统里素材的列表查询、分类统计、标签筛选，都属于典型的多条件组合查询，用它的LambdaQueryWrapper可以在 Java 代码里动态拼接条件，可读性和维护性比在 XML 里写一长串动态 SQL 好得多。

有一个容易疏忽的地方必须提醒：MyBatis-Plus 的分页插件PaginationInnerInterceptor需要手动注册到 MybatisPlusInterceptor 里。很多人以为引入依赖分页就能用，结果查出来的永远是全表数据，这就是因为没注册拦截器。后面实战部分我会把完整配置贴出来。

1.3 MySQL8.0 带来的几个实际便利

MySQL8.0 在这套系统里有用到几个新特性。字符集默认是 utf8mb4，直接解决 emoji 表情和生僻字存储乱码的问题。素材文件的中文标题、备注信息经常混着特殊符号，老版本 MySQL 要单独改库、改表才能支持，8.0 不用操心。MySQL8.0 对窗口函数的支持也完善了，做素材使用统计、分类上传量排行这类报表非常顺手，一条 SQL 就能搞定，不用在 Java 层做多次查询再手动聚合。另外 JSON 类型的函数更稳定，我把素材的扩展属性（视频时长、图片宽高、文档页数）直接存成 JSON 字段，查询和更新都用 JSON 函数完成，Java 层不用做额外的序列化转换，省了不少代码。

2. 系统核心功能拆解与数据库设计

2.1 素材管理核心业务模型：用户、分类、标签、素材信息

多媒体素材管理系统的核心业务模型可以拆成四个实体：用户、分类、标签、素材信息。用户负责登录和权限控制，管理员可以上传、编辑、删除素材，普通用户只能浏览和下载。分类是树形结构，比如图片下面还可以分“摄影”、“插画”、“截图”，层级不能太深，实际系统里控制在三级以内就行，不然前端树形组件渲染和查询递归都会变复杂。标签是扁平结构，一个素材可以挂多个标签，便于跨分类检索。

素材信息表是核心中的核心，不仅要存文件名和路径，还要存素材类型（图片、视频、音频、文档）、大小、格式、上传人、下载次数、状态。文件本身存磁盘或对象存储，数据库存的是访问路径和元数据。另外还需要预留关联表——素材与标签是多对多关系，要拆一张关联表；用户上传记录要单独留一份日志表，方便做报表统计。

2.2 关键表结构设计与字段考量

素材信息表material_info是设计重点，我列几个关键字段：

分类表material_category的要点在 pid 字段，父级分类 ID，0 表示一级分类。标签表material_tag和关联表material_tag_rel是一对多的标准拆法，关联表只存素材ID和标签ID，查询时用JOIN或者IN都能高效取出标签列表。

设计时有一个经验：不要把文件字节内容存进数据库，除非是几 KB 的小图标。视频动辄几百 MB，塞进 MySQL 的 BLOB 字段性能会非常难看。正确做法是文件走本地磁盘或 OSS，数据库只存路径，访问时通过静态资源映射或预签名 URL 对外暴露。这个系统用的是本地磁盘 + Nginx 映射方式，后续扩展成 MinIO 也容易。

3. 后端落地：从接口到业务的完整闭环

3.1 SpringBoot2 工程初始化与目录规划

工程目录我建议按业务模块分包，而不是按技术层分包。很多新手喜欢建controller、service、dao三个包把所有类扔进去，项目小的时候还好，功能一多就乱。这个系统我用的结构是：

src/main/java/com/example/media/ ├── common/ // 通用返回对象、异常处理、工具类 ├── config/ // MyBatis-Plus分页配置、CORS配置、静态资源映射 ├── controller/ // 控制层，只做参数接收和结果封装 ├── module/ │ ├── material/ // 素材模块：控制器、服务、Mapper按模块聚合 │ ├── category/ // 分类模块 │ ├── tag/ // 标签模块 │ └── system/ // 用户登录、日志模块 └── util/ // 文件处理、日期处理等工具

module目录下每个模块内部再分controller、service、mapper、entity、dto，这样改一个功能只需要进对应的模块目录，不需要在四个大包里来回跳。pojo 里的 Entity 对应数据库表字段，DTO 对应接口入参和出参，两者分离，避免直接用 Entity 接前端参数造成的字段暴露问题。

pom.xml 里核心依赖就五个：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.3.1</version> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency>

MySQL 8.0 的驱动类要用com.mysql.cj.jdbc.Driver，连接串建议带参数。serverTimezone=Asia/Shanghai不写的话，日期字段读写差 8 小时；useUnicode=true&characterEncoding=utf8不写的话，中文可能出现乱码。

3.2 基于 MyBatis-Plus 实现素材分页查询

素材列表是系统使用频率最高的接口，支持按关键字、分类、标签、类型、时间范围筛选，还要分页返回。用 MyBatis-Plus 的LambdaQueryWrapper实现非常顺手，不用写 XML：

@Override public PageResult<MaterialVO> pageMaterial(MaterialQueryDTO query) { Page<MaterialInfo> page = new Page<>(query.getPageNum(), query.getPageSize()); LambdaQueryWrapper<MaterialInfo> wrapper = new LambdaQueryWrapper<>(); // 关键字模糊匹配，搜索名称和备注 if (StringUtils.hasText(query.getKeyword())) { wrapper.and(w -> w.like(MaterialInfo::getName, query.getKeyword()) .or().like(MaterialInfo::getRemark, query.getKeyword())); } // 分类条件 if (query.getCategoryId() != null) { wrapper.eq(MaterialInfo::getCategoryId, query.getCategoryId()); } // 类型条件 if (StringUtils.hasText(query.getFileType())) { wrapper.eq(MaterialInfo::getFileType, query.getFileType()); } // 状态条件，普通用户只能看到已发布素材 wrapper.eq(MaterialInfo::getStatus, MaterialStatus.PUBLISHED.getCode()); // 排序：最新上传的排前面 wrapper.orderByDesc(MaterialInfo::getCreateTime); Page<MaterialInfo> result = materialMapper.selectPage(page, wrapper); // 将 Entity 转 VO，补充标签列表和上传人姓名 return PageResult.of(result, this::convertToVO); }

有几个细节值得注意。StringUtils.hasText比StringUtils.isNotBlank多一层 null 保护，直接用省心。LambdaQueryWrapper的and方法一定要用，否则关键字条件可能被后续的eq条件覆盖，SQL 拼接结果会不符合预期。分页查询得到结果后不要直接返回 Entity，要转 VO。素材列表需要带标签名称、分类名称、上传人昵称，这些信息分散在不同表里，最简单的方式是在 Service 层查完后用批量 ID 集合做二次查询填充，避免在循环里逐条查数据库。

分页插件配置类要注意注册顺序，多租户插件、分页插件、乐观锁插件最好按固定顺序添加，否则可能数据源切换时报错：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }

3.3 文件上传、预览与存储方案

文件上传是多媒体系统最核心的接口，也是和普通 CRUD 管理系统差异最大的地方。我做了两个接口：一个普通表单上传，一个流式分片上传。普通上传适合 100MB 以内的文件，分片上传适合大视频。分片方案不是一开始就要做的，如果业务场景确定是办公素材为主，普通上传加一个 Nginx 的client_max_body_size配置就能扛住大部分场景。

普通上传接口的核心逻辑：

@PostMapping("/upload") public Result<UploadVO> upload(@RequestParam("file") MultipartFile file, @RequestParam("type") String type) { // 校验文件是否为空 if (file.isEmpty()) { return Result.fail("上传文件不能为空"); } // 校验扩展名是否在白名单内 String ext = getExt(file.getOriginalFilename()); if (!allowExtSet.contains(ext)) { return Result.fail("不支持的文件格式：" + ext); } // 生成 UUID 文件名，按日期分目录存储 String dateDir = LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE); String uuidName = UUID.randomUUID().toString().replace("-", "") + "." + ext; Path targetPath = Paths.get(uploadRootDir, dateDir, uuidName); Files.createDirectories(targetPath.getParent()); file.transferTo(targetPath); // 组装返回信息 UploadVO vo = new UploadVO(); vo.setUuid(uuidName); vo.setUrl("/files/" + dateDir + "/" + uuidName); vo.setSize(file.getSize()); vo.setExt(ext); return Result.success(vo); }

文件存储路径按日期分目录，好处是归档清晰，后续做冷热数据迁移直接按目录切就行。文件名用 UUID 而不用原始文件名，是为了避免中文文件名导致 URL 转义乱码和路径穿越风险，但数据库里一定要保留原始 name 字段，否则用户在列表看到的就是一串无意义的字符。

静态资源映射要在 SpringBoot 里配置，把/files/**映射到本地磁盘目录：

@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Resource private StorageProperties storageProperties; @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/files/**") .addResourceLocations("file:" + storageProperties.getUploadRootDir()); } }

上传接口返回的 URL 就是http://域名/files/20250101/uuid.mp4，前端直接把这个路径给<video>或<img>标签就能预览。这里有个大坑——本地磁盘路径最后一定要加斜杠，Windows 下file:D:/upload/这样写，不加斜杠 Spring 路径匹配会失败，访问 404。跨域问题如果前后端分离部署也要处理，我用的方案是配置CorsRegistry，允许本地开发端口 5173 访问后端 8080，线上环境走 Nginx 同域代理，就不需要开跨域。

3.4 登录鉴权与菜单权限设计

这个系统的登录采用 JWT 方案，SpringBoot 端生成 token，前端存储到 localStorage，每次请求在Authorization头里携带。用户表设计的时候要预留一个role字段，管理员和普通用户通过拦截器区分接口访问权限。用拦截器而不是 Shiro 或 Spring Security 的原因很简单——项目角色少，权限模型简单，引入重框架反而增加配置复杂度。

拦截器实现时要注意放行白名单，登录、注册、文件预览这些接口必须放行，否则前端登录页加载时静态资源也被拦截。实际开发中我遇到过一个隐蔽问题：JWT 过期时间设置了 24 小时，但是用户中午开始用，跨天后过期，前端没有做统一异常处理，接口返回 401 但页面没有任何提示，用户感觉是系统卡死了。后来在 Axios 拦截器里统一处理 401 响应，自动跳转登录页并弹出友好提示，这个问题才算解决。

4. Vue3 前端的实战落地

4.1 Vue3 工程结构与路由组织

前端用 Vite 构建，工程结构采用按功能划分的方式。素材管理、分类管理、标签管理、用户中心各自独立一个目录，内部再按views、components、hooks、api组织。这样做的收益是：每个模块的静态资源、接口请求、业务逻辑都在同一个文件夹里，改动素材列表时不用跳到别的目录找文件。

路由设计上用createWebHistory+ 懒加载。懒加载是必须做的，因为素材管理页面里图片预览组件、富文本编辑器体积都不小，全部打进首屏包会非常慢。实际配置示例：

const routes = [ { path: '/', component: () => import('@/layouts/MainLayout.vue'), children: [ { path: 'material/list', name: 'MaterialList', component: () => import('@/views/material/List.vue') }, { path: 'material/upload', name: 'MaterialUpload', component: () => import('@/views/material/Upload.vue') } ] } ]

路由懒加载配合 Vite 的代码分割，素材详情页和编辑器页只有访问时才加载，首屏体积能降下来一半以上。菜单权限控制我是通过路由守卫实现的——从后端拿到用户角色，根据角色动态调用router.addRoute添加可见的路由，用户没权限的菜单直接不注册。

4.2 素材管理页面核心组件实现

素材列表页用的组合式 API 写法，核心逻辑抽成一个useMaterialList函数，页面组件代码量少很多。筛选条件用 reactive 对象维护，监听查询条件变化自动请求列表。列表渲染用<el-table>不如<el-card>网格更直观——素材管理系统本来就要展示图片和视频封面，卡片式布局更符合视觉习惯。

列表卡片的核心逻辑：

<script setup> import { ref, reactive, onMounted } from 'vue' import { getMaterialPage } from '@/api/material' const filters = reactive({ keyword: '', fileType: '', categoryId: null, pageNum: 1, pageSize: 24 }) const materialList = ref([]) const loading = ref(false) async function loadList() { loading.value = true try { const data = await getMaterialPage(filters) materialList.value = data.records } finally { loading.value = false } } function handleSearch() { filters.pageNum = 1 loadList() } onMounted(loadList) </script>

上传素材这个功能我用了一个封装过的UploadDialog组件，支持拖拽上传、进度显示和上传成功后表单联动。进度条用的axios的onUploadProgress回调。不同素材类型展示也不同：图片直接展示缩略图，视频用 video 标签生成预览，音频只显示封面和播放按钮，文档用文件格式图标代替。预览模态框里视频播放用原生<video>标签加上controls属性就够用，不需要引入 vue-video-player，减少不必要的依赖体积。

4.3 前端与后端接口对接规范

接口对接最容易出问题的是参数命名不一致。后端 Java 习惯用驼峰命名categoryId，前端 JS 也是驼峰，本来不会出问题。但表单里有几个字段是后端 DTO 用下划线定义的，前端传的是page_num，结果匹配不上，查了半天才发现是命名风格没统一。后来干脆定死规范：所有接口字段一律用驼峰命名，后端在 DTO 上用@JsonProperty注解做映射，前端不用做任何转换。

Axios 封装也要注意几点。基础路径用import.meta.env.VITE_API_BASE_URL读取环境变量，在.env.development和.env.production里分环境配置，不要写死。请求拦截器里统一带上 token，响应拦截器里统一处理错误码——业务错误码、401、500 分开处理，这样前端业务代码不需要每个请求都做异常判断。文件下载这个环节还有一个特写：后端返回的是 blob，需要一个单独的处理逻辑，提取响应头里的content-disposition获取文件名，而不是用请求配置里的默认文件名。

4.4 高清图片与视频预览的细节优化

素材预览是用户体验的重点。我的列表页做了懒加载，图片只在进入视口时才加载，用IntersectionObserver实现，<img>标签的loading="lazy"属性也能作为方案，但IntersectionObserver可以自定义阈值，比如在距离视口 200px 时就开始加载，体验更顺滑。视频预览不直接加载原文件，而是调用后端的截图接口生成一张封面图，否则列表页同时渲染几十个<video>标签，带宽压力很大。

视频截图接口用 Java 的FFmpeg命令调用实现，上传完成后异步生成一张封面存到封面字段。这个功能本身并不复杂，但注意服务器上要提前装好 FFmpeg，并且 Java 进程要有执行命令的权限，否则调用时会直接抛IOException，排查起来比较隐蔽。

5. 环境部署与常见问题排查实录

5.1 MySQL8.0 安装与字符集配置

这个系统开发环境用的 MySQL8.0，安装过程本身不复杂，但有几个配置一定要处理。第一，用 Docker 安装的话，一定要指定character-set-server=utf8mb4和collation-server=utf8mb4_unicode_ci，否则容器默认字符集可能不是 utf8mb4，中文插进去没问题，但 emoji 和生僻字会报错：

docker run -d \ --name mysql8 \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=yourpassword \ -e TZ=Asia/Shanghai \ mysql:8.0 \ --character-set-server=utf8mb4 \ --collation-server=utf8mb4_unicode_ci

第二，8.0 默认身份认证插件是caching_sha2_password，但一些老版本 JDBC 驱动只支持mysql_native_password。如果启动后端连接报错提示“Unable to load authentication plugin”，优先把 MySQL 连接器的 Maven 依赖版本升到 8.0.33 以上，而不是去改数据库用户的认证方式，升级驱动才是治本。第三，8.0 对ORDER BY和GROUP BY的默认行为更严格，SQL 里面出现SELECT * FROM material GROUP BY category_id，在 5.7 能过，在 8.0 会直接报错，因为name、file_path这些字段不在 GROUP BY 里。遇到这类问题，SQL 写法要做相应的调整。

5.2 前后端联调中的典型问题

前后端联调遇到的第一个大问题是端口冲突和跨域。SpringBoot 默认跑在 8080，Vite 开发服务默认 5173，前端直接访问后端接口必然跨域。我在开发环境配置了 Vite 的代理，生产环境用 Nginx 反向代理，/api前缀的请求转发到后端 8080：

location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; client_max_body_size 500m; }

client_max_body_size这个配置很关键。第一次上传视频时，Nginx 直接报 413 Request Entity Too Large，前端页面却只显示“上传失败”，没有任何详细错误，排查了整整一下午才发现是 Nginx 默认上传大小限制 1MB。后来在server块里加上client_max_body_size 500m，问题立刻解决。文件预览 404 也是常见问题，SpringBoot 静态资源映射和 Nginx 的location /files/配置很容易混淆，如果前端能访问素材但是图片和视频加载不出来，优先检查 Nginx 有没有把/files/也代理到后端，或者后端静态资源目录是否写对。

还有一个隐蔽的时区问题。MySQL8.0 连接串里不配置serverTimezone=Asia/Shanghai的话，后端返回的时间字段和数据库存储时间可能差 8 个小时。素材上传列表按日期筛选时，晚上传的文件会归到第二天。这个问题在本地开发环境因为 JDBC 驱动自动适配不明显，但部署到云服务器后，时区设置不一致就容易露馅。建议无论是 Docker 容器还是云服务器，都显式设置系统时区为 Asia/Shanghai。

5.3 常见问题速查表

6. 实操心得与后续扩展方向

这个系统做完之后，我最大的体会是：选对技术栈能把项目下限拉高，但真正的复杂度藏在业务细节里。比如素材文件预览、大文件上传、时区与字符集处理，这些在技术文档里不会教，需要实际动手踩坑才能积累经验。如果你是准备拿这个项目做毕业设计或者课程设计，建议在现有基础上再加一个素材审核流程，业务闭环会更完整；如果是要放到生产环境，强烈建议把文件存储切到 MinIO 或者其他对象存储，本地磁盘方案在单机演示没问题，但面对多人并发访问时，磁盘 IO 和容量都可能成为瓶颈。

另外一个小技巧：开发过程中把前后端接口文档用 Apifox 维护起来，写完一个模块就测试一个模块，不要全部堆到最后联调。这个项目后期改了三版接口字段，如果都堆到最后，光是沟通成本就能拖垮整个进度。数据库表结构如果业务还没完全确定，不要急着加太多冗余字段，宁可第一次设计少一点，后续通过ALTER TABLE补充。字段命名和大小写规则要统一，MySQL 在 Linux 下表名是大小写敏感的，Windows 下不敏感，这个差异容易让开发环境正常但生产环境报错，项目一开始就要约定全小写加下划线的命名规范。

如果你正打算用自己的方式复刻一套类似的系统，希望这篇内容能帮你少走点我走过的弯路。还想继续折腾的话，下一个版本可以试试引入 Redis 做素材热度排行，或者用 Elasticsearch 替换数据库的模糊查询，体验一下不同中间件在同一项目里共存的感觉。