简介：这是一套面向学校与教学管理场景的码蚁成绩管理系统源码，适合需要搭建校内成绩录入、统计与查询平台的开发者或教务人员使用。系统覆盖系统信息与单位信息设置、学期班级班主任学科管理、管理员权限角色分配，以及学生信息、考试信息与考试号生成等基础模块，并支持在线录入、表格录入和扫码枪录入成绩。统计端提供成绩列表、成绩图表与统计结果展示，包含柱形图、折线图、雷达图、箱体图、仪表图及成绩报告，还可查看学生历次成绩趋势，教师与学生分身份登录，并按职务、教研组长、班主任等控制数据权限。资源包共2000个文件，以1568个php源码为核心，辅以html页面、js脚本、css样式、json与config配置、sql数据库脚本及md说明文档，另有图片、字体等静态资源，压缩包约8.03MB。目前已有427人学习下载，可帮助读者快速理解成绩管理系统的模块划分、权限设计与统计图表实现思路。

1. 成绩管理系统的真实需求：从一张Excel表到一套可查可统的Web应用

每到期中期末，教务老师最头疼的不是考试本身，而是考完之后那堆事：成绩录入靠Excel来回传，统计靠手动拉公式，学生查询靠群里发截图。一套「码蚁成绩管理系统」要解决的正是这三个环节——录入、统计、查询——把它们从离线表格搬到线上，让数据一次写入、多方复用。这不是什么高深技术，核心就是一张成绩表加几个查询接口，但真正落地时会发现：并发录入怎么防冲突、统计口径怎么统一、查询权限怎么隔离，每一个都是坑。这篇文章面向想自己搭一套成绩管理系统的开发者，从数据模型设计讲到接口实现，再到部署上线的注意事项，每一步都给可复现的代码和参数说明。适合有基础Web开发经验、想找一个完整练手项目或内部工具方案的读者。

2. 数据模型与表结构设计：成绩录入之前先把地基打对

2.1 三张核心表撑起整个系统

成绩管理系统的数据模型不复杂，但设计不好后面全是麻烦。我一般会拆成三张核心表：学生表、课程表、成绩表。学生表存基本信息，课程表存课程元数据，成绩表是关联表，记录「谁在哪门课上考了多少分」。

先看学生表：

