请求体¶

当你需要将数据从客户端（例如浏览器）发送给 API 时，你将其作为「请求体」发送。

请求体是客户端发送给 API 的数据。响应体是 API 发送给客户端的数据。

你的 API 几乎总是要发送响应体。但是客户端并不总是需要发送请求体。

我们使用 Pydantic 模型来声明请求体，并能够获得它们所具有的所有能力和优点。

Info

你不能使用 GET 操作（HTTP 方法）发送请求体。

要发送数据，你必须使用下列方法之一：POST（较常见）、PUT、DELETE 或 PATCH。

导入 Pydantic 的 `BaseModel`¶

首先，你需要从 pydantic 中导入 BaseModel：

Python 3.10+Python 3.8+

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


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

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


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

创建数据模型¶

然后，将你的数据模型声明为继承自 BaseModel 的类。

使用标准的 Python 类型来声明所有属性：

Python 3.10+Python 3.8+

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


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

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


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

和声明查询参数时一样，当一个模型属性具有默认值时，它不是必需的。否则它是一个必需属性。将默认值设为 None 可使其成为可选属性。

例如，上面的模型声明了一个这样的 JSON「object」（或 Python dict）：

{
    "name": "Foo",
    "description": "An optional description",
    "price": 45.2,
    "tax": 3.5
}

...由于 description 和 tax 是可选的（它们的默认值为 None），下面的 JSON「object」也将是有效的：

{
    "name": "Foo",
    "price": 45.2
}

声明为参数¶

使用与声明路径和查询参数的相同方式声明请求体，即可将其添加到「路径操作」中：

Python 3.10+Python 3.8+

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


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

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


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

...并且将它的类型声明为你创建的 Item 模型。

结果¶

仅仅使用了 Python 类型声明，FastAPI 将会：

将请求体作为 JSON 读取。
转换为相应的类型（在需要时）。
校验数据。
- 如果数据无效，将返回一条清晰易读的错误信息，指出不正确数据的确切位置和内容。
将接收的数据赋值到参数 item 中。
- 由于你已经在函数中将它声明为 Item 类型，你还将获得对于所有属性及其类型的一切编辑器支持（代码补全等）。
为你的模型生成 JSON 模式定义，你还可以在其他任何对你的项目有意义的地方使用它们。
这些模式将成为生成的 OpenAPI 模式的一部分，并且被自动化文档 UI 所使用。

自动化文档¶

你所定义模型的 JSON 模式将成为生成的 OpenAPI 模式的一部分，并且在交互式 API 文档中展示：

而且还将在每一个需要它们的路径操作的 API 文档中使用：

编辑器支持¶

在你的编辑器中，你会在函数内部的任意地方得到类型提示和代码补全（如果你接收的是一个 dict 而不是 Pydantic 模型，则不会发生这种情况）：

你还会获得对不正确的类型操作的错误检查：

这并非偶然，整个框架都是围绕该设计而构建。

并且在进行任何实现之前，已经在设计阶段经过了全面测试，以确保它可以在所有的编辑器中生效。

Pydantic 本身甚至也进行了一些更改以支持此功能。

上面的截图取自 Visual Studio Code。

但是在 PyCharm 和绝大多数其他 Python 编辑器中你也会获得同样的编辑器支持：

使用模型¶

在函数内部，你可以直接访问模型对象的所有属性：

Python 3.10+Python 3.8+

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

请求体 + 路径参数¶

你可以同时声明路径参数和请求体。

FastAPI 将识别出与路径参数匹配的函数参数应从路径中获取，而声明为 Pydantic 模型的函数参数应从请求体中获取。

Python 3.10+Python 3.8+

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.put("/items/{item_id}")
async def create_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.put("/items/{item_id}")
async def create_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

请求体 + 路径参数 + 查询参数¶

你还可以同时声明请求体、路径参数和查询参数。

FastAPI 会识别它们中的每一个，并从正确的位置获取数据。

Python 3.10+Python 3.8+

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.put("/items/{item_id}")
async def create_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.dict()}
    if q:
        result.update({"q": q})
    return result

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.put("/items/{item_id}")
async def create_item(item_id: int, item: Item, q: Union[str, None] = None):
    result = {"item_id": item_id, **item.dict()}
    if q:
        result.update({"q": q})
    return result

函数参数将依次按如下规则进行识别：

如果在路径中也声明了该参数，它将被用作路径参数。
如果参数属于单一类型（比如 int、float、str、bool 等）它将被解释为查询参数。
如果参数的类型被声明为一个 Pydantic 模型，它将被解释为请求体。

不使用 Pydantic¶

如果你不想使用 Pydantic 模型，你还可以使用 Body 参数。请参阅文档请求体 - 多个参数：请求体中的单一值。

请求体¶

导入 Pydantic 的 BaseModel¶

创建数据模型¶

声明为参数¶

结果¶

自动化文档¶

编辑器支持¶

使用模型¶

请求体 + 路径参数¶

请求体 + 路径参数 + 查询参数¶

不使用 Pydantic¶

导入 Pydantic 的 `BaseModel`¶