这套基于SpringBootVue的线上历史馆藏系统管理系统说白了就是给不靠堆代码也能看懂的数字化馆藏项目一个完整的落地方案。项目用了Java后端里最常见的SpringBootMyBatis组合配MySQL存数据前端用Vue开发页面最终做到展品录入、展览展示、在线预约、后台审核这样一套基本的馆藏业务闭环。我把它从零到一做完之后最大的感受是历史馆藏这类业务并不复杂但真正需要花时间的不是写代码而是搞清楚一件文物从库房到展线再到线上可预约之间数据状态到底是怎么流转的。这篇文章会给准备拿这个方向做毕业设计、或者想练手全栈项目的人把整体架构、数据库、核心接口和部署里那些真正会导致你卡住的细节都捋一遍。1. 想清楚要管什么业务对象、角色与状态流转1.1 展品、展览、预约三个不能绕过的核心对象很多人一接到线上历史馆藏系统的题目第一反应是赶紧建一张文物表然后开始写增删改查。这个思路不能说错但做出来的东西往往只有一个壳前台能列出几条文物介绍后台能往数据库里插入一条记录看起来功能齐了实际上没有业务闭环。真正把一个馆藏系统撑起来的是三个对象之间的关系展品、展览、预约。展品是资产本身。它需要记录编号、名称、年代、质地、来源、当前状态。展览是一个时间段内的展示事件某场主题展在什么时间举办、在哪个展厅、有哪些展品参与。预约则是人的行为游客看到展品和展览之后决定来线下参观于是产生一条预约记录馆员审核这条记录再决定是否确认。这三者的关系在数据库里天然是多对多一件展品可以先后参加多场展览一场展览可以同时展出多件展品。如果不提前建中间表而是把展品清单塞进展览表的一个字段里等你想查这件东西参加过哪些展览的时候就得写一串没人愿意维护的字符串切割逻辑那才是灾难。所以我的建议是动手建表之前先拿张纸把这三个对象之间的连线画出来。画完之后你会很自然地得出四张核心表展品表、展览表、展品展览关联表、预约表。这个顺序不是拍脑袋定的是跟着业务关系推出来的。1.2 三类角色与两条流程线上历史馆藏系统不是给单一用户用的至少要先分清三类角色游客、馆员、管理员。游客可以浏览公开的展品信息和展览日程登录之后能够提交参观预约。馆员负责展品信息的日常维护包括录入、修改、上下架同时维护展览信息并审核游客的预约。管理员在馆员的基础上多出用户管理和数据维护的权限。这样划分好之后前端路由该怎么守卫、后端接口该怎么鉴权基本就清晰了。与角色对应的是两条核心业务流程。第一条是展品状态流转。馆员录入一件展品时它的状态默认是在库。把它加入某场展览并发布展览后状态变成展览中。展览结束或撤展后再回到在库。如果遇到破损修复还可以有一个下架状态。这套状态机并不复杂但它决定了游客端能看到什么——游客页面只展示展览中或长期陈列的展品在库未展出的东西不该出现在前台否则等于把库房信息全部暴露了。第二条是线上预约流程。游客登录后选择参观日期、填写人数提交后生成一条状态为待审核的预约单。馆员在后台看到之后确认没问题就把状态改成已确认游客端看到确认状态后按计划到馆。实际操作里还可以继续扩展成生成二维码闸机核销但对于课程设计或小型馆藏的数字化起步做到审核状态流转已经是一个完整的闭环了。我每次带人做这类项目时都会强调业务流程图画明白后面开发速度会快非常多。数据库表结构、接口设计、前端页面数量都是从这两张图里长出来的。1.3 非功能性需求的底线除了能不能跑通还要考虑几个评委或项目验收人一定会问的点。第一是查询速度。馆藏数据虽然不像电商那样动辄上百万条但几千条文物加多张图片资源后模糊搜索也不能明显卡顿。解决办法就是分页加索引把按名称模糊查按年代精确查按分类查这些条件都落到SQL层面。第二是图片管理。文物照片通常是高清大图千万不要把图片转成Base64塞进数据库那一张图就能让接口响应变成好几秒。标准做法是图片上传到服务器目录数据库里只存访问路径。第三是安全。密码不能明文存后台接口不能裸奔。哪怕项目再小管理员操作至少也要有登录拦截不然别人拿到接口地址就能删数据演示的时候会非常尴尬。这些点不用做得很高级但在设计文档和答辩陈述里要能明确说出来。哪怕你最终只是用了最简单的分页、文件路径存储和一个拦截器也要让听的人知道你考虑过这个问题这个印象分差别很大。2. 技术栈与工程结构SpringBoot、MyBatis、Vue三者如何配合2.1 SpringBoot为什么省事后端选用SpringBoot核心原因是约定大于配置这一套把项目起步的成本压得很低。以前做SSH或SSM项目要手动维护Spring容器配置、SpringMVC的视图解析器、事务管理器光配置文件就能写一大摞。SpringBoot用起步依赖加自动装配把绝大部分默认配置封装好了我一个人从零建工程到把第一个Hello接口跑通基本只需要几步。开发这套馆藏系统时我用的依赖就那么几类spring-boot-starter-web提供Web能力spring-boot-starter-validation做参数校验mybatis-spring-boot-starter接MyBatismysql-connector-java连MySQL加一个jjwt做登录token再配合lombok减少实体类样板代码。简洁程度和可读性都比老框架时代好太多。2.2 MyBatis比JPA更合拍的原因在一些团队或个人项目里持久层也会选择JPA/Hibernate。我在这里用MyBatis是因为馆藏系统的查询条件特别容易变。今天要按年代筛选明天要加一个分类条件后天可能要同时按来源和状态组合搜索这种需求用MyBatis的动态SQL处理起来非常顺手写出来的SQL自己一眼能看懂出了性能问题也容易分析。JPA的Criteria API不是不行但对很多人来说理解成本更高一不留神还会生成一些让人看不懂的关联查询。另外一点是MyBatis能让我精确保留对SQL的控制权。比如查展品列表时我想在SQL里直接做状态过滤、排序、分页逻辑一目了然。对于以查询展示为主的历史馆藏系统来说这种直观感比对象导航带来的便利感更值钱。2.3 前后端分离的目录划分与通信约定我把项目拆成museum-backend和museum-frontend两个独立工程后端专门提供REST接口前端只负责页面渲染和数据展示。这么做的好处是职责分明配置和依赖互不污染。如果哪天想把前端或者后端单独部署到不同服务器也不需要结构上的大改。后端包结构建议这样分controller层接收请求和参数校验service层写业务规则mapper层放MyBatis接口entity对应数据库表dto负责和前端的数据传输config放跨域、拦截器、静态资源映射等配置utils放通用工具类common放统一返回结果和全局异常处理。这个分层没有任何新意但非常抗造项目从小到大都能往里装。前端和后端的通信约定要早期定好。我规定所有接口都以/api开头返回体统一是{code, message, data}结构。前端拿到返回体后先看codecode为200表示成功其他情况统一弹错误信息。这个约定看起来简单但能省掉大量后续联调时的沟通成本。3. 数据库建模从展品到预约的状态流转设计3.1 展品表字段设计与两个易错点展品表是整套系统的地基。我的核心字段大致如下字段类型说明idBIGINT主键自增exhibit_codeVARCHAR(32)展品编号唯一nameVARCHAR(100)名称dynastyVARCHAR(50)年代materialVARCHAR(50)质地categoryVARCHAR(50)分类如瓷器、书画、青铜器sourceVARCHAR(100)来源descriptionTEXT简介image_urlVARCHAR(255)主图路径statusTINYINT0在库 1展览中 2下架create_timeDATETIME创建时间update_timeDATETIME更新时间这里有两个新写代码的人容易踩的点。第一exhibit_code必须唯一。馆藏系统在清点、盘库、借展交接时系统主要靠这个编号来识别实物不能只依赖自增ID。如果编号重复后面做数据统计和实物对照时会彻底乱套。第二description用TEXT不要用VARCHAR(255)。文物简介随便写深一点就可能超过255字字段不够再迁移费时费力且容易出错。TEXT字段存几段简介绰绰有余是更稳妥的选择。3.2 展览和展品之间的中间表展览表和展品表是多对多关系必须用中间表解耦。展览表本身记录展览的标题、主题、开始日期、结束日期、展厅位置、状态。中间表主要保存展览ID和展品ID的对应关系我还会加一个sort_order字段表示展品在展览中的排序序号。CREATE TABLE exhibition ( id BIGINT AUTO_INCREMENT PRIMARY KEY, title VARCHAR(100), theme VARCHAR(200), start_date DATE, end_date DATE, location VARCHAR(100), status TINYINT, created_by BIGINT ); CREATE TABLE exhibition_exhibit ( id BIGINT AUTO_INCREMENT PRIMARY KEY, exhibition_id BIGINT, exhibit_id BIGINT, sort_order INT );sort_order这个字段很多简单实现会忽略掉。但线上虚拟展厅或者按序布展时列表顺序直接决定展示的先后逻辑。如果一开始没有这个字段后面想调顺序就得把关联表删了重建非常麻烦。3.3 预约表与用户角色表的处理预约表记录人和展览、参观日期之间的关系。字段包括预约人ID、预约的展览ID或展品ID、参观日期、人数、联系电话、状态、创建时间。预约状态我用数字枚举0待审核、1已确认、2已取消、3已参观。预约这类订单型数据有一个原则尽量不物理删除只改状态。游客和馆员都需要看到历史预约记录删掉一条记录会让前端的时间线和后台的统计数据变得不连续。如果实在担心表膨胀可以加一个deleted逻辑删除字段查询时统一过滤掉。用户和角色的设计我用的是经典三表结构user表、role表、user_role关联表。用户表存用户名、密码、昵称、手机号、头像、创建时间密码字段存BCrypt加密后的密文绝对不存明文。登录成功后后端签发JWTJWT里带上用户ID和角色ID后续接口就靠token来识别身份。3.4 索引与时间字段的细节数据库字段设计完成后要顺手把索引建好。根据查询场景我在exhibit_code上加唯一索引在exhibit表的name字段上建普通索引在预约表的visit_date和status上建联合索引。这样前台模糊搜索、后台按审核状态列表页的SQL都能走到索引。时间字段我统一用DATETIME前端传来的是标准日期时间字符串MyBatis映射成LocalDateTime序列化后返回给前端也是标准格式。避免用VARCHAR存时间否则后面做日期筛选、统计报表时还得挨个做类型转换纯属给自己找麻烦。4. 后端实现登录鉴权、动态查询与图片上传的关键代码4.1 基于JWT的登录与权限拦截登录接口的逻辑不复杂接收用户名和密码用BCrypt的matches方法校验密码校验通过后生成JWT返回给前端。JWT载荷里放userId和role过期时间我设置的24小时。前端拿到后保存在localStorage之后每个请求都在Authorization请求头里带上这个token。后端用一个拦截器来统一鉴权。拦截器实现HandlerInterceptor接口在preHandle方法里解析token。如果token缺失或过期直接返回统一结构的401错误。重点是配置白名单游客不需要登录就能访问首页列表、展品详情等接口登录、注册接口也不能拦截否则用户根本进不了系统。我在WebMvcConfigurer里通过excludePathPatterns来管理白名单思路比代码本身更重要。这里的三个细节要特别留意一是后端要开跨域配置二是管理端接口要额外校验角色不能只校验是否登录三是拦截器放行和拦截的路径要写清楚避免出现游客能访问后台管理接口的漏洞。4.2 展品分页检索与MyBatis动态SQL展品列表是整套系统出场率最高的接口。前端支持按关键字、按年代、按分类、按状态进行组合筛选。MyBatis的XML配置文件里核心就是动态SQL标签select idselectExhibitPage resultTypecom.example.museum.entity.Exhibit SELECT * FROM exhibit where if testkeyword ! null and keyword ! AND name LIKE CONCAT(%, #{keyword}, %) /if if testdynasty ! null and dynasty ! AND dynasty #{dynasty} /if if testcategory ! null and category ! AND category #{category} /if if teststatus ! null AND status #{status} /if /where ORDER BY create_time DESC LIMIT #{offset}, #{pageSize} /select这里有两个点几乎每次答辩都会被问到。第一 标签会自动处理条件前面的AND比老代码里常见的WHERE 11干净得多。虽然结果一样但阅读体验和专业感完全两回事。第二模糊查询用CONCAT(%, #{keyword}, %)而不是%${keyword}%。#{}是预编译参数安全${}是字符串拼接存在SQL注入风险。这一点必须记住不能图省事。4.3 图片上传与静态资源映射文物图片上传的做法是后端接收MultipartFile先检查文件类型和后缀再限制大小然后生成一个新的文件名格式是UUID加原始扩展名。这样能避免中文名、重名和路径注入的问题。文件保存到服务器指定目录数据库里只存相对路径比如/images/2025/xx.jpg。开发环境里很多人习惯把图片存到项目源码的upload目录下。这样开发时没问题但服务器上打jar包重新部署target目录被清掉图片也没了。我第一次就是吃了这个亏后来统一改成服务器上的固定目录比如/usr/local/museum-images再在SpringBoot配置类里做静态资源映射把/images/**映射到该目录。图片和代码分离之后部署升级就安全了。4.4 统一返回结构与全局异常处理统一返回结构我定义成一个泛型类Result 包含code、message、data三个字段。Controller里所有接口都返回这个结构业务逻辑里预期的错误情况用不同的业务码区分数据库异常和兜底异常则交给全局异常处理器处理。使用RestControllerAdvice把参数校验异常、业务异常、系统异常分别捕获转换成统一格式返回。这样前端Axios拦截器里只需要判断一种返回结构弹错误提示时不用每个接口单独处理。优点是代码可读性和联调效率都高让错误信息变得可预测。5. 前端落地Vue路由、Axios封装与后台管理页5.1 工程创建与路由分级前端用Vite创建Vue 3工程配合Element Plus组件库。路由分为两层游客端页面挂在根路径下管理端页面全部挂在/admin下。管理端路由加meta元信息标记requiresAuth和role然后在路由守卫里统一判断。用户没登录或者角色不对直接重定向到登录页。路由模式方面如果工程最终部署时后端没有配置重写规则href模式在用户刷新页面时会404。我建议先使用createWebHashHistory演示起来最省心。等以后搭了Nginx再做重写规则切换到html5 history模式也不迟。5.2 Axios封装里的token与错误处理我建了一个request.js统一封装Axios实例。请求拦截器从localStorage取出token加到请求头里。响应拦截器判断返回体的codecode是200就放行让业务代码拿到datacode是其他值就弹错误提示如果是401就清空登录状态并跳转登录页。把这一步做好之后业务代码里不需要到处写try catch和弹窗只要关心自己的数据逻辑就行。我见过很多项目在每一个页面里重复书写token加载和错误弹窗代码量虚高且容易忘记某处统一封装是成本最低的优化。5.3 游客端的展品列表和详情页游客端首页是根据筛选条件展示的展品列表。我采用前端分页组件加后端分页接口的配合方式每次切换页码或筛选条件重新请求当前页数据。这种模式在几千条数据量下表现稳定代码也容易理解。页面加载时用Loading组件防止图片未加载前布局跳动数据为空时显示占位图不要让页面白屏。展品详情页根据路由参数里的展品唯一编号请求后端详情接口。页面布局包括主图、基本信息、简介以及关联的展览信息。如果有时间还可以加一个相关展品推荐根据分类字段拉取同类别展品提升浏览深度。5.4 管理端表单回显与上传交互后台管理页的核心是表格加弹窗表单。展品管理页面里表格展示展品缩略图、名称、年代、分类、状态编辑按钮打开弹窗弹窗里回显当前数据。这里最需要留意的是提交时的数据范围把列表接口返回的createTime、updateTime等字段一起回传可能会在更新时覆盖掉数据库中的正确时间。图片上传的交互也要设计成选择图片时立即上传保存表单时只提交URL。如果反过来用户填了很长时间的表单最后保存时才上传图片一旦网络波动导致上传失败所有表单数据都要重新填体验非常糟糕。先上传拿URL、再提交表单才是正常做法。管理端的展览管理页面和预约管理页面逻辑类似区别在表单和表格列不同。预约管理页需要有一个审核操作把预约状态从待审核改成已确认或已取消这个操作调后端的一个状态更新接口即可。6. 联调和部署跨域、Long精度、打包这三大坑6.1 跨域问题处理前后端分离后第一个遇到的几乎必然是跨域。后端在SpringBoot里配置CorsConfiguration允许指定源、指定请求头和指定方法前端开发服务器再配置代理把/api下的请求转发到后端端口两边都打通后本地联调基本不会再撞见浏览器拦截。这里给一个简单的后端配置思路Configuration public class CorsConfig { Bean public CorsFilter corsFilter() { CorsConfiguration config new CorsConfiguration(); config.addAllowedOriginPattern(*); config.addAllowedHeader(*); config.addAllowedMethod(*); UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/**, config); return new CorsFilter(source); } }生产环境如果前后端用Nginx统一入口同源部署就可以关掉或收紧这个配置。本地联调时宽松一点没关系上线前记得收紧。6.2 Long类型在JavaScript里的精度丢失另一个很少被新手提前注意的问题是后端返回的Long类型主键在JavaScript里可能精度丢失。Java的Long是64位前端Number是双精度浮点超过2的53次方的整数会被截断。平时数据量小没感觉等主键越来越大你会发现前端拿到详情ID后请求接口一直404。解决方案有两个一是后端把主键序列化成字符串返回二是前端请求详情时尽量用exhibitCode这类字符串编号而不是数字主键。我建议两个方向都做省心也确实能避免奇怪的线上问题。6.3 MyBatis驼峰映射与列名对不上MyBatis默认不会把数据库的create_time自动映射成Java属性createTime。第一次跑通接口前端拿回来的createTime一直是null检查了半天才发现是映射问题。解决办法很简单在application.yml里开启驼峰映射mybatis: configuration: map-underscore-to-camel-case: true如果不开启就只能每个查询都写resultMap手动映射字段一旦表结构调整resultMap也得同步改维护成本明显高。我建议优先开启驼峰映射除非你真的需要把数据库列名和Java属性名设计成不一样。6.4 打包部署的两种方式部署方案有两个选择。第一种是前后端分开部署后端打成jar包前端打包成dist后放到Nginx静态目录Nginx把/api反向代理到后端端口。这样做的好处是发布时互不影响以后要做后端多实例扩展也方便。第二种是合并部署把前端dist下的所有文件复制到SpringBoot的src/main/resources/static目录重新打一个jar包一条命令启动jar就能同时提供页面和接口。这种方案适合单机演示和交作业简单可靠不需要额外装Nginx。如果只是自己本地演示我建议先走合并部署减少环境变量带来的不确定因素。如果是多人使用的线上环境建议走前后端分离加Nginx运维更灵活。7. 一些源码之外的思考预置数据与后续扩展7.1 演示数据为什么重要很多人在交项目之前数据库里几乎是空的。一打开前端首页列表是空白后台管理也是空白给任何人的第一观感都不好。我在项目里预置了十几条馆藏数据包括青铜器、瓷器、书画三类再配一场古代青铜器特展的展览数据。游客端一进首页就有完整列表和详情管理端也有可以编辑、审核的真实数据演示效果立刻不一样。准备测试数据也是项目开发的一部分不是浪费时间。它能帮你提前发现SQL问题、渲染问题和接口异常还能让整个项目的完整度上一个台阶。7.2 这个项目还能往哪些方向扩展做完基础功能之后如果想继续深入有两条路值得走。一条是功能扩展比如加全文检索把文物名称和简介做成搜索引擎支持的索引或者加虚拟展厅用全景图展示展厅空间预约模块还能继续扩展二维码核销和短信通知。另一条是性能优化比如引入Redis缓存热门展品数据把列表查询压力从数据库转移到缓存层或者把图片存储切换到对象存储并配置CDN。从课程设计角度做到预约审核闭环已经可以交差了。从个人项目成长角度每次往这个系统里加一个新能力都会逼着你补一块新知识比重复写一百遍增删改查更有价值。