新生儿疫苗预约小程序开发实战：后端防超卖与状态机设计

如果你想找一个既有后端业务复杂度、又能在微信小程序端完整跑通的项目来练手，这套社区新生儿疫苗预约小程序（源码编号 26885）是很典型的样例。我见过很多同学做预约类系统，最后做成了“一张报名表 + 一个列表”，数据库里塞一张 appointment 表就完事。真正放在社区卫生服务中心场景下，疫苗预约要解决的问题比想象中多：哪些疫苗在哪些日期有号、同一天不同疫苗会不会冲突、同一个宝宝能不能重复约、门诊医生打完针之后怎么把记录归档、家长放鸽子之后号源怎么释放，这些都需要在业务设计初期就想清楚。

这篇文章会按照这个项目的前后端完整链路来拆。后端是基于 Spring Boot 开发的服务端，存储用的是 MySQL，持久层搭配 MyBatis Plus；前端是原生微信小程序，面向家长端提供疫苗目录、排班查询、在线预约、接种记录等功能。项目整体结构不复杂，但非常适合用来理解“社区医疗预约类业务”的核心建模，也适合准备毕业设计或者想提高项目经验的人反复读源码。我会把数据库设计、核心接口实现、小程序对接逻辑、常见报错全部串起来讲，顺序就是我从这个源码里实际阅读和实践的顺序。

1. 项目挂在社区场景下的真实需求：疫苗预约绝不只是“加张预约表”

很多同学第一次看到这个标题，会觉得“社区新生儿疫苗预约”只是把商城秒杀预约换了个壳。实际不是。疫苗预约的难点在于它必须同时满足“人去得了”“苗有货”“时间对得上”“不重不漏”四个条件，单纯的 CRUD 很容易做出逻辑漏洞。

1.1 新生儿疫苗接种场景有哪些特殊约束

先说“人”的维度。疫苗服务的对象不是成人自己，而是新生儿。一个微信号下可能管理两个孩子，家长用小程序预约前，系统必须确认孩子档案存在、归属正确、出生日期能对上。比如“乙肝疫苗第 2 剂”，要求宝宝满 1 月龄到 6 月龄之间接种，如果后端不校验月龄就直接放号，那家长抢到号到了门诊也会被医生劝返，反而造成资源浪费。

再说“苗”的维度。疫苗目录不等于简单的商品表，疫苗和普通商品最大的区别是它存在“剂次”概念。同样是“脊灰疫苗”，有第 1 剂、第 2 剂、第 3 剂、第 4 剂；同样是“百白破疫苗”，前面几剂和后面的加强剂次不一样。所以 this 项目的表设计里一定要有一个字段明确表示“这是第几剂次”，并且要和宝宝的年龄范围做联动判断。很多照着商城抄的预约代码，在这一步就直接穿帮了。

还有“时间”维度。疫苗接种不是随时都能打，社区门诊通常会在每周固定几天开放接种门诊，比如周一、周三、周五的上午，并且每个开放日还会为不同疫苗分配不同数量的号源。如果简单把一天拆成几个时段再下单，容易出现两个问题：一是号源超约，二是家长能看到“今天可约”但实际日期对应的疫苗排班根本没开。项目源码里单独设计了一张排班表，就是为了把“疫苗”和“具体日期/时段/号源余量”对应起来。

1.2 这套源码包含哪些角色和业务闭环

我从源码的代码结构里看到的业务闭环是这样的：门诊医生或管理员先在维护页面维护好疫苗目录，然后为某一天、某个接种时段创建排班，填入总号源数量；家长通过小程序进入疫苗列表，选择一个宝宝，查看当前可预约的日期和剩余号源，确认后提交预约；到了接种当天，家长按预约时间到门诊，医生核对信息后把预约单状态改为已完成，并录入实际接种的疫苗批号、接种部位、接种医生等信息，形成可追溯的接种记录。

