您如何为嵌套和复杂的请求体建立模型？

Question

您如何为嵌套和复杂的请求体建立模型？

Accepted Answer

Pydantic 模型可以**嵌套**——一个模型字段本身可以是另一个模型、模型列表或复杂类型——让 FastAPI 自动验证深层结构化 JSON（对象中的对象、对象数组）。

## 嵌套模型

```python
from pydantic import BaseModel

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

class User(BaseModel):
    name: str
    address: Address                    # a NESTED model
    tags: list[str] = []                # a list of strings
    addresses: list[Address] = []       # a list of NESTED models

@app.post("/users")
def create(user: User):                  # validates the WHOLE nested structure
    return user
```

```json
// FastAPI validates this entire structure, including the nested address:
{ "name": "Ann",
  "address": { "street": "1 Main", "city": "NY", "zip": "10001" },
  "tags": ["vip"] }
```

类型为另一个模型（或 `list[Model]`）的模型字段会递归验证——嵌套对象和对象数组都会根据其架构自动检查。

## 复杂和特殊类型

```python
from pydantic import BaseModel, HttpUrl, EmailStr
from datetime import datetime
from enum import Enum

class Status(str, Enum):                 # enums constrain to allowed values
    active = "active"
    inactive = "inactive"

class Item(BaseModel):
    url: HttpUrl                          # validates URL format
    email: EmailStr                       # validates email format
    created: datetime                     # parses ISO 8601 strings → datetime
    status: Status                        # must be one of the enum values
    metadata: dict[str, int]              # typed dict
    coordinates: tuple[float, float]      # typed tuple
```

Pydantic 处理丰富的类型：枚举（限制允许的值）、`datetime`（解析 ISO 字符串）、`HttpUrl`/`EmailStr`（格式验证）和类型化字典/元组——全部自动验证。

## 泛型/可重用包装器

```python
from typing import Generic, TypeVar
T = TypeVar("T")
class Paginated(BaseModel, Generic[T]):   # a reusable generic response wrapper
    items: list[T]
    total: int
# Paginated[User] → { items: [User...], total: N }
```

## 为什么这很重要

现实世界的 API 很少处理扁平数据——它们处理复杂的嵌套结构（一个用户有地址和订单列表、一个订单有行项目、配置对象），Pydantic 能够**嵌套模型**的能力使验证这些深层结构化请求体变得轻而易举。

了解模型字段可以是另一个模型、模型列表或丰富类型——以及 FastAPI **递归地自动验证整个嵌套结构**——对于构建安全接受真实复杂输入的 API 很重要。

丰富类型支持（枚举用于受限值、`datetime` 解析、`HttpUrl`/`EmailStr` 格式验证、类型化集合）进一步确保复杂数据无需手动检查即可正确。

知道如何对嵌套和复杂的请求体建立模型（以及用于分页等功能的可重用泛型包装器）是构建处理真实应用所需结构化数据的 API 的实用知识，并且完全自动提供验证——这是 FastAPI 基于 Pydantic 的设计的关键优势。