SpringBoot+MyBatis健身俱乐部管理系统设计与实现

每天来馆里锻炼的会员要刷卡签到，私教课要排课、要预约，课时包什么时候用完、会员卡什么时候到期，还有一堆报表要统计，光靠前台小姐姐拿Excel表去记，早晚要出乱子。我接手的这个“基于Spring Boot的健身俱乐部管理系统”项目，就是要把这些线下琐碎事全部搬到线上，让管理员、前台、教练各干各的活，数据自动流转，账目一目了然。这篇文章从一个可以落地的完整项目角度出发，拆解它的业务需求、表结构设计、核心接口逻辑、Spring Boot + MyBatis的工程实现，以及我实际开发中踩过的坑，给正在做类似管理系统或者拿这个题目练手的朋友一个可以直接抄作业的参考。

先说清楚这套系统适合谁。如果你是刚学完Spring Boot、MyBatis，想找一个综合性不那么高但五脏俱全的练手项目，它很合适；如果你是给健身房做内部系统，需要一个能跑起来的基础骨架，它也能直接改改就用。整个系统包含会员管理、课程管理、私教预约、教练排班、储值消费、到期提醒和统计报表等模块，覆盖了中小型健身俱乐部日常运营的绝大部分场景。

1. 健身俱乐部管理系统到底要管什么

1.1 业务场景与需求拆解

很多人在网上搜“Spring Boot”相关项目时，会看到各种千奇百怪的系统，比如大学生就业推荐、电商跨境商城、监控平台等等。健身俱乐部管理系统之所以值得单独拿来拆，是因为它的业务边界非常清晰，表与表之间的关系也典型。

你可以把整个系统要管的业务拆成四条主线：

• 会员生命周期：办卡录入信息 -> 每次到店签到 -> 卡即将到期提醒 -> 续费或冻结 -> 退卡。
• 课程与预约：教练创建课程 -> 会员查看课表 -> 预约 -> 上课签到 -> 取消预约。
• 教练与排班：教练信息维护 -> 每月/每周排课 -> 课时费统计。
• 财务流水：办卡缴费、私教课扣次、商品消费储值扣款、退款，每一笔都要落账，最终汇成日报月报。

这四条线不是孤立的。会员预约课程会同时影响课程表、会员卡剩余次数和教练的课时安排；会员储值余额扣减又会写入财务流水。所以数据库设计时如果不提前把这些关联理清楚，后续写接口就会陷入各种“查完一个表再逻辑判断另一个表”的泥潭。

1.2 角色与权限划分

这个系统的用户角色我最终定了四种，没有做很复杂的RBAC权限模型，而是用一个简单的用户表和角色字段搞定：

• 系统管理员：管会员、教练、课程、所有订单流水，能看全部统计数据。
• 前台/运营人员：会员开卡、续费、签到、预约处理。
• 教练：看自己的排课表、维护课程信息、标记上课完成。
• 会员：微信端或前台登记后，查看课表、预约、查看自己的剩余课时和储值余额。

在实际开发中，权限切分不用一上来就上Spring Security那套“用户-角色-权限-资源”四级模型，多数管理系统用“用户表 + 角色字段 + 拦截器校验角色”就够用。等业务复杂到菜单权限都需要动态配的时候再改造，不要为了技术炫技增加开发量。

1.3 核心功能清单与优先级

我整理功能清单时按P0/P1/P2排了个优先级，避免一上来就铺太大摊子：

2. 技术选型：为什么是Spring Boot + MyBatis

2.1 Spring Boot版本怎么选

最近网上关于Spring Boot版本讨论很多，有搜“spring boot 2.3.x 2.6.x”的，也有搜“spring boot 3”的。我的建议很简单：不要盲目追新，看你的JDK和依赖生态。

