1. 为什么是uniapppython而不是原生小程序或Java后端1.1 前端技术栈的取舍逻辑医院预约挂号这类系统最麻烦的不是功能有多复杂而是“触点太多”。患者可能用微信小程序挂号医生护士可能用平板看排班管理人员可能要在PC浏览器里维护科室和医生信息。如果每一端都单独开发原生的东西成本直接翻倍。选uniapp就是冲着一套代码同时输出小程序、H5和App去的。拿我做的这个项目来说核心场景是微信小程序端但后台管理界面我用的是同样的uniapp项目跑H5只是路由和权限做了区分。这样前端只需要维护一份代码改个bug不用在小程序和H5里各改一遍。很多团队做医疗类项目时还抱着“微信小程序就必须用原生语法”的思路实际上如果未来要考虑支付宝小程序、百度小程序或者要做App壳uniapp的跨端能力能省掉大量的重复工作。1.2 为什么后端选Python而不是Java技术选型的时候同事也讨论过要不要上Spring Boot。说实话如果是大型三甲医院的全院级系统几十个微服务、高并发挂专家号Java确实是更稳的选择。但预约挂号这个场景核心是业务逻辑清晰、CRUD为主、并发量集中在某个固定时间段Python完全扛得住而且开发效率高。Flask足够轻量路由简单配合SQLAlchemy操作数据库也很顺手。Python在数据清洗、统计报表这块也天生有优势。医院后续经常要拉数据做“科室挂号量排名”“医生出诊负荷分析”用Python的pandas直接能处理不需要再单独搞一套报表系统。这种后端选型本质上是“用80%的开发时间解决95%的需求”剩下5%的极端并发场景用架构手段去兜底就够了。1.3 整体架构长什么样整个系统就是经典的前后端分离结构前端uniapp编译成微信小程序负责用户交互、页面跳转、登录态管理后端Python Flask提供RESTful API处理预约逻辑、号源扣减、支付回调数据库MySQL存用户、科室、医生、排班、订单这些核心数据中间层Nginx做反向代理gunicorn跑Flask服务。你可能会问有必要分离得这么彻底吗有。因为医院的环境很特殊前端小程序和后端服务大概率不在同一台服务器上甚至小程序域名都要单独做ICP备案。前后端分离之后接口地址可配置前端打包时只需改一个baseURL后端怎么部署、怎么换服务器前端完全不用关心。2. 数据库设计才是预约挂号的核心表结构和防超卖方案2.1 核心表拆解预约挂号系统听起来业务简单但表设计做不好后续改起来会非常痛苦。我的做法是把“排班”和“号源”分开建模而不是让用户订单直接关联一张日期表。我实际用到的核心表包括用户表openid、昵称、手机号、创建时间科室表科室名称、科室简介、排序字段医生表姓名、职称、科室ID、头像、擅长领域、简介排班表医生ID、出诊日期、时段上午/下午/晚上、总号数、剩余号数、状态订单表订单号、用户ID、排班ID、医生ID、就诊日期、时段、状态、支付状态、创建时间、取消时间。这里有个关键点一个医生某一天的某个时段只有一条排班记录剩余号数是一个数字字段而不是给每个号生成一条记录。我见过有人把号源也建成一张表每个号一条记录挂了100个号就插100条数据这种设计在并发高的时候锁竞争非常严重纯属自找麻烦。用数字字段去控制剩余号量配合原子更新才是正确姿势。2.2 防超卖的关键SQL预约挂号的本质和黄牛抢票是一样的多个用户同时抢最后一个号。如果不做控制高并发下很容易出现“同一时段同一个号被两个人同时挂到”的问题。我第一次上线前用并发工具压测1秒内100个请求同时打过来剩余号数从5直接减到了-3超卖了8个号。这就是典型的“先select再update”的写法导致的竞态问题。正确的写法是单条原子更新UPDATE schedule SET remain_number remain_number - 1 WHERE id ? AND remain_number 0;然后检查这条SQL影响的行数影响1行说明抢号成功影响0行说明该时段已经没有号源了。这个方案不需要加锁也不需要事务因为数据库的单条更新本身就是原子操作在高并发下性能是最好的。如果你还要更稳一点可以在订单表创建时加一个唯一索引比如(schedule_id, user_identifier_encrypted)防止同一个用户重复挂同一个排班。当然从产品角度讲同一个用户重复挂同一个医生本来就应该被拦截这个接口层已经做了数据库兜底是为了防并发穿透。2.3 时间字段和“未来7天”的排班生成排班数据不是手工一条一条录入的。医院一般是每周生成一次未来7天的出诊计划所以我在后端写了一个定时任务每天凌晨自动检查未来7天的排班是否存在不存在就根据医生配置的出诊规则自动生成。这里有个容易踩的坑时区问题。很多人直接把datetime.now()存进去导致小程序端显示的时间跟服务器时间差8小时。我的做法是数据库统一用DATE和TIME类型存日期和时段不存带时区的timestamp后端生成排班时明确用东八区时间计算。这样无论服务器部署在哪个地区患者的就诊日期都不会错。3. 小程序端页面设计从科室列表到预约成功的完整链路3.1 首页科室分类与索引定位患者打开小程序最先看到的就是科室列表。一个三甲医院几十个科室直接平铺会很乱我更推荐按首字母索引或者按“内科、外科、妇儿、其他”这样的大类分组。uniapp里实现索引列表可以用scroll-view配合v-for渲染也可以用官方插件市场里的索引列表组件。我个人建议直接手写因为医院的科室分类往往不是单纯的字母顺序而是有业务上的排列优先级比如“儿科、产科”这种高频科室要放在靠前的位置手写可控性更强。科室列表的接口设计也要注意返回字段不需要太多科室ID、名称、图标、简要描述、今日可挂号状态就够了。过多的字段除了增加小程序的渲染负担没有实际价值。3.2 日期选择和医生出诊时段展示这个页面是整个小程序交互最复杂的部分。患者选完科室之后要能看到医生列表点进医生后看到排班日历。日历组件我踩过坑直接拿第三方日历组件改功能是够用但是包体积会增加而且UI风格很难和项目现有设计统一。后来我改成自己封装一个极简的日期选择条——横向滚动的未来14天日期列表每个日期显示“今天”“明天”或“周几日期”下面再放当前日期该医生的出诊时段。时段按钮的状态有三种可选有号绿色、约满灰色禁点、停诊红色禁点。这个状态由后端接口直接返回前端只做展示不要在本地做任何判断。因为有些停诊的调整是管理员在后端手动改的前端如果缓存了旧的排班状态患者会看到错误的号源。3.3 订单确认与支付环节的体验把控选好医生和时段之后患者进入确认订单页。这一页要展示的信息包括患者姓名默认取微信昵称可修改、就诊人手机号用于接收通知、就诊科室和医生、就诊日期和时段、挂号费。确认页有个细节手机号不能直接拿微信的自动填充。微信小程序目前提供手机号快速验证组件但需要企业主体申请而且接口是收费的。个人开发或者企业内部系统我的建议是让用户手动输入并做一个简单的正则校验1开头、11位数字。如果对真实性要求高可以再接短信验证码但医疗场景下手机号主要用于通知简单校验足够。支付环节我用的是微信支付统一下单有商户号就能接。支付成功后小程序会收到uni.requestPayment的成功回调但要注意——支付结果不能只听前端必须以后端回调为准。前端回调只能用来跳转页面真正的订单状态修改要等微信服务器把支付结果通知到后端接口后才执行。3.4 网络请求封装和登录态管理uniapp开发小程序时uni.request是每次都要用的API。如果不做封装每个页面里都要写一遍success/fail回调代码会丑到没法看而且token的携带、错误提示、401跳转这些公共逻辑根本没法统一处理。我封装了一个简单的请求模块核心逻辑是把uni.request用Promise包一层请求头自动带上Authorization值是登录后缓存的token响应码统一判断401强制重新登录500弹全局错误提示后端返回的code0才是业务成功不是HTTP 200就代表成功。登录流程用的是微信小程序的标准方式uni.login获取code然后把code传给后端后端再拿code去微信接口换openid。换到openid之后后端生成一个自己的token返回给前端前端存到uni.setStorageSync里。注意openid和session_key都是敏感信息不能直接暴露给前端前端只持有token。4. 后端接口设计与预约状态机订单状态不能乱跳4.1 接口清单与设计思路后端接口我按业务域拆了模块每个模块对应一组路由。核心接口如下科室模块GET /api/departments获取科室列表医生模块GET /api/departments/{id}/doctors获取科室下的医生排班模块GET /api/doctors/{id}/schedules?start_datexxend_datexx获取医师出诊排班预约模块POST /api/orders创建订单POST /api/orders/cancel取消订单GET /api/orders获取我的预约列表支付模块POST /api/pay/notify微信支付回调接口。接口命名就是很朴素的RESTful风格不要为了追求“高级”把接口拆得特别碎。医院里的对接场景里最怕的就是接口语义不清楚。比如“取消订单”和“退号”在业务上是同一个动作但在接口上如果你搞出两个不同的路由微信支付退款那边就会非常混乱。4.2 预约创建流程的全链路时序一个人从选号到支付成功后端经历的完整流程是这样的小程序端携带token和后端传schedule_id后端解析token得到用户标识校验排班是否存在、是否停诊、是否在预约时间范围内执行原子更新扣减剩余号数扣减成功生成订单号状态为“待支付”这一步要在事务中完成调用微信支付统一下单接口拿到预付单号返回支付参数给前端前端调起支付。我强调一下第4步和第5步为什么要放在同一个事务里因为如果扣了号源但订单创建失败号数就凭空少了如果先创建订单再扣号源又可能把最后一个号给多人创建订单。所以必须保证“扣号建订单”同时成功或同时失败。4.3 订单状态机哪些状态能跳哪些不能跳订单状态这个坑特别隐蔽但影响很大。如果没有明确的状态机开发过程中很容易写出“从已完成退号”这种业务上不该出现的状态。我定义的状态流转是待支付下单成功但未付款用户可以自己取消超时15分钟后系统自动取消并归还号源已支付支付回调确认后进入此状态也可以叫“已预约”此时用户不可直接取消要取消必须走退号流程已完成就诊日期当天结束后系统自动把当天的预约标记为已完成已取消用户主动取消或系统超时取消已退费已支付状态下的用户取消预约退款完成后的终态。状态机在代码里的实现不要只靠if-else乱写最好是建立一个“当前状态→允许的动作→目标状态”的映射表。比如“已支付→取消→已退费”是合法的但“已完成→取消→已退费”就要直接抛异常拒绝。这个逻辑写清楚之后后续就算有不同的人接手代码也不容易改出业务漏洞。5. 微信生态能力接入登录、支付、订阅消息的落地细节5.1 登录流程和服务端签发Token微信小程序的登录很多人以为就是前端uni.login一下就完事了。实际上uni.login拿到的只是临时凭证code这个code只能用一次而且5分钟内有效。真正要换取的是openid需要后端拿着code去调用微信的code2Session接口。这一步必须放后端原因有两个一是小程序前端的appid和secret不能暴露在代码里secret一旦泄露任何人都能冒充你的小程序调用接口二是微信接口返回的session_key是加密会话密钥涉及用户数据解密绝对不能下发到前端。拿到openid之后我再把用户信息查出来或新建然后生成一个自己的token我用的是JWT有效期的逻辑很关键。太短用户天天要重新登录太长账号被盗风险高。医疗类场景我一般设24小时有效配合7天内自动续期。因为患者不需要高频登录24小时足够覆盖一次完整的挂号流程。5.2 支付流程和回调验签支付环节是整个项目里最容易出问题的地方也是我调试时间最长的一个模块。先说基本流程前端创建订单后后端调用微信支付的统一下单接口传入金额、订单号、回调地址、openid等参数微信返回prepay_id。后端用这个prepay_id再生成支付参数返回给前端前端调用uni.requestPayment拉起支付。这里我遇到的最典型的坑是签名。微信支付的签名算法虽然文档写得很详细但参数顺序、大小写、URL编码这些细节但凡错一个就会报签名错误。排错的时候建议把请求参数按字典序排序后手动拼接一遍再用工具比对一下签名结果效率比猜要高得多。再说回调微信服务器在支付成功后会往你的回调地址POST一段XML数据。回调接口要做三件事验签确认数据确实来自微信校验订单金额防止有人伪造回调更新订单状态返回微信要求的成功应答XML。整个回调其实就是一个“幂等”的过程。如果微信重复回调你要保证不会重复给用户加余额、重复改状态。在订单表里加一个pay_status字段回调里先判断当前状态如果已经是已支付就直接返回成功跳过更新逻辑。5.3 订阅消息预约成功通知和停诊通知患者预约成功后一般会希望收到一条消息提醒比如“您已成功预约X月X日X科室X医生”。微信小程序里这个功能叫订阅消息而且是“一次性订阅”。这个设计的坑在于时机必须在用户操作的时候弹窗请求授权等支付成功后再请求授权用户已经错过了弹不出来。所以我在确认订单页面用户点击“提交预约”按钮的同一时刻就调用uni.requestSubscribeMessage去申请订阅授权。用户同意后后端在订单创建成功或支付成功时推送订阅消息。还有一类重要通知是停诊通知。医生临时停诊患者已经预约的号需要提醒。但微信的一次性订阅消息不支持“事后补发”用户没有提前授权停诊时就发不出去。我目前的方案是把订阅授权记录在用户表里停诊时能发几条是几条发不了的就通过短信补。注意短信接入需要资质合法合规的前提下订阅消息是主力短信是兜底。6. 真机联调与部署阶段踩过的坑和稳定运行的建议6.1 小程序域名校验开发环境与生产环境的差异开发阶段调试最舒服的方式是在微信开发者工具里勾选“不校验合法域名”。但真机预览的时候这个选项是不存在的手机上的小程序会直接拦截所有非HTTPS、未备案域名的请求。我在第一次用真机测试的时候忘了把小程序的合法域名加到小程序管理后台的“request合法域名”配置里结果一上线就发现所有接口请求全部失败页面数据一片空白。排查了半天才发现是域名白名单没配。同时还有一件很容易被忽略的事后端接口地址必须用域名不能用IP。微信小程序对合法域名的要求是必须是HTTPS协议、域名必须ICP备案、必须在小程序后台配置白名单。如果你的服务器还没备案千万别急着上线可以先开发调试备案下来再切换线上地址。6.2 高并发实测号源扣减的最终压测结果系统写完以后我用压力测试工具对核心的“创建订单”接口做了一轮模拟测试。场景设置是一天内某个热门科室的号源剩余10个10秒内连续发起500个预约请求。结果让我比较满意剩余号数从10减到了0最终生成了10条成功订单其余490个请求全部返回“号源不足”。没出现一例超卖也没出现重复预约。这得益于前面讲的原子更新SQL和事务控制。但有一个隐藏问题暴露出来当并发量到500的时候MySQL的连接数被打满了部分请求直接超时。这个问题的根源不在代码而是数据库连接池配置太小。后来我把连接池的上限调大同时给Flask那边也加了连接池复用问题就解决了。这里要提醒一句做压测不要只看功能正确也要看系统的并发承载能力尤其是医院这种场景每天早上8点是挂号高峰如果在这个时段系统卡死影响面是很大的。6.3 部署环境建议传统服务器比云托管更适合医院部署方案这里我有自己的倾向性。一开始我也试过把Flask服务放在云托管平台管理是方便付费透明但是有两个问题一是冷启动延迟早上高峰期的第一个请求可能要等好几秒才响应二是自定义域名和HTTPS证书的配置在云托管平台上灵活性不够。后来我改成了传统做法一台具有公网IP的服务器装Nginx gunicorn MySQL。Nginx负责处理静态资源、反向代理和HTTP转发gunicorn负责跑Flask应用。HTTPS证书直接用免费的域名证书就够了一年一续。这套组合的稳定性我用到现在没出过大问题。日常维护也很简单更新代码只需要git pull然后systemctl restart服务就行。医院信息科的人如果自己管服务器这套方案的学习成本是最低的。6.4 上线后我最后悔没早点做的事如果让我再重来一次有几个事情我一定会提前做第一日志体系要早搭。最开始我只有print输出和Flask默认日志出了问题翻半天也找不到原因。后来加了统一的日志模块按天滚动保存把请求参数、用户ID、接口名、耗时、错误信息全部打出来排查问题的效率提升了十倍。第二定时任务要加告警。排班生成脚本如果某天挂了第二天患者看到的就全是“停诊”。我加了一个简单的告警逻辑如果当天生成排班的数量为0就往管理员的手机推送一条消息。第三订单数据要定期做一致性校验。每周写个脚本比对订单表和排班表的数据看有没有订单存在但号源没扣、或者号源扣了但订单不存在的脏数据。这种问题在接口异常的时候很容易产生靠人眼根本看不出来。