Spring Boot智能宾馆预定系统：状态机与并发控制实战

在做宾馆预订这类系统时，我见过太多团队一上来就堆砌 Cron 定时任务、搞了一堆微服务，结果连房间库存和订单状态的一致性都没处理好。这个基于 Spring Boot 的智能宾馆预定系统，说到底是个非常典型的业务系统，核心不是“智能”这两个字，而是如何把房间状态、订单流转、价格策略这些琐碎又关键的逻辑，用 Spring Boot 那套成熟的生态干净利落地落地。这篇文章我会从项目整体的思路拆解开始，详细讲清楚技术选型、数据库设计、核心模块实现，以及我在实际开发中踩过的坑和排查过程，希望能给正在做类似管理系统的朋友一些参考。

1. 项目从零到一，先搞懂这套系统到底在解决什么问题

很多初学者拿到“宾馆预定系统”这种题目，第一反应是去画用例图、写需求文档，但真到了写代码的时候，脑子里只有“增删改查”四个字。这套系统真正难的地方，在于业务状态的流转，而不是 CRUD 本身。

1.1 “智能”二字体现在哪几个真实场景里

我理解这个“智能”不是说用了什么 AI 算法，而是系统能在无人干预的情况下，自动处理一些原本需要前台人员手工判断的逻辑。比如客人选好房型下单后，系统要能自动锁定房间、计算入住天数、生成订单金额；到了退房时间，订单状态要能自动从“入住中”翻转为“已完成”，同时释放房间资源；如果有客人取消订单，释放出来的房间要能立刻重新进入可预订列表，而不是等管理员半夜去数据库里改状态。

这个“智能”还有一层意思，是价格策略。周末、节假日、淡旺季，同一间房的价格应该是不一样的。系统里可以设计一套基于日期区间的价格表，下单时根据入住日期动态计算总价，而不是让前台拿着 Excel 表去手动改房价。我见过太多酒店管理系统把房价写死在房间表里，结果一到节假日，前台就开始手工改价格，然后又忘了改回来，导致客人按节假日高价下单后，系统却显示的是平日价，整个对账都乱了。所以这套系统在设计上，我会把“房价”当成一个独立于“房间”的维度来做，这是很多初级开发者容易忽略的点。

1.2 这套系统适合谁来参考、能解决什么问题

如果你是刚学完 Spring Boot 基础、想找一个综合性的练手项目，或者你是做毕业设计、课程设计需要一套完整可演示的管理系统，那么这套智能宾馆预定系统的代码结构和设计思路是很好的参考样本。它麻雀虽小，但五脏俱全——前端页面、后端接口、数据库表、权限控制、异常处理、状态机流转，全都有涉及。

更重要的是，它会教你如何用 Spring Boot 的四层架构去组织代码。控制层只做参数接收和响应封装，业务层专注处理业务规则，数据访问层负责和数据库打交道，实体层对应数据库表结构。我见过很多人把业务逻辑写在 Controller 里，几百行的代码全堆在一个方法里，刚开始写起来爽，后面改需求的时候痛不欲生。这套系统从一开始就会按照四层架构去拆，你可以直接当成一个标准模板来用。

2. 技术选型和四层架构，Spring Boot 在这里为什么是首选

技术选型这件事，很多人会纠结到底用 Spring Boot 还是 SSM，用 JPA 还是 MyBatis。我个人的观点很明确：做这种业务管理系统，Spring Boot 加 MyBatis 或者 Spring Data JPA，都是没问题的组合，关键看团队习惯和项目复杂度。但如果你问我个人推荐，我会选 Spring Boot 加 MyBatis，理由后面慢慢说。

2.1 四层架构到底怎么分，每一层的职责边界是什么

很多教程会把四层架构挂在嘴边，但真要落笔写代码，很容易把层与层之间的依赖关系搞乱。我在这套系统里用的分层方式是这样的，你可以直接当成模板：

