1. 项目背景为什么选了 PythonVue 来做宿舍管理系统宿舍管理系统几乎是每个做 Web 开发的人绕不开的“练手级”项目。学期末的课程设计、毕设选题、入职前的个人项目翻来覆去都是这一类人员管理、房间分配、报修登记、门禁记录。它看起来不起眼但背后涉及的恰恰是信息管理系统里最常见的那一套范式——角色权限、数据建模、增删改查、前后端联调。把这一套东西跑通了换任何业务场景都能快速迁移。我这次做的是 Python 后端 Vue 前端的组合后端在 Django 和 Flask 之间纠结了一阵子最后两条路都实测了一遍各有各的脾气。整个项目用 Pycharm 作为开发环境前后端分离架构Vue 负责页面渲染和用户交互后端提供 JSON 接口数据落在 MySQL。标题里同时带了 Django 和 Flask其实两种方案都能完成这个系统区别在于你更看重“开箱即用”还是“轻量可控”。如果你是刚接触全栈开发的学生或者想快速攒一个能演示、能答辩、能拿得出手的项目这套方案非常合适。它不需要高深的算法不需要分布式架构但能把前端框架、后端框架、ORM、RESTful API、跨域处理、权限控制这些高频技能全部串一遍。做完之后你对“一个 Web 系统是怎么跑起来的”会有完整的认知而不是停留在碎片化的教程里。2. 整体设计与技术选型拆解2.1 业务需求梳理宿舍管理系统到底要管什么别看“宿舍管理”四个字简单真正梳理需求时模块能拆出七八个。一般高频核心模块包括学生信息管理学号、姓名、学院、班级、联系方式以及入住宿舍的绑定关系。宿舍楼栋与房间管理楼栋信息、房间号、床位数量、已住人数、剩余床位。分配与调宿学生入住分配、宿舍调整、退宿处理这部分要处理好“房间满员”的判断。报修管理学生提交报修工单宿管查看进度维修人员更新状态。访客/门禁记录进出记录、访客登记至少要有记录列表和条件筛选。公告通知管理员发布宿舍公告学生端能查看。用户与权限管理员、宿管、学生三类角色权限分级。学生只能看自己的信息、提交报修宿管可以管理本楼数据管理员拥有全部权限。从技术层面看这些模块本质就是围绕几张核心表的“增删改查 关系查询”。但难点在三处第一宿舍与学生的关系是动态的分配、调宿、退宿要处理好状态变更第二权限控制要落地到接口级别第三前端表格、表单、弹窗的交互要顺畅数据回显不出错。2.2 Django 还是 Flask怎么选才是最优解标题里同时出现 Django 和 Flask那我直接把我的选型思路讲透。Django 是“全家桶”路线自带 Admin 后台、ORM、认证系统、表单处理连迁移工具都是内置的。做宿舍管理系统这种标准的业务系统Django 能省非常多事。比如 Admin 后台零代码就能得到一个可用的数据管理界面对课设答辩来说非常加分再比如 Django ORM定义了模型后执行 migrate表结构自动生成不需要手写 SQL。如果你希望快速出活、少踩坑Django 是我的首选推荐。Flask 则走“轻量微框架”路线核心只做路由和视图其他全部靠第三方库搭配。它的好处是灵活可控适合你希望把每个环节都看得清清楚楚、学到更多底层的场景。数据库用 Flask-SQLAlchemy迁移用 Flask-Migrate认证用 Flask-JWT-Extended整个链路需要自己拼装。一句话总结追求效率、想要省心选 Django追求灵活、想练手底层逻辑选 Flask。我这次项目最终以 Django 为主路线做完整演示但关键的接口设计思路在两种框架下是完全通用的Flask 版本我会把差异化配置单独指出来。2.3 Pycharm 在项目里到底起了什么作用很多初学者把 Pycharm 简单理解成“写 Python 的记事本”其实它在这个全栈项目里的作用比想象中大。先说 Virtualenv 管理。Pycharm 里新建项目时可以顺手创建虚拟环境Django、Flask、各类依赖都装在里面不污染全局 Python。我见过太多同学把包直接装到全局环境里项目一多互相冲突最后只能重装解释器。再说前后端联调。Vue 项目本身跑在 Node 环境但 Pycharm 专业版对 JavaScript、TypeScript、Vue 单文件组件都有支持可以直接在 Pycharm 里打开前端工程改完代码不用切窗口。调试时先用 Pycharm 启动 Django 后端带断点调试再用终端启动 Vue 开发服务器配合代理配置实现联调效率比纯手写高很多。还值得一提的是 Pycharm 的数据库工具。它内置数据库面板可以直接连上 MySQL浏览表结构、执行测试 SQL、查看查询结果不需要额外装 Navicat 或 DataGrip。排查 ORM 生成的 SQL 是否合理、字段类型是否对得上在数据库面板里一目了然。3. 数据库建模与核心接口设计3.1 数据表设计与关键关联关系宿舍管理系统的核心是两张主表学生表和宿舍表其余业务表都围绕它们展开。我最终设计的核心表包括User 用户表存放登录账号、密码哈希、角色类型admin / dorm_admin / student。这里要注意学生信息与用户账号可以分开也可以合并我是采用“用户表 学生档案表”分离的方式方便扩展宿管、维修工等角色。StudentProfile 学生档案表学号、姓名、性别、学院、班级、电话、入住状态。Building 楼栋表楼栋名称、楼栋编号、楼层数、宿管负责人。Room 宿舍表所属楼栋、房间号、床位数、已住人数、空调/独卫等设施标记同时用状态字段标记是否可分配。Assignment 住宿分配表学生ID、宿舍ID、入住日期、退宿日期、状态。这张表是关键不要直接在学生表里存宿舍ID因为调宿、退宿会导致数据覆盖丢失历史记录。RepairOrder 报修表报修人、宿舍关联、报修内容、图片URL、状态待处理/处理中/已完成、提交时间。Notice 公告表标题、内容、发布时间、发布人。外键关系上Room 从属于 BuildingAssignment 关联 Student 和 RoomRepairOrder 关联 Student 和 Room。一个常见的误区是“学生表里加一个 room_id 字段不就行了”这样做当时看起来简单一旦学生从 101 调去 202原来的宿舍关系就丢了后续做历史追溯非常麻烦。所以关联表一定要单独建这属于数据结构上的基本功但很多人图省事埋了坑。3.2 用 Django ORM 建模的关键代码片段Django 里定义模型非常直观下面是我在实际项目中确定的核心模型代码关键是状态字段和关联关系处理这里只做片段展示from django.db import models class Building(models.Model): name models.CharField(楼栋名称, max_length50, uniqueTrue) floors models.IntegerField(楼层数, default6) class Room(models.Model): building models.ForeignKey(Building, on_deletemodels.CASCADE, related_namerooms) room_no models.CharField(房间号, max_length20) bed_count models.IntegerField(床位数, default4) occupied models.IntegerField(已住人数, default0) class Meta: unique_together (building, room_no) property def is_full(self): return self.occupied self.bed_count class StudentProfile(models.Model): student_no models.CharField(学号, max_length20, uniqueTrue) name models.CharField(姓名, max_length50) gender models.CharField(性别, max_length10) college models.CharField(学院, max_length100) phone models.CharField(联系电话, max_length20) class Assignment(models.Model): student models.OneToOneField(StudentProfile, on_deletemodels.CASCADE) room models.ForeignKey(Room, on_deletemodels.CASCADE) check_in_date models.DateField(入住日期) check_out_date models.DateField(退宿日期, nullTrue, blankTrue)这里有几个细节值得展开。unique_together保证了同一栋楼里房间号不会重复这是数据库层面的兜底is_full用 property 而不是直接存一个布尔值是为了避免“已住人数变更后忘记同步满员标志”的问题check_out_date是空值时表示当前正在入住。分配房间的逻辑我放在 service 层方法里def assign_room(student, room): if room.is_full: raise ValueError(房间已满员无法分配) if Assignment.objects.filter(studentstudent, check_out_date__isnullTrue).exists(): raise ValueError(该学生当前已有入住记录) assignment Assignment.objects.create(studentstudent, roomroom, check_in_datedate.today()) room.occupied 1 room.save() return assignment这个逻辑最容易被忽略的是“一个学生不能同时有两条未退宿的分配记录”。界面操作时看不出来但并发请求时如果没有判断就会出现数据错乱。加一个查询判断成本极低但能堵住大问题。3.3 Flask 版本的等价实现配置差异重点如果你选择 Flask同样的模型用 Flask-SQLAlchemy 表达核心差异有三个一是模型基类变为db.Model二是字段类型要在初始化时传参而不是在内部写三是迁移工具要单独配置 Flask-Migrate。我直接把等效的代码写出来看差异就清晰了from flask_sqlalchemy import SQLAlchemy db SQLAlchemy() class Room(db.Model): __tablename__ room id db.Column(db.Integer, primary_keyTrue) building_id db.Column(db.Integer, db.ForeignKey(building.id), nullableFalse) room_no db.Column(db.String(20), nullableFalse) bed_count db.Column(db.Integer, default4) occupied db.Column(db.Integer, default0) property def is_full(self): return self.occupied self.bed_countFlask 的 Serializer 没有内置方案一般配合 Marshmallow 做序列化这跟 Django 的serializers模块是两种套路。我的建议是如果不是特别想折腾这些拼装过程就直接选 Django把精力省下来放到前端联调上。3.4 接口设计规范与权限控制落地前端 Vue 通过 HTTP 请求获取数据因此后端接口需要按 RESTful 风格设计。以报修模块为例接口划分为GET /api/repairs/?status1page1按状态分页获取报修列表宿管可用。POST /api/repairs/学生提交报修。PUT /api/repairs/{id}/更新报修状态维修工/宿管可用。DELETE /api/repairs/{id}/删除错误报修单管理员可用。权限控制方面Django 自带的IsAuthenticated只能解决“是否登录”解决不了“角色是否允许”。比较简洁的做法是自定义权限类from rest_framework.permissions import BasePermission class IsDormAdmin(BasePermission): def has_permission(self, request, view): return request.user.is_authenticated and request.user.role dorm_admin请求进来先判登录再判角色不满足就直接 403前端拿不到数据会弹提示这属于后端的第一道闸门。同时前端路由也要做角色守卫不能只靠隐藏按钮来防越权因为懂技术的人直接打开浏览器开发者工具就能改请求拿数据。4. 实操过程从空目录到前后端联调4.1 环境准备与版本选型实测稳定的组合这个项目实测下来最稳的环境组合是Python 3.10Django 4.2 LTSDjango REST Framework 3.14Vue 3 ViteNode 18MySQL 8.0Pycharm 中新建 Django 项目时可以直接选中虚拟环境解释器。数据库连接我推荐使用pymysql并做好兼容配置。这里有一个非常容易踩的坑MySQL 8.0 默认认证方式是caching_sha2_password如果 Django 连接报错需要在 MySQL 里调整一下用户认证方式或者直接用较新的 PyMySQL 版本同时把pymysql.install_as_MySQLdb()放到__init__.py里Django 才能正确识别它作为数据库驱动。Vue 工程这边不再推荐 Vue CLIVite 创建更快、依赖更少。创建命令很简单npm create vitelatest frontend -- --template vue cd frontend npm install npm install axios element-plus vue-router piniaElement Plus 作为 UI 组件库表单、表格、弹窗、消息提示都有现成组件适合快速搭建后台管理界面。Pinia 做全局状态管理比如登录后保存用户信息、token在不同页面间共享。Vue Router 用 history 模式配置路由守卫来控制页面访问权限。4.2 后端接口实现与 DRF 配置在 Django 里启用 DRF 后接口的编写效率确实高。我是在views.py里用ModelViewSet快速完成了报修模块的基础接口from rest_framework import viewsets from .models import RepairOrder from .serializers import RepairOrderSerializer class RepairOrderViewSet(viewsets.ModelViewSet): queryset RepairOrder.objects.all() serializer_class RepairOrderSerializer def get_queryset(self): qs super().get_queryset() status self.request.query_params.get(status) if status: qs qs.filter(statusstatus) return qs但要注意ModelViewSet生成的接口默认允许任何已认证用户调任意接口如果不重写权限或过滤逻辑就会出现“普通学生可以删除所有报修单”的风险。我实际用下来最合适的做法是重写perform_create和get_queryset让普通学生只能操作自己的数据class RepairOrderViewSet(viewsets.ModelViewSet): ... def perform_create(self, serializer): student StudentProfile.objects.get(userself.request.user) serializer.save(studentstudent) def get_queryset(self): if self.request.user.role student: return RepairOrder.objects.filter(student__userself.request.user) return RepairOrder.objects.all()这里的关键点在于学生提交报修时报修人信息不要信任前端传来的 user id而是从当前登录用户中直接解析。这是安全常识——前端传什么都可以伪造后端必须自己认人。URL 路由配置用 DRF 的 DefaultRouter几行就能把所有标准接口都生成出来from rest_framework.routers import DefaultRouter from .views import RepairOrderViewSet, RoomViewSet, AssignmentViewSet router DefaultRouter() router.register(rrepairs, RepairOrderViewSet) router.register(rrooms, RoomViewSet) router.register(rassignments, AssignmentViewSet) urlpatterns router.urls4.3 Vue 前端与 Axios 请求封装前端这一步做好后大部分页面其实就是写表格 弹窗表单。但有一个比较重要的基建工作Axios 的请求封装。我统一维护了一套请求工具所有接口访问都走它统一处理 token 注入、错误提示和状态码// src/utils/request.js import axios from axios import { ElMessage } from element-plus import router from ../router const request axios.create({ baseURL: /api, timeout: 10000 }) request.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization JWT ${token} } return config }) request.interceptors.response.use( response response.data, error { if (error.response.status 401) { localStorage.removeItem(token) router.push(/login) } ElMessage.error(error.response?.data?.detail || 请求失败) return Promise.reject(error) } ) export default request这里有个我在实际联调过程中才意识到的问题生产环境下Vue 打包后的静态文件和 Django 可能部署在同一个域名的不同路径所以baseURL最好配置成相对路径/api而不是写死http://localhost:8000。这样开发时用 Vite 代理转发部署时用 Nginx 反向代理一个配置不用改。Vite 开发代理配置如下这也是解决跨域问题的主要手段// vite.config.js export default defineConfig({ server: { proxy: { /api: { target: http://127.0.0.1:8000, changeOrigin: true } } } })4.4 登录流程、JWT 认证与路由守卫宿舍管理系统要区分角色登录流程里一定要把 token 和用户信息分开存。我的做法是用户输入账号密码后请求POST /api/auth/login/后端校验通过返回token和user_info。前端拿到后分别存储token 存 localStorage用户信息存 Piniaconst res await request.post(/auth/login/, { username, password }) localStorage.setItem(token, res.token) userStore.setUser(res.user_info) router.push(userStore.isAdmin ? /admin : /home)路由守卫可以防止未登录用户直接通过改 URL 访问后台页面。在router/index.js里加一段判断router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next(/login) } else if (to.meta.requiresAdmin !userStore.isAdmin) { next(/403) } else { next() } })这里要说明一点前端路由守卫只能提升体验不能真正防越权。真正的安全底线在接口权限上——如果后端没有做权限校验前端路由守卫生效也没用。实际测试时我试过直接通过浏览器控制台发送请求访问学生列表接口没有任何页面配合如果后端不拦截就直接拿到数据了。所以前后端权限必须同时做前端负责“展示控制”后端负责“数据控制”。4.5 宿舍分配与报修流程的完整闭环拿宿舍调宿来举例完整流程涉及多个接口协作。前端把学生和目的宿舍传给后端后端执行几件事验证学生当前有未退宿的入住记录验证目标宿舍未满员关闭旧的分配记录设置 check_out_date创建新的分配记录同时更新新旧宿舍的已住人数。这几个步骤中间任何一步失败都不能产生半截数据所以我用事务把整个流程包起来from django.db import transaction transaction.atomic def change_room(student, new_room): old_assignment Assignment.objects.filter(studentstudent, check_out_date__isnullTrue).first() if not old_assignment: raise ValueError(该学生当前没有入住记录) if new_room.is_full: raise ValueError(目标宿舍已满员) old_assignment.check_out_date date.today() old_assignment.save() old_room old_assignment.room old_room.occupied - 1 old_room.save() new_room.occupied 1 new_room.save() Assignment.objects.create(studentstudent, roomnew_room, check_in_datedate.today())这段代码是整套系统里最值得细看的比单纯写增删改查有价值。不加事务就会出现退宿成功了但入住失败或者旧宿舍人数减了但新宿舍人数没加数据全乱。事务保证了操作原子性要么全部成功要么全部回滚。宿舍管理系统表面简单但这类隐藏的业务逻辑才是拖垮项目质量的地方。5. 常见问题与排查技巧实录5.1 跨域报错与接口 403开发模式下前端跑在 5173后端跑在 8000两个端口不同必然触发跨域。我的处理方式分两层。开发时优先使用 Vite 代理它把请求转发到后端浏览器看到的始终是同源请求配置在上面已经写过。部署时在 Django 的Middleware里加跨域头同时安装django-cors-headersINSTALLED_APPS [ ..., corsheaders ] MIDDLEWARE [ corsheaders.middleware.CorsMiddleware, ... ] CORS_ALLOW_ALL_ORIGINS False CORS_ALLOWED_ORIGINS [http://localhost:5173]需要特别说明的是如果使用了 JWT 认证跨域请求头的Authorization字段必须在允许范围内。Django-cors-headers 默认允许的请求头里包含 Authorization所以一般不会出问题。但如果你自己从零配置 Nginx 反向代理就一定要显式加上add_header Access-Control-Allow-Headers Authorization否则前端请求发出去后浏览器会拦截响应报错信息看起来像是接口崩了实际上是 CORS 层没有放行。5.2 ORM 查询产生的 N1 问题列表页展示报修记录时表格里有“学生姓名”“宿舍号”这种关联字段。如果序列化时不加select_relatedDjango ORM 会一条主查询查出 20 条报修然后每条再查一次学生和宿舍合计发出 41 条 SQL。数据量小时没感觉数据过千后接口延迟会非常明显。解决方式是在 queryset 里提前用select_related把外键关系一次性查出来queryset RepairOrder.objects.select_related(student, room).all()同理学生列表展示宿舍信息时用belongs_to反查也一样要预先关联。这个优化属于“看似没动接口快了十倍”的典型案例面试时也常被问到值得记下来。5.3 前端表格数据格式对不上的问题Element Plus 的el-table默认期望数据是数组而后端分页接口返回的是{ count: 100, results: [...] }。如果直接传给el-table页面表格会空白。很多初学者在这里卡半天以为接口写错了。解决办法是取response.data.results传给表格count传给分页组件的total。类似的问题还有时间格式化。Django 返回的时间格式是2025-01-14T15:30:00.123456Z页面直接显示出来非常难看。我在序列化器里统一配置了时间格式class RepairOrderSerializer(serializers.ModelSerializer): created_at serializers.DateTimeField(format%Y-%m-%d %H:%M) class Meta: model RepairOrder fields __all__Flask 里用 Marshmallow 时from marshmallow import Schema, fields class RepairOrderSchema(Schema): created_at fields.DateTime(format%Y-%m-%d %H:%M)前后端花点时间把字段格式对齐能省掉大量不必要的联调沟通。5.4 图片上传与静态资源服务报修功能里我设计了一个“上传现场照片”的字段。这个功能踩的坑比想象多。首先图片不能直接存数据库正确做法是把文件存到磁盘或者对象存储数据库里只存 URL。Django 默认的MEDIA_ROOT和MEDIA_URL可以处理本地存储MEDIA_URL /media/ MEDIA_ROOT BASE_DIR / media开发模式下在urls.py里手动加上媒体文件路由from django.conf import settings from django.conf.urls.static import static urlpatterns [ ... ] if settings.DEBUG: urlpatterns static(settings.MEDIA_URL, document_rootsettings.MEDIA_ROOT)部署到生产环境后静态文件和媒体文件的托管要交给 Nginx而不是让 Django 处理。否则并发一上来Django 内置的开发服务器会直接卡死。这个坑几乎每个全栈新手都会踩一遍我只是提个醒。5.5 常见排查问题速查表组合排查问题时我用下面的表格可以快速定位现象可能原因处理方式前端请求返回 404路由注册遗漏或 URL 前缀不对检查项目内urls.py和router.register前端请求返回 403权限类拦截或 CSRF 校验失败确认登录状态和角色DRF 中关闭 CSRFAPI 用 Token 认证登录成功后刷新页面失效未在 Pinia 初始化时恢复用户信息在 Store 初始化时从 localStorage 读取并解析用户报修图片不显示媒体文件路由未配置或静态服务缺失配置MEDIA_ROOT并在 urls 中绑定宿舍人数超过床位数分配时未检查is_full在事务中分配前强制校验并加数据库约束中文乱码MySQL 字符集设置不对建库时指定utf8mb4连接字符串加charsetutf8el-table 表格空白数据格式不是数组从分页对象中取得results数组再传入这不是一份普通的知识点列表每一条都是我在实际调试中真正遇到过的。特别是中文乱码的问题新手很容易忽略 MySQL 字符集配置等到前端页面上出现问号时才追查而问题往往出在最初建库的那条 SQL 上。6. 从项目到答辩/面试的经验沉淀做完这个宿舍管理系统后最大的感受是全栈项目的难点从来不是单个技术而是“权限怎么串起来、状态怎么保持一致、前后端怎么协同”。很多人学着学着只记住了“会调接口、会写页面”一旦面对“你设计宿舍调宿时怎么处理数据一致性”这种问题就卡壳而这类问题恰恰是答辩和面试的高频考题。我把这个项目翻来覆去优化了好几轮才真正意识到一个道理项目的亮点不在于功能数量多而在于边界场景的处理。比如学生退宿后房间人数是否正确回减、满员房间能否被并发分配、报修状态流转能不能被随意跳过。你只要在项目里认真处理过其中任何一个场景就能在讲述时明显比其他人多一层深度。最后分享一个小技巧开发时一定要在列表接口都加上分页和搜索过滤不要嫌麻烦。答辩时演示几十条数据看不出差异但面试官问“数据量上来了怎么优化”时你能直接答出分页、select_related、索引这几个点会比只说“用 Vue 写的”有说服力得多。这个项目的价值不在于代码量而在于你能否把每个环节的“为什么”讲清楚。