这其实就是社区卫生服务中心预防接种门诊的日常工作流。家长端能看到的“今日可约”“已约完”“待接种”“已完成”等状态，在后端都是通过一套状态枚举和关联表来维护的。源码中把家长端和管理端拆开处理，微信小程序面对的是家长，Spring Boot 接口同时服务小程序和管理后台，这也是实际项目常见的前后端分离布局。看这个项目时不能只盯着“下单”那一个接口，要把管理员端维护排班、家长端预约、医生核销这三个动作连起来读，才能理解字段为什么要那样设计。

2. 数据库和核心模块是怎么设计的：先看表再写代码

这个项目的后端代码包结构比较标准，主要分成 controller、service、mapper、entity、common 这几层。但我在读代码时习惯先看 SQL 初始化脚本，因为表结构能直接反映作者对业务的理解深度，尤其是字段约束和索引，比看一堆封装好的 Service 方法更有信息量。

2.1 核心表结构与字段设计思路

项目数据库里最核心的几张表是：用户表、宝宝档案表、疫苗表、疫苗排班表、预约订单表、接种记录表。我挑重点说明。

用户表对应的业务对象是“微信小程序用户”，核心字段包括微信号唯一标识、昵称、头像、手机号、注册时间。因为家长在小程序端是通过微信登录，所以该表应该有一列专门存微信侧的 openid，后续拿 code 换 session 时就是靠它来识别用户。这里注意：同一个手机号可能注册了两个账号，或者一个账号换了手机号，所以登录识别不能依赖手机号，要以 openid 为主。

宝宝档案表相对容易理解，一个家长可以建多个宝宝，所以宝宝表里要存家长用户 id，还要存宝宝姓名、性别、出生日期。出生日期这个字段在疫苗预约里极其重要，因为在业务规则上很多疫苗会限定月龄区间，后端要么在 SQL 里用出生日期计算月龄，要么在 Java 服务里做判断。考虑到查询列表要展示“这个宝宝适不适合打某支疫苗”，建议把月龄相关的计算放到服务层集中处理，避免到处写 SQL 片段。

疫苗表除了常规名称之外，还要有“适用月龄最小值/最大值”“建议剂次”“疫苗类型”“生产企业”等字段。之所以要区分剂次，是因为同一支疫苗可能打多针，每针的适用时间窗口不同。疫苗类型在这里建议区分“免费疫苗”和“自费疫苗”，方便列表筛选；但具体的医学判断还是要以门诊医生为准，系统只做业务规则辅助判断，不能替代医生。

排班表是整套系统的“库存表”，也是预约并发控制最容易出问题的地方。我把源码里的排班表核心字段简化成下面这样，方便理解。