实体层对应数据库里的表，一张表对应一个实体类，字段名和表字段保持一样，不写任何业务逻辑。控制层只负责接收前端请求、调用业务层接口、把结果封装成统一格式返回，不写任何 if else 业务判断。业务层是这套系统的核心，所有业务规则都写在这里，比如下单时先查房间有没有被占、计算价格、生成订单号，这些都是业务层的事。数据访问层就是一套 MyBatis 的 Mapper 接口，提供对单表或关联表的增删改查方法，不写业务逻辑。

提示：分层架构最忌讳的就是数据访问层返回实体对象，然后业务层又去改动这个对象的字段，最后把改完的对象再塞回数据库里。这样做看起来很省事，但代码一多，你会完全分不清这个对象到底在哪个环节被谁改过。我在这个项目里会严格要求业务层自己创建或组装需要的对象，数据访问层返回的实体只读，不改动。

2.2 为什么用 MyBatis 而不是 JPA，以及 Spring Boot 4.x 带来的变化

我之所以在这个项目里用 MyBatis，是因为宾馆预定系统的查询场景天然复杂。比如要统计某一天的入住率，要查出每个房型剩余的可预订房间数，这些 SQL 往往需要多表关联加条件判断，用 JPA 的 Specification 写起来非常绕。而 MyBatis 可以直接写 SQL，所有的查询逻辑一眼就能看明白，出了问题也容易排查。尤其是做这种偏业务型的系统，SQL 的可读性比对象关系映射的“优雅”要重要得多。

Spring Boot 现在很多人在讨论 4.x 版本的事情。如果你在网上搜索 Spring Boot 4.x，会发现大家讨论比较多的是哪里去找 DataSourceAutoConfiguration 这样的话题。其实在我做这个项目的时候，我用的还是 Spring Boot 2.7.x 和 3.x 的中期版本，所以我建议你初学者就不要去追求最新版本了，用稳定的 3.x 版本就好。4.x 刚出来的时候很多第三方组件的兼容性会遇到问题，比如 Jackson 的 JsonMapper$Builder 配置方式就调整过，没有必要为了赶新版本去踩这些坑。

2.3 数据库表结构怎么设计，才能既灵活又直观

数据库设计是整个系统的地基。我见过太多项目，代码写得挺漂亮，但数据库表设计得乱七八糟——订单表和房间表混在一个表里，价格字段散落在各个表里，关联关系全靠外键硬连。这套系统的表设计，我会按照下面这个思路来做：

房间表记录宾馆里每一间房的基本信息，比如房间号、房型、楼层、是否可预订。房型表记录标准间、大床房、套房这些分类。价格表比较关键，它记录每个房型在不同日期区间内的价格。订单表是核心，记录客人预订了哪个房间、什么时间段入住、订单状态是什么、总价是多少。客房订单关联表处理一个订单对应多间房的情况，虽然大多数订单可能只订一间房，但设计上仍然要为多人多房场景预留能力。

这里我特别想强调的是order_status_log表。很多系统只维护订单表里那个 status 字段，出了问题想排查却根本不知道它之前是什么状态、什么时候变的。加上这张日志表，每次状态变更都记录下来，一是方便给客人看订单履历，二是出了问题可以从日志回放整个生命周期。而且这个表设计起来很便宜，加不加外键也无所谓，就是一个纯粹的记录表。

3. 核心模块如何实现，订单状态机是整套系统的灵魂

如果这套系统只有一个地方值得反复琢磨，那一定是订单状态机。从客人提交订单到退房离店，订单会经历多个状态，每个状态都对应不同的业务动作，而且状态之间的跳转是有方向、有条件的。如果这套逻辑理不清，后面写并发控制、写取消订单功能的时候，你会被各种边界情况折磨到怀疑人生。

3.1 状态机怎么设计才清晰，状态流转图这样理解最容易

