乡镇医院挂号预约小程序实战：Spring Boot后端与并发控制全解析

接到“乡镇医院挂号预约小程序”这类需求，第一反应是好事，说明基层医疗机构的信息化终于动起来了。但真做起来就会发现，它和市面上那些面向城市三甲医院的预约系统根本不是一回事：没有庞大的号源池、没有复杂的分级诊疗、甚至科室都可能不到十个，但业务链条一样不能少，而且对稳定性和可维护性的要求一点不含糊。

这个项目我按“Spring Boot后端 + 微信小程序前端 + 管理后台”三件套来做的，整套流程走完后攒了不少经验，今天把这套系统的设计思路、核心实现、还有那些文档里不会告诉你的坑，一次性梳理清楚。如果你正准备接类似的挂号预约项目，或者正在做相关毕业设计，这篇内容应该能帮你少走不少弯路。

1. 项目核心拆分：乡镇医院挂号预约到底要解决什么问题

1.1 需求场景与用户角色

乡镇医院的挂号场景和城市三甲有本质区别。三甲医院讲究多渠道分流、分时段精准预约、复杂专家排班；乡镇医院的需求更朴素——让镇上居民不用一大早跑来窗口排队，尤其是老人子女帮忙挂号、慢性病复诊开药这类高频场景。系统要服务好三类人群：普通患者（含帮家人挂号的年轻人）、医院号源管理科室、以及坐诊医生。

患者端要的功能很直接：选科室、选医生、选日期、看剩余号、提交预约、查记录、取消预约。管理端需要的是排班管理、号源发放、停诊处理、预约记录导出。医生端更轻，可能只需要看当天预约列表和标记到诊。整个系统的核心难点不在功能多，而在“号源不能超卖”和“停诊改约不能乱”这两件事上。

我把用户角色设计成三个端：微信小程序给患者用，Web管理后台给医院科室管理员用，医生端暂时复用管理后台的简单视图（不单独开发小程序，降低交付成本）。这个取舍在乡镇医院场景很务实——预算有限、使用人数少，多端并行反而增加培训和维护成本。

1.2 功能模块划分与技术选型逻辑

系统整体拆成三大块：预约核心链路、基础数据维护、通知与统计。预约核心链路包含科室/医生查询、号源查询、预约/取消预约、我的预约；基础数据维护包含科室管理、医生信息、排班计划、号源模板；通知与统计包含预约成功通知、停诊通知、预约取消提醒、以及每日预约统计报表。

后端框架用Spring Boot 2.7.x，原因后面会细说。小程序端不选原生开发而是用了uni-app，主要考虑医院后期可能有App端和H5端的扩展需求，一套代码多端复用对这类预算有限的项目很有吸引力。数据库用MySQL 8.0，缓存用Redis，ORM层面用MyBatis-Plus减少单表CRUD的重复劳动。

选型的核心逻辑是“常规但不陈旧”。Spring Boot已经是Java后端的绝对主流，招人和维护都容易；MyBatis-Plus在中小项目里比JPA更容易控制SQL，尤其在多表查询时更直观。前端选uni-app而不是微信原生语法，是因为医院项目普遍后续会要“再做个App吧”“做个公众号H5吧”这种需求，提前防一手比后面重构划算。

2. 后端设计与核心实现：Spring Boot的硬核部分

2.1 项目初始化与版本选型避坑

很多人一开始就踩进版本的坑，这里必须先展开讲。Spring Boot 3.x 已经出来很久了，但它基于 JDK 17，而很多医院的部署环境还停留在 JDK 8，或者运维只会装 Tomcat 8/9。如果选 Spring Boot 3.x，JDK 版本不符合，项目启动就是从头到尾的报错。所以这个项目我用的是 Spring Boot 2.7.18 + JDK 8，这也是目前国内中小型项目兼容性最稳的组合。

用 IDEA 创建项目时有几个细节值得注意：Spring Initializr 默认的 Server URL 可能连国外源很慢，建议把 Server URL 改成阿里云镜像。依赖选择上，只勾选 Spring Web、MyBatis Framework 和 MySQL Driver，Redis 和 Validation 可以在 pom.xml 里手动添加，这样创建速度更快，也不容易因为网络问题失败。

项目包结构我按功能模块划分而不是按技术层次划分，这是实际项目里很重要的一点：

