SpringBoot+Vue3+MyBatis构建陕西民俗文化展示系统全流程解析

做陕西民俗类的文化展示系统，最容易踩进去的坑是把它当成"普通官网"来做。普通的公司官网核心是图文展示，数据模型一张文章表基本够用；但民俗内容的组织方式完全不一样——一个民俗项目有分类属性、地域属性、图片素材、关联资讯，前台既要支持按分类浏览，还要支持关键词搜索，数据之间的关系是网状的，不是线性的。所以这个项目的技术栈选了Java SpringBoot+Vue3+MyBatis，配MySQL，前后端分离，不是为了炫技，而是这套组合在"内容管理+灵活查询+快速迭代"这三个要求上正好各司其职。

这篇博文会把整个项目从头到尾拆一遍：需求怎么拆、表怎么建、接口怎么设计、Vue3页面怎么组织、部署踩过哪些坑。无论你是拿它当毕业设计参考，还是想给某个地方文化项目搭一套展示系统，都可以直接对照落地。下面开始。

1. 需求拆解：陕西民俗内容系统的特殊之处

1.1 先定义用户：谁在看，谁在维护

做系统之前第一件事不是选框架，而是老老实实想清楚这个站给谁用。这个项目我划分了三类角色，每类角色的诉求完全不同。

第一类是普通访客。他们的典型行为是：打开首页，看到轮播图里有近期民俗活动，点进分类页面浏览民间戏曲、传统手工艺，然后在搜索框里输入"皮影""社火"这类词，找到对应的民俗项目介绍和资讯文章。访客要的是"快速找到内容"和"阅读体验舒服"，对后台逻辑一概不关心。

第二类是内容运营者。这个角色决定了系统的表结构能不能用。运营者要维护民俗分类、录入民俗条目、发布活动报道、上传图片素材。他们不是程序员，所以后台界面要直观，分类层级要清晰，图片上传不能出岔子。

第三类是我自己，也就是系统管理员。我关心的是数据是否规范、接口是否稳定、部署是否方便，以及后续加功能时改动成本高不高。

把这三类人的需求叠在一起，系统的核心模型就浮现出来了：民俗分类、民俗条目、资讯文章、图片素材，外加一个管理员账号体系和访客留言。这四块数据之间有清晰的关联关系，但又不能像企业ERP那样做太强的业务耦合，因为民俗内容本身是灵活多变的。

1.2 功能地图：前台浏览、后台管理两块闭环

基于上面的用户分析，功能清单可以分成两个端。

前台展示端：

• 首页：轮播图、热门民俗推荐、最新资讯列表。
• 民俗分类页：按照大类展示民俗条目，支持分类切换和分页。
• 民俗详情页：名称、分类、地区、简介、详细内容、图片集、相关资讯。
• 资讯文章页：新闻动态与活动报道的列表和详情。
• 搜索：按关键词检索民俗条目和资讯文章。

后台管理端：

• 管理员登录、会话校验。
• 分类管理：增删改查，支持树形层级。
• 民俗条目管理：录入、编辑、上下架、封面图设置。
• 资讯文章管理：富文本编辑、发布、置顶。
• 留言管理：审核与删除。

看到这里你应该能理解，为什么我一直强调别把民俗网站做成普通官网。普通官网的资讯模块是站点的全部，而这里民俗条目才是主角，资讯只是围绕它的动态补充。主表不同，整个字段设计和查询逻辑就全都不一样了。

2. 技术选型：为什么这套栈能扛住这类内容项目

2.1 前后端分离：一次性投入换长期的开发自由

这个项目用了前后端分离架构，后端只提供JSON接口，前端用Vue3独立构建。坦白说，对于这种体量的内容展示系统，前后端不分离一样能做出来，用Thymeleaf模板引擎渲染可能更快。那我为什么仍然坚持分离？

核心原因是内容类项目的页面改版频率远高于业务系统。今天首页想换个排版，明天详情页想加个图片墙，如果前后端耦合在一个工程里，每次改版都要动后端代码、重新部署整个服务，运维成本非常高。分离之后，前端样式和交互的调整完全是独立发布的，后端接口只要保持稳定就不受影响。