• 如果你用的是JDK 8，选Spring Boot 2.6.x或2.7.x最顺，第三方组件兼容性好，网上资料也最多。
• 如果你用JDK 17，可以直接上Spring Boot 3.x，但要注意Spring Security、MyBatis等都要用配套新版本，老文章里的配置很多会报错。
• 这个健身管理系统我实际开发用的是Spring Boot 2.7.18，稳，并且能和mybatis-spring-boot-starter 2.3.x无缝衔接。

标题里有人搜“intellij idea 社区版怎么用spring boot”，其实IDEA社区版完全可以开发Spring Boot项目，只要装好Lombok和Spring Boot插件，用Maven直接创建即可，不必非要付费版。

2.2 MyBatis和MyBatis-Plus选哪个

很多教程里写“Spring Boot + MyBatis”，但实际写代码时更多人会用MyBatis-Plus。这里有区别：

• 原生MyBatis：灵活度拉满，SQL全写在XML里，适合复杂查询和复杂关联，但CRUD要自己写一堆重复代码。
• MyBatis-Plus：内置单表CRUD、分页插件、条件构造器，同样可以写XML自定义SQL，开发效率高很多。

我的做法是两者结合：单表操作和分页用MyBatis-Plus自带的IService接口，多表关联和复杂统计在XML里写SQL。这样既能保住开发速度，又不会遇到过于复杂的查询时被条件构造器绕晕。

2.3 前端方案与通信方式

后台管理端我用的是Vue 3 + Element Plus，搭建起来快，表格、表单、弹窗这些跟管理系统太匹配了。但要注意如果你不想写前端，也可以用Spring Boot自带的Thymeleaf模板引擎搭一个简单的多页面。纯后端的同学建议先把接口写好，用Swagger或Postman调通后再补前端，避免两边同时开导致问题无法定位。

前后端通信我统一用JSON格式，接口路径遵循/api/...前缀，方便后面加网关或者做权限拦截。跨域问题开发阶段用@CrossOrigin或者在配置类里配CORS解决，不要给Controller到处加注解，太丑还容易漏。

2.4 项目分层结构

整个工程我用了最常见的四层结构：

com.fitness ├── controller ├── service │ ├── impl ├── mapper ├── entity ├── dto ├── config └── common

• controller只做参数接收和结果封装。
• service写业务逻辑，比如会员开卡时同时改动会员表、卡表、流水表，这一步必须在service里做事务。
• mapper只负责数据库交互，不要在mapper里写业务。
• dto用于接收前端参数，entity严格对应数据库表字段。