我先定义一个约定的订单状态集合，这里我用了整数来代表不同的状态，数据库里存整数，代码里用常量或者枚举来对应，这样做的好处是数据库层面一目了然，而且便于写 SQL 查询各类订单。状态定义大致是这样的：待支付、已支付待确认、已确认入住、已入住、已退房、已取消、已关闭。

这个状态机看起来简单，但你在写代码时要特别注意流转的合法性。比如“已取消”只能从“待支付”或者“已支付待确认”跳过去，如果已经“已入住”了，就不能取消，只能走退房流程。“已关闭”是超时未支付或者管理员手工作废的结果。所以我在业务层会写一个核心的状态校验方法，任何状态变更都必须先经过它，非法跳转直接抛业务异常。

// 状态校验伪代码示例 boolean canTransition(int fromStatus, int toStatus) { switch (fromStatus) { case STATUS_PENDING_PAYMENT: return toStatus == STATUS_PAID || toStatus == STATUS_CANCELLED || toStatus == STATUS_CLOSED; case STATUS_PAID: return toStatus == STATUS_CONFIRMED || toStatus == STATUS_CANCELLED; case STATUS_CONFIRMED: return toStatus == STATUS_CHECKED_IN || toStatus == STATUS_CANCELLED; case STATUS_CHECKED_IN: return toStatus == STATUS_CHECKED_OUT; default: return false; } }

这套校验看着简单，但它就是整个订单系统的核心防线。我在实际开发中就遇到过测试同学想绕过状态机直接改数据库，把订单从“待支付”改成“已入住”，这种操作如果不设防，会出现房间还没付款但已经入住的情况，最后变成糊涂账。

3.2 房间库存的并发问题怎么解决，分布式锁在这个项目里到底要不要用

宾馆房间的库存和电商的库存看着像，其实不一样。电商的商品库存动辄几万件，超卖几件影响不大，而宾馆的房间类型可能就几十间，任何一间房的重复预订都是重大事故。很多人一谈并发就直接上 Redis 分布式锁，其实在一个单体应用里，数据库层面的乐观锁或者悲观锁就足够解决问题了。

我的做法是在下单的整个事务里，先通过SELECT ... FOR UPDATE把目标房间的行锁住，然后检查房间状态和对应日期的订单，如果发现冲突就直接报错，否则插入订单并更新房间状态。这里用悲观锁是因为宾馆房间竞争比较激烈，而且单个事务时间很短，锁冲突的概率很小，用悲观锁反而逻辑最简单、不容易出错。

// 核心下单逻辑（事务方法） @Transactional public BookingOrder createOrder(CreateOrderRequest request) { Room room = roomMapper.selectByIdForUpdate(request.getRoomId()); if (room == null || !ROOM_AVAILABLE.equals(room.getStatus())) { throw new BizException("房间不可预订"); } boolean conflict = orderMapper.existsOverlappingOrder( request.getRoomId(), request.getCheckInDate(), request.getCheckOutDate()); if (conflict) { throw new BizException("该房间在所选日期内已被预订"); } BigDecimal totalPrice = calcPrice(room.getRoomTypeId(), request.getCheckInDate(), request.getCheckOutDate()); BookingOrder order = buildOrder(request, totalPrice); orderMapper.insert(order); return order; }

注意这个existsOverlappingOrder方法，它的 SQL 判断逻辑是这样的：查出的订单和你想要的时间段有重叠就说明冲突。重叠的判断不是简单地比较相等，而是判断两个区间是否有交集，所以用check_in_date < #{checkOut} AND check_out_date > #{checkIn}这个条件，才能把所有交叉的情况都覆盖到。我见过有新手直接用等号判断日期，结果同一间房被两个不同日期段的订单同时占用，客人来了发现房间还没退，现场直接翻车。

3.3 价格计算怎么做才灵活，日期区间定价的坑和应对

