很多朋友看到“源码可直接运行”几个字第一反应都是解压、打开、点运行结果要么后端启动报错要么前端依赖装不上要么数据库导入就失败。一套SpringBootVueMySQL的完整项目真正从压缩包变成浏览器里能正常操作的系统中间隔着版本、环境、依赖、数据库好几道坎。这篇内容就围绕“医院药品管理系统”这套源码展开从技术选型、数据库设计到启动步骤、坑点排查一次性讲透。这套系统很适合正在做毕设、想学前后端分离开发、或者准备接医疗信息化方向项目的读者先别急着跑代码把整体设计看明白了调试起来会顺手很多。1. 项目整体设计与技术选型思路1.1 系统的业务定位不只是一个CRUD医院药品管理系统从名字就能看出是医疗行业里的信息管理系统核心是药库和药房的日常业务数字化。它要解决的痛点很明确药品品种多、批次杂、有效期管理容易漏、出入库靠手工记录容易错、月底盘点对不上账。所以系统的核心不是“增删改查”这四个字而是把药品从供应商送到药库、再从药库流向药房和患者手里的全过程管起来。我见过不少人拿到这套源码后只把它当作一个CRUD练手项目其实它的业务含金量远超普通后台管理。它里面对“库存”的处理不是简单的加减法而是围绕批号、有效期、出入库单据来做追踪。也就是说同样的药不同批次进来价格和效期都不一样出库的时候得按先进先出的规则来。这套逻辑吃透了再去接触供应链、仓储系统你会发现思路是相通的。系统里一般会涉及这些角色系统管理员管账号权限药库管理员做入库和采购计划药房操作员负责发药和出库科室人员提交领药申请。角色不同看到的功能菜单和能操作的按钮都不一样。所以前端要配合后端做动态路由和按钮级权限控制这也是这类项目里比较有价值的一部分。1.2 技术栈选型为什么是这套“三件套”SpringBoot Vue MySQL这个组合现在是中小型管理系统的绝对主流。SpringBoot负责后端接口它的核心价值是“约定大于配置”把以前SpringMVCXML那套繁琐的配置基本省掉了内嵌Tomcat打成一个jar包就能跑。Vue负责前端页面组件化开发让页面拆分成一个个独立模块配合Element-UI这类组件库后台管理界面做得又快又整齐。MySQL则是数据落地的地基开源、稳定、资料多对于医院药房这种数据量级别完全够用。选这套技术栈还有一个现实原因招聘市场上需求量巨大。很多公司招Java开发要求里写的就是SpringBootVue或者SpringBootReactMySQL更是必备技能。对学习的人来说把这套系统吃透相当于把企业里最常见的“前端页面后端接口数据库表”的开发模式完整走了一遍比零散看教程效果好得多。也有朋友会问现在都讲微服务、分布式这种单体系统是不是过时了我的看法是单体架构不等于落后。三级医院的HIS系统可能确实上了微服务但一个区级医院、社区卫生院、药房管理系统单体完全扛得住而且开发和运维成本低得多。做技术选型匹配业务复杂度才是第一原则。1.3 版本匹配先把“版本地狱”拦在门外这套源码最常见的运行问题不是代码逻辑问题而是版本不匹配。SpringBoot 2.x和3.x之间有个巨大差异3.x基于JDK17并且把javax包名迁移到了jakarta。如果你的电脑装的是JDK8硬跑SpringBoot 3.x的源码启动直接失败反过来如果你本机是JDK17跑SpringBoot 2.x项目虽然能编译但Maven配置不对也会报错。我建议在动手前先确认三件事JDK版本、SpringBoot版本、Vue版本。一般这种毕设级源码用SpringBoot 2.7.x居多配合JDK8最稳。MySQL用5.7或8.0都行但连接驱动和URL参数写法有区别。前端如果是Vue2建议用Node14或16如果是Vue3Node16或18更合适。Node版本太高尤其超过18以后容易在npm install阶段碰到依赖兼容问题网上说的“springboot版本太高”其实就是这一类连锁反应。2. 核心功能模块与业务流程梳理2.1 药品档案与分类管理药品档案是整个系统的数据基石。药库里每一种药都要在这里建立基础信息包括药品编码、通用名、商品名、规格、剂型、单位、生产厂家、批准文号、零售价等。别小看这些字段很多是医疗行业特有的。比如“批准文号”对应的是国药准字这个字段在普通进销存系统里根本不存在再比如同一通用名可能对应多个厂家、多个规格不能简单用药品名称做唯一标识。药品分类通常采用树形结构比如“抗生素类”“心脑血管类”“中成药类”大类下面还能分小类。前端用el-tree组件展示后端用parent_id字段做无限级分类。这里有个容易踩的坑删除分类时如果有子分类或者有药品挂在这个分类下面必须先做校验提示不然会造成孤儿数据药品列表查不出来。档案管理和入库操作是联动关系。新药品第一次入库时可以自动在药品档案里生成基础信息也可以先建档案再入库。多数系统的做法是档案优先入库单里只能选择已经在档案里存在的药品这样能保证数据一致性和报表统计的准确性。2.2 入库、出库与库存流水入库单和出库单是系统里最核心的两类业务单据。入库的来源一般是采购或者供应商送货药库管理员填一张入库单里面有多条药品明细审核通过后系统把库存加上去。出库方向则是科室领药、药房领药或者退药出库单审核后库存相应扣减。这里有一个设计上的关键点库存变动不能直接update库存表了事而是要先插一条入/出库明细再更新库存数量最后写一条库存流水记录。流水记录里包含操作时间、操作人、单据号、变动类型入库、出库、报损、盘点调整、变动前后数量。为什么要这样做因为一旦以后对账发现有出入或者想统计某段时间的药品消耗量直接查流水表就能还原整个业务过程。没有流水的库存系统出问题基本只能靠人工盘点去猜。单据编号一般会做成业务编号比如RK20250115001前缀加日期加流水号。在代码里注意并发问题不要用简单的数据库自增主键直接给用户看而是通过Redis或者数据库sequence生成有规则的单据号这样既能防止重复用户体验也好。2.3 效期预警与库存预警药品管理跟普通商品不同有一个“效期管理”的概念。药品批号不同有效期就不同。系统里每条库存记录都要保存生产日期、有效期至、批次号。快到期的药品系统要提前预警比如设置“有效期前30天”自动标记为预警状态让药库管理员合理安排出库顺序。库存预警则更常见每一种药品设置一个最低库存量当实际库存小于等于这个阈值时列表里出现高亮或者弹窗提醒。这个逻辑实现起来不难但阈值设置得好不好会直接影响使用感受。阈值设太高满屏都是预警大家就麻木了设太低预警形同虚设。合理的做法是在药品档案里为每类药品单独设置预警阈值并且支持修改而不是在代码里写死。比如注射剂类用量大低库存阈值可以设成300而一些急救用药用量小阈值设成20就够。这个经验值不是拍脑袋定的是药房实际运营数据沉淀出来的。如果你是在做毕设可以在答辩时把这些细节讲出来会显得你对业务理解相当到位而不是只会写CRUD。2.4 用户、角色与操作日志用户权限模块虽然每个系统都有但药品管理系统这里的权限设计有一个医疗行业特色操作留痕。药房人员发放了处方药系统必须能追踪到这个操作是谁做的、什么时候做的。所以除了常见的登录、菜单权限管理之外系统还需要一个操作日志功能把入库审核、出库审核、库存调整这些关键操作全部记录下来。角色权限建议用RBAC模型用户属于角色角色绑定了菜单和操作按钮。比如药库管理员有“入库单审核”按钮权限但看不到“用户管理”菜单系统管理员则全部可见。前端根据登录接口返回的权限标识数组用v-if去控制按钮显隐路由上也挂一个前置守卫做拦截。后端接口层面也要用自定义注解或者拦截器校验权限防止有人绕过前端直接调接口这一点很多毕设项目做得不到位但对实际的系统评审是加分项。3. 数据库设计与核心表结构3.1 表关系总览数据库设计直接决定系统的上限。我建议不管用什么工具先把表关系理清楚再写代码。这套系统的核心表大概分成四组基础数据、业务单据、库存、系统权限。基础数据里有药品分类表、药品信息表、供应商表、科室表。业务单据是入库单/入库明细、出库单/出库明细。库存单独一张库存表按药品批次保存数量和效期。系统权限就是用户表、角色表、菜单表和关系表。用户表里一般直接存一个role_id简化处理如果要做复杂的多角色分配再加user_role中间表。药品信息表和库存表的关系是一对多一个药品会有多个批次的库存记录。库存表和出入库明细之间通过drug_id和batch_no关联。这里要特别注意库存表和业务明细不该做成强外键约束生产环境里外键会影响插入性能而且后期要做数据清洗会很痛苦逻辑关系靠代码维护就够了。3.2 关键设计细节为什么库存要按批次存很多新手会把库存表设计成每行一个药品、一个总数量入库就加、出库就减。这种设计对付简单的进销存还行但放在药品管理里面就出问题了。同一种药上个月进来一批有效期到2026年这个月又进来一批有效期到2025年两批价格可能还不一样。如果只存一个总数出库的时候到底出的哪一批效期怎么追踪所以库存表一定要带上batch_no、production_date、expiry_date这几个字段每一条库存记录对应一个具体批次。出库时按“先进先出”原则先出效期最近的批次。在SQL上查询可用库存时按expiry_date升序排列出库扣减也按这个顺序去扣。这个设计是整套系统里最有含金量的地方也是面试和答辩时经常被问到的问题。药品表上还有一个字段容易被忽略status状态。药品不是永远是启用状态的有些药停产了或者被淘汰了应该做下架停用处理而不是直接物理删除。如果直接删除了药品档案历史入库单和出库单的关联数据就会断裂。所以所有主数据表都建议加逻辑删除字段或状态字段查询列表时默认只查启用状态的数据。3.3 库存事务与SQL陷阱库存扣减操作涉及到数据库事务这是容易出现并发问题的重灾区。两个药房操作员同时出库同一种药品如果代码里先查库存再计算扣减后的数量再update在网络并发场景下就可能出现超卖。解决方法是加行级锁在SQL里用select ... for update锁住库存行或者干脆在update语句里加库存判断条件比如update drug_stock set quantity quantity - #{num} where drug_id #{drugId} and quantity #{num}受影响行数为0就说明库存不足直接抛出业务异常即可。这类写法能有效避免并发超卖代码里也建议把整个扣减操作和插入出库明细、写入流水放在同一个事务方法中用Transactional注解保证原子性。这里还有一个细节出库明细表里除了记录drug_id和数量也要同步保存drug_name、specification、unit等冗余字段。为什么因为药品的基本信息后续可能修改如果明细表不冗余保存快照历史单据显示的时候就会出现药品名称和当时实际出货不一致的情况。4. 从零搭建环境到项目启动全流程4.1 工具链版本清单在动手运行前先对照下面这份版本清单检查自己的电脑环境。这套清单是我验证过的稳定组合实测跑这类毕设项目基本不会出问题。组件推荐版本注意事项JDK1.88u201SpringBoot 2.x必需3.x需要JDK17Maven3.6.3或3.8.x配置阿里云镜像加速依赖下载MySQL5.7或8.08.0需要设置utf8mb4字符集Node.jsVue2用14/16Vue3用16/18版本过高会报ERESOLVEIDEA2021及以上安装Lombok插件必装数据库工具Navicat或DataGrip导入sql需要执行UTF-8编码后端用IDEA打开项目后要等Maven把依赖全部下载完成再启动。如果之前没有配置过Maven的阿里云镜像下载依赖会非常痛苦尤其spring-boot-starter-parent这种大包默认中央仓库在国内拉取速度很慢。在Maven的settings.xml里加上mirror配置这是第一步就该做的事。4.2 后端启动详细步骤依赖下载完成后启动后端前必须改两个地方。第一个是application.yml里的数据库连接配置把url、用户名、密码改成自己本机的。第二个是确认数据库本身已经导入好了SQL脚本。先新建一个数据库名称建议和项目里一致比如ehrms或者medical_drug设置字符集为utf8mb4然后导入项目自带的sql文件。导入完成后检查表数量和导入日志有没有报错尤其是中文字段乱码通常意味着字符集没设置对。改完配置直接运行Application类里的main方法。如果看到类似Tomcat started on port(s): 8080的日志说明后端已经起来了。这里有朋友会好奇端口被占用怎么办Windows下用netstat -ano | findstr 8080查占用进程PID然后taskkill /PID 进程号 /F强制结束或者直接改application.yml里的server.port。4.3 前端启动详细步骤前端部分先在项目根目录打开终端执行npm install安装依赖。这里最大的坑是node-sass如果项目用的是node-sassNode版本和node-sass版本不匹配会直接编译崩溃。比较稳的解决办法是优先选Node14安装后用npm install --legacy-peer-deps如果依然失败检查package.json里sass的版本或者换成dart-sass。依赖安装成功后执行npm run dev。启动前看一眼项目根目录下的.env.development文件里面会有VUE_APP_BASE_URL这样的配置值一般是http://localhost:8080也就是后端接口地址。前端开发服务器默认端口通常为8080如果和后端冲突Vue CLI会提示自动换到8081。浏览器里看到登录页说明前端和后端已经连通。默认账号密码一般在README文档里常见的是admin/admin123。如果登录一直提示失败先用后端接口调试工具直接访问登录接口验证问题就出在前端链路还是后端链路。4.4 启动后验证清单项目跑起来之后建议按下面的清单快速过一遍确认不是“表面能跑实际一堆坑”登录成功后刷新页面确认登录态没有丢失JWT的token是否被正确保存和回传。进入“药品管理”菜单新增一种测试药品看列表里能否正常显示并且不出编码重复错误。做一张入库单审核通过后去库存列表查数量是否增加批次和效期是否写入。再做一张出库单确认库存数量减少并且库存流水表里能查到对应记录。找一个过期或临期药品确认预警列表能展示。这套验证走完基本就能确定前端组件、后端接口、数据库三层的调用链路是通的。如果做毕设这些验证过程还可以整理成测试截图放进论文里。5. 关键实现细节解析5.1 JWT登录认证与接口鉴权前后端分离项目里登录认证最常用的方案就是JWT。用户登录成功后后端用用户的id、用户名、角色生成一个签名字符串返回给前端前端放在localStorage里每次请求在请求头带上Authorization。后端写一个拦截器或过滤器对非白名单的接口进行token校验。我之前看一套源码时发现一个典型问题拦截器只验证了token是否存在没有验证token是否过期、用户是否还存在、角色权限是否有变化。这样用户被禁用后老的token依然能用存在安全隐患。正确做法是每在拦截器里解析token并验证签名和过期时间再去查一次用户的状态如果disable了就直接返回401。JWT的生成和解析建议抽成一个独立的JwtUtil工具类密钥和过期时间配置在application.yml里不要写死在代码里。过期时间一般设成2小时左右前端在axios响应拦截器里判断401状态码跳转到登录页并清除本地存储这个交互体验要做好。5.2 统一返回体与全局异常处理后端接口的设计规范程度直接体现开发者的水平。每套系统都应该定义一个统一返回体比如Result对象里面包含code、msg、data三个字段。所有Controller的返回值都用Result包装前端就能用一套统一的逻辑去处理响应。code为200表示成功401表示未认证500表示服务端异常。全局异常处理用RestControllerAdvice ExceptionHandler注解来实现。把自定义业务异常比如库存不足、药品编码重复、参数校验异常、系统异常分开处理返回对应的错误code和提示。这里有个容易忽略的地方异常信息不要直接抛给前端否则会把SQL报错、堆栈信息都暴露出来既不好看也不安全。统一返回一个“操作失败请稍后重试”之类的提示具体原因记录在服务端日志里即可。5.3 前端Axios封装与路由守卫前端如果每个页面都手动用axios发请求会出现大量重复代码。好的做法是在utils/request.js里统一封装axios实例设置baseURL、超时时间、请求拦截器和响应拦截器。请求拦截器里把token加到请求头响应拦截器里统一处理错误码。后端返回401时自动跳转登录页网络异常时统一弹Message提示页面代码里只需要关心业务数据。路由守卫配合登录状态使用。在router/index.js里给每个需要登录的页面加上meta:{ requiresAuth: true }然后在前置守卫里判断如果localStorage没有token跳转登录页如果有token但访问的是登录页跳转首页。管理员和普通用户的路由还可以按权限动态生成不过这会让代码复杂不少如果毕设时间紧先把静态路由守卫做好就够用。有一类前端问题排查起来特别费时间跨域。开发环境用Vue CLI的proxy代理转发请求一般不会跨域但打包上线后如果前端和后端不在同一个域名/端口下就会出现CORS错误。解决办法是在后端加CorsFilter配置或者在Nginx里配置反向代理把/api开头的请求转发给后端服务。5.4 分页查询与条件检索后台管理的列表页都有一个标配功能条件查询加分页。后端用MyBatis-Plus的Page对象前端传current页码和size每页条数再加上各种筛选条件比如药品名称、分类、状态。MyBatis-Plus的分页插件配置好后会自动生成limit语句不需要手写分页SQL。这里要注意的是条件查询不要用字符串拼接SQL防止SQL注入。使用MyBatis-Plus的LambdaQueryWrapper构建查询条件代码可读性好也安全。前端表格里加上搜索表单点“查询”按钮时重置页码为1再请求不然会出现搜索后在第5页但结果已经不足5页的尴尬情况。另外所有列表数据的时间字段建议从后端格式化好再返回前端专注展示不要在前端处理时间格式化逻辑放在一处维护成本更低。6. 常见问题排查与避坑实录6.1 数据库连接报错类这类是出现频率最高的。如果你启动后端时报错信息里有Access denied for user rootlocalhost先确认密码是否正确然后用命令行或者图形工具能不能正常连上数据库。如果有Communications link failure多半是连接地址里写了localhost但MySQL监听的是socket协议或者MySQL服务没启动。启动MySQL服务在Linux下是systemctl start mysqldWindows下在服务管理器里找到MySQL服务右键启动。连接MySQL 8.0时另一个高频报错是The server time zone value Öйú±ê׼ʱ¼ä is unrecognized。这个直接看就是时区问题在jdbc连接url后面加上serverTimezoneAsia/Shanghai即可。这个坑我记了很多年每次装新版MySQL都会遇到一次。6.2 SpringBoot启动失败类启动失败最常见的情况是端口被占用。第二种是缺少Lombok依赖导致编译报错IDEA里需要安装Lombok插件并开启Annotation Processing否则实体类上的Data注解全会变成红色的报错信息。第三种是MyBatis-Plus版本和SpringBoot版本冲突比如MyBatis-Plus 3.5.9的某些版本对SpringBoot 2.2以下不兼容直接报创建Bean失败。解决办法是把SpringBoot版本提升到2.7.x或者降低MyBatis-Plus版本。还有第四种情况日志报找不到Mapper接口的Bean。检查启动类上有没有MapperScan注解或者每个Mapper接口上有没有Mapper注解二选一即可。这个错在培训机构作业里几乎每周都能看到。6.3 前端编译与联调类npm install失败是前端第一大坑。如果报错里带ERESOLVE overriding peer dependency用npm install --legacy-peer-deps能解决。如果报node-sass相关错误要么换Node版本要么把node-sass改成sass。编译过后浏览器打开页面白屏F12看控制台如果是SyntaxError或者Module not found大概率是某个npm包没装全重新删除node_modules目录后安装。联调时常见的另一个问题是接口能通但无数据。浏览器Network里看请求返回的状态码如果是200但data是null查后端SQL和实体类字段映射是否一致。尤其注意MySQL的字段是下划线命名法Java实体是驼峰命名需要开启MyBatis的map-underscore-to-camel-case配置不然查出来的数据全是null但SQL执行又完全正常。6.4 实用排查命令速查表问题类型诊断命令/工具解决思路端口占用netstat -ano | findstr 8080taskkill /PID 进程号 /F后端日志异常IDEA控制台找Exception栈最底层Caused by前端依赖异常npm install输出优先看ERR!开头的行SQL执行异常Navicat手动执行先单独在数据库跑一遍验证接口联调异常Postman/Apifox直接调后端绕过前端隔离问题JVM内存不足IDEA配置文件修改maven的jvm参数或重启IDEA7. 打包部署与二次开发扩展7.1 前后端分离部署开发环境跑通只是第一步真实项目最终要部署到服务器上。后端打包非常简单在项目根目录执行mvn clean package -DskipTests然后target目录下会生成一个jar包。服务器上只需要有JDK环境执行nohup java -jar xxx.jar app.log 21 即可后台运行。这里注意线上环境不要用application.yml里的开发配置用application-prod.yml单独配置生产数据库地址和日志级别。前端部署走构建流程执行npm run build:prod后生成dist目录里面是一堆静态文件。把这些文件放到Nginx的html目录下并配置反向代理。Nginx配置里把location /api/的请求proxy_pass到http://127.0.0.1:8080这样前端页面和后端接口就处于同一个域名下不会产生跨域问题。数据库上线前记得导出完整SQL并备份一次修改生产数据库连接配置时不要在服务器vi编辑器里直接改明文密码好的做法是把敏感配置放到环境变量或者配置中心里虽然毕设可能用不上但这个意识值得养成。7.2 二次开发优先扩展的方向如果这套系统要用于真实场景或者进一步学习有几个值得扩展的方向。第一个是数据统计报表药品管理系统天然适合做月度消耗分析、科室领药排行、采购成本趋势前端用ECharts画图后端提供聚合统计接口做完整个系统的档次立刻不一样。第二个是Excel导入导出药品定期盘点时手工录入几百条数据太痛苦做成模板导入导出能极大提高效率用EasyPOI或者阿里巴巴的EasyExcel都很方便。第三是结合HIS系统的集成方案比如和门诊挂号、医生开方做对接药品库存能实时扣减这是医疗信息化的进阶玩法。第四是部署容器化写一份Dockerfile和一个docker-compose.yml把SpringBoot应用和MySQL都用Docker跑起来一套命令就能复现整个环境。说到这里我想起很多朋友第一次用Docker部署SpringBoot时总在Dockerfile的JAR包路径上翻车其实只要确认jar包名和执行命令里的路径一致就好其他都很直观。从我个人的经验看这类药品管理系统源码真正有价值的地方不在于它用了多新的技术而在于它的业务完整度。“药品效期预警”这样一个点背后牵扯出批次库存、先进先出、库存流水这些连锁设计把这些想明白了就相当于把企业级业务系统的核心思维学了一遍。如果你现在正好拿到了这套源码别急着大改大动先按文章里的验证清单把链路跑通再挑一两个模块做二次开发效果会好很多。最后再分享一个小技巧给系统本地跑通后把初始数据稍微整理一下录一批真实感强的药品数据进去演示调试的时候页面会漂亮很多也更容易看出功能有没有异常。