基于Python的校园体育器材租赁系统：Django+Flask混合架构实战

1. 为什么校园体育器材租赁系统需要单独开发一套

很多人觉得器材管理不就是个Excel表的事吗？真正去体育器材室借过几次东西，你就不会这么想了。高校里的体育器材租赁业务，表面上是"登记—借用—归还"三个动作，实际上牵扯到的细节远比想象中复杂。

以某高校的实际场景为例：体育课高峰期，两个班同时上课，一节课要借出篮球、排球、羽毛球拍等上百件器材；课外活动时段，学生个人借用和社团批量借用混在一起；遇到运动会，器材出库入库量直接翻几倍。传统的人工登记方式，器材室老师在忙的时候根本来不及逐一核对，经常出现"账上显示有球，架子上找不到""学生明明还了，记录里却是未归还"这类扯皮事。更重要的是，器材损耗和赔偿管理几乎全靠老师记忆，期末盘点时账实不符是常态。

做这个基于Python的校园体育器材租赁管理系统，核心目标就是把这些乱象梳理清楚：学生通过系统预约和借用器材，管理员在后台统一处理借用审批、归还登记、损坏赔偿，所有的库存变动、借还记录、损耗状态都能实时追踪。整个项目涉及的角色有三类——学生用户、器材室管理员、系统超级管理员，对应的权限和操作完全不同。这套系统跑起来之后，器材室老师的日常工作从"人工对账"变成了"系统审批"，高峰期处理效率能提升一大截。

对于想学习Python Web开发的读者来说，这个项目的价值在于它同时用到了Django和Flask两种主流框架。Django负责后台管理端和核心业务逻辑，Flask负责对外API接口和轻量级查询服务。一套系统里能体验到两种框架各自的定位和分工，比单学一个框架更能理解"框架选型"这件事的实际意义。

2. 技术选型：Django和Flask各自负责什么

2.1 为什么不让一个框架从头管到尾

先说我踩过的一次选型弯路。最早我打算全站用Django实现，理由很简单：Django自带Admin后台、ORM、认证系统，开发效率确实高。但做到移动端对接的时候就难受了——虽然Django也能写API，但为了接口文档和请求校验，我得额外装DRF，为了处理跨域又得配中间件，为了轻量权限还得自己写装饰器。一套折腾下来，接口层变得又重又绕。

后来我在另一个项目里尝到了用Flask写独立API服务的甜头：路由简单、请求上下文清晰、配合蓝图模块化后代码结构一目了然。于是这个校园体育器材租赁系统我做了个混合架构：

• Django端：承载后台管理系统、数据库模型、用户认证、器材库存管理、借还审批流。这部分是数据密集型操作，Django的ORM和管理后台能省掉大量重复劳动。
• Flask端：承载前端小程序/网页端需要调用的API接口，比如器材列表查询、个人借用记录、预约提交、库存余量实时查询。这些接口的特点是"读多写少、响应要快"，Flask轻量得刚刚好。

为什么这么分？因为后台管理行为和管理员操作绑得很紧，需要完善的事务处理和权限控制，这是Django的强项；而前端接口要暴露给多种客户端调用，需要简洁的请求处理、灵活的响应格式、低耦合的路由分发，这是Flask的舒适区。说白了，一个项目里不同模块对框架特性的诉求不一样，没必要用一把锤子砸所有钉子。

2.2 两端的模块划分与数据交互方式

两个服务之间靠什么通信？直接操作同一个数据库，还是通过HTTP调用？我最终选用的是MySQL 8.0作为共享数据库，Django负责建表、迁移和数据写操作，Flask端做查询时也走同一个库，但只读不写。这么设计的原因有两个：一是避免双写造成的数据一致性问题；二是Django的ORM迁移机制是最省心的建表方式，Flask端不需要维护自己的模型层，直接执行SQL查询即可。

核心模块划分如下：

为了拿到可用的Token，Django在登录成功后生成一个签名凭证，Flask端在收到请求时通过一个共享的密钥来校验。这个校验逻辑写在Flask的装饰器里，每个需要登录的接口都加上，代码量很少，却很实用。

3. 数据模型设计：器材、用户、订单三张核心表怎么建

3.1 用户模型：三种角色的权限区分

校园场景下的用户模型和普通电商系统不太一样。学生、教师、管理员对器材的使用场景不同，权限边界也不同。我建了一张UserProfile表，和Django内置的User表通过一对一关联扩展字段：

