FastAPI 学生管理项目实战：用 Pydantic 模型约束接口返回值

在上一节中我们学习了 Pydantic 的基本用法，这节课把它真正落地到学生管理项目中：定义一个 Student 数据模型，并用它约束「获取全部学生」和「获取单个学生」两个接口的返回结构，最后通过 Swagger 文档验证效果。

一、本节目标

• 在项目中引入 Pydantic 的 BaseModel
• 定义 Student 模型，约束学生信息的字段类型
• 通过 response_model 让两个查询接口按模型返回数据
• 在接口文档中验证成功与失败两种场景

二、引入依赖并定义模型

打开项目入口文件 main.py，先引入 Pydantic 的 BaseModel：

from pydantic import BaseModel

模型类通常定义在 app 目录下。我们在这里构建一个学生模型 Student，继承 BaseModel，并把学生信息的各个字段声明出来：

class Student(BaseModel):
    id: int
    name: str
    student_no: str
    gender: str
    birthday: datetime.date | None = None
    phone: str
    class_id: int

其中 birthday 是日期类型，需要导入内置的 datetime 模块。按照开发规范，导入顺序建议为：Python 内置模块 → 第三方模块 → 自定义模块，因此 import datetime 放在文件顶部：

import datetime
from pydantic import BaseModel

birthday 字段使用了 datetime.date | None = None 的写法：竖线表示「或」，即该字段可以是日期，也可以为空；用户不填时默认赋值为 None。

三、为接口添加返回模型约束

1. 获取全部学生信息

原来的接口返回的是一串字符串，没有明确的数据结构。现在在路由装饰器中添加 response_model 参数，指定返回类型为 List[Student]——外层是列表，列表里每个元素是一个学生信息，与测试数据的结构一一对应：

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

2. 获取单个学生信息

单个学生接口返回的就是一个学生对象，直接把 response_model 设为 Student 即可：

@app.get("/api/v1/students/{student_id}", response_model=Student,tags=["学生管理"])
def get_student(student_id: int):
    ...

四、测试验证

启动服务后刷新 Swagger 文档页面，逐个接口验证。

1. 获取全部学生

进入「获取全部学生信息」接口，点击 Try it out。此时 Successful Response 下的 Example Value 已经变成列表嵌套字典的结构——而在添加模型约束之前，这里显示的只是一个字符串，没有正确的示例。点击 Execute 发送请求，返回状态码 200，响应体正是我们构建的假数据，只是现在被模型约束后返回效果发生了变化。

2. 获取单个学生

切换到「获取单个学生信息」接口，点击 Try it out，填入第一个学生 ID。执行前同样可以看到成功示例；点击 Execute 后成功返回该学生的信息。

3. 异常场景

• ID 不存在：填入 100 后执行，返回 404，提示学生 ID 为 100 的记录不存在。
• ID 类型错误：填入 ABC 后执行，请求直接报错，提示学生 ID 的值必须是整数。

五、小结

本节通过构建 Student 模型，完成了对两个接口的改造：

• 获取全部学生信息：response_model=List[Student]，约束返回为「学生列表」；
• 获取单个学生信息：response_model=Student，约束返回为「单个学生对象」。

改造后，接口文档会自动生成正确的返回示例，返回数据也会按模型进行校验。下一节将继续介绍其他几个接口的实现。