Spring Boot + Vue 全栈开发在线医疗预约挂号系统实战指南

最近刚把一个基于Spring Boot Vue的线上医疗服务系统完整跑通前端用的Vue3加Element Plus后端Spring Boot配上MyBatis-Plus算是一套很典型的全栈结构。这套系统覆盖了用户注册登录、科室与医生展示、在线预约挂号、医生问诊写病历、后台数据管理这几块核心业务整体做下来差不多六张业务表、三十个左右接口。写这篇文章主要是把我从数据库设计到前后端联调部署的完整思路和踩坑记录整理出来给正在做类似项目或者准备做毕设的同学一个可以直接参考的底稿。1. 项目定位与核心需求梳理1.1 这个系统到底要解决什么问题线上医疗服务系统本质上是把线下的挂号、候诊、病历管理流程搬到网上。传统的就医流程中患者需要到医院现场排队挂号医生接诊后手写病历复诊时想翻查历史诊断记录特别费劲。这套系统要做的就是三件事让患者可以在线看到科室和医生信息并完成预约让医生可以管理自己当天的接诊列表并在线填写病历和处方让管理员可以维护基础数据比如科室、医生信息、账号状态。从角色角度看系统分成了三端普通用户端、医生端、管理端。用户提交预约后医生端能看到待接诊的预约单接诊之后生成病历记录这就能形成一个相对完整的业务闭环。对毕业设计或者练手项目来说这种闭环非常有价值——它不是零散的增删改查而是带有状态流转的真实业务既能展示后端接口设计能力又能展示前端交互细节。整个项目的核心痛点不在技术复杂度而是在业务约束。预约要防止同一个医生同一时间段被重复预约病历要关联到具体的预约单和患者不同角色能看到的菜单和数据范围必须严格区分。把这些问题都处理掉系统才算真正有可用性。1.2 技术选型为什么是Spring Boot Vue技术选型这块我直接说结论后端Spring Boot配合MyBatis-Plus前端Vue3配合Vite和Element Plus数据库用MySQL 8.0身份认证用JWT这套组合是目前做全栈管理类系统最稳的组合。Spring Boot的好处在于自动配置和起步依赖一个Spring Boot项目配合starter-web、starter-validation、starter-security或者不用Security只写拦截器就能把基础框架搭起来。MyBatis-Plus相对原生MyBatis来说最大的优势是不用写大量XML映射单表CRUD直接用BaseMapper提供的方法条件查询用LambdaQueryWrapper就能搞定开发效率非常高。这也是为什么现有很多Java开源项目都选择这个组合。前端用Vue3而不是Vue2主要考虑到Element Plus是基于Vue3的组件库组件更新和维护更活跃Vite的冷启动速度也比webpack舒服很多。管理类页面本身就是大量表格、表单、弹窗、抽屉的组合Element Plus的Table、Form、Dialog、Message组件基本够用没必要再引重量级UI框架。数据库用MySQL项目里统一使用utf8mb4编码排序规则用utf8mb4_general_ci日期字段全部用datetime金额字段用decimal(10,2)状态字段用tinyint。这些看起来是小事但后期联调时少很多编码和精度问题。2. 数据库建模与核心表设计2.1 六张核心表的结构设计数据库设计是整个项目的地基表结构错了后面接口再怎么改都难受。我这个系统一共设计了六张核心表用户表、科室表、医生表、预约表、病历表、药品表。下面把每张表的关键字段和使用逻辑说一下。用户表放在最前面字段包含user_id主键、username登录名、password加密密码、real_name真实姓名、phone手机号、role角色USER/DOCTOR/ADMIN、status状态0禁用、1正常、create_time创建时间。要注意的是医生也是用户医生表通过user_id和用户表关联不要单独再建一套医生登录账号不然登录逻辑会分成两套复杂度直接翻倍。科室表相对简单dept_id、dept_name、description、sort_order。医生表稍微复杂一些doctor_id、user_id、dept_id、title职称比如主任医师、副主任医师、intro简介、avatar头像地址、visit_fee挂号费再留一个is_available字段表示是否在岗。预约表是核心业务表字段有appointment_id、patient_id关联用户表、doctor_id、dept_id、visit_date就诊日期、time_slot时间段、status状态UNPAID/PAID/COMPLETED/CANCELLED或者用数字0/1/2/3、create_time创建时间。病历表要记录诊断和处方信息record_id、patient_id、doctor_id、appointment_id关联预约单、chief_complaint主诉、diagnosis诊断结论、treatment_plan治疗方案、prescription_drugs处方内容、create_time。药品表在有药品库存管理需求时才需要字段包括drug_id、drug_name、specification规格、price单价、stock库存、usage_dosage用法用量。实际开发中处方和药品可以用一个中间表拆开但毕设量级下直接在病历表里存处方文本加药品明细关联表就能跑通不用过度设计。字段类型上我有个习惯所有主键用bigint自增不用int是因为考虑到未来数据量虽然毕设没那么多数据但习惯要养好字符串长度不要都写成255手机号varchar(20)、身份证号varchar(18)这种按实际长度走金额字段一定用decimal用float存金额会在精度上出问题。还有外键我建议不要加物理外键约束业务表之间用字段逻辑关联理由很简单加了外键之后删除和插入数据时数据库会强制校验数据清理和测试阶段会平白多出很多麻烦。2.2 用MyBatis-Plus优雅生成建表SQL很多同学在纠结建表SQL到底手写还是用工具生成。我推荐的方案是实体类用MyBatis-Plus注解设计好再用工具或者手写脚本把建表SQL落库。这样两者保持一致不会出现实体类字段和数据库字段对不上的情况。实体类上最常用的注解一共就那几个。TableName指定表名比如用户表TableName(sys_user)。TableId(type IdType.AUTO)表示主键自增。逻辑删除字段加TableLogicMyBatis-Plus在查询时会自动带上deleted0条件删除时自动转成update语句。自动填充字段加TableField(fill FieldFill.INSERT)配合MetaObjectHandler就能在插入时自动填create_time。如果你真的想让MyBatis-Plus根据实体类自动生成建表SQL需要额外引入扩展或者配置SqlInjector但在项目里这样做反而增加了复杂度。更稳的做法是让实体类设计先定好然后用Navicat或者直接执行SQL脚本建表。下面这是我用户表和预约表的建表SQL直接抄到Navicat里就能用CREATE TABLE sys_user ( user_id bigint(20) NOT NULL AUTO_INCREMENT, username varchar(50) NOT NULL COMMENT 登录账号, password varchar(100) NOT NULL COMMENT BCrypt加密密码, real_name varchar(50) DEFAULT NULL COMMENT 真实姓名, phone varchar(20) DEFAULT NULL COMMENT 手机号, role varchar(20) NOT NULL DEFAULT USER COMMENT 角色, status tinyint(4) NOT NULL DEFAULT 1 COMMENT 状态 1正常 0禁用, deleted tinyint(4) NOT NULL DEFAULT 0 COMMENT 逻辑删除, create_time datetime DEFAULT NULL COMMENT 创建时间, PRIMARY KEY (user_id), UNIQUE KEY uk_username (username) ) ENGINEInnoDB AUTO_INCREMENT1 DEFAULT CHARSETutf8mb4 COMMENT系统用户表;CREATE TABLE appointment ( appointment_id bigint(20) NOT NULL AUTO_INCREMENT, patient_id bigint(20) NOT NULL COMMENT 患者ID, doctor_id bigint(20) NOT NULL COMMENT 医生ID, dept_id bigint(20) DEFAULT NULL COMMENT 科室ID, visit_date date DEFAULT NULL COMMENT 就诊日期, time_slot varchar(20) DEFAULT NULL COMMENT 时间段 如08:00-08:30, status tinyint(4) NOT NULL DEFAULT 0 COMMENT 0待接诊 1已接诊 2已取消, create_time datetime DEFAULT NULL COMMENT 创建时间, deleted tinyint(4) NOT NULL DEFAULT 0, PRIMARY KEY (appointment_id), KEY idx_doctor_date (doctor_id, visit_date, time_slot) ) ENGINEInnoDB AUTO_INCREMENT1 DEFAULT CHARSETutf8mb4 COMMENT预约挂号表;这里的唯一键和联合索引可不是摆设。联合索引idx_doctor_date就是用来支撑预约冲突查询的查询条件一旦带上doctor_id、visit_date、time_slot这三个字段索引就能直接命中。设计索引的原则是WHERE条件里最常用的字段放前面选择性高的字段也放前面。3. 后端核心接口与业务流程实现3.1 后端工程结构与统一返回封装后端工程结构我按controller、service、mapper、entity、dto、config、common这样分包。common里放统一返回结果、异常处理、工具类。用一个Result类统一包装所有接口返回字段就是code、message、data。这样做的好处是前端axios拦截器可以统一判断code不需要每个请求单独写success判断逻辑。Data public class ResultT { private Integer code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.code 200; result.message 操作成功; result.data data; return result; } public static T ResultT error(Integer code, String message) { ResultT result new Result(); result.code code; result.message message; return result; } }Controller层的命名我习惯用资源名加动作比如预约相关接口就放在AppointmentController下路径设计是POST /appointment提交预约GET /appointment/myMyAppointments查我自己的预约GET /appointment/doctor/list医生查自己的接诊列表。RESTful风格能让人一眼看出这个接口是干什么的也方便前端对接。这里要特别说一个很多人忽略的点DTO和VO要分离不要把实体类Entity直接暴露给前端。实体类里的password字段如果直接返回给前端密码就泄漏了。我在用户登录后返回给前端的是一个UserVO只包含userId、username、realName、role、phone这些必要字段。这个习惯在真实项目里是强制要求在毕设里也能成为答辩亮点。3.2 登录认证与JWT防绕过设计登录认证我用了JWT加拦截器的方案没有引入完整的Spring Security。不是说Spring Security不好而是对这套系统来说Spring Security的过滤器链和权限表达式配置比较重理解成本高出问题也不好排查。JWT加HandlerInterceptor的方案代码量很少控制在几百行以内逻辑完全透明非常适合中小型前后端分离项目。密码存储用BCrypt加密。BCrypt是自适应哈希每次加密生成的密文都不一样但校验时能通过密文中的盐去验证所以数据库里存密码字段用varchar(100)因为BCrypt密文长度是60位左右。登录接口流程是前端传username和password后端查出用户、校验status是否为正常、用BCryptPasswordEncoder匹配密码通过后生成JWT返回给前端。String token JwtUtil.createToken(user.getUserId(), user.getUsername(), user.getRole());JwtUtil的核心逻辑就是生成token和解密token。我用的是HMAC256签名密钥放在application.yml配置里过期时间设为24小时。拦截器里从Header的Authorization中取出token去掉“Bearer ”前缀解析出userId和role并存到ThreadLocal里。这里有个细节如果解析不到用户信息直接返回401并提示重新登录不要在拦截器里做跳转因为前后端分离项目后端做重定向是无效的。拦截器注册的时候要排除登录、注册这两个接口其余接口全部拦截校验。角色控制我是通过自定义注解RequireRole实现的标注在Controller方法上拦截器解析注解判断当前用户的role是否有权限访问。比如管理端的删除用户接口加RequireRole(ADMIN)普通用户就算拿到了token也无法调用。这是权限控制里最容易出问题的地方——只拦没token的请求不拦角色不对的请求会造成越权。3.3 预约挂号冲突校验与事务处理预约挂号的业务逻辑是整个系统最核心的部分也是最容易写错的地方。正常的预约流程是用户查看科室列表进入医生详情页选择就诊日期和时间段提交预约生成待接诊预约单。关键在于同一时间段的号源不能被两个用户同时抢到。我的实现思路是先查询appointment表中是否已存在“同医生同日期同时间段状态为待接诊”的记录如果存在就返回“该时段已被预约”不存在则插入预约记录。很多人觉得这个先查后插的方案够了但在高并发下可能出问题两个请求同时查到没有记录同时插入就重复了。要彻底解决要么给doctor_id、visit_date、time_slot、status加唯一索引要么在插入时用数据库锁毕设场景下先查后插加事务已经够用但如果想显得专业可以加上悲观锁或唯一索引兜底。Transactional(rollbackFor Exception.class) public Result createAppointment(AppointmentDTO dto) { LambdaQueryWrapperAppointment wrapper new LambdaQueryWrapper(); wrapper.eq(Appointment::getDoctorId, dto.getDoctorId()) .eq(Appointment::getVisitDate, dto.getVisitDate()) .eq(Appointment::getTimeSlot, dto.getTimeSlot()) .in(Appointment::getStatus, 0, 1); Long count appointmentMapper.selectCount(wrapper); if (count 0) { return Result.error(500, 该时间段已被预约请选择其他时段); } Appointment appointment new Appointment(); BeanUtils.copyProperties(dto, appointment); appointment.setPatientId(LoginUtil.getUserId()); appointment.setStatus(0); appointmentMapper.insert(appointment); return Result.success(); }为什么这里要加Transactional因为理论上后续还要做更新号源剩余数量的操作比如医生表有一个remaining_count字段预约成功就减一取消就加一那这两个写操作必须放在同一个事务里要么都成功要么都失败。事务加在Service方法上rollbackFor设置成Exception.class否则默认只在RuntimeException时回滚捕获了异常不抛出会导致数据不一致。这个坑我说过很多次确实有很多同学因此写了半个系统才发现数据对不上。4. 前端Vue页面搭建与交互实现4.1 前端工程初始化和路由守卫前端工程我用的Vite创建Vue3项目命令是npm create vitelatest模板选vue。创建完项目之后安装依赖npm install然后安装vue-router、pinia、axios、element-plus。Element Plus最好用按需自动导入的方式配合unplugin-auto-import和unplugin-vue-components这样打包体积会小很多。工程目录结构按views、components、router、store、api、utils来划分。views下面按业务模块建子目录比如views/user下面放用户端页面views/admin下面放管理端页面。router配置里定义所有路由登录页、首页、科室列表、医生详情、预约页、我的预约、管理后台。这里要注意用到动态路由的地方根据用户角色动态加载管理端路由普通用户登录后访问/admin要直接拦截跳回首页。路由守卫是整个前端权限拦截的关键router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (!token to.path ! /login) { next({ path: /login }) } else if (token to.path /login) { next(/) } else { const role localStorage.getItem(role) if (to.meta.role to.meta.role.indexOf(role) -1) { next(/) } else { next() } } })这段代码解决了三个问题未登录用户不许跳转、已登录用户不需要重复登录、非管理员不能进管理后台。登录成功之后我把token和role放进localStorage路由守卫从localStorage读取这样刷新页面之后登录状态也不会丢。4.2 请求封装、状态管理与角色控制Axios封装这块我直接说结论一定要做到统一拦截器不要在每一个页面里重复写请求代码。我的utils/request.js里用axios.create创建实例设置baseURL为/prod-api在请求拦截器里从localStorage读token并放进Authorization头在响应拦截器里统一处理返回结果。service.interceptors.response.use( (response) { const res response.data if (res.code ! 200) { ElMessage.error(res.message || 请求失败) return Promise.reject(new Error(res.message)) } return res }, (error) { if (error.response error.response.status 401) { localStorage.removeItem(token) router.push(/login) } ElMessage.error(error.response?.data?.message || 网络异常) return Promise.reject(error) } )状态管理用的Pinia只存两样东西用户信息和动态路由标记。用户信息在登录之后从接口返回存到Pinia里页面刷新时需要重新获取。动态路由的加载我放在路由守卫里判断如果Store里没有加载标记说明是刷新页面需要重新根据角色生成可访问的路由表再跳转这能避免刷新后管理菜单消失的问题。角色控制在页面的表现就是菜单渲染和按钮权限。菜单根据role字段判断用户端显示“科室列表”“我的预约”医生端显示“我的患者”“接诊管理”管理端显示“用户管理”“医生管理”“科室管理”“药品管理”。按钮级权限不需要做太复杂顶多审核功能的按钮写在v-if里判断一下角色就能搞定。4.3 预约页、管理后台与组件复用的实现细节预约页面是交互细节最多的页面。用户进入医生详情页页面展示医生头像、职称、简介、挂号费下面就是选择就诊日期和时间段。日期选择器需要禁掉过去的日期时间段从后端接口返回固定列表比如上午08:00-08:30、08:30-09:00这些时段。时间段按钮被选中后高亮提交按钮在请求期间置为loading防止用户重复点击提交。等请求完成后再恢复按钮状态这个细节看起来不起眼实则是防重复预约的第一道防线。病历填写和处方选择放到医生端接诊页面。医生从待接诊列表点击“接诊”弹出抽屉或者弹窗里面是患者信息、主诉、诊断建议处方部分可以用一个药品下拉选择框加数量输入框。这里我用到Vue插槽来复用表单组件封装一个BaseFormModal组件不同业务往里塞不同表单slot。比如接诊窗口和编辑科室信息窗口外层逻辑都是打开弹窗、提交请求内容完全由slot决定代码复用率提上去了维护成本也降下来了。管理后台的表格页可以用一个通用模板套路来写顶部是筛选条件表单中间是el-table底部是el-pagination分页。不要把分页参数写死currentPage、pageSize传到后端接口后端返回total前端就能完整渲染分页。删除操作统一弹MessageBox确认不要点了就直接删。样式冲突是Vue项目里特别常见的问题。Element Plus组件的样式默认没有隔离你写了一个全局样式想覆盖某个组件结果影响到了所有页面。解决办法就是给每个Vue文件的style标签加scoped如果必须要改第三方组件内部样式用:deep()选择器比如:deep(.el-input__inner)。这个坑我在写科室卡片样式时踩过一次全局给卡片加了hover阴影结果所有弹窗里的卡片也跟着抖动。5. 部署上线与环境坑实录5.1 后端打包与前端Nginx部署前后端分离项目的部署后端就是把Spring Boot项目打包成可执行jar前端打包成静态文件交给Nginx代理。先说后端。修改application.yml里的server.port默认8080如果被占用改成你想要的端口就行。打包命令是mvn clean package如果跳过测试就加-DskipTests。最后生成的jar包路径在target目录下用java -jar xxx.jar启动。如果在Windows环境用命令行启动jar中文乱码问题很常见。解决办法是在启动命令里加-Dfile.encodingutf-8例如java -Dfile.encodingutf-8 -jar xxx.jar或者在IDEA里给运行配置加上环境变量。乱码问题很多时候不是代码的问题是控制台编码和文件编码不一致。前端部署分两步执行npm run build生成dist目录然后把dist文件夹放到Nginx的html目录下配置Nginx。要注意接口地址的代理配置前端请求的baseURL要跟Nginx里的location对应起来server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /prod-api/ { proxy_pass http://localhost:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这段配置里try_files是Vue Router必须的否则访问页面刷新后会出现404。proxy_pass转发的时候/prod-api/路径会被替换成proxy_pass里的/也就是说请求/prod-api/login会转发到http://localhost:8080/login。这个规则搞清楚了前端就不用关心生产环境的接口地址是怎么拼接的。5.2 频繁踩到的环境与依赖问题环境配置永远是最消磨耐心的部分我遇到的第一个问题是JDK多版本并存。电脑上装了JDK8和JDK17环境变量JAVA_HOME改了之后命令行的java -version还显示旧版本。原因是Path里还残留着之前JDK安装目录的路径并且顺序排在JAVA_HOME前面。解决办法是检查Path环境变量把具体路径删掉只保留%JAVA_HOME%\bin。第二个高频问题是Maven依赖下载慢和版本冲突。Spring Boot和MyBatis-Plus版本不匹配会直接启动报错最常见的是NoSuchMethodError或者ClassNotFoundException。我给的建议是Spring Boot用2.7.x版本MyBatis-Plus用3.5.x版本这对组合非常稳妥网上资料也多。JDK版本最好用8或者11别在毕设阶段用JDK17去跑Spring Boot 2.7虽然能跑但有些反射相关的问题处理起来非常绕。第三个问题是前端启动报错。Node版本太老会导致Vite不支持版本太新又会有OpenSSL错误。Vite 4一般要求Node 14.18或者16推荐直接用Node 16或18稳定版。npm install报错的时候优先删除node_modules和package-lock.json再重新安装能解决80%的依赖问题。有的人习惯把node_modules一起压缩发出去几百兆的包发来发去纯属折磨正确做法是只发源码让对方重新npm install。第四个问题是MyBatis-Plus的字段映射。Java实体类是visitDate数据库字段是visit_date如果没配置驼峰映射就会查不到值。Spring Boot中mybatis-plus.configuration.map-underscore-to-camel-case默认是true但如果自己重新定义了MybatisPlusConfiguration就可能覆盖默认配置导致字段匹配不上。排查这种问题最简单的方法是打开SQL日志输出看看MyBatis-Plus实际执行了什么SQL再对照返回实体看字段值。5.3 业务数据层面的坑与检查清单业务数据层面的坑我整理成了检查清单每做完一个模块就过一遍。第一项时间字段格式要统一。Java后端用LocalDateTime接收前端传的日期时间需要加JsonFormat(pattern yyyy-MM-dd HH:mm:ss)注解否则前端拿到的是带T的ISO格式显示不好看。就诊日期这种date字段也用字符串传给后端后端统一用LocalDate接收并转换。第二项密码绝不能明文入库。就算暂时没做找回密码功能也一定要用BCrypt加密再入库。一个最简单验证方式去用户表直接查密码字段如果能看到123456这种原文说明代码里漏了加密流程需要回去检查注册接口是否调用了encode。第三项越权访问要严防。查询接口必须跟前端传的用户ID绑定。比如医生查自己的接诊列表接口里不要用前端传的doctorId来查询而是从token里解析出当前用户的userId再用userId去查对应的doctor信息。很多同学图省事前端传doctorId后端直接查结果用户把doctorId改成别人的就能偷偷看到别人的接诊单这是面试官特别喜欢追问的漏洞。第四项逻辑删除字段deleted统一放在每张表。MyBatis-Plus配置了逻辑删除后selectById和selectList会自动带上deleted0条件删除也变成update不会真正物理删除数据。业务里做“作废预约”功能时直接调deleteById就能正确改写数据不用自己再单独写update语句。第五项事务不要只放在Controller方法上。有一个容易犯的错误是在Controller里写业务逻辑然后给Controller方法加Transactional到后期改逻辑时发现事务总是控制不住。规范写法是Controller里只做参数接收和调用业务逻辑全部写在Service层Transactional放在Service方法上一个方法就是一个完整业务逻辑单元。结尾这套系统做完之后的几点体会整个项目从设计到部署跑通我个人最大的感受是别急着写代码先把接口清单列出来。我第一版是想到哪写到哪后端接口设计得很散前端对接时来回改。后来把所有业务场景列成了三十个接口的清单每个接口标清请求方式、入参、出参、权限要求前后端照着清单开发联调过程中几乎没再改过接口。还有一个小经验上线之前一定要自己完整走一遍流程用两个账号分别测试用户端和医生端。我最后一次测试时发现医生接诊完用户端“我的预约”页面状态没有自动变化原因是我用了前端写死状态刷新而不是每次进入页面重新拉取接口数据。后来改成路由切换时重新加载数据这个问题就解决了。这套系统后面要扩展也不难。想接在线支付可以在预约表加支付单号和支付状态字段想接短信通知可以在预约成功后调短信服务商的接口想做小程序端后端接口基本不用动小程序直接复用同一套API。真正有价值的不是某个炫酷技术而是把一条完整业务线跑顺这个过程中积累的排错和分析能力才是做这类项目最大的收获。