价格计算看起来是个小功能，但做不好特别容易出问题。很多系统的价格表设计的是一天一个价格，一个月的房态就是 30 条记录，然后页面上让管理员一天一天去改，这个体验很糟糕。我的方案是用区间表，支持连续日期段的统一价格。

但这个方案也存在边界问题。比如节假日和普通日期是穿插的，节假日那几天需要单独调整价格，如果用区间表就会造成价格区间碎片化，一个月的日历可能被划分成 5 到 6 个价格区间。为了解决这个问题，可以在区间表里增加 priority 字段，日期精确匹配的区间优先于日期范围匹配的区间。比如“2025-10-01 到 2025-10-07 国庆价”这个区间的优先级是 10，而“2025-10-01 到 2025-10-31 平季价”的优先级是 5，那么计算 10 月 2 日的价格时，优先取 10，即国庆价。

计算总价的逻辑需要遍历入住日到退房日的每一天，逐天取价格再求和。这一步性能上没有任何问题，因为一个订单最多也就住十天半个月，循环几十次完全能接受。反倒是要注意，日期遍历时一定要用LocalDate，不要用Date去加减天数，那真是给自己挖坑。

4. 实操过程中的高频问题与排查技巧，这些坑你迟早要踩一遍

我写这套系统的过程中，确实踩了不少坑。有些问题是代码层面的，有些是环境层面的，还有的是思路层面的。这一章我就把那些高频问题整理出来，配合排查思路，帮你省点时间。

4.1 房间和订单的状态总是对不上，怎么通过接口排查

这个问题我遇到过好几次，后来发现根因基本都是同一个：更新房间状态和更新订单状态没有放在同一个事务里。比如客人取消了订单，释放房间应该和订单状态翻转为已取消在同一个事务里完成。如果这两步操作分成了两个事务，正好赶上系统崩溃或者接口调用失败，就会出现订单是已取消，房间还是已入住的情况。

排查方法也很简单，写一个管理后台的核对接口，定时去比对订单表和房间表的数据一致性。比如查出所有状态为已入住的订单对应的房间，如果房间状态不是已入住，就说明数据不一致了。这个核对接口平时用不上，但在出问题的时候是救命稻草。

注意：线上环境千万不要直接去数据库里改数据。如果你发现订单状态和房间状态对不上，第一件事是去查订单状态日志表，看状态是什么时候变的、有没有异常记录，再通过接口去修正状态，而不是手改数据库。

4.2 Spring Boot 项目里文件上传和参数绑定，为什么老报错

这个系统的“智能”部分通常会包含用户上传身份证照片、房间照片等需求，而文件上传这个问题是 Spring Boot 开发中的高频踩坑点。最容易出的问题有这几个：

第一个问题是上传一个文件带一个普通参数时，Controller 方法的参数签名写错了。正确的写法是@RequestPart("file") MultipartFile file加上@RequestParam("name") String name，而不是把文件参数写成@RequestParam。我见过太多新手在MultipartFile前面加上@RequestBody，结果前端传了半天一直报 415 错误。

