在健身行业从线下办卡转型线上运营的这几年一套能管理会员、课程、教练与预约流程的网站系统几乎是俱乐部的刚需。我做这个基于 Java SpringBoot Vue3 MyBatis MySQL 的前后端分离健身俱乐部网站系统初衷很直接用一套足够轻量、不堆砌多余框架的完整源码跑通“会员注册登录→浏览课程→在线预约→后台管理”这条核心业务链。项目本身不追求大而全而是把高频、实用的功能做成完整闭环既适合作为计算机专业的毕设课题也适合想系统性掌握前后端分离开发套路的新手拿来逐行学习。全文不会只讲功能列表会把表结构为什么这么设计、接口为什么这么拆、联调时那些最容易卡壳的姿势一并说清楚。1. 项目概述与整体设计思路1.1 业务场景与核心需求健身俱乐部的日常运营痛点很典型会员信息散落在纸质表格或Excel里课程排期靠前台口头通知预约情况全靠到店询问教练的课时统计月底要对半天账。这套系统要解决的就是把这三件事数字化一是会员端能在线查看课程并预约教练端能查看自己的排课和预约名单管理员端能统一维护会员、课程、教练和公告信息。从使用角色上看系统天然分三种身份普通用户会员、教练、管理员。会员和教练都是注册用户只是角色权限不同。核心业务流我梳理成一条主线管理员维护教练和课程数据普通用户注册登录后浏览课程列表选择合适的课程预约教练登录后能看到该课程的预约学员名单管理员在后台还能处理用户下架、课程停用等管理动作。这个业务模型本身不复杂但麻雀虽小五脏俱全。它覆盖了完整系统必备的模块认证授权、增删改查、一对多和关联查询、文件上传教练头像等恰好把Java开发日常用到的主力技能点都沾了一遍。这也是我选择做这个课题而不是做纯工具类项目的原因——它的功能边界清晰能讲清楚做完之后能形成一种“我掌握了一条完整业务线如何落地”的信心。1.2 为什么选择前后端分离架构前后端分离现在几乎是企业级Web开发的主流形态这个项目选它不是跟风而是因为它贴合这套系统的真实协作场景。前端Vue3跑在开发服务器默认5173端口后端SpringBoot跑在8080端口两者通过JSON格式的HTTP接口通信。前端只关心页面渲染和用户交互后端只关心业务逻辑和数据持久化互不侵入。对于学习来说这种架构有个明显的好处查问题的时候范围缩小了。页面没数据先看Network面板里请求到底发出没有请求发了但报500把锅锁定在后端Controller和Service请求没发那八成是前端axios封装或路由拦截出了问题。这套排查思路能帮你以后快速融入真正的团队协作开发节奏因为大厂和正规公司的项目基本都长这样。当然前后端分离也带来了必须处理的额外成本跨域问题、Token认证、接口文档约定。这些在单体服务里几乎不存在但在分离架构里绕不开。我的做法是把这些问题当成项目的一部分系统性解决而不是临时打补丁。跨域用统一的CORS配置类处理认证用JWT 拦截器统一收口接口约定统一返回Result对象。这样处理完前后端协作的体验其实比单体开发更清爽。1.3 技术选型背后的逻辑对比每次做项目技术选型是最容易被忽略但最影响开发体验的环节。这套系统的选型逻辑值得展开说说。SpringBoot选型上建议直接用SpringBoot 2.7.x而不是最新3.x。理由非常务实3.x基于Jakarta EE规范很多网上现成的教程、依赖写法还是基于javax命名空间新手照着做容易踩版本不兼容的坑。2.7.x是2.x系列的最终版本稳定、资料多、第三方整合信息齐全。如果你非要用3.x后面遇到Druid连接池或老版分页插件的兼容问题就要做好自己Debug的准备。ORM框架用MyBatis而不是Spring Data JPA核心考虑是“可控性”。健身俱乐部这类业务查询场景经常需要多表关联课程列表要带出教练姓名预约记录要带出课程名称和会员信息。MyBatis的SQL由自己写每一条查询都写得明明白白出问题能直接定位到SQL语句本身。JPA的自动SQL虽然省事但对新手来说一旦发生N1查询或懒加载问题排查成本反而更高。MySQL作为存储层没有悬念考虑到这个项目数据量级撑死几万条记录合理设计索引后性能完全不是瓶颈。前端选Vue3而不是Vue2是因为组合式APIComposition API在逻辑复用上的优势在这几年已经充分验证。尤其在封装登录状态、请求逻辑这类跨页面共享功能时用组合式函数的方式组织代码明显比Vue2的mixin清晰一个量级。2. 项目架构蓝图表结构、接口与原理解析2.1 数据库表设计与关系梳理数据库设计是整套系统的地基设计得好不好直接决定后期写SQL是否痛苦。为了兼顾演示效果我没有做得特别复杂一共规划5张核心表用户表、教练表、课程表、预约表、公告表。这里的用户表是统一的登录账号表通过role字段区分是普通会员还是管理员教练表单独拆出来是因为教练除了有账号信息还有专业领域、简介、头像等专属资料。核心关系的梳理是理解这套表结构的关键用户表user与教练表coach一对一关系。教练既是用户要登录系统看预约又是业务实体要被课程引用。用coach表的user_id字段关联用户表主键。课程表course与教练表coach多对一关系。一门课程属于一个教练在course表中用coach_id字段关联。预约表booking与课程表course、用户表user多对一关系。一条预约记录指向一个课程和一个用户同时记录预约时间、状态。设计上有几个细节值得注意。第一状态字段都用tinyint类型而不是字符串Y/N因为数字在数据库比较运算上更快而且语义明确0代表正常或未处理1代表停用或已确认2代表已完成。第二预约表加了book_date和book_time两个字段是因为健身课程有明确的日期场次只存一个创建时间没法解决“预约哪一天哪一节”这个核心问题。第三所有表都统一带create_time字段方便后期做运营分析——比如你知道周几的预约量最高就能针对性安排热门课程。建表语句我贴一个核心版本方便直接做参考。需要完整脚本的话项目中已包含db文件夹的.sql文件CREATE TABLE user ( id int(11) NOT NULL AUTO_INCREMENT, username varchar(50) NOT NULL COMMENT 用户名, password varchar(100) NOT NULL COMMENT BCrypt加密后的密码, real_name varchar(50) DEFAULT NULL COMMENT 真实姓名, phone varchar(11) DEFAULT NULL COMMENT 手机号, role tinyint(1) NOT NULL DEFAULT 1 COMMENT 1-会员 2-管理员, create_time datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_username (username) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_general_ci;2.2 核心接口划分与状态码约定接口设计遵循RESTful风格但不过度教条。资源用名词复数动作靠HTTP方法区分这一点前后端能形成共识。我把接口按模块分成几组认证模块、课程模块、预约模块、用户模块、教练模块和公告模块。具体到接口清单核心接口概览如下功能描述请求方式接口路径备注用户注册POST/api/user/register开放接口用户名去重用户登录POST/api/user/login返回JWT Token获取当前用户信息GET/api/user/info需要Token课程列表分页GET/api/course/list支持按名称模糊查询课程详情GET/api/course/{id}关联教练信息返回创建预约POST/api/booking/add需要登录校验是否重复预约我的预约列表GET/api/booking/my按当前用户查询带课程和教练信息教练端查看预约名单GET/api/booking/coach按登录教练关联的课程查课程新增POST/api/course/save仅管理员课程下架PUT/api/course/status/{id}仅管理员逻辑删除这些接口的设计有两个隐性约定需要强调。第一所有返回结果统一包裹在Result对象里结构是{code, message, data}。code为200是成功401是未认证500是业务异常。这样前端axios响应拦截器只需要判断code不需要对每个接口单独解析。第二管理员操作的接口路径与普通接口混在一起通过权限拦截器校验而不是在建表时就区分管理员模块。因为业务量不大没必要单独拆一套管理端后端服务但通过注解方式标记权限接口归属和权限语义依然清晰。2.3 JWT登录方案与权限控制的实现思路登录认证这块我采用的是JWT SpringBoot拦截器方案。JWTJSON Web Token本质上是一个携带用户身份信息的加密字符串服务端签发后发给前端前端每次请求带在请求头里服务端验签通过就信任身份信息。它比Session方案更适合前后端分离因为Token是无状态的后端不需要维护Session存储水平扩展时也无需考虑Session共享问题。密码存储这块必须单独拿出来强调绝不能明文存密码。项目里使用Spring Security Crypto库中的BCryptPasswordEncoder做加密这是一种加盐的哈希算法相同密码每次加密结果都不同即使数据库泄露暴力破解的成本也极高。注册时将明文密码编码后入库登录时将明文密码与库中哈希值做校验全程数据库不落地明文。JWT工具类里我只放三个核心字段userId用户ID、username用户名、role角色过期时间设置为24小时。生成逻辑用HMAC-SHA256算法签名密钥是自定义字符串。每个请求到了后端先过拦截器拦截器中解析请求头里的Authorization字段格式统一为Bearer 加Token用JWT工具类验签通过后从Token中提取用户信息存入ThreadLocal方便后续业务代码直接拿当前用户。权限控制上自定义了一个RequireRole注解标记在管理端接口上。拦截器在验签通过后检查注解要求的路由权限是否匹配。如果当前用户角色不是管理员直接返回401的JSON结构。这个方案比起引入Spring Security全家桶代码量少、逻辑直白非常适合中小型项目和教学场景。想要更细粒度的话后续可以引入自定义注解加AOP做操作日志和权限校验扩展路径也留好了。3. 实操过程从后端到前端的关键实现3.1 后端核心逻辑与MyBatis使用技巧后端实现的骨架比较标准Controller接收请求、Service处理业务、Mapper操作数据库。在实际开发中有几个细节对项目成败非常关键必须单独拆开说。第一个是Mapper接口与XML文件的对应。MyBatis的Mapper接口不能直接和XML分开看它俩是一个整体。接口里的方法名必须与XML中标签的id完全一致我习惯直接跟方法名一致命名空间必须是Mapper接口的全限定名。如果出现绑定异常Invalid bound statement九成是这两处没对上。在这个项目里所有复杂SQL都写在XML中用注解写SQL只保留最简单的按ID查询这是个经验和取舍——XML方便统一管理动态SQL超过两行拼接逻辑的SQL写注解里会非常难读。第二个是结果映射的配置。项目中专门设置了map-underscore-to-camel-casetrue让数据库下划线字段自动映射到Java驼峰属性比如user表里的real_name自动映射到realName字段。但这有个例外要注意多表关联查询返回的复合结果比如CourseVO里同时包含课程属性和教练姓名就不能依赖自动映射了必须用resultMap显式声明每个字段的映射关系否则查询结果会出现对应字段全部为null的诡异问题。第三个是关于预约接口的并发场景考虑。最简单的实现是先查预约表是否已有记录没有则插入但高并发下可能两个请求同时通过查询插入两条重复记录。因为预约表的联合唯一索引约束在数据库层面会直接报错不会产生重复脏数据。项目里用了INSERT IGNORE配合唯一索引user_id course_id book_date这样重复预约的请求会返回影响行数为0业务层就可以友好提示“您已预约过该课程”这是在性能和正确性之间一个相当舒服的平衡点。下面这段是课程分页查询的Mapper XML这个场景很典型条件查询加关联查询改造为分页逻辑都在XML里定义好select idselectCoursePage resultMapCourseVOMap SELECT c.id, c.course_name, c.course_time, c.max_count, c.current_count, c.status, c.coach_id, c.image_url, c.description, t.teacher_name AS coach_name FROM course c LEFT JOIN coach t ON c.coach_id t.id where if testcourseName ! null and courseName ! AND c.course_name LIKE CONCAT(%, #{courseName}, %) /if /where ORDER BY c.create_time DESC /select这里用LEFT JOIN关联教练表用where加if组装动态查询条件。特别注意LIKE查询必须用CONCAT函数拼%不要直接写LIKE %#{courseName}%后者会直接报语法错误——这是MyBatis新手最常踩的坑之一。3.2 前端Vue3组合式API封装与组件设计前端这端我用Vue3加Vite构建UI组件库选择Element Plus配合Pinia做状态管理。相比Vue2时期一上来就把所有代码塞进单文件组件里Vue3的组合式API更强调“按逻辑组织代码”。我这个项目的做法是把所有请求封装抽到一个统一的request.js模块用axios实例统一配置baseURL和超时时间再通过请求拦截器自动在请求头里附加Token。状态管理方面我专门写了useUserStore这个Pinia模块存Token和用户基本信息。登录成功后直接调用store的setLoginInfo方法把Token和用户信息存起来同时持久化到localStorage刷新页面后通过Pinia插件自动恢复登录态。退出登录时清除store和localStorage再跳转到登录页。这套设计比在每个页面里手动处理localStorage要整洁得多。路由守卫也是一个核心细节。项目里配置了全局前置守卫逻辑很清晰判断目标路由是否在免登录白名单中登录页、注册页如果不在检查Store里有没有TokenToken存在但是第一次进入系统先调/api/user/info接口拉取用户信息并回填Store再做路由跳转。因为前端刷新后用户信息会丢而路由守卫拦截时又需要它来判断角色权限这个“先拉信息再跳转”的设计必须从一开始就想清楚不然刷新页面后总有跳转异常。页面组件方面我按业务拆成以下几个核心视图首页课程展示公告栏、课程列表页、课程详情页预约入口、我的预约页、登录注册页、管理后台课程管理、用户管理、教练管理、预约总览。组件复用的点在于课程列表和后台管理都使用同一套课程卡片组件只是父组件传来的数据源不同。用props加emit的模式实现父子通信既有单文件组件高内聚的优点又不至于退化成全局组件式的混乱。3.3 前后端联调跨域、请求拦截与响应处理前后端联调往往是新手第一次崩溃的地方因为一打开页面控制台就飘红。跨域报错是前后端分离架构绕不开的一个坎。浏览器的同源策略规定当前页面地址的协议、域名、端口只要有一个与请求地址不同浏览器就会拦截响应。开发环境下前端跑在http://localhost:5173后端在http://localhost:8080端口不同天然跨域。解决办法我建议分两层处理。第一层后端写一个CORS配置类允许前端地址的跨域访问第二层前端开发环境的Vite配置文件里配proxy代理把所有/api前缀的请求转发到8080端口。实际开发中两层配合更稳妥前者解决直连场景下的跨域后者是为了让前端代码里的请求地址保持简洁不用写完整的后端网址。等部署上线后Nginx反向代理同样能完成代理转发这就是后话了。axios响应拦截器上我会在response拦截器中统一处理后端返回的Result结构code为200直接返回data字段业务代码拿到的就是干净的数据code为401时弹出“请先登录”提示并跳转登录页同时清理掉本地失效的Token其他code则统一用ElMessage弹出后端返回的message信息。这样每个页面里只需要关心自己的业务数据错误处理全局只写一遍——这是让前端代码量大减的关键设计。4. 部署、配置与运行经验4.1 本地环境搭建与项目启动第一次把项目跑起来看着简单其实组合起来有几个隐藏难点。后端要确保本机装了JDK 1.8或以上、Maven 3.6、MySQL 5.7。克隆代码后用IDEA打开右键pom.xml选Maven的Reload Project等待依赖下载。这里有个网络问题要注意Maven中央仓库在国内直接访问有时会超时建议配置阿里云镜像库速度会有质的改善。MySQL这边先创建一个名为fitness_club的数据库然后执行项目里db目录下的init.sql脚本。执行完之后检查一下application.yml里的数据库连接配置把密码改成自己本机实际的MySQL密码。后端启动很简单直接运行FitnessClubApplication.java的main方法。看到控制台打印“Started”就说明启动成功。前端步骤也比较固定进入vue目录执行npm install安装依赖。这里如果node_modules下载慢同样可以配置npm淘宝镜像源。依赖装完执行npm run devVite会启动开发服务器看到“Local: http://localhost:5173/”说明前端起来了。用浏览器打开5173端口注册一个普通用户账号就可以正常使用基本功能。管理员账号我在init.sql中内置了一个用户名admin密码admin123角色是管理员方便直接进后台看管理功能。4.2 配置文件中容易被忽略的三个细节配置文件看似不起眼实际是项目是否能正常运行的命门。项目里有几个细节我几乎每次分享都被问到底。第一个是MySQL连接串时区配置。因为新版MySQL驱动对时区要求严格不指定时区经常报The server time zone value ... is unrecognized。连接串上加上serverTimezoneAsia/Shanghai能解决这也是我在配置里写死的参数。第二个是字段命名策略配置。MyBatis-Plus或MyBatis的驼峰映射在yml里要显式打开设置map-underscore-to-camel-case: true否则user表里real_name字段是查不出realName值的。第三个是Jackson时间格式化。后端返回的日期类型如果默认序列化方式不统一前端拿到的时间格式会是时间戳或者带T的ISO格式不好看。在配置里设置spring.jackson.date-format: yyyy-MM-dd HH:mm:ss以及time-zone: GMT8前后端时间显示就统一了。这三个配置不看文档真的记不住但每次项目都得配一遍。4.3 打包部署与上线方案本地开发验证通过后部署上线是另一个维度的话题。后端打包很简单在项目根目录执行mvn clean package -DskipTeststarget目录下会生成一个jar包。Jar包上传到服务器后用java -jar fitness-club.jar --spring.profiles.activeprod命令启动配好生产环境用的数据库连接就行。前端打包是npm run build生成一个dist目录。生产环境的静态文件托管用Nginx比较成熟。Nginx配置里做两件事一是将根路径指向dist目录负责托管前端静态资源二是把/api/路径的请求反向代理到后端对应的服务地址同时加上try_files配置解决前端路由history模式的刷新404问题。这里还有一个小细节生产环境下前端的请求地址不能再写localhost需要根据实际部署的域名或IP来配置。我的方案是在前端代码里通过环境变量区分开发环境读.env.development文件生产环境读.env.production文件打包时自动切换不需要手动改代码里的写死地址。这一招对于频繁切换测试、生产环境的团队非常实用。5. 常见问题与排查技巧实录5.1 数据库连接与初始化相关**问题一数据库连不上报Communications link failure。**排查顺序别乱第一步ping数据库服务器IP第二步用命令行工具navicat或mysql命令尝试用同样的账号密码远程连接第三步检查MySQL的bind-address配置确认没有只允许本地连接。八成问题出在授权上远程登录的账号需要执行GRANT ALL ON 数据库名.* TO 用户名%才能生效。**问题二执行init.sql报错提示表已存在。**这通常是重复执行造成的。脚本里可以在每个建表语句前加上DROP TABLE IF EXISTS或者干净点把整个数据库drop掉重建。开发环境无所谓生产环境千万不能这样操作生产库表结构变更要用版本化迁移工具管理。5.2 MyBatis与SQL相关**问题三Invalid bound statement (not found)。**这是出现频率最高的MyBatis报错之一。检查三处Mapper接口和XML文件是否在同一包路径下、XML的namespace是否精确到接口全限定名、接口方法名是否与XML标签id一致。这三处只要有一处不一致就会报这个错。另外如果用了Maven构建注意pom.xml里是否把mapper目录下的XML文件排除在了打包范围之外这是非常经典的坑。**问题四联表查询返回的关联字段全为null。**用resultMap显式解决不要指望自动映射能处理多表关联结果。到了这一步先查SQL在数据库客户端里运行结果是否正常如果SQL没问题再检查resultMap的字段对应是否正确。这个排查顺序能避开90%的无效定位时间。**问题五使用MySQL时报错This function has none of DETERMINISTIC。**这个多数出现在创建函数或存储过程时。MySQL的binlog模式下创建函数需要声明其确定性。开发环境下直接执行SET GLOBAL log_bin_trust_function_creators 1;能快速解决但生产环境建议单独评估。5.3 前后端联调与部署相关**问题六前端请求能到后端但控制台报CORS错误。**先确认后端CORS配置类是否生效再确认浏览器请求的Origin头是不是后端允许的来源。如果用了Vite代理就检查代理是否只应用于/api前缀——路径不匹配时请求会从浏览器直接发向后端跨域就会冒出来。最后检查是否重复配置了跨域头有的同学在拦截器里又加了一遍CORS头反而把原先的合法配置覆盖了。**问题七history模式部署后刷新页面出现404。**这个根本原因在于前端路由用的是HTML5 History模式刷新某个子路由时Nginx找不到对应的物理文件路径。Nginx配置里加上location / { try_files $uri $uri/ /index.html; }把所有不存在的路径统一回退到index.html由前端路由自己接管问题就解决了。**问题八打包部署后页面能打开但所有接口请求都404。**优先检查Nginx反向代理的location匹配规则。如果配置了location /api/ { proxy_pass http://127.0.0.1:8080; }注意proxy_pass末尾是否带斜杠带斜杠表示去掉/api前缀再转发不带斜杠则保留原路径。这俩行为差异极大配错的表现百变最容易造成“前端没问题后端没问题但就是不通”的诡异状态。6. 写在最后的个人经验做这套系统前后耗时三周回头看最有价值的不是代码本身而是把“完整项目负责人”的思维方式理清楚了一遍。一开始我也想着把功能堆得越全越好后来才意识到一个能跑通核心闭环的项目价值远大于一堆半成品的花哨功能。比如预约模块我只做了“预约取消查看”但这三个功能从表设计、接口封装、前端状态管理到权限控制全链路打通了任何一个环节换成其他技术栈迁移成本都很低。一个比较意外的收获是多表关联的SQL调试过程中反复能用到那些概念JOIN类型、索引失效、explain执行计划分析。这些在面试题里背得滚瓜烂熟的知识真正上手遇到问题了才变成自己的。做这个项目之前我的SQL卡在单表CRUD水平做完它我知道联表查询该用LEFT JOIN还是INNER JOIN知道在哪些字段上索引能真正提高查询效率知道批量插入时用INSERT IGNORE怎么优雅处理冲突。最后分享一个小技巧在写预约接口之前先花半小时把“一个用户对同一课程重复预约”的场景在纸上推演一遍怎么处理然后去数据库里加联合唯一索引。这半小时省掉的不是代码量而是上线之后反复接到“为什么能重复预约”的麻烦。做系统这件事很多坑其实都可以提前用逻辑推演避开关键是你愿不愿意在动手写第一行代码之前多想三分钟“这个数据从哪来到哪去边界情况是什么样的”。如果你也想基于这套源码做二次开发建议从预约模块的取消功能着手把状态流转补完整再往后可以引入Redis做热门课程缓存、用WebSocket做排课变更通知。项目本身的边界很清晰往下怎么长取决于你需要的业务深度。这也是我喜欢这个项目的原因——它不是终点而是很多可能性的起点。