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


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

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

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

第一章:请求体参数基础

1.1 什么是请求体参数?

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

python 复制代码
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,可以轻松定义模型类。

python 复制代码
class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None


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

示例请求

json 复制代码
{
  "name": "Foo",
  "price": 45.2,
  "tax": 3.2
}

1.3 数据校验

Pydantic 模型支持多种数据校验规则,如 Fieldconstr 等。

python 复制代码
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 什么是嵌套模型?

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

python 复制代码
class Address(BaseModel):
    street: str
    city: str
    state: str
    zip_code: str


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

2.2 嵌套模型的使用

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

python 复制代码
@app.post("/users/")
async def create_user(user: User):
    return user

示例请求

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

2.3 嵌套模型的校验

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

python 复制代码
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 模型继承

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

python 复制代码
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 类,可以配置模型的行为,如别名生成、额外字段处理等。

python 复制代码
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 模型文档

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

python 复制代码
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:请求体参数校验

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

python 复制代码
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:嵌套模型

问题 :如何定义一个嵌套模型?
答案

python 复制代码
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 类实现:

python 复制代码
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:在嵌套模型中为字段设置默认值:

python 复制代码
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 模型的核心知识。现在可以通过以下命令测试您的学习成果:

bash 复制代码
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

往期文章归档:

相关推荐
程序员编程指南14 小时前
Qt 网络编程进阶:RESTful API 调用
c语言·网络·c++·qt·restful
cts61818 小时前
全文检索官网示例
python·全文检索·fastapi
半新半旧2 天前
FastAPI中间件
中间件·fastapi
爱吃羊的老虎3 天前
【后端】FastAPI的Pydantic 模型
数据库·后端·python·fastapi
Elastic 中国社区官方博客3 天前
使用 FastAPI 构建 Elasticsearch API
大数据·数据库·python·elasticsearch·搜索引擎·全文检索·fastapi
陈小桔4 天前
SQLALchemy
python·fastapi
alpszero4 天前
使用UV管理FastAPI项目
fastapi·uv
**梯度已爆炸**5 天前
Python Web框架详解:Flask、Streamlit、FastAPI
python·flask·fastapi·streamlit
鼠鼠我捏,要死了捏5 天前
Spring Boot中REST与gRPC并存架构设计与性能优化实践指南
springboot·restful·grpc
斟的是酒中桃6 天前
基于Transformer的智能对话系统:FastAPI后端与Streamlit前端实现
前端·transformer·fastapi