@PostMapping("/upload") public R<String> upload(@RequestPart("file") MultipartFile file, @RequestParam("roomId") Long roomId) { // 处理文件，保存到本地磁盘或对象存储 return R.ok(fileStorageService.store(file, roomId)); }

第二个问题是上传文件的大小限制。Spring Boot 默认单个文件最大是 1MB，一张手机拍出来的房间照片轻松超过这个值。如果你不调配置，传一张照片就报 MaxUploadSizeExceededException。这个配置要在application.yml里调，同时要注意不同的 Spring Boot 版本配置项名称有细微差异：

spring: servlet: multipart: max-file-size: 20MB max-request-size: 100MB

第三个问题是前端上传文件时，Content-Type要设成multipart/form-data，而且multipart请求体里的参数顺序要和后端一致。有些前端同学习惯用 JSON 去传文件，后端怎么修改都接收不到，这就是纯粹的前后端对接问题。

4.3 Docker 部署时遇到的环境问题，日志收集怎么做到位

这系统做完之后，我把它用 Docker 部署到了服务器上。这里有几个经验想分享给你。第一个是 Dockerfile 里基础镜像的版本一定要和本地开发环境的 JDK 版本保持一致，否则会出现本地跑得好好的，容器一启动就报各种奇怪的类找不到异常。第二个是数据库连接要写在环境变量里，不要写在配置文件里。Docker 容器每次重建 IP 都可能变，如果你把数据库地址写死在配置里，每次容器换 IP 你都得上服务器去改配置文件，这个体验太糟糕了。

关于日志收集，我自己用过 Elastic 那套方案，也用过更轻量级的方案。如果项目初期只有一台服务器，直接用docker logs加文件挂载的方式就够用了。等服务器多了，再考虑接入 Filebeat 统一收集日志。我这套系统目前就一台服务器，所以直接在 Docker Compose 里做了文件卷挂载，日志落地到宿主机，出了问题直接登录服务器翻日志文件就行。

4.4 前后端联调时常见的 404、跨域、参数缺失问题

联调是整个项目开发中进度最不可控的阶段。Spring Boot 后端服务默认端口是 8080，前端开发服务器通常用 3000 或 5173，这就必然牵扯到跨域问题。我这边后端加了全局 CORS 配置，允许所有来源访问开发环境，但上线时一定要把允许的来源收紧到指定的前端域名，否则别人可以直接跨域调用你的接口。

404 问题也很常见，尤其是 Spring Boot 和前端路由结合的时候。你在写 Controller 时要记得，@RequestMapping的路径不要以斜杠开头也不会影响配置，但前端请求时的路径一定要以斜杠开头，比如/api/order/list，少一个斜杠就会变成 404，而且报错信息不明确，排查起来很费时间。

参数缺失是另一类高频问题。前端传from和to，后端那边用from和to接，但前端实际传的是fromDate和toDate，结果一接就是 null。这个问题的根源是前后端字段名没有对齐，所以我在后端多封装一个统一的请求类，前端传参时严格按字段名匹配，不搞那些奇奇怪怪的别名字段。

5. 这套系统做完之后，还能往哪些方向扩展

项目做完不是终点，能做扩展才是这套系统的价值所在。我列几个我认为比较有价值的方向，你可以结合自己的实际情况来选。

第一个方向是管理后台的升级。现在很多系统都用的是前后端分离的架构，前端用 Vue 或者 React，后端提供 REST 接口。如果你已经在做管理后台，可以考虑加一个数据看板功能，统计每天的房间入住率、营收情况、订单量趋势。这些数据查询用 MyBatis 写复杂 SQL 非常顺手，而且视觉呈现效果也好，作为项目亮点写进简历里很加分。

第二个方向是加入消息通知。比如客人预订成功后，系统自动发一条短信或者邮件确认订单信息；客人取消订单后，系统通知前台人员及时释放房间。这个功能的实现方式有很多种，可以用 Spring 的事件监听机制，也可以在业务层直接调用第三方短信服务的 SDK，根据成本和需求来选择。

第三个方向是做一个小程序端。现在很多酒店的预订入口都已经从 PC 网站转移到微信小程序或者 App 上了，如果你把一个 PC 端的预定系统扩展出一个小程序前端，后端接口大部分是可以复用的。主要工作集中在鉴权方式的变化和接口参数的适配上，整体工程量不大，但完整度会高很多。

我做这套系统最大的体会是，真正决定系统质量的，不是用了多新的框架、多炫的技术，而是对业务状态的理解是否透彻，对数据一致性的把控是否到位。Spring Boot 那套东西，熟练了之后都是套路，真正拉开差距的还是在业务模型设计和异常情况处理上。希望这个项目的拆解过程能给你一些启发，少走一些我走过的弯路。