from django.db import models from django.contrib.auth.models import User class UserProfile(models.Model): USER_TYPE_CHOICES = ( ('student', '学生'), ('teacher', '教师'), ('admin', '管理员'), ) user = models.OneToOneField(User, on_delete=models.CASCADE, related_name='profile') user_type = models.CharField(max_length=20, choices=USER_TYPE_CHOICES, default='student') student_id = models.CharField(max_length=20, blank=True, null=True, verbose_name='学号') department = models.CharField(max_length=50, blank=True, null=True, verbose_name='学院/部门') phone = models.CharField(max_length=11, blank=True, null=True, verbose_name='联系电话') credit_score = models.IntegerField(default=100, verbose_name='信用分') def __str__(self): return f'{self.user.username} - {self.get_user_type_display()}'

信用分这个字段是实际运营中很关键的设计。学生逾期不还或者器材损坏，信用分会扣减，低于某个阈值（比如60分）时禁止借用。这比单纯靠罚款更柔性，也更容易被学生接受。管理员端在审批借用时能看到申请人的信用分，作为是否批准的依据。

3.2 器材模型：唯一编号和状态流转

器材管理的难点在于"同一类器材有很多件，每一件又必须能追踪"。所以器材表我设计了两个层次：

class EquipmentCategory(models.Model): """器材类别表：篮球、排球、羽毛球拍等""" name = models.CharField(max_length=50, unique=True, verbose_name='器材类别') total_stock = models.IntegerField(default=0, verbose_name='总库存') available_stock = models.IntegerField(default=0, verbose_name='可借库存') daily_rental_fee = models.DecimalField(max_digits=6, decimal_places=2, default=0, verbose_name='日租金/元') deposit = models.DecimalField(max_digits=6, decimal_places=2, default=0, verbose_name='押金/元') class EquipmentItem(models.Model): """器材实例表：每件具体器材""" STATUS_CHOICES = ( ('available', '可借用'), ('borrowed', '已借出'), ('maintenance', '维修中'), ('damaged', '已损坏'), ('discarded', '已报废'), ) category = models.ForeignKey(EquipmentCategory, on_delete=models.CASCADE, related_name='items') equipment_code = models.CharField(max_length=30, unique=True, verbose_name='器材编号') location = models.CharField(max_length=50, blank=True, null=True, verbose_name='存放位置') status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='available') purchase_date = models.DateField(null=True, blank=True, verbose_name='购买日期')

为什么要拆成两张表？因为类别表管的是"这一类器材有多少可借"，实例表管的是"具体哪一件在谁手里"。很多管理系统只做到类别层面，结果一查"篮球还了5个"，但不知道还的是哪几个，真出了问题根本追溯不了。拆开之后，每一件器材都有自己从入库到报废的完整生命周期。

3.3 订单模型：预约、借用、归还一体的状态机

订单是整个系统里最核心的表，它承载了从预约到最终归还的全流程状态流转：

class RentalOrder(models.Model): ORDER_STATUS = ( ('pending', '待审批'), ('approved', '已批准'), ('borrowed', '已借出'), ('returned', '已归还'), ('overdue', '已超期'), ('cancelled', '已取消'), ) order_no = models.CharField(max_length=30, unique=True, verbose_name='订单号') user = models.ForeignKey(User, on_delete=models.CASCADE, related_name='rental_orders') category = models.ForeignKey(EquipmentCategory, on_delete=models.CASCADE, verbose_name='器材类别') items = models.ManyToManyField(EquipmentItem, blank=True, verbose_name='实际借出的器材') quantity = models.IntegerField(default=1, verbose_name='借用数量') start_time = models.DateTimeField(verbose_name='借用开始时间') end_time = models.DateTimeField(verbose_name='预计归还时间') actual_return_time = models.DateTimeField(null=True, blank=True, verbose_name='实际归还时间') status = models.CharField(max_length=20, choices=ORDER_STATUS, default='pending') purpose = models.CharField(max_length=100, blank=True, null=True, verbose_name='借用用途') create_time = models.DateTimeField(auto_now_add=True)

状态机的流转逻辑是这样的：学生提交预约 →pending；管理员审批通过 →approved；学生到器材室扫码/报号领取 →borrowed；归还时管理员确认器材状态并收回 →returned；如果超过end_time未归还，系统定时任务自动把状态标为overdue，同时扣信用分。整个过程每一步都有时间戳记录，账目可追溯。

实际做的时候，很多同学容易漏掉items和category的双重关联。光记录"借了3个篮球"，却不记录具体拿了哪几件，后面库存核对和损坏赔偿就会对不上。我建议宁可订单表复杂一点，也要把"预约的是数量"和"实际领走的是哪些具体器材"分开记录。

