做客栈管理系统这类项目最怕的不是业务复杂而是技术栈堆得花里胡哨最后连部署都费劲。我最近给一家小型客栈做的后台用的是一条很稳的路Spring Boot 做应用骨架MyBatis 管SQLMySQL 存核心数据Thymeleaf 直接跑服务器端页面模板。整套系统没有引入中间件也没做前后端分离核心就是四个业务模块——客房管理、预订管理、入住结算、统计报表——把它们串成一条完整闭环。这套方案不是所谓的最佳架构而是最不容易出错的选择小团队或个人开发者拿过来都维护得住。如果你是刚接触后台管理系统的人或者手头正好有一个类似客栈、民宿、公寓看板的小项目这篇会把从建表到页面渲染的每个环节都拆给你看。我用的环境以 Spring Boot 2.7.x、MySQL 8.0 为例其他版本大同小异。写出的代码不追求炫技但每个地方都解释清楚“为什么这么做”尤其是日期重叠判断、加锁防超卖、状态流转设计、Thymeleaf路径处理这些都是真实项目里反复踩坑的点。1. 整体架构与技术选型思路1.1 技术组合的边界为什么不做前后端分离做技术选型之前我先盘了一遍需求客栈规模不大前台要开房、订房、退房老板要看每天的房费和出租率整个系统的数据表不超过十张页面以列表、表单、统计图为主。这类项目最大的要求是“上线快、维护简单”而不是高并发、高扩展。Spring Boot 的价值是省去大量配置。内嵌服务器和自动配置让你不用为 Tomcat、Spring MVC 的环境问题耗费精力一个 fat jar 扔到服务器上就能跑。MyBatis 的价值是SQL控制力。客栈业务里“某个房间在某个时间段是否可订”这种带日期区间的查询用 XML 写成 SQL 可以反复打磨比在 ORM 里拼API更直观。MySQL 负责关系数据存储对日订单量只有几十到几百条的应用来说绰绰有余。Thymeleaf 可能有一点争议毕竟现在都在讲前后端分离但客栈后台本质是内部工具用户量极小让前后端再维护接口联调和跨域配置纯属浪费。服务器端渲染把页面和接口放在同一套工程里前后端也不用分开部署。这套组合的逻辑就是用最成熟的基础组件把业务主流程跑通把开发重心放在房间状态流转和预订规则上而不是放在框架本身。1.2 四大模块的边界与状态设计四个业务模块的划分参考了客栈前台的日常动线客人到店先看房、选房接着预订或直接入住住的过程中可能有加收费用最后退房结账老板每天还要看经营报表。所以模块定为客房管理、预订管理、入住结算、统计报表。它们不是简单拼接而是通过一套“状态机”串起来的。客房状态用 TINYINT 表示0空闲、1已预订、2入住中、3维修。预订记录也用 TINYINT0待入住、1已入住、2已退房、3已取消。用数字而不是字符串是因为数字在比较和索引上更高效代码里再定义枚举对应可读性也不会丢。两个状态集合之间有明确联动客房变成1必然对应一条待入住的预订记录客房变成2预订记录必须变成已入住退房结算后客房回到0预订记录变成已退房。如果一个系统里这些状态靠人工随手改迟早出现脏数据。所以我在 Service 层把状态流转收敛成几个固定方法创建预订、取消预订、入住登记、退房结算外部操作只能走这些方法不允许直接改状态字段。这一点是整个项目里最值得花时间设计的后面接任何新需求都不会乱。2. 从零搭建项目依赖、配置与数据库初始化2.1 项目骨架与依赖清单搭建项目我习惯手动建好目录而不是只靠脚手架一键生成。目录按 controller、service、mapper、entity、dto 分层MyBatis 的 XML 文件放在 resources/mapper 下结构清晰比省那几十秒更重要。Java 版本用的 8配合 Spring Boot 2.7.x资料多、坑少遇到问题搜起来方便。如果你用更新的 Boot 3.x记得把 MyBatis 对应的 Starter 版本一起升级否则会有兼容问题。依赖方面核心是下面几个spring-boot-starter-web 提供 MVC 和内置服务器spring-boot-starter-thymeleaf 提供模板引擎mybatis-spring-boot-starter 负责 MyBatis 与 Spring Boot 的整合mysql-connector-j 是 MySQL 驱动。我额外加了 spring-boot-starter-validation 做参数校验还加了 Lombok 简化实体类 getter/setter。如果你的环境不方便用 Lombok去掉也不影响自己手写实体类就行。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.1/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency2.2 数据表结构设计与初始化SQL整个系统我最终只用了四张核心表room、reservation、bill、customer。其中客户表本来是单独设计的后来发现客栈不像酒店有大量会员体系客人信息直接冗余到预订表反而少一次关联查询。所以实际项目里 customer 表可以砍掉预订表里直接存客户姓名和电话即可。客房表的核心字段是房号、房型、价格、楼层、状态。CREATE TABLE room ( id BIGINT AUTO_INCREMENT PRIMARY KEY, room_no VARCHAR(20) NOT NULL, room_type VARCHAR(50), price DECIMAL(10, 2) NOT NULL, floor_no INT DEFAULT 1, status TINYINT DEFAULT 0 COMMENT 0空闲 1已预订 2入住中 3维修, UNIQUE KEY uk_room_no (room_no) );预订表要记录房间、客户名、电话、入住日期、离店日期和预订状态。日期字段用 DATE 类型不需要带时分秒客栈业务的日切点在中午按天处理就够用。CREATE TABLE reservation ( id BIGINT AUTO_INCREMENT PRIMARY KEY, room_id BIGINT NOT NULL, customer_name VARCHAR(50), customer_phone VARCHAR(20), check_in_date DATE NOT NULL, check_out_date DATE NOT NULL, status TINYINT DEFAULT 0 COMMENT 0待入住 1已入住 2已退房 3已取消, created_time DATETIME DEFAULT CURRENT_TIMESTAMP, KEY idx_room_date (room_id, check_in_date, check_out_date) );账单表我单独拆出来。为什么不把金额挂在预订表上因为退房时间可能提前或延后系统需要重新计算实际房价bill 表记录结账现场方便对账和统计。字段里 room_price 是结算当天的房费快照day_count 是实际住宿天数extra_fee 是加床、酒水等额外消费。CREATE TABLE bill ( id BIGINT AUTO_INCREMENT PRIMARY KEY, reservation_id BIGINT, room_id BIGINT, room_price DECIMAL(10, 2), day_count INT, extra_fee DECIMAL(10, 2) DEFAULT 0, total_fee DECIMAL(10, 2), settle_time DATETIME DEFAULT CURRENT_TIMESTAMP );注意价格一律用 DECIMAL不要用 DOUBLE。DOUBLE 在计算金额时会出现精度问题比如 0.1 加 0.2 得到 0.30000000000000004这在账单场景是不能接受的。2.3 数据源与 MyBatis 基础配置application.yml 是踩坑最多的地方核心配置如下spring: datasource: url: jdbc:mysql://localhost:3306/inn_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver thymeleaf: cache: false mybatis: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: true server: port: 8080这里有三点要特别解释。第一连接地址必须带 characterEncodingutf8 和 serverTimezoneAsia/Shanghai否则中文乱码和日期时区报错会把人逼疯。第二MyBatis 必须开启驼峰映射否则数据库的 check_out_date 映射不到 Java 的 checkOutDate 属性。第三开发阶段 Thymeleaf cache 必须设为 false不然改了页面看不到效果要不停重启。3. 客房与预订模块核心业务实现3.1 客房管理房态流转与价格维护客房模块的重点不在 CRUD而在状态流转的控制。客房列表、按房型查询、修改价格都是基础操作真正容易出问题的是“把房间状态改成维修”这件事。维修前必须检查这个房间有没有待入住或者正在入住的预订如果有这些单子要提前处理掉否则客人到店发现房间被锁前台就尴尬了。我把房态流转的入口都收敛在 Service 中。public void markMaintenance(Long roomId) { int active reservationMapper.countActiveByRoom(roomId, ReservationStatus.BOOKED, ReservationStatus.CHECKED_IN); if (active 0) { throw new BusinessException(该房间存在未结束的预订不能设置为维修); } roomMapper.updateStatus(roomId, RoomStatus.MAINTENANCE); }这种判断写在 Controller 里太薄写在 Service 才有复用价值。另一个细节是前端页面展示房态时不要直接显示数字要在 VO 里转换成“空闲”“已预订”“入住中”“维修”。转换逻辑放后端前端只管渲染这样以后改文案不用动页面。3.2 预订可用性检查与防冲突SQL预订模块是整个系统含金量最高的地方。客栈的核心业务就是“某房间在某时间段内是否可订”这个判断稍有不慎就会产生重复订单。可用性查询的条件是该房间不是维修状态同时没有其他预订在目标时间区间内重叠。区间重叠的判断是经典 SQL 题。如果我预订从 check_in_date 到 check_out_date用左闭右开区间表示即入住当天包含、离店当天不包含那么两个区间重叠当且仅当res.check_in_date #{checkOut} AND res.check_out_date #{checkIn}这个条件非常简洁却经常写错。很多新手写的是res.check_out_date #{checkIn} AND res.check_in_date #{checkOut}看起来差不多但在“前一单当天退房、后一单当天入住”的边界场景会多占用一天。举个例子房间 A 的订单入住 10 月 1 日、离店 10 月 3 日新订单想入住 10 月 3 日、离店 10 月 5 日。正确逻辑下它应该可以订因为 10 月 3 日中午前原客人退房中午后新房客入住。错误的比较条件会把 10 月 3 日这一天重叠进来导致房间被白白锁死。查询可用房时直接查“没有被活跃预订占用的空闲房间”select idfindAvailableRooms resultTypeRoomDTO SELECT r.* FROM room r WHERE r.status 0 AND r.id NOT IN ( SELECT res.room_id FROM reservation res WHERE res.status IN (0, 1) AND res.check_in_date lt; #{checkOut} AND res.check_out_date gt; #{checkIn} ) /select这里状态只取 0待入住和 1已入住已退房和已取消的订单不会占房间。3.3 预订创建的事务与并发控制可用房查询没问题不代表创建预订没问题。两个前台同时操作查询时都看到房间空闲然后都插入预订就会超卖。防止超卖最简单可靠的办法是“先锁房间再查冲突”。MyBatis 里提供一个带悲观锁的查询select idselectRoomForUpdate resultTypeRoom SELECT * FROM room WHERE id #{id} FOR UPDATE /selectService 方法用 Transactional 包裹先锁房间行再查冲突然后插入预订记录并更新房间状态。Transactional public Reservation createReservation(ReservationDTO dto) { Room room roomMapper.selectRoomForUpdate(dto.getRoomId()); if (room null || room.getStatus() ! RoomStatus.AVAILABLE) { throw new BusinessException(房间不可预订); } int conflict reservationMapper.countConflict(dto.getRoomId(), dto.getCheckIn(), dto.getCheckOut()); if (conflict 0) { throw new BusinessException(该时间段房间已被占用); } Reservation reservation new Reservation(); reservation.setRoomId(room.getId()); reservation.setCustomerName(dto.getCustomerName()); reservation.setCustomerPhone(dto.getCustomerPhone()); reservation.setCheckInDate(dto.getCheckIn()); reservation.setCheckOutDate(dto.getCheckOut()); reservation.setStatus(ReservationStatus.BOOKED); reservationMapper.insert(reservation); roomMapper.updateStatus(room.getId(), RoomStatus.BOOKED); return reservation; }这里有两个细节值得说。FOR UPDATE会锁住该行直到事务提交或回滚因此另外一笔预订请求会在这个位置等待从而避免同一房间被卖两次。房间状态更新成“已预订”后所有可用房查询会自动把它排除这是状态机的第一次联动。4. 入住结算与统计报表闭环的最后两块拼图4.1 入住登记与状态校验客人到店后前台根据预订记录办理入住。这个过程看似简单但状态校验必须严格。只能对待入住状态的预订执行入住如果订单已经被取消或者已经办理过入住再登记就会产生脏数据。Transactional public void checkIn(Long reservationId) { Reservation reservation reservationMapper.selectById(reservationId); if (reservation null) { throw new BusinessException(预订记录不存在); } if (reservation.getStatus() ! ReservationStatus.BOOKED) { throw new BusinessException(当前状态不允许办理入住); } reservationMapper.updateStatus(reservationId, ReservationStatus.CHECKED_IN); roomMapper.updateStatus(reservation.getRoomId(), RoomStatus.OCCUPIED); }入住登记最容易被忽略的是“提前到店”和“延后到店”的边界。如果客人在预订入住日期之前到店应当先修改预订日期再办入住。如果客人超过预订日期一天没到房间会被一直占着所以我在系统中加了一个定时任务每天凌晨把超过离店日期仍未入住的待入住订单自动置为取消并释放对应房间。这个功能虽然是后加的但上线后避免了大量房间空置的纠纷。4.2 退房结算的费用计算退房结算需要重新计算天数不能直接信任预订时的日期。比如客人原本订了三天结果第二天有急事要走结账天数就得变成两天。实际住宿天数的计算方式是离店日期减去入住日期但离店日期如果还没到要取当前日期和预订离店日期中较早的那个。public Bill settle(Long reservationId, BigDecimal extraFee) { Reservation res reservationMapper.selectById(reservationId); if (res.getStatus() ! ReservationStatus.CHECKED_IN) { throw new BusinessException(只有入住中的订单才能结算); } LocalDate actualOut res.getCheckOutDate().isAfter(LocalDate.now()) ? LocalDate.now() : res.getCheckOutDate(); long days ChronoUnit.DAYS.between(res.getCheckInDate(), actualOut); Room room roomMapper.selectById(res.getRoomId()); BigDecimal totalFee room.getPrice() .multiply(BigDecimal.valueOf(days)) .add(optionalExtraFee(extraFee)); Bill bill new Bill(); bill.setReservationId(res.getId()); bill.setRoomId(room.getId()); bill.setRoomPrice(room.getPrice()); bill.setDayCount((int) days); bill.setExtraFee(extraFee); bill.setTotalFee(totalFee); billMapper.insert(bill); reservationMapper.updateStatus(res.getId(), ReservationStatus.SETTLED); roomMapper.updateStatus(room.getId(), RoomStatus.AVAILABLE); return bill; }天数计算用 DAYS.between取两个日期相差的自然日。额外费用必须用 BigDecimal 相加不要用 double这是钱相关代码的底线。退费逻辑我没有做得很复杂因为真实客栈里“少退多退”往往由前台人工确认系统只需要把账算准、把房间释放掉。4.3 统计报表的SQL与接口统计模块帮助老板回答三个问题今天收了多少房费本月预订量怎么样最近一周出租率如何日营收报表按 settle_time 分组聚合SELECT DATE_FORMAT(settle_time, %Y-%m-%d) AS day, COUNT(*) AS settle_count, ROUND(SUM(total_fee), 2) AS total_fee FROM bill WHERE settle_time #{start} AND settle_time #{end} GROUP BY DATE_FORMAT(settle_time, %Y-%m-%d) ORDER BY day;MyBatis 的返回结果可以直接映射到一个简单的实体类或者 Map在 Thymeleaf 页面里用 th:each 循环展示。这里要注意如果日期跨月GROUP BY 的日期表达式必须和 SELECT 里的完全一致否则数据库会报错或按错误的分组维度统计。出租率如果按天算可以这样查SELECT COUNT(*) AS occupied_rooms FROM room WHERE status 2再除以房间总数即可。细心的读者会发现这个口径是即时快照而不是全天平均值。对小型客栈够用了老板看的是趋势不需要复杂的房晚模型。5. Thymeleaf 页面集成服务器端渲染的细节5.1 页面布局与公共片段Thymeleaf 的布局机制比 JSP 干净很多最常使用的是片段复用。我建了一个 layout 模板把顶部导航和左侧菜单抽成公共片段每个页面通过替换 content 区域实现复用。!DOCTYPE html html xmlns:thhttp://www.thymeleaf.org head title th:text${pageTitle}客栈管理系统/title link relstylesheet th:href{/css/app.css} /head body header th:fragmentheader h1客栈管理系统/h1 nav a th:href{/room/list}客房管理/a a th:href{/reservation/list}预订管理/a a th:href{/report/dashboard}统计报表/a /nav /header div th:fragmentcontent 页面主体内容 /div /body /html子页面通过th:replace引入公共片段同时保持自身的内容区域各自独立。第一次用 Thymeleaf 的人最容易搞混th:replace和th:insert前者直接替换当前标签后者在内部嵌入。布局用 replace 更可控。5.2 表单提交、日期选择与错误回显预订管理页面是表单交互最重的地方。前台要选择房间、填客人姓名电话、选入住和离店日期然后提交。Controller 接收表单参数用 DateTimeFormat 指定日期格式PostMapping(/reservation/create) public String create(Valid ReservationDTO dto, BindingResult bindingResult, Model model) { if (bindingResult.hasErrors()) { model.addAttribute(error, bindingResult.getAllErrors().get(0).getDefaultMessage()); return reservation/form; } try { reservationService.createReservation(dto); return redirect:/reservation/list; } catch (BusinessException e) { model.addAttribute(error, e.getMessage()); model.addAttribute(dto, dto); return reservation/form; } }如果业务抛出异常比如房间被占、日期跨度过长我需要把错误信息回显到表单页面。这里有个小坑redirect之后 Model 里的数据会丢所以错误提示不能放在重定向目标里而是直接 return 模板让 Thymeleaf 用th:if${error}显示。5.3 静态资源与路径处理Thymeleaf 的路径规则是HTML 模板放在src/main/resources/templates/下CSS、JS、图片放在src/main/resources/static/下。模板里引用静态资源必须用th:href{/css/app.css}这种写法Spring Boot 自动加上上下文路径部署到子目录也不会丢。页面跳转我用redirect:/reservation/list而不是直接返回视图名。原因是列表页需要重新加载数据如果直接返回视图页面 URL 停留在/reservation/create用户刷新一下就会重复提交表单。重定向能避免这个问题是 POST 后处理的标准做法。开发阶段把 thymeleaf.cache 设为 false 后改完 HTML 刷新就能看到效果。但上线前我会把它改回 true否则模板每次请求都重新解析性能会有损耗。6. 常见问题排查与避坑实录6.1 数据库连接与初始化问题我遇到的第一个坑是数据库连接失败报Access denied for user。排查顺序一般是账号密码是否正确、MySQL 是否允许远程访问、URL 中的数据库名是否拼对。还有一个很隐蔽的是 MySQL 8 驱动类名变化Boot 2.7 虽然能自动识别但如果你手动指定要用com.mysql.cj.jdbc.Driver老的com.mysql.jdbc.Driver会被提示已过时。6.2 MyBatis 映射与参数问题MyBatis 最常见的是查出来的日期字段是 null。绝大多数原因是没开驼峰映射check_out_date无法映射到checkOutDate。开了map-underscore-to-camel-case: true就解决。如果用的是个别复杂查询显式写 resultMap 比依赖全局配置更保险。另一个常见问题是多个参数传递时报错Parameter xxx not found。两个及以上的参数必须加 Param 注解否则 MyBatis 不知道参数名对应关系。我在代码里都用了#{roomId}、#{checkIn}就是靠注解支撑的。6.3 Thymeleaf 模板渲染问题Whitelabel Error Page是新手最容易看到的错误页。出现它通常有三种原因Controller 返回的视图名找不到、模板路径写错、模板里引用了不存在的字段。排查顺序是先看控制台异常栈如果是TemplatingException基本就是模板语法或路径问题。模板里访问对象的属性时Spring Boot 不强制要求 getter 命名规范但如果你用了 Lombok漏掉Data会导致属性访问不到这种错误往往只在运行时才暴露。6.4 并发与数据一致性问题预订超卖这种问题在单测里很难发现因为并发操作需要多线程模拟。我的经验是除了 Service 层用for update锁房间还要在数据库层加唯一约束兜底。比如同一个房间在同一时间段只能有一条有效预订这种约束用业务代码保证不是万无一失数据库索引才是最终防线。日期索引建议用(room_id, check_in_date, check_out_date)组合因为几乎所有的冲突查询都按房间和时间过滤。6.5 常见错误速查表问题现象可能原因解决方案页面中文乱码数据库连接未指定utf8URL加characterEncodingutf8Date字段为null未开启驼峰映射设置map-underscore-to-camel-case模板改完不生效Thymeleaf缓存开启开发环境cache设为false日期参数绑定失败前端格式与后端不一致后端加DateTimeFormat账单金额有小数误差使用double/float全部使用BigDecimal房间重复预订缺少并发控制Service加for update锁重定向后Model数据丢失不理解redirect错误提示直接return模板这些坑分布在不同阶段最花时间的是并发类问题因为它不会稳定复现。我的排查办法是写一个多线程测试用 20 个线程同时预订最后一个空闲房间观察数据库里是否有两条状态为待入住的记录。跑通了这个测试并发问题基本都能兜住。做完这套系统我最大的感受是客栈这类中小型管理项目的重点永远是业务流程而不是技术框架。Spring Boot、MyBatis、MySQL、Thymeleaf 各自解决的只是“怎么做得舒服”真正决定系统好坏的是状态流转、日期冲突判断、结算准确性这些细节。前面提到的 for update 锁、状态机联动、统计 SQL单独看都很基础合在一起就是一张完整的业务网。最后一个小建议上线前别急着加功能先把“创建预订→入住→结算”这条主流程用几个自动化测试保护起来之后所有改动都有底气。这套组合的后续扩展空间也很大比如把页面换成前后端分离或者给客栈加一个移动端前台底层的数据模型都不用大改。