SpringBoot+Vue+MVC架构：文物征集管理系统从设计到部署全解析

做管理系统这么多年，SpringBoot + Vue 这套组合我搭过不少，但真正把 MVC 模式从头到尾理得特别清楚，是在做这套文物征集管理系统之后。技术栈没什么花哨的，就是 SpringBoot、Vue、MVC 模式、MyBatis 和 MySQL，从文物预征集登记到鉴定评估、入库归档，一条业务链路全部打通。前端负责页面交互，后端严格按 Controller-Service-Mapper 拆分，数据库用 MySQL 承载，整个项目从零到落地跑完，无论是业务方还是开发的同事，都觉得这套结构是清晰且好维护的。这篇文章我就按真实项目的推进顺序，把架构设计、表结构、核心代码、联调部署和踩坑记录完整摊开来讲，给正准备做管理类系统、或者对这套技术栈还不够顺手的开发者，提供一个能直接参考的范本。

1. 项目选型与整体架构设计

1.1 为什么锁定 SpringBoot + Vue + MVC 这套组合

文物征集管理系统是典型的 CRUD 密集型业务系统，最怕的不是业务有多复杂，而是开发效率低和后期不好维护。我选 SpringBoot 做后端基座，核心原因是它把 Spring 的配置压力降到了极低，内嵌 Tomcat，一个 jar 包能直接跑，配合 Maven 管理依赖，几乎不用操心外部容器部署的问题。Vue 负责前端，页面组件化以后，像征集登记表单、鉴定评估列表、归档台账这类页面写一次就能复用，配合 Vue Router 做页面路由，整体开发速度比传统 JSP 时代快了好几个量级。

MVC 模式在这个项目里不是老生常谈的教条，而是真正解决了协作问题。在前后端分离的背景下，传统 MVC 里的 View 被 Vue 接管，但 Controller-Service-Model 的骨架依然清晰存在：Controller 只做参数接收和响应封装，Service 承载业务逻辑，Mapper 层跟数据库打交道，模型对象在 Entity、DTO、VO 之间做边界隔离。这样分的核心好处是业务变更时能精准定位改动点，比如征集鉴定规则调整，只需要动 Service 层的逻辑，Controller 和 Mapper 层基本不动，测试回归范围能控制在一个很小的圈子里。

MyBatis 和 MySQL 则是数据侧的黄金搭档。MyBatis 上手快，SQL 完全由自己掌控，适合文物征集这种存在大量动态条件查询的场景；MySQL 作为开源关系型数据库，部署成本低，事务能力可靠，对中小型管理系统的读写压力完全够用。整条技术链路没有特别新奇的东西，但每一环都能说清楚为什么用它，这比盲目追新重要得多。实际开发里我也见过强行上微服务、引入各种中间件的管理系统，最后没有人能维护，反而是这种朴素务实的组合最能出活。

1.2 业务模块与系统边界划分

文物征集管理系统不是一个花哨的系统，但业务链条比较长。我把整个流程拆成五个核心模块，每个模块在前端和后端都有明确的对应关系：

这五个模块之间不是孤立存在的。预征集登记通过文物编号关联到鉴定评估，鉴定结论为通过之后才能触发入库操作，入库完成自动生成档案记录。这种状态流转如果放在 Controller 层，代码很快就会变乱，所以我把状态机校验放进 Service 层，每个状态变更都强制校验前置状态，比如未鉴定通过的文物不允许入库，用一段简单的状态判断就能守住。

设计边界的时候我也踩过一些坑。最初想在一个 Controller 里把所有查询接口都堆进去，后来发现征集登记、鉴定评估、入库管理三个模块都要查询文物基本信息，接口复用变成接口纠缠。后来统一抽了一个文物基础信息查询接口，各模块按需调用，配合后端的 DTO 做字段裁剪，前端拿到的数据不会多也不会缺。边界划分的原则就一句话：模块之间通过接口通信，开发的时候能独立并行推进，出了问题也能快速定位到具体模块，而不是在几百行的 Controller 里到处找。

2. 数据库表设计与 MyBatis 核心配置

2.1 MySQL 表结构设计的几个关键决策