4. 核心业务流程的实现：从提交预约到归还入库

4.1 预约与审批：Django后台的事务处理

预约流程直接写在前端页面里，学生选择器材类别、填写借用时间段和用途，提交后生成一条pending状态的订单。审批是管理员在Django Admin后台完成的。这里要注意一个关键点：审批通过的同时，必须锁定库存。

from django.db import transaction from django.utils import timezone @transaction.atomic def approve_order(order_id): order = RentalOrder.objects.select_for_update().get(pk=order_id) if order.status != 'pending': raise ValueError('该订单已不在待审批状态') category = order.category if category.available_stock < order.quantity: raise ValueError('库存不足，无法批准') # 锁定库存 category.available_stock -= order.quantity category.save() order.status = 'approved' order.save() return order

transaction.atomic+select_for_update是这套逻辑里最核心的两个点。select_for_update会对这条订单记录加行级锁，防止两个管理员同时审批同一单导致库存扣重复；transaction.atomic保证扣库存和改状态要么都成功，要么都失败。没有这两层保护，高并发下一定会出问题。

同样地，学生取消审批通过的订单，也要在事务里把库存加回来。这个补偿逻辑别忘了，不然会出现"订单取消了，库存却永久少了"的bug。

4.2 借用与归还：管理员扫码核验

我实际做的时候，给每件器材的编号做成了条形码贴纸，学生领器材时管理员扫一下条形码，系统自动把对应的EquipmentItem.status从available改成borrowed，同时关联到当前订单。归还时再扫一次，状态改回available，订单状态改为returned，写入实际归还时间。

为什么要用扫码而不是手动输入编号？手动输入在高峰期根本来不及，而且容易输错。扫码器本质上是键盘输入设备，扫一下等于输入一串编号加回车，代码里只需要写一个输入框监听回车事件就行，成本极低、效率极高。

归还时的破损检查必须做成强制流程。归还页面里我加了一个"器材状态确认"的选项组：正常 / 轻微磨损 / 明显损坏 / 丢失。选了后两项，会自动弹出报损单，要求上传照片并填写说明。这一步卡住了，后面赔偿核算才有依据。

4.3 超期订单的自动标记与信用分扣减

超期不能全靠管理员肉眼盯，我写了一个Django management command，配合系统计划任务每小时跑一次：

from django.core.management.base import BaseCommand from django.utils import timezone from rentals.models import RentalOrder class Command(BaseCommand): def handle(self, *args, **options): overdue_orders = RentalOrder.objects.filter( status='borrowed', end_time__lt=timezone.now() ) for order in overdue_orders: order.status = 'overdue' order.save() # 扣信用分，每超期一天扣5分 profile = order.user.profile overdue_days = (timezone.now() - order.end_time).days profile.credit_score = max(0, profile.credit_score - overdue_days * 5) profile.save() self.stdout.write(f'处理 {overdue_orders.count()} 条超期订单')

计划的执行频率我设的是每小时一次，主要考虑到超期扣分是"提醒性质"的，不需要精确到分钟。如果哪天学校觉得扣分太狠或者太轻，调整overdue_days * 5这个乘数就行。

5. Flask端API开发：给前端页面提供轻量接口

5.1 蓝图结构设计与Token校验

Flask端的项目结构我按功能拆成了蓝图，每个蓝图管一块接口：

flask_api/ ├── app.py # 主入口，注册蓝图 ├── config.py # 数据库连接、密钥配置 ├── decorators.py # 登录校验装饰器 ├── blueprints/ │ ├── auth.py # 登录/刷新Token │ ├── equipment.py # 器材列表、余量查询 │ ├── order.py # 提交预约、取消预约、我的订单 │ └── stats.py # 借用统计报表

登录校验装饰器是整个API层的看门人。Django端在用户登录成功后，用itsdangerous库签发一个带有过期时间的Token，Flask端用同一个密钥解析Token，解析成功就放行，失败就返回401。

from functools import wraps from flask import request, jsonify, current_app import itsdangerous def login_required(f): @wraps(f) def decorated_function(*args, **kwargs): token = request.headers.get('Authorization', '').replace('Bearer ', '') if not token: return jsonify({'code': 401, 'message': '未登录'}), 401 try: s = itsdangerous.TimestampSigner(current_app.config['SECRET_KEY']) user_id = s.unsign(token).decode('utf-8') request.user_id = int(user_id) except itsdangerous.BadSignature: return jsonify({'code': 401, 'message': 'Token无效或已过期'}), 401 return f(*args, **kwargs) return decorated_function

