1. 项目背景与整体设计1.1 非遗文化网站到底要解决什么问题几年前我参与过一个面向西北某省的非物质文化遗产数字化展示系统开发。非遗文化网站这类项目表面看是“给非遗项目做一个展示官网”真正做起来才发现痛点相当集中一是非遗种类庞杂包含传统技艺、民俗、戏曲、舞蹈、医药等多个门类数据关联关系复杂二是每一类非遗又涉及传承人、所属地区、历史渊源、保护等级等多种属性普通的内容管理系统很难兼顾展示效果和数据管理效率三是大量图片、视频资源需要稳定地上传、存储和回显前端展示和后端处理要配合好四是管理者往往不是专业程序员后台操作必须直观、简单。这个项目最终采用的是SpringBoot2 Vue3 MyBatis-Plus MySQL8.0这套组合。SpringBoot负责提供稳定的后端接口服务Vue3负责前台展示和后台管理界面的交互MyBatis-Plus作为数据访问层的利器大大简化了CRUD开发MySQL8.0则承载全部结构化数据。整套技术栈在中小型Web项目中属于非常成熟可靠的搭配开发速度快后期维护也方便。选这套组合还有个实际考虑非遗网站系统的用户量通常不像电商、社交平台那样呈爆发式增长它的核心诉求是“数据清晰、展示美观、管理顺手、运行稳定”这套技术栈正好全部命中。另外对于高校实验室、文化单位或外包团队来说这套技术栈的学习成本低招人也好招不像某些小众框架那样后期维护困难。1.2 技术选型背后的取舍逻辑先说SpringBoot2。为什么不选SpringBoot3非遗类系统往往需要集成大量第三方库和旧版本依赖SpringBoot2在生态兼容性上更稳妥尤其是很多MyBatis-Plus版本、连接池版本和权限组件在Boot2下踩坑最少。而且大部分服务器上跑的JDK还是8或11SpringBoot2配合得最舒服。不是追新不好而是做项目要优先考虑稳定可控。Vue3的选择同样有讲究。Vue3的组合式APIComposition API让逻辑复用变得非常顺手比如非遗项目的“分类筛选关键字搜索分页”这一套逻辑抽成一个自定义hook之后在多个页面里都能复用代码量能少很多。配合Vite构建开发时的热更新速度明显比Vue2Webpack快对调试体验的提升非常直接。MyBatis-Plus的价值在于它把单表CRUD全部封装好了。非遗项目的核心表包括非遗项目表、传承人表、分类表、新闻资讯表、用户表等每一张表的增删改查都是高度相似的模板代码。用MyBatis-Plus的BaseMapper和IService这些基础操作连SQL都不用写直接调现成方法就能完成。复杂查询再用注解或XML自定义SQL既保证开发效率又不失灵活。MySQL8.0的选择理由就更朴素了。MySQL8.0的窗口函数在处理“按地区统计非遗项目数量”这类统计报表时非常方便JSON类型的字段支撑也能让扩展性更好。另外8.0默认的utf8mb4字符集对非遗名称里可能出现的生僻字、特殊符号支持得很完整这一条就足够说服团队做决定了。2. 数据库设计非遗数据模型怎么建才合理2.1 核心表结构与表关系梳理非遗网站的数据模型是整项目的根基。我当时的做法是先梳理出几大核心实体非遗项目、传承人、分类、地区、资讯、用户。非遗项目和传承人是多对多关系一个项目可能有多个传承人一个传承人也可能掌握多个非遗项目项目和分类是多对一关系每个非遗项目归属一个具体的分类项目和地区是多对一关系标注它流传的主要区域。非遗项目表是最核心的一张表字段设计上有几个地方值得注意。项目名称用varchar(100)但索引要建上因为前台搜索和列表排序都会用到。保护等级字段用tinyint类型存储0代表未定级1代表县级2代表市级3代表省级4代表国家级这样在后台做筛选时条件构造非常方便。项目简介用text类型详细描述用longtext因为非遗介绍往往包含较长篇幅的历史渊源和传承谱系。传承人表建议独立出来不要写在项目表里。之前有个同行图省事把传承人姓名直接作为字段存在项目表里结果后来要做“按传承人搜索他掌握的所有非遗项目”时发现SQL写得极其别扭最后不得不拆表。这种从业务反推表结构的过程其实很考验对需求的理解深度。拆表的代价是关联查询会多一些但数据模型的清晰度提升了一个档次后期扩展“传承人详情页”是非常自然的事情。附件资源表也要单独设计。非遗项目往往伴随大量图片、视频资源把这些资源的路径存到独立表中用module_type和module_id两个字段去关联具体业务记录后续做视频轮播、图片画廊就很灵活。我看到很多初学者喜欢直接在业务表里加一个“图片地址”字段这在后期维护时会出现各种代码层面的混乱实际开发中不太可取。2.2 MySQL8.0下的建表细节与字符集处理建表时字符集统一用utf8mb4排序规则选utf8mb4_general_ci就够了。有些项目会选utf8mb4_unicode_ci但对非遗这种中文字段为主的场景两者性能差距微乎其微通用排序规则反而更省心。表的引擎默认InnoDB事务支持在后台批量导入数据时非常重要——比如一次性导入几十个非遗项目任何一个失败都要全部回滚不能出现一半成功一半失败的情况。这里给出项目表的一个简化建表SQL参考CREATE TABLE intangible_heritage ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT 主键ID, name VARCHAR(100) NOT NULL COMMENT 非遗项目名称, category_id BIGINT NOT NULL COMMENT 分类ID, region_id BIGINT DEFAULT NULL COMMENT 地区ID, protection_level TINYINT DEFAULT 0 COMMENT 保护等级0未定级 1县级 2市级 3省级 4国家级, intro TEXT COMMENT 项目简介, detail LONGTEXT COMMENT 项目详细介绍, cover_image VARCHAR(255) DEFAULT NULL COMMENT 封面图片路径, status TINYINT DEFAULT 1 COMMENT 状态0草稿 1发布, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新时间, PRIMARY KEY (id), KEY idx_category (category_id), KEY idx_region (region_id), KEY idx_status (status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT非遗项目表;几个设计心得可以分享。create_time和update_time这种字段强烈建议用DATETIME而不是TIMESTAMPTIMESTAMP在2038年会有溢出问题而且DATETIME的写入和展示逻辑更直观。所有表都建议保留status字段用于逻辑删除和发布状态控制不要真的物理删除数据非遗数据往往可能重新修订后再次发布物理删了再要恢复就是灾难。2.3 数据库索引优化与查询避坑非遗网站的数据量虽然不大但索引策略依然不能乱。分类筛选、地区筛选、保护等级筛选是列表页最常用的三个查询条件所以索引要尽量覆盖这些查询组合。我习惯建立联合索引category_id, status, protection_level因为列表查询通常同时带这三个条件联合索引能最大程度命中。MyBatis-Plus使用过程中最典型的坑是条件构造器使用不当导致索引失效。比如在LambdaQueryWrapper中对索引字段使用like查询且前置百分号例如like(%剪纸)这个查询没法走索引数据量大了之后响应时间会明显变慢。前台搜索框的模糊查询建议采用ngram全文索引或者限制查询范围最简单的办法是对name字段加一个全文索引然后用MATCH AGAINST语法查询支持度会好很多。ALTER TABLE intangible_heritage ADD FULLTEXT INDEX ft_name (name) WITH PARSER ngram;MySQL8.0默认支持ngram全文解析器对中文分词的内置支持已经不错。当年MySQL5.7时代做中文全文检索需要额外装插件现在8.0一条命令解决确实方便很多。如果不想用全文索引退而求其次可以用右模糊查询也就是like(剪纸%)虽然不如全文索引精确但至少能走索引性能不会太差。3. 后端业务逻辑实现与核心接口开发3.1 SpringBoot2工程结构与分层设计工程结构上没有跟随网上那些过度拆分的微服务思想就是一个标准的单应用多模块结构controller、service、mapper、entity、common、config这几个包。非遗网站的并发量有限单体应用完全够用过度设计反而是负担。分层的思想值得铺开讲一下。Controller层只负责接收参数和返回结果不写任何业务代码Service层承载业务逻辑比如“发布一个非遗项目时需要同时更新项目状态和生成一条操作日志”这种组合操作Mapper层就是纯数据库访问。这样分层的最大好处是出了问题能快速定位——接口报错先看Controller逻辑不对查ServiceSQL有问题找Mapper层级分明。我之前接手过一个小团队的项目他们把SQL拼接、参数校验、权限判断全部堆在Controller里单个类的代码动辄上千行。这种代码不是不能跑是每次需求变更都让大家头皮发麻。所以这个项目我宁可多写几个类也要保持每一层的职责纯粹。3.2 非遗项目列表与详情接口的封装列表接口是前台访问量最大的一个我直接使用了MyBatis-Plus的分页插件。先注册一个MybatisPlusInterceptor加入PaginationInnerInterceptor然后分页查询就变成下面这样IPageHeritageVO page new Page(current, size); LambdaQueryWrapperHeritage wrapper new LambdaQueryWrapper(); wrapper.eq(Heritage::getStatus, 1) .eq(StringUtils.isNotBlank(categoryId), Heritage::getCategoryId, categoryId) .like(StringUtils.isNotBlank(keyword), Heritage::getName, keyword) .orderByDesc(Heritage::getUpdateTime); IPageHeritageVO result heritageService.pageCustom(page, wrapper);注意这里的eq方法配合StringUtils.isNotBlank判断是条件构造器非常经典的一种用法——参数有值才拼接条件没值就跳过避免了在代码里写一堆if-else。对于前端传过来的筛选条件这种写法可以在一行内完成“可选条件”的处理比手写动态SQL舒服多了。详情接口需要注意的点是浏览量计数。非遗项目的详情页通常要展示访问次数但如果每次请求都发一条UPDATE语句去更新浏览量字段高并发下会给数据库带来无谓的压力。我这里采用了Redis计数浏览量写入Redis的String类型键定时批量刷新到数据库。如果项目里没接Redis也可以用内存缓存加定时任务的方式但一旦实例重启计数就会丢失。对于中小型非遗网站来说其实浏览量并不是一个需要精确到个位数的指标用定期刷新的方式足够。3.3 后台管理关键功能实现后台管理功能中非遗项目的增删改查是最核心的模块其中“新增项目”涉及的信息录入项特别多基本信息、分类归属、地区归属、传承人关联、图片视频资源、详细介绍等。这个表单一次提交的数据量很大如果用单表一次性insert会非常笨重更好的做法是在Service层使用事务先插入主表数据拿到主键ID再插入子表数据传承人关联、附件资源关联所有步骤在同一个事务里完成。Transactional(rollbackFor Exception.class) public Long createHeritage(HeritageDTO dto) { Heritage heritage new Heritage(); BeanUtils.copyProperties(dto, heritage); heritageMapper.insert(heritage); // 保存传承人关联 if (CollectionUtils.isNotEmpty(dto.getInheritorIds())) { heritageInheritorService.saveBatch(dto.getInheritorIds().stream() .map(inheritorId - new HeritageInheritor(heritage.getId(), inheritorId)) .collect(Collectors.toList())); } // 保存附件资源 if (CollectionUtils.isNotEmpty(dto.getAttachments())) { attachmentService.saveBatch(dto.getAttachments().stream() .map(url - new HeritageAttachment(heritage.getId(), url)) .collect(Collectors.toList())); } return heritage.getId(); }Transactional在SpringBoot里的使用有个细节很容易被忽略它默认只在抛出RuntimeException时回滚如果你在事务方法里捕获了异常然后返回一个错误提示事务是不会回滚的。实际开发中我会把异常继续抛出去由全局异常处理器统一处理这样事务才能正确感知到异常并完成回滚。3.4 文件上传与静态资源映射非遗项目的图片和视频上传是后台使用频率非常高的功能。文件上传我用的是本地存储方案把上传目录配置到application.yml中同时配置静态资源映射让前端能通过URL直接访问到上传的文件。SpringBoot中配置本地文件映射的代码非常简单Configuration public class WebConfig implements WebMvcConfigurer { Value(${file.upload-path}) private String uploadPath; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/uploads/**) .addResourceHandler(file: uploadPath /); } }文件上传时要注意文件名不要用用户原始文件名直接存原因是可能会包含中文、特殊字符甚至路径穿越符号。我的做法是用UUID重命名文件原始名称存入数据库的name字段存储路径只用UUID。这样既避免了文件名冲突也杜绝了安全问题。音频视频这种大文件上传时要设置SpringMVC的文件大小限制尤其要区分单个文件大小和请求总大小两个配置。非遗项目的视频往往有几十MB限制放宽到100MB是合理的但要注意Nginx的client_max_body_size也要一起调整否则前端上传到Nginx就被拦截了后端配置得再大也没用。4. 前端Vue3与前后端交互细节4.1 路由设计与页面架构Vue3前端我采用的是Vite构建、Vue Router管理路由、Pinia管理全局状态。页面结构分为两块前台展示端和后台管理端。两个端用不同的布局组件但共用同一套技术基础。前台页面包括首页、非遗项目列表页、项目详情页、传承人列表页、传承人详情页、资讯列表页、关于我们等。首页的设计比较关键因为非遗网站很强调视觉冲击力首页要在首屏内展示代表性非遗项目的轮播大图。轮播数据从后端接口获取取保护等级最高、浏览量最高的几个项目。后台管理端采用经典的侧边栏加内容区布局左侧菜单包括工作台、非遗项目管理、传承人管理、分类管理、地区管理、资讯管理、附件管理等。侧边菜单的配置数据放在前端路由的meta字段里根据用户的角色权限动态生成可见菜单。Vue3的Composition API在这种后台系统中非常好用。比如列表页的“搜索分页”逻辑我提取了一个usePageList组合式函数把请求参数、响应数据、加载状态、分页方法都封装进去每个列表页只需五行代码就能完成基础逻辑绑定。这个hook在很多后台项目里都能直接复用属于写一次受益很久的代码资产。4.2 分页组件与加载状态处理后台管理端的表格列表和前台的项目列表都涉及分页。分页参数的设计要前后端统一页码用current每页条数用size返回数据用records加total的结构。列表页请求发出后必须有loading状态的反馈否则用户会以为页面卡住了。Element Plus的表格组件自带loading属性绑定一个ref后请求结束再置为false体验非常顺滑。详情页的数据加载要考虑是否存在级联依赖。比如打开非遗项目详情页时需要同时加载项目基本信息、传承人列表、图片轮播数据这三个接口相互独立可以并发请求而不是串行等待。Vue3中用Promise.all一发出去总耗时只取决于最慢的那个接口页面加载体验明显提升。我在实际调试中发现很多新手写详情页时会把三个请求写成三层嵌套的写法第二个请求要等第一个请求结束后才发出白白增加了不必要的响应时间。这里的优化几乎是免费的却能给用户带来直观的感受提升。4.3 跨域配置与请求封装前后端分离最典型的障碍就是跨域问题。开发环境下Vite默认监听5173端口而后端跑在8080两者不同源必须配置跨域。最省事的方式是后端在WebConfig里配置CORS映射registry.addMapping(/**) .allowedOriginPatterns(http://localhost:*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowCredentials(true) .maxAge(3600);注意allowedOriginPatterns和allowCredentials同时使用时不能写成allowedOrigins(*)加allowCredentials(true)的组合这种配置浏览器会直接拒绝响应。这个细节花了很多人半天时间排查。另一个方案是用Nginx反向代理开发环境不做跨域生产环境把/api前缀的请求转发到后端服务这种方式更贴近真实的部署形态。前端请求统一使用Axios封装拦截器里做好鉴权令牌的携带和统一错误提示。后端接口返回统一格式的数据结构code、message、data。前端在响应拦截器中判断code非200时统一弹错误提示避免每个页面重复写错误处理代码。登录认证采用JWT形式前端在登录成功后把token存储到本地在请求头中携带Authorization字段。4.4 富文本组件在资讯管理里的应用资讯管理模块中发布非遗新闻动态或政策文件时需要富文本编辑能力。这个模块我使用了现成的富文本组件但做了一些定制图片上传走的是后端的文件上传接口编辑器中粘贴的图片以及本地选择的图片都先传到服务器然后回填图片URL。这样做的好处是富文本内容里存的都是可直接访问的完整链接不依赖编辑器本地状态。富文本内容存储到数据库时要注意XSS防护。非遗资讯的后台编辑者有可能是内部工作人员如果富文本内容里被注入了恶意脚本其他用户访问页面时就会中招。后端在返回富文本内容前做一次HTML清理过滤掉script标签和onerror等事件属性是很必要的安全措施。关于富文本组件再分享一个经验不要把富文本内容原封不动存到数据库就不管了建议同时对纯文本内容做一份提取存储到单独字段里。这样列表页摘要展示时直接取纯文本字段截断不需要对HTML字符串做各种正则处理省心很多。5. 权限认证与安全防护5.1 JWT登录认证的实现方案后台管理端必须做登录认证。这个项目采用的是JWT方案后端在用户登录成功后签发一个有效期2小时的token前端存储后每次请求带上后端拦截器验证token合法性并解析出用户信息。JWT在SpringBoot中的实现并不复杂引入jjwt依赖后核心代码就是生成token和解析token两个方法。生成时注意把用户ID、用户名和角色ID写入Claims解析时从Claims中取出来放入ThreadLocal这样后续的业务代码在同一个请求线程内随时可以拿到当前登录用户信息。public String generateToken(User user) { return Jwts.builder() .setSubject(user.getUsername()) .claim(userId, user.getId()) .claim(role, user.getRole()) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() 7200000)) .signWith(SignatureAlgorithm.HS256, SECRET_KEY) .compact(); }token过期时间的选择要平衡安全性和便利性。2小时对后台管理来说比较合适太短了管理员频繁重新登录会烦躁太长了token泄露后的风险窗口就变大。做了这个项目的登录模块后我的体会是“安全与体验之间永远是在互相妥协”关键是找到适合场景的平衡点。5.2 接口权限控制与角色区分后台管理系统的用户至少要分为超级管理员和普通管理员两种角色。超级管理员可以管理用户账号和所有业务数据普通管理员只能管理业务数据不能操作用户和权限。这个需求用拦截器加角色判断就能实现。实现方式是在Controller方法上使用自定义注解RequirePermission(heritage:edit) PostMapping(/heritage/update) public Result updateHeritage(RequestBody HeritageDTO dto) { ... }拦截器中解析注解对比当前用户的角色权限集合如果权限不足直接返回403响应。权限配置数据放到数据库用户表或权限表中不要在代码里写死角色清单因为后续需求变化时会相当被动。这里要专门提醒一个小坑拦截器拦截路径时要注意放行登录接口、验证码接口和前台展示接口。非遗网站的前台访客是不需要登录的如果拦截器把所有路径都拦截了前台页面全部无法访问。配置放行路径时花十分钟列一个清单远比上线后再频繁加白名单强得多。5.3 常见Web安全风险的防御实践对这个项目而言SQL注入的防御主要靠MyBatis-Plus的预编译机制。使用LambdaQueryWrapper构造条件时参数都是预编译传值很少会出现注入问题。风险点在于那些手写XML的SQL语句如果使用${}拼接参数就有注入风险必须改成#{}占位符。XSS攻击的防御分两个层面。输入层面后端接收参数时统一做HTML标签转义防止脚本内容入库。输出层面前端展示时Vue默认的插值语法会自动转义但v-html指令不会富文本内容使用v-html渲染时必须保证后端已经清理过脚本标签。这个项目的资讯模块做了双重校验后端入库前清理一遍接口返回时再清理一遍。CSRF防御在前后端分离架构下主要是靠token验证机制。因为我们的接口要求携带自定义请求头Authorization跨站请求伪造很难构造出带正确请求头的请求天然具备一定防护能力。加上项目对涉及数据变更的接口全部限制为POST请求进一步降低了风险。另一个容易被忽略的安全问题是配置文件中的数据库密码。项目中我将数据库凭据放到独立的配置文件中在部署时通过环境变量注入避免明文密码写死在代码仓库里。这个习惯越早养成越好后期接入持续集成时就知道好处了。6. 部署上线与运维避坑实录6.1 环境准备与前后端打包这套项目部署起来不算复杂。后端打成jar包扔到服务器上Java环境装好JDK8以上就能跑前端通过npm run build生成dist目录放到Nginx的html目录下。后端打包时注意application.yml中的配置要区分开发环境和生产环境。SpringBoot的Profile机制可以定义application-dev.yml和application-prod.yml两个文件启动时通过spring.profiles.active指定。数据库连接、文件上传路径、前端访问地址这些配置项在不同环境下的值往往不同不做Profile拆分就只能每次部署前手动改配置非常容易出错。Nginx配置是前后端分离项目部署的关键一环。前端静态资源由Nginx直接服务同时配置/api前缀的请求反向代理到后端服务的8080端口。一个典型的server块配置如下server { listen 80; server_name your-domain.com; root /var/www/heritage-web; index 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/heritage-uploads/; } }前端路由使用history模式时还要配置一个try_files将所有不存在的路径指向index.html否则用户直接访问某个详情页地址时Nginx会返回404。这个配置属于前后端分离项目的必踩坑忘了它首页正常但细节页刷新就白屏。6.2 常见问题与排查方法整理我整理一下这个项目开发和部署过程中遇到频率最高的几个问题每个都是实际踩过的坑。问题一前端访问接口404。排查思路先看请求URL是否正确再看Nginx代理目标是否可达然后看后端接口是否真的存在。曾经遇到过一次404是因为Controller类上漏了RestController注解方法返回的是字符串而不是JSON前端拿到String当JSON解析直接报错。问题二MyBatis-Plus分页不生效。最常见的解决方式是检查是否注册了PaginationInnerInterceptor插件。很多人引入MyBatis-Plus后直接用分页方法发现返回的结果全量数据就是漏了这一步配置。Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; }问题三图片上传成功但访问不到。这通常是因为静态资源映射没配置对或者Nginx的alias路径和上传目录不一致。排查时先看后端日志确认文件写到了哪个绝对路径再看这个路径和配置的映射是否吻合然后访问完整的URL看是前端路径拼错还是后端映射问题。问题四MySQL8时区报错。数据库连接串需要带上serverTimezoneAsia/Shanghai否则驱动会报时区异常。这个问题几乎每个用MySQL8的SpringBoot项目都会遇到加在JDBC URL后面就行。问题五跨域配置后还是报跨域错误。这时要检查浏览器实际发出的请求是否带了触发预检的复杂请求头。如果是带自定义Header的POST请求会先发一个OPTIONS预检请求预检请求需要被后端正确处理。如果拦截器拦截了OPTIONS请求或者CORS配置没有覆盖到这个路径就会表现成跨域失败。6.3 项目经验总结与扩展思路做完这个非遗网站系统我最大的感触是非遗文化类项目的核心价值不在于技术难度多高而在于能不能把文化数据有序地管理起来、生动地展示出去。技术的意义在于帮助文化单位完成数字化转型的第一步让非遗资料从纸质档案变成可检索、可展示、可传播的数字资产。这个项目后续还可以继续扩展的方向不少。比如增加地图展示功能用地图标记的方式展示非遗项目的地理分布再比如做移动端适配或小程序版本让游客能在手机上更方便地浏览还能对接文化馆的数据系统实现数据的互联互通。技术栈方面如果数据量增长明显可以考虑引入Redis缓存热点数据和ElasticSearch做全文搜索但这些优化都要建立在明确的需求和数据量基础上不建议盲目上。最后再分享一个经验部署后记得关闭SpringBoot的默认错误信息泄露。生产环境配置中把server.error.include-message设置为never避免异常堆栈直接暴露给前端用户。很多人做完项目上线就完事了但这些细节才真正体现一个开发者是不是有生产环境经验。每次看到这类细节都会想起自己前几年在运维上吃的亏也算是一种成长印记。