去年帮朋友做了套健身房管理系统项目定名基于Spring Boot的健身服务与轻食间平台管理系统——一句话说就是把健身房的课程预约、会员管理、轻食点单、订单结算这些事统一收进一个后台。做之前我去他店里蹲了两天发现问题比想象中多会员约课在微信群里接龙轻食点单靠前台手写便签体测数据躺在教练的Excel里月底对账要几个人加班。这篇文章就把从需求梳理、技术选型、数据库设计、核心业务实现到Docker部署的完整过程写出来针对的读者是准备做类似Spring Boot项目的同学或者真想给健身房做一套内部系统的开发者。文章里会穿插大量开发时真正卡住我的问题和对应的排查思路希望你能少走弯路。1. 做这个项目前我先理清了健身房的真实业务流1.1 约课靠微信群点单靠喊数据靠Excel传统健身房运营最大的问题不是没有数据而是数据散落在各种地方。会员约课在微信群里接龙前台整理到一张共享表格里轻食区点单靠前台手写结账用普通收银机体测数据在教练个人电脑里客户问我上个月体脂率多少还要等教练翻记录。更麻烦的是教练离职时Excel跟着人走了会员历史数据直接断档。我一开始就发现了这个项目的核心竞争力不是做个网站而是把散落的业务流集中起来。所以动手写代码之前先用一整天把健身房的所有角色和动作画了出来。角色有会员、前台、教练、店长、轻食厨房这几类动作有注册登录、预约课程、取消预约、到店核销、点轻食、支付、取餐、查看报表等。把这些动作捋顺了数据库的表结构基本就出来了一半。1.2 系统边界不做什么比做什么更重要朋友一开始给我的需求列表特别长排课、预约、点餐、收银、库存、会员卡、体测、报表全都要甚至还想加个私教课销售提成。我当时果断划掉了一大半定下一期只做三件事服务预约、轻食点单、会员管理。收银只做支付状态记录不做完整财务私教课提成用线下表格先处理财务报表就在后台做简单的统计展示。这个决策非常重要。管理系统最容易死的地方就是什么都想做什么都没做好。把范围压住之后数据库设计、接口设计、前后端联调的复杂度都降了一个量级。后来项目上线前两个月朋友反馈的重心也都落在预约和点单这两个核心场景上报表那些边缘功能根本没人用。如果当初贪多很可能项目到现在还在开发中。2. 技术选型不跟风Spring Boot版本与配套组件的取舍2.1 基础框架Spring Boot 2.7而不是3.x的理由技术选型时最纠结的是Spring Boot到底选2.7还是3.x。最后定了Spring Boot 2.7.18核心原因是JDK版本。项目部署环境的服务器还是JDK 1.8而Spring Boot 3.0强制要求JDK 17选3.x意味着服务器也要升级JDK牵一发动全身。Spring Boot 2.7是2.x的最后一个大版本社区资料多各种组件的兼容方案也都验证过踩坑成本最低。顺便聊一下Spring Boot自动装配的原理这个在排查问题时特别有用。Spring Boot的自动装配是基于spring.factories文件2.7版本和EnableAutoConfiguration注解实现的。启动时会扫描classpath下所有jar包里的spring.factories把里面配置的AutoConfiguration类全部加载进来再根据项目里是否存在对应的类通过ConditionalOnClass注解判断决定要不要生效。理解了这套机制你就明白为什么某些配置不起作用时第一反应应该是这个自动配置类有没有被加载。提示如果你是在全新的环境里学习Spring Boot可以直接用3.x但如果要部署到现有的JDK 1.8服务器或老机器上Spring Boot 2.7 JDK 1.8仍是目前最稳的组合。2.2 持久层MyBatis-Plus为什么比JPA合适持久层选型时在MyBatis-Plus和Spring Data JPA之间犹豫过。最终选了MyBatis-Plus原因是这个系统的业务偏关系型数据操作动态查询场景特别多。比如轻食订单列表前端要做条件筛选包括订单状态、下单时间范围、会员等级、商品分类用MyBatis-Plus的LambdaQueryWrapper可以动态拼接条件代码写起来非常简洁。而JPA的动态查询虽然也能做但复杂场景下会生成非常奇怪的SQL排查起来很头疼。另外MyBatis-Plus的代码生成器非常适合这类中后台管理系统。根据数据库表直接生成Entity、Mapper、Service、Controller省去大量重复的CRUD代码。我当时就是在数据库表结构设计完成后用代码生成器几分钟生成了一版基础代码然后在这个基础上改业务逻辑效率非常高。2.3 Redis和JWT登录凭证与在线状态的方案组合登录认证这块最初考虑用Session但后端接口要同时给Vue后台和后续可能接入的微信小程序用跨域环境下Session处理不方便最终决定用JWT。用户登录成功后后端签发JWT令牌返回前端前端每次请求在Authorization请求头带上令牌后端通过拦截器解析令牌获取当前用户身份。Redis在这个项目里承担两个职责。第一个是存JWT黑名单用户注销或管理员强制下线时把JWT的唯一标识jti放进Redis并设置过期时间这样即使令牌本身没过期也无法继续使用。第二个是存验证码会员注册或找回密码时发送的手机验证码5分钟有效利用Redis的SET EX自动过期机制实现完全不用手动清理。访问令牌的过期时间我设置成2小时没有做刷新令牌机制。健身房这种业务低频的场景下2小时足够支撑用户完整使用过期了重新登录的成本很低。如果做刷新令牌就要考虑双令牌并发刷新的安全性复杂度高不少对这个体量的系统不值得。3. 数据库设计会员、教练、课程与轻食订单的地基3.1 核心表结构与实体关系梳理这个项目的核心实体有会员、教练、课程、课程排期、预约记录、轻食商品、轻食订单、订单明细、体测记录这几张表。会员表字段包含id、微信openid、手机号、姓名、性别、会员等级、积分、状态、创建时间。保留openid是因为很多健身房的预约和点单都在微信小程序上完成后续要接入微信授权登录时直接用这个字段。教练表和课程表是多对一关系课程排期表关联课程ID、教练ID、上课日期、开始时间、结束时间、最大人数、已预约人数。预约记录表记录了会员ID、排期ID、预约时间、状态已预约/已取消/已核销/已爽约。这里有一个并发设计的细节预约时要在事务里判断已预约人数是否小于最大人数同时给排期表加上乐观锁版本号或者悲观锁防止两个人同时抢最后一个名额导致超卖。3.2 轻食订单与库存扣减的设计思路轻食商品表包含ID、名称、分类、价格、成本、库存、图片、描述、状态。分类包括高蛋白餐、低卡主食、能量饮品、健身零食等。库存操作是这个模块最需要小心的部分我采用了预占库存模式用户提交订单时先锁定库存支付成功后实际扣减库存取消订单或支付超时则释放库存。订单表和订单明细表分离存储。订单明细记录下单时的商品快照包括商品名称、价格、数量而不是只记录商品ID。这一点很重要因为商品价格会调整如果订单明细只存ID历史订单的金额就对不上了到月底对账时会出大问题。在并发控制上由于门店体量不大直接用数据库行级锁就够用了。核心SQL是这样设计的UPDATE meal SET stock stock - #{num} WHERE id #{id} AND stock #{num}返回影响行数为1才表示扣减成功否则就说明库存不足。这条语句是原子操作不需要额外加锁就能防止超卖。如果订单量增长到每秒几百笔再考虑引入Redis预扣库存的方案但对健身房门店来说完全没有必要。3.3 体测记录与健康档案的灵活存储体测数据存储是这次设计里比较特别的一个点。体测记录包括体重、体脂率、BMI、骨骼肌率、基础代谢等指标。一开始想用一张宽表把所有指标字段都放进去但后来发现不同时期的测量项目不一样有的教练还会加测腰臀比、水分率宽表方案后期改表结构会非常痛苦。于是改成了主表和明细表分离的设计。body_measurement主表只存会员ID、测量时间、测量教练IDbody_measurement_item明细表存指标code、指标值、单位。新增测量指标时不需要改表结构只需要在指标字典表里加一条配置。查询时按measurement_id分组在代码里组装成JSON返回前端。这个设计可以类比成超市购物小票小票主表记录单号和结账时间小票明细记录每件商品的名称和价格。后来超市新增了商品品类不需要重新设计小票格式。这种思路在处理维度随时可能增加的数据时非常实用尤其是体测、健康档案这类历史数据灵活性比固定列更重要。4. 核心业务实现预约、订餐与订单状态机4.1 课程预约的并发控制与状态流转课程预约是整个系统里最容易出Bug的功能没有之一。我把排期状态和预约记录状态分开管理排期状态有可约、已满、已关闭、已结束预约记录状态有已预约、已取消、已核销、已爽约。用户提交预约时事务内执行三步先对course_schedule表的id加行级锁再检查已预约人数是否小于最大人数然后更新已预约人数加1最后插入预约记录。这里为什么要加锁因为两个用户同时抢最后一个名额时不加锁的话两边都会检查通过然后都插入预约记录最终就超卖了。虽然健身房场景并发量不大但作为系统设计这个坑不能埋。取消预约的规则也提前定了开课前2小时允许用户自助取消取消时释放名额开课前2小时内取消视为爽约需要联系前台处理。核销环节由前台或教练在后台操作校验预约记录状态必须是已预约而且排期日期是当天防止提前核销或重复核销。每次状态流转都通过状态机校验逻辑判断是否合法避免数据错乱。4.2 轻食订单状态闭环与积分联动轻食订单的状态机设计创建订单待支付、支付成功已支付、厨房接单制作中、备餐完成待取餐、会员取餐已完成、用户取消或超时未支付已取消、退款中、已退款。每个状态之间的流转做了严格限制比如已支付订单才能进入制作中已完成订单不能再取消。这个系统的亮点是健身与轻食的联动。我设计了一个简单的积分规则会员完成课程签到获得积分积分可以兑换轻食优惠券轻食订单满足金额条件可以使用积分抵扣累计消费金额还能提升会员等级不同等级享受不同的轻食折扣。这样健身和吃就形成了一个业务闭环——练得多、吃得好、省得多会员复购意愿明显提升。支付超时处理用了定时任务方案。通过Spring Boot自带的Scheduled每5分钟扫描一次超过30分钟仍未支付的订单将其置为已取消并释放预占库存。为什么不用Redis过期事件因为Redis的key过期事件默认不保证即时性而且需要额外配置监听器漏单风险高。定时任务依赖数据库状态扫描简单可靠虽然会有几分钟延迟但在这个场景里完全可接受。4.3 给前端Vue的接口设计与前后端分离这个项目的前后端完全分离前端用的Vue后端只提供RESTful API。接口响应结构统一为Result 包含code、message、data三个字段code200表示成功400参数错误401未认证403无权限500服务器异常。前端拿code判断业务是否成功不用每次解析HTTP状态码。跨域配置是前后端分离必须处理的问题。后端写了一个CorsConfig配置允许的域名、请求方法、请求头并设置allowCredentials(true)。这里有个坑allowCredentials(true)的时候allowedOrigins不能设置成*必须写出具体的域名否则浏览器会拦截带凭证的请求。用JWT的场景登录态不依赖Cookie但这个规范还是要遵守。接口按模块划分/auth/**处理注册登录/member/**处理会员信息和体测数据/course/**处理课程和排期/booking/**处理预约/meal/**处理轻食商品/order/**处理轻食订单/admin/**处理后管功能。每个接口先通过拦截器校验JWT再用自定义注解RequireRole区分会员、教练、前台、店长的角色权限配合Spring Boot的拦截器注册实现菜单级别的角色管理。5. 开发中踩过的坑事务、循环依赖与版本兼容5.1 Transactional失效的三种场景这个项目踩过的第一个大坑是Transactional不生效而且是在上线前测试时才发现的。典型的失效场景有三种我都碰到了。第一种是同类内部调用。类A有个public方法a()方法a内部调用了同类中的b()b上标了Transactional。Spring的声明式事务基于AOP代理实现内部调用走的是this.b()不会经过代理对象事务自然不生效。解决办法是把b()提到另一个Service里或者用TransactionTemplate编程式事务。我后来很多核心业务方法直接改用TransactionTemplate代码更直白也不容易踩代理的坑。第二种是异常被捕获后没有抛出。在轻食下单扣库存的业务里一开始写了try-catch记录日志但没把RuntimeException重新抛出去结果MySQL更新失败时事务不会回滚第二天查数据发现一堆脏数据。正确做法是catch里拿到异常后如果决定要回滚就抛出RuntimeException或者在catch块里手动调用TransactionAspectSupport.currentTransactionStatus().setRollbackOnly()。第三种是数据库引擎不支持事务。这种情况在新建表时很少出现但如果把老系统的数据表导入进来表引擎可能是MyISAM而不是InnoDB事务直接失效。花了很多时间排查后才发现是表引擎的问题所以建表后一定要检查ENGINEInnoDB。5.2 循环依赖怎么出现又怎么干掉它循环依赖这个问题我在项目中期重构时遇到了。具体场景ActivityService里注入了MemberService用来给会员发活动积分。后来MemberService又要查询用户参与的活动记录于是在MemberService里也注入了ActivityService。项目启动时直接报错The dependencies of some of the beans in the application context form a cycle。Spring Boot 2.6之后默认禁止循环依赖这个设计是好事逼着你去改代码结构而不是绕过去。我当时把发放积分这个操作抽到了独立的MemberPointsService中ActivityService和MemberService都依赖它问题就解决了。通过这次重构我对职责划分有了更深的理解——遇到循环依赖不要想着开allow-circular-referencestrue本质是代码分层不够清晰。5.3 Spring Boot版本太高带来的组件兼容问题热搜词里有条springboot 4.0 找不到aop其实对应的就是版本升级带来的兼容性问题。我也遇到过类似情况Spring Boot 3.x之后底层规范从Java EE切换到Jakarta EE很多旧版本的MyBatis、Druid、PageHelper如果不升级启动时就会出现ClassNotFoundException之类的错误。这个健身系统用的Spring Boot 2.7问题少很多但并不是没有。引入MinIO的SDK时版本不对就会启动失败Hutool工具包也出现过版本冲突。我的解决方案有两个一是能用Spring Boot官方BOM管理的依赖尽量不手动指定版本二是非官方集成的库单独查它的GitHub Releases选择标明支持当前Spring Boot版本的稳定版本。每个选好的版本我都记录在项目README的依赖说明里方便以后排查。5.4 application.yml不提示和单元测试的优化建议开发环境里遇到最烦人的问题之一就是Idea中application.yml完全没有代码提示。原因通常是项目没有被Idea识别为Spring Boot项目或者spring-boot-configuration-processor依赖没有加。解决办法是检查下面几个点File - Project Structure - Facets里确认添加了Springpom.xml里引入spring-boot-configuration-processor并重新import Maven写yml时确认用空格缩进而不是Tab。单元测试一开始也让我很头疼。SpringBootTest会启动完整上下文如果本机没启动Redis或者依赖的MySQL数据不对测试直接失败。后来我总结了一套方案测试类用test的profileRedisTemplate用MockBean模拟数据库用独立的测试库。这样单元测试完全不依赖外部中间件就能跑通也不会污染开发数据。Spring Boot单元测试的最佳实践不是追求覆盖率而是让核心业务逻辑有快速反馈保证改动后心里有底。6. 部署上线从本机到Docker的最后一段路6.1 JDK 1.8项目打包到Docker Desktop项目最终是打包成Docker镜像部署的。本地开发环境是JDK 1.8目标环境是Docker容器。很多人卡在本地跑得好好的Docker里一启动就报Class version error原因就是镜像里的JDK版本比本地低或者本地用了17、21编译容器里是8类文件版本对不上。我给这个项目写的Dockerfile很简单FROM openjdk:8-jdk-alpine WORKDIR /app COPY target/fitness-app.jar app.jar ENV TZAsia/Shanghai EXPOSE 8080 ENTRYPOINT [java,-jar,app.jar]需要注意的点有两个openjdk:8这个基础镜像必须和编译JDK版本一致都是1.8设置时区环境变量否则容器默认UTC时区定时任务会在错误的时间执行。打包时还要检查pom.xml里maven-compiler-plugin的source和target都设为1.8。Docker Desktop本地构建时要注意Apple Silicon芯片上构建的arm64镜像和线上x86服务器不完全兼容我后来直接用docker buildx指定平台参数构建。6.2 配置外部化与图片资源映射项目里有一些配置不能写死在application.yml里比如数据库密码、微信小程序AppSecret、Redis密码。这些用Spring Boot的配置外部化机制启动时通过环境变量覆盖。例如spring: datasource: url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}?useUnicodetruecharacterEncodingutf8 username: ${DB_USER} password: ${DB_PASSWORD}Docker启动时通过-e参数传入或者用docker-compose的environment配置。这样数据库密码不会出现在代码仓库里也方便不同环境复用同一个jar包。资源映射这块springboot 如何做资源映射问的其实就是上传的图片文件怎么通过URL访问。系统里轻食商品图片上传后存在服务器的/data/images目录我在WebMvcConfigurer里重写addResourceHandlers方法Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/images/**) .addResourceLocations(file:/data/images/); }同时配置了上传文件大小限制spring.servlet.multipart.max-file-size10MBmax-request-size20MB。如果后续要上传课程视频这类大文件就需要考虑分片上传和断点续传MinIO是一个不错的选择。引入minio-java依赖配置endpoint、accessKey、secretKey、bucket封装一个MinioService就能实现文件对象存储比本地磁盘方式可靠得多。6.3 上线后的稳定性优化要点系统上线后稳定运行才是关键这里有几个优化点非常实用。第一数据库连接池。Spring Boot默认用HikariCP性能很好。注意maximum-pool-size配置健身房系统同时在线用户几十个连接池默认10就够用调太大会浪费数据库资源。第二日志配置。用logback-spring.xml按天滚动info和error日志分开存储。关键业务节点——下单、支付、预约、核销——都要打业务日志包含会员ID、订单号、操作结果和耗时。线上出了问题时这些日志就是定位问题的第一手线索。第三定时任务的时区问题。Scheduled的任务在本地跑和线上跑行为可能不一样。比如每天凌晨2点清理30分钟前未支付订单这个任务如果容器时区是UTC每天会在北京时间上午10点才执行完全错误。Dockerfile里设置ENV TZAsia/Shanghai这个坑一定要记得填。最后再分享一点个人感受。做这套系统最大的收获不是用了多少新技术而是学会了围绕业务做设计。健身和轻食一个管练一个管吃表面上两个模块但当课程的核销记录能联动轻食订单积分月底对账时系统能一目了然地告诉你这个月轻食卖了多少钱、哪款卖得最好、哪个教练课程预约率最高这个系统的价值就远远超过了一堆CRUD代码的堆叠。你如果准备做类似的Spring Boot项目建议一定先从业务流程梳理开始把角色和动作列清楚再写代码开发过程中遇到问题多从Bean生命周期、事务边界、版本兼容性三个角度去排查绝大多数的坑都能定位到根因。