前后端分离这类项目最怕的就是“源码拿到手却跑不起来”。尤其是健身俱乐部这种带会员管理、课程预约、私教计费的系统业务逻辑一眼看不全启动报错倒是花样百出。我之前接手过一个类似的模拟项目X源码也是 SpringBoot Vue MyBatis MySQL 这套组合前后端分离表面看着不复杂真正动手部署才发现坑全藏在细节里。这套系统主要解决的是健身俱乐部日常运营中最琐碎的三件事会员信息与储值卡管理、课程与私教预约、以及基础的订单消费记录。它不是一个摆样子的Demo而是能实际跑起来、有完整前后端交互的代码项目。适合正在学 SpringBoot 和 Vue 的开发者用来练手也适合需要快速搭一套内部管理系统的同学直接改改就用。我下面把整个项目的设计思路、核心代码逻辑、部署步骤和踩坑记录都掰开讲清楚保证你照着做能少走一半弯路。1. 项目概述1.1 这套健身俱乐部系统到底解决什么问题健身俱乐部日常运营里最头疼的往往不是训练本身而是“人”和“课”的管理。会员来了要登记、要办卡、要扣次、要续费教练排了课会员要预约约满了要候补放鸽子了要处理私教课一节多少钱、怎么消课时、会员卡什么时候到期这些问题全靠 Excel 和微信聊天记录来搞迟早出乱子。这个项目就是针对这些场景设计的。它把会员、教练、课程、卡类型、预约记录、消费流水这几类核心数据统一管理起来提供了一套可以实际使用的管理后台和用户操作界面。管理员能维护会员资料、管理课程分类和排课、查看所有订单会员可以浏览课程、预约课程、查看自己的卡信息和消费记录。说白了它是一个典型的“内部管理系统 用户端小程序”的简化版只不过用户端做成了 Web 页面。1.2 技术选型为什么是 SpringBoot Vue MyBatis MySQL这个技术组合在目前的Java后端项目里属于最经典、资料最多、招聘需求也最常出现的搭配用来做毕业设计或者项目实战都合适。SpringBoot解决了传统 Spring 配置繁琐的问题内置了 Tomcat一个main方法就能把后端跑起来非常适合快速开发这类单体管理系统。Vue负责前端页面和交互配合 Element UI 这类组件库能快速搭建出看起来很像样的管理界面而且前后端分离的开发模式让不同角色的开发者可以并行工作。MyBatis作为持久层框架SQL 是自己写的对于这种业务逻辑相对固定的项目反而比 MyBatis-Plus 更容易让人理解数据是怎么查出来、怎么映射成对象的。后面排查 SQL 问题也直观。MySQL不用多说开源、免费、稳定中小型项目基本首选。很多人会纠结为什么不用更流行的 Spring Cloud 微服务或者前后端不分离的 Thymeleaf。我的看法是这个项目的体量决定了它的复杂度上限。健身俱乐部管理系统最多几十张表并发量也有限用微服务纯属自己给自己找麻烦。前后端分离的好处是后期如果想把用户端拆成小程序后端接口几乎不用动复用价值很高。2. 整体设计与核心模块拆解2.1 前后端分离的标准架构整个项目分为backend和frontend两层后端提供 RESTful API前端通过 Axios 发送请求获取 JSON 数据渲染页面。从数据流向上看大概是这样一个流程浏览器页面 - Vue 组件 - Axios 请求 - SpringBoot Controller - Service - MyBatis Mapper - MySQL 数据库。后端没有用复杂的多模块拆分就是标准的 Controller-Service-Mapper 三层。这个设计很干净面试的时候也容易讲清楚。Controller 只做参数接收和响应封装Service 写业务逻辑Mapper 管数据库操作。实体类对应数据库表DTO 用于接收前端参数VO 用于返回给前端展示。这种分层方式虽然不是最潮的但胜在清晰别人接手你的代码半小时就能看懂。前端部分Vue 的目录结构也是常规套路views存放页面router配置路由api封装所有请求store如果是 Vuex管理登录状态。页面组件按功能划分比如会员管理页、课程管理页、预约管理页、登录页。组件之间尽量不直接跳转去拿数据统一走路由参数和接口请求这样维护起来不会越改越乱。2.2 会员管理模块与权限设计会员模块是这个系统的基础包含会员信息的增删改查、会员卡绑定、卡状态管理、到期提醒等功能。数据库里通常会有这几张核心表会员表member、会员卡表card、卡类型表card_type以及消费记录表consume_record。这里最关键的逻辑是卡类型和会员卡的状态联动。卡类型比如“季卡”“年卡”“50次次卡”每张会员卡都关联一种卡类型并有自己的开始时间、结束时间和剩余次数。到期之前要能续费续费分两种延长时间针对时长卡或增加次数针对次卡。很多新手在做这个模块时容易把“卡类型”和“会员卡”混在一起导致续费逻辑写得很绕。正确做法是卡类型是模板会员卡是实例续费时只调整会员卡的字段不需要动卡类型。权限设计上这个系统至少要有两种角色管理员和会员。管理员可以访问所有后台管理页面会员只能看到自己的信息和课程预约页面。后端用了一个简单的拦截器在请求进入 Controller 之前校验请求头里的 Token然后根据 Token 解析出来的角色判断能不能访问。没有用 Spring Security 这种重量级框架因为角色少自己写拦截器反而更可控也方便理解原理。2.3 课程预约、私教服务与计费逻辑课程预约是健身俱乐部系统的核心业务也是最容易出逻辑漏洞的地方。课程表course和排课表schedule需要拆开。课程是固定的比如“动感单车”“瑜伽基础”排课是课程的一个具体时间实例比如“周一晚上7点-8点 动感单车 教练A 限额20人”。会员预约排课时系统要做几件事先校验该排课是否还存在、是否已约满再校验会员是否有有效的卡卡状态要是正常预约成功后排课的已约人数加一生成一条预约记录。这里需要注意并发问题。如果两个人同时抢最后一个名额简单的先查询后更新会出现超卖。我看到的这个项目源码用的是数据库行锁也就是在更新排课表已约人数时使用UPDATE schedule SET booked_count booked_count 1 WHERE id ? AND booked_count max_count用受影响行数来判断是否成功。这是个很实用的处理方式虽然不如 Redis 分布式锁高级但在这个场景下完全够用而且不容易出问题。私教服务的核心是课时包。会员购买了比如“20节私教课”每预约一次私教课并完成后扣减一次剩余课时。这个逻辑在数据库里体现为关联私教订单表和消课记录表每次消课都要记录时间、教练、会员避免日后扯皮。3. 源码结构与实操部署全流程3.1 拿到源码后先看什么目录结构与关键配置不管代码是从哪里下载的第一步永远不是急着启动而是先摸清家底。打开项目根目录应该有backend或server和frontend或web两个文件夹。先看 README没有 README 的就看配置文件这比直接运行重要得多。需要重点看的文件包括后端application.yml或application.properties里面配置了数据库连接、端口、文件上传路径等关键信息还有前端的.env.development或src/api/request.js里面配置了接口请求地址和代理规则。这些配置不改对后面启动必报错。我看过太多人拿着源码跑不起来最后发现是 MySQL 密码没改成自己的。3.2 数据库导入与环境准备数据库这块项目里一般会附带sql文件夹里面有建库建表脚本和初始数据。导入时要注意几点数据库版本建议 5.7 或 8.0导入前先创建好数据库指定 utf8mb4 字符集避免中文乱码。如果脚本里没有写CREATE DATABASE那就自己先建库再导入。导入后打开每个表检查一下重点看一下member表有没有测试账号密码card_type表有没有初始卡类型数据。很多时候系统跑起来了但登录不进去是因为初始数据没导入完整。准备环境时后端需要 JDK 1.8 或以上Maven 3.6前端需要 Node.js 14npm 或 yarn 都行。这些工具安装就不多说了网上教程很多关键是注意版本别太新。比如 Node.js 18 以上的版本跑旧项目经常因为依赖兼容性报错我建议直接用 Node 14 或 16稳定。3.3 后端启动步骤与常见配置后端启动步骤很固定但很容易踩坑。用 IDE比如 IntelliJ IDEA打开backend目录让 Maven 自动下载依赖。如果下载慢就在 Maven 的settings.xml里配置国内镜像。修改application.yml里的数据库地址、用户名、密码。这里有个细节如果你本机的 MySQL 端口不是默认的 3306一定要改连接字符串比如jdbc:mysql://localhost:3306/fitness?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai时区参数建议加上不然后端启动会报时区错误。找到启动类就是类名上带SpringBootApplication的那个右键运行。看到日志输出 “Started ... in X seconds” 就说明启动成功。启动后先别急着连前端直接在浏览器访问http://localhost:8080/xxx看是否能返回 JSON 或页面确认接口通不通。后端比较容易出的问题有两个一个是端口被占用报Port 8080 was already in use另一个是数据库连接失败报Access denied for user。前者改端口或者在命令行netstat -ano找到占用进程关掉后者检查用户名密码和权限。3.4 前端启动步骤与接口联调前端启动之前先检查src/api/request.js或src/utils/request.js里的baseURL。两种常见做法一种是直接写完整的后端地址比如http://localhost:8080另一种是写成/api然后在vue.config.js里配置 devServer 代理。如果使用了代理访问前端的 8081 端口时接口请求会自动转发到后端 8080这样浏览器就不会有跨域问题。启动命令npm install这里容易卡很久主要是依赖包体积大。建议使用镜像源安装然后npm run dev启动成功后打开浏览器访问http://localhost:8081正常会跳转到登录页。如果页面打不开先确认端口再去vue.config.js里看端口配置。联调阶段最常遇见的就是请求 404 或 500404 大多是接口路径写错500 大多是后端抛异常直接看后端控制台日志定位。4. 核心功能实现细节4.1 登录鉴权与 Token 处理登录逻辑不复杂但属于前后端交互最核心的部分。流程是前端提交用户名和密码后端校验通过后生成一个 Token 返回给前端前端把 Token 存到 localStorage 或 sessionStorage之后每次请求都在请求头里带上Authorization: Bearer xxx后端拦截器解析 Token解析成功就放行失败就返回 401。生成 Token 的方式有很多种这个项目用的是基于 UUID 存数据库的简单方式就是把 token 字符串存到一张 token 表中登录时生成退出时删除。这种方式虽然没有 JWT 那么“优雅”但好处是服务端能主动控制 token 的失效比如管理员能强制踢人下线。如果你拿到的源码是 JWT 版本那逻辑大同小异只是 Token 本身是无状态的过期时间靠签名来校验。我特别提醒一点前端路由守卫不能少。很多新手写前端只关注登录页跳转却忘了在router.beforeEach里判断是否已登录。如果没写用户直接输入 URL 就能访问后台页面权限形同虚设。这个项目里路由守卫是有的拦截方式是判断 localStorage 里是否存在 token以及路由 meta 里的角色是否匹配。4.2 会员卡管理有效期计算与状态变更会员卡管理的难点在于状态判断。一张卡正常情况下是“正常”但可能因为过期、停用、次数用完而有不同状态。设计上我建议在会员卡实体里加一个“状态”字段取值范围1-正常2-过期3-停用4-次数用完。每次查卡列表时用 SQL 判断并更新状态或者在查询时动态计算。看源码里的实现它是写了一个定时任务每天凌晨扫描一次所有卡如果当前时间大于结束时间且状态还是正常就自动改成过期。我起初觉得这个设计还行但后来发现一个问题如果某张卡是“停用”状态时间也过期了定时任务把它改成“过期”那管理员再想续费时状态就变乱了。所以这里最好加一个逻辑只有状态为“正常”的卡才允许被自动改成“过期”停用的卡不参与自动变更。源码里有这个判断算是处理对了。有效期计算还有一个常见需求用户办卡时如果选择“开卡日期”那有效期的起算点有两种含义。一种是办卡当天就生效另一种是用户第一次去健身房激活才生效。这个项目默认是办卡当天生效代码里在插入会员卡时直接取当前日期作为开始时间再根据卡类型的天数算结束时间。如果你要改成激活生效就需要在卡表上加一个activate_date字段没激活前状态是“未激活”第一次使用或管理员手动操作时才算开始时间。这个小改动很多毕业设计都会用到可以试试。4.3 课程排期与预约防冲突排课表设计得有讲究。schedule表一般包含所属课程 id、教练 id、开始时间、结束时间、场地、限额人数、已约人数。这里我建议必须设计“场地”字段因为健身房里不同课可能共用同一个操房没有场地限制就会出现同一时间两节课抢一个房间的冲突。源码里对同一时间内同一场地是否有重复排课是有校验的。它的做法是在插入排课时查询是否存在“时间重叠且场地相同”的排课记录若有则拒绝插入。这个校验的 SQL 条件比较经典我贴出来给大家参考SELECT COUNT(*) FROM schedule WHERE room_id #{roomId} AND start_time #{endTime} AND end_time #{startTime}这段 SQL 的逻辑就是“新排课的开始时间必须在已有排课的结束时间之前新排课的结束时间必须在已有排课的开始时间之后”。只要查出数量大于 0就说明冲突。这是一个标准的区间重叠判断公式很多场景都可以复用。预约防冲突方面前面提到了已约人数用条件更新解决。但还有一个细节防止同一会员重复预约同一节课程。这个是用数据库唯一索引实现的联合唯一索引放在预约记录表的member_id和schedule_id字段上。如果没有这个索引光靠业务代码先查询再判断在高并发下一定会出现重复预约。现在有很多同学在做这类系统时忽略了唯一索引全靠if判断风险很高。建议检查一下项目的建表 SQL有没有类似UNIQUE KEY uk_member_schedule (member_id, schedule_id)的语句如果没有就手动加上非常有必要。5. 常见问题与排查技巧实录5.1 端口占用与数据库连接失败后端启动直接报Web server failed to start. Port 8080 was already in use是最常见的问题。最简单的解决办法是杀掉占用进程。Windows 上可以先netstat -ano | findstr 8080拿到 PID然后taskkill /PID xxxx /FMac 上可以用lsof -i :8080和kill -9 PID。如果是因为本机跑了很多服务不想杀也可以直接改后端端口但改了之后记得前端代理的 target 和 baseURL 也要同步改不然接口全部连不上。数据库连接失败报错一般是Access denied for user rootlocalhost或Communications link failure。前者是账号密码错排查方式很简单用 Navicat 或命令行本地连一下能连上就不是数据库问题那就要看是不是配置里的用户名密码多了一个空格。后者一般是 MySQL 没启动、端口不对、或者连接地址写错。我遇到过最无语的情况是数据库密码包含符号在application.yml里没加特殊处理导致解析错误。解决方式是整个连接串的密码部分用引号包起来或者用amp;转义特殊字符具体要看 YAML 的解析规则。5.2 前端跨域与请求404跨域是前后端分离开发的老大难。浏览器报Access-Control-Allow-Origin错误基本就是前后端域名或端口不一致导致的。解决办法有三种按推荐程度排列第一种后端加全局 CORS 配置允许所有来源访问。符合项目里使用的场景可以快速解决开发环境问题。第二种前端配置代理比如 devServer 里设置proxy: { /api: { target: http://localhost:8080, changeOrigin: true } }注意pathRewrite可能需要把/api前缀去掉具体看后端接口路径是否有/api前缀。第三种使用 Nginx 反向代理让前后端同源。这几种在项目里都有对应实现建议优先用代理方式因为不需要后端代码支持。接口 404 的问题排除后端没启动之外大多是路径匹配不上。比如前端请求/member/list但后端 Controller 只写了/api/member/list或者反过来。这需要核对baseURL、pathRewrite、RequestMapping三者之间的关系。我看过很多新手在这上面卡了两个小时最后发现只是/api前缀没对上。5.3 MyBatis 常见坑驼峰映射与动态SQL这个项目的 SQL 是写在 XML 文件里的很容易遇到两个问题。第一个是数据库字段用下划线风格比如create_timeJava 属性用驼峰风格createTime如果 MyBatis 没有开启驼峰映射查出来的结果就是 null。解决办法是在application.yml里写mybatis: configuration: map-underscore-to-camel-case: true很多项目没加这个配置新手查半天数据就是null其实是映射问题不是查询语句的问题。第二个问题是动态 SQL 的if标签判断空值。比如查询会员列表时按姓名模糊搜索很多人写if testname ! null and name ! 但前端传了个空格字符串导致条件没生效查出了全部数据。建议在 service 层先对参数做 trim或者 SQL 里用if testname ! null and name.trim() ! 。另外MyBatis 的foreach在遍历空集合时生成的 SQL 是IN ()直接报语法错误也要注意在调用前判断集合是否为空。5.4 部署到服务器时的注意点本地跑通以后部署到服务器又是另一回事。这里分享几个最常见的坑第一个项目里的上传文件路径。健身系统一般会有会员头像上传、课程图片上传功能。如果你在代码里写的是本地绝对路径比如D:/upload/部署到 Linux 服务器上就会报错。正确做法是改成相对路径或配置到外部文件中。我建议在application.yml里定义一个自定义属性比如file.upload-path/data/fitness/upload然后代码里读取这个配置。服务器上预先创建好这个目录并赋予写权限不要直接往用户目录下塞文件。第二个打包问题。后端打包用mvn clean package -DskipTests打出来的是 jar 包。前端打包用npm run build产物在dist目录。部署方式有两种一种是 jar 包和 dist 目录放在同一台服务器用 Nginx 托管前端静态文件同时把/api请求反向代理到localhost:8080另一种是把 dist 目录里的静态文件放进 jar 包的static目录下实现单端口部署。第二种方式适合个人小项目不用折腾 Nginx但如果有更多静态资源还是推荐用 Nginx 分开部署。第三个MySQL 连接超时和时区问题。服务器上的 MySQL 如果使用默认配置长时间没有数据库请求时连接会被服务端断开项目第二天一早访问时第一次请求经常报错。解决办法是在 JDBC 连接串里加上autoReconnecttrueinitialTimeout5connectTimeout20000之类的参数同时建议在连接池配置里设置一个小于 MySQL 回收时间的空闲检测时间比如 HikariCP 的connection-test-query配置。这一点是项目中比较隐蔽的坑生产环境容易踩。6. 延展优化方向如果这套项目你想当作自己的作品来展示或者继续开发这几个方向是性价比比较高的第一增加微信小程序端。后端接口如果设计得足够规范小程序端只需要复用现有的接口再写一个前端小程序这就能从一个后台管理系统变成一个真正有两端的产品含金量明显提升。第二引入 Redis 做缓存。目前课程列表、会员信息都是直接查 MySQL在数据量大了以后会有压力。可以先把课程分类和热门课程列表缓存到 Redis预约并发时也可以用 Redis 做原子操作避免数据库行锁带来的性能损耗。第三增加数据统计功能。健身俱乐部运营者很需要统计报表比如每月的办卡数量、课程预约率、会员活跃度、私教课消课率。可以做一个简单的统计接口用聚合查询把数据算出来前端用图表组件展示。这部分做出来在面试的时候非常加分因为它展示了你对业务的理解而不只是会 CRUD。第四权限控制升级。当前简单的拦截器如果要支持多角色、细粒度权限建议引入 Spring Security 或者 Sa-Token同时将权限数据表设计成用户-角色-菜单-权限的关系模型。这个改造过程可以复习很多东西也弥补了项目在高安全性场景下的缺陷。说实话我一直在强调这个项目的核心价值在于“完整”和“可跑通”。很多初学者拿到一个半成品项目改了半天跑不起来信心直接被打没了。而这个系统的代码结构、注释和部署文档都比较友好只要你耐心从头理一遍把每一层的作用搞明白收获会远大于单纯刷几个月的教程。最后再分享一个小技巧不管你是拿它做毕业设计还是练习一定要自己动手把数据库表重新设计一遍再用代码反推业务逻辑这个过程比任何视频课程都值得。