FastAPI入门：请求体的字段、嵌套模型、额外数据、额外数据类型
请求体字段
与在路径操作函数中使用 Query、Path 、Body 声明校验与元数据的方式一样，可以使用 Pydantic 的 Field 在 Pydantic 模型内部声明校验和元数据。
在声明请求体数据模型时可以使用Field定义模型属性
from fastapi import FastAPI, Query , Path, Body
from typing import Annotated, Literal
from pydantic import BaseModel, Fieldclass Item(BaseModel):name: strdescription: str | None = Field(default=None, title="The description of the item",max_length=300)price: float = Field(gt=0,description="The price of the item")tax: float | None = Noneapp = FastAPI()@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):result = {"item_id": item_id,"item": item}return result请求体嵌套模型
List字段
可以将一个属性定义为拥有子元素的类型。例如 Python list
from fastapi import FastAPI
from pydantic import BaseModelapp = FastAPI()class Item(BaseModel):name: strdescription: str | None = Noneprice: floattax: float | None = Nonetags: list = []@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):results = {"item_id": item_id, "item": item}return results
这将使 tags 成为一个由元素组成的列表。不过它没有声明每个元素的类型。
具有子类型的list字段
tags: list[str] = []
Set类型
tags: set[str] = set()
嵌套模型
对于不同的pydantic模型，可以实现彼此嵌套
from fastapi import FastAPI
from pydantic import BaseModelapp = FastAPI()class Image(BaseModel):url: strname: strclass Item(BaseModel):name: strdescription: str | None = Noneprice: floattax: float | None = Nonetags: set[str] = set()image: Image | None = None@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):results = {"item_id": item_id, "item": item}return results
对于Item将期待以下格式的请求体
{"name": "Foo","description": "The pretender","price": 42.0,"tax": 3.2,"tags": ["rock", "metal", "bar"],"image": {"url": "http://example.com/baz.jpg","name": "The Foo live"}
}
纯列表请求体
如果你期望的 JSON 请求体的最外层是一个 JSON array（即 Python list），则可以在路径操作函数的参数中声明此类型
from fastapi import FastAPI
from pydantic import BaseModel, HttpUrlapp = FastAPI()class Image(BaseModel):url: HttpUrlname: str@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):return images
额外定义数据
可以使用 Config 和 schema_extra 为Pydantic模型声明一个示例
from fastapi import FastAPI
from pydantic import BaseModelapp = FastAPI()class Item(BaseModel):name: strdescription: str | None = Noneprice: floattax: float | None = Nonemodel_config = {"json_schema_extra": {"examples": [{"name": "Foo","description": "A very nice Item","price": 35.4,"tax": 3.2,}]}}@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):results = {"item_id": item_id, "item": item}return results
这会在doc文档中生成示例
在Field, Path, Query, Body等声明中也可以附加额外参数
from fastapi import FastAPI
from pydantic import BaseModel, Fieldapp = FastAPI()class Item(BaseModel):name: str = Field(examples=["Foo"])description: str | None = Field(default=None, examples=["A very nice Item"])price: float = Field(examples=[35.4])tax: float | None = Field(default=None, examples=[3.2])@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):results = {"item_id": item_id, "item": item}return results
以及可以将额外参数传递给Body
from typing import Annotatedfrom fastapi import Body, FastAPI
from pydantic import BaseModelapp = FastAPI()class Item(BaseModel):name: strdescription: str | None = Noneprice: floattax: float | None = None@app.put("/items/{item_id}")
async def update_item(item_id: int,item: Annotated[Item,Body(examples=[{"name": "Foo","description": "A very nice Item","price": 35.4,"tax": 3.2,}],),],
):results = {"item_id": item_id, "item": item}return results
额外数据类型
可以用到的其他参数类型：
| 参数类型 | 说明 |
|---|---|
| UUID | 一种标准的 “通用唯一标识符” ，在许多数据库和系统中用作ID。在请求和响应中将以 str 表示。 |
| datetime.datetime | 一个 Python datetime.datetime.在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 2008-09-15T15:53:00+05:00. |
| datetime.date | Python datetime.date.在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 2008-09-15. |
| datetime.time | 一个 Python datetime.time.在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 14:23:55.003. |
| datetime.timedelta | 一个 Python datetime.timedelta.在请求和响应中将表示为 float 代表总秒数。Pydantic 也允许将其表示为 “ISO 8601 时间差异编码” |
| frozenset | 在请求和响应中，作为 set 对待：在请求中，列表将被读取，消除重复，并将其转换为一个 set。在响应中 set 将被转换为 list 。产生的模式将指定那些 set 的值是唯一的 (使用 JSON 模式的 uniqueItems)。 |
| bytes | 标准的 Python bytes。在请求和响应中被当作 str 处理。生成的模式将指定这个 str 是 binary “格式”。 |
| Decimal | 标准的 Python Decimal。在请求和响应中被当做 float 一样处理。 |