另一个原因是并行开发效率。前后端分离后，接口定义清楚，前端可以先拿Mock数据开发页面，后端专注业务逻辑，不会互相阻塞。这个项目到家时，也正是靠这一点把开发周期压了下来。

2.2 后端选型：SpringBoot版本、MyBatis与MyBatis-Plus

后端我选的是Java SpringBoot 2.7系列，JDK用的1.8。我知道SpringBoot 3.x已经普及，但就这个项目而言，2.7.18是一个更稳妥的选择：它的生态非常成熟，网上资料多，遇到问题都好查，而且可以平滑兼容JDK 1.8。如果你没有明确的升级需求，没必要为了新而新。

ORM层用了MyBatis，但实际开发中我同时引入了MyBatis-Plus。这两个不冲突，我把它们的分工划分得很清楚：

为什么不直接用JPA？JPA的自动建表能力确实诱人，但一旦查询条件复杂起来，生成的SQL常常不是你想要的，排查问题要从框架往下挖，心智负担不小。MyBatis的SQL完全掌控在自己手里，对于民俗条目这种多条件混合查询的场景反而更省心。

2.3 前端工具链：Vue3 + Vite + Element Plus + Pinia

前端这一侧，Vue3配合Vite做构建，UI组件库选Element Plus，状态管理用Pinia，请求库用Axios。这套组合在目前的Vue生态里基本是标准答案。

Vite最直观的收益是启动速度快，改代码热更新几乎无感。Element Plus则解决了后台管理页面的开发效率问题，表格、表单、弹窗这些组件开箱即用。Pinia相比Vuex的优势是API更简洁，在数据量不大的项目里写起来非常清爽。

组件库的选择有讲究。前台展示页面我尽量不用Element Plus，而是自己写卡片、列表、轮播这些组件，因为UI组件库做后台合适，做面向访客的前台页面容易显得千篇一律。前台自然一点，后台效率一点，这个边界很重要。

3. 数据库建模：一张民俗条目表背后的设计细节

3.1 六张核心表的关系梳理

表结构是这个项目的灵魂。我最终设计了六张核心表，它们的关系可以从业务角度串起来：

• category：民俗分类表，通过parent_id支持树形层级，比如"传统手工艺"下面挂"皮影制作""剪纸"。
• folk_item：民俗条目表，这是主角，通过category_id关联分类，通过region记录地域归属。
• article：资讯文章表，通过item_id关联到具体的民俗条目，也支持独立发布。
• image：图片素材表，通过target_type和target_id来标记图属于哪个条目或哪篇文章。
• comment：访客留言表，挂在民俗条目或文章下面。
• admin_user：管理员表。

为什么图片表不直接在folk_item里加一个image_url字段存一张图？因为民俗条目的图片几乎总是一组，封面图、细节图、场景图都有，用单独的图片表存多张图，扩展起来非常自然。通用关联字段target_type这种设计也别嫌抽象，它是让一套图片逻辑同时服务民俗条目和资讯文章的关键。

3.2 核心建表语句与索引设计

下面是folk_item和category的实际建表SQL，我删掉了注释和冗余字段，保留了最核心的部分。

