第1章 - 项目概述
嗨，朋友！我是长安。
现在我们要正式开始实战项目了！说实话，这个学生管理系统是我精心设计的，包含了真实项目中最常见的功能。完成这个项目，你就可以自信地写入简历了！
🎯 本章目标
- 了解项目需求
- 熟悉功能模块
- 设计数据库结构
1️⃣ 项目背景
这是一个非常典型的场景：学校需要一个系统来管理学生信息。我当年大二的时候就写过类似的项目，现在把经验分享给你。
系统需要管理：
- 学生基本信息（姓名、性别、年龄等）
- 班级信息
- 学生成绩
2️⃣ 功能需求
学生管理
- 添加学生
- 查看学生列表（支持分页、搜索）
- 查看学生详情
- 修改学生信息
- 删除学生
班级管理
- 添加班级
- 查看班级列表
- 查看班级详情（包含学生列表）
- 修改班级信息
- 删除班级
成绩管理
- 录入成绩
- 查看成绩
- 修改成绩
- 删除成绩
- 成绩统计（平均分、最高分、最低分等）
数据统计
- 学生总数统计
- 各班级人数统计
- 成绩分布统计
- 成绩排名
3️⃣ API 设计
学生接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/students | 创建学生 |
| GET | /api/students | 获取学生列表 |
| GET | /api/students/{id} | 获取学生详情 |
| PUT | /api/students/{id} | 更新学生信息 |
| DELETE | /api/students/{id} | 删除学生 |
班级接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/classes | 创建班级 |
| GET | /api/classes | 获取班级列表 |
| GET | /api/classes/{id} | 获取班级详情 |
| PUT | /api/classes/{id} | 更新班级信息 |
| DELETE | /api/classes/{id} | 删除班级 |
| GET | /api/classes/{id}/students | 获取班级学生 |
成绩接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/scores | 录入成绩 |
| GET | /api/scores | 获取成绩列表 |
| GET | /api/scores/{id} | 获取成绩详情 |
| PUT | /api/scores/{id} | 更新成绩 |
| DELETE | /api/scores/{id} | 删除成绩 |
| GET | /api/students/{id}/scores | 获取学生成绩 |
统计接口
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/statistics/overview | 总体统计 |
| GET | /api/statistics/class/{id} | 班级统计 |
| GET | /api/statistics/ranking | 成绩排名 |
4️⃣ 数据库设计
ER 图
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ classes │ │ students │ │ scores │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ id (PK) │───┐ │ id (PK) │───┐ │ id (PK) │
│ name │ │ │ name │ │ │ student_id │──┐
│ grade │ └──>│ class_id │ └──>│ subject │ │
│ teacher │ │ gender │ │ score │ │
│ created_at │ │ age │ │ exam_date │ │
└─────────────┘ │ phone │ │ created_at │ │
│ address │ └─────────────┘ │
│ created_at │ │
└─────────────┘<───────────────────────┘
班级表 (classes)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER | 主键，自增 |
| name | VARCHAR(50) | 班级名称 |
| grade | VARCHAR(20) | 年级 |
| teacher | VARCHAR(50) | 班主任 |
| created_at | DATETIME | 创建时间 |
学生表 (students)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER | 主键，自增 |
| student_no | VARCHAR(20) | 学号，唯一 |
| name | VARCHAR(50) | 姓名 |
| gender | VARCHAR(10) | 性别 |
| age | INTEGER | 年龄 |
| phone | VARCHAR(20) | 联系电话 |
| address | VARCHAR(200) | 地址 |
| class_id | INTEGER | 班级ID，外键 |
| created_at | DATETIME | 创建时间 |
成绩表 (scores)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER | 主键，自增 |
| student_id | INTEGER | 学生ID，外键 |
| subject | VARCHAR(50) | 科目 |
| score | FLOAT | 分数 |
| exam_date | DATE | 考试日期 |
| created_at | DATETIME | 创建时间 |
5️⃣ 项目结构
student-management/
├── app/
│ ├── __init__.py
│ ├── main.py # 主程序入口
│ ├── config.py # 配置文件
│ ├── database.py # 数据库配置
│ ├── models/ # 数据库模型
│ │ ├── __init__.py
│ │ ├── class_model.py
│ │ ├── student.py
│ │ └── score.py
│ ├── schemas/ # Pydantic 模型
│ │ ├── __init__.py
│ │ ├── class_schema.py
│ │ ├── student.py
│ │ └── score.py
│ ├── crud/ # CRUD 操作
│ │ ├── __init__.py
│ │ ├── class_crud.py
│ │ ├── student.py
│ │ └── score.py
│ ├── api/ # API 路由
│ │ ├── __init__.py
│ │ ├── classes.py
│ │ ├── students.py
│ │ ├── scores.py
│ │ └── statistics.py
│ └── utils/ # 工具函数
│ ├── __init__.py
│ └── response.py
├── requirements.txt # 依赖文件
└── README.md # 项目说明
6️⃣ 响应格式设计
统一的 API 响应格式：
成功响应
{
"code": 200,
"message": "success",
"data": {
// 具体数据
}
}
列表响应（带分页）
{
"code": 200,
"message": "success",
"data": {
"items": [],
"total": 100,
"page": 1,
"size": 10,
"pages": 10
}
}
错误响应
{
"code": 400,
"message": "参数错误",
"data": null
}
📝 小结
本章我们完成了：
- ✅ 明确项目需求
- ✅ 设计 API 接口
- ✅ 设计数据库结构
- ✅ 规划项目结构
- ✅ 定义响应格式
🏃 下一步
需求和设计都清楚了，接下来开始搭建项目！