code复制com.hospital.appointment
├── controller        # 接口层，只处理请求参数和返回
├── service           # 业务逻辑层
├── mapper            # 数据访问层
├── entity            # 数据库实体
├── dto               # 数据传输对象
├── vo                # 视图对象
├── config            # 配置类（Redis、拦截器、WebMvc）
├── common            # 公共类（统一返回、异常处理、工具类）
└── task              # 定时任务

统一返回结果用 Result<T> 包装，包含 code、message、data 三个字段，所有接口统一走这个格式。异常处理用 @RestControllerAdvice 全局捕获，业务异常统一抛 ServiceException。这样小程序端处理返回值非常方便，只看 code 就行，不需要每个接口单独判断，省掉大量重复的状态码判断逻辑。

2.2 数据库表结构设计

表结构是这套系统的地基，我设计时会反复提醒自己，乡镇医院场景下数据量不大，但逻辑不能少。核心涉及到六张表：

• sys_user：用户表，包含 openid、手机号、姓名、性别、年龄等字段
• hospital_department：科室表，包含科室名称、排序号、状态
• hospital_doctor：医生表，包含姓名、所属科室ID、职称、简介、头像URL、状态
• doctor_schedule：排班表，包含医生ID、排班日期、开始/结束时间、总号源数、剩余号源数、状态
• appointment_record：预约记录表，包含预约编号、排班ID、用户ID、就诊人姓名、手机号、预约状态（待就诊/已取消/已完成/爽约）
• notification_message：通知消息表，包含用户ID、标题、内容、类型、已读状态

关键设计逻辑在第一张预约记录表上。每个预约记录冗余了医生姓名、科室名称、就诊人姓名、手机号、就诊日期、时段，而不是通过外键去关联查询。这是典型的空间换时间策略，因为小程序端“我的预约”页面如果每次都要关联四五张表，查询效率会明显下降，而且冗余字段在展示层几乎不需要额外处理。

排班表是另外一张关键表。医生排班不是直接存名字和时间，而是存排班模板生成的实例。一条排班记录包含医生ID、日期、时段、总号数和剩余号数。这里的总号数和剩余号数是核心字段，所有并发控制都会聚焦在这上面。

2.3 号源并发控制与预约核心接口

号源并发控制是整个项目里技术含量最高的地方，也是面试官最爱深挖的部分。先说我踩过的坑：第一版用“先查剩余号数，大于0就减一”的常规写法，结果模拟并发测试时轻松就超卖了，30个号源在100并发下直接卖出42个号。这个场景像超市限时抢购，如果不做并发保护，库存就失控了，区别只是挂号超卖会造成约了号没号可看，这问题在医疗场景极其严重。

解决方案用了组合拳：数据库乐观锁 + Redis分布式锁双层保护。

先看数据库层的乐观锁，在 doctor_schedule 表加 version 字段，更新时带上版本判断：

sql复制UPDATE doctor_schedule
SET remain_number = remain_number - 1,
    version = version + 1
WHERE id = #{scheduleId}
  AND remain_number > 0
  AND version = #{version}

这样更新操作本身就是一个原子判断，不会出现“读到一个旧值再写回”的覆盖问题。如果更新影响行数为0，说明号源已经被抢完或版本冲突，直接抛出“号源不足”的业务异常。

Redis分布式锁用在提交预约接口上，锁的key设计为预约记录的幂等控制。用户点击“提交预约”后，先用用户ID加锁，防止同一个用户疯狂点击重复提交，锁过期时间设5秒。同时前端按钮也要做防重复提交处理，双保险才放心。

预约接口的完整流程是：参数校验（排班是否存在、日期是否过期）→ 加Redis锁 → 校验用户是否已预约同一时段 → 乐观锁扣减号源 → 生成预约记录 → 发送通知 → 释放锁。任何一步异常都要保证事务回滚，不会出现号扣了但预约记录没生成的情况。

写接口还要注意一点，数据库事务内部不要执行耗时操作。一开始我把微信订阅消息的发送放在事务方法里，结果Redis连接超时会导致整个预约回滚，后来把通知发送改成事务提交后异步处理，问题就消失了。

2.4 自动装配原理与配置实践

既然热搜里大量出现“springboot自动装配”，那就顺便把这块讲透，因为它直接关系到项目的可维护性。Spring Boot 最核心的魔法就是 @SpringBootApplication 里的 @EnableAutoConfiguration，它的本质是扫描 META-INF/spring.factories 文件里的自动配置类，按条件注解按需装配。