这个方案比直接用Django Session或JWT都更轻。Session需要存储会话状态，Flask端还要连Session后端；JWT要引入额外的库处理签名算法。itsdangerous本身就是Django和Flask共用的签名工具，两边都能用同一个SECRET_KEY验签，省掉不少对接成本。

5.2 器材余量查询接口：警惕N+1查询

器材列表接口是最常用的接口，前端首页要展示所有类别的名称、库存余量、租金、押金。第一版我写得很天真：

categories = EquipmentCategory.query.all() result = [] for c in categories: result.append({ 'name': c.name, 'available': c.available_stock, 'rental_fee': str(c.daily_rental_fee), 'deposit': str(c.deposit), })

数据量小的时候没问题，但一旦器材类别上百，每个类别还要关联查询实例表里的可用数量，就会产生大量SQL查询。我在实际压测时，这个接口的响应时间直接到了800毫秒以上。优化方案是只在页面初始化时查一次，然后前端做缓存，接口响应压到50毫秒以内：

categories = EquipmentCategory.query.all() # 一次性查出所有可借器材数量，避免N+1 available_counts = dict( db.session.query( EquipmentItem.category_id, func.count(EquipmentItem.id) ).filter(EquipmentItem.status == 'available') .group_by(EquipmentItem.category_id) .all() )

5.3 预约提交接口与库存校验的并发问题

预约提交这个接口，必须考虑并发场景：两个学生同时提交同一个器材类别的预约，剩余库存只有最后1件，但两个人都显示预约成功。根本原因在于"先查库存再插入订单"这两步之间有间隙。

Flask端的校验不能只做一次。我的做法是：提交预约时，先检查该时间段内该器材类别的预约占用数量 + 当前剩余库存是否足够；同时Django端在审批时再做一次终极校验。两道校验虽然冗余，但能保证前端响应快，后台数据准。前端校验失败直接返回"库存不足"，后台审批失败则事务回滚。

预约信息到达Flask后，Flask会调用Django的接口写入订单。这里Flask和Django之间我用的是HTTP调用，地址走内网IP，不走公网，省去了权限认证的麻烦。

6. 前端页面：后台管理端怎么做到好用

6.1 Django Admin的改造：不要直接用默认界面

很多人的后台就是Django Admin原样交付，功能是有了，但管理员用起来很别扭。器材室的老师不是程序员，他们需要的是"打开就能看到今天要处理哪些审批、哪些器材要归还"这种直观界面。

我的做法是给Admin自定义了首页看板。通过重写admin/index.html模板，把待办事项放到首页最上面：待审批订单数、今日应归还数量、库存不足预警、损坏待处理列表。管理员登录后第一眼就看到这些数字，点进去直接处理，不用东翻西找。

Admin列表页也别直接展示所有字段，通过list_display只展示关键信息，加上list_filter按状态筛选。不然几百条订单堆在一个页面上，找一条要滚半天。

6.2 面向普通用户的借用页面逻辑

学生端的前端页面（如果直接做成Web版）逻辑要足够简单：

1. 进入器材列表页，看到所有可借类别和实时余量
2. 点击"借用"，选择时间段（默认不超过7天），填写用途
3. 提交后显示"等待管理员审批"，审批结果通过站内消息或邮件通知
4. 审批通过后，页面上显示"请在XX时间前到器材室领取"
5. 使用完毕，到器材室归还，系统更新订单状态

前端和后端的交互全部走Flask的API。这里有个经验：预约时前端最好把归还时间限制为"当天不借、明确节假日不可预约"。学校里的实际情况是，节假日器材室基本没人值班，闭馆期间器材是不能借出的。我第一版没做这个限制，有学生预约了国庆期间的器材，结果到了时间器材室大门紧锁，订单卡在"已批准"状态等了一天，最后还得人工取消。

7. 我在实际部署和测试中遇到的几个棘手问题

7.1 器材状态和数据一致性问题

最容易出现的bug是：器材在系统中显示"可借用"，但物理位置上根本找不到。原因是某些器材被临时调去比赛或维修，没有走系统流程。后来我加了"批量状态调整"功能，管理员可以一键把一批器材标记为维修中或报废，并在备注里填写原因。同时，每个月至少做一次账实盘点，发现差异直接在系统里调整。

另一个坑是：订单关联了很多具体器材后，如果其中一件损坏，不能把整笔订单都标记为已损坏。我在订单和器材关联表里增加了return_status字段，用来单独记录每件器材的归还状态，这样一单里可以同时存在"正常归还2件、损坏1件"的情况。