CREATE TABLE student ( id BIGINT PRIMARY KEY AUTO_INCREMENT, student_no VARCHAR(20) NOT NULL UNIQUE COMMENT '学号，业务主键', name VARCHAR(50) NOT NULL COMMENT '姓名', class_name VARCHAR(50) NOT NULL COMMENT '班级', created_at DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_class (class_name) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

学号用VARCHAR而不是数字类型，因为学号可能有前导零，用INT会丢掉。student_no加唯一索引，防止重复录入。class_name加普通索引，因为按班级筛选是高频操作。

课程表：

CREATE TABLE course ( id BIGINT PRIMARY KEY AUTO_INCREMENT, course_code VARCHAR(20) NOT NULL UNIQUE COMMENT '课程编号', course_name VARCHAR(100) NOT NULL COMMENT '课程名称', credit DECIMAL(3,1) NOT NULL DEFAULT 0 COMMENT '学分', semester VARCHAR(20) NOT NULL COMMENT '学期，如2024-2025-1', created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

学分用DECIMAL(3,1)而不是FLOAT，因为学分通常是0.5的倍数，浮点数会有精度问题。semester字段用字符串存学期标识，方便按学期筛选。

成绩表是核心：

CREATE TABLE score ( id BIGINT PRIMARY KEY AUTO_INCREMENT, student_id BIGINT NOT NULL, course_id BIGINT NOT NULL, score DECIMAL(5,2) COMMENT '成绩，允许NULL表示缺考', exam_type VARCHAR(20) NOT NULL DEFAULT 'final' COMMENT '考试类型', updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_student_course_type (student_id, course_id, exam_type), INDEX idx_course (course_id), FOREIGN KEY (student_id) REFERENCES student(id), FOREIGN KEY (course_id) REFERENCES course(id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

这里有几个关键决策。第一，score允许NULL，因为缺考和零分是两回事，统计时要区分。第二，唯一键是(student_id, course_id, exam_type)三列组合，意味着同一个学生同一门课的同一考试类型只能有一条记录，重复录入会触发唯一键冲突，这是防重复的第一道防线。第三，加了外键约束，虽然有些团队不推荐在生产环境用外键，但在成绩管理这种数据一致性要求高的场景，外键能省掉很多脏数据的排查时间。

2.2 成绩录入接口：批量插入与冲突处理

成绩录入最常见的场景是老师拿到一份Excel，里面是全班某门课的成绩，需要一次性导入。接口设计成批量提交，而不是一条一条调。

# Flask 示例：批量录入成绩 from flask import request, jsonify from sqlalchemy.dialects.mysql import insert from models import db, Score @app.route('/api/scores/batch', methods=['POST']) def batch_import_scores(): data = request.get_json() course_id = data.get('course_id') exam_type = data.get('exam_type', 'final') records = data.get('records', []) # [{"student_no": "2024001", "score": 87.5}, ...] if not course_id or not records: return jsonify({"code": 400, "msg": "参数缺失"}), 400 # 先查学号对应的 student_id，避免逐条查询 student_nos = [r['student_no'] for r in records] students = Student.query.filter(Student.student_no.in_(student_nos)).all() no_to_id = {s.student_no: s.id for s in students} # 检查是否有不存在的学号 missing = [no for no in student_nos if no not in no_to_id] if missing: return jsonify({"code": 400, "msg": f"以下学号不存在: {missing}"}), 400 # 构造批量插入数据 rows = [] for r in records: rows.append({ "student_id": no_to_id[r['student_no']], "course_id": course_id, "score": r.get('score'), # 允许 None "exam_type": exam_type }) # 使用 ON DUPLICATE KEY UPDATE 实现幂等写入 stmt = insert(Score).values(rows) stmt = stmt.on_duplicate_key_update( score=stmt.inserted.score, updated_at=db.func.now() ) db.session.execute(stmt) db.session.commit() return jsonify({"code": 0, "msg": "导入成功", "count": len(rows)})

这段代码的核心逻辑是：先批量查学号映射，再构造插入数据，最后用ON DUPLICATE KEY UPDATE实现「存在则更新，不存在则插入」。这样老师重复导入同一份文件不会报错，也不会产生重复记录。

参数说明：course_id和exam_type定位到具体的考试，records是成绩列表。score字段传null表示缺考。返回的count是实际处理的记录数。

注意：批量插入时如果记录数超过几千条，建议分批提交，每批500条左右，避免单条SQL过大导致执行超时。

2.3 统计口径：平均分、及格率、分数段怎么算才不翻车

成绩统计看起来简单，但口径不统一就会出问题。比如平均分，是算所有学生的平均，还是只算有成绩的？及格率的分母是全班人数还是实考人数？这些必须在接口层面定死。

我一般会提供两种统计模式：include_absent和exclude_absent，由调用方决定。

# 统计接口：平均分、及格率、分数段分布 @app.route('/api/scores/statistics', methods=['GET']) def score_statistics(): course_id = request.args.get('course_id', type=int) exam_type = request.args.get('exam_type', 'final') mode = request.args.get('mode', 'exclude_absent') # include_absent / exclude_absent # 查出该课程该考试类型的所有成绩 scores = Score.query.filter_by(course_id=course_id, exam_type=exam_type).all() if mode == 'exclude_absent': valid_scores = [s.score for s in scores if s.score is not None] else: valid_scores = [s.score if s.score is not None else 0 for s in scores] total = len(valid_scores) if total == 0: return jsonify({"code": 0, "data": {"total": 0}}) avg = sum(valid_scores) / total pass_count = sum(1 for s in valid_scores if s >= 60) pass_rate = pass_count / total # 分数段：<60, 60-69, 70-79, 80-89, 90-100 segments = {"0-59": 0, "60-69": 0, "70-79": 0, "80-89": 0, "90-100": 0} for s in valid_scores: if s < 60: segments["0-59"] += 1 elif s < 70: segments["60-69"] += 1 elif s < 80: segments["70-79"] += 1 elif s < 90: segments["80-89"] += 1 else: segments["90-100"] += 1 return jsonify({ "code": 0, "data": { "total": total, "average": round(avg, 2), "pass_rate": round(pass_rate * 100, 2), "segments": segments } })

参数说明：mode控制缺考是否计入统计。exclude_absent模式下，缺考学生不参与平均分和及格率计算；include_absent模式下，缺考按0分处理。分数段固定五档，这是最常见的划分方式，如果需要自定义，可以再加一个segments参数传入边界值。

这里有个容易翻车的点：如果直接用SQL的AVG()函数，NULL值会被自动忽略，但COUNT(*)会把缺考也算进去，导致及格率分母偏大。所以我在应用层做统计，逻辑更可控。

3. 成绩查询与权限隔离：学生只能看自己的，老师能看全班的

3.1 基于角色的查询接口设计

成绩查询不是简单的SELECT * FROM score，不同角色看到的数据范围完全不同。学生只能查自己的成绩，老师能查自己带的班级，管理员能查全部。这个权限逻辑必须在接口层做死，不能靠前端隐藏。

我一般用JWT在token里带角色信息，接口层根据角色拼接不同的查询条件。

# 成绩查询接口：根据角色返回不同范围 @app.route('/api/scores/query', methods=['GET']) def query_scores(): user = get_current_user() # 从JWT解析当前用户 role = user['role'] # student / teacher / admin course_id = request.args.get('course_id', type=int) semester = request.args.get('semester') query = Score.query.join(Student).join(Course) if role == 'student': # 学生只能查自己 query = query.filter(Student.student_no == user['username']) elif role == 'teacher': # 老师只能查自己带的班级（假设teacher表有class_name字段） teacher = Teacher.query.filter_by(teacher_no=user['username']).first() if not teacher: return jsonify({"code": 403, "msg": "无权限"}), 403 query = query.filter(Student.class_name == teacher.class_name) # admin 不加额外条件，查全部 if course_id: query = query.filter(Score.course_id == course_id) if semester: query = query.filter(Course.semester == semester) results = query.all() data = [] for s in results: data.append({ "student_no": s.student.student_no, "name": s.student.name, "class_name": s.student.class_name, "course_name": s.course.course_name, "score": float(s.score) if s.score is not None else None, "exam_type": s.exam_type }) return jsonify({"code": 0, "data": data})

这段代码的关键在于：权限过滤是在数据库查询层面完成的，不是查出来再过滤。学生角色的filter条件直接锁死学号，老师角色锁死班级，管理员不加限制。这样即使前端传了别人的学号，也查不到数据。

参数说明：course_id和semester是可选筛选条件。返回的score字段如果是None，前端显示为「缺考」。

3.2 分页与导出：数据量大了怎么办

一个班几十条数据随便查，但一个学院几千条、全校几万条的时候，不分页直接查会把内存打爆。查询接口必须支持分页。

# 分页查询 page = request.args.get('page', 1, type=int) per_page = request.args.get('per_page', 20, type=int) per_page = min(per_page, 100) # 限制最大每页100条 paginate = query.paginate(page=page, per_page=per_page, error_out=False) data = [] for s in paginate.items: data.append({...}) return jsonify({ "code": 0, "data": data, "pagination": { "page": page, "per_page": per_page, "total": paginate.total, "pages": paginate.pages } })

per_page限制最大100，防止有人传per_page=999999把数据库拖垮。分页信息返回给前端，方便做翻页组件。

导出功能我一般用异步任务处理，因为导出全校成绩可能要几十秒，同步接口会超时。简单做法是生成CSV文件后返回下载链接，复杂一点用Celery跑后台任务。

# 导出CSV（小数据量同步导出） import csv from io import StringIO @app.route('/api/scores/export', methods=['GET']) def export_scores(): # ... 权限校验和查询逻辑同上 ... output = StringIO() writer = csv.writer(output) writer.writerow(['学号', '姓名', '班级', '课程', '成绩', '考试类型']) for s in results: writer.writerow([ s.student.student_no, s.student.name, s.student.class_name, s.course.course_name, s.score if s.score is not None else '缺考', s.exam_type ]) output.seek(0) return Response( output.getvalue().encode('utf-8-sig'), # utf-8-sig 让Excel正确识别中文 mimetype='text/csv', headers={'Content-Disposition': 'attachment; filename=scores.csv'} )

注意utf-8-sig这个编码，普通utf-8导出的CSV用Excel打开会乱码，加BOM头才能正常显示中文。这是血泪经验，踩过一次就记住了。

4. 避坑与排查：成绩管理系统上线后最容易翻车的五个地方

4.1 并发录入导致成绩覆盖

现象：两个老师同时导入同一门课的成绩，后导入的覆盖了先导入的，部分学生成绩丢失。

原因：批量插入用了ON DUPLICATE KEY UPDATE，如果两个请求同时到达，后一个请求的score会覆盖前一个。如果两个老师手里的数据版本不同，就会出问题。

解决：在成绩表加一个version字段做乐观锁，或者录入前先检查该课程该考试类型是否已有成绩，有则提示「已存在，是否覆盖」。更稳妥的做法是加一个导入批次号，每次导入生成一个批次，查询时取最新批次的数据。

4.2 统计结果和手工算的对不上

现象：系统算的平均分和老师用Excel算的差0.1分。

原因：浮点数精度问题。DECIMAL(5,2)存的是精确值，但Python的float运算会有精度损失。比如sum([87.5, 62.3]) / 2可能得到74.90000000000001。

解决：统计时用Decimal类型运算，最后再转float返回。或者用round(avg, 2)强制保留两位小数。更彻底的做法是数据库层用DECIMAL聚合，应用层不做浮点运算。

4.3 学号前导零丢失

现象：学号001234导入后变成1234，查不到这个学生。

原因：Excel里学号列被识别为数字，前导零被吃掉。或者代码里用int()转换了学号。

解决：导入模板里学号列必须设置为文本格式。代码里学号全程用字符串处理，不做类型转换。数据库字段用VARCHAR。

4.4 权限漏洞：学生改URL查别人成绩

现象：学生把自己的学号改成别人的，能查到别人的成绩。

原因：查询接口信任了前端传来的学号参数，没有从JWT里取当前用户身份。

解决：学生角色的查询条件必须从token解析出的用户名来，不能从前端参数取。上面3.1节的代码已经做了这个处理，Student.student_no == user['username']是写死的。

4.5 导出大文件导致接口超时

现象：导出全校成绩时接口返回502，Nginx日志显示 upstream timeout。

原因：同步导出几万条数据，数据库查询加CSV生成超过Nginx默认的60秒超时。

解决：小数据量（几千条以内）同步导出，大数据量走异步任务。异步方案：接口只返回任务ID，后台用Celery或线程池生成文件，前端轮询任务状态，完成后返回下载链接。Nginx的proxy_read_timeout也可以适当调大，但治标不治本。

5. 进阶技巧：用缓存和索引把查询压到50毫秒以内

成绩查询的频率远高于录入，尤其是期末查分那几天，学生疯狂刷新。如果每次查询都走数据库，几千人同时查就会把数据库压垮。我的做法是在查询接口前面加一层Redis缓存，缓存键按「课程+考试类型+班级」维度设计，缓存时间设5分钟。

import redis import json r = redis.Redis(host='localhost', port=6379, db=0) def get_scores_with_cache(course_id, exam_type, class_name): cache_key = f"scores:{course_id}:{exam_type}:{class_name}" cached = r.get(cache_key) if cached: return json.loads(cached) # 数据库查询 results = Score.query.join(Student).filter( Score.course_id == course_id, Score.exam_type == exam_type, Student.class_name == class_name ).all() data = [{"student_no": s.student.student_no, "score": float(s.score) if s.score else None} for s in results] r.setex(cache_key, 300, json.dumps(data)) # 缓存5分钟 return data

缓存键的设计要细，不能用一个scores:all缓存所有数据，否则一个班更新了成绩，其他班也跟着失效。按班级维度缓存，更新时只删对应班级的键。

索引方面，成绩表除了主键和唯一键，我还加了idx_course索引。查询时WHERE course_id = ? AND exam_type = ?能直接走索引。如果经常按学期查，可以在课程表的semester字段加索引，然后join时用上。

还有一个技巧是「预计算」。统计接口如果每次实时算，数据量大时也慢。可以在成绩录入后触发一次统计计算，把结果存到一张statistics表里，查询时直接读结果。代价是录入后统计有延迟，但查询速度极快。适合对实时性要求不高的场景。

最后说一个我自己的习惯：任何成绩相关的接口，上线前一定用真实数据量压测一遍。用ab或wrk模拟200并发查一个班30条数据，看响应时间。如果超过200毫秒，就要检查索引和缓存了。成绩查询这种场景，学生等3秒就会疯狂刷新，越刷越慢，最后雪崩。提前压测能避免期末被投诉。

希望帮到你。

本文还有配套的精品资源，点击获取