我对接了Redis、MyBatis-Plus、定时任务，每个都有自己的自动配置。实际开发中建议的配置方式是在 application.yml 里面显式写清楚自己的配置，避免过于依赖默认值。比如 Redis 配置，我会写上：

yaml复制spring:
  redis:
    host: 127.0.0.1
    port: 6379
    timeout: 3000ms
    lettuce:
      pool:
        max-active: 8
        max-idle: 8
        min-idle: 0

还有MyBatis-Plus的分页插件需要手动配置，这属于典型的“自动配置覆盖不到”的场景。在配置类里加一个 MybatisPlusInterceptor 的Bean，注册 PaginationInnerInterceptor，才能让分页查询生效。我还设置了 mapper-locations 的路径，避免XML文件找不到的经典报错。

3. 小程序端核心实现：从登录到预约

3.1 微信登录与code换token的完整流程

小程序端的用户体系不能自己造轮子，必须依托微信登录能力。核心流程是：小程序调用 wx.login() 获取临时 code，把 code 传给后端，后端用 code 调用微信接口换取 openid 和 session_key，然后把 openid 作为用户唯一标识存入数据库，同时生成自定义 token 返回给小程序，小程序后续请求都带上这个 token。

很多人对“微信小程序用code换token”这一步不熟，其实后端代码就几行，但要注意几个细节。第一步是正确配置小程序的 appid 和 secret（不要硬编码在前端，这是安全隐患），第二步是请求微信接口时要用 HTTPS，第三步是 token 要设置过期时间（我用 JWT，有效期设7天，用户每次进入小程序自动静默续期）。如果用户删除小程序重新进入，需要用 openid 重新匹配用户。

手机号绑定这里有个合规要求：小程序必须通过微信官方“手机号快速验证”组件获取，不能用 input 框让用户手动输入。这也是现在很多小程序备案审核的重点审查区域。获取到手机号后，如果用户没有绑定过，就更新 sys_user 表的手机号字段；如果手机号已经被其他账号绑定，提示用户联系管理员处理，直接合并账号也不合适，可能引发隐私问题。

3.2 预约流程页面设计与动态设置标题

小程序端页面结构分四大块：首页（科室/医生展示、搜索）、预约页（选科室、选医生、选日期时段）、我的预约页（记录列表、取消/详情）、个人中心页（用户信息、就诊人管理）。

重点讲预约页，用户路径是“选科室 → 选医生 → 选日期 → 选时段 → 填就诊人 → 确认预约”，整个过程要尽量控制在3到4个页面内，否则乡镇用户很容易因操作繁杂而中途放弃。我最终用的是“科室医生列表页”+“排班选择页”+“确认预约页”三个页面的模式。

关于小程序头部标题，这是个经常被忽略的细节，热搜里也有“小程序动态设置标题”，说明还是有不少人在处理这个功能。预约流程中，如果一个页面承载多个功能（比如同一个页面既展示科室列表又展示医生列表），就需要动态设置标题。用 wx.setNavigationBarTitle 就可以实现，我一般这样处理：

javascript复制onLoad(options) {
  if (options.type === 'department') {
    wx.setNavigationBarTitle({ title: '选择科室' })
  } else if (options.type === 'doctor') {
    wx.setNavigationBarTitle({ title: '选择医生' })
  }
}

动态标题的意义不只是体验，对用户理解当前所处流程有实际帮助。另外，自定义导航栏的高度适配也是老问题，不同机型顶部状态栏高度不同，使用 wx.getSystemInfoSync() 拿到状态栏高度，再动态计算导航栏高度，避免顶部元素被刘海屏遮挡。

3.3 组件选型与关键交互细节

预约流程用到的关键组件有几个值得单独说说。

第一个是微信小程序单选框，选就诊人时很多人会用 radio-group 配合 radio 实现，但有个坑：默认的 radio 样式非常丑，而且点击区域小，对不熟悉智能手机的老年用户不友好。我更推荐用 van-radio（Vant Weapp）配卡片式布局，或者直接用自定义点击事件配合选中状态的样式切换，实际效果更好，点击区域可以放大到整个卡片。

第二个是“确认预约”按钮的处理。既要防重复点击（前端加 isSubmitting 状态），又要防用户退出页面后再回调导致状态错乱，所以在 onUnload 里要把提交中的请求标记为取消，这个细节虽然小，但是体验提升明显。

第三个是预约记录的状态展示，我用小程序端的分段器组件做“全部/待就诊/已完成/已取消”四个筛选项，配合一个列表滚动。列表数据用分页加载，每次加载10条，上拉触底加载更多。