7.2 Django Admin登录安全性

Django Admin是管理员的入口，默认情况下登录接口容易被暴力尝试。我加了两个简单的防护：一是登录失败5次后锁定该账号15分钟（写一个简单的失败计数，存到缓存里）；二是启用Django自带的AdminSite.site_header自定义样式的同时，把Admin后台的URL从默认的/admin/改成了一个不容易猜到的路径。这个改动成本几乎为零，但能有效挡住绝大多数批量扫描流量。

7.3 整点并发压测：库存为什么会变成负数

上线前我做过一次并发测试：50个线程同时提交预约，目标是一个库存只有30件的篮球类别。测试结果惊到了我——订单只成功8笔，但库存变成了-7。原因是Flask端的高并发请求都涌到了Django审批接口，而Django端的库存校验和扣减没有放在同一个事务里。

排查过程是这样的：先看错误日志，发现大量IntegrityError，SQL层面出现了唯一键冲突；再看数据库记录，发现有两笔订单是同一时刻写入的；最后定位到代码，审批流程里"查询库存"和"更新库存"确实是两条独立的SQL语句，中间没有加锁。修复方案就是把审批逻辑完整包进@transaction.atomic，并加上select_for_update强制锁行。改完之后重新压测，30件的库存最多成功30单，不会再多。

7.4 归还流程中的权限漏洞

我最初设计的归还接口只校验了"当前用户是否登录"，结果是任何登录用户都可以调用归还接口。如果有学生知道某笔订单的订单号，他可以手动标记别人的订单为"已归还"，造成账实不符。修复时我在归还接口增加了双重校验：不仅校验Token，还要校验order.user_id是否等于当前用户，管理员归还不受此限制。这类"水平越权"问题在开发中很容易被忽略，但做管理系统时必须从第一天就绷紧这根弦。

8. 代码组织与部署：直接照抄的可运行方案

8.1 后端整体目录结构

我最终交付的项目结构是这样的，分前后端两个服务独立部署：

django_backend/ ├── manage.py ├── config/ │ ├── settings.py # Django配置，包含数据库、Admin、日志 │ └── urls.py ├── apps/ │ ├── users/ # 用户认证与UserProfile │ ├── equipment/ # 器材类别与实例 │ ├── rental/ # 订单、审批、归还逻辑 │ └── reports/ # 统计报表接口 └── requirements.txt flask_api/ ├── app.py ├── config.py ├── decorators.py ├── blueprints/ │ ├── auth.py │ ├── equipment.py │ ├── order.py │ └── stats.py └── requirements.txt

Django端通过python manage.py runserver跑在8000端口，Flask端通过gunicorn跑在5000端口。内外网访问策略是：Django Admin只允许校园网内访问，Flask API所在的服务器同时提供对前端页面的托管，不做额外负载均衡——这个体量的系统，一台4核8G的服务器绰绰有余。

8.2 Nginx配置要点

Nginx上我们需要处理两件事：一是静态文件指向Django的static目录，二是将/api/路径的请求转发到Flask服务。配置片段的写法不再赘述，但有一个关键点：Flask接口返回的JSON里必须带Cache-Control: no-store头，否则学生端查到的器材余量可能是缓存的脏数据。

8.3 定时任务还得考虑节假日

上面的超期自动标记脚本，平时跑没问题，但寒暑假会误伤。假期里器材室闭馆，所有订单都处于"应该归还但没人还"的状态，如果自动脚本照常扣信用分，学生开学后会集体来投诉。我加了假期时间表配置：在系统设置里维护一个节假日起止日期的列表，定时任务检测到当前日期在假期内，就直接跳过处理。

这个细节看着小，但直接决定了系统能不能真正用起来。任何管理系统，脱离实际作息规则的功能都是负担。

若从这个系统继续往后做，比较自然的扩展方向是：

• 给Flask接口增加按时间段的器材热度统计，帮助学生避开借还高峰
• 把器材实例表里的条形码换成二维码，学生可以通过小程序扫码查看器材状态和来源记录
• 对接学校的统一身份认证平台，省去单独的注册流程，学号即账号

做这类校园系统最深的体会是：技术选型和代码结构固然重要，但真正决定系统能不能落地的是对业务场景的理解——什么时候闭馆、假期谁值班、损坏怎么界定、信用分怎么扣才不会引发矛盾。这些规则想清楚了，写代码只是时间问题；想不清楚，再好的架构也只是个精美的空壳。