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

aHkhyRRhlaks · 3 天前

<hr>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

<hr>

扫描二维码关注或者微信搜一搜：编程智域前端至全栈交流与成长
探索数千个预构建的 AI 应用，开启你的下一个伟大创意
第一章：请求体参数基础

1.1 什么是请求体参数？

请求体参数是 RESTful API 中用于传递复杂数据的变量，通常出现在 POST、PUT 等请求的请求体中。例如，创建用户时传递的用户信息就是请求体参数。
from fastapi import FastAPIfrom pydantic import BaseModelapp = FastAPI()class User(BaseModel): name: str age: int@app.post("/users/")async def create_user(user: User): return user1.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, constrclass 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
原因：请求体参数类型转换失败或校验不通过
解决方案：检查请求体参数的类型定义和校验规则。
<hr>第二章：嵌套模型

2.1 什么是嵌套模型？

嵌套模型是指在一个模型中包含另一个模型，用于表示复杂的数据结构。
class Address(BaseModel): street: str city: str state: str zip_code: strclass User(BaseModel): name: str age: int address: Address2.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
原因：嵌套模型校验失败
解决方案：检查嵌套模型的校验规则。
<hr>第三章：高级用法与最佳实践

3.1 模型继承

通过模型继承，可以复用已有的模型定义。
class BaseUser(BaseModel): email: str password: strclass UserCreate(BaseUser): name: str@app.post("/users/")async def create_user(user: UserCreate): return user3.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 item3.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 product3.4 常见错误与解决方案

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

测验 1：请求体参数校验

问题：如何定义一个包含校验规则的请求体参数？
答案：
from pydantic import BaseModel, Fieldclass 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: strclass User(BaseModel): name: str address: Address@app.post("/users/")async def create_user(user: User): return user<hr>错误代码应急手册

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

Q：请求体参数能否使用枚举类型？
A：可以，使用 Enum 类实现：
from enum import Enumclass Status(str, Enum): ACTIVE = "active" INACTIVE = "inactive"class User(BaseModel): name: str status: Status@app.post("/users/")async def create_user(user: User): return userQ：如何处理嵌套模型的默认值？
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<hr>通过详细讲解和实战项目，您已掌握 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
往期文章归档：

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

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

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

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