FastAPI自学教程（11）- 请求体嵌套模型

1.嵌套模型基础

from typing import List
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tags: list = []

app = FastAPI()

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

• 模型属性可以包含其他模型类型
• 使用标准Python类型声明嵌套结构（如list）
• 支持原生Python类型与Pydantic模型的组合嵌套

2.多层嵌套模型

class Image(BaseModel):
    url: str
    name: str

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tags: set[str] = set()
    image: Image | None = None
    images: list[Image] | None = None

• 支持无限层级的嵌套模型
• 可以组合使用特殊类型（如set）
• 可选字段通过None设置默认值
• 自动生成交互式API文档的嵌套结构

3.列表属性与集合类型

from typing import Set, Tuple

class Item(BaseModel):
    tags: Set[str] = set()
    dimensions: Tuple[int, int, int] | None = None

• list：允许重复元素的可变序列
• set：自动去重的唯一元素集合
• tuple：固定大小的不可变序列
• 集合类型自动进行数据验证和转换

4.深度嵌套模型

class Offer(BaseModel):
    name: str
    description: str | None = None
    price: float
    items: list[Item]

• 模型可以包含模型列表
• 支持多级嵌套结构（如列表中的子模型）
• 自动验证嵌套结构的所有层级
• 深度嵌套错误会精确显示错误位置

5.特殊类型与响应模型

from pydantic import HttpUrl

class Image(BaseModel):
    url: HttpUrl
    name: str

@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
    return images

• 内置特殊类型（如HttpUrl）自动验证URL格式
• 响应模型支持排除默认值字段（response_model_exclude_unset=True）
• 支持纯列表响应模型（如list[Item]）
• 嵌套模型自动生成对应的Swagger文档结构