1. 一个普普通通的课程作业我为什么加了这么多戏事情是这样的上一学期某门软件工程课带课老师布置了一个结课项目题目就一句话——“课堂的作业”要求我们独立实现一个课堂作业管理系统两周期限最后要现场演示。我拿到题目的时候第一反应是这题太常见了网上随便一搜能搜到一堆学生信息管理系统的代码无非就是增删改查、登录注册那一套。但真正动手之后我发现正是因为题目看着简单反而最容易翻车。老师虽然没有细说功能边界但演示时要考察的思路无非这么几点学生能不能上传作业文件、老师能不能查看和批改、提交有没有截止时间控制、最终分数能不能被学生看到。这四条是一条完整的作业闭环缺一个都显得这个系统“没做完”。我最后交付的是一个用 Flask 做后端、MySQL 存数据、Bootstrap 做前端的小型 Web 系统代码量不算大大概三千行左右但里边涉及到的上传校验、权限分层、状态流转和若干次“上线前差点崩了”的排障我觉得比代码本身更值得拿出来说说。这篇文章我会尽量还原我自己从读题到做设计再到踩坑修复的整个过程包括数据库表怎么建、角色权限怎么切、文件上传为什么会出各种诡异问题以及几个我改了三遍才彻底想明白的设计点。如果你也正在做类似的课设或者刚接触 Web 开发想找一个完整的练手项目应该能从中找到不少可以直接抄作业的思路。当然这不是什么大厂级的高并发系统我只是想分享一个“认真把一个课堂作业当产品做”的经历里面所有的功能设计和选型思路都对得起这个规模的项目。下面我从最初那四行需求开始讲起。1.1 原始需求其实只有四行字老师给的题目描述非常简洁大致内容如下实现一个课堂作业管理系统支持学生提交作业、教师查看与批改作业。要求作业有截止时间学生只能看到自己的成绩和评语。技术栈不限两周后演示。就这么几句话。说实话这种需求拿来直接开写一周就能写出一个“能跑”的版本但能不能扛得住演示时的追问就是另一码事了。老师的演示提问一向很刁钻比如“如果学生过了截止时间还能上传怎么办”、“助教能不能替老师批改”、“成绩算错了怎么回滚”。这些问题在最初的四行需求里根本没有答案但它们恰恰是系统设计里最见功夫的地方。我当时的做法是先把问题按角色拆开对着每一个角色把“痛点”写出来然后再把痛点翻译成具体功能。学生角色的痛点很简单交作业的入口要清晰、提交完成后要能确认“我真的交上了”、过了截止时间最好能禁止提交或者明确标记为晚交。教师角色的痛点就多了要能一眼看到有哪些学生没交、批改时要能打开学生上传的文件、给分后学生能收到通知、期末要能把成绩导出来。助教角色的痛点介于两者之间需要能批改但不能删改课程配置。1.2 我给系统划定的功能边界很多同学做课设容易犯一个毛病——功能越加越多。今天想加个公告栏明天想加个站内信后天想加个班级论坛结果两周过去了核心链路反而没打磨好。我给自己定了一条硬性原则只做“作业闭环”也就是从老师布置作业、学生提交文件、助教/老师批改、到成绩反馈这一条线其余任何功能先砍掉。于是最终的功能清单锁定在下面这些登录与角色识别学生、助教、老师三种身份一个账号只属于一个角色。课程管理老师创建课程助教绑定课程学生选课。作业发布老师针对某门课程发布作业设定截止时间可附加说明。作业提交学生在截止时间前上传文件支持覆盖提交、查看历史版本。批改打分助教或老师对已提交作业打分、写评语支持打回让学生重新提交。成绩回看学生只能看自己课程下的作业得分和评语。数据导出老师可以把某门课程所有学生的成绩导出成 Excel。基础统计每门作业的提交率、平均分、未交名单。这套范围后来证明是刚好够用的。演示时老师每问一个场景系统里都有对应入口而且不会因为功能太多导致演示时迷路。有时候克制住“加一个也不难”的冲动比写代码本身更需要定力。2. 把四行需求翻译成能落地的功能清单我以为最难的环节是写代码真正动手才发现是“想清楚到底要做什么”。这里我不是在讲方法论空话而是想说一个特别实际的点课堂作业这类项目最容易翻车的地方不是技术难点而是“你以为你做了某功能但其实没做”。我先画了一张最笨的功能推导表从用户故事出发一行一行往下推推出页面和接口。比如“学生想交作业”这个故事往下拆就有这些子问题学生进入哪个页面能看到哪些未提交的作业上传后如何确认提交成功了能不能撤回重传过了截止时间界面怎么变化每一个子问题对应一个需求点这些需求点汇总成后端接口。2.1 从“学生交了作业老师能看到”倒推功能树我拿“学生交了作业老师能看到”这个最基础的闭环举例。要先让这句话成立至少需要这些部件一个学生身份登录的入口能区分当前用户是谁。一个已经布置了作业的课程也就是要有课程和作业两张表。学生要能进入作业详情页看到截止时间、作业要求。一个文件上传接口前端选择文件后能传到服务器指定目录。上传成功后要在数据库中记录谁、哪个作业、什么时间、哪个文件路径。老师端要有一个列表遍历所有学生关联到对应的提交记录。如果学生没提交列表里要显示“未交”而不是直接不显示这一行。注意最后一条这是很多初写系统的人最容易漏掉的。如果你只查 submission 表那没交作业的学生就压根不会出现在老师眼里。你得反过来从“学生与课程关系表”出发左连接提交记录才能把“未交”这个状态展示出来。这个小小的反查思路在演示时帮了我大忙因为老师第一个问题就问“你怎么知道谁没交作业”2.2 我没用原型工具就靠两张手绘图做功能清单的时候很多教程会建议你用 Axure 画原型。但我必须诚实地说对于这种两周课设画原型的时间成本可能比写代码还高。我的做法是在 A4 纸上画了两张页面草图一张是学生视角一张是老师视角。学生视角的页面流程是登录 → 课程列表 → 作业列表 → 提交页 → 提交成功反馈页。我在纸上标注了每个页面要展示什么字段比如作业列表要显示“状态”这一列状态有三种取值未开始、待提交、已提交。已提交后面还要跟一个“截止时间”防止学生不知道什么时候过期。老师视角的页面流程是登录 → 课程管理 → 布置作业 → 作业列表 → 批改页。批改页我画得很细因为这是整个系统里交互最重的一页。它需要左侧是学生提交列表右侧是预览区和评语输入区老师要能一边看文件内容一边打分。这个“一页内完成查看打分”的设计直接决定了后期代码怎么写也决定了演示时老师会不会觉得好用。画完纸之后我又做了个特别无聊但特别有用的事把每张图里的按钮和跳转关系列成一个表比如“提交作业按钮 → 后端 /api/submit → 数据库 insert submission → 跳回作业列表并刷新状态”。这个表后来就成了接口设计文档写代码时基本不需要动脑想路由照着表填就行。3. 技术选型我不追新只选一周内能跑通的组合每年的新框架和新工具都层出不穷但课堂作业场景里最要紧的不是技术够不够新而是你能否在有限时间内独立把它跑通并讲清楚。我最后选了 Flask MySQL Bootstrap这个组合可能在很多人眼里有点“老气”但我现在回头看这是当时正确率最高的选择。有的人会说都什么时代了还用 Flask怎么不用 Spring Boot我承认 Spring Boot 功能确实很全但对于一个集中精力写两周的课设来说Spring Boot 的配置成本、依赖管理成本、还有你在演示现场被问到“这个注解是什么原理”的答不上来风险都明显更高。Flask 的核心逻辑非常直白路由就是函数请求进来调用函数返回模板或 JSON。这个心智负担几乎为零我可以把全部精力放在业务逻辑本身。3.1 后端为什么用 Flask 而不是 Spring Boot我不是说 Spring Boot 不好只是它不适合当时的我。当时我的需求是快速迭代、路由直觉化、数据库操作直接可控。Flask 配 SQLAlchemy 以后ORM 的操作方式非常接近写 SQL 的直觉Person.query.filter_by(course_idxxx).all() 这种写法基本就是把查询条件翻译成英文。而且 Flask 的模块化很简单按蓝图拆分后auth、course、homework、submission 各占一个包目录结构清清楚楚。还有一个很现实的原因课设演示时老师可能会让你现场改代码。Flask 应用的代码改动可以立刻在开发服务器上生效调试模式下报错信息直接展示在浏览器里排查问题的链路非常短。这种“改完就刷新看结果”的反馈速度在两周开发周期里能节省大量时间。3.2 前端为什么不折腾 SPA我也考虑过前端用 Vue写个前后端分离的单页应用这样显得技术含量更高。但冷静算了一笔账前后端分离意味着我要同时维护两套工程还要处理跨域、Token 认证、接口联调这些额外复杂度。对于一个演示为主的课设来说收益低得可怜。最后前端是 Jinja2 模板 Bootstrap 少量原生 JavaScript。Jinja2 可以直接在 HTML 里渲染后端传来的数据不用写一堆 fetch 代码。Bootstrap 提供的表单样式和表格样式基本够用我自己只需要写很少量的 CSS 来调整布局。原生 JS 只用来做两件事提交前的文件类型检查、以及后台轮询批改结果其实这个也没有必要后来改成了同步刷新。这个组合让我一个人干两个人的活还能干完这才是最重要的。有一个细节值得一说我并没有用 Flask-WTF 那套表单扩展而是直接用 HTML 里的 form 和 input 标签手动提交。因为课设里的表单数量有限手动处理反而能精确控制每个字段的名字和校验逻辑不会被框架的抽象层牵着走。这个选择让我在排查文件上传 bug 时少绕了很多弯。4. 数据库设计六张表怎么牵起来以及我改了三遍的字段数据库设计是课设里最容易被轻视、也最容易返工的部分。很多同学上手就建一张“作业表”里面塞上学生姓名、课程名、文件名、分数很快就会发现这表根本没法扩展。如果两个老师教同一门课怎么办如果一个学生选了两次同一门课怎么办如果作业被打回重新提交原来的分数是保留还是覆盖我最终的数据库一共六张表用户表 users、课程表 courses、学生选课关联表 course_students、教师授课关联表 course_teachers、作业表 homeworks、提交记录表 submissions。没有单独建分数表因为一份提交记录天然对应一次批改后的分数分数字段直接放在 submissions 里即可。评语字段也放在同一行不必为一条评语单独开一张表。4.1 每张表的核心字段和它们的关系users 表是最基础的一张字段有 id、username、password_hash、role。password_hash 用的是 Werkzeug 自带的 generate_password_hash存的是哈希值而不是明文密码这一点在演示时老师一定会看数据库结构看到明文密码简直是低级错误。role 字段只有三个取值student、assistant、teacher。courses 表字段有 id、name、description、semester。这里我一开始没有加 semester 字段后来意识到一个问题同一门课可能每个学期都会开如果只按课程名关联作业跨学期数据会混在一起。加一个“学期”字段才能保证查询某门课某学期的作业时不会串。homeworks 表是作业定义字段有 id、course_id、title、description、deadline。deadline 我用的是 DATETIME 类型这里有两个细节一是必须带时区概念二是前端展示时要转成用户本地时间。这个细节我在第七节会专门展开讲一次事故。submissions 表是整个系统的核心字段有 id、homework_id、student_id、file_path、file_name、file_size、status、score、comment、submitted_at。其中 status 字段的取值我调整过三次这一点值得详细讲。4.2 状态字段的设计别用布尔值表达一切状态我第一版设计里submissions 表只用了两个状态submitted 和 graded用一个名为 is_graded 的布尔值来表示。结果写到一半就发现不够了。因为老师可能会把作业打回让学生重新提交这时候这条提交记录既不是“待批改”也不是“已批改”而是一种“需要学生重新操作”的状态。我又加了一个布尔值 is_returned结果布尔值越来越多每次判断状态都要写 if submitted and not graded and not returned代码越来越乱。最后我把这两种布尔值删掉换成一个叫 status 的字符串字段submitted学生已上传等待批改。graded已批改分数已出。returned已批改但被打回学生需要重新提交。resubmitted学生针对打回后的作业重新提交等待新一轮批改。这个状态枚举看起来毫不起眼但它直接让批改页的逻辑清晰了老师看到 submitted 的记录可以打分看到 resubmitted 的记录可以重新打分看到 graded 的记录可以再次修改分数但会有提示。一个字符串枚举替代三个布尔值复杂性降了一个量级。后来演示时老师问“作业打回之后还能再交吗”我当场演示了一遍这个状态流转效果非常好。4.3 软删除到底加不加一个 deleted_at 字段还有一个设计我在网上看了很多帖子才下定决心。要不要在最核心的 submissions 表上做软删除也就是说删除一条提交记录时不真正 delete 那行而是标记一个 deleted_at 时间戳查询时统一过滤掉。我最终的答案是主表不加只在一个“提交历史”表里做。原因很简单软删除会污染所有查询逻辑每一个 SELECT 后面都要跟着 AND deleted_at IS NULL一旦漏了统计数字就会出错。而课上作业场景里删除提交记录的操作极少真出现“学生提交错了文件想删除”这种需求更好的方案是保留历史版本而不是物理删除。所以我另加了一张 submissions_history 表每次学生上传新文件时把旧记录复制一份到历史表主表只保留最新版本。这样老师可以看到一个学生提交过几版文件每一版是什么时候传的。这个“历史版本”设计算是整个项目里最超出课设要求的功能但在演示时反而成了亮点。5. 三种角色的权限边界学生、助教、老师怎么各管一段权限控制是这种多人系统的灵魂。我第一版完全没有做权限任何登录用户只要知道路径就能访问批改页面后来用一分钟时间演示了什么叫做“灾难”。补权限的时候我认真想了两层第一层是角色权限第二层是数据范围权限。这两层缺一个都不行。角色权限很好理解学生不能进批改页老师不能提交作业助教可以批改但不能发布作业。数据范围权限则微妙得多某个助教可能只协助一门课他应该只能批改这门课的作业不能看到同一系统里其他课程的提交记录。如果只校验角色不校验数据范围助教只要自己拼一个参数就能越权看其他课程的学生数据。5.1 用装饰器统一做角色校验Flask 里实现角色校验最顺手的工具是装饰器。我写了一个 require_role 的装饰器放在每个路由函数上方传入允许的角色列表。核心代码大约长这样from functools import wraps from flask import session, abort def require_role(*roles): def decorator(f): wraps(f) def wrapper(*args, **kwargs): if role not in session: abort(401) if session[role] not in roles: abort(403) return f(*args, **kwargs) return wrapper return decorator使用方法就是在路由上加一行require_role(teacher, assistant)。这样如果学生直接访问批改 URL会收到 403 页面而不是看到一个可以随便输入的批改表单。这个“先拒绝再验证”的顺序很重要一定要先判断是否登录再判断角色是否在允许列表中顺序反了可能会出现未登录用户直接触发 403 的边界问题。但是装饰器只能解决“角色对不对”的问题解决不了“这个助教有没有权处理这门课”的问题。所以我紧接着写了一个更细的检查函数在进入批改页之前先用当前用户 id 去 course_teachers 表查是否存在这条关联记录如果不存在直接返回“无权访问该课程”。这个检查不能省更不能合并到装饰器里因为装饰器无法知道后面路由参数里的 course_id 具体是什么。5.2 水平越权最容易被忽略的漏洞我记得自己刚写完权限装饰器时挺得意觉得这波稳了。结果一个朋友提醒我“你试过用学生账号直接改 URL 里的 submission_id 去看别人的作业吗”我试了一下差点从椅子上弹起来。批改和查看成绩这类接口如果只校验登录状态任何人都可以遍历 id 看到别的学生的提交文件。这就是典型的水平越权。修复方式是在每一个涉及具体资源的查询前先验证当前用户与资源之间的归属关系。比如学生查看成绩时查询里必须带上 WHERE student_id 当前用户 id而不是只根据 submission_id 去查老师批改时必须确认这门课的作业确实属于当前老师的授课范围。这个逻辑我散落在各个路由里虽然写起来有点啰嗦但它才是权限控制真正见效的地方。顺带说一下我在 session 里存的是用户 id 和角色没有存用户名。因为查询时需要频繁根据用户 id 关联查询session 里存 id 效率最高。用户名在模板层再通过关联查询取出来即可两者各司其职不要混在一起。6. 提交与批改链路每个环节都埋着意想不到的坑系统最核心的业务闭环就是“学生提交、老师批改”。这条链路初看只需四个字“上传文件”实际写起来涉及的细节多到让人抓狂。文件上传、大小校验、类型黑白名单、文件名处理、截止时间判断、重复提交限制……我这里挑几个特别值得展开讲讲的处理方式。6.1 文件上传后缀白名单只能算及格线我最初的文件上传校验只判断了后缀名比如只允许 .pdf、.zip、.docx、.py 这些。但很快就发现了问题一个叫“xxx.pdf”的 HTML 文件同样能通过后缀判断如果老师端直接预览这个文件浏览器会解析其中的脚本代码这就是典型的存储型 XSS 漏洞。后来我做的三层校验第一层是前端 JS 校验后缀目的是给用户即时反馈比如选了一个 .exe 文件直接弹提示“不支持的文件类型”第二层是后端再次校验后缀和 MIME 类型MIME 类型通过 request.files 里的 mimetype 字段读取第三层是文件存储时统一重命名不用用户原始文件名而是用 uuid 加上安全后缀保存。这样即使用户上传了一个伪装的文件存储层的文件名也是我控制的不会被浏览器按原来的类型解析。文件大小限制也必须有。我一开始没有设置任何大小限制直到有个同学上传了一个 1.2GB 的视频文件服务器磁盘瞬间告警。后来我加了两个限制一是 Flask 的配置项 MAX_CONTENT_LENGTH 设为 50MB超过直接返回 413二是在上传代码里再用 os.path.getsize 检查一次文件实际大小双保险。50MB 这个值也参考了主流网盘的作业上传限制正常写代码作业和 PDF 作业都远远不会超。6.2 截止时间判断前端校验不是校验这是我在课设里学到的刻骨铭心一课。第一版我做截止时间校验时在提交按钮上写了段 JS如果当前时间晚于 deadline按钮就变灰禁用。当时觉得这个设计很巧妙直到我用开发者工具把按钮重新启用、绕过页面直接调用上传接口顺利提交了一个截止时间之后的作业。从那以后我彻底明白了前端的任何判断都只是用户体验的一部分真正的规则必须落在服务端。服务端校验的逻辑是读取 homeworks 表里的 deadline和当前服务器时间做比较如果当前时间大于 deadline直接返回“已过截止时间无法提交”并且不执行任何写数据库操作。这个校验写在 Flask 路由里紧跟在登录校验之后是所有上传逻辑的前置条件。6.3 批改页的细节可预览、可打分、可来回改批改页我花了最多时间去打磨。它的核心是左侧学生列表、右侧评语和分数输入区。我在左侧列表里用状态标记区分不同提交情况绿色表示已批改、黄色表示待批改、灰色表示未提交。点击某个学生后右侧刷新出该学生的文件名、上传时间、文件预览链接下方是分数输入框和评语文本框。批改动作本身只是更新 submissions 表的 status、score、comment 三个字段。但我额外做了一步当分数从有值改成另一个值时前端会弹一个确认框“该作业已有成绩确定要修改吗”。这个确认框不是为了为难老师而是为了减少误操作。课堂作业场景下学生的成绩直接关系到期末总评一次手滑把 85 改成 8 是实实在在可能发生的事。打回重交的逻辑和批改不同。打回时只更新 status 为 returned清空 score保留 comment 作为“打回原因”。学生看到 status 变成 returned 后可以重新上传文件此时状态回到 resubmitted老师再次进入批改页时看到的就是新版本的附件和文件时间。历史版本在 submissions_history 表里随时可查家长找不到“老师是不是看错版了”的争辩机会。7. 上线前被自己坑到的三个真实事故照理说技术方案想得再周全实际写起来也一定会出幺蛾子。我这次项目在演示前一周密集踩了三个坑每一个都属于“不遇到根本想不到”的类型。我把完整的排查链路写出来不直接给答案因为复现问题的过程本身就很有价值。7.1 事故一中文文件名上传后文件变成了一串乱码现象学生提交一份名为“机器学习第一次作业.pdf”的文件老师在后台点击预览浏览器地址栏里 show_file/xxx 后面跟着一串百分号编码打开页面直接 404。我一开始怀疑是路由问题但在本地试了半天都没复现因为我的开发环境全是英文文件名。排查链路先在服务器上用命令行手动上传一个中文文件名发现文件确实能写进磁盘但文件名变成了类似 b\xe6\x9c\xba\xe5\x99\xa8... 这样的 bytes 字符串。这时我意识到问题出在上传接口里的文件名保存逻辑它直接用了 filename 字段的原始字节没有做解码和规范化。修复方式是在保存文件名时强制使用 secure_filename 函数规范化并且把附件存储路径里的文件名统一改成 uuid不再用用户原文件名。这样既避免了中文乱码也顺带消除了路径穿越的隐患。这个事故让我明白一个道理任何用户可控的字符串都不应该直接拼进文件系统路径。7.2 事故二一个上传的 HTML 文件差点让全班浏览器中招现象内部测试时发现学生上传一个 .html 文件后老师只要在批改页点击预览浏览器就会执行文件里的 JavaScript 脚本。这个脚本如果写成恶意代码就能偷取同域名下的 session 信息。一开始我完全没把附件预览当回事以为文件放在 /uploads 目录下就不会被执行但 Flask 的静态文件路由会按扩展名自动设置 Content-Type.html 文件会被浏览器当成网页渲染。修复思路第一层后端过滤上传扩展名不允许 .html、.svg、.js 这类容易被执行的格式。第二层在返回文件时强制设置 Content-Disposition: attachment让浏览器永远走“下载”而不是“打开”的路径。第三层也是我后来补的一层在 Nginx 层面对 /uploads 目录关闭脚本执行权限所有静态文件一律当作普通二进制流输出。这个三层防护里任何一层单独都能挡住一部分攻击合在一起才算是真正安心。7.3 事故三Excel 导出里的成绩列数值全乱了现象老师导出某门课成绩时Excel 里“成绩”列显示为 85.000001 这种诡异数字而且有的行是文本型数字有的行是数值型排序时会把 99 排到 10 前面。排查链路我先在数据库里直接查数据发现存的分数字段类型是 FLOAT。MySQL 的 FLOAT 在存储 85.3 这种小数时本身就有精度误差查询时显示正常但导出成 Excel 后精度问题就暴露出来了。这让我意识到与金钱、成绩、数量有关的字段永远应该用整数或 DECIMAL绝不能用 FLOAT。我最终把 score 字段从 FLOAT(5,2) 改成了 DECIMAL(5,1)只保留一位小数同时把导出逻辑里的数值全部转成字符串并且统一设置为文本格式。这一改问题彻底消失。事后想到更深层的原因分数本质上是离散的等级不是连续测量值用 FLOAT 本身就是概念错误。一个字段的物理类型应该由它的业务含义决定而不是“看起来可能带小数”就选浮点。这条教训后来在我写任何项目的数据库设计时都起了作用。8. 演示那天的结果以及这段经历真正教会我的事演示当天其实没有出现什么戏剧性的高潮。老师坐在电脑前按他的提问清单一个一个点布置作业、修改截止时间、学生提交、助教批改、打回、重新提交、导出成绩。每个操作都在一两步内完成了整个过程十几分钟就结束。老师最后的评价我记得很清楚“这个项目功能完成度不错但没有炫技所有设计都是为了业务闭环服务这是对的。”说实话听到这个评价比拿高分还让我高兴。因为“没有炫技”这四个字恰好是我这次课设里最想做到的事情。我没有用任何复杂的架构、新潮的框架也没有刻意堆砌高深术语只是老老实实地把“学生交作业、老师看作业”这几件事做扎实了。技术选型上的朴素、状态设计的反复推敲、权限系统的层层补漏每一环都不是为了“看起来厉害”而是在回答具体的业务问题。对我个人来说这个课堂作业最大的收获不是那些外键和装饰器而是我学会了一种拆解问题的方式拿到一个模糊的题目先不要急着写代码而是把它翻译成“有哪些人要用、每个人要做什么、做完之后要给谁看”。当这三个问题想清楚以后数据库表、路由、页面其实都呼之欲出。这种“从需求倒推设计”的习惯我后来在做其他项目时一直在用。如果你现在也在做类似的课设我想说两件事。第一不要觉得“课堂作业”就只是应付差事把它当成一个完整产品来做你会收获远远超出分数的经验。第二遇到坑别怕今天踩过的每一个诡异问题都是你将来面对真实系统时的盾牌。当然最后一个小提醒如果时间允许一定要把你的数据库备份脚本写好演示前五分钟把整个库 dump 一遍这个习惯能在多少生死时刻救你一命——相信我我就靠它救过一次。