CREATE TABLE `category` ( `id` int NOT NULL AUTO_INCREMENT, `parent_id` int NOT NULL DEFAULT '0' COMMENT '父分类ID，0表示顶级', `name` varchar(50) NOT NULL COMMENT '分类名称', `type` tinyint NOT NULL DEFAULT '1' COMMENT '1民俗条目分类 2资讯分类', `sort` int NOT NULL DEFAULT '0' COMMENT '排序值，越小越靠前', `status` tinyint NOT NULL DEFAULT '1' COMMENT '1启用 0禁用', `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_parent_id` (`parent_id`), KEY `idx_type` (`type`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='民俗分类表'; CREATE TABLE `folk_item` ( `id` int NOT NULL AUTO_INCREMENT, `category_id` int NOT NULL COMMENT '所属分类ID', `name` varchar(100) NOT NULL COMMENT '民俗项目名称', `region` varchar(100) DEFAULT NULL COMMENT '归属地区', `summary` varchar(500) DEFAULT NULL COMMENT '一句话简介', `content` text COMMENT '详细介绍', `cover_img` varchar(255) DEFAULT NULL COMMENT '封面图URL', `view_count` int NOT NULL DEFAULT '0' COMMENT '浏览量', `status` tinyint NOT NULL DEFAULT '1' COMMENT '1上架 0下架', `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_category_id` (`category_id`), KEY `idx_region` (`region`), KEY `idx_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='民俗条目表';

两个细节需要强调。第一，字符集必须用utf8mb4，因为民俗条目的介绍里经常出现生僻字和特殊符号，utf8mb4才能完整存储。第二，索引不是越多越好，我在这张表上只建了category_id、region、status三个二级索引，分别支撑分类查询、地域筛选和上下架过滤。像content这种大字段千万不能建索引，谁建谁吃亏。

3.3 分类的树形设计与查询策略

category表的parent_id字段让分类可以无限级扩展。前端展示时，我一般只加载两级：顶级分类作为导航，第二级在分类页左侧做筛选。查询的时候有两种做法，一种是递归查全树，另一种是懒加载。

我更推荐懒加载：先查顶级分类，用户点击某个顶级分类后再查它的子分类。对于陕西民俗这种数据量，一次查全表也就几百行，但懒加载的逻辑更清晰，新增分类时也不用担心破坏树结构。如果以后数据量真的大到需要一次返回整棵树，可以用一条SQL按parent_id排序查出所有分类，然后在内存里组装树，不要写递归SQL，性能和可读性都更好。

4. 后端开发：SpringBoot分层与MyBatis动态SQL实战

4.1 工程结构与统一返回格式

后端工程我按标准的四层结构组织：Controller负责接收请求，Service负责业务逻辑，Mapper负责数据库访问，Entity负责映射表和返回对象。代码量不算大，但包结构一定要清晰，否则项目越写越乱。

com.example.folklore ├── common # 统一返回体、全局异常、常量 ├── config # 跨域配置、拦截器、静态资源映射 ├── controller # 前端接口 ├── entity # 数据库实体 ├── mapper # MyBatis/MyBatis-Plus接口 ├── service # 业务接口和实现 └── util # 工具类

接口统一返回一个Result对象，结构是code、message、data三件套。这样做的好处是前端Axios拦截器里可以根据code统一判断成功失败，不用每个接口在Controller里反复封装。代码大概长这样：

@Data public class Result<T> { private Integer code; private String message; private T data; public static <T> Result<T> ok(T data) { Result<T> r = new Result<>(); r.setCode(200); r.setMessage("success"); r.setData(data); return r; } public static <T> Result<T> fail(String message) { Result<T> r = new Result<>(); r.setCode(500); r.setMessage(message); return r; } }

配合全局异常处理器，把所有业务异常和未捕获异常统一包装成Result返回，前端永远拿到的是固定结构。这样处理之后，联调阶段双方的沟通成本会低很多。

4.2 多条件搜索接口的动态SQL实现

民俗条目查询是后端最核心的接口，它要同时支持分类ID、关键词、地域这三个筛选条件，还要分页。这个逻辑用MyBatis的动态SQL写起来很自然：

<select id="searchFolkItems" resultType="com.example.folklore.entity.FolkItem"> SELECT * FROM folk_item <where> <if test="categoryId != null"> AND category_id = #{categoryId} </if> <if test="region != null and region != ''"> AND region = #{region} </if> <if test="keyword != null and keyword != ''"> AND (name LIKE CONCAT('%', #{keyword}, '%') OR summary LIKE CONCAT('%', #{keyword}, '%')) </if> AND status = 1 </where> ORDER BY view_count DESC </select>

动态SQL的 标签会自动处理条件拼接时多余的AND，这个特性非常实用。关键词搜索我用的是LIKE模糊匹配，陕西民俗的数据量几百条撑死了，性能完全够。如果有人给你推荐一上来就上Elasticsearch的方案，在这个体量下属于过度设计，简单问题就该用简单办法解决。

分页我用的MyBatis-Plus的Page对象，Controller接收页码和每页条数，Service里传给Mapper，返回时带上total、current、pages这些分页信息。前端拿到之后渲染分页条，逻辑非常顺。

4.3 图片与静态资源映射的细节处理

图片上传和访问是个容易出现小问题的地方。文件本身不能存数据库，我存的是上传目录下的相对路径，比如/uploads/folk/20240501/xxx.jpg，数据库里存这个相对路径，访问时再拼上域名。

开发阶段，在SpringBoot里配置静态资源映射，把本地磁盘的上传目录映射成虚拟路径：

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/uploads/**") .addResourceHandler("file:" + System.getProperty("user.dir") + "/uploads/"); } }

生产环境我建议直接交给Nginx来处理静态资源，Java服务只负责接口，这样能减轻Tomcat的负担。路径前缀保持统一，前端无论在开发还是生产环境都使用相同的URL格式，换环境时只需要改一层代理配置，页面代码一行都不用动。

5. Vue3前端落地：页面、组件与接口联调

5.1 前端目录与路由设计

前端用Vite初始化Vue3项目，目录结构如下：

src ├── api # 接口定义，按模块拆分 ├── assets # 静态资源 ├── components # 通用组件 ├── router # 路由配置 ├── stores # Pinia状态 ├── views # 页面组件 │ ├── home # 首页 │ ├── folk # 民俗列表和详情 │ ├── article # 资讯列表和详情 │ └── admin # 后台管理 └── utils # 工具函数

路由用createRouter配合懒加载配置，组件通过动态import引入。懒加载的意义在于，首页和后台管理是不同的访问路径，用户打开前台时完全不必加载后台的Element Plus组件，这样首屏加载速度会明显更快。

const routes = [ { path: '/', name: 'home', component: () => import('@/views/home/index.vue') }, { path: '/folk/:id', name: 'folkDetail', component: () => import('@/views/folk/detail.vue') }, { path: '/admin', name: 'admin', component: () => import('@/views/admin/layout.vue') } ]

5.2 Axios封装与请求拦截

接口请求统一封装在一个axios实例里，开发和生产的baseURL不一样，通过环境变量区分。响应拦截器统一处理code不等于200的情况，后端出现问题直接弹出错误提示，不用在每一个组件里重复写错误分支。

import axios from 'axios' const request = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL || '/api', timeout: 10000 }) request.interceptors.response.use( (response) => { const res = response.data if (res.code === 200) { return res.data } return Promise.reject(new Error(res.message || '请求失败')) }, (error) => { return Promise.reject(error) } ) export default request

开发阶段的跨域问题，我通过Vite的proxy配置解决，让前端发起的/api请求转发到后端的8080端口：

server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }

这个配置联调的时候非常关键。没配代理，前端直接请求后端端口，必然遇到跨域；配了代理之后，浏览器看到的请求和页面是同源的，跨域问题从根源上消失。

5.3 首页组件拆解与详情页数据回填

首页我拆成了四个组件：轮播图、分类导航、民俗条目卡片列表、最新资讯。每个组件只干一件事，通过父组件引用组合起来。轮播图自己封装，分类导航从后端读取顶级分类，民俗卡片点击后跳转详情页并带过去ID。

详情页是数据交互最集中的地方。进入页面时根据路由参数ID请求民俗详情，同时并行请求图片列表和关联资讯。关键点在于请求失败时的兜底处理：接口超时或者数据下架，页面要有明确提示，不能一直转圈。我的做法是加一个loading状态和一个error状态，分别渲染加载动画和"内容不存在"的占位页。

后台管理页面用Element Plus就很顺手了：表格组件绑定数据源，表单弹窗做新增编辑，上传组件对接后端的图片上传接口，分页组件配合Page对象的数据。后台的关键是表单校验要写好，民俗名称、分类、简介这些必填项在提交前都要校验，减少后端的数据清洗压力。

6. 部署上线与踩坑记录：从本地跑通到服务器稳定运行

6.1 本地联调最容易翻车的三个点

第一个坑是数据库连接配置。SpringBoot连接MySQL时，URL里必须加上时区参数，否则会在启动后报错或者时间差八个小时。我用的连接串是jdbc:mysql://localhost:3306/folklore?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai。另外，MySQL 8.0和5.7的驱动类名不同，如果用8.0的驱动，com.mysql.jdbc.Driver已经废弃，要写com.mysql.cj.jdbc.Driver。

第二个坑是MyBatis的驼峰映射。数据库字段是下划线风格category_id，Java属性是categoryId，如果不在配置里开启mapUnderscoreToCamelCase，查询结果里categoryId永远是null，而且没有任何报错提示，特别容易让人抓狂。在application.yml里加一行mybatis.configuration.map-underscore-to-camel-case: true就解决了。

第三个坑是前后端分离部署时的接口路径。开发阶段Vite代理把/api转发到8080，但生产环境如果没配置Nginx反向代理，前端打包后请求的/api会指向Nginx自身，结果404。这个问题的排查思路是：浏览器Network里看请求的实际地址，别只看页面报错。

6.2 打包、部署与Nginx反向代理配置

后端打包前先执行测试确认没问题，然后执行mvn package -DskipTests跳过测试直接打jar包。前端执行npm run build生成dist目录。

服务器上我选择直接用jar包启动，Java进程管理用nohup：

nohup java -jar folklore-system.jar --server.port=8080 > app.log 2>&1 &

Nginx的配置是前后端分离部署的核心。静态页面放在/var/www/folklore目录，前端请求/api时反向代理到本机的8080端口，上传的图片单独映射：

server { listen 80; server_name your-domain.com; root /var/www/folklore; 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 /uploads/ { alias /data/uploads/; } }

try_files那一行特别重要，Vue3是SPA应用，路由切换依赖前端history模式，如果用户直接刷新一个子路径（比如/folk/12），Nginx找不到这个文件就会404，加上try_files回退到index.html后，前端路由就能接管。

6.3 上线后的日常维护项

上线不等于结束，我列几个日常要盯的点。每天看一次app.log，重点检查有没有数据库连接池泄露和接口异常。数据库要定期备份，最简单的方式是每天凌晨用mysqldump导出一次，保留最近一周的备份。磁盘空间也要关注，图片和日志是增长大户，建议在上传目录加个清理策略，比如三个月前的临时图片自动删除。

管理员密码别用明文存储，用BCrypt加密。前端会话通过Token维持，后端提供登录接口签发Token，其他接口统一走拦截器校验。这一点在开发阶段可以偷懒，但一旦真实对外开放，就必须守住。

7. 这个项目还能怎么玩：可复用资产与后续迭代

7.1 沉淀下来的通用能力

做完这个项目你会发现，可复用的不只是那几十个接口。树形分类模型、统一返回体加全局异常的组合、动态SQL多条件查询、Vite代理联调模式、Nginx前后端分离部署模板，这五样东西在几乎任何内容管理类系统里都能直接搬过去用。下次接到类似项目，先把这些骨架搭好，业务往里填就行。

分类模型的通用性尤其高。地方文化、行业知识库、产品手册，凡是内容有层级、有归属的内容系统，都逃不开分类和条目这两张核心表。我后来做另一个非遗展示项目时，连建表语句都只改了表名和少数字段。

7.2 值得做的三个扩展方向

第一个方向是数据可视化。后台增加一个统计面板，用ECharts展示各分类条目占比、浏览量Top排行、地域分布图。前台也可以做一张"民俗分布地图"，用地图组件把不同地域的民俗项目标注出来，配合地区筛选，展示效果会提升一大截。

第二个方向是富文本和全文检索。后台文章编辑器换成富文本编辑器，让运营者排版更自由。当民俗条目量超过几千条时，LIKE查询会变慢，这时候再引入全文索引或者专门的搜索组件才是合理的时机。

第三个方向是移动端适配。民俗场景经常发生在现场，访客大概率用手机访问。可以把前台改造成响应式布局，或者单独做一个轻量的小程序版，复用现有的接口，只重写前端页面。

做内容系统给我最深的一个体会是：技术不是难点，对内容的建模才是。民俗条目怎么分类、图片怎么组织、资讯和条目之间怎么建立联系，这些想明白了，代码写起来又快又稳。这个项目走到今天，最值钱的部分恰恰是刚开始花了两天做的那份需求拆解和表结构设计。希望这篇拆解能帮你少走同样的弯路。