接手过健身房管理系统这类项目的同学应该都知道它表面上是个“增删改查”但真正做起来涉及会员、私教、团课、储值卡、临时卡、预约、排班、营收统计一堆业务逻辑稍不注意模块边界和数据库设计后期就会改到怀疑人生。我这次分享的是一个基于 SpringBoot Vue MyBatis MySQL 的健身房管理系统前后端分离源码可以直接跑起来改很适合用来做毕业设计、个人项目或者给中小型健身房做一套轻量级 SaaS 化的基础版本。这篇文章会把整个系统从设计思路、数据库建模、后端核心实现、前端联调到打包部署和常见坑位完整走一遍已经踩过的坑都直接标出来能帮你省不少时间。1. 系统整体设计思路与技术选型拆解1.1 这个项目到底解决什么问题健身房管理系统的核心价值是把线下门店的几类高频业务搬到线上会员办卡与续费、会员上下店核销、私教课约课与销课、团课排期与预约、商品零售毛巾、补剂、运动装备以及月底的营收统计和会员到期提醒。如果你只做最简单的会员信息增删改查那叫表格管理软件不叫管理系统真正让店长愿意天天打开系统的是“办卡后额度自动变化”“预约课程后库存自动减少”“会员卡到期前能够批量导出名单发送短信”这类联动逻辑。所以做这个项目之前我建议你先对着真实健身房的工作流走一遍前台开卡会做什么操作教练上私教课怎么刷会员卡扣课时会员在公众号或者小程序上看到团课课表后如何锁定一个位置。把这几个主流程理清了代码其实就是体力活。项目里我按“基础资料 - 业务动作 - 统计报表”三层来划分模块基础资料包括会员、会员卡类型、课程、教练、门店业务动作包括办卡、续费、预约、签到、划扣统计报表则包括日营收、卡种销量、课程出勤率、会员流失预警。这样划分的好处是职责清晰后续给前台、教练、店长做不同角色权限的时候只需要按模块挂菜单即可。1.2 为什么选择这套技术栈SpringBoot Vue MyBatis MySQL 已经是国内中小型管理系统里最常见的一套组合选它不是因为它多先进而是因为它足够“稳”且能随时找到人接手。SpringBoot 解决了传统 SSM 里大量 XML 配置的痛点内嵌 Tomcat 让部署变成一个 java -jar 命令版本管理上直接用 Maven 依赖坐标就能锁定Vue 的优势是组件化开发加上生态足够成熟Element Plus 或者更老牌的 Element UI 直接能把后台管理界面搭个八九不离十MyBatis 这种半自动 ORM 在复杂多表查询时非常灵活动态 SQL 可以自己控制每一条 SQL 的拼装逻辑比 JPA 那种全自动方案更直观排查性能问题也更容易MySQL 则不需要多说稳定、免费、资料多健身房这种体量的并发完全够用。有人会问为什么不用 Spring Cloud 或者微服务。说实话健身房单店或者几店连锁的数据量单体应用完全没有压力微服务带来的分布式事务、服务治理、部署复杂度反而会拖垮小团队的交付进度。技术选型这件事永远是匹配业务复杂度而不是越“高级”越好。这个项目里我建议保持经典的单体架构后端拆成 controller、service、mapper 三层前端拆成视图组件、路由、API 模块将来如果真的要扩展多门店再在现有结构上拆独立服务也不迟。1.3 功能模块全景图与角色权限设计系统把用户分为三类角色系统管理员、前台/运营、教练/私教。管理员负责卡种配置、课程管理、教练排班、数据报表前台负责会员开户、办卡续费、散客入场登记、商品零售教练负责查看自己的排课表、确认学员到场、标记课程完成。权限这块我没有引入 Spring Security 那套复杂的过滤器链而是用 JWT 拦截器加自定义注解来控制接口权限原因是内部管理系统角色固定、接口数量有限手写一个注解拦截比引入全套安全框架更轻量也更容易讲清楚原理。权限模型大致是用户表存账号密码和角色标识登录成功后返回一个包含用户 ID 和角色标识的 JWT前端把 Token 存在本地存储每次请求在请求头带上后端写一个 HandlerInterceptor先校验 Token 有效期再从 Token 里解析出角色和自定义注解 RequireRole(admin) 对比不匹配就返回 403。这样做的好处是接口级别的权限控制粒度足够又不会让新手被一堆 AuthorizationManager 配置绕晕。功能清单上我按管理端和用户端两个视角整理过核心菜单管理端包括工作台、会员管理、卡务管理、课程排期、预约订单、商品管理、系统设置用户端则是面向学员的课表浏览、在线预约、历史记录第一个版本可以先不做小程序做一个移动端适配的 H5 页面即可后续再套壳成小程序。2. 核心业务模块与数据库表设计2.1 业务模块划分与状态机设计健身房的业务里藏着一个很容易被忽略的点很多字段不是简单的字符串而是带有状态流转的。比如一张会员卡它的生命周期是“未激活 - 生效中 - 已暂停 - 已到期”到期后还有 30 天宽限期宽限期结束后才真正失效再比如一节团课预约状态是“已预约 - 已签到 - 已取消”但取消又分为用户主动取消和系统超时自动取消超时自动取消后名额要释放给其他用户。如果不对这些状态做统一管理代码写到最后一定是到处 if-else非常难维护。所以我在设计模块时把状态相关的逻辑单独抽了一层给每个核心实体定义一个状态枚举并把所有状态流转写在 Service 层的独立方法里。拿会员卡来说续费操作会触发状态从“已到期”变回“生效中”同时把过期时间往后延部分健身房的卡类型还允许“冻结”操作会员出差可以申请暂停一个月暂停期间不计算有效期。这些规则看起来零散但都属于同一个领域模型统一由 CardService 处理就规范很多。团课预约模块则涉及名额的并发控制这个我后面会专门讲涉及数据库乐观锁和唯一索引如果你直接用了“先查一下再插入”的方式一定会遇到超卖问题。2.2 数据库表结构设计详解数据库设计是整个项目的重中之重我直接给出一版经过验证的建表方案。核心表包括member会员表、member_card会员卡表、card_type卡种表、course课程表、course_schedule排课表、appointment预约记录表、payment_order订单表、employee员工/教练表。会员表跟会员卡表我特意做了拆分因为一个会员在健身房历史上可能办过多张卡比如先办了季卡后来又续年卡如果直接给会员表加一个 expire_date 字段历史记录就丢了。会员卡表是最有意思的一张表关键字段有 card_no卡号、member_id、card_type_id、remain_count剩余次数、valid_start、valid_end、status。私教课次卡需要记录剩余次数储值卡则需要一个 balance 字段这两类卡的计费逻辑完全不同我建议用卡种表里的 card_category 字段来区分次卡走扣次数时长卡只看有效期储值卡走余额扣款。这样在续费的时候只需要根据 card_category 走不同分支即可。为了避免多张关联表之间产生复杂的实时计算我在订单表里冗余存储了消费时的卡名、卡类型、单价、数量等快照字段这样后期拉充值流水报表时即使卡种被删改也不影响历史数据。排课表 course_schedule 需要设计成能支持每周重复的排班形式我采用的方案是存 start_time、end_time、coach_id、course_id、max_member、signed_up_count 以及一个 schedule_date 字段作为实际上课日期。对于每周重复的固定课表后台提供一个“按周规则生成”的辅助方法一次性生成未来四周的排课记录如果某天教练请假则单条记录做暂停标记。这样实现比存 cron 表达式再动态解析要直观得多查询某天课表直接 where schedule_date 某天 即可索引也非常简单。2.3 表关系与 MyBatis 多表查询映射这些表之间的关系并不复杂会员与会员卡是一对多会员卡与卡种是多对一课程排课与课程是多对一预约记录与排课、会员是多对一。反而多对多关系出现在了“教练与门店”和“课程与可选教练”这类配置场景但我也都用中间表拆掉了。MyBatis 处理这种一对多关系我建议尽量用分页查询加子查询的方式避免一次性加载深层次的嵌套集合。比如会员列表页只需要会员表关联卡表查出一个“当前有效卡数量”字段而不是把每张卡的完整明细都塞进 resultMap 里。因为一旦嵌套了集合分页就会出问题总记录数会被笛卡尔积放大这是个非常经典的坑。对于预约订单这类核心列表接口我用 XML 文件里手写多表联查 SQL配合自定义的 resultMap 进行映射。一个典型的写法查询预约记录时 left join 排课表、课程表、会员表、教练表把需要展示的字段一次性查出来用别名映射到 DTO 对象。虽然看起来有点辛苦但优势是 SQL 执行的效率可控而且前端需要什么字段完全可以照着写不用像 JPA 那样为了懒加载掉进 N1 查询的坑。课程列表页展示“可预约数”时我习惯在 SQL 里直接算 max_member - signed_up_count 这个虚拟字段而不是查两次再做减法。3. 核心环节实操后端与前端完整衔接3.1 工程初始化与版本兼容要点这个项目我会直接推荐一套稳定的版本组合JDK 1.8稳妥或 JDK 17如果想用新特性SpringBoot 2.7.xMyBatis 相应使用 mybatis-spring-boot-starter 2.3.xMySQL 使用 8.0 版本前端 Vue 2.7 Element UI 2.15如果是新手或 Vue 3 Vite Element Plus如果能熟练掌握 setup 语法。需要特别注意的是SpringBoot 3.x 对 JDK 版本要求是 17 及以上并且很多第三方 starter 的包名从 javax 换成了 jakarta如果你照着网上 SpringBoot 2.x 的老教程做会遇到一堆编译错误。我的建议是如果只是做课设或者练习直接锁死 SpringBoot 2.7.18 JDK 1.8这是社区资料最全、踩坑成本最低的组合如果是企业新项目可以用 SpringBoot 3.x 但必须统一所有依赖的版本。项目骨架创建我一般先用 Spring Initializr 生成手动勾选 Web、MySQL Driver然后单独引入 MyBatis 的 starter 和 Lombok。IDEA 里要注意 Maven 仓库的配置国内网速下建议换阿里云镜像否则第一次拉依赖可能会卡到怀疑人生。后端目录结构上我习惯按模块分包而不是按技术层分包比如把 member、card、course、order 作为顶级包每个包下面再放 controller、service、mapper、entity、dto。这样做的好处是业务归属感强改会员相关功能时相关的 Controller 和 Service 都在同一个包下面而不需要在一大堆 xxxController 列表里翻半天。3.2 MyBatis 整合细节与 XML 配置实践MyBatis 的整合主要区分两种方式注解 SQL 和 XML 映射。健身管理系统这种业务比较复杂的项目我建议核心报表查询走 XML简单增删改走注解。XML 文件里最容易犯的错误是忘了在 application.yml 配置 mapper-locations导致启动时报 Invalid bound statement (not found)。正确的配置是这样的spring: datasource: url: jdbc:mysql://localhost:3306/gym_system?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.gym.system.entity configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl这里有两个关键点要注意第一MySQL 8 的连接 URL 必须带 serverTimezone否则会报时区错误第二useSSLfalse 可以避免 SSL 连接警告allowPublicKeyRetrievaltrue 是在 MySQL 8 使用 caching_sha2_password 认证插件时必需的否则会报 Public Key Retrieval is not allowed 的错误。map-underscore-to-camel-case 这个配置强烈建议打开可以让数据库字段 create_time 自动映射成 Java 属性 createTime少写很多手动映射。XML 里动态 SQL 是 MyBatis 的灵魂拿会员列表的搜索来说条件可能有姓名、手机号、卡状态、过期时间范围用 if 标签拼接最方便但拼接 SQL 时有个容易踩的坑直接在 where 后面加 and 会导致如果第一个条件不成立SQL 变成 where and xxx。解决办法是使用 标签它会自动忽略掉第一个多余的 and 或 or。3.3 后端核心业务实现预约与扣次并发控制预约团课这个功能表面上就是往 appointment 表插一条记录但真正写代码的时候必须考虑“超卖”问题两个会员同时看到剩余 1 个名额同时点击预约。如果先查询剩余名额再插入预约记录两个请求都会通过查询然后都插入成功最后 signed_up_count 变成了负数。解决这个问题有两个常用方案我项目中用的是数据库层面的乐观锁加唯一索引组合。第一步在 appointment 表上建立 (member_id, course_schedule_id) 的唯一索引保证同一个会员对同一节课只能有一条预约记录。第二步在更新排课表名额时不用普通的 update 语句而是用带条件的更新update course_schedule set signed_up_count signed_up_count 1 where id #{scheduleId} and signed_up_count 1 max_member。这样在数据库层面就保证了名额不会被超额affected rows 等于 0 就说明名额已满直接返回友好提示。这里不需要麻烦的 Redis 分布式锁因为很多健身房系统本身就是单机部署数据库原子更新已经足够。给会员卡扣次数的逻辑也是同样的思路扣次数时在 update 语句里加剩余次数大于 0 的判断避免负数。预约接口的整体流程大致如下校验会员卡是否在有效期内并检查剩余次数或储值余额检查排课状态是否为“可预约”且未超过截止时间执行预约插入和扣次操作注意这里要把两条数据操作放在同一个事务里如果扣次发生在预约时那么取消预约就要自动回补次数回补的同时也要判断卡当前状态避免过期卡因为回补次数而“复活”。项目里我把这些动作都写在 CourseAppointmentService 里事务注解直接加在 public 方法上注意不要出现类内部方法调用导致事务注解失效的情况。3.4 Vue 前端搭建与接口联调前端搭建如果是从零开始我的推荐路线是先装 Node.js建议用 18 或者 20 的 LTS 版本太老或太新的版本都可能跟依赖包冲突。创建 Vue 项目可以直接用 Vue CLI 或 ViteVue 2 项目用 vue createVue 3 项目用 npm create vite。安装完依赖后第一件事是配置代理解决本地开发跨域问题在 vue.config.js 里把 /api 开头的请求代理到后端地址后端 Controller 里的 RequestMapping 统一加一个 /api 前缀。这样线上部署时前端打包出来的静态文件可以直接放在后端静态资源目录下两者共用一个端口连跨域问题都彻底绕开了。Axios 封装这块我建议每个前端项目都做一个 request.js 工具类统一设置 baseURL、请求超时时间、请求拦截器自动附加 JWT Token响应拦截器统一处理 HTTP 401 跳转到登录页、业务码非 0 时弹出错误提示。这样后端返回的 JSON 结构最好也统一一下我常用的返回体是 { code: 200, message: success, data: {} }这样前端拦截器写起来非常干净。路由那边项目里我用到了 vue-router管理端采用动态路由方式根据后端返回的角色权限动态注册菜单而不是把全部路由写死在代码里这样能避免学员角色在地址栏手动输入管理员路径就能看到后台页面的问题。Element UI 的表格和表单组件非常省事会员管理列表页基本就是 el-table el-dialog el-form 的组合。需要注意的一个细节是日期组件绑定值的类型默认返回的是 Date 对象而后端接口往往需要字符串提交前需要格式化。我建议统一用 dayjs 或自己写一个 formatDate 工具函数把日期都转成 yyyy-MM-dd HH:mm:ss 格式再提交。另一个容易忽略的问题是表格序号和分页参数el-pagination 的 current-page 和 page-size 要通过 v-model 绑定在后端接口里对应 pageNum 和 pageSize 参数。4. 常见问题排查与避坑实录4.1 条件查询不生效MyBatis 动态 SQL 的坑做会员列表条件搜索时遇到最多的问题就是“我传了姓名参数但是 where 条件没生效”或者“SQL 拼接错误”。第一种情况大概率是 XML 里 if 标签 test 写的参数名不对比如 Java 字段是 memberNameXML 里写的是 name而 MyBatis 的 OGNL 表达式对 null 或者空字符串的判断跟 Java 不太一样如果参数是 nulltestmemberName ! null and memberName ! 的值是 falseSQL 就不拼接了。排查这类问题最快的办法是把 mybatis 的 log-impl 配置成 StdOutImpl直接看控制台打印的 SQL 和参数一目了然。第二种情况是拼接顺序问题。虽然 标签能自动去掉第一条 and但当条件包含一些非等值比较比如 time range 查询用 ]] 符号时要注意 MyBatis 会把 和 当作标签符号解析必须用 CDATA 包裹或者转义。还有一点如果前端传过来的是一个空数组用 foreach 标签遍历 in 条件时collection 参数名写错也会导致编译报错建议 collection 统一指定为参数对象的属性名。4.2 前后端联调中的跨域与路径问题本地开发最常见的就是跨域报错浏览器控制台提示 Access-Control-Allow-Origin。我之前提到用 devServer 代理解决但如果后端没有配置支持跨域线上分开部署时还是会遇到。解决方式两种一是在后端写一个全局 CORS 配置类允许指定来源的请求带 Token 访问二是更省事的把前端打包后的 dist 目录直接放到 SpringBoot 的 static 目录或者用 Nginx 统一代理到后端端口统一以后就不存在跨域了。线上部署我用得比较多的是 Nginx 方案Nginx 监听 80 端口/ 路径指向前端静态文件/api 路径 proxy_pass 到后端服务的 8080 端口这样既保证了性能也避免前端打包进 jar 后每次改页面都要重新打后端包。另外一个很隐蔽的问题是刷新页面 404。管理端用 history 模式的路由时每次刷新非首页路径Nginx 会去真实路径找文件然后报 404解决方法是 Nginx 配一个 try_files $uri $uri/ /index.html。如果你用的是 hash 模式则没有这个问题但地址栏会带 #看个人取舍。4.3 MySQL 安装与连接阶段的连环坑不少同学卡在最开始的 MySQL 安装上尤其是 Windows 环境。官方安装包走图形界面相对省心但企业里很多时候是用免安装版或 Linux 环境装。Windows 下免安装版需要注意解压后需要新建 my.ini 配置文件里面指定 basedir 和 datadir然后用命令行执行 mysqld --initialize-insecure 初始化数据目录再执行 mysqld --install 注册服务最后 net start mysql 启动。初始化后 root 用户默认无密码需要登录后自己 ALTER USER 修改密码。Linux 上通过 rpm 或者 tar 包安装时5.7 和 8.0 的初始化命令不一样5.7 用 mysqld --initialize8.0 也一样但会生成临时密码在日志里找日志这一步经常让新手栽跟头。连接阶段常见问题是 SSL 错误和时区错误。SSL 相关报错一般是 url 里 useSSL 参数引起的开发环境直接 false 即可时区问题就是忘记加 serverTimezone报错信息会出现 The server time zone value。另外 MySQL 8 的默认认证插件是 caching_sha2_password老旧版本的 JDBC 驱动不兼容所以必须用 mysql-connector-java 8.x 以上版本最好直接使用 com.mysql.cj.jdbc.Driver。我遇到过还有人把数据库密码设置成包含特殊字符如 # 的结果 url 里的密码没转义导致连接失败建议开发环境密码尽量简单。4.4 关于 SpringBoot 版本太高引发的连锁反应最后想专门聊聊 SpringBoot 版本问题因为最近很多人一上来就用 IDEA 默认的 SpringBoot 3.x 最新版结果网上找到的教程全是 SpringBoot 2.x导致各种不对劲。SpringBoot 3.0 开始强制要求 JDK 17同时把 javax.servlet 迁移到了 jakarta.servlet如果你引用的第三方工具包还停留在旧版本就会出现 ClassNotFoundException 找不到 javax.servlet.Filter 之类的错误。另外 SpringSecurity 6 的配置方式和 5 完全不同如果直接用网上 5.x 的 SecurityConfig 代码大概率编译都过不了。我的建议非常直接新手别追新用 2.7.x 足够如果确实用了 3.x所有依赖都去 mvnrepository 确认对应的最新版本特别是 mybatis-spring-boot-starter 要用 3.0 以上才支持 JDK 17。5. 部署上线实用指南与后续扩展建议以上四个大块把设计、库表、编码、排坑都讲完了部署这块单独补充一段。项目打好的后端 jar 包放到服务器上命令是 java -jar gym-system.jar但如果要长期运行建议配合 systemd 服务或者用脚本管理进程避免终端关掉服务就停了。前端打包则是 npm run build生成 dist 目录把 dist 里的文件拷贝到服务器 Nginx 的 html 目录并配置好 proxy 转发。在服务器上如果数据库用的是宝塔面板这类工具要注意开启数据库的远程访问权限或者直接在服务器本地连接数据库避免暴露 3306 端口造成安全隐患。上线前一定要做三件事默认的管理员密码强制修改、数据库开启自动备份、日志打印级别调整为 warn 级别否则硬盘很快被庞大的 debug 日志塞满。后续扩展方向我实际验证过的路径第一是增加 Redis 缓存热点数据想提升首屏性能把课程表、卡种列表这类不常变化的数据缓存起来一是减少数据库压力二是课程预约的并发控制可以升级为 Lua 脚本加 Redis 原子操作第二是增加微信小程序客户端复用现有的后端接口只需要新写一层小程序的登录鉴权把 JWT 换成微信 code 登录换取 openid 再签发 JWT 即可第三是增加简单的数据大屏展示通过 ECharts 展示实时的会员增长、课程出勤率和营收趋势这类功能给店长看非常加分同时能进一步检验你当前统计表设计是否合理。做这个系统时我自己最大的体会是不要急着写代码先花两天把业务表关系和状态流转理清楚后面开发的速度会翻倍。希望这份实操总结能给正在做类似系统的人省下一些折腾时间。