企业官网建设流程全解析

去年帮朋友做了套健身房管理系统，项目定名"基于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、测量时间、测量教练ID，body_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三个字段，code=200表示成功，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，事务直接失效。花了很多时间排查后才发现是表引擎的问题，所以建表后一定要检查ENGINE=InnoDB。

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-references=true，本质是代码分层不够清晰。

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里确认添加了Spring；pom.xml里引入spring-boot-configuration-processor并重新import Maven；写yml时确认用空格缩进而不是Tab。

单元测试一开始也让我很头疼。@SpringBootTest会启动完整上下文，如果本机没启动Redis或者依赖的MySQL数据不对，测试直接失败。后来我总结了一套方案：测试类用test的profile，RedisTemplate用@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 TZ=Asia/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}?useUnicode=true&characterEncoding=utf8 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-size=10MB，max-request-size=20MB。如果后续要上传课程视频这类大文件，就需要考虑分片上传和断点续传，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 TZ=Asia/Shanghai这个坑一定要记得填。

最后再分享一点个人感受。做这套系统最大的收获不是用了多少新技术，而是学会了围绕业务做设计。健身和轻食，一个管练一个管吃，表面上两个模块，但当课程的核销记录能联动轻食订单积分，月底对账时系统能一目了然地告诉你"这个月轻食卖了多少钱、哪款卖得最好、哪个教练课程预约率最高"，这个系统的价值就远远超过了一堆CRUD代码的堆叠。你如果准备做类似的Spring Boot项目，建议一定先从业务流程梳理开始，把角色和动作列清楚再写代码，开发过程中遇到问题多从Bean生命周期、事务边界、版本兼容性三个角度去排查，绝大多数的坑都能定位到根因。