有人在搜“spring boot 对外提供的接口应该放在哪里”，很多项目的后端里既有给管理端用的接口，又要对外开放接口给第三方。我的经验是：内网后台接口统一放/admin/**，外部调用接口如果量不大可以放/open/**并且单独做签名校验，千万不要把对外开放的接口和内部接口混在一个Controller里，安全策略完全不同，后期很容易出漏洞。

3. 数据库表设计与核心模块分配

3.1 核心表结构

数据库方面，我用的是MySQL 8.0，库名fitness_club，字符集统一utf8mb4，排序规则utf8mb4_unicode_ci。

主要表如下：

这里我特别要提醒两个容易踩的坑：

• 会员卡剩余次数和预约记录必须联动。预约成功时remain_count - 1，取消预约时remain_count + 1，这两个操作必须放在同一个事务里，并且要注意并发情况，否则会出现“明明没有了，还能约上”的情况。
• 不要为了省事把会员余额、剩余次数直接放在member表，一旦卡升级或过期要改的话，字段耦合很痛苦。单独member_card表让一个会员可以有多张卡，更贴近真实场景。

3.2 会员状态与卡状态

会员状态我定义为：正常、冻结、过期、退卡。会员卡要区分：未激活、生效中、已过期、已冻结。

这里有个业务经验：会员过期不代表这个会员要删掉，而是把它的卡状态改成过期，保留历史数据。这样才能统计“流失会员数量”，这对于健身房的运营很重要。冻结功能也好理解，比如会员出差两个月，申请暂停，就把卡的结束日期往后顺延，同时把状态置为冻结，冻结期间不能预约签到。

实现冻结操作的时候，service层要做三步：

1. 修改member_card的status为冻结。
2. 更新end_date（顺延时长）。
3. 在流水表登记一条“冻结延期”记录，方便财务核对。

三步必须加@Transactional，别问我怎么知道的，第一版没加，结果出现好几张卡状态改了日期没变的脏数据。

3.3 预约冲突检测

预约是这套系统里业务逻辑最需要动脑子的地方。我的设计思路是：教练同一时间不能有重叠课程，会员同一时间段不能预约两节课。

实现时不是等用户提交以后再硬查，而是在教练排课阶段就做一次冲突校验。排课时前台传入教练ID、开始时间、结束时间，后台SQL查一下：

SELECT COUNT(*) FROM course WHERE trainer_id = #{trainerId} AND status IN (1, 2) AND start_time < #{endTime} AND end_time > #{startTime}

这里用的是区间重叠判断逻辑，只要两个时间段存在交集，就说明冲突。我见过有人写成start_time >= ? AND end_time <= ?的判断，这是错的，因为课程A的时间是9:00-10:00，课程B的时间是9:30-10:30，B完全被A包含，等于B的查询条件里A既不“开始时间大于等于B开始时间”，也不“结束时间小于等于B结束时间”，就漏掉了。

会员预约时也做同样的校验，只不过把trainer_id换成member_id，并且需要排除掉已取消的预约记录。

3.4 财务统计

财务这块，我做了充值流水记录和消费流水记录。每次充值和扣款都要往payment表插一条。

统计日报的逻辑是：

SELECT DATE(create_time) AS date, SUM(CASE WHEN type = 'RECHARGE' THEN amount ELSE 0 END) AS recharge_amount, SUM(CASE WHEN type = 'PAYMENT' THEN amount ELSE 0 END) AS consume_amount FROM payment WHERE create_time >= #{startDate} AND create_time < #{endDate} GROUP BY DATE(create_time) ORDER BY date

月报就是把日期粒度改成月份，用DATE_FORMAT(create_time, '%Y-%m')分组。前端图表用ECharts展示，柱状图看充值、折线图看趋势，这个对管理员来说很直观。

4. 从零搭建项目与关键代码实现

4.1 创建项目与依赖配置

用IDEA新建Spring Boot项目时，我通常直接选择Spring Initializr，在依赖里勾选Spring Web、MySQL Driver、Lombok，然后再手动加上MyBatis-Plus等依赖。最终pom.xml里关键的依赖长这样：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.18</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.5</version> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <dependency> <groupId>com.auth0</groupId> <artifactId>java-jwt</artifactId> <version>4.4.0</version> </dependency> </dependencies>

这里注意，如果用的Spring Boot 3.x，mysql-connector-java的groupId变了，直接用新版就行，还有javax.servlet相关的包也要替换成jakarta.servlet。这也是为什么我建议新手老老实实用2.7.x的原因。

4.2 application.yml配置

我的配置内容如下，比较简单，不在这里做逻辑混淆：

server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/fitness_club?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai username: root password: 123456 mybatis-plus: mapper-locations: classpath:mapper/**/*.xml configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: id-type: auto

有人在搜“spring boot修改demo端口号”，改默认端口就是上面server.port这个配置。如果启动时8080被占用，要么改端口，要么用命令行mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=8081。

log-impl配置成StdOutImpl以后，控制台会直接打印SQL和参数，开发阶段排查问题很舒服。上线前记得把这个去掉，否则日志膨胀得吓人。

4.3 登录认证与权限拦截

登录这块没有引入特别重型的Spring Security，而是用JWT做了token验证。为什么这么选？因为后台管理系统的接口大多数是需要身份校验的，而Spring Security的配置学习和Debug成本对于这个体量的项目偏高，JWT配合拦截器完全够用。

