fastapi/docs/zh/docs/tutorial/body.md

请求体

当你需要从客户端（比如浏览器）向你的 API 发送数据时，会把它作为请求体发送。

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

你的 API 几乎总是需要发送响应体。但客户端不一定总是要发送请求体，有时它们只请求某个路径，可能带一些查询参数，但不会发送请求体。

使用 Pydantic 模型来声明请求体，能充分利用它的功能和优点。

/// info | 信息

发送数据应使用以下之一：POST（最常见）、PUT、DELETE 或 PATCH。

规范中没有定义用 GET 请求发送请求体的行为，但 FastAPI 仍支持这种方式，只用于非常复杂/极端的用例。

由于不推荐，在使用 GET 时，Swagger UI 的交互式文档不会显示请求体的文档，而且中间的代理可能也不支持它。

///

导入 Pydantic 的 BaseModel

从 pydantic 中导入 BaseModel：

{* ../../docs_src/body/tutorial001_py310.py hl[2] *}

创建数据模型

把数据模型声明为继承 BaseModel 的类。

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

{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}

与声明查询参数一样，包含默认值的模型属性是可选的，否则就是必选的。把默认值设为 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
}

声明为参数

使用与声明路径和查询参数相同的方式，把它添加至路径操作：

{* ../../docs_src/body/tutorial001_py310.py hl[16] *}

...并把其类型声明为你创建的模型 Item。

结果

仅使用这些 Python 类型声明，FastAPI 就可以：

• 以 JSON 形式读取请求体。
• （在必要时）把请求体转换为对应的类型。
• 校验数据。
  • 数据无效时返回清晰的错误信息，并指出错误数据的确切位置和内容。
• 把接收的数据赋值给参数 item。
  • 因为你把函数中的参数类型声明为 Item，所以还能获得所有属性及其类型的编辑器支持（补全等）。
• 为你的模型生成 JSON Schema 定义，如果对你的项目有意义，还可以在其他地方使用它们。
• 这些 schema 会成为生成的 OpenAPI Schema 的一部分，并被自动文档的 UIs 使用。

自动文档

你的模型的 JSON Schema 会成为生成的 OpenAPI Schema 的一部分，并显示在交互式 API 文档中：

并且，还会用于需要它们的每个路径操作的 API 文档中：

编辑器支持

在编辑器中，函数内部你会在各处得到类型提示与补全（如果接收的不是 Pydantic 模型，而是 dict，就不会有这样的支持）：

还支持检查错误的类型操作：

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

并且在设计阶段、实现之前就进行了全面测试，以确保它能在所有编辑器中正常工作。

我们甚至对 Pydantic 本身做了一些改动以支持这些功能。

上面的截图来自 Visual Studio Code。

但使用 PyCharm 和大多数其他 Python 编辑器，你也会获得相同的编辑器支持：

/// tip | 提示

如果你使用 PyCharm 作为编辑器，可以使用 Pydantic PyCharm 插件。

它能改进对 Pydantic 模型的编辑器支持，包括：

• 自动补全
• 类型检查
• 代码重构
• 查找
• 代码审查

///

使用模型

在路径操作函数内部直接访问模型对象的所有属性：

{* ../../docs_src/body/tutorial002_py310.py *}

请求体 + 路径参数

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

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

{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}

请求体 + 路径 + 查询参数

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

FastAPI 会分别识别它们，并从正确的位置获取数据。

{* ../../docs_src/body/tutorial004_py310.py hl[16] *}

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

• 如果该参数也在路径中声明了，它就是路径参数。
• 如果该参数是（int、float、str、bool 等）单一类型，它会被当作查询参数。
• 如果该参数的类型声明为 Pydantic 模型，它会被当作请求体。

/// note | 注意

FastAPI 会根据默认值 = None 知道 q 的值不是必填的。

str | None（Python 3.10+）或 Union[str, None]（Python 3.9+ 中的 Union）并不是 FastAPI 用来判断是否必填的依据；是否必填由是否有默认值 = None 决定。

但添加这些类型注解可以让你的编辑器提供更好的支持并检测错误。

///

不使用 Pydantic

即便不使用 Pydantic 模型也能使用 Body 参数。详见请求体 - 多参数：请求体中的单值{.internal-link target=_blank}。