还有个值得分享的经验：小程序的模板消息已升级为订阅消息，预约提醒和停诊通知需要用户一次性订阅。这里要注意，订阅消息的模板ID必须在小程序后台申请，而且用户订阅一次只能发送一条通知，所以在“确认预约”页面要设计订阅消息的引导位置，让用户点击订阅后提交预约，才能确保后续能收到通知。如果用户拒绝订阅，预约依然要成功，只是收不到通知而已，但不能因为订阅被拒绝就中断预约流程，这个边界要处理清楚。

4. 管理后台与排班配置

4.1 基于Vue的运维端整体设计

管理后台是医院运维的核心，我用的是Vue 3 + Element Plus的组合，和Spring Boot后端形成典型的前后端分离结构。这个后台不需要太复杂，但必须覆盖这些功能模块：科室管理、医生管理、排班管理（按周模板设置）、号源查询与调整、预约记录查询（条件筛选+导出）、停诊管理、通知发送、数据统计。

管理员创建排班时，我故意把“排班模板”和“实际排班”分开设计。排班模板是医生每周固定出诊时间的模板（比如周一上午、周三下午），管理员可以直接把模板应用到某个日期范围生成实际排班。这样乡镇医院每周只需点一次“应用模板”就能生成一周的排班，再针对节假日和临时停诊做微调，运营效率提升非常明显。

后台和普通管理系统相比，最需要细抠的是权限控制。我实现了简单的RBAC模型：管理员（超管）可以配置所有内容，医生只可以查看自己的排班和预约记录，导诊人员可以查询预约记录但不能修改排班。用Spring Boot的拦截器结合自定义注解实现接口权限校验，操作简单、代码侵入性也小。

4.2 排班调整与停诊联动的特殊设计

这里有个容易被忽略但非常核心的场景：医生临时停诊或排班调整时，已经预约成功的患者怎么办？

处理方案我分三个层级。如果医生全天停诊：管理员在后台把该排班的状态从“开放”改为“停诊”，系统自动给所有已预约该排班的用户发送停诊通知，同时推荐改约到该医生后续可用排班；如果仅某个时段停诊：只取消该时段的预约记录；如果医生临时请假且未来排班都被取消：要给患者一个“改约”入口，用户在小程序端看到停诊卡片，点击“改约到其他时间”，选择新的排班重新提交。

改约的接口设计也有讲究。不能直接走“取消旧预约+新建预约”的两步操作，因为这两步之间用户的号源可能被别人抢走。正确的方案是在一个事务里完成：锁定原排班、检查新排班余号、执行原预约状态变更（改为“已改约”）、创建新预约记录、扣减新排班余号。整个流程虽然是两个动作，但对用户来说必须表现为一个原子操作。

另外提醒一下，排班调整对核心业务影响很大，后台操作排班调整时，前端最好弹窗提示“本次操作将影响N条预约记录，是否确认执行”，防止管理员误操作导致大量用户受影响。

5. 联调部署与高频问题排查实录

5.1 前后端联调的三个高频问题

联调阶段是最容易出现“你觉得没问题但我这明明不行”的矛盾期，这里整理了三个最常遇到的问题和我的排查经验。

第一个是跨域问题。前后端分离部署时，开发环境下后端接口和小程序本地调试的域名不同，需要后端配置跨域。我建议在后端写一个 WebMvcConfigurer 的配置类处理 CORS，而不是在小程序端 request 里强行设置header，因为小程序端设置跨域头是无效的。生产环境则一般建议用Nginx反向代理统一入口，前端请求都走同一个域名。

第二个是请求时间格式问题。Java后端默认的日期时间格式是 2024-01-15T10:30:00，小程序端直接展示会变成一串奇怪的字符串。解决方式是在后端配置统一的时间格式化，我用的方案是配置Jackson的 LocalDateTime 序列化格式，加上 @JsonFormat(pattern = "yyyy-MM-dd HH:mm") 注解，规则统一比较好维护。

第三个是统一异常处理联调时的覆盖面问题。一开始只处理了 ServiceException，结果漏掉了参数校验异常。前端提交空数据时直接返回了500错误，页面显示“系统繁忙”，但实际是参数没传全。后来补充了 MethodArgumentNotValidException 和 BindException 的全局处理，前端才能提示“就诊人姓名不能为空”这种准确信息。

5.2 部署上线与备案备注实操

