FastAPI 实战：从零构建学生信息查询接口

上一节我们跑通了 FastAPI 的 Hello World，这一节来写一个真正有业务意义的接口——学生信息查询接口。为了先熟悉 FastAPI 和它自带的 Swagger 文档，本节先用写死在代码里的假数据把接口跑通，后续再替换成数据库。

最终我们要完成两个接口：

• 获取所有学生信息
• 根据学生 ID 获取指定学生信息

---

一、准备假数据

在 main.py 中先定义一个模拟数据库 fake_student_db。它是一个列表，列表里每个元素都是一个字典，包含学生的 ID、姓名、学号、性别、生日等字段。这里先放三条假数据：

fake_students_db = [
    {
        "id": 1,
        "name": "张伟",
        "student_no": "2026010101",
        "gender": "male",
        "birthday": "2005-03-15",
        "phone": "13800000001",
        "class_id": 1,
    },
    {
        "id": 2,
        "name": "李娜",
        "student_no": "2026010102",
        "gender": "female",
        "birthday": "2005-07-22",
        "phone": "13800000002",
        "class_id": 1,
    },
    {
        "id": 3,
        "name": "王磊",
        "student_no": "2026010103",
        "gender": "male",
        "birthday": "2004-11-08",
        "phone": "13800000003",
        "class_id": 2,
    },
]

---

二、接口一：获取所有学生

1. 编写路由

路径设计为 API/v1/students，其中 v1 是版本号（原因后续章节再讲），students 用复数形式表示"获取所有学生"。函数命名为 GetStudents，直接返回假数据列表：

@app.get("/api/v1/students")
def get_students():
    return fake_student_db

2. 在 Swagger 文档中测试

启动服务后访问 /docs，可以看到文档里多了一个接口 API/v1/students。点击 Try it out，再点击 Execute 发送请求：

• 请求 URL：API/v1/students
• 返回码：200
• 响应内容：JSON 格式的学生列表

可以看到，FastAPI 会自动把 Python 的字典/列表数据转换成 JSON 返回，无需手动序列化。

---

三、给接口分组并美化文档

1. 用 tags 给接口分类

Swagger 文档默认把所有接口放在 default 分组下。我们可以通过 tags 参数给接口分类，比如学生相关接口统一归到"学生管理"：

@app.get("/api/v1/students", tags=["学生管理"])
def get_students():
    return fake_student_db

刷新文档后，接口就出现在"学生管理"分组下了。后续班级接口可以用 tags=["班级管理"]、成绩接口用 tags=["成绩管理"] 来区分。

2. 设置文档标题、描述与版本号

在创建 FastAPI 实例时传入 title、description、version 参数，可以让 Swagger 文档更美观：

app = FastAPI(
    title="学生管理",
    description="基于 FastAPI + MySQL 的学生管理系统 API",
    version="0.0.1",
)

保存后刷新文档，页面顶部就会显示标题、描述和版本号。

---

四、接口二：根据 ID 获取单个学生

1. 路径参数设计

路径写成 /api/v1/students/{student_id}，花括号中的 student_id 是路径参数，值不固定——传 1 就查 ID 为 1 的学生，传 2 就查 ID 为 2 的学生。

@app.get("/api/v1/students/{student_id}", tags=["学生管理"])
def get_student(student_id: int):
    for student in fake_students_db:
        if student["id"] == student_id:
            return student
    # 找不到抛出异常
    raise HTTPException(status_code=404, detail=f"学生ID为{student_id} 不存在")

要点说明：

• 函数参数名与路径中的 {student_id} 同名，FastAPI 会自动从 URL 中取值并传给函数，无需手动解析。
• 遍历 fake_student_db，用字典中的 id 与参数比较，相等则返回该学生信息。
• 找不到时抛出 HTTPException，状态码 404，并在 detail 中说明哪个 ID 不存在。

2. 引入异常类

HTTPException 需要从 FastAPI 中导入：

from fastapi import FastAPI, HTTPException

---

五、调试：类型不匹配导致查不到数据

第一次测试时，输入 ID 为 1 却返回了"学生ID 1 不存在"。为定位问题，在函数中打印参数值和类型：

print(student_id, type(student_id))

再次请求后，在运行 FastAPI 的终端里看到输出为字符串 str 类型——也就是说，路径参数默认被当成了字符串 "1"，而假数据里的 id 是整数 1，两者比较自然不相等。

解决办法：声明参数类型

给参数加上类型注解 student_id: int，FastAPI 就会保持原始数据类型，用整数去匹配整数：

def get_student(student_id: int):

---

六、测试结果

清空输入后重新测试：

• 输入 1 → 返回 ID 为 1 的学生"章尾"
• 输入 2 → 返回 "Linna"
• 输入 3 → 返回 "王磊"
• 输入 99 → 返回 404，提示"学生ID 99 不存在"

两个接口均正常运行。

---

七、小结

本节完成了：

1. 用假数据构建了"获取所有学生"和"按 ID 获取学生"两个接口；
2. 通过 tags 给接口分组、通过 title/description/version 美化 Swagger 文档；
3. 掌握了路径参数的接收方式，以及用类型注解 int 保证参数类型正确；
4. 学会了用 HTTPException 返回 404 错误。

关于接口路径为什么这样设计（如 API/v1/students 的复数形式与版本号），下一节会专门介绍 RESTful 接口设计规范。