sql复制CREATE TABLE `t_schedule` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `vaccine_id` bigint NOT NULL COMMENT '疫苗ID',
  `vaccine_name` varchar(50) NOT NULL COMMENT '疫苗名称冗余',
  `clinic_date` date NOT NULL COMMENT '接种日期',
  `start_time` varchar(10) NOT NULL COMMENT '开始时间，如08:30',
  `end_time` varchar(10) NOT NULL COMMENT '结束时间，如11:30',
  `total_number` int NOT NULL DEFAULT 0 COMMENT '总号源',
  `remaining_number` int NOT NULL DEFAULT 0 COMMENT '剩余号源',
  `status` tinyint NOT NULL DEFAULT 1 COMMENT '状态：1开放，0关闭',
  `create_time` datetime DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `idx_date_vaccine` (`clinic_date`, `vaccine_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='疫苗排班表';

排班表里把疫苗名称做了冗余，纯粹是为了列表查询少一次 join。业务量不大的社区项目可以接受，但如果后续扩展成名副其实的省级平台，冗余字段要谨慎使用，容易产生数据一致性问题。total_number 和 remaining_number 是这一套预约的逻辑核心，前者表示放了多少号，后者表示还剩多少号。每次预约成功必须让 remaining_number 原子减一，这个操作看起来简单，却是超卖问题的高发地，我后面会重点讲。

预约订单表记录的是每一次预约动作，状态字段是本表核心，我用一个枚举来维护，先说明普通定义：预约成功等待接种、已完成、已取消、逾期未种。在数据库里一般用 tinyint 类型保存。订单上需要把 schedule_id、baby_id、member_id 都冗余进去，同时生成一个可读性较强的预约号。从实际使用角度来说，医生核销时扫一眼预约号就能定位，比用数据库自增 id 友好得多。

接种记录表则对应疫苗接种本上的实际记录，孩子打了哪支疫苗、哪一批次、在哪个门诊、哪个医生操作的，都记录在这张表。项目里这张表和生产批次信息关联，也就是记录里的 vaccine_batch_no，这样出了问题能回溯到具体的疫苗批号。

2.2 预约状态机与数据结构上的防重设计

很多代码初学者会把“预约状态”当作普通字段，随随便便 set 一下，结果后面统计报表时数据一团乱。这个项目值得学习的一点是：它在设计阶段就把预约状态转变路径理清楚了。待接种的预约可以因为用户主动取消而变成已取消；如果用户没有取消也没去接种，等当天的排班结束，定时任务会把预约状态改成逾期未种；只有医生在门诊按实际核销，才可以把待接种改成已完成，并且会额外生成一条接种记录。

这种状态流其实是在保护业务数据的真实性。为什么不能由前端直接调接口把预约改成已完成？因为如果不加限制，家长自己在家就能把记录改了，医疗数据就失去了可信度。所以在接口权限设计上，改已完成状态的接口必须绑定操作人，也就是登录后台的医生。阅读源码时应多关注 Controller 层到 Service 层的权限校验，理解哪些操作属于用户自助操作，哪些必须走后台。

防重设计也是同样的思路。一个宝宝能不能在已经约了周一上午的乙肝疫苗后，再约同一天上午的百白破疫苗？现场安排上不允许同一时段给孩子同时打多种预约单，所以在提交预约的 Service 中要按宝宝和排班维度去查有效状态。更硬的兜底方式是给预约订单表加一个联合唯一索引，比如 uk_baby_schedule (baby_id, schedule_id)，数据库层面保证同一个宝宝在同一排班下不可能存在两条有效订单。源码里通常不会只做唯一索引就结束，还会在状态字段上做筛选，因为允许同一宝宝、同一排班有“已取消”的历史记录，真正的拦截目标是“仍是待接种或已完成状态的记录”。

3. 后端 Spring Boot 实操拆解：预约接口、库存扣减和定时任务

数据库设计理清楚后，就能看懂后端代码里每一个 Service 方法在做什么了。我以源码编号 26885 中 Spring Boot 端的实现为例，从工程结构一路讲到最关键的预约接口。

3.1 工程结构与启动配置

后端工程是标准的 Maven 单模块结构，包名按 com.something.vaccine 划分。启动类在根包下，配置放在 application.yml 中，控制器统一接收前端请求，Service 层处理业务，Mapper 层面向数据库。MyBatis Plus 的作用主要是减少单表 CRUD 代码量，让开发者能集中精力处理预约这类复杂业务。

启动配置里需要注意的点不少。项目如果是在本机开发，数据源配置大概长这样：

yaml复制server:
  port: 8080
  servlet:
    context-path: /api

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/vaccine_appointment?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: 你的数据库密码

mybatis-plus:
  mapper-locations: classpath:/mapper/**/*.xml
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

这里把 context-path 设置成 /api，意味着所有接口访问前缀都是 /api 开头。很多同学部署后遇到 404，往往是忘记自己在配置里加过 context-path，导致前端请求路径和后端不一致。数据库连接串里的 serverTimezone 也要解释一句：MySQL 8 版本如果不指定时区，有可能出现插入时间和本地时间相差 8 小时的问题。在本地开发时可以临时设置 Asia/Shanghai，生产环境更推荐统一用数据库服务器的时区配置。

项目里还有一个常见的 Jackson 配置，主要处理 LocalDateTime 的序列化问题。如果代码实体用的是 LocalDateTime，而配置里没有注册 JavaTimeModule，前端拿到的可能是“2025-01-01T10:30:00”这种带字母 T 的格式。我建议在配置里直接固定一下。

java复制@Bean
public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() {
    return builder -> {
        builder.serializers(new LocalDateTimeSerializer(
            DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
        builder.deserializers(new LocalDateTimeDeserializer(
            DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
    };
}

这种小配置看似不起眼，但能避免小程序端在解析时间时多写很多兼容代码。

3.2 预约接口的实现核心：事务、锁和原子更新

预约接口是整套系统的核心，我把源码里最值得学习的逻辑抽出来讲。先看一个简化版的 Controller：

java复制@RestController
@RequestMapping("/appointment")
public class AppointmentController {

    @Resource
    private AppointmentService appointmentService;

    @PostMapping("/book")
    public Result book(@RequestBody @Validated AppointmentCreateRequest request) {
        Appointment result = appointmentService.book(request);
        return Result.ok(result);
    }
}

Controller 很薄，真正的逻辑都在 Service 里。Service 的伪代码如下：

java复制@Transactional(rollbackFor = Exception.class)
public Appointment book(AppointmentCreateRequest request) {
    Baby baby = babyMapper.selectById(request.getBabyId());
    VaccinationSchedule schedule = scheduleMapper.selectById(request.getScheduleId());

    if (baby == null) {
        throw new BusinessException("宝宝档案不存在");
    }
    if (schedule == null || schedule.getStatus() == 0) {
        throw new BusinessException("该疫苗排班未开放");
    }
    // 校验月龄是否在可接种范围内
    int month = calculateMonth(baby.getBirthDate(), schedule.getClinicDate());
    if (month < schedule.getMinMonth() || month > schedule.getMaxMonth()) {
        throw new BusinessException("宝宝当前月龄不在该疫苗建议接种范围内");
    }
    // 校验是否已有有效预约
    Long exists = appointmentMapper.selectCount(
        new LambdaQueryWrapper<Appointment>()
            .eq(Appointment::getBabyId, baby.getId())
            .eq(Appointment::getScheduleId, schedule.getId())
            .in(Appointment::getStatus, AppointmentStatus.WAITING, AppointmentStatus.FINISHED));
    if (exists > 0) {
        throw new BusinessException("该宝宝在此排班下已有有效预约");
    }
    // 原子扣减库存，防止超约
    int rows = scheduleMapper.reduceRemaining(schedule.getId());
    if (rows == 0) {
        throw new BusinessException("手慢了，号源已被约完");
    }
    // 构造预约单
    Appointment appointment = new Appointment();
    appointment.setAppointmentNo(generateAppointmentNo());
    appointment.setBabyId(baby.getId());
    appointment.setVaccineId(schedule.getVaccineId());
    appointment.setScheduleId(schedule.getId());
    appointment.setAppointmentDate(schedule.getClinicDate());
    appointment.setStatus(AppointmentStatus.WAITING);
    appointmentMapper.insert(appointment);
    return appointment;
}

这里最关键的扣减逻辑对应 Mapper 里的一条 SQL：

java复制@Update("UPDATE t_schedule SET remaining_number = remaining_number - 1, " +
        "update_time = NOW() WHERE id = #{id} AND remaining_number > 0")
int reduceRemaining(@Param("id") Long id);

我强烈建议你重点记住这条 SQL 的思路。它表面上是“剩余号减一”，实际上利用数据库的原子性保证了两点：第一，UPDATE 语句自带行锁，同一时刻只有一个事务能成功修改同一行数据；第二，remaining_number > 0 这个条件保证了没号时不会减出负数。用影响行数是否等于 1 来判断有没有扣成功，既简洁又可靠。

千万不要改成“先 SELECT 查询余号，如果大于 0 再 UPDATE”这种写法。就算代码里加了 synchronized 或者 JVM 锁，也只对单台服务器有效，一旦部署多实例，锁就失效了。数据库本身的原子更新是天然可靠的兜底方式，社区门诊预约的并发量级虽然不算特别大，但一旦在开放号源的瞬间涌入几百个请求，不处理并发一定会出现超约。

另外还要注意 @Transactional 只是保证原子性，不负责解决并发。真正防超卖靠的是 UPDATE 条件和唯一索引约束，不是事务本身。还有一个小细节：状态校验时我用了 in(WAITING, FINISHED)，为什么把已完成也排除在外？因为从家长体验角度讲，如果已完成过的疫苗还能再次预约，就可能出现同一天同一排班下留下两条记录。数据库唯一索引也可以兜住这种脏数据，但业务层尽量早拦截，异常提示会友好很多，也能减少无意义的数据库锁竞争。

3.3 定时任务与号源释放逻辑

除了预约接口，项目里还有一个容易被忽略但很重要的部分：定时任务。我看到的源码里用 @Scheduled 注解实现了一个每日凌晨执行的定时器，作用是处理“预约了但没去接种”的订单。因为家长预约后如果忘了取消，到了接种日没有到门诊，系统不能一直占用号源，把状态挂成待接种会阻塞后续统计。

处理思路通常是这样：每天凌晨把 clinic_date 早于当天、状态仍为待接种的预约单批量更新为逾期未种。如果排班表的设计是把号源在预约成功后立即减掉，那逾期状态要不要恢复 number？要分业务场景。部分项目会恢复号源，因为家长没去，门诊可以开放现场号；部分项目不会自动恢复，因为现场号源由医生手动释放，自动恢复可能导致系统号和现场号重复。这个项目的做法比较稳，预约成功后占用的号源不会因为逾期自动恢复，而是让管理员在后台查看实际到诊情况后决定是否补开放。如果需要实现自动释放，可以在更新预约状态的同时还原排班的 remaining_number，但这两个操作必须在同一事务里完成，否则可能出现号源释放了但订单状态还是待接种的情况。

写定时任务时还有一个 Spring Boot 细节提醒：默认线程池只有一个线程，如果项目里有多个 @Scheduled 任务，长时间执行的任务会阻塞后面的任务。在配置里单独设置线程池是更专业的做法，源码里也有对应的异步配置。看代码时不要只把注意力放在预约接口上，定时任务、清理缓存、生成预约号这些旁支逻辑，其实才是项目能否上线运行的关键。

4. 微信小程序端从登录到提交预约的完整链路

后端接口写得再完整，前端小程序对接不好，整个项目还是跑不起来。这套源码的小程序端是原生微信小程序开发，没有引入重量级框架，目录清晰，比较适合学习基础概念。下面我把从页面进入到最终预约成功的流程拆开。

4.1 小程序目录结构与应用启动初始化

小程序端的根目录下通常能看到 app.js、app.json、app.wxss，以及 pages 目录、utils 目录、components 目录。app.json 里注册页面路由和底部 tabBar，这个项目一般有首页、疫苗列表、预约记录、我的这四个主页面。app.js 里定义 globalData，至少会保存一个后端接口的基础地址，方便所有页面统一调用。

javascript复制App({
  globalData: {
    baseUrl: 'http://localhost:8080/api'
  }
});

在开发阶段，baseUrl 写成 localhost 或者局域网 IP 都没有问题，但一旦用手机真机预览，localhost 指向的是手机自身，不是电脑。初学者最常犯的错就是电脑上开发者工具能打开，换到手机就白屏报错。如果没有搭建后台服务器，可以先在小程序开发者工具里勾选“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”，这样本地开发才能正常发起请求。

utils 目录里的 request.js 可以统一封装 wx.request，同时携带 token、统一处理 HTTP 状态码，这块完全可以仿照常见的 axios 封装思路。核心就是返回一个 Promise 对象，避免每个页面都重复写 wx.request 的 success/fail 回调。

javascript复制function request(path, method = 'GET', data = {}) {
  return new Promise((resolve, reject) => {
    wx.request({
      url: getApp().globalData.baseUrl + path,
      method: method,
      data: data,
      header: {
        'Content-Type': 'application/json',
        'Authorization': wx.getStorageSync('token') || ''
      },
      success(res) {
        if (res.data.code === 200) {
          resolve(res.data.data);
        } else {
          wx.showToast({ title: res.data.msg || '请求失败', icon: 'none' });
          reject(res.data);
        }
      },
      fail(err) {
        wx.showToast({ title: '网络异常', icon: 'none' });
        reject(err);
      }
    });
  });
}

需要在 page 里引入并使用这个 request 方法。查看源码时你会发现，凡是页面里直接写 wx.request 的地方，基本都有重复代码的问题；而封装了公共请求方法的页面代码会干净很多。这也算是一个代码整洁度层面的评判标准。

4.2 疫苗列表、排班展示与预约下单交互

预约小程序主流程是：用户打开首页或疫苗列表页，先看到当前机构开放预约的疫苗列表；点击某支疫苗进入详情页后，能看到这支疫苗可以预约的排班日期和剩余号源；选择排班后，再选择宝宝档案，最后点击立即预约。

在进入预约页时，页面需要拿到“可约的排班数据”。接口参数一般会传 vaccineId 和 babyId，后端根据宝宝出生日期计算月龄，过滤掉当前月龄不符合的排班，并且只返回 clinic_date 在当前日期之后的开放排班。这样前端根本不需要知道月龄规则，后端直接把可约项算好返回即可。小程序端要做的只是把 schedule.remainingNumber 展示出来，如果等于 0，就把按钮置灰并显示“约满”。

提交预约时，我建议前端必须把 scheduleId、babyId 作为两个必要参数传给后端，不要只传一个疫苗 id。因为同一支疫苗在同一天可能有上午场和下午场两个排班，它们 id 不同，如果前端只传疫苗 id，后端口无法确定到底约了哪一个场次。同时提交前要在前端禁用按钮，防止用户连点两次产生两条订单。虽然后端有防重逻辑兜底，但一个排班同一用户其实不该重复提交，前端提前拦截体验会更好。

提交成功后，页面跳转到预约记录页，用户能看到这条预约的预约号、疫苗名称、排班时间、当前状态是待接种。这里注意：预约成功后显示的是排班上的 clinic_date 和 start_time，而不是下单时的当前时间。如果前端错把当前时间当预约时间展示，用户会误以为自己预约的是“现在”，这是新手开发时经常出现的问题。

4.3 微信登录态与 openid 的处理方案

小程序端的登录不是传统意义上的账号密码，而是通过 wx.login 获取一个临时 code，再把 code 发给后端，由后端调用微信接口换取 openid。代码上大致是这样：

javascript复制handleLogin() {
  wx.login({
    success: async (res) => {
      if (res.code) {
        const data = await request('/auth/login', 'POST', { code: res.code });
        wx.setStorageSync('token', data.token);
      }
    }
  });
}

后端收到 code 后，用小程序 appid 和 secret 请求微信的 code2Session 接口，拿到 openid。如果你的小程序还没有申请到正式 AppID，本地开发的确会遇到问题，因为 wx.login 能拿到 code，但云端换 openid 时 appid/secret 不匹配，登录会失败。通常的做法是先在微信公众平台申请一个测试号，或者注册一个小程序账号拿到正式 AppID，但要注意 appSecret 绝对不能暴露在小程序前端代码里。

为什么项目里后端要返回一个自定义 token，而不是直接把 openid 返回给前端？因为 openid 是用户在某个小程序内的唯一标识，如果每次请求都带着 openid，用户身份完全没被校验。后端在登录成功后生成一个 token 存到服务端或者通过 JWT 方式签发，前端后续请求放在 header 里，后端统一拦截校验，才能确认“当前请求来自已登录用户”。源码里你在 util 或 common 目录基本能看到一个拦截器，专门从 Authorization 头中解析用户信息。

5. demo 跑起来后的常见报错与排查清单

看源码最头疼的地方在于环境依赖。项目代码本身没问题，但自己电脑上跑的时候会冒出各种诡异问题。我把这套项目开发过程中最容易碰到的问题汇总成一个小清单，每一个都是真实踩过的坑。

5.1 启动和联调阶段的高频配置问题

第一个问题是“Spring Boot 启动失败，端口被占用”。很多同学电脑上开了多个后端服务，8080 端口已经被占用。解决方式很简单，要么改 application.yml 里的 server.port，要么用命令行查找并结束占用进程。注意如果改了端口，小程序端的 baseUrl 也要同步改，否则会出现后端启动了、但小程序请求一直失败的假象。

第二个问题是“前端小程序显示加载成功，但所有接口都报 404”。这种问题八九不离十是 context-path 没对齐。如果后端配置了 /api 前缀，小程序端请求路径就要写成 /appointment/list、/vaccine/list，而不是直接写 /appointment。源码里 Controller 类的 @RequestMapping 若写的是 /appointment，那么最终完整路径其实是 /api/appointment。排查时可以先用浏览器直接访问 http://localhost:8080/api/vaccine/list，看看用 Postman 能不能通，先确定后端路径本身没问题，再查前端请求路径。

第三个问题是“MySQL 连接报错 Public Key Retrieval is not allowed”。这个主要发生在 MySQL 8 版本，数据库连接串里最常见解决方案是加上 allowPublicKeyRetrieval=true。如果加上之后仍然报错，要检查数据库用户名和密码是否正确，以及当前用户是否有权限访问对应的数据库。初学者还会犯一个错误：本机 MySQL 服务根本没启动，或者装的 5.x 版本和驱动 8.x 不匹配，建议直接使用与 JDBC 驱动大版本一致的 MySQL 8。

5.2 预约场景下的并发和状态类问题

有一个非常经典的问题：为什么用户在页面连续点击两次，或者两台手机同时提交，数据库里还是出现了两条预约记录？原因在于只做了前端按钮禁用，没有在后端做防重。后端的防重不仅要查询当前是否存在有效订单，还要在数据库层面加联合唯一索引。查询的时候两条请求同时进来，两个事务都发现没有记录，于是都执行了插入。不要完全相信代码里的 if 判断，数据库唯一索引才是最可靠的兜底。

还有一个状态相关的问题是“取消预约后，号源没有恢复”。如果代码里取消预约只更新预约单状态，没有调用 scheduleMapper 的 release 方法把 remaining_number 加一，那么门诊的号源就会越来越少，最后明明有人取消了，家长还是约不上。排查方式很直接：查看取消预约的 Service 方法里，是否出现了两条 SQL，一条是 update appointment，另一条是 update schedule，且两个操作在同一个事务中。如果漏了后者，就是典型的号源不释放 bug。

5.3 上线部署前需要关注的几个细节

本地开发没问题不代表能直接部署上线。小程序的 request 合法域名要求其实是很严格的，正式环境下要求后端接口必须是 HTTPS，并且需要在微信公众平台把域名配置成 request 合法域名。也就是说，后端不能只跑在开发者的电脑上，必须部署到有公网地址的服务器，并配置 SSL 证书。代码层面还要注意几个点：数据库密码不能明文写死在配置里；上传到代码仓库前要检查 application.yml 里有没有本机地址和密码；日志尽量不打印个人敏感信息。

另外，项目中的定时任务也需要关注时钟问题。服务器时间和数据库时间如果不同步，预约状态可能会提前变成逾期、预约日期展示错乱。最简单的做法是在部署文档里统一说明用 Asia/Shanghai 时区，并确保操作系统、数据库连接串、JVM 默认时区三者一致。我在跑这套源码的时候就遇到过：后端日志时间正确，但是数据库插入时间少了 8 小时，最后排查出来是 MySQL 连接的 serverTimezone 没配置导致的。

6. 结语

我从这套源码里收获最大的地方不在某个惊艳的技术点，而在于它完整呈现了“预约类业务”必须思考的一连串问题：库存如何扣减、状态如何流转、号源如何释放、同一用户如何防重、前端和后端如何配合。这些都是课程作业里不会重点强调，但实际工作中每个系统设计面试官都很在意的地方。

最后分享一个我读源码时的习惯：不要一开始就打开 Controller 看接口列表，而是先把数据库脚本导入本地，然后把项目启动起来，用 Postman 手动把一个“创建排班—查询排班—提交预约—取消预约—再次提交”的完整流程走通，再回到代码里对照每一条 SQL。这样你能把业务流程和代码一一对应起来，以后自己写预约类项目时，脑子里会有一个清晰的业务地图，而不是一片模糊的框架代码。