我在common包里写了一个JwtUtil工具类，负责生成token和校验token。登录接口逻辑如下：

1. 根据用户名查sys_user表。
2. 用MD5加盐对比密码。这里有人会说MD5不安全，确实，但管理系统内部用MD5是历史遗留常规做法，如果要更安全，可以把密码字段换成BCrypt，代码改动也不大。
3. 生成token，里面塞入userId、username、role，过期时间设为24小时。
4. 前端把token存在localStorage，每次请求在请求头带Authorization: Bearer <token>。

拦截器在config包里注册一个WebMvcConfigurer，把/api/login/**、/api/open/**放行，其余所有/api/**都走token校验。校验通过后把当前用户信息放到ThreadLocal，方便后面业务逻辑里取操作人。

登录逻辑的代码大致这样：

public LoginResult login(String username, String password) { SysUser user = userMapper.selectOne( new LambdaQueryWrapper<SysUser>() .eq(SysUser::getUsername, username)); if (user == null) { throw new BusinessException("用户不存在"); } String md5Pwd = DigestUtils.md5DigestAsHex( (password + user.getSalt()).getBytes(StandardCharsets.UTF_8)); if (!md5Pwd.equals(user.getPassword())) { throw new BusinessException("密码错误"); } String token = JwtUtil.generateToken(user.getId(), user.getUsername(), user.getRole()); return new LoginResult(token, user.getRealName(), user.getRole()); }

4.4 会员开卡功能的接口实现

开卡是一个比较典型的跨表事务操作。会员到前台办卡，可能有两种情况：

• 新会员：先插入member记录，再插入member_card记录，再插入payment流水。
• 老会员办新卡：插入新的member_card记录，同时插入payment流水。

对应的service方法我加了@Transactional(rollbackFor = Exception.class)。这里有一个常见误区：只写@Transactional不指定rollbackFor，这样如果方法内部抛出的是自定义的RuntimeException能回滚，但如果你捕获异常后不抛出，事务还是不会回滚。所以一定要记住：事务回滚的前提是异常能传递到Spring的事务代理外面，捕获了就要重新抛出去。

开卡核心代码：

@Transactional(rollbackFor = Exception.class) public Long createMemberAndCard(MemberCreateDTO dto) { Member member = new Member(); member.setName(dto.getName()); member.setPhone(dto.getPhone()); member.setGender(dto.getGender()); member.setStatus(1); memberMapper.insert(member); MemberCard card = new MemberCard(); card.setMemberId(member.getId()); card.setCardTypeId(dto.getCardTypeId()); card.setStartDate(LocalDate.now()); card.setEndDate(LocalDate.now().plusMonths(cardType.getDurationMonths())); card.setTotalCount(cardType.getTimes()); card.setRemainCount(cardType.getTimes()); card.setStatus(1); cardMapper.insert(card); Payment payment = new Payment(); payment.setMemberId(member.getId()); payment.setType("CARD_OPEN"); payment.setAmount(cardType.getPrice()); payment.setPaymentMethod(dto.getPaymentMethod()); paymentMapper.insert(payment); return member.getId(); }

这个接口要在事务里跑，因为memberMapper、cardMapper、paymentMapper三个表要么全部成功，要么全部回滚。直观理解：办了卡但流水没记录下来，月底账就对不上；或者流水记录了但卡没办理成功，人家会员拿不到卡，都是大事故。

4.5 课程预约与取消预约

预约课程，我设计了两个接口：

• 预约：POST /api/booking
• 取消：POST /api/booking/cancel

预约时先做三步检查：

1. 卡是否在有效期内，status是否为正常。
2. 剩余次数是否大于0。
3. 该会员在该课程时间是否有冲突。

这三步同样要在同一个事务方法里。先SELECT ... FOR UPDATE锁定这条会员卡记录再扣次数，否则并发下会出现超卖。用MyBatis-Plus时，可以在Mapper里自定义方法：

<update id="deductRemainCount"> UPDATE member_card SET remain_count = remain_count - 1 WHERE id = #{cardId} AND remain_count > 0 </update>

注意这里的AND remain_count > 0很关键，它能帮你挡住并发超扣。如果返回影响行数为0，说明次数已经扣减失败，直接抛异常回滚。

取消预约就反过来：判断预约状态为已预约，改为已取消，同时把remain_count加回。这里有个边界情况要处理：如果课程已经结束了，就不允许取消预约，否则会有人事后“补取消”导致次数白赚。

4.6 前端页面与接口对接

前端我用Vue3 + Element Plus + Axios。工程结构大概是：

views ├── Dashboard.vue ├── Member.vue ├── Course.vue ├── Booking.vue ├── Payment.vue └── Login.vue

每个页面调用后端的接口，封装在src/api目录下面。Axios请求拦截器统一加上token：

service.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers['Authorization'] = 'Bearer ' + token } return config })

响应拦截器里统一处理401和业务错误码：

service.interceptors.response.use( response => { const res = response.data if (res.code !== 200) { ElMessage.error(res.msg) return Promise.reject(new Error(res.msg)) } return res }, error => { if (error.response && error.response.status === 401) { router.push('/login') } ElMessage.error('网络错误') return Promise.reject(error) } )

项目开发时Vite默认8080端口会和后端冲突，所以我在vite.config.js里设置了代理：

server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }

这个代理能解决前端开发时的跨域问题。你要是搜过“vscode spring boot”，你会发现在VS Code里也可以直接运行和调试Spring Boot项目，配上Spring Boot Extension Pack插件，效果和IDEA差不多，不过是改端口的话就去application.yml里改就行。

5. 实操过程中踩过的坑与排查实录

5.1 时间字段的时区问题

这个项目在第一次部署到服务器时，突然发现课程表的开始时间全部比实际时间晚了8个小时。排查下来是JDBC连接串里没有加serverTimezone=Asia/Shanghai，本地MySQL和服务器MySQL的默认时区不一致导致的。

解决办法就是在数据库连接URL上显式指定时区：

serverTimezone=Asia/Shanghai

同时在实体类里，日期时间字段我全部用LocalDateTime而不是java.util.Date，配合Jackson的配置，能避免很多序列化问题。如果前端需要展示格式化好的日期，应该在DTO里返回字符串，不要直接返回LocalDateTime让前端自行处理格式。

5.2 MyBatis XML文件里的特殊符号

在写预约冲突检测SQL时，XML文件里的<和>直接使用是会报错的，因为XML解析器把它们当成了标签符号。解决方式有两种：

• 转义：<写成<，>写成>。
• 用<![CDATA[ ]]>包裹SQL片段。

我比较推荐用CDATA，因为可读性更强。比如：

<select id="checkConflict" resultType="java.lang.Integer"> <![CDATA[ SELECT COUNT(*) FROM course WHERE trainer_id = #{trainerId} AND status IN (1, 2) AND start_time < #{endTime} AND end_time > #{startTime} ]]> </select>

这个坑对于第一次用MyBatis的新手来说几乎必踩，我见过有人把整个SQL的前后都包上CDATA还发现报错，原因是CDATA内部不包含]]>就行，别嵌套使用即可。

5.3 事务不生效的三种情况

项目中遇到过三次事务不回滚的问题，背景各不相同，但都很有代表性。

第一种：方法内部自己调自己。比如Controller直接调service的一个方法，而这个方法内部又调用了同类中的另一个方法。由于Spring事务是通过代理实现的，同类内部调用不会走代理，事务自然不生效。解决方式是拆成两个Bean，或者把事务注解放到Controller层调用的入口方法上。

第二种：异常被捕获后没有抛出。有个需求是要在预约失败时记录日志，于是我在service里加了try-catch，把异常吃掉以后返回false，结果前面的会员卡扣次数操作也一起被提交了。解决方式是改用事务监听器或者在catch里重新抛出异常。

第三种：事务方法不是public。Spring的@Transactional只对public方法生效，改成private后Spring不报错，但事务完全没有包住任何敏感操作。这个要仔细检查方法声明。

5.4 MyBatis-Plus的字段自动填充问题

创建时间和更新时间如果每个表都手动去set，很容易漏。我用MyBatis-Plus的MetaObjectHandler实现自动填充：

@Component public class MyMetaObjectHandler implements MetaObjectHandler { @Override public void insertFill(MetaObject metaObject) { this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now()); } @Override public void updateFill(MetaObject metaObject) { this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now()); } }

实体类字段上要加@TableField(fill = FieldFill.INSERT)和@TableField(fill = FieldFill.INSERT_UPDATE)。这个功能能省去很多重复代码，但要注意如果数据库字段和实体类字段命名不一致，一定要在字段上标注@TableField("create_time")。

5.5 并发预约导致超卖

第一次上线测试时，我拿了两个账号同时抢同一节课，结果两个都预约成功了，但数据库里remain_count只减了1。原因就是前面提到的扣减次数SQL没有带AND remain_count > 0条件，也没有加行锁。

修正方案是两步并行：

• 扣减SQL带条件。
• 在service里先用SELECT id FROM member_card WHERE id = #{cardId} FOR UPDATE锁行，再执行扣减。

实际测试下来并发100个线程也不会出现超卖。不过FOR UPDATE锁的粒度是行级，前提是查询走了主键索引，如果查出来是全表扫描，MySQL会在某些情况下升级为表锁，性能就会急剧下降。

5.6 前端菜单权限暴露问题

后台管理界面一开始把“财务统计”菜单只做了前端隐藏，结果有个员工改了localStorage里的role字段，菜单就显示出来了，还能访问统计接口。这个教训说明：前端隐藏菜单只是体验优化，真正的权限控制必须在后端做。我在拦截器里增加了基于角色的接口放行判断，比如财务统计类的接口只允许ADMIN角色访问，这样就算前端被篡改，后端也会拒绝响应。

5.7 报表查询慢的优化

数据量到几十万条以后，日报表SQL查起来明显变慢。我的优化手段主要有：

• payment表在create_time字段上建索引，日报月报查询基本走索引。
• 报表类查询不要实时去跑原始流水，可以每天凌晨用一个定时任务把昨天的统计数据汇总到stats_daily表，查询时直接读汇总表。
• Spring Boot里做定时任务很简单，在启动类上加上@EnableScheduling，然后在方法上写@Scheduled(cron = "0 30 2 * * ?")表示每天凌晨2点30分执行。

这里的定时任务如果要做幂等控制，可以在执行前先查一下stats_daily表有没有当天的记录，有就跳过，避免重复调度导致数据翻倍。

5.8 启动不了的常见问题速查

顺手整理一份高频问题的排查对照表：

系统做到这个程度，我个人最大的体会是：Spring Boot本身并不难，难的是把业务规则和框架能力揉在一起。预约冲突、并发扣减、事务回滚、权限拦截，这些才是区别一个“能跑的demo”和“能用的系统”的分界线。你在网上搜“spring boot 实现监控，都有哪些需求和功能”，会发现一堆人讨论监控指标、接口监控、系统监控，那当然很好，但健身俱乐部这个项目再往上扩，还可以做消息推送提醒会员上课、对接小程序端让会员自助约课、用Redis缓存热门课表减轻数据库压力，扩展路径是现成的。

最后分享一个开发时的小习惯：每个复杂接口写完以后，除了用Postman调通正常流程，一定再手测一遍异常情况。比如会员卡已过期去预约，已经约满的课再去约，取消已经上完的课。把这些边界场景的数据也造出来放进数据库里，跑一遍看会不会报错。老话讲“能跑通不算本事，各种怼都不出问题才是”，这句话用在管理系统开发上，一点不假。