前阵子帮一个朋友调试医疗挂号管理系统顺手把整份代码完整过了一遍。这套系统技术上用的是SpringBoot2 Vue3 MyBatis-Plus MySQL8.0前后端完全分离源码附带详细的开发文档拿来学习、做毕业设计、或者直接改造成小规模诊所的预约挂号后台都非常合适。为了让你对它有直观印象先说说这系统能干什么患者端可以在线选科室、选医生、选时段挂号医生端能处理接诊、写病历、开处方管理员端负责科室维护、医生排班、号源管理、业务统计角色权限都互相隔离开不串号。我花了两天时间把代码从数据库脚本到前端路由全部捋了一遍整体观感是结构规整注释到位没有那种为了凑功能硬堆代码的痕迹。今天这篇文章就打算从技术选型、功能模块、核心实现、部署流程、避坑经验到二次开发思路把整个项目拆开揉碎讲清楚。无论你是刚学完SpringBoot想找个完整项目练手还是准备交毕业设计需要一套能跑、能讲、能改的系统或者说要在小诊所里快速搭一套挂号管理后台这篇文章都能给你一份可以直接参考的实战地图。1. 项目整体设计思路与技术选型1.1 为什么选择前后端分离早年做这类管理系统常见方案是Thymeleaf模板引擎加后端渲染页面收到什么就是什么代码耦合度很高。这套系统直接走了前后端分离路线后端只提供JSON接口前端Vue3负责页面渲染和用户交互。从实际体验来看前后端分离最大的好处是分工明确——后端同学只管接口逻辑前端同学只管交互展示两边可以并行开发互不阻塞。而在部署上前端打包成静态文件扔到Nginx后端打成一个可执行Jar包独立运行扩展时也能单独给后端做集群不至于把前端也拖着一起扩展。我实际跑完这套代码以后发现前后端分离还有个隐性好处二次接手的人不需要同时搞懂模板语法和业务逻辑前端就是一个标准的Vite工程打开即明了后端就是标准的Spring Boot分层工程Controller-Service-Mapper一条线下去新人上手成本显著降低。1.2 技术栈选型背后的考量先说SpringBoot2。很多人现在纠结是不是应该直接上SpringBoot3但实际情况是SpringBoot2.7.x依然有大量存量项目在跑稳定性和第三方生态兼容性都非常成熟。这个项目选SpringBoot2而不是3主要考虑到国内多数教学资源、网上踩坑案例、公司存量代码基本都是2.x系列遇到问题搜得到答案。如果你拿它做毕设或二次开发别被“版本低”劝退2.x完全够用。再讲Vue3。前端用了Vue3 Vite Element Plus。Vue3的组合式API让组件逻辑更集中比如挂号页面的表单校验、数据加载、时间选择可以集中写在setup里不用像Vue2那样分散在data、methods、computed里来回切换。Element Plus提供现成的表格、表单、弹窗、日期选择器和医疗后台这种注重信息录入、列表展示的场景匹配度很高不需要重复造轮子。MyBatis-Plus则是这套数据访问层的亮点。它不是一个独立框架而是MyBatis的增强工具。单表CRUD不用手写SQL继承一个BaseMapper就能具备insert、update、selectById、selectPage等方法条件构造器LambdaQueryWrapper写起来比拼SQL字符串安全得多分页插件配置好以后前端传页码和每页条数后段直接调Page对象省去一堆PageHelper的配置。项目里多表关联查询依然保留XML自定义SQL两者结合既保证开发效率又保留了复杂SQL的灵活性。MySQL8.0则提供了更优的执行计划、支持窗口函数、JSON类型、公共表表达式CTE默认字符集也是utf8mb4存中文、存表情符号都没问题。和旧版MySQL5.7相比8.0在数据备份、事务处理、并发性能上都有提升而且项目自带初始化SQL脚本建库建表一条命令搞定极大降低环境搭建成本。2. 功能模块拆解挂号系统到底做了哪些事2.1 用户与权限体系系统面向三类角色管理员、医生、患者。登录认证采用JWT服务端不保存会话状态用户登录成功后拿到一个带有效期的Token后续请求在请求头里带上这个Token后端通过拦截器统一校验身份并识别角色权限。后端权限控制我建议重点关注两个点一是接口粒度是否做到角色隔离。比如删除科室、修改排班这类管理操作只允许管理员调用不能让普通医生Token乱Malloc接口二是前端路由是否有守卫。项目里前端通过Vue Router的路由守卫来判断用户角色能不能进入某个页面否则普通人直接敲URL也能绕过菜单进入管理页。这套系统两处都做了虽然实现不算特别复杂但符合实际业务安全要求。实际设计上用户表通常包含username、password、realName、role字段角色不是单独关联表而是用枚举字符串区分管理员、医生、患者分别在业务表中存储额外信息比如医生关联所属科室、职称、简介患者存储身份证、联系方式、过敏史。这种简化设计的好处是代码直观易读适合中小型系统如果你要扩展成企业级平台可以再引入Spring Security加RBAC权限模型但当前项目这样已经够用。2.2 科室、医生与排班管理医疗挂号系统里最核心的树状结构是科室Department管辖若干医生Doctor医生发布排班Schedule患者基于排班去预约挂号Registration。开发时容易把医生理解成和普通用户平行的表但更合理设计是医生是User表里role为DOCTOR的记录再通过doctor_info关联doctorId和departmentId避免重复存储姓名密码等基本信息。排班表设计是这套系统里比较值得学习的部分。一般字段包括排班日期、出诊时段上午/下午、对应的医生ID、科室ID、总号源数量、剩余号源数量、挂号费。逻辑上“总号源-剩余号源”这种设计可以避免反复查挂记录来统计可挂数量挂号时先判断剩余号源是否大于0然后插入挂号记录再更新剩余号源减1两步操作放到一个事务里保证数据不超挂。如果还想加时段可以进一步细化成“上午8-10点、10-12点、下午14-16点、16-18点”不过原型项目通常只做到上午、下午两个时段。2.3 挂号与看诊核心流程整个挂号流程可以整理成一条线患者登录查看科室列表选择科室后查看该科室下已排班且号源充足的医生选择日期和时段确认挂号。此时系统创建一条挂号记录状态为已挂号或待就诊医生端打开工作台能看到当前时段挂号的患者列表点击接诊后状态变为就诊中看诊结束后医生可以填写病历内容、开具处方并提交保存状态变成已完成。这套流程虽然看起来简单但有几个细节是实际开发中的坑一是挂号记录必须同时保存医生ID、科室ID、日期、时段否则后续统计或签到会需要额外关联查询二是挂号后在患者端要做“取消挂号”功能取消后应该释放号源也就是剩余号源加回1三是数据状态流转必须用常量或枚举表示不能满是魔法数字。项目里用了状态字段加注释清晰不少。2.4 患者管理与就诊历史除了核心挂号流程系统还包含了患者基础档案、历史挂号记录、历史病历查询。患者信息不仅仅存在User表里还要有专门的patient_profile表记录更细的医疗信息比如姓名、身份证号、联系电话、出生日期、性别、家庭住址、过敏药物、既往病史。这些信息在医生写病历时可以直接带入提升接诊效率。就诊历史模块在实际开发中有个容易踩的点患者通过挂号记录关联病历记录但挂号记录里已经存了医生和科室的快照所以查询历史时不需要再join医生表直接根据挂号表的doctorName和deptName展示即可性能好很多。如果当初设计时没有冗余字段每次要查医生姓名就要连表数据量大时性能会明显下降。项目这里做了冗余给点个赞。3. 数据库设计与后端核心实现3.1 数据库初始化与表关系拿到项目后第一步不是急着启动而是先看SQL脚本。项目里通常有一个init.sql或schema.sql包含建库建表语句和基础测试数据。表结构大致如下sys_user用户表字段包括id、username、password、real_name、role、avatar、phone、status等department科室表字段dept_id、dept_name、description、statusdoctor_info医生信息表关联user_id、dept_id、title、intro、good_atschedule排班表关联doctor_id、dept_id、work_date、time_type、total、remain、amountregistration挂号表关联patient_id、doctor_id、dept_id、schedule_id、register_date、time_type、status、create_timemedical_record病历表关联patient_id、doctor_id、diagnosis、advice、drugs等prescription处方表可能包含药品名、剂量、用法等表之间主要关系是外键逻辑关联没有强行加物理外键约束是为了方便开发和测试数据导入。这一点符合主流开发实践因为物理外键在大型业务中反而影响扩展性能更多是靠应用层保证数据一致性。如果你要写技术文档可以画出一张简单的ER图患者通过挂号表与排班表产生预约关系医生通过排班表发布出诊计划最后通过病历表完成医疗记录闭环。3.2 后端分层与统一响应体打开后端源码最显眼的包结构是controller、service、mapper、entity、config、common。common里放了统一返回类型Result比如成功返回200加data失败返回500加message。为什么一定要统一响应体因为前后端分离后前端Axios拦截器需要判断状态码和业务状态码如果不统一前端每个页面都要重复处理异常格式维护成本极高。项目里Axios封装了响应拦截器如果返回code不为200自动弹出ElMessage报错逻辑清爽。Service层通常有接口和Impl两个文件这是经典风格。在简单项目里我见过直接不用接口、只有一个ServiceImpl类的做法省代码但扩展性差。项目保留接口层后续要加缓存、加消息通知时不用去动Controller顺着接口实现改就行这对学习者来说也是个好示范。3.3 登录鉴权与JWT实现登录接口接收username和password数据库里密码是用BCrypt加密过的字符串。调试时注意不要拿明文密码去对比数据库而是用BCryptPasswordEncoder的matches方法验证。生成Token的逻辑大致如下用userId、username、role塞进Claims设置过期时间用SecretKey签名返回Token字符串。我特别提醒一下项目里的密钥、过期时间、Token头名称都放在application.yml或配置类里不要写死在代码里。如果二次开发务必改掉默认密钥否则别人知道密钥后能任意伪造Token整个系统等于裸奔。前端拿到Token后存到localStorage或Pinia仓库Axios请求拦截器从仓库取Token并加到Header的Authorization字段后端再通过拦截器解析Header并放行这是一条完整的健壮链路。3.4 挂号接口的实现细节我挑最典型的创建挂号接口来展示后端逻辑。假设前端传参包含patientId、scheduleId、deptId、doctorId、registerDate、timeType后端需要先查schedule记录判断日期是否有效、剩余号源是否大于0然后插入registration表同时更新schedule的remain减一。这两步如果只做插入不扣减号源就会造成超挂如果扣减了插入失败又会导致号源丢失所以必须放在一个事务方法里去调用Transactional注解。部分版本项目还会有“确认挂号”和“取消挂号”两个接口。取消挂号要实现逆操作判断挂号状态是否为待就诊更新状态为已取消并把对应schedule的remain加回1。这个逆操作很容易被人忽略。很多初学同学只实现了创建不实现取消部署一跑发现患者随便取消几次号源就不对了。如果还要做同一天同一时段不能重复挂号的校验就需要在挂号表里添加一个查询看patientId、registerDate、timeType三者是否已存在有效挂号记录。项目如果要上生产环境这里还建议加一个数据库唯一索引双保险防重复。不过作为学习项目业务接口做了校验就够了原理讲清楚别人问你你也能答得上来。4. 前端Vue3实现与页面交互4.1 前端工程目录结构前端使用Vite构建目录结构大体是src/api放接口调用src/router放路由配置src/store放Pinia状态src/views放页面组件src/utils放Axios封装。这个结构非常标准哪怕你在其他项目里也能复用同样思路不会出现“页面目录破壁”的问题。按钮级别权限是通过自定义指令实现的比如管理员页面里“删除科室”按钮只有管理员能看到医生页面不会出现这个按钮。指令本质是在mounted钩子里判断用户角色若没权限则直接removeChild按钮。这比单纯靠隐藏菜单要精细一层也更好解释菜单只是路径层面的控制按钮级指令是操作层面的控制。4.2 Axios封装与请求拦截器前端真正和后端交互的核心在Axios封装文件里。项目通常会在utils/request.js里创建Axios实例设置baseURL为/api通过Vite的proxy代理转发到后端http://localhost:8080。这样开发时就不会有跨域问题因为浏览器访问的是同源地址Vite在本地做了服务器转发。请求拦截器里从Pinia或localStorage取出Token设置Authorization请求头响应拦截器判断HTTP状态码和业务状态码如果Token过期则跳转登录页面并清除本地存储信息。项目里这个处理逻辑很完善实测中模拟Token过期重放接口前端确实会自动退出登录不会出现白屏或连续弹错误提示的糟糕体验。4.3 挂号页面与接口联动挂号页面是多步骤交互的代表。选择科室时触发一个接口拉取科室列表选择医生时触发另一个接口根据科室ID查医生选择日期后触发接口获取该医生的排班信息。前端有三个核心实践值得学习一是日期选择器限制了只能选择今天及之后的7天避免挂过去日期的号二是在显示剩余号源时如果数量为0按钮直接禁用并高亮“约满”三是提交订单前再次确认排班ID和时间防止用户在页面停留太久后排班数据已经变化。另外医生端工作台页面会有“接诊”和“完成”两个操作按钮点击接诊会把挂号状态从0置为1点击完成则写病历并置为2。这个流程里前端要做状态联动比如接诊后不能再次接诊已完成按钮置灰如果不对按钮做禁用用户多点几次就会把状态重复修改和后端不幂等的接口配合起来就是事故现场。所以前端状态控制同样重要。4.4 路由守卫与权限控制前端路由使用Vue Router定义路由时给需要权限的页面添加meta.role字段。路由守卫beforeEach里获取当前用户的角色如果访问路径要求的角色和用户角色不匹配就强制跳转到403页面或首页。这个逻辑虽然只有十几行代码但却是整个系统安全的第二道防线。我实测过程中发现项目里对登录态的检查不是只判断本地有没有Token而是调了一次“getInfo”接口去后端验证Token是否有效。这样避免了一个常见安全漏洞攻击者手工伪造一个假的Token塞到localStorage然后刷新页面如果前端只判断Token非空就放行伪造Token也能进入系统。所以要做完整的校验必须让后端解析Token并返回用户信息。这套项目是这么做的。5. 本地部署与运行指南5.1 环境准备在本地跑起来之前建议先确认这几个软件版本JDK1.8或JDK11SpringBoot2.x都能跑、Maven3.6、Node.js14以上的LTS版本、MySQL8.0服务。很多人环境搭到一半卡住大多是MySQL版本不匹配或Node版本过低。建议先执行java -version、mvn -version、node -v、npm -v确认环境正常再继续下一步。数据库准备最省心的方式是执行项目里的sql脚本。通过命令行进入MySQL执行source /你的路径/init.sqlWindows下注意路径用正斜杠。如果脚本里没有建库语句需要自己先建一个hospital库并设置字符集为utf8mb4。导入完成后用Navicat或DataGrip看到表结构即可。5.2 后端启动步骤后端启动前要改application.yml里的数据库账号密码。改完以后在项目根目录使用mvn spring-boot:run或先mvn clean package打包后再运行Jar包。启动日志出现“Tomcat started on port(s): 8080”就代表后端成功起来。第一次启动如果报MySQL驱动类找不到多半是Maven依赖没拉全检查一下本地仓库是否有mysql-connector-j包或者用mvn clean install -DskipTests强制更新依赖。后端启动后可以先用Swagger或Postman测一下登录接口。项目集成了Swagger3.0启动后访问http://localhost:8080/swagger-ui/index.html就能看到接口文档不用手动敲URL去验证。这里建议先调登录获取Token然后在Swagger右上角把Token填到全局Authorization里就能直接调试挂号、病历等需要鉴权的接口效率提升很大。5.3 前端启动步骤前端启动相对简单在vue目录下执行npm install安装依赖安装完成后执行npm run dev。Vite默认端口通常是5173启动后在浏览器访问http://localhost:5173。前端开发环境一定要确认vite.config.js里的proxy配置是否把/api转发到后端http://localhost:8080否则浏览器会直接请求相对路径导致404。登录时如果页面一直转圈或报跨域不要急着怪后端先把浏览器F12打开Network面板看请求URL是不是指向8080端口再把Console面板的错误信息贴出来排查。配置正确的情况下点击登录应该能看到登录请求返回Token并自动跳转到首页。5.4 生产环境打包部署生产部署时后端执行mvn clean package -DskipTests生成的项目名.jar文件使用nohup java -jar 项目名.jar 后台运行。前端执行npm run build生成dist目录然后把dist目录下的静态文件放到Nginx的html目录里。Nginx配置里至少要有两点一是将location /指向dist目录并配置try_files确保Vue前端路由能正确处理刷新404问题二是将location /api/反向代理到后端服务的8080地址同时传递Host头。值得注意的是生产环境的前端请求不走Vite代理而是走Nginx代理所以前端代码里baseURL要改成请求相对路径/api否则请求地址会直接被浏览器拼成站点的/api实际没有对应后端就会打不到后端服务。很多新手在这一步翻车明明本地好好的部署到服务器就是接口404就是因为没配合Nginx转发规则。我建议在Nginx配置里加上一段location /api/ { proxy_pass http://localhost:8080; }再配合后端的context-path调整基本稳了。6. 常见问题与避坑实录6.1 MySQL8.0密码认证插件问题MySQL8.0默认密码认证插件是caching_sha2_password但某些低版本JDBC驱动不认它启动后端会报“Unable to load authentication plugin caching_sha2_password”。解决办法通常是升级mysql-connector-java版本或者在创建用户时指定IDENTIFIED WITH mysql_native_password BY 密码。这个坑在本地环境反复出现过记录下来能省下至少一小时排查时间。另外MySQL8.0连接URL建议显式加上时区和字符集参数jdbc:mysql://localhost:3306/hospital?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai。如果不加serverTimezone默认情况下会跟国内本地时间差8小时排班日期和挂号日期出现错位测试时非常困惑。6.2 跨域配置重复导致奇怪问题有时候前端项目明明配了Vite代理后端又额外配置了全局CorsAllowedOrigins结果浏览器会收到两次跨域响应头或者OPTIONS预检请求都被拦截。建议开发环境只用Vite代理或者只用后端CORS二选一生产环境必须用Nginx代理后端CORS反而建议关闭。这个项目里默认是后端开了CORS我本地调试时就直接注释掉CORS配置改用Vite代理逻辑更清晰。6.3 MyBatis-Plus分页不生效MyBatis-Plus分页需要手动注入PaginationInnerInterceptor配置类否则调用selectPage时数据库会把全部数据查出来再在内存里面分页数据量一多直接卡死。检查时重点看config包下有没有MybatisPlusConfig类并确认里面配置了MybatisPlusInterceptor。如果没有配置分页接口返回的total永远是总记录数page数据也不准。某些版本里分页插件还会和自定义SQL冲突如果多表查询的XML里使用了LIMIT则不再需要分页插件介入。项目中的多表查询如果直接使用自定义分页注意参数顺序和MySQL方言匹配。调试时可以在SQL日志里看到实际分页语句确认有没有加上LIMIT关键字。6.4 前端Token过期后白屏只要Token过期后端拦截器返回401前端响应拦截器会清除本地状态并跳转登录。但测试时发现一个问题如果Pinia状态已经清空路由跳转也没有重置滚动条刷新后页面偶尔会白屏。解决方案一般是在路由守卫里做前置检查如果发现没有Token且当前访问的是受限页面直接跳回登录页并清空所有页面缓存。另一个细节是密码修改后旧Token依然有效直到过期时间如果做二次开发建议在修改密码接口中让旧Token失效比如引入Token黑名单机制。当前项目没做但面试或答辩时提这个优化点能加分不少。6.5 号源并发问题学习系统上线试跑时并发量低号源扣减问题不明显但如果真要做预约挂号必须考虑并发请求下号源超卖。建议至少把“查询剩余号源并更新”放在一个事务里并使用UPDATE schedule SET remain remain - 1 WHERE id ? AND remain 0这种原子SQL来更新。如果框架要求先查再更新就必须加分布式锁比如使用Redis的SETNX。我把这一点写在避坑里因为这是后续从“能跑”到“能上线”最重要的一道坎。7. 二次开发方向与扩展建议7.1 接入支付与在线预约通知最常规的扩展是增加挂号订单的在线支付功能。一般情况下挂号成功后先标记为待支付调用支付接口生成二维码或跳转收银台支付成功后回调接口再更新订单状态为已支付。这里还要考虑支付超时取消下单10分钟内未支付系统定时任务自动把挂号状态改为已取消剩余号源增加回来。如果不做支付也可以接入微信公众号模板消息或短信平台在挂号成功和就诊前一天推送提醒。7.2 引入Redis提升性能当前系统的排班查询每次都会请求MySQL如果秒杀式抢号数据库压力会非常大。二次开发时可以把当日某个科室医生剩余的号源数量缓存到Redis前端查询时直接读缓存挂号时使用Redis原子DECR扣减再异步写回数据库。缓存还能用于存储验证码和Token等多场景另一个常用做法是引入Spring Cache注解比如给科室列表加Cacheable避免每次都查库。不过千万别一步到位先把现有流程跑稳再引入缓存。缓存最麻烦的是数据一致性医生改排班、患者取消挂号都要同步清理或更新Redis数据否则会出现显示有号但数据库没号的情况。我见过的失败案例十有八九就是缓存过期策略没设置好。7.3 使用代码生成器快速增加新模块如果想给系统增加新功能比如检查报告模块或药品库存模块完全可以基于项目的MyBatis-Plus代码生成器思想根据数据库表生成实体类、Mapper接口、Service、Controller。最简单方式是写一个CodeGenerator类配置数据库连接和表名运行main方法即可生成基础CRUD代码再手动补充业务逻辑和前端页面。这样基于现有骨架做扩展一两天就能加出一个像样的新模块。7.4 项目文档维护与接口管理题目里特别强调了“含文档”我在实际使用中发现这份文档的价值比源码本身还要高。它通常包含需求概述、数据库设计说明、接口文档、部署流程覆盖率很全。建议二次开发时同步维护这份文档特别是新增接口时在Swagger注解里补全参数说明数据库变更及时更新SQL脚本。我见过太多项目代码一堆但文档停留在初始版本最后自己都记不清字段含义维护成本翻倍。保持文档和代码同步是对团队和时间最大的尊重。最后再分享一个小技巧这套系统在本地跑通之后不要急着改功能。先把登录、选科室、挂号、接诊、写病历这条主链路反复点几遍同时开数据库日志观察每个操作背后的SQL。等你闭着眼都能说出每一步对应哪些表、哪些字段时再进行二次开发你会发现做任何改动都有底气。这也是我个人调试这类管理系统最受益的方式。 
长河君 · 2026/10/13 13:07:14 · 阅读 1.2k SpringBoot2+Vue3+MyBatis-Plus+MySQL8.0医疗挂号系统全栈实战详解
前阵子帮一个朋友调试医疗挂号管理系统顺手把整份代码完整过了一遍。这套系统技术上用的是SpringBoot2 Vue3 MyBatis-Plus MySQL8.0前后端完全分离源码附带详细的开发文档拿来学习、做毕业设计、或者直接改造成小规模诊所的预约挂号后台都非常合适。为了让你对它有直观印象先说说这系统能干什么患者端可以在线选科室、选医生、选时段挂号医生端能处理接诊、写病历、开处方管理员端负责科室维护、医生排班、号源管理、业务统计角色权限都互相隔离开不串号。我花了两天时间把代码从数据库脚本到前端路由全部捋了一遍整体观感是结构规整注释到位没有那种为了凑功能硬堆代码的痕迹。今天这篇文章就打算从技术选型、功能模块、核心实现、部署流程、避坑经验到二次开发思路把整个项目拆开揉碎讲清楚。无论你是刚学完SpringBoot想找个完整项目练手还是准备交毕业设计需要一套能跑、能讲、能改的系统或者说要在小诊所里快速搭一套挂号管理后台这篇文章都能给你一份可以直接参考的实战地图。1. 项目整体设计思路与技术选型1.1 为什么选择前后端分离早年做这类管理系统常见方案是Thymeleaf模板引擎加后端渲染页面收到什么就是什么代码耦合度很高。这套系统直接走了前后端分离路线后端只提供JSON接口前端Vue3负责页面渲染和用户交互。从实际体验来看前后端分离最大的好处是分工明确——后端同学只管接口逻辑前端同学只管交互展示两边可以并行开发互不阻塞。而在部署上前端打包成静态文件扔到Nginx后端打成一个可执行Jar包独立运行扩展时也能单独给后端做集群不至于把前端也拖着一起扩展。我实际跑完这套代码以后发现前后端分离还有个隐性好处二次接手的人不需要同时搞懂模板语法和业务逻辑前端就是一个标准的Vite工程打开即明了后端就是标准的Spring Boot分层工程Controller-Service-Mapper一条线下去新人上手成本显著降低。1.2 技术栈选型背后的考量先说SpringBoot2。很多人现在纠结是不是应该直接上SpringBoot3但实际情况是SpringBoot2.7.x依然有大量存量项目在跑稳定性和第三方生态兼容性都非常成熟。这个项目选SpringBoot2而不是3主要考虑到国内多数教学资源、网上踩坑案例、公司存量代码基本都是2.x系列遇到问题搜得到答案。如果你拿它做毕设或二次开发别被“版本低”劝退2.x完全够用。再讲Vue3。前端用了Vue3 Vite Element Plus。Vue3的组合式API让组件逻辑更集中比如挂号页面的表单校验、数据加载、时间选择可以集中写在setup里不用像Vue2那样分散在data、methods、computed里来回切换。Element Plus提供现成的表格、表单、弹窗、日期选择器和医疗后台这种注重信息录入、列表展示的场景匹配度很高不需要重复造轮子。MyBatis-Plus则是这套数据访问层的亮点。它不是一个独立框架而是MyBatis的增强工具。单表CRUD不用手写SQL继承一个BaseMapper就能具备insert、update、selectById、selectPage等方法条件构造器LambdaQueryWrapper写起来比拼SQL字符串安全得多分页插件配置好以后前端传页码和每页条数后段直接调Page对象省去一堆PageHelper的配置。项目里多表关联查询依然保留XML自定义SQL两者结合既保证开发效率又保留了复杂SQL的灵活性。MySQL8.0则提供了更优的执行计划、支持窗口函数、JSON类型、公共表表达式CTE默认字符集也是utf8mb4存中文、存表情符号都没问题。和旧版MySQL5.7相比8.0在数据备份、事务处理、并发性能上都有提升而且项目自带初始化SQL脚本建库建表一条命令搞定极大降低环境搭建成本。2. 功能模块拆解挂号系统到底做了哪些事2.1 用户与权限体系系统面向三类角色管理员、医生、患者。登录认证采用JWT服务端不保存会话状态用户登录成功后拿到一个带有效期的Token后续请求在请求头里带上这个Token后端通过拦截器统一校验身份并识别角色权限。后端权限控制我建议重点关注两个点一是接口粒度是否做到角色隔离。比如删除科室、修改排班这类管理操作只允许管理员调用不能让普通医生Token乱Malloc接口二是前端路由是否有守卫。项目里前端通过Vue Router的路由守卫来判断用户角色能不能进入某个页面否则普通人直接敲URL也能绕过菜单进入管理页。这套系统两处都做了虽然实现不算特别复杂但符合实际业务安全要求。实际设计上用户表通常包含username、password、realName、role字段角色不是单独关联表而是用枚举字符串区分管理员、医生、患者分别在业务表中存储额外信息比如医生关联所属科室、职称、简介患者存储身份证、联系方式、过敏史。这种简化设计的好处是代码直观易读适合中小型系统如果你要扩展成企业级平台可以再引入Spring Security加RBAC权限模型但当前项目这样已经够用。2.2 科室、医生与排班管理医疗挂号系统里最核心的树状结构是科室Department管辖若干医生Doctor医生发布排班Schedule患者基于排班去预约挂号Registration。开发时容易把医生理解成和普通用户平行的表但更合理设计是医生是User表里role为DOCTOR的记录再通过doctor_info关联doctorId和departmentId避免重复存储姓名密码等基本信息。排班表设计是这套系统里比较值得学习的部分。一般字段包括排班日期、出诊时段上午/下午、对应的医生ID、科室ID、总号源数量、剩余号源数量、挂号费。逻辑上“总号源-剩余号源”这种设计可以避免反复查挂记录来统计可挂数量挂号时先判断剩余号源是否大于0然后插入挂号记录再更新剩余号源减1两步操作放到一个事务里保证数据不超挂。如果还想加时段可以进一步细化成“上午8-10点、10-12点、下午14-16点、16-18点”不过原型项目通常只做到上午、下午两个时段。2.3 挂号与看诊核心流程整个挂号流程可以整理成一条线患者登录查看科室列表选择科室后查看该科室下已排班且号源充足的医生选择日期和时段确认挂号。此时系统创建一条挂号记录状态为已挂号或待就诊医生端打开工作台能看到当前时段挂号的患者列表点击接诊后状态变为就诊中看诊结束后医生可以填写病历内容、开具处方并提交保存状态变成已完成。这套流程虽然看起来简单但有几个细节是实际开发中的坑一是挂号记录必须同时保存医生ID、科室ID、日期、时段否则后续统计或签到会需要额外关联查询二是挂号后在患者端要做“取消挂号”功能取消后应该释放号源也就是剩余号源加回1三是数据状态流转必须用常量或枚举表示不能满是魔法数字。项目里用了状态字段加注释清晰不少。2.4 患者管理与就诊历史除了核心挂号流程系统还包含了患者基础档案、历史挂号记录、历史病历查询。患者信息不仅仅存在User表里还要有专门的patient_profile表记录更细的医疗信息比如姓名、身份证号、联系电话、出生日期、性别、家庭住址、过敏药物、既往病史。这些信息在医生写病历时可以直接带入提升接诊效率。就诊历史模块在实际开发中有个容易踩的点患者通过挂号记录关联病历记录但挂号记录里已经存了医生和科室的快照所以查询历史时不需要再join医生表直接根据挂号表的doctorName和deptName展示即可性能好很多。如果当初设计时没有冗余字段每次要查医生姓名就要连表数据量大时性能会明显下降。项目这里做了冗余给点个赞。3. 数据库设计与后端核心实现3.1 数据库初始化与表关系拿到项目后第一步不是急着启动而是先看SQL脚本。项目里通常有一个init.sql或schema.sql包含建库建表语句和基础测试数据。表结构大致如下sys_user用户表字段包括id、username、password、real_name、role、avatar、phone、status等department科室表字段dept_id、dept_name、description、statusdoctor_info医生信息表关联user_id、dept_id、title、intro、good_atschedule排班表关联doctor_id、dept_id、work_date、time_type、total、remain、amountregistration挂号表关联patient_id、doctor_id、dept_id、schedule_id、register_date、time_type、status、create_timemedical_record病历表关联patient_id、doctor_id、diagnosis、advice、drugs等prescription处方表可能包含药品名、剂量、用法等表之间主要关系是外键逻辑关联没有强行加物理外键约束是为了方便开发和测试数据导入。这一点符合主流开发实践因为物理外键在大型业务中反而影响扩展性能更多是靠应用层保证数据一致性。如果你要写技术文档可以画出一张简单的ER图患者通过挂号表与排班表产生预约关系医生通过排班表发布出诊计划最后通过病历表完成医疗记录闭环。3.2 后端分层与统一响应体打开后端源码最显眼的包结构是controller、service、mapper、entity、config、common。common里放了统一返回类型Result比如成功返回200加data失败返回500加message。为什么一定要统一响应体因为前后端分离后前端Axios拦截器需要判断状态码和业务状态码如果不统一前端每个页面都要重复处理异常格式维护成本极高。项目里Axios封装了响应拦截器如果返回code不为200自动弹出ElMessage报错逻辑清爽。Service层通常有接口和Impl两个文件这是经典风格。在简单项目里我见过直接不用接口、只有一个ServiceImpl类的做法省代码但扩展性差。项目保留接口层后续要加缓存、加消息通知时不用去动Controller顺着接口实现改就行这对学习者来说也是个好示范。3.3 登录鉴权与JWT实现登录接口接收username和password数据库里密码是用BCrypt加密过的字符串。调试时注意不要拿明文密码去对比数据库而是用BCryptPasswordEncoder的matches方法验证。生成Token的逻辑大致如下用userId、username、role塞进Claims设置过期时间用SecretKey签名返回Token字符串。我特别提醒一下项目里的密钥、过期时间、Token头名称都放在application.yml或配置类里不要写死在代码里。如果二次开发务必改掉默认密钥否则别人知道密钥后能任意伪造Token整个系统等于裸奔。前端拿到Token后存到localStorage或Pinia仓库Axios请求拦截器从仓库取Token并加到Header的Authorization字段后端再通过拦截器解析Header并放行这是一条完整的健壮链路。3.4 挂号接口的实现细节我挑最典型的创建挂号接口来展示后端逻辑。假设前端传参包含patientId、scheduleId、deptId、doctorId、registerDate、timeType后端需要先查schedule记录判断日期是否有效、剩余号源是否大于0然后插入registration表同时更新schedule的remain减一。这两步如果只做插入不扣减号源就会造成超挂如果扣减了插入失败又会导致号源丢失所以必须放在一个事务方法里去调用Transactional注解。部分版本项目还会有“确认挂号”和“取消挂号”两个接口。取消挂号要实现逆操作判断挂号状态是否为待就诊更新状态为已取消并把对应schedule的remain加回1。这个逆操作很容易被人忽略。很多初学同学只实现了创建不实现取消部署一跑发现患者随便取消几次号源就不对了。如果还要做同一天同一时段不能重复挂号的校验就需要在挂号表里添加一个查询看patientId、registerDate、timeType三者是否已存在有效挂号记录。项目如果要上生产环境这里还建议加一个数据库唯一索引双保险防重复。不过作为学习项目业务接口做了校验就够了原理讲清楚别人问你你也能答得上来。4. 前端Vue3实现与页面交互4.1 前端工程目录结构前端使用Vite构建目录结构大体是src/api放接口调用src/router放路由配置src/store放Pinia状态src/views放页面组件src/utils放Axios封装。这个结构非常标准哪怕你在其他项目里也能复用同样思路不会出现“页面目录破壁”的问题。按钮级别权限是通过自定义指令实现的比如管理员页面里“删除科室”按钮只有管理员能看到医生页面不会出现这个按钮。指令本质是在mounted钩子里判断用户角色若没权限则直接removeChild按钮。这比单纯靠隐藏菜单要精细一层也更好解释菜单只是路径层面的控制按钮级指令是操作层面的控制。4.2 Axios封装与请求拦截器前端真正和后端交互的核心在Axios封装文件里。项目通常会在utils/request.js里创建Axios实例设置baseURL为/api通过Vite的proxy代理转发到后端http://localhost:8080。这样开发时就不会有跨域问题因为浏览器访问的是同源地址Vite在本地做了服务器转发。请求拦截器里从Pinia或localStorage取出Token设置Authorization请求头响应拦截器判断HTTP状态码和业务状态码如果Token过期则跳转登录页面并清除本地存储信息。项目里这个处理逻辑很完善实测中模拟Token过期重放接口前端确实会自动退出登录不会出现白屏或连续弹错误提示的糟糕体验。4.3 挂号页面与接口联动挂号页面是多步骤交互的代表。选择科室时触发一个接口拉取科室列表选择医生时触发另一个接口根据科室ID查医生选择日期后触发接口获取该医生的排班信息。前端有三个核心实践值得学习一是日期选择器限制了只能选择今天及之后的7天避免挂过去日期的号二是在显示剩余号源时如果数量为0按钮直接禁用并高亮“约满”三是提交订单前再次确认排班ID和时间防止用户在页面停留太久后排班数据已经变化。另外医生端工作台页面会有“接诊”和“完成”两个操作按钮点击接诊会把挂号状态从0置为1点击完成则写病历并置为2。这个流程里前端要做状态联动比如接诊后不能再次接诊已完成按钮置灰如果不对按钮做禁用用户多点几次就会把状态重复修改和后端不幂等的接口配合起来就是事故现场。所以前端状态控制同样重要。4.4 路由守卫与权限控制前端路由使用Vue Router定义路由时给需要权限的页面添加meta.role字段。路由守卫beforeEach里获取当前用户的角色如果访问路径要求的角色和用户角色不匹配就强制跳转到403页面或首页。这个逻辑虽然只有十几行代码但却是整个系统安全的第二道防线。我实测过程中发现项目里对登录态的检查不是只判断本地有没有Token而是调了一次“getInfo”接口去后端验证Token是否有效。这样避免了一个常见安全漏洞攻击者手工伪造一个假的Token塞到localStorage然后刷新页面如果前端只判断Token非空就放行伪造Token也能进入系统。所以要做完整的校验必须让后端解析Token并返回用户信息。这套项目是这么做的。5. 本地部署与运行指南5.1 环境准备在本地跑起来之前建议先确认这几个软件版本JDK1.8或JDK11SpringBoot2.x都能跑、Maven3.6、Node.js14以上的LTS版本、MySQL8.0服务。很多人环境搭到一半卡住大多是MySQL版本不匹配或Node版本过低。建议先执行java -version、mvn -version、node -v、npm -v确认环境正常再继续下一步。数据库准备最省心的方式是执行项目里的sql脚本。通过命令行进入MySQL执行source /你的路径/init.sqlWindows下注意路径用正斜杠。如果脚本里没有建库语句需要自己先建一个hospital库并设置字符集为utf8mb4。导入完成后用Navicat或DataGrip看到表结构即可。5.2 后端启动步骤后端启动前要改application.yml里的数据库账号密码。改完以后在项目根目录使用mvn spring-boot:run或先mvn clean package打包后再运行Jar包。启动日志出现“Tomcat started on port(s): 8080”就代表后端成功起来。第一次启动如果报MySQL驱动类找不到多半是Maven依赖没拉全检查一下本地仓库是否有mysql-connector-j包或者用mvn clean install -DskipTests强制更新依赖。后端启动后可以先用Swagger或Postman测一下登录接口。项目集成了Swagger3.0启动后访问http://localhost:8080/swagger-ui/index.html就能看到接口文档不用手动敲URL去验证。这里建议先调登录获取Token然后在Swagger右上角把Token填到全局Authorization里就能直接调试挂号、病历等需要鉴权的接口效率提升很大。5.3 前端启动步骤前端启动相对简单在vue目录下执行npm install安装依赖安装完成后执行npm run dev。Vite默认端口通常是5173启动后在浏览器访问http://localhost:5173。前端开发环境一定要确认vite.config.js里的proxy配置是否把/api转发到后端http://localhost:8080否则浏览器会直接请求相对路径导致404。登录时如果页面一直转圈或报跨域不要急着怪后端先把浏览器F12打开Network面板看请求URL是不是指向8080端口再把Console面板的错误信息贴出来排查。配置正确的情况下点击登录应该能看到登录请求返回Token并自动跳转到首页。5.4 生产环境打包部署生产部署时后端执行mvn clean package -DskipTests生成的项目名.jar文件使用nohup java -jar 项目名.jar 后台运行。前端执行npm run build生成dist目录然后把dist目录下的静态文件放到Nginx的html目录里。Nginx配置里至少要有两点一是将location /指向dist目录并配置try_files确保Vue前端路由能正确处理刷新404问题二是将location /api/反向代理到后端服务的8080地址同时传递Host头。值得注意的是生产环境的前端请求不走Vite代理而是走Nginx代理所以前端代码里baseURL要改成请求相对路径/api否则请求地址会直接被浏览器拼成站点的/api实际没有对应后端就会打不到后端服务。很多新手在这一步翻车明明本地好好的部署到服务器就是接口404就是因为没配合Nginx转发规则。我建议在Nginx配置里加上一段location /api/ { proxy_pass http://localhost:8080; }再配合后端的context-path调整基本稳了。6. 常见问题与避坑实录6.1 MySQL8.0密码认证插件问题MySQL8.0默认密码认证插件是caching_sha2_password但某些低版本JDBC驱动不认它启动后端会报“Unable to load authentication plugin caching_sha2_password”。解决办法通常是升级mysql-connector-java版本或者在创建用户时指定IDENTIFIED WITH mysql_native_password BY 密码。这个坑在本地环境反复出现过记录下来能省下至少一小时排查时间。另外MySQL8.0连接URL建议显式加上时区和字符集参数jdbc:mysql://localhost:3306/hospital?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai。如果不加serverTimezone默认情况下会跟国内本地时间差8小时排班日期和挂号日期出现错位测试时非常困惑。6.2 跨域配置重复导致奇怪问题有时候前端项目明明配了Vite代理后端又额外配置了全局CorsAllowedOrigins结果浏览器会收到两次跨域响应头或者OPTIONS预检请求都被拦截。建议开发环境只用Vite代理或者只用后端CORS二选一生产环境必须用Nginx代理后端CORS反而建议关闭。这个项目里默认是后端开了CORS我本地调试时就直接注释掉CORS配置改用Vite代理逻辑更清晰。6.3 MyBatis-Plus分页不生效MyBatis-Plus分页需要手动注入PaginationInnerInterceptor配置类否则调用selectPage时数据库会把全部数据查出来再在内存里面分页数据量一多直接卡死。检查时重点看config包下有没有MybatisPlusConfig类并确认里面配置了MybatisPlusInterceptor。如果没有配置分页接口返回的total永远是总记录数page数据也不准。某些版本里分页插件还会和自定义SQL冲突如果多表查询的XML里使用了LIMIT则不再需要分页插件介入。项目中的多表查询如果直接使用自定义分页注意参数顺序和MySQL方言匹配。调试时可以在SQL日志里看到实际分页语句确认有没有加上LIMIT关键字。6.4 前端Token过期后白屏只要Token过期后端拦截器返回401前端响应拦截器会清除本地状态并跳转登录。但测试时发现一个问题如果Pinia状态已经清空路由跳转也没有重置滚动条刷新后页面偶尔会白屏。解决方案一般是在路由守卫里做前置检查如果发现没有Token且当前访问的是受限页面直接跳回登录页并清空所有页面缓存。另一个细节是密码修改后旧Token依然有效直到过期时间如果做二次开发建议在修改密码接口中让旧Token失效比如引入Token黑名单机制。当前项目没做但面试或答辩时提这个优化点能加分不少。6.5 号源并发问题学习系统上线试跑时并发量低号源扣减问题不明显但如果真要做预约挂号必须考虑并发请求下号源超卖。建议至少把“查询剩余号源并更新”放在一个事务里并使用UPDATE schedule SET remain remain - 1 WHERE id ? AND remain 0这种原子SQL来更新。如果框架要求先查再更新就必须加分布式锁比如使用Redis的SETNX。我把这一点写在避坑里因为这是后续从“能跑”到“能上线”最重要的一道坎。7. 二次开发方向与扩展建议7.1 接入支付与在线预约通知最常规的扩展是增加挂号订单的在线支付功能。一般情况下挂号成功后先标记为待支付调用支付接口生成二维码或跳转收银台支付成功后回调接口再更新订单状态为已支付。这里还要考虑支付超时取消下单10分钟内未支付系统定时任务自动把挂号状态改为已取消剩余号源增加回来。如果不做支付也可以接入微信公众号模板消息或短信平台在挂号成功和就诊前一天推送提醒。7.2 引入Redis提升性能当前系统的排班查询每次都会请求MySQL如果秒杀式抢号数据库压力会非常大。二次开发时可以把当日某个科室医生剩余的号源数量缓存到Redis前端查询时直接读缓存挂号时使用Redis原子DECR扣减再异步写回数据库。缓存还能用于存储验证码和Token等多场景另一个常用做法是引入Spring Cache注解比如给科室列表加Cacheable避免每次都查库。不过千万别一步到位先把现有流程跑稳再引入缓存。缓存最麻烦的是数据一致性医生改排班、患者取消挂号都要同步清理或更新Redis数据否则会出现显示有号但数据库没号的情况。我见过的失败案例十有八九就是缓存过期策略没设置好。7.3 使用代码生成器快速增加新模块如果想给系统增加新功能比如检查报告模块或药品库存模块完全可以基于项目的MyBatis-Plus代码生成器思想根据数据库表生成实体类、Mapper接口、Service、Controller。最简单方式是写一个CodeGenerator类配置数据库连接和表名运行main方法即可生成基础CRUD代码再手动补充业务逻辑和前端页面。这样基于现有骨架做扩展一两天就能加出一个像样的新模块。7.4 项目文档维护与接口管理题目里特别强调了“含文档”我在实际使用中发现这份文档的价值比源码本身还要高。它通常包含需求概述、数据库设计说明、接口文档、部署流程覆盖率很全。建议二次开发时同步维护这份文档特别是新增接口时在Swagger注解里补全参数说明数据库变更及时更新SQL脚本。我见过太多项目代码一堆但文档停留在初始版本最后自己都记不清字段含义维护成本翻倍。保持文档和代码同步是对团队和时间最大的尊重。最后再分享一个小技巧这套系统在本地跑通之后不要急着改功能。先把登录、选科室、挂号、接诊、写病历这条主链路反复点几遍同时开数据库日志观察每个操作背后的SQL。等你闭着眼都能说出每一步对应哪些表、哪些字段时再进行二次开发你会发现做任何改动都有底气。这也是我个人调试这类管理系统最受益的方式。