FastAPI 请求体参数与 Pydantic 模型完全指南：从基础到嵌套模型实战 🚀

头像
风流倜傥的伤痕
     广东
    阅读 7 分钟

    title: FastAPI 请求体参数与 Pydantic 模型完全指南：从基础到嵌套模型实战 🚀
    date: 2025/3/7
    updated: 2025/3/7
    author: cmdragon

    excerpt:
    本教程深入探讨 FastAPI 请求体参数与 Pydantic 模型的核心机制，涵盖从基础模型定义到嵌套模型的高级用法。通过详细的代码示例、课后测验和常见错误解决方案，帮助初学者快速掌握 FastAPI 请求体参数的使用技巧。您将学习到如何通过 Pydantic 模型进行数据校验、类型转换和嵌套模型设计，从而构建安全、高效的 API 接口。

    categories:

    • 后端开发
    • FastAPI

    tags:

    • FastAPI
    • 请求体参数
    • Pydantic模型
    • 嵌套模型
    • 数据校验
    • API设计
    • RESTful

    image

    image

    扫描二维码关注或者微信搜一搜：编程智域 前端至全栈交流与成长

    探索数千个预构建的 AI 应用，开启你的下一个伟大创意

    第一章：请求体参数基础

    1.1 什么是请求体参数？

    请求体参数是 RESTful API 中用于传递复杂数据的变量，通常出现在 POST、PUT 等请求的请求体中。例如，创建用户时传递的用户信息就是请求体参数。

    from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class User(BaseModel):
    name: str
    age: int


@app.post("/users/")
async def create_user(user: User):
    return user

    1.2 Pydantic 模型基础

    Pydantic 模型用于定义请求体参数的结构和校验规则。通过继承 BaseModel，可以轻松定义模型类。

    class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None


@app.post("/items/")
async def create_item(item: Item):
    return item

    示例请求：

    {
  "name": "Foo",
  "price": 45.2,
  "tax": 3.2
}

    1.3 数据校验

    Pydantic 模型支持多种数据校验规则，如 Field、constr 等。

    from pydantic import Field, constr


class Product(BaseModel):
    name: constr(min_length=3, max_length=50)
    price: float = Field(..., gt=0)
    description: str = Field(None, max_length=100)


@app.post("/products/")
async def create_product(product: Product):
    return product

    示例请求：

    • 合法：{"name": "Laptop", "price": 999.99} → 返回产品信息
    • 非法：{"name": "A", "price": -10} → 422 错误

    1.4 常见错误与解决方案

    错误：422 Validation Error
    原因：请求体参数类型转换失败或校验不通过
    解决方案：检查请求体参数的类型定义和校验规则。

    第二章：嵌套模型

    2.1 什么是嵌套模型？

    嵌套模型是指在一个模型中包含另一个模型，用于表示复杂的数据结构。

    class Address(BaseModel):
    street: str
    city: str
    state: str
    zip_code: str


class User(BaseModel):
    name: str
    age: int
    address: Address

    2.2 嵌套模型的使用

    通过嵌套模型，可以处理复杂的请求体参数。

    @app.post("/users/")
async def create_user(user: User):
    return user

    示例请求：

    {
  "name": "John Doe",
  "age": 30,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "12345"
  }
}

    2.3 嵌套模型的校验

    嵌套模型同样支持数据校验。

    class OrderItem(BaseModel):
    name: str
    quantity: int = Field(..., gt=0)
    price: float = Field(..., gt=0)


class Order(BaseModel):
    items: List[OrderItem]
    total: float = Field(..., gt=0)


@app.post("/orders/")
async def create_order(order: Order):
    return order

    示例请求：

    • 合法：{"items": [{"name": "Laptop", "quantity": 1, "price": 999.99}], "total": 999.99} → 返回订单信息
    • 非法：{"items": [{"name": "Laptop", "quantity": 0, "price": 999.99}], "total": 999.99} → 422 错误

    2.4 常见错误与解决方案

    错误：422 Validation Error
    原因：嵌套模型校验失败
    解决方案：检查嵌套模型的校验规则。

    第三章：高级用法与最佳实践

    3.1 模型继承

    通过模型继承，可以复用已有的模型定义。

    class BaseUser(BaseModel):
    email: str
    password: str


class UserCreate(BaseUser):
    name: str