部署环境我建议选轻量应用服务器即可，2核4G的配置跑这套系统绰绰有余。部署架构是：Nginx 承载静态文件与反向代理，后端 Spring Boot 打成 jar 包运行（用 systemd 管理服务），MySQL 和 Redis 部署在同一台服务器或用云数据库。

后端打成 jar 包后，有个建议是不要在服务器上直接 java -jar app.jar 这样裸跑，而是写一个 systemd 服务单元文件，实现开机自启和崩溃自动重启。我通常还会配合一个简单的 shell 部署脚本，实现拉取代码、执行构建、停旧服务、启动新服务、查看日志一条龙完成。

小程序上线前必须完成备案。热搜里有“小程序备案备注信息怎么填”，这里实操时还真是有不少细节。小程序备案时的“备注信息”不是随便写的，需要说明经营范围或服务内容，比如“本小程序用于乡镇医院线上预约挂号服务，为用户提供科室查询、医生排班、在线预约等功能”，要写具体，不能写“技术服务”“信息服务”这种模糊表述。性质选择要选“医疗卫生服务”相关的分类，如果医院没有互联网医院资质，运营范围就要谨慎，绝对不能涉及在线问诊、开药等功能，这是合规红线，项目说明书里要明确标注“仅做预约，不做诊疗”。

小程序后台还需要配置业务域名和服务器域名。request、uploadFile 合法域名必须是 HTTPS，并且要在小程序管理后台配置。上线前确保服务器已经配置好SSL证书，建议直接用云厂商免费的SSL证书，一年一换虽然麻烦但够用。

5.3 常见问题速查表

把整个开发过程中容易踩的坑整理成速查表，方便大家直接对照排查：

5.4 部署后性能与监控的几点经验

部署上线不是终点，运行监控也要跟上。挂号预约系统对可用性要求不低——用户正在预约时服务挂了，影响的是患者对医院的信任。

日志方面，我建议至少保留三个维度的日志：访问日志（记录每个接口的耗时和状态）、业务日志（记录预约创建、取消、改约的关键动作）、异常日志（记录异常堆栈）。配合 logback-spring.xml 按天滚动切割日志文件，定期清理旧日志，避免磁盘被塞满。

监控方面，不用一上来就上整套Prometheus+Grafana，太重了。简单的方案是写一个定时任务，每5分钟ping一次核心接口，失败就调用告警接口通知管理员。再配合Spring Boot Actuator暴露健康检查端点，配合云厂商的监控告警，基本就能保证第一时间发现服务异常。

另外数据库连接池的参数也值得注意。我用的是HikariCP（Spring Boot默认），在小并发场景下要调低 maximum-pool-size，连接池开太大（比如默认10）对乡镇医院这种日预约量只有几十上百的项目来说，资源浪费明显。调成5就足够了，既减少了空闲连接的内存开销，也避免数据库连接数超限。

6. 实操心得与扩展建议

这个项目从设计到上线，前后调整比较大的地方有两个，都是“做完才明白当初为什么那么设计”的典型。

第一个是排班模板和实际排班的拆分。最初直接让管理员手动创建每一天的排班，运营人员反馈工作量太大，后来改成模板生成机制，管理员只需要每周五花两分钟应用下周模板，再处理节假日和临时调休即可。这个改动让后台的使用意愿高了很多——系统做出来没人用等于白做，这个道理在B端项目里是最重要的。

第二个是停诊改约的一体化流程。最初也是设计成“取消再约”，结果测试时就发现新号源会被抢走，用户怨气很大。改成事务内原子化改约后，体验提升立竿见影。这些经验都验证了一个原则：核心业务流程，尤其是涉及资源扣减和状态变更的操作，宁可代码写复杂一点，也要保证用户侧是简单的、安全的。

后续如果要扩展，可以考虑的方向包括：患者电子健康档案的接入（复诊时医生能直接看到历史就诊记录）、候诊队列的大屏展示（结合门诊叫号系统）、以及微信提醒的加强（现场取号报到、检验报告出结果通知）。这些功能在架构上都是可插拔的，不影响现有核心链路。

最后再分享一个小技巧：这类预约系统上线后，第一个月一定要安排专人盯预约数据，如果出现大量“预约未到诊”的记录，大概率不是系统问题，而是周边居民还不知道怎么用小程序。可以在医院门诊大厅放一个易拉宝，引导用户扫码，第一次使用时由导诊台护士帮忙演示一遍。资料显示，乡镇级医疗信息化的成败往往不在技术，而在运营推广，这个话放在这里同样适用。