全套SpringBoot+Vue中药实验管理系统，从数据表到权限控制一篇讲透
去年实验室要上一套中药实验管理系统，老台账登记方式实在撑不住了——实验方案写在纸质本上，药材领用记录在Excel里，报告存档又散落在各台电脑中。要做一份汇总统计，得翻半天文件夹。后来我们几个人花了三周时间，从零搭了一套SpringBoot+Vue的前后端分离系统，把实验方案、药材库存、实验记录、报告审核这些环节全部串成了一个闭环。
这套系统做完之后，不少同学问我要源码和设计思路，干脆写成这篇拆解文档，把数据库设计、接口文档、权限控制、前后端对接、部署运行全部讲清楚。如果你正在做Java Web方向的项目，或者想找一份能直接参考复现的SpringBoot+Vue全栈案例，这篇文章刚好适合你。思路是通用的，代码结构可以直接拿来改。
1. 项目背景与需求分析
1.1 中药实验管理的业务痛点
先说说为什么需要这样一套系统。中药实验和普通实验室管理不太一样，它的核心流程是：确定实验目的、编写实验方案、采购或者领用药材、执行煎煮或提取操作、记录实验数据、出报告、再由负责人审核归档。整个链条涉及的角色不止一个人，数据形态也很杂，有方案文字、药材批次信息、工艺参数、实验结果表格、报告附件，等等。
在没有系统之前，最常见的状态就是实验员A手写方案，实验员B拿着方案去库房领药，库房登记一本台账，实验过程中数据记在个人记录本上，最后整理报告时再汇总成Word。这样的流程有三个明显的问题：
一是数据孤岛非常严重。药材消耗了多少、哪个批次用得最快、某类实验结果统计，这些数据散落在不同人手里，根本无法快速汇总。
二是规范性没法保证。实验操作步骤是否按方案执行、原始记录是否完整可追溯，这些审计要求难以落地，报告出了偏差也难以复盘定位。
三是审批和状态流转基本靠人肉提醒。谁提交了报告、谁没审核、审核被打回的原因是什么，全靠口头沟通，效率极低。
我们在需求阶段和实验室负责人反复沟通后，把核心目标定成：建立一套以"实验方案"为起点、以"实验记录"为核心、以"报告审核"为结果闭环的完整流程管理系统。同时把药材库存纳入管理，做到每个方案的药材消耗可回溯，每一份实验记录提交后不可随意修改。
1.2 系统角色与核心业务流程
这套系统的用户角色不复杂，按实际工作分工划分成三类：系统管理员、实验负责人、普通实验员。
系统管理员负责用户管理、角色权限配置、基础数据维护，比如药材分类、单位信息、操作工艺选项这些基础字典。
实验负责人是业务的核心把关人，负责审批实验方案、审核实验报告、抽查实验记录。当实验方案的状态需要变更，比如从"草稿"改为"进行中"或者"已结束"的时候，也需要负责人来确认。
普通实验员的工作内容最多，包括新建实验方案、申请领用药材、录入实验过程中的观察数据和测量数据、上传原始记录附件、提交实验报告。
业务流程可以压缩成三步来看。第一步是实验立项阶段，实验员填写方案并提交，负责人审批通过后，方案状态变为"已通过"，系统自动生成一条实验任务。第二步是执行与记录阶段，实验员在任务下填写每一次实验操作的记录数据，包括药材批次、操作日期、工艺参数、观察结果，同时关联从库房领取的药材批次，系统自动扣减库存。第三步是报告与归档阶段，实验员上传实验报告附件并提交审核，负责人通过后整个实验闭环完成，自动归档。
这里的核心逻辑是：方案必须先审后用，记录跟着任务走，报告的审核要绑定完整的过程数据。如果没有前置记录，报告不允许提交。这个设计可以从根本上避免"先写报告、后补数据"的造假问题。
2. 技术选型与整体架构设计
2.1 后端为何选SpringBoot
后端框架的选择在Java生态里其实没什么悬念。我们用的是SpringBoot 2.7 + JDK 8的组合，搭配MyBatis-Plus做数据访问，MySQL存储业务数据，Redis做缓存和Token管理，Swagger生成接口文档。
为什么选SpringBoot而不是传统的SpringMVC加一堆XML配置？对于这种以业务功能为主、开发周期偏短的项目来说，SpringBoot的自动配置能力能省掉大量环境搭建时间。以前配Spring的时候，数据源、事务管理器、视图解析器每一样都要手动写配置，现在一个spring-boot-starter-web依赖就全部搞定。内置Tomcat也让调试简单很多，本地启动直接运行main方法，不用再装一个外部服务器。
ORM这一层我们选了MyBatis-Plus，不是纯MyBatis。核心原因是我希望在SQL可控的前提下，尽量减少重复的CRUD代码。BaseMapper提供的基础增删改查方法，覆盖了大约六成以上的简单操作，剩下的联表查询和复杂统计才需要手写XML。在实验记录按条件分页查询、方案状态统计这些场景里，MyBatis的灵活注解和XML都能很好应对。
权限控制用Spring Security还是自定义拦截器？这是我们斟酌过的一个点。考虑到系统只有三种角色，权限维度也比较固定，最终选择用JWT加自定义拦截器的方式实现，没有上Spring Security的完整框架。理由很简单：Spring Security对很多人来说学习曲线陡，配置不当反而容易出安全漏洞，而一个基于拦截器和注解的自定义权限方案，在这个量级下更直观、更好排查问题。
2.2 前端为何选Vue
前端选型比较明确，用Vue 2.6 + Element UI + Vue Router + Vuex的组合。为什么不上Vue 3？坦白讲，这套项目落地的时候Vue 3生态虽然已经有了，但Element Plus、相关的周边库兼容性还没有完全稳定，而我们团队里多数人对Vue 2的选项式API更熟，开发效率更高。对于管理后台这类中后台项目来说，Vue 2的组件生态、社区方案都相当成熟，踩坑成本低。
Element UI帮了大忙。像表格、表单、日期选择器、分页组件、对话框这类中后台系统的"标准零件"，Element UI开箱即用，样式统一，基本不用额外调CSS。比如实验记录列表页面，核心就是el-table加上el-pagination，字段一绑定，数据一填充，页面就直接能用了。
状态管理选择Vuex，虽然很多人觉得Vuex模板代码多，但对于这个项目来说是值得的。登录用户的角色信息、权限标识、侧边栏菜单状态这些全局状态，多页面都要用，放在Vuex里可以避免组件间层层传递的麻烦。特别是路由守卫里，每次跳转都要读取用户角色信息来做权限判断，从Vuex读比从localStorage读语义更清晰，也方便做统一处理。
2.3 前后端分离架构与项目整体结构
前后端分离的核心思路是：前端只负责页面渲染和用户交互，后端只负责业务逻辑和数据处理，两者通过RESTful接口进行通信。这么做的好处很多，最重要的一点是两边可以并行开发互不阻塞。前端按接口文档先Mock数据，后端按接口文档提供真实接口，联调阶段统一替换。
后端项目的包结构按业务模块划分，入口类放在最外面统一扫描：
com.example.labmanage ├── controller // 接口层，只做参数接收和结果返回 ├── service // 业务逻辑层，处理核心业务 ├── mapper // 数据访问层，对应MyBatis的Mapper ├── entity // 实体类，与数据表字段一一对应 ├── dto // 传输对象，接收前端参数或扩展返回字段 ├── vo // 视图对象，按前端需要组装返回数据 ├── config // 配置类，包括跨域、拦截器、MyBatis-plus配置 ├── common // 公共工具类、统一返回结果、异常处理 ├── utils // 工具类，如JWT工具、时间处理工具 └── interceptor // 拦截器，Token验证与权限控制前端按功能模块组织，在src目录下分成api、views、router、store、components这几个目录。api目录按模块封装请求方法，views目录放页面组件，router统一配置路由，store放Vuex的modules。这里有一个值得记住的经验：api目录中封装的每一个请求方法，都要和后端Controller的接口路径一一对应，命名尽量统一，比如listExperimentPage对应的就是后端的/api/experiment/page，这样联调的时候对照接口文档找起来特别快。
3. 数据库设计与SQL脚本解读
3.1 核心数据表清单
整套系统一共设计了十到十一张核心表，按业务模块可以分成四组：权限用户组、实验管理组、药材管理组、公告与字典辅助组。
权限用户组包括用户表、角色表、用户角色关联表这三级。用户表存登录账号、密码、姓名、联系方式、状态等基本信息；角色表只有三条记录，对应管理员、实验负责人、实验员；用户角色关联表解决的是用户和角色的多对多关系，虽然当前业务里一个用户基本只对应一个角色，但保留多对多的结构，后续扩展会方便很多。
实验管理组是核心中的核心，包含实验方案表、实验记录表、实验报告表。方案表记录实验的名称、目的、操作步骤、状态、审批意见；记录表记录每次实验操作的详细过程数据；报告表关联方案，存报告附件路径和审核信息。
药材管理组包括药材信息表、药材出入库记录表。药材信息表维护药材名称、规格、生产批次、库存数量、有效期等属性；出入库记录表记录每一次库存变动的来源和去向，特别是要关联实验方案ID，做到"这一批药材用在了哪个实验"的追溯能力。
辅助表包括公告表和数据字典表。公告表用于发布实验室通知，数据字典表维护药材单位、实验类型、工艺类型等下拉选项，让前端下拉框的数据不用写死在代码里，管理员可以直接维护。
3.2 关键表结构设计详解
重点说三张核心表的结构设计思路。
用户表的核心字段是id、username、password、real_name、role_id、status。password存的是BCrypt加密后的密文，不是明文。注意，这里没有直接把角色字段冗余在用户表里，而是通过关联表去映射，虽然多一次join查询，但角色信息的扩展性更强。
实验方案表是流程的主线，字段设计要覆盖整个审批流程：
表名：experiment_plan id 主键 plan_no 方案编号，如SY202501001 title 实验名称 purpose 实验目的描述 procedure 实验操作步骤，用换行分隔存文本 type 实验类型，关联字典 status 状态，0草稿 1待审批 2已通过 3已驳回 4已结束 create_by 创建人ID create_time 创建时间 approve_by 审批人ID approve_time 审批时间 approve_comment 审批意见 deleted 逻辑删除标记方案编号这里做了一个细节设计：由前缀SY加年月日加当天自增序号组成，在插入记录时通过查询当天已有记录的最大序号再+1生成。这样做的好处是编号有规律可读，而且直接能在数据库层面实现，不需要额外引入生成策略。当然这个设计在并发高时有小概率序号重复，但在实验室内网这种低并发场景完全够用。
实验记录表的字段更能体现业务特点：
表名：experiment_record id 主键 plan_id 关联实验方案ID record_no 记录编号 record_date 实验日期 batch_no 药材批次号，关联药材 weight 药材用量 process_type 工艺类型，如煎煮、萃取、过滤 process_param 工艺参数，存json字符串 result_desc 观察结果描述 attachment_path 附件路径，原始记录照片或扫描件 create_by 记录人ID create_time 记录时间工艺参数用JSON字符串存储是刻意的。不同实验类型的工艺参数差异很大，煎煮实验需要记录温度时间，萃取实验需要记录溶剂种类和用量，如果每种实验建一张表，表数量会失控。JSON存灵活性最大，查询时即使需要过滤某些参数，也可以在业务层处理。这里牺牲了一点数据库层面的强约束，换来的是扩展性，要我说，对于实验记录类明细数据，这笔买卖划算。
药材出入库记录表设计了一个type字段区分入库和出库，并冗余了关联对象ID和关联类型，确保任何一条出入库记录都能找到对应的来源或去向。比如领药出库，关联对象ID就是实验方案ID，关联类型标记为"方案领用"；采购入库，关联对象ID就是采购单ID（如果有），关联类型标记为"采购入库"。这个设计让库存的每一次变动都有据可查。
3.3 数据表关系与流程状态设计
表间关系属于经典的"主表-明细表"结构。实验方案表是所有业务的聚合根，往下挂实验记录、实验报告、药材出库记录；药材表独立维护，但通过出库记录表和方案表建立关联；用户表贯穿所有表，因为每个业务表都需要记录操作人。
状态驱动整个流程，这是这个系统的一个重要设计思路。实验方案表用status字段驱动流程：草稿可以编辑修改，提交后变成待审批，负责人审批时只能选通过或驳回，通过后实验员才能填写记录和提交报告，驳回后方案必须修改重新提交。实现的时候，每个状态变更都做了前置状态校验，比如待审批状态下的方案不能被再次提交，已结束的方案不允许新增记录。状态校验的逻辑统一放在service层，返回统一的业务异常信息，前端捕获后弹出提示。
逻辑删除字段deleted几乎每张业务表都有，删除操作统一走update语句将deleted置为1，查询时通过MyBatis-Plus的逻辑删除机制自动过滤。为什么不用物理删除？因为实验数据涉及审计追溯，即便管理员删错了，也不能真正把记录抹掉，而是应该保留数据、只做标记，数据恢复也更方便。
4. 接口文档设计与认证授权机制
4.1 接口设计规范
接口文档在整个项目中的作用被严重低估了。只要前后端分开开发，接口文档就是两边沟通的契约。我们用Swagger自动生成接口文档，Controller里写好注解和实体类描述后，运行起来访问一个固定地址就能看到文档，不需要额外花时间维护Word。
接口路径设计遵循RESTful风格，统一以/api开头，按模块区分，然后按动作区分。比如/api/user/login是登录接口，/api/user/info是获取当前用户信息，/api/plan/page是实验方案分页查询，/api/record/add是新增实验记录，/api/report/audit是审核实验报告。
统一返回结构是接口设计中非常重要的约定。所有接口的返回值都封装在一个Result对象中，包含code、message、data三个字段。code为200表示成功，为500表示业务异常，为401表示未认证，为403表示无权限。前端axios拦截器统一处理这个结构：code为200时取data走正常逻辑，code为401时跳转登录页，其他code弹出message提示。这个约定前后端都要严格遵守，否则很容易出现"接口返回了、页面却没反应"的隐性Bug。
分页查询接口统一使用page、size、keyword三个参数，其中keyword按各模块的搜索需求替换成具体条件。返回数据结构统一为{records, total, current, size}，前端直接传给el-table和el-pagination就能渲染，不需要再做二次适配。
4.2 Token认证与权限控制
认证方案用的是JWT加自定义拦截器，流程是这样的：用户通过login接口提交用户名和密码，后端用BCrypt校验密码是否正确，校验通过后生成一个包含userId的Token，有效期设置为24小时，返回给前端。前端把Token存在localStorage里，之后每次请求都在Header中携带Authorization字段。
拦截器的处理策略是所有/api/**的请求都要经过Token校验（白名单除外），校验逻辑分三步：第一步从Header中取出Token，如果为空直接返回401；第二步解析Token并校验签名，解析失败或过期也返回401；第三步从Token中取出userId，查询出用户的完整信息和角色信息，放到ThreadLocal中，供后续业务代码随时获取当前用户。
权限控制的粒度在这个系统里做到了接口级别和按钮级别两层。接口级别通过自定义注解@RequirePermission("plan:audit")标记在Controller方法上，拦截器在Token校验通过后会继续校验注解指定的权限标识是否在用户的权限集合中。按钮级别则由前端控制，根据用户的权限列表决定页面上的审核按钮、删除按钮是否渲染。两层控制缺一不可，接口层面是真正的安全防线，页面按钮只是用户体验优化，绝对不能把前端隐藏按钮当作安全手段。
有一个细节值得提醒：Token过期时间不能设置太长。很多项目为了"省事"把Token有效期设成7天甚至30天，一旦过期时间的校验逻辑出现漏洞或者Token被截获，系统等于裸奔。24小时是一个相对合理的选择，配合前端在登录页做好"登录已过期"的提示，用户体验并不会有明显影响。
4.3 核心接口逻辑与示例
拿最关键的"提交实验记录"接口来拆解，能看出这套系统接口层面做了哪些事。
POST /api/record/add 请求体： { "planId": 21, "recordDate": "2025-01-15", "batchNo": "20250105-03", "weight": 15.0, "processType": "煎煮", "processParam": "{\"temperature\":100,\"duration\":45,\"waterVolume\":300}", "resultDesc": "药材煎煮30分钟后滤出药液，颜色棕黄，无明显沉淀。", "attachmentPath": "/upload/record/20250115_xxx.jpg" }后端处理的逻辑链路是：接收参数后先由@Validated做字段合法性校验，然后调用业务层。业务层第一件事是校验planId对应的方案状态必须是"已通过"，不是草稿也不是已结束；第二件事是根据batchNo查出药材信息，扣减库存，写一条出库记录；第三件事才是插入记录数据。这三步放在同一个事务里，任何一个环节失败都可以回滚，保证数据一致性。
为什么要把扣减库存放到记录提交这个动作里，而不是放到领药申请阶段？这是和实验室负责人反复确认后的决定。领药申请时减库存，容易出现在正式实验前药材被借用或者退回的混乱情况，改为在实验记录提交时扣库存，每一笔扣减都对应一次真实的实验操作，库存数据更贴近实际消耗。
统一返回这里体现得很清楚：
Result.success(recordId) // 返回新增记录的自增ID Result.error("500", "当前方案状态不允许新增记录") // 业务校验失败前端拿到Result后，只在code为200时刷新列表并关闭弹窗，其余情况一律提示message内容，不用再额外判断各种边界条件。
5. 前端页面与交互设计
5.1 页面结构与路由管理
前端页面按功能模块划分，一共有这些核心页面：登录页、系统首页、用户管理页、实验方案列表页、实验方案编辑页、实验记录页、药材管理页、库存流水页、报告审核页、公告页。
路由配置时按权限动态生成是一个比较重要的小技巧。登录完成后，前端拿到当前用户的角色和权限列表，然后根据权限列表动态的往路由表中添加可见路由。比如没有"计划审批"权限的用户，路由表中根本不存在审批页面，主动通过URL访问也会在路由守卫中被拦截。这个方案比单纯在页面里隐藏菜单更安全，也更符合"前端做体验优化、后端做真正安全控制"的原则。
路由守卫的逻辑分三段：第一段判断是否登录，没有Token就全部重定向到登录页；第二段判断当前路由是否需要权限，需要权限就校验本地权限列表；第三段判断是否需要拉取用户信息，用户信息还没加载时先发一个请求获取，避免刷新页面后Vuex里状态丢失导致权限判断失败。
5.2 核心功能页面的实现细节
实验方案列表页是最典型的Element UI表格页：顶部放搜索区，包括关键字输入框、状态下拉框、时间范围选择器，中间是数据表格，底部是分页组件。搜索条件发生变化后就重新调用分页接口，这个逻辑用一个watch可以统一搞定，注意不要每次搜索都新建一个列表组件实例，否则输入框失去焦点会特别影响体验。
实验方案编辑页的处理比列表页复杂，因为方案表单字段多，包含一个可以动态增删行的步骤列表。这里实现上有一个经验：步骤列表用"数组渲染加动态加减行"方案，新增一行时在数组中push一个空对象，删除一行时splice掉对应元素，表单提交时再把数组转成以换行分隔的纯文本。这样数据库存起来简单，页面操作也直观。
药材管理页有一个比较实用的联动效果：选择和查询药材时，表格按库存数量做视觉区分。当库存低于一个阈值（比如50克）时，这一行用红色标记显示"库存不足"标签。实现方式是前端拿到列表数据后进行遍历，如果stock字段小于预警阈值，就给数据行加一个特殊标记，el-table通过row-class-name的方法实现。
实验记录填写页里，附件上传是另一个值得说的点。我们是在前端用Element UI的el-upload组件，配置action指向后端的上传接口，上传成功后拿到返回的附件路径，把路径存到隐藏字段里，最后随表单一起提交。后端统一用固定配置处理上传文件，按日期分目录存储，防止同名文件互相覆盖。这个方式不复杂，却特别好用，比用FTP上传再手动填路径可靠得多。
5.3 按钮级权限控制实现
前面提到按钮级权限控制，这里把实现方式展开说一下。前端维护一份权限标识和页面按钮的映射关系，比如plan:audit对应"方案审批"按钮，record:add对应"新增记录"按钮，report:audit对应"报告审核"按钮。
在Vue里通过自定义指令实现按钮控制，指令内部检查当前用户的权限列表，没有权限时直接移除该按钮对应的DOM元素。模板里的写法：
<el-button v-if="hasPermission('plan:audit')" type="primary" @click="openAuditDialog">审批</el-button>也可以封装成一个公共方法，在按钮上统一调用。实际开发中我建议两种结合：简单的按钮用v-if加hasPermission方法，因为逻辑清晰便于调试；需要频繁出现的按钮（表格操作列的按钮）用自定义指令，代码更简洁。注意一个常见错误：不要只根据角色名称判断权限，比如"role === 'admin'就显示按钮"，一旦后续新增一个半权限角色或者角色重新分配，这种判断会全面失控。基于权限标识判断是最稳定的。
6. 系统部署与运行指南
6.1 环境准备与版本要求
一套系统要交付出去或者复现运行，环境版本的一致性至关重要。我建议按照这个清单来准备运行环境，亲测组合稳定：
| 组件 | 版本要求 | 说明 |
|---|---|---|
| JDK | 1.8及以上 | SpringBoot 2.7完全兼容JDK 8 |
| Maven | 3.6及以上 | 管理后端依赖 |
| MySQL | 5.7或8.0 | 注意8.0以上需要调整驱动配置 |
| Node.js | 14.x或16.x | Vue2项目的构建环境 |
| npm | 6.14及以上 | 前端依赖安装 |
MySQL版本这里有两个容易踩的坑：如果使用8.0，JDBC驱动要替换成com.mysql.cj.jdbc.Driver，并加上serverTimezone=Asia/Shanghai参数；如果使用5.7，则可以继续用老的驱动类名。项目里我建议直接在application.yml中按版本注释切换，运行前检查一次就好。
Redis不是必须的吗？坦白说，我们的JWT方案里没有强制依赖Redis，Token校验只做JWT签名解析，不依赖Redis存储会话。如果你想把"用户踢下线"之类的功能做得更强，可以用Redis做Token黑名单，但这不是本系统的必要运行条件。
6.2 数据库初始化与配置修改
拿到项目源码后，SQL脚本是整个系统正常运行的关键。初始化步骤是：
先创建数据库，建议字符集用utf8mb4而不是utf8，因为utf8mb4支持完整的Unicode字符，包括生僻汉字和特殊符号，中药名称里生僻字比较多，这里很重要。然后导入SQL脚本，脚本里包含了建表语句和初始数据，其中初始数据里有默认的管理员账号和密码。导入完成后再修改后端配置文件application.yml里的数据库连接，改成自己环境的IP和密码。
提醒一件事：SQL脚本里的默认密码是密文，不是明文，这是BCrypt加密后的字符串。如果你要修改初始密码，不要直接改数据库里的密文字段，而是用项目的工具类生成新密文再更新，或者注册一个新的管理员账号。直接写明文密码进去，登录时会校验失败，很多人第一次跑项目就在这卡住。
6.3 前后端启动步骤
后端启动非常简单，用IDEA打开项目，等待Maven下载完依赖，然后运行入口类的main方法即可。有一个细节要注意：IDEA中File Encoding检查一下，务必设置成UTF-8，因为前面提到JSON字符串、中文查询参数都依赖UTF-8编码，这个配置不对会出现中文乱码这种非常隐蔽的Bug。
前端启动分两步，先npm install装依赖，再npm run serve开启开发服务器。默认端口是8080，如果被人占用，修改vue.config.js或者package.json里的配置。启动成功后你会发现一个开发代理配置的问题：直接让前端请求后端接口会有跨域报错，开发环境下最优雅的解决方案是前端配置代理，把请求转发到后端端口，具体做法是在vue.config.js中设置devServer.proxy。生产环境下则完全不需要代理，因为前端静态资源会被Nginx托管，后端接口由Nginx反向代理转发，只需要在Nginx配置文件中设置转发规则。
6.4 生产环境打包发布
开发调试完成后的打包我按Linux服务器Nginx部署来写。
后端执行mvn clean package，生成的可执行JAR包直接上传到服务器，用java -jar命令启动。生产环境里不建议再打开Swagger文档，可以在配置文件中把Swagger关掉，避免信息泄露。要保证后端服务稳定运行，建议用Systemd写一个service文件管理进程，启动退出时自动重启。
前端构建执行npm run build，生成的dist目录是纯静态文件，放到Nginx的html目录下。Nginx配置里有一个关键点：前端路由使用的是历史模式（history模式），直接访问某个具体路由路径时Nginx会返回404，需要在Nginx中配置try_files，让所有请求都回退到index.html，由前端路由自己处理。这个配置不写的话，用户刷新列表页就直接白屏，项目上线时最容易在这里出问题。
location / { root /usr/share/nginx/html; index index.html index.htm; 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; }7. 实战中的常见问题与排查技巧
7.1 跨域问题排查
前后端分离项目里，跨域是碰到最多的报错之一。现象非常直观：浏览器控制台报"CORS policy"错误，接口一个都调不通。
这里我先明确一个观念：开发环境优先用前端代理，生产环境优先用Nginx反向代理，后端代码里写@CrossOrigin或者全局CORS配置反而属于最后的手段。为什么不推荐后端开CORS？因为CORS配置一旦放开就是所有接口都放开，容易引入安全隐患，而且调试时浏览器看到的请求路径还是8080，后端日志和前端请求对不上，排查效率低。
如果确认某些接口必须支持跨域调用（比如给外部系统提供开放接口），后端需要配置一个专门的CORS过滤器，只对需要开放的路径生效，允许的域名也要明确指定，不要直接用通配符。
7.2 时间格式与统一问题
前后端时间传递的坑几乎每个项目都会踩。我遇到过的情况是：前端传的日期格式是yyyy-MM-dd，后端用Date类型接收时报400；后端返回的日期经过序列化后变成了时间戳，前端没法直接展示；数据库存的日期比实际日期早了8小时等等。
解决思路是统一约定。所有接口参数里的日期，前端统一传yyyy-MM-dd HH:mm:ss字符串，后端的DTO对应字段使用@DateTimeFormat注解指定格式。实体类里的日期字段加上@JsonFormat注解，返回时统一格式。连接数据库的URL中配置serverTimezone为Asia/Shanghai。这四层约定统一后，时间问题基本就绝迹了。
7.3 常见报错与解决方案速查表
我把开发过程中遇到的高频问题整理成了一张速查表，直接给出快速定位思路：
| 报错信息 | 可能原因 | 处理方式 |
|---|---|---|
| 404 Not Found | 前端代理未配置 | 检查vue.config.js的proxy配置 |
| 404 Not Found | 后端Controller路径与前端不一致 | 对照Swagger文档检查路径 |
| 401 Unauthorized | 未携带Token或Token过期 | 检查localStorage是否有Token |
| 403 Forbidden | 权限不足 | 检查角色权限分配，必要时用管理员账号排查 |
| 500 Data too long | 字段长度超出数据库限制 | 检查实体字段长度注解 |
| Invalid bound statement | Mapper接口与XML不匹配 | 检查XML命名空间和方法ID |
| Unknown column | 实体字段与表字段不对应 | 开启MyBatis-Plus映射下划线转驼峰配置 |
| Refused to display | iframe嵌套页面被拦截 | 检查X-Frame-Options配置 |
| EADDRINUSE | 前端端口被占用 | 杀掉占用进程或修改启动端口 |
| npm ERR! code ERESOLVE | 依赖版本冲突 | 删除node_modules和lock文件重新install |
7.4 排查方法与调试技巧
开发过程中我养成了几个习惯，对排查问题特别有效：
第一个是接口日志打全。全局拦截器里把请求路径、参数、耗时、返回状态码统一记录下来，排查问题的时候直接搜请求路径，上下文一目了然。没有日志就只能靠前后端各自猜，效率极低。
第二个是数据库自动日志。MyBatis-Plus开启SQL日志打印，看到真实执行的SQL语句，很多业务逻辑问题就直接暴露了。比如分页查询返回的总数不对，一看SQL发现where条件少了一个状态过滤。
第三个是善用浏览器开发者工具的Network面板。所有接口调用的状态码、响应时间、请求参数、响应体都在这里一目了然。排查前端问题时，先看Network再想代码，能少走很多弯路。
第四个是一个小习惯：在Vuex里把当前用户信息打印到控制台。很多权限相关的Bug，最后查出来都是当前用户的角色信息加载失败，导致权限判断走了else分支。前端调试阶段在store里加一行console.log，能快速确认用户信息是否正常加载。
这套中药实验管理系统，从需求分析到前后端联调，再到上线稳定运行，整个过程中让我最感慨的一点是：业务流程的梳理比技术实现重要得多。技术选型上SpringBoot+Vue都是成熟方案，没有太多惊险的部分，反而是反复确认"方案状态怎么流转""库存什么时候扣减""记录什么时候允许修改"这些业务细节，才真正决定了系统能不能用起来。
如果你要用这套思路做自己的项目，我的建议是：先花时间把流程图画清楚，把状态设计好，再写第一行代码。数据表设计对了，接口文档定了，后面的开发就是填充业务逻辑。遇到问题先看日志，再查数据库，最后才改代码。这套系统后续还可以继续扩展：比如接入消息通知、增加实验数据的图表统计分析、支持导出一整套实验报告的Word模板，都是很有价值的演进方向。