@app.post("/users/")
async def create_user(user: UserCreate):
    return user

    3.2 模型配置

    通过 Config 类，可以配置模型的行为，如别名生成、额外字段处理等。

    class Item(BaseModel):
    name: str
    description: str = None

    class Config:
        alias_generator = lambda x: x.upper()
        allow_population_by_field_name = True


@app.post("/items/")
async def create_item(item: Item):
    return item

    3.3 模型文档

    通过 Field 的 description 参数，可以为模型字段添加描述信息，这些信息将显示在 API 文档中。

    class Product(BaseModel):
    name: str = Field(..., description="产品名称")
    price: float = Field(..., description="产品价格", gt=0)


@app.post("/products/")
async def create_product(product: Product):
    return product

    3.4 常见错误与解决方案

    错误：422 Validation Error
    原因：模型校验失败
    解决方案：检查模型的校验规则和配置。

    课后测验

    测验 1：请求体参数校验

    问题：如何定义一个包含校验规则的请求体参数？
    答案：

    from pydantic import BaseModel, Field


class Item(BaseModel):
    name: str = Field(..., min_length=3)
    price: float = Field(..., gt=0)


@app.post("/items/")
async def create_item(item: Item):
    return item

    测验 2：嵌套模型

    问题：如何定义一个嵌套模型？
    答案：

    class Address(BaseModel):
    street: str
    city: str


class User(BaseModel):
    name: str
    address: Address


@app.post("/users/")
async def create_user(user: User):
    return user

    错误代码应急手册

    错误代码典型触发场景解决方案
    422类型转换失败/校验不通过检查模型定义的校验规则
    404请求体格式正确但资源不存在验证业务逻辑中的数据存在性
    500未捕获的模型处理异常添加 try/except 包裹敏感操作
    400自定义校验规则触发拒绝检查验证器的逻辑条件

    常见问题解答

    Q：请求体参数能否使用枚举类型？
    A：可以，使用 Enum 类实现：

    from enum import Enum


class Status(str, Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"


class User(BaseModel):
    name: str
    status: Status


@app.post("/users/")
async def create_user(user: User):
    return user

    Q：如何处理嵌套模型的默认值？
    A：在嵌套模型中为字段设置默认值：

    class Address(BaseModel):
    street: str
    city: str = "Anytown"


class User(BaseModel):
    name: str
    address: Address = Address(street="123 Main St")


@app.post("/users/")
async def create_user(user: User):
    return user

    通过详细讲解和实战项目，您已掌握 FastAPI 请求体参数与 Pydantic 模型的核心知识。现在可以通过以下命令测试您的学习成果：

    curl -X POST "http://localhost:8000/users/" -H "Content-Type: application/json" -d '{"name": "John Doe", "age": 30, "address": {"street": "123 Main St", "city": "Anytown", "state": "CA", "zip_code": "12345"}}'

    余下文章内容请点击跳转至 个人博客页面 或者 扫码关注或者微信搜一搜：编程智域 前端至全栈交流与成长，阅读完整的文章：FastAPI 请求体参数与 Pydantic 模型完全指南：从基础到嵌套模型实战 🚀 | cmdragon's Blog

    往期文章归档：

    后端pythonflaskdjangofastapi
    风流倜傥的伤痕
    79 声望23 粉丝
    « 上一篇
    FastAPI 查询参数完全指南：从基础到高级用法 🚀
    下一篇 »
    FastAPI Cookie 和 Header 参数完全指南：从基础到高级实战 🚀

    引用和评论

    推荐阅读
    头像
    Pydantic Schema生成指南：自定义JSON Schema

    风流倜傥的伤痕

    头像
    再见 XShell！一款万能通用的终端工具，用完爱不释手！

    macrozheng赞 2阅读 2.2k

    头像
    🔥必看！AnythingLLM+DeepSeek 快速构建私有知识库！

    阮小贰赞 6阅读 11.8k评论 1

    头像
    追女神必备！使用 Python 构建小红书用户动态监控系统（二）- 实现自动点赞和评论功能

    悖论BeilunYang赞 4阅读 1.4k评论 3

    头像
    🔥全程不用写代码，我用 AI 程序员写了一个飞机大战

    北京宏哥阅读 64.9k

    头像
    Redis 持久化原理分析和使用建议

    vivo互联网技术赞 3阅读 1.5k评论 1

    头像
    MyBatis-Plus结合Spring Boot实现数据权限

    Pursuer丶赞 3阅读 7.8k

    0 条评论
    得票最新