健身房管理系统开发实战：Python与Django、Flask、Vue全栈实现

上个月我一个做健身房运营的朋友来找我帮忙说要搞一套会员管理系统。他们店现在还是前台拿Excel记会员、用微信群发课程表教练排课全凭记忆月底做业绩报表得手动对账会员续卡、课程约满这种事全靠肉眼盯。我听完直接给了个技术方案前端用Vue后端用Python再按业务复杂度拆成Django和Flask两个服务开发工具统一用PyCharm。这套方案从需求梳理到上线跑通前后花了半个多月效果还不错前台和教练都顺利上手了。今天把整个从需求拆解、技术选型、代码落地到部署排错的完整过程整理出来。不管你是想给自己的健身房做系统还是准备拿这个方向写毕业设计、练手项目这篇都可以当一份比较实在的参考。1. 健身房管理系统到底要管什么需求拆解与模块边界很多初学者做系统第一反应是打开IDE直接建表写页面结果做到一半发现需求混乱、字段反复改越写越没底。我做这类项目的习惯是先把业务现场“逛”一遍把所有角色、流程、痛点列清楚再决定哪些做、哪些不做。1.1 角色与权限一个系统里有四种完全不同的使用者健身房管理系统最容易踩的坑是所有人共用一套界面。实际上一个中型健身房至少有四类角色需求差异非常大老板/管理者关心营业额、续卡率、到店率、教练业绩排行需要的是统计报表和经营看板。前台接待负责会员登记、办卡、续费、课程预约登记需要的是快速录入和会员信息查询。私教/团课教练关心自己的排课表、预约名单、课时费结算需要的是课程与会员对接。会员想看到课程安排能在线预约课程、查看自己的卡到期时间最好是手机就能操作。如果一套界面要同时满足这四种人页面就会非常臃肿。我在设计时直接按角色拆功能不同角色登录后看到的菜单完全不同。这块对应到Django里就是基于组和权限的RBAC控制后面会详细说。1.2 核心业务模块从“卖卡”到“约课”是一条完整链路健身房的主业务逻辑其实是一条链会员建档 → 办卡/续卡 → 预约课程 → 现场签到 → 统计数据。沿着这条链去拆模块就不会漏功能。我的系统划分了五个核心模块会员管理姓名、电话、性别、身高体重体脂等基础档案以及会员卡信息。会员卡管理卡类型月卡、季卡、年卡、次卡、开卡时间、到期时间、剩余次数。课程管理团课的课程名称、教练、上课时间、时长、最大人数、已约人数。预约管理会员预约课程、取消预约预约状态流转。数据统计今日到店人数、预约数、销售额、课程热度排行、教练业绩。另外还有两个容易忽略但是实际上经常用到的点会员卡到期提醒以及重复预约同一课程的拦截。这两个功能在业务上很小但如果没有前台会天天手动补课记录系统体验直接减半。1.3 MVP阶段要敢于砍需求我给朋友做的第一版并不是功能全开的。比如在线支付、小程序端、会员自助查询机这些都不是第一版该做的。MVP范围就锁定在后台管理端Web完成会员卡管理、课程排期、预约操作、统计报表会员端可以先只做“查看课程和预约”这两个动作。砍需求的原因是你不可能在两周内把一套商业SaaS做出来但你可以用两周做出一套能真正运转的内部管理系统。先把主链路跑通后续再逐步加支付、加小程序、加会员自助端这样的节奏对个人开发者和毕业设计都更现实。2. 技术选型与架构分工Django和Flask各干各的活技术选型是很多人纠结的第一步。网上Python后端框架的对比文章一大堆但落到健身房管理系统这个具体场景思路其实很清晰核心业务用重型框架统计服务用轻量框架。2.1 为什么核心后端用Django而不是只用FlaskDjango最大的优势是“全家桶”它自带ORM、Admin后台、认证系统、迁移工具和强大的查询API。对健身房管理系统这种典型的CRUD业务Django可以非常快地把表结构建立起来然后直接用Admin后台先给前台用起来再慢慢写前端界面。特别是会员卡、预约这类强关联的数据Django的ORM在做跨表查询时太方便了比如“查所有预约了本周课程且年卡未过期的会员”只要一条链式filter就行。这种需求在Flask里如果不用SQLAlchemy就要手写一堆SQL开发速度差很多。另外Django自带的Admin后台不要看不起它在项目初期是神器。我们第一版甚至没写管理界面直接让内部员工用Django Admin录入会员和课程前端界面只做给会员和教练看的预约/查询页面。这种“两步走”的节奏比一上来就全栈梭哈稳妥很多。2.2 Flask在这个项目里的真实定位前台数据大屏可能有人会问既然Django这么强为什么还要用Flask我听搜这个项目的人里也有不少在纠结Django还是Flask我的回答是你可以两个都用关键是分清边界。健身房老板提了个需求要在前台放一块大屏幕实时显示今日到店人数、课程热度、销售额等数据。这个服务和主业务系统本质上可以完全独立它只负责读数据库、做统计、出JSON接口给大屏前端。如果把这个统计服务也塞进Django里等于在主项目里堆一堆独立的定时任务和统计View后期开发主业务时容易互相干扰。所以我把统计服务拆成一个独立的Flask应用单独放在一个report_server目录下只连接数据库做统计查询对外提供几个JSON接口。Flask轻量、启动快、依赖少做这种“小而专”的服务非常合适。整个项目架构是这样的Django主服务gym_backend处理会员、办卡、课程、预约等核心业务对外提供REST API。Flask报表服务report_server独立进程读取同一MySQL库提供统计接口给大屏前端。Vue前端gym_frontend一个SPA应用内部员工端和大屏共用根据路由区分页面。2.3 Vue负责什么组件化解决的是页面快速迭代问题前端选择Vue核心原因是组件化。健身房管理系统里“会员列表”“课程卡片”“预约日历”这些场景天然适合拆成组件。比如课程列表是一张卡片上面显示课程名、教练、时间、剩余名额这个卡片在员工端、教练端、大屏端都要用做成一个组件处处引用改样式只改一处。Vue配合Element Plus组件库表单、表格、弹窗、日期选择全部现成一周就能把主界面搭出来。相比用Django模板渲染页面Vue更适合这种需要频繁联动局部刷新的交互场景而且后期加移动端适配也方便。3. 开发环境从零搭建Python、PyCharm、Node与Vue的搭配搜索这个项目的人里很大一部分卡在开发环境这一关。Python装了、PyCharm配了、Vue环境也建了但三者就是串不起来。我在第一次跑通这套项目时也踩了不少坑把流程整理成下面几步每一步都有清晰目的。3.1 Python版本与虚拟环境别在全局环境里装依赖我推荐用Python 3.10或3.11这两个版本稳定且主流的第三方库都已经适配。不要图新用3.13有些库的编译轮子还没跟上装起来很痛苦。装好Python之后一定要给项目单独建虚拟环境。很多新手图省事直接在全局环境里pip install django结果多个项目依赖互相打架。项目根目录下执行python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate激活后注意终端前面会出现(venv)标志这就是当前处于虚拟环境。然后再装依赖pip install django djangorestframework django-cors-headers pip install flask flask-cors pip install pymysql我把Django和Flask的依赖装在同一套虚拟环境里因为它们都连同一个数据库开发阶段放在一起管理反而方便。部署时才需要把两个服务进程分开跑。3.2 PyCharm的配置把项目根目录和解释器选对PyCharm这边需要做的有两件事一是设置好虚拟环境解释器二是把项目根目录识别清楚。打开PyCharm在Settings里找到Project: 项目名 → Python Interpreter选择刚才创建的那个venv下面的python。如果你用的是社区版也可以通过命令行创建venv后PyCharm会自动检测到。关于PyCharm专业版和社区版我的建议是开发这种项目社区版完全够用不用纠结。专业版的数据库工具、远程部署等功能确实香但如果手头没有正版授权去研究各种破解方案反而浪费时间和精力。JetBrains家族产品都提供官方试用和教育免费授权走正规渠道最稳。社区版配一个基础的Python工具包写Django和Flask项目一点问题都没有。配置好解释器后再确认项目目录结构gym_project/ ├── venv/ # 虚拟环境 ├── gym_backend/ # Django主服务 ├── report_server/ # Flask报表服务 ├── gym_frontend/ # Vue前端 └── README.md3.3 Node、npm与Vue项目创建版本不匹配是头号麻烦Vue侧需要Node环境建议安装Node 18以上的LTS版本。装完后在项目目录下创建Vue前端npm create vitelatest gym_frontend -- --template vue cd gym_frontend npm install npm install axios vue-router element-plus echarts这里有一个坑旧项目模板里用的是Vue CLI基于webpack新脚手架默认是Vite两者配置方式完全不同。网上大量教程还在教vue create命令你如果用vite项目去跑vue create的配置就会对不上。我们这次用的是Vite配置文件是根目录下的vite.config.js这个要记清楚。Vite启动速度快热更新也快开发体验比webpack时代舒服太多。启动Vue开发服务器后在浏览器里能看到Vite默认页面就算基础环境通了。接下来进入正题从后端开始写业务。4. 用Django落地核心业务会员、课程与预约接口进入Django主服务的时候我先花十分钟把项目建好包括app的划分。很多人喜欢把会员、课程、预约全塞在一个app里我一开始也这么干过后来发现模型一多models.py几百行根本没法维护。所以按业务边界拆app是最值钱的习惯。4.1 项目初始化与数据模型设计先创建Django项目和一个统一管理入口django-admin startproject gym_backend cd gym_backend python manage.py startapp members python manage.py startapp courses python manage.py startapp appointments然后在settings.py里把新app和DRF注册进去INSTALLED_APPS [ # django自带app django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, # 第三方 rest_framework, corsheaders, # 业务app members, courses, appointments, ]数据模型是核心中的核心。会员和会员卡是典型的一对多关系会员卡的状态直接影响预约逻辑。示例模型如下# members/models.py from django.db import models class Member(models.Model): GENDER_CHOICES [(male, 男), (female, 女)] name models.CharField(max_length50, verbose_name姓名) phone models.CharField(max_length20, uniqueTrue, verbose_name手机号) gender models.CharField(max_length10, choicesGENDER_CHOICES, defaultmale) create_time models.DateTimeField(auto_now_addTrue, verbose_name建档时间) def __str__(self): return f{self.name}({self.phone}) class MembershipCard(models.Model): CARD_TYPE [ (month, 月卡), (quarter, 季卡), (year, 年卡), (count, 次卡), ] member models.ForeignKey(Member, on_deletemodels.CASCADE, related_namecards) card_type models.CharField(max_length10, choicesCARD_TYPE) start_time models.DateTimeField() expire_time models.DateTimeField() remaining_count models.IntegerField(default0, verbose_name剩余次数)模型建好后执行python manage.py makemigrations python manage.py migrate python manage.py createsuperuser然后在admin.py里注册模型这样不用写前端就能先用Admin后台管理数据。这里有个小技巧related_name一定要起好名字比如member的cards这样会员查自己的所有卡时直接member.cards.all()查询语义特别清晰。4.2 DRF下的查询与删除操作核心业务要暴露成API我用的是DRF的ModelViewSet它能自动生成增删改查接口省掉大量重复代码# members/serializers.py from rest_framework import serializers from .models import Member, MembershipCard class MemberSerializer(serializers.ModelSerializer): class Meta: model Member fields [id, name, phone, gender, create_time] # members/views.py from rest_framework.viewsets import ModelViewSet from .models import Member from .serializers import MemberSerializer class MemberViewSet(ModelViewSet): queryset Member.objects.all() serializer_class MemberSerializer路由在项目级urls.py注册from rest_framework.routers import DefaultRouter from members.views import MemberViewSet router DefaultRouter() router.register(rapi/members, MemberViewSet) urlpatterns router.urls到这一步会员的增删改查API就已经能用了。但实际业务光靠默认接口不够还要写业务查询。比如“找出所有有效卡还没过期的会员”from django.utils import timezone now timezone.now() active_member_ids MembershipCard.objects.filter( expire_time__gtnow, remaining_count__gt0 ).values_list(member_id, flatTrue).distinct() members Member.objects.filter(id__inactive_member_ids)删除操作也要注意。默认的物理删除是dangerous的会员删掉了他的历史预约记录也就没了。实际项目里我加了软删除字段class Member(models.Model): # ...原有字段 is_deleted models.BooleanField(defaultFalse)所有查询默认过滤is_deletedFalse删除操作变成标记删除。这样统计报表里历史数据不会丢这是商业系统里非常重要的一个细节网上很多教程都不会提。4.3 预约防重复与权限控制预约模块有三个关键逻辑会员卡有效性校验、课程名额校验、防止重复预约。前两个用条件判断就能做第三个靠数据库约束从根本上保证# appointments/models.py class Appointment(models.Model): STATUS [(booked, 已预约), (cancel, 已取消), (done, 已完成)] member models.ForeignKey(Member, on_deletemodels.CASCADE, related_nameappointments) course models.ForeignKey(Course, on_deletemodels.CASCADE, related_nameappointments) status models.CharField(max_length10, choicesSTATUS, defaultbooked) create_time models.DateTimeField(auto_now_addTrue) class Meta: constraints [ models.UniqueConstraint( fields[course, member], conditionmodels.Q(statusbooked), nameunique_booked_appointment ) ]这个唯一约束能保证同一会员不能重复预约同一课程即使并发请求同时打过来数据库层也会拦截一条。这种“数据层兜底业务层提示”的做法是后端开发的稳妥思路。权限控制对应的是RBAC。我在Django里建了三个组admin_group、staff_group、coach_group然后在每个ViewSet里用rest_framework的IsAuthenticated权限类配合自定义权限类from rest_framework.permissions import IsAuthenticated class IsAdminOrStaff(IsAuthenticated): def has_permission(self, request, view): if not super().has_permission(request, view): return False return request.user.groups.filter(name__in[admin_group, staff_group]).exists()Django自带的组和权限模型非常成熟这种轻量级RBAC完全不用自己造轮子。新员工入职时在前台系统里给他分配权限组就自然能访问对应接口。5. Flask在项目里的真正用处独立报表服务与数据可视化我观察网上的Django和Flask争论很多人非黑即白地认为“Django是重的Flask是轻的选一个就够了”。但实际一个复杂系统里完全可以两个都出现关键看职责是否独立。Flask在我们的架构里就是纯粹的“只读统计服务”。5.1 为什么单独拆一个Flask服务而不是少量加几个Django View第一版的时候我确实把统计接口直接写在Django里了比如/api/stats/today。但后来发现统计接口需要定时刷新缓存、需要频繁调整SQL性能、还要对接大屏的独立前端调用这些改动往往和主业务的发布节奏冲突。主业务发一次版本报表服务要跟着重启很麻烦。拆成独立Flask服务之后两个进程互不干扰。主业务发布也好、报表服务单独重启也好都各自独立。Flask服务的好处是启动快、依赖少我用它连接同一个MySQL数据库只做select查询不写业务表风险完全可控。5.2 接口设计与request参数的数据类型问题报表服务暴露三个核心接口# report_server/app.py from flask import Flask, jsonify, request from flask_cors import CORS import pymysql app Flask(__name__) CORS(app) def get_db(): return pymysql.connect( host127.0.0.1, usergym_user, passwordyour_password, databasegym, charsetutf8mb4 ) app.route(/report/api/stats/today) def stats_today(): conn get_db() cursor conn.cursor() cursor.execute(SELECT COUNT(*) FROM appointments WHERE DATE(create_time)CURDATE()) appoint_count cursor.fetchone()[0] cursor.close() conn.close() return jsonify({appointments_today: appoint_count}) if __name__ __main__: app.run(host0.0.0.0, port5000, debugTrue)Flask的request对象在调试时有个高频问题从客户端传入的参数类型永远是字符串。很多新手写日期范围统计接口时会直接拿request.args.get(start_date)去做加减运算结果报错。正确的做法是显式转换并且做好容错app.route(/report/api/stats/sales) def sales_stats(): start request.args.get(start) # 永远都是str end request.args.get(end) if not start or not end: return jsonify({error: 缺少日期参数}), 400 try: from datetime import datetime start_date datetime.strptime(start, %Y-%m-%d) end_date datetime.strptime(end, %Y-%m-%d) except ValueError: return jsonify({error: 日期格式应为 YYYY-MM-DD}), 400 # 继续查询这个“显式转换异常拦截”的套路解决了Flask开发里最常见的调试问题能看到参数实际类型和格式。5.3 大屏数据如何联动ECharts只负责画Flask只负责给数数据可视化大屏是健身房老板非常看重的功能。前端大屏用ECharts画折线图、柱状图、环形图数据来源全部来自Flask接口。前端通过fetch或axios定时轮询接口比如每60秒获取一次最新数据// report大屏里的轮询示例 setInterval(async () { const res await fetch(/report/api/stats/today) const data await res.json() todayAppointments.value data.appointments_today }, 60000)这里我刻意用轮询而不是WebSocket因为大屏数据对实时性要求没有那么高一分钟拉一次完全够。如果真是要做“后台有数据前端实时推送”这种需求比如预约成功后的实时弹窗提醒那才需要引入WebSocket。Django侧可以上channelsFlask侧可以用flask-socketio会用Griffith吗放心这种扩展聊起来很热闹但MVP阶段别急着上先让轮询把业务跑通后续有需求再加不迟。6. Vue前端联调axios请求、路由参数与跨域代理后端接口有了前端的工作就变成“把接口数据以合适的形态展示出来”。Vue项目里最核心的三件套是axios封装、vue-router路由、Element Plus组件。6.1 项目初始化与依赖安装先按前面章节创建的Vite项目安装依赖这里再把完整命令列一遍npm install npm install axios vue-router element-plus echarts安装完成后在src/main.js里全局注册Element Plusimport { createApp } from vue import App from ./App.vue import ElementPlus from element-plus import element-plus/dist/index.css import router from ./router import axios from ./utils/request const app createApp(App) app.use(ElementPlus) app.use(router) app.config.globalProperties.$axios axios app.mount(#app)6.2 路由设计与路由参数的正确用法按角色拆页面路由设置为// src/router/index.js import { createRouter, createWebHistory } from vue-router const routes [ { path: /, redirect: /dashboard }, { path: /login, component: () import(../views/LoginView.vue) }, { path: /dashboard, component: () import(../views/DashboardView.vue) }, { path: /members, component: () import(../views/MemberListView.vue) }, { path: /members/:id, component: () import(../views/MemberDetailView.vue), props: true }, { path: /courses, component: () import(../views/CourseListView.vue) }, { path: /appointments, component: () import(../views/AppointmentView.vue) }, ]这里有个非常重要的面试题级别的问题“路由参数怎么获取”在Vue3中用useRoute()获取整个路由对象然后route.params.id就是动态参数。作为对比还有一个写法是直接在路由配置里写props: true这样组件里可以直接通过defineProps拿到id代码更简洁script setup const props defineProps({ id: String }) // 直接用 props.id 请求会员详情 /script6.3 axios封装、请求拦截器与跨域问题axios不能裸着用工程化习惯是封装一个统一的request工具。比如自动携带Token、统一处理错误状态码、格式化时间字段// src/utils/request.js import axios from axios import { ElMessage } from element-plus const service axios.create({ baseURL: /api, timeout: 10000, }) service.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }) service.interceptors.response.use( response response.data, error { ElMessage.error(error.response?.data?.message || 请求失败) return Promise.reject(error) } ) export default service跨域问题是联调期最大的坑。Vue开发服务器默认跑在5173端口Django跑在8000端口浏览器直接请求Django接口会触发CORS拦截。解决方案有两个方向一个是后端加django-cors-headers另一个是前端开代理。我的建议是开发阶段用前端代理最简单最干净。在vite.config.js里配置export default defineConfig({ server: { proxy: { /api: { target: http://127.0.0.1:8000, changeOrigin: true, }, /report: { target: http://127.0.0.1:5000, changeOrigin: true, }, } } })这样前端代码里请求的地址就是/api/members浏览器看到的也是相对路径完全没有跨域问题。生产环境则通过Nginx做同源代理后面部署章节再展开。7. 部署上线静态文件、数据库与实时推送的坑项目做到这里代码层面已经能跑通了但离真正交给门店使用还差一步——部署。这一步大家平常开发时容易忽略真正上线时又各种奇怪问题集中爆发。我把我们上线时踩到的坑列出来尤其是和前后端分离架构相关的。7.1 三端构建部署Vue构建产物由Nginx托管生产环境的架构是Nginx托管Vue的静态文件同时把API请求反向代理到Django和Flask两个后端服务。前端构建cd gym_frontend npm run build构建完会生成dist目录里面是一堆纯静态文件。把dist目录拷到服务器上配置Nginxserver { listen 80; server_name gym.example.com; # Vue静态资源 location / { root /www/gym_frontend/dist; try_files $uri /index.html; } # Django接口 location /api/ { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # Flask报表接口 location /report/ { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; } }Django和Flask都是Python进程不能直接对外开放80端口需要借助WSGI服务器。Django用gunicorn启动gunicorn gym_backend.wsgi:application -b 127.0.0.1:8000 --workers 3Flask同样用gunicorn启动gunicorn app:app -b 127.0.0.1:5000 --workers 27.2 Django静态文件显示不了一个低级的配置坑很多新手在开发Django时遇到“img标签引用static文件显示不了”的问题其实九成是settings.py里的static配置没写对。Django自己处理静态文件需要两步# settings.py STATIC_URL /static/ STATICFILES_DIRS [BASE_DIR / static]然后模板里这样引用{% load static %} img src{% static images/logo.png %} altlogo开发模式下django.contrib.staticfiles会自动服务STATICFILES_DIRS里的文件。如果还是显示不了先检查路径是否大小写正确再检查settings里面有没有拼写错误这个问题90%都是路径问题。生产环境下静态文件可以直接交给Nginx管理不经过Django性能更好location /static/ { alias /www/gym_backend/static/; }7.3 数据库连接与代码安全别把密码硬编码部署时最容易忽略的安全细节是数据库密码。开发时图方便在settings.py和Flask的app.py里直接写数据库密码上线后没有及时改这是很危险的习惯。建议把敏感配置放到环境变量或配置文件里用os.environ读取import os DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: os.environ.get(DB_NAME, gym), USER: os.environ.get(DB_USER, gym_user), PASSWORD: os.environ.get(DB_PASSWORD, ), HOST: os.environ.get(DB_HOST, 127.0.0.1), } }7.4 实时推送的需求要不要上WebSocket我们本来想做“课程开始前10分钟自动提醒会员”这个功能一开始想用Django Channels做WebSocket推送但考虑到MVP阶段的消息渠道还没有打通最后是用最简单的方案过渡写了一个定时脚本每隔5分钟检查一次即将开始的课程通过短信/邮件接口发送提醒。这个方案实现成本低一行cron就能定时执行不需要WebSocket长连接稳定性也高。如果你确实要在页面上实时展示预约成功、课程开始等动态消息那再考虑WebSocket也不迟。Django用channelsFlask用flask-socketio但要注意的是WebSocket意味着你的后端进程必须常驻内存且保持长连接部署复杂度和资源占用都会上一个台阶。小体量项目先把轮询用好效果就已经很好了。这套健身房管理系统做下来我最大的体会是选型和架构不能脱离业务场景空谈。Django的核心业务承载能力、Flask的轻量统计服务、Vue的前端组件化每一块都在它最合适的位置上发挥作用。如果当时被“Django和Flask谁好”这种问题绊住项目可能到现在还没开工。另外M3U8格式的课程回放视频可以用hls.js在Vue里轻松播放但要确保视频内容有合法授权别给自己找麻烦。这个系统后续还有很多可以扩展的方向在线支付、微信小程序会员端、教练课酬自动结算甚至接智能硬件做门禁签到。代码跑通只是起点能跟着真实业务不断迭代才是这套项目最值得学习的地方。