宿舍管理系统算是我接触过的Python Web项目里非常典型的一类CRUD应用。说是“典型”是因为它的业务逻辑不复杂核心就是对学生信息、宿舍床位、入住退宿、报修记录这些数据进行增删改查但真正把一个宿舍管理系统从零写明白需要处理的需求细节却不少。我最早用Django做这个系统时光是一个“宿舍满了怎么办”就折腾了好几个版本后来才把数据模型和流程理顺。这篇博文就把我完整的实现思路、数据库设计、核心代码和踩坑记录整理出来不管是期末课程设计、毕业设计还是想快速搭建一个内部管理后台都可以直接参考。1. 项目定位与需求拆解1.1 宿舍管理到底在管什么做任何系统之前先把业务对象想清楚。宿舍管理系统的核心参与者有三类学生、宿管员、系统管理员。围绕这三类角色日常业务可以拆成这么几块学生信息管理学号、姓名、性别、院系、专业、联系方式以及这个学生当前住在哪个宿舍。这是最基础的数据。宿舍资源管理楼栋、房间号、床位容量、当前已住人数以及房间是男生宿舍还是女生宿舍。入住与退宿流程学生入住时要分配宿舍退宿时要释放床位换宿时要记录历史。报修处理学生提交水电、门锁、家具等报修申请宿管员更新处理状态。公告通知管理员发布停水停电、安全检查等通知学生登录后能看到。这些需求看起来简单但真正做起来会发现很多细节会影响数据库设计。比如宿舍分配时如果房间已经住满了系统必须拦截退宿之后该学生不能再占着床位调宿舍时还要保留历史记录方便以后查账或者排查问题。这些流程性需求必须在数据模型层面就想清楚而不是等写代码的时候再临时补。1.2 为什么选 Python Django而不是其他方案我见过不少人用PHP、或者用Node.js写前后端分离来折腾宿舍管理但说实话对这种偏内部管理的系统Python加Django是开发效率最高的组合之一。理由很实在Django自带ORM可以直接用Python类定义表结构迁移命令一键建表不用手写SQL。Django自带Admin后台默认就有数据管理页面开发阶段几乎不用写前端代码就能完成大部分管理操作。自带用户认证体系登录、权限、session这些直接复用省掉一大块工作量。模板引擎够用列表页、详情页直接用Django Template渲染不需要维护前后端两套工程。如果用前后端分离方案等于把简单问题复杂化要单独做接口、做Token认证、做跨域配置还得再写一套Vue页面。宿舍管理系统本身没有复杂的交互Django的“服务端渲染 Admin后台”路线一个人短时间内就能把完整系统跑起来这是它最大的优势。当然选择Django也有需要注意的地方。它的“约定优于配置”风格意味着目录结构、命名规范最好按官方习惯来否则后面维护会别扭。还有Django自带的ORM在简单查询上非常舒服但遇到极复杂的统计SQL时还是得用extra或原生SQL兜底。针对宿舍管理这个体量这些都不是问题。2. 整体设计与数据库建模2.1 功能模块划分我在设计时没有把功能拆得特别碎而是按照业务域划分成四个APP每个APP职责单一方便维护accounts用户登录、学生账号与User模型关联、宿管员权限分组。dormitory宿舍楼栋与房间管理、学生基本信息管理、入住和退宿记录。repair报修工单的创建、处理、状态流转。notice公告的发布与展示。这种拆分的好处是后续如果只想给某个模块加字段改对应APP即可不会动到其他模块。比如报修模块要增加“维修人员电话”字段只需要改repair里的模型而宿舍模块完全不受影响。权限设计上我用了Django自带的User模型加Group分组。管理员属于admin组宿管员属于dorm_manager组学生用户标记为is_staffFalse并用OneToOne关联到Student表。视图层通过装饰器做准入判断比如发布公告只能管理员操作处理报修需要宿管员或管理员权限。2.2 核心数据表与关联关系数据库是这类系统最值得花时间的地方。我设计了五张核心表下面把字段和关系写清楚。第一张是宿舍表Dormitorybuilding楼栋名比如“1号楼”“2号楼”room_number房间号比如“101”capacity床位容量一般是4、6、8gender_type宿舍类型男/女用于分配时防止混住唯一约束同一楼栋下房间号不能重复第二张是学生表Studentstudent_no学号唯一name姓名gender性别department院系major专业phone手机号dormitory外键关联Dormitory允许为空空表示当前未入住create_time创建时间第三张是住宿记录表HousingRecordstudent外键关联Studentdormitory外键关联Dormitorymove_in_time入住时间move_out_time退宿时间为空表示在住status状态在住/已退第四张是报修表RepairOrderstudent外键关联Student记录谁报修的dormitory外键关联Dormitory保存报修时所在的宿舍信息category报修类型比如水电、门锁、家具description详细描述status待处理/处理中/已完成created_time报修时间finish_time完成时间第五张是公告表Noticetitle标题content正文publisher发布人外键关联Userpublish_time发布时间这里最关键的是Student和HousingRecord之间的配合。Student里的dormitory字段保存的是“当前状态”HousingRecord保存的是“每一次入住退宿的历史流水”。这两个并行存在既保证了列表页可以快速知道谁住在哪又不会丢失调宿记录。2.3 设计取舍当前状态和历史流水分开我最早做的时候图省事只给学生表加了一个宿舍外键退宿直接置空。后来被问到“上学期这个学生住过哪个房间”时完全答不上来因为没有历史表。所以我加了一张HousingRecord专门记录每一次住宿变更。为什么不用单一外键覆盖全部业务因为需求场景不同。当前状态追求的是查询快历史记录追求的是可追溯。用一张表同时满足两个场景要么冗余字段多要么查询逻辑复杂。分开之后逻辑非常清晰改宿舍先更新Student.dormitory再往HousingRecord插入一条“新入住”记录退宿时更新Student.dormitory为空同时把HousingRecord里在住记录标记为退宿。还有一个细节值得提外键的on_delete参数。学生对应的宿舍如果被删除合理行为是保留学生记录但置空宿舍字段所以用on_deletemodels.SET_NULL并且nullTrue。而HousingRecord关联的学生如果被删除这条历史记录本身也没有保留意义了可以用CASCADE。报修记录我建议用PROTECT防止学生被删后报修记录被连锁删除方便后期审计。3. 从零到一核心代码实现3.1 环境准备与项目初始化开发环境我用的是Python 3.10和Django 4.2 LTS。Django 4.x和旧版本有个明显区别就是时区处理、路由配置的写法已经比较现代网上资料也最多遇到问题容易搜到解决方案。初始化项目的步骤我列一下# 创建项目目录并进入 mkdir dormitory_system cd dormitory_system # 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Windows系统用 venv\Scripts\activate # 安装Django pip install django # 创建项目和APP django-admin startproject config . python manage.py startapp accounts python manage.py startapp dormitory python manage.py startapp repair python manage.py startapp notice创建完APP后记得在config/settings.py的INSTALLED_APPS里注册这五个模块。还需要配置语言和时区把LANGUAGE_CODE改成zh-hansTIME_ZONE改成Asia/Shanghai并设置USE_TZFalse。如果不改时区后面写入数据库的时间会差8个小时排查起来很头疼。3.2 模型层用ORM把表结构写清楚模型是Django里最不能省事的部分。我把dormitory/models.py里几个核心模型分享出来这些代码是完整跑通过了的。from django.db import models class Dormitory(models.Model): GENDER_TYPE_CHOICES ( (M, 男), (F, 女), ) building models.CharField(楼栋, max_length50) room_number models.CharField(房间号, max_length20) capacity models.PositiveIntegerField(床位容量, default4) gender_type models.CharField(宿舍类型, max_length1, choicesGENDER_TYPE_CHOICES) class Meta: verbose_name 宿舍 verbose_name_plural verbose_name unique_together (building, room_number) def __str__(self): return f{self.building}-{self.room_number} property def current_count(self): return self.student_set.filter(dormitoryself).count() property def is_full(self): return self.current_count self.capacityDormitory里的current_count属性在Admin列表页和分配宿舍时都会用到直接统计当前住在这个房间的学生数量。unique_together保证了同一个楼栋下不会出现两个相同的房间号这是数据完整性最基本的保障。再看Student模型class Student(models.Model): GENDER_CHOICES ( (M, 男), (F, 女), ) student_no models.CharField(学号, max_length30, uniqueTrue) name models.CharField(姓名, max_length50) gender models.CharField(性别, max_length1, choicesGENDER_CHOICES) department models.CharField(院系, max_length100) major models.CharField(专业, max_length100) phone models.CharField(联系方式, max_length20) dormitory models.ForeignKey( Dormitory, verbose_name宿舍, on_deletemodels.SET_NULL, nullTrue, blankTrue, related_namestudent_set ) class Meta: verbose_name 学生 verbose_name_plural verbose_name def __str__(self): return f{self.name}({self.student_no}) property def dormitory_info(self): return f{self.dormitory.building}-{self.dormitory.room_number} if self.dormitory else 未入住Student用ForeignKey关联Dormitory注意on_delete用的是SET_NULL。我在实际开发中吃过亏如果直接CASCADE删除一个宿舍会把所有学生都删掉这在业务上绝对不允许。管理员误删宿舍最多就是学生变成“未入住”可以通过手动重新分配恢复。HousingRecord记录历史流水class HousingRecord(models.Model): STATUS_CHOICES ( (IN, 在住), (OUT, 已退), ) student models.ForeignKey(Student, on_deletemodels.CASCADE, verbose_name学生) dormitory models.ForeignKey(Dormitory, on_deletemodels.PROTECT, verbose_name宿舍) move_in_time models.DateTimeField(入住时间, auto_now_addTrue) move_out_time models.DateTimeField(退宿时间, nullTrue, blankTrue) status models.CharField(状态, max_length3, choicesSTATUS_CHOICES, defaultIN) class Meta: verbose_name 住宿记录 verbose_name_plural verbose_nameHousingRecord的status和move_out_time其实有一部分信息是重复的在住时move_out_time为空退宿时move_out_time不为空。我为什么还要冗余一个status字段因为对于在住的宿舍我会频繁统计“当前在住学生”直接filter(statusIN)比同时判断move_out_time是否为空要直观得多。索引上也更友好如果数据量变大还能在status上加索引。RepairOrder模型class RepairOrder(models.Model): CATEGORY_CHOICES ( (WATER, 水电), (DOOR, 门窗锁具), (FURNITURE, 家具), (OTHER, 其他), ) STATUS_CHOICES ( (PENDING, 待处理), (PROCESSING, 处理中), (DONE, 已完成), ) student models.ForeignKey(Student, on_deletemodels.PROTECT, verbose_name报修学生) dormitory models.ForeignKey(Dormitory, on_deletemodels.PROTECT, verbose_name宿舍) category models.CharField(报修类型, max_length20, choicesCATEGORY_CHOICES) description models.TextField(问题描述) status models.CharField(状态, max_length10, choicesSTATUS_CHOICES, defaultPENDING) created_time models.DateTimeField(报修时间, auto_now_addTrue) finish_time models.DateTimeField(完成时间, nullTrue, blankTrue) class Meta: verbose_name 报修记录 verbose_name_plural verbose_nameRepairOrder里我保存了一个独立的dormitory字段而不是通过student再查一次宿舍。因为报修单创建后如果学生后来调了宿舍报修单上的宿舍仍然应该是“报修时所在宿舍”否则维修师傅会跑错地方。这种冗余在业务上是合理的。写模型时有个小建议每个字段都要写verbose_name并且尽量写完整的帮助信息。课程设计或团队协作时别人看到字段名first time就能明白含义不至于还要翻代码。3.3 视图层列表筛选与入住分配模型建好之后视图层是业务逻辑最集中的地方。我没有用Django的通用视图Class-Based View而是选择了函数视图。原因很简单宿舍管理的每个操作比如入住、退宿、报修状态变更都需要插入额外的业务判断函数视图写起来更直观调试的时候也更容易定位问题。学生列表页是多条件筛选的经典场景我贴一下核心代码from django.shortcuts import render, get_object_or_404, redirect from django.db.models import Q from .models import Student, Dormitory def student_list(request): students Student.objects.select_related(dormitory).order_by(student_no) keyword request.GET.get(keyword, ).strip() gender request.GET.get(gender, ) building request.GET.get(building, ) if keyword: students students.filter( Q(student_no__icontainskeyword) | Q(name__icontainskeyword) ) if gender: students students.filter(gendergender) if building: students students.filter(dormitory__buildingbuilding) return render(request, dormitory/student_list.html, { students: students, dormitories: Dormitory.objects.values_list(building, flatTrue).distinct(), })这里有个很重要的优化Student.objects.select_related(dormitory)。如果不加这一句列表页每显示一个学生Django就会去数据库查一次他对应的宿舍页面渲染100个学生就是101条SQL。加了select_related之后Django会用一次JOIN把宿舍信息一起查出来。我在开发时用django-debug-toolbar一眼就看到这个问题不加之前列表页有几十条重复SQL加完之后降到了一次。入住分配的逻辑是这样的先判断宿舍是否存在再判断是否满员还要判断性别是否匹配最后才执行分配。def assign_dormitory(request, student_id): student get_object_or_404(Student, pkstudent_id) if request.method POST: dorm_id request.POST.get(dormitory) dorm get_object_or_404(Dormitory, pkdorm_id) if dorm.is_full: return render(request, error.html, {message: 该宿舍已住满无法分配}) if student.gender ! dorm.gender_type: return render(request, error.html, {message: 性别不匹配无法分配}) # 当前状态更新 student.dormitory dorm student.save() # 历史流水记录 HousingRecord.objects.create( studentstudent, dormitorydorm, statusIN ) return redirect(dormitory:student_detail, student_idstudent.id) available_dormitories Dormitory.objects.filter( gender_typestudent.gender ).exclude( id__in[d.id for d in Dormitory.objects.all() if d.is_full] ) return render(request, dormitory/assign_dormitory.html, { student: student, dormitories: available_dormitories, })这段代码里有两个细节值得注意。第一个是“住在满员宿舍”的判断dorm.is_full这个属性会实时统计学生数量确保并发情况下也不会超住。第二个是性别校验在分配前就拦截掉不匹配的情况而不是写入后再修复。实际宿舍管理中男生住在女生宿舍这种问题是管理员最想避免的代码层面直接硬性校验比事后检查靠谱得多。这里我也踩过一个坑先用列表推导式Dormitory.objects.all()去判断is_full如果宿舍数量大性能会很差。实际课程设计规模下没问题但放到正式环境更好的做法是在数据库层面用annotate统计学生数再filter比较。我在文章后面的优化建议里会再强调。3.4 Admin后台不写前端也能管理Django Admin是这个项目最大的福音。我几乎没为管理端写任何HTML页面全部靠注册Admin模型就实现了宿舍、学生、报修、公告的后台管理。以下是dormitory/admin.py的配置from django.contrib import admin from .models import Dormitory, Student, HousingRecord class StudentInline(admin.TabularInline): model Student extra 0 fields (student_no, name, gender, major) admin.register(Dormitory) class DormitoryAdmin(admin.ModelAdmin): list_display (building, room_number, capacity, current_count, is_full, gender_type) list_filter (building, gender_type) search_fields (building, room_number) inlines [StudentInline] admin.register(Student) class StudentAdmin(admin.ModelAdmin): list_display (student_no, name, gender, department, major, dormitory_info) list_filter (gender, department, dormitory__building) search_fields (student_no, name, phone) autocomplete_fields (dormitory,) admin.register(HousingRecord) class HousingRecordAdmin(admin.ModelAdmin): list_display (student, dormitory, move_in_time, move_out_time, status) list_filter (status, dormitory__building)Admin配置的几个点放一起看会更有体会current_count和is_full是模型里的property可以直接显示在管理列表中宿管员一眼就能看出哪些房间满了。StudentInline嵌入在宿舍详情页里。管理员打开某个房间时能直接看到住在这个房间的学生体验非常自然。HousingRecord单独注册方便按学生查询住宿历史。这些配置看着简单但把Django Admin的“可配置性”用足了。Student模型里没有自己的list_display函数我在Admin里定义了dormitory_info直接调用模型属性列表页就不用显示“外键对象”那种不友好的形式了。4. 项目跑通与常见问题排查4.1 拿到“源码数据库”怎么快速跑起来如果你拿到的是别人分享的“源码数据库文档”这种形式的项目第一步不要急着打开一堆代码文件而是先看README或者文档里的“快速开始”部分。规范的交付包一定会有环境要求、数据库配置说明和启动命令。以我的项目为例拿到后按下面的步骤执行# 1 使用虚拟环境项目里已经有 venv 目录就激活没有就新建 python -m venv venv source venv/bin/activate # 2 安装依赖 pip install -r requirements.txt # 3 如果数据库文件比如 db.sqlite3没压缩直接放项目根目录如果有SQL脚本则需要先建库再导入 python manage.py migrate # 4 创建管理员账号 python manage.py createsuperuser # 5 启动开发服务器 python manage.py runserver这里有个常见误区很多新手以为拿到了别人项目里的db.sqlite3直接就能用。实际上如果你的Django版本和对方不一致或者对方迁移文件不完整数据库表结构可能对不上。最好的做法是先跑migrate把空库结构建出来再通过Admin后台录入数据或者用fixture文件导入测试数据。数据库文件是SQLite时只要文件完整放到根目录通常就能直接用。换成MySQL或PostgreSQL时需要在settings.py里修改数据库配置并且提前创建好数据库。我建议项目里同时提供一份SQL导出脚本方便使用者通过Navicat或命令行工具导入。4.2 高频报错与排查实录运行这类Django项目时下面几个问题出现频率最高我整理成表格方便对照排查报错信息主要原因解决方案CSRF verification failed表单模板中缺少{% csrf_token %}在form标签内部加{% csrf_token %}No such table: dormitory_student迁移未执行运行python manage.py makemigrations再运行migrateOperationalError: no such column数据库表结构和模型不一致检查迁移文件必要时用makemigrations重新生成迁移NameError: name xxx is not defined视图里使用了未导入的模型检查模型导入语句AttributeError: Dormitory object has no attribute student_set外键related_name设置问题检查related_name是否正确或者通过dormitory.student_set调用反向关系staticfiles 404异常DEBUGFalse时未收集静态文件运行collectstatic并配置STATIC_ROOT和STATIC_URL时间差了8小时时区配置不对settings.py里设置LANGUAGE_CODEzh-hansTIME_ZONEAsia/ShanghaiUSE_TZFalsedatabase is lockedSQLite并发写入限制开发环境可接受生产环境切换MySQL或PostgreSQLCSRF问题是我见过最多的。Django默认开启CSRF中间件只要模板里的form没有加csrf_token提交必报403。新手容易在写API或者搜索时看到“CSRF verification failed”就直接禁用中间件这是不推荐的。正确做法是在模板中加上模板标签既安全又省事。还有一个特别容易踩的坑是migrate冲突。假设你修改了某个model字段运行makemigrations后生成了迁移文件但后来发现写错了手动把迁移文件删了重新makemigrations时会提示“No changes detected”。这是因为Django的记录在django_migrations表里。我一般会先到数据库里把对应迁移记录删除再重新生成或者直接删库重建。开发阶段数据不重要删库重建最干净。4.3 生产环境部署要点如果这个系统要真正上线用光靠python manage.py runserver是不行的。runserver自带的是开发服务器性能低、安全性差而且并发能力很弱。我在部署时用的是nginx加gunicorn加supervisor的组合下面说一下关键步骤。首先安装gunicorn并启动应用pip install gunicorn gunicorn config.wsgi:application --bind 0.0.0.0:8000 --workers 3然后修改settings.py里的一些生产配置DEBUG False ALLOWED_HOSTS [your-domain.com, ip地址] STATIC_ROOT BASE_DIR / staticfiles MEDIA_ROOT BASE_DIR / media MEDIA_URL /media/接着收集静态文件否则Admin后台样式全丢python manage.py collectstatic最后用supervisor守护gunicorn进程保证服务器重启后应用能自动拉起。nginx反向代理配置里把80/443端口的请求转发到8000端口同时负责静态文件和媒体文件的处理。数据库方面如果项目从SQLite切换到MySQL需要安装驱动并修改配置DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: dormitory_db, USER: dorm_user, PASSWORD: your_password, HOST: 127.0.0.1, PORT: 3306, OPTIONS: { charset: utf8mb4, }, } }MySQL记得建库时指定utf8mb4否则中文数据存进去容易出现乱码问题。部署上线之前还有一个非常容易被忽略的部分备份。SQLite备份直接复制db.sqlite3文件就行但要注意服务运行期间不要直接复制最好先停服务或者使用SQLite的在线备份API。MySQL部署的话用mysqldump做定时任务脚本每天导出一次保留最近七天的备份即可。很多课程设计项目都是因为没做备份数据丢失后无从恢复真的很可惜。5. 从实战中总结的经验这个项目做完之后我最大的体会是宿舍管理系统的难点不在技术选型而在于把业务规则用数据模型和代码表达清楚。比如满员判断、性别匹配、历史记录这些规则如果不在一开始就想明白后面写代码一定会东补西补。关于ORM使用我强烈建议养成调试时观察SQL的习惯。Django的query日志或者django-debug-toolbar都能让你看到每次ORM操作背后的SQL语句。我在优化列表页时就是通过这个工具发现了N1查询问题加了select_related之后页面响应时间肉眼可见地变快。关于数据库设计不要急着堆表。先画出核心业务对象的字段和关系再问自己几个问题删除某个对象时关联数据应该怎么办查询某个列表时最常用的筛选条件是什么有没有需要保留的历史流水这些问题想清楚表结构基本不会有大改动。最后再分享一个小技巧开发阶段一定要学会使用Django的Admin后台。它不仅是管理页面更是验证模型设计是否合理的最快方式。你注册好模型进入Admin看一眼列表页和详情页字段显示是否清晰、筛选是否好用、关联数据是否直观一目了然。大部分设计问题在这个阶段就能暴露出来比等到做前端页面再返工高效得多。宿舍管理系统这种体量的项目用Django做一遍能把Web开发的整个流程从头到尾打通值得花时间认真做。