数据库是整个系统的地基。文物征集涉及的信息维度多，包括文物本体信息、征集来源信息、鉴定信息和图片附件，如果全部塞进一张表，后期查询和维护都是噩梦。我做的是主表加子表加关联表的拆分方案。

主表叫 rel_artifact，存文物的核心属性：文物编号、名称、年代、质地、尺寸、来源类型（捐赠、移交、收购）、征集状态、登记人、登记时间。子表 rel_artifact_detail 存扩展描述，像纹饰特征、保存状况、流传经过这种大字段；rel_appraise 存鉴定记录，一个文物可能有多条鉴定意见；rel_attachment 存图片和扫描件路径，一对多关联。

CREATE TABLE rel_artifact ( id BIGINT PRIMARY KEY AUTO_INCREMENT, artifact_no VARCHAR(32) NOT NULL COMMENT '文物编号', name VARCHAR(128) NOT NULL COMMENT '文物名称', era VARCHAR(64) COMMENT '年代', material_type VARCHAR(32) COMMENT '材质类型', dimensions VARCHAR(128) COMMENT '尺寸', source_type TINYINT COMMENT '来源类型 1捐赠 2移交 3收购', status TINYINT DEFAULT 0 COMMENT '状态 0预登记 1待鉴定 2已鉴定 3已入库', registrant VARCHAR(64) COMMENT '登记人', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文物征集主表';

几个设计细节值得单独说。第一，status 状态字段用 TINYINT 而不是字符串，减少存储占用，也方便 Java 侧用枚举映射，前端显示文本由后端统一转换成字典值，不要在前端写死下拉选项。第二，create_time 和 update_time 使用 MySQL 的默认值机制，业务代码里不用手动维护时间，避免多台服务器时间不一致导致的数据错乱。第三，每张子表都带上主表 id 作为逻辑关联，但不建物理外键约束，原因是后期做数据迁移和批量导入时物理外键会拖慢效率，有效性靠应用层的业务规则保证，这在绝大多数管理系统中是常见的取舍。

除了主表和子表，还要单独提一下征集计划表 rel_plan。它跟文物表是多对多的关系，一个计划征集多件文物，一件文物也可以出现在多个征集计划里，所以需要关联表 rel_plan_artifact 来解耦。多对多关系如果不用关联表，直接在主表里加一个 plan_ids 字段存逗号分隔的 id，查询和统计时会非常痛苦，这个坑我见过太多次了。

2.2 MyBatis 全局配置与动态 SQL

MyBatis 在 SpringBoot 项目里的使用，先要在 pom.xml 引入依赖，推荐用 mybatis-spring-boot-starter，版本要跟 SpringBoot 版本匹配，不然会出现自动配置失效的问题。配完依赖之后，在 application.yml 里设置 Mapper XML 路径和驼峰映射：

mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.artifact.entity configuration: map-underscore-to-camel-case: true cache-enabled: false

map-underscore-to-camel-case 这个开关一定要开，它是数据库下划线字段跟 Java 驼峰属性自动映射的关键，不开的话每个字段都要手动写 resultMap，效率低还容易漏。cache-enabled 我默认关掉，因为文物征集管理系统的数据一致性要求高，一二级缓存如果配置不当容易出现脏读，让 MyBatis 只做 SQL 映射器，缓存交给业务层按需控制更稳妥，这个选择后续会细讲。

动态 SQL 是这个项目里用得最频繁的特性。征集档案检索页有文物名称、年代、材质、来源方式、征集状态五个条件，用户可能只填其中几个，前端传参不确定，MyBatis 的<where>和<if>标签完美解决了这个问题。举个例子，文物列表检索：

<select id="selectArtifactList" resultType="com.artifact.entity.Artifact"> SELECT id, artifact_no, name, era, material_type, status, registrant, create_time FROM rel_artifact <where> <if test="name != null and name != ''"> AND name LIKE CONCAT('%', #{name}, '%') </if> <if test="era != null and era != ''"> AND era = #{era} </if> <if test="status != null"> AND status = #{status} </if> </where> ORDER BY create_time DESC </select>

动态 SQL 避免了在 Java 代码里拼字符串的丑陋写法，也防住了 SQL 注入风险，因为参数都走预处理占位符。实际开发中我建议把复杂查询都写进 XML，简单单表操作用注解，分工明确可读性也强。注意<where>标签会自动去掉第一个多余的 AND，这个小细节能省掉不少麻烦。

2.3 多表关联查询与分页

文物列表页需要同时展示征集来源、鉴定状态这些关联信息，如果一张表一张表查再组装，代码量会爆炸。我的做法是在 Mapper XML 里写关联查询，一次性把需要的字段查出来，用 resultMap 映射到查询 VO。分页用 PageHelper 插件，引入依赖后一行 PageHelper.startPage() 就能完成物理分页，返回 PageInfo 里有 total、pageNum 这些分页数据，前端表格直接能用。

这里有一个经验之谈：分页查询一定要先 count 再 select，PageHelper 在 startPage 之后紧跟的第一条查询语句才会被分页拦截，如果中间插了其他 SQL，分页数据就会错乱。另外，关联查询字段多的时候，select 的列尽量只查页面需要的，别贪多查全表字段，不然数据量上来之后即使分页了，传输和映射的损耗也会拖慢接口响应。做这类系统，数据库侧多花一点心思，应用侧就能少做很多无谓的优化。

3. SpringBoot 后端核心实现细节

3.1 Controller-Service-Mapper 三层代码落地

后端代码按三层结构组织，我先说 Controller 层。Controller 只做三件事：接收前端参数、调用 Service、封装统一响应。以文物预征集登记接口为例，前端传来的是 preRegisterForm 对象，Controller 里直接接收这个 DTO：

@RestController @RequestMapping("/api/artifact") public class ArtifactController { @Resource private ArtifactService artifactService; @PostMapping("/preRegister") public Result<String> preRegister(@RequestBody @Valid ArtifactRegisterDTO dto) { String artifactNo = artifactService.preRegister(dto); return Result.success(artifactNo); } }

这里有几个关键点。第一，接口统一返回 Result 对象，里面包含 code、message、data 三个字段，前端通过 code 判断业务是否成功，而不是依赖 HTTP 状态码，这样业务异常和系统异常能分开处理，前端拦截器也好统一处理。第二，@Valid 注解配合 DTO 里的字段校验注解，比如 @NotBlank、@Size，在进入 Service 之前就把非法参数拦下来，避免 Service 层写一堆 if else 判空。第三，DTO 跟 Entity 严格分离，前端传过来的对象不能直接拿来操作数据库，这是防止越权字段注入的基本手段。

Service 层是业务逻辑的核心。preRegister 要做的事情包括：生成文物编号、校验登记信息是否完整、判断征集计划是否存在并关联、插入主表和子表。编号生成规则我设计成“年份+模块缩写+当天流水号”，比如 2025-ZJ-0001，用数据库乐观锁加时间戳兜底，保证并发场景下的唯一性。整体逻辑虽然不复杂，但从 Controller 到 Service 再到 Mapper 的调用链很清晰，每个方法只干自己该干的事。

Mapper 层就比较简单了，一个接口加一个 XML 文件。这里要特别说一个规范：Mapper 接口方法名跟 XML 里的 id 必须一一对应，参数用 @Param 注解显式命名，这样 XML 里引用参数时不会因为编译器混淆而踩坑。多人协作时，如果 Mapper 方法命名随意，XML 里写错一个 id 启动就报错，排查起来虽然不难，但会打断开发节奏。

3.2 事务管理与状态流转控制

文物征集入库是一个典型的需要事务保护的场景。入库操作涉及多个动作：更新文物主表状态为已入库、插入库位分配记录、生成档案基础信息，任何一个环节失败，前面做了一半的变更必须回滚。SpringBoot 里加一个 @Transactional 注解就能解决，但要注意使用位置和生效条件。

我在入库 Service 方法的 public 方法上加 @Transactional，因为 Spring 默认只对 public 方法生效，而且通过代理机制拦截，同类内部方法之间的调用不会触发事务代理，这是很多人趟过的坑。还有一个容易被忽略的点：事务方法内部不要自己捕获异常后吞掉，要让 RuntimeException 向外抛，事务拦截器才能感知并回滚。如果确实要处理异常，记得手动对事务状态做一个回滚标记，不然数据就悄悄不一致了。

状态流转控制我单独抽了一个状态枚举，ArtifactStatus 定义了预登记、待鉴定、已鉴定、已入库、已退档几种状态，每个业务方法里先校验前置状态再更新。这种显式的状态机写起来有点啰嗦，但好处是流程不会被绕过去，比如征集人员不能绕过鉴定直接入库，这在业务上是底线。实际开发中我还加了一个状态变更流水表，每次状态切换都记录操作人和时间，方便后期追溯，出了争议数据也能快速定位。

3.3 文件上传与静态资源处理

文物征集系统离不开图片和扫描件，预登记时要上传文物照片，鉴定时可能要传专家意见扫描件。后端接收 MultipartFile，保存到服务器本地目录，数据库只存相对路径，这是最简单也最稳的方案。

SpringBoot 默认有个文件大小限制，multipart.max-file-size 默认只有 1MB，这在业务场景下完全不够用，我在配置里放开到了 20MB，同时限制图片格式和单个文件大小。经验之谈：文件上传接口要单独设定合理超时时间，图片处理如果还要做缩略图，建议加图像处理组件做压缩，不然上传几百张原图存储压力会很明显。更完整的方案是接 MinIO 对象存储，把文件从服务器本地挪到独立存储服务里，通过预签名 URL 做访问控制，我在这个项目里也做了 MinIO 的接入改造，本地磁盘方案只用来兜底。做管理系统的都知道，文件存储这种事前期不规划好，后期迁移数据时真的想哭。

4. Vue 前端界面与前后端联调

4.1 前端工程化与目录组织

前端我用 Vue CLI 加 Vue 2 这套栈，考虑到这套系统需要兼容老浏览器环境。项目初始化后，我先做目录规划，src 下面分 api、views、components、router、store 几个目录。api 目录负责所有接口调用，每个模块一个文件；views 放页面组件，按业务模块建子目录；components 放可复用组件，比如通用列表、通用弹窗、图片上传。

Vue 环境配置上，Node 和 npm 装好之后，创建项目、安装依赖这两步其实有不少坑。npm 源如果不是镜像源，装依赖会慢到怀疑人生，所以第一步就是切换镜像源。项目跑起来之后，开发环境的跨域问题用 vue.config.js 里的 devServer.proxy 解决，把 /api 前缀的请求代理到后端地址，这样前端开发时不需要后端开启对所有人开放的 CORS，更安全也更干净。

路由设计我用了静态路由加菜单映射。每个业务模块的路由配置带 meta 信息，里面存菜单标题和权限标识，侧边栏菜单根据路由配置自动生成。权限控制在后端接口层做最终校验，前端只是控制入口的展示，这是前后端分离项目里比较合理的权限分工。前端藏起来不等于没有权限，后端不校验接口权限才是大忌，这一点团队里新同学最容易理解反。

4.2 核心页面与组件复用

征集登记页是整个系统最复杂的一个页面。表单字段多、校验规则复杂，还要支持动态添加鉴定记录。我把它拆成了基础信息表单、来源信息表单、鉴定记录列表三个子组件，父组件负责整体提交和进度管理。这里用到了 v-model 和 props 向下传、事件向上抛的通信机制，组件之间通过 props 和 $emit 通信，没有引入复杂的状态管理，因为页面之间需要共享的数据并不多，强行上 Vuex 反而增加理解成本。

列表页的设计更讲究。文物列表、征集计划列表、入库台账列表长得都很像，都有搜索条件区、数据表格、分页器、操作按钮，这种高度相似的功能，我抽了一个通用列表组件，传入搜索字段配置和表格列配置就能生成一个完整的列表页。组件化的好处在这个场景体现得非常直接：新增一个业务模块的列表页，只需要写配置文件，不用复制粘贴页面代码，后期维护起来也轻松。

4.3 Vue Router 与数据请求的工程化处理

Vue Router 配置里我用了 hash 模式，部署到 Nginx 不需要额外配置服务端回退，虽然 URL 里带个 # 号不太好看，但省心。如果业务上必须清理 URL 里的 # 号，就换 history 模式，同步在 Nginx 里配置 try_files 回退到 index.html，二选一即可，别混着用。

axios 封装是前端工程化的标配：实例的 baseURL 设成 /api，请求拦截器统一加 token，响应拦截器统一处理 code 非 200 的情况，弹出错误提示，code 是 401 时跳转登录页。接口定义不要散落在页面里，我在 api/artifact.js 里统一导出函数，页面组件只调用这些封装好的函数，后端接口变了只改一个文件，全局生效。数据请求组件卸载时要取消挂起的请求，防止页面切换后状态更新报错，这个细节在快速切换列表页、详情页时很重要，不然控制台会刷出一堆无意义的报错。

5. 关键流程联调与部署

5.1 前后端联调流程安排

联调阶段最怕的是接口对不上，字段名、类型、枚举值、嵌套结构，任何一个地方不一致，页面就跑不通。我一般会在后端接口自测通过后，先整理一份简短的接口文档，字段名、类型、成功失败返回结构都写清楚，前端按文档联调。通用 Result 结构和分页 PageInfo 的字段约定是联调的第一步，这两个基础形状不对，后面所有接口都要返工，所以建议项目启动第一天就定好。

实际联调中，GET 请求的参数传递、POST 的 JSON 结构、文件上传的 form-data 格式，这三个最容易出问题。我习惯在后端启动日志里打印请求入参，前端出问题时先看请求是否发对，再看后端日志是否收到，通过这种方式快速定位是前端参数拼错还是后端处理出错。CORS 和代理配置就位之后，大部分联调问题都能在前半程解决，剩下的基本是字段语义的理解偏差，所以接口文档里每个字段的注释要写清楚，别嫌麻烦。

5.2 打包部署与 Nginx 配置

SpringBoot 后端打成可执行 jar 包，前端 Vue 项目执行 build 生成静态文件。部署我采用两个方案：小规模场景直接用 SpringBoot 内嵌的静态资源目录把前端 dist 文件复制进去，一个 jar 包管完，简单方便；正式环境用 Nginx 托管前端静态文件，反向代理 /api 请求到后端服务，静态资源交给 Nginx 处理，性能更高也更灵活。

Nginx 配置里几个关键项：location / 匹配前端资源，location /api/ 做反向代理，同时把 Host 和 X-Real-IP 这些 header 带上，不然后端拿不到真实客户端 IP。部署后记得检查后端日志是否有跨域相关报错，前后端同域部署的情况下一般不会有，但如果是分开部署就得确认 CORS 配置和服务端代理是否生效。另外，jar 包部署时建议写一个简单的启动脚本，设置 JVM 内存参数和日志输出路径，不然进程挂了都不知道去哪看日志。

6. 高频问题与避坑实录

6.1 MyBatis 最容易踩的四个坑

第一个是缓存问题。我在这个项目里默认关了二级缓存，但还是看到有人喜欢把常用的查询配置成二级缓存，结果数据更新后其他会话还在读旧数据。MyBatis 二级缓存在多表查询下很难保证一致性，管理系统的数据准确性优先级最高，所以我建议默认关闭，需要提速的场景优先在数据库层优化，比如建索引、优化 SQL，而不是依赖缓存掩盖问题。

第二个是 N+1 查询。列表页初始化时查询文物列表，循环里又去查每件文物的鉴定记录，数据量一上来就触发 N+1。减少这种问题的方式是批量查询，比如 where id in (...) 然后把结果组装成 Map，代码里做内存关联，SQL 次数从 N+1 降成 2 次，效率提升非常明显。排查这类问题，可以在 MyBatis 配置里打开 SQL 日志，看有没有规律性的重复查询语句。

第三个是 TypeHandler 类型转换。MySQL 里一些特殊类型比如枚举、日期在 Java 侧的映射，默认 TypeHandler 可能处理不了。我处理方式是在配置里注册自定义 TypeHandler，或者干脆在 SQL 层面转换，不要在图省事的时候用 resultType 直接接收 Object，后面处理数据的时候类型转换错误会非常头疼。

第四个是 XML 里的特殊字符。小于号、大于号在 XML 文件里会被解析器拦截，动态 SQL 里做范围判断时必须写成<和>，或者用<![CDATA[]]>包起来。这个坑看着小，实际遇到的时候排查起来比较费神，因为报错信息不一定直接指向那一行。

6.2 MySQL 连接层的典型报错

MySQL 8.x 版本默认的认证插件是 caching_sha2_password，如果 JDBC 驱动版本太旧，启动 SpringBoot 项目时就会报连接失败。经验之谈：项目里统一用 MySQL Connector/J 8.x 以上版本，驱动类用 com.mysql.cj.jdbc.Driver，连接串里带上 serverTimezone=Asia/Shanghai 和 useSSL=false 两个参数，前者解决时区报错，后者杜绝证书验证失败。

MySQL 服务端时区设置也很关键。数据库和 JVM 时区不一致会导致时间字段差 8 小时，这种问题特别隐蔽，业务数据量大的时候很难发现偏移。我在连接串里显式指定 serverTimezone，同时在 MySQL 服务端设置系统时区为东八区，双保险。还有一个常见问题是数据库账号授权范围，localhost 和%要区分清楚，后端服务器连接数据库时账号权限不足会在启动阶段才爆出来，排查起来比较绕，建议建账号时直接确认好权限。

6.3 SpringBoot 版本与依赖兼容

SpringBoot 版本真的不是越高越好。这个项目里我选的是稳定度高的 2.7.x 系列，配合对应的 MyBatis starter 和 PageHelper 依赖，整体兼容性没出大问题。SpringBoot 3.x 项目要求 Java 17+，部分老依赖的包名都变了，迁移成本很高，如果团队对生态还不太熟，贸然上新版本很容易把自己卡住。

启动慢或者端口被占用这类问题也要留意。内嵌 Tomcat 默认端口 8080，被占用时会报端口冲突，用 --server.port 参数或者配置文件改掉就好。JVM 内存不充足时，打包的 jar 可能启动几秒就挂了，查看日志会发现 OutOfMemoryError，给部署环境预留足够的堆内存，这类问题能提前规避。

6.4 Vue 侧的开发体验优化

Vue 开发中让我最难受的是依赖安装和路由模式。镜像源切换成镜像之后，npm install 的体验会好很多，装依赖的时间从十几分钟降到一两分钟，开发效率提升立竿见影。Router 的 history 模式和 hash 模式的选择，前面提到用 hash 模式省事，但如果业务上必须清理 URL 里的 # 号，就用 history 模式，同步在 Nginx 里配置 try_files 回退到 index.html。

另外一个高频报错是“Cannot find module”，大部分是因为 node_modules 没装全或者版本不一致，删除 node_modules 和 package-lock.json 重新 install 一般能解决。组件开发时注意 props 不要直接修改，Vue 的单项数据流机制下，直接在子组件里改 props 的值，控制台会报警告，而且行为不可预期，正确做法是子组件用 data 或 computed 承接 props 值再操作。还有一件事，多人协作时 node 版本尽量统一，不然同一个项目在不同机器上表现可能不一样，这种问题排查起来非常浪费时间。

7. 一点个人总结与后续计划

项目做到这里，主干流程已经完整跑通，从文物征集的线索录入、鉴定评估，到入库归档、检索统计，SpringBoot、Vue、MyBatis、MySQL 这套组合在这个场景里表现得非常稳定。我做这类系统最大的体会是：技术选型别贪新，业务建模别图快，把状态流转和表结构这两块地基打牢，后面所有功能都顺了。如果你正准备做类似的征集管理系统，我建议第一版先把征集登记、鉴定评估、入库归档这条主干流程跑通，别急着堆砌复杂报表和精细化权限，二期再迭代也来得及。数据库脚本和核心模块的代码我正在整理，之后会单独发一版补充分享，也欢迎大家在实际开发中遇到类似问题来找我讨论。