-「_[...] 我最近大量使用 **FastAPI**。[...] 我实际上计划把它用于我团队在 **微软的机器学习（ML）服务**。其中一些正在集成进核心 **Windows** 产品以及一些 **Office** 产品。_」
+「_[...] 我最近大量使用 **FastAPI**。[...] 我实际上计划把它用于我团队在 **微软的所有机器学习（ML）服务**。其中一些正在集成进核心 **Windows** 产品以及一些 **Office** 产品。_」
Kabir Khan -
Microsoft (参考)
@@ -235,7 +235,7 @@ async def read_item(item_id: int, q: str | None = None):
**注意**:
-如果你不确定，请查看文档中 _"In a hurry?"_ 章节的 [`async` 和 `await`](https://fastapi.tiangolo.com/zh/async/#in-a-hurry) 部分。
+如果你不确定，请查看文档中关于 [`async` 和 `await`](https://fastapi.tiangolo.com/zh/async/#in-a-hurry) 的 _"急用？"_ 章节。
@@ -409,9 +409,9 @@ item: Item
* 路径参数。
* 查询参数。
* Cookies。
- * Headers。
- * Forms。
- * Files。
+ * 请求头。
+ * 表单。
+ * 文件。
*
转换输出数据：从 Python 数据和类型转换为网络数据（JSON）：
* 转换 Python 类型（`str`、`int`、`float`、`bool`、`list` 等）。
* `datetime` 对象。
@@ -473,10 +473,10 @@ item: Item
**剧透警告**：教程 - 用户指南包括：
-* 来自不同位置的**参数**声明：**headers**、**cookies**、**form 字段**和**文件**。
+* 来自不同位置的**参数**声明：**请求头**、**cookies**、**表单字段**和**文件**。
* 如何设置**校验约束**，如 `maximum_length` 或 `regex`。
* 功能强大且易用的 **
依赖注入** 系统。
-* 安全与认证，包括对 **OAuth2**、**JWT tokens** 和 **HTTP Basic** 认证的支持。
+* 安全与认证，包括对结合 **JWT tokens** 的 **OAuth2** 和 **HTTP Basic** 认证的支持。
* 更高级（但同样简单）的 **多层嵌套 JSON 模型** 声明技巧（得益于 Pydantic）。
* 通过 [Strawberry](https://strawberry.rocks) 等库进行 **GraphQL** 集成。
* 许多额外特性（归功于 Starlette），例如：
@@ -544,7 +544,7 @@ Pydantic 使用：
Starlette 使用：
-* [`httpx`](https://www.python-httpx.org) - 使用 `TestClient` 时需要。
+* [`httpx2`](https://pydantic.dev/docs/httpx2/)（或 `httpx`）- 供 `TestClient` 使用。
* [`jinja2`](https://jinja.palletsprojects.com) - 使用默认模板配置时需要。
* [`python-multipart`](https://github.com/Kludex/python-multipart) - 使用 `request.form()` 支持表单
「解析」时需要。
diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md
index fb2139640c..d312ab2db8 100644
--- a/docs/zh/docs/tutorial/bigger-applications.md
+++ b/docs/zh/docs/tutorial/bigger-applications.md
@@ -155,15 +155,14 @@ from app.routers import items
```Python hl_lines="1"
@router.get("/{item_id}")
-async def read_item(item_id: str):
- ...
+async def read_item(item_id: str): ...
```
...前缀不能以 `/` 作为结尾。
因此，本例中的前缀为 `/items`。
-我们还可以添加一个 `tags` 列表和额外的 `responses` 列表，这些参数将应用于此路由器中包含的所有*路径操作*。
+我们还可以添加一个 `tags` 列表和额外的 `responses`，这些参数将应用于此路由器中包含的所有*路径操作*。
我们可以添加一个 `dependencies` 列表，这些依赖项将被添加到路由器中的所有*路径操作*中，并将针对向它们发起的每个请求执行/解决。
@@ -269,13 +268,13 @@ from ...dependencies import get_token_header
* 在该父包中，找到 `dependencies` 模块（位于 `app/dependencies.py` 的文件）...
* 然后从中导入函数 `get_token_header`。
-这将引用 `app/` 的往上一级，带有其自己的 `__init __.py` 等文件的某个包。但是我们并没有这个包。因此，这将在我们的示例中引发错误。🚨
+这将引用 `app/` 的往上一级，带有其自己的 `__init__.py` 等文件的某个包。但是我们并没有这个包。因此，这将在我们的示例中引发错误。🚨
但是现在你知道了它的工作原理，因此无论它们多么复杂，你都可以在自己的应用程序中使用相对导入。🤓
### 添加一些自定义的 `tags`、`responses` 和 `dependencies` { #add-some-custom-tags-responses-and-dependencies }
-我们不打算在每个*路径操作*中添加前缀 `/items` 或 `tags =["items"]`，因为我们将它们添加到了 `APIRouter` 中。
+我们不打算在每个*路径操作*中添加前缀 `/items` 或 `tags=["items"]`，因为我们将它们添加到了 `APIRouter` 中。
但是我们仍然可以添加*更多*将会应用于特定的*路径操作*的 `tags`，以及一些特定于该*路径操作*的额外 `responses`：
@@ -313,7 +312,7 @@ from ...dependencies import get_token_header
{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[4:5] title["app/main.py"] *}
-由于文件 `app/routers/users.py` 和 `app/routers/items.py` 是同一 Python 包 `app` 一个部分的子模块，因此我们可以使用单个点 ` .` 通过「相对导入」来导入它们。
+由于文件 `app/routers/users.py` 和 `app/routers/items.py` 是同一 Python 包 `app` 一个部分的子模块，因此我们可以使用单个点 `.` 通过「相对导入」来导入它们。
### 导入是如何工作的 { #how-the-importing-works }
@@ -422,7 +421,7 @@ from .routers.users import router
{* ../../docs_src/bigger_applications/app_an_py310/internal/admin.py hl[3] title["app/internal/admin.py"] *}
-但是我们仍然希望在包含 `APIRouter` 时设置一个自定义的 `prefix`，以便其所有*路径操作*以 `/admin` 开头，我们希望使用本项目已经有的 `dependencies` 保护它，并且我们希望它包含自定义的 `tags` 和 `responses`。
+但是我们仍然希望在包含 `APIRouter` 时设置一个自定义的 `prefix`，以便其所有*路径操作*以 `/admin` 开头，我们希望使用本项目已经有的 `dependencies` 保护它，并且我们希望它包含 `tags` 和 `responses`。
我们可以通过将这些参数传递给 `app.include_router()` 来完成所有的声明，而不必修改原始的 `APIRouter`：
diff --git a/docs/zh/docs/tutorial/body-fields.md b/docs/zh/docs/tutorial/body-fields.md
index 36be7c4191..88eaafcac5 100644
--- a/docs/zh/docs/tutorial/body-fields.md
+++ b/docs/zh/docs/tutorial/body-fields.md
@@ -42,13 +42,13 @@ Pydantic 的 `Field` 返回也是 `FieldInfo` 的类实例。
## 添加更多信息 { #add-extra-information }
-`Field`、`Query`、`Body` 等对象里可以声明更多信息，并且 JSON Schema 中也会集成这些信息。
+可以在 `Field`、`Query`、`Body` 等对象里使用 `json_schema_extra` 声明更多信息，并且生成的 JSON Schema 中也会集成这些信息。
*声明示例*一章中将详细介绍添加更多信息的知识。
/// warning | 警告
-传递给 `Field` 的额外键也会出现在你的应用生成的 OpenAPI 架构中。
+在 `json_schema_extra` 中传递的额外键也会出现在你的应用生成的 OpenAPI 架构中。
由于这些键不一定属于 OpenAPI 规范的一部分，某些 OpenAPI 工具（例如 [OpenAPI 验证器](https://validator.swagger.io/)）可能无法处理你生成的架构。
///
@@ -57,4 +57,4 @@ Pydantic 的 `Field` 返回也是 `FieldInfo` 的类实例。
Pydantic 的 `Field` 可以为模型属性声明更多校验和元数据。
-传递 JSON Schema 元数据还可以使用更多关键字参数。
+还可以使用 `json_schema_extra` 传递额外的 JSON Schema 元数据。
diff --git a/docs/zh/docs/tutorial/cookie-param-models.md b/docs/zh/docs/tutorial/cookie-param-models.md
index 368fe47626..0d3eeb0386 100644
--- a/docs/zh/docs/tutorial/cookie-param-models.md
+++ b/docs/zh/docs/tutorial/cookie-param-models.md
@@ -71,6 +71,22 @@
}
```
+## 组合参数模型 { #combine-parameter-models }
+
+你可以将多个 cookie 参数模型与单独的 cookie 参数及依赖项组合使用。每个模型都会独立提取和验证，具体说明请参阅[查询参数模型](query-param-models.md#combine-parameter-models)。
+
+每个模型的 `extra` 配置适用于所有 cookie 参数，包括在其他模型或依赖项中声明的参数。使用 `extra="forbid"` 时，该模型之外的任何 cookie 都会被拒绝。使用 `extra="allow"` 时，这些 cookie 会作为模型的额外字段包含在内。
+
+## 可选 Cookie 参数模型 { #optional-cookie-parameter-models }
+
+使用 `| None` 并将默认值设为 `None` 来声明 cookie 参数模型，即可将这组参数设为可选。
+
+{* ../../docs_src/cookie_param_models/tutorial003_an_py310.py hl[15] *}
+
+如果既未发送 `theme` 也未发送 `locale`，则 `preferences` 为 `None`。如果发送了其中任意一个，FastAPI 就会验证模型，并要求两个字段都存在。
+
+默认值、额外字段和 OpenAPI 的规则与[可选查询参数模型](query-param-models.md#optional-query-parameter-models)相同。
+
## 总结 { #summary }
你可以使用 **Pydantic 模型**在 **FastAPI** 中声明
**cookie**。😎
diff --git a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
index a57271c8e7..f5cad3dcaf 100644
--- a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
@@ -58,14 +58,16 @@ query_extractor --> query_or_cookie_extractor --> read_query
如果在同一个*路径操作* 多次声明了同一个依赖项，例如，多个依赖项共用一个子依赖项，**FastAPI** 在处理同一请求时，只调用一次该子依赖项。
-FastAPI 不会为同一个请求多次调用同一个依赖项，而是把依赖项的返回值进行
「缓存」，并把它传递给同一请求中所有需要使用该返回值的「依赖项」。
+FastAPI 不会为同一个请求多次调用同一个依赖项，而是把依赖项的返回值进行
「缓存」，并把它传递给同一请求中所有需要使用该返回值的「依赖方」。
-在高级使用场景中，如果不想使用「缓存」值，而是为需要在同一请求的每一步操作（多次）中都实际调用依赖项，可以把 `Depends` 的参数 `use_cache` 的值设置为 `False`:
+在高级使用场景中，如果不想使用「缓存」值，而是需要在同一请求的每一步操作（可能多次）中都实际调用依赖项，可以在使用 `Depends` 时设置参数 `use_cache=False`：
//// tab | Python 3.10+
-```Python hl_lines="1"
-async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_cache=False)]):
+```Python hl_lines="2"
+async def needy_dependency(
+ fresh_value: Annotated[str, Depends(get_value, use_cache=False)],
+):
return {"fresh_value": fresh_value}
```
diff --git a/docs/zh/docs/tutorial/extra-models.md b/docs/zh/docs/tutorial/extra-models.md
index 5672ccbb2d..6fc7aa0b6b 100644
--- a/docs/zh/docs/tutorial/extra-models.md
+++ b/docs/zh/docs/tutorial/extra-models.md
@@ -55,10 +55,10 @@ print(user_dict)
```Python
{
- 'username': 'john',
- 'password': 'secret',
- 'email': 'john.doe@example.com',
- 'full_name': None,
+ "username": "john",
+ "password": "secret",
+ "email": "john.doe@example.com",
+ "full_name": None,
}
```
@@ -87,10 +87,10 @@ UserInDB(
```Python
UserInDB(
- username = user_dict["username"],
- password = user_dict["password"],
- email = user_dict["email"],
- full_name = user_dict["full_name"],
+ username=user_dict["username"],
+ password=user_dict["password"],
+ email=user_dict["email"],
+ full_name=user_dict["full_name"],
)
```
@@ -125,11 +125,11 @@ UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
```Python
UserInDB(
- username = user_dict["username"],
- password = user_dict["password"],
- email = user_dict["email"],
- full_name = user_dict["full_name"],
- hashed_password = hashed_password,
+ username=user_dict["username"],
+ password=user_dict["password"],
+ email=user_dict["email"],
+ full_name=user_dict["full_name"],
+ hashed_password=hashed_password,
)
```
diff --git a/docs/zh/docs/tutorial/header-param-models.md b/docs/zh/docs/tutorial/header-param-models.md
index e7d5483173..43805d1cac 100644
--- a/docs/zh/docs/tutorial/header-param-models.md
+++ b/docs/zh/docs/tutorial/header-param-models.md
@@ -67,6 +67,26 @@
///
+## 组合参数模型 { #combine-parameter-models }
+
+你可以将多个 header 参数模型与单独的 header 参数及依赖项组合使用。每个模型都会独立提取和验证，如[查询参数模型](query-param-models.md#combine-parameter-models)中所述。
+
+每个模型的 `extra` 配置都适用于所有 header 参数，包括在其他模型或依赖项中声明的参数。使用 `extra="forbid"` 时，不属于该模型的任何 header 都会被拒绝。使用 `extra="allow"` 时，这些 headers 会作为模型的额外字段包含在内。
+
+每个模型在读取请求和生成 OpenAPI 时，都会使用各自的 `Header(convert_underscores=...)` 设置。显式指定的字段别名会原样用作 header 名称。
+
+## 可选的 Header 参数模型 { #optional-header-parameter-models }
+
+使用 `| None` 声明 header 参数模型，并将默认值设为 `None`，即可将这组参数设为可选。
+
+{* ../../docs_src/header_param_models/tutorial004_an_py310.py hl[15] *}
+
+如果既未发送 `x-client-name` 也未发送 `x-client-version`，则 `client` 为 `None`。如果发送了其中任意一个，FastAPI 就会验证模型，并要求提供这两个字段。
+
+默认值、额外字段和 OpenAPI 的规则与[可选的查询参数模型](query-param-models.md#optional-query-parameter-models)相同。
+
+`Host` 等 headers 也遵循模型的 `extra` 配置。使用 `extra="allow"` 时，即使未提供任何一个已声明的字段，这些 headers 也会使模型被视为已提供。
+
## 总结 { #summary }
您可以使用 **Pydantic 模型**在 **FastAPI** 中声明 **headers**。😎
diff --git a/docs/zh/docs/tutorial/path-params-numeric-validations.md b/docs/zh/docs/tutorial/path-params-numeric-validations.md
index cb4985119c..30cd1d139d 100644
--- a/docs/zh/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/zh/docs/tutorial/path-params-numeric-validations.md
@@ -28,7 +28,7 @@ FastAPI 在 0.95.0 版本添加了对 `Annotated` 的支持（并开始推荐使
/// note | 注意
-路径参数总是必需的，因为它必须是路径的一部分。即使你将其声明为 `None` 或设置了默认值，也不会产生任何影响，它依然始终是必需参数。
+路径参数总是必需的，因为它必须是 URL 路径的一部分。在其类型中添加 `None` 并不会使其变为可选参数。使用 `Path` 声明的参数不能有默认值。
///
@@ -68,7 +68,7 @@ FastAPI 在 0.95.0 版本添加了对 `Annotated` 的支持（并开始推荐使
///
-这里有一个小技巧，可能会很方便，但你并不会经常需要它。
+这里有一个**小技巧**，可能会很方便，但你并不会经常需要它。
如果你想要：
@@ -81,7 +81,7 @@ FastAPI 在 0.95.0 版本添加了对 `Annotated` 的支持（并开始推荐使
在函数的第一个参数位置传入 `*`。
-Python 不会对这个 `*` 做任何事，但它会知道之后的所有参数都应该作为关键字参数（键值对）来调用，也被称为
kwargs。即使它们没有默认值。
+Python 不会对这个 `*` 做任何事，但它会知道之后的所有参数都应该作为关键字参数（键值对）来调用，也被称为
kwargs。即使它们没有默认值。
{* ../../docs_src/path_params_numeric_validations/tutorial003_py310.py hl[7] *}
@@ -95,7 +95,7 @@ Python 不会对这个 `*` 做任何事，但它会知道之后的所有参数
使用 `Query` 和 `Path`（以及你稍后会看到的其他类）你可以声明数值约束。
-在这里，使用 `ge=1` 后，`item_id` 必须是一个整数，值要「`g`reater than or `e`qual」1。
+在这里，使用 `ge=1` 后，`item_id` 必须是一个整数，值要大于等于（`g`reater than or `e`qual）`1`。
{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py310.py hl[10] *}
diff --git a/docs/zh/docs/tutorial/query-param-models.md b/docs/zh/docs/tutorial/query-param-models.md
index fc691839d5..a3fdaeecab 100644
--- a/docs/zh/docs/tutorial/query-param-models.md
+++ b/docs/zh/docs/tutorial/query-param-models.md
@@ -16,7 +16,7 @@ FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓
{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
-**FastAPI** 将会从请求的**查询参数**中**提取**出**每个字段**的数据，并将其提供给你定义的 Pydantic 模型。
+**FastAPI** 将会从请求的**查询参数**中**提取**出**每个字段**的数据，并将你定义的 Pydantic 模型提供给你。
## 查看文档 { #check-the-docs }
@@ -57,6 +57,42 @@ https://example.com/items/?limit=10&tool=plumbus
}
```
+## 组合参数模型 { #combine-parameter-models }
+
+你可以声明多个查询参数模型，并将它们与单独的查询参数或依赖项组合使用。
+
+{* ../../docs_src/query_param_models/tutorial003_an_py310.py hl[9:15,20:22] *}
+
+请求参数仍处于同一层级。
+
+```http
+https://example.com/items/?limit=5&offset=10&tags=red&tags=blue&search=shirt
+```
+
+查询字符串中没有 `pagination` 或 `filters` 键。每个模型都使用自己的默认值、字段验证器和模型验证器独立验证查询参数。在依赖项中声明模型或单独的参数时也是如此。
+
+如果模型共享参数名或别名，每个模型都会独立验证该请求参数。对于相互独立的值，请使用不同的名称或别名。OpenAPI 只会列出共享参数一次，就像处理与依赖项共享的参数一样，因此共享参数的声明应描述相同的类型和约束。
+
+每个模型的 `extra` 配置都适用于所有查询参数，包括在其他模型或依赖项中声明的参数。使用 `extra="forbid"` 时，该模型之外的任何参数都会被拒绝。使用 `extra="allow"` 时，这些参数会作为模型的额外数据被包含在内。
+
+这同样适用于 `Header` 和 `Cookie` 模型。
+
+## 可选查询参数模型 { #optional-query-parameter-models }
+
+声明查询参数模型时，使用 `| None` 并将默认值设为 `None`，即可使这组参数变为可选。
+
+{* ../../docs_src/query_param_models/tutorial004_an_py310.py hl[18] *}
+
+如果既未发送 `start` 也未发送 `end`，则 `date_range` 为 `None`。如果发送了其中任意一个，FastAPI 就会验证模型，并要求提供两个字段。
+
+使用 `| None` 但不设置默认值时，该参数仍然是必需的。
+
+额外参数遵循模型的 `extra` 配置。被忽略的额外参数不会使模型被视为已提供。
+
+OpenAPI 会逐一列出这组参数的字段，并将它们标记为可选。
+
+你也可以声明可选的 [header 参数模型](header-param-models.md#optional-header-parameter-models)和 [cookie 参数模型](cookie-param-models.md#optional-cookie-parameter-models)。
+
## 总结 { #summary }
你可以使用 **Pydantic 模型**在 **FastAPI** 中声明**查询参数**。😎
diff --git a/docs/zh/docs/tutorial/query-params-str-validations.md b/docs/zh/docs/tutorial/query-params-str-validations.md
index 88d4306f0b..81405c47eb 100644
--- a/docs/zh/docs/tutorial/query-params-str-validations.md
+++ b/docs/zh/docs/tutorial/query-params-str-validations.md
@@ -220,14 +220,22 @@ q: Annotated[str | None, Query(min_length=3)] = None
{* ../../docs_src/query_params_str_validations/tutorial006_an_py310.py hl[9] *}
-### 必填，但可以为 `None` { #required-can-be-none }
+### 必填参数与 `None` { #required-parameters-and-none }
-你可以声明一个参数可以接收 `None`，但它仍然是必填的。这将强制客户端必须发送一个值，即使该值是 `None`。
-
-为此，你可以声明 `None` 是有效类型，但不声明默认值：
+类型 `str | None` 允许使用 Python 值 `None`，但不会让查询参数变为可选。没有默认值时，该参数仍然是必填的：
{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
+查询参数值以字符串形式传入，没有内置的 `None` 表示方式。发送 `?q=None` 或 `?q=null` 分别传入的是字符串 `"None"` 和 `"null"`。发送 `?q=` 传入的是空字符串，在此示例中无法通过 `min_length=3` 校验。
+
+要允许客户端省略 `q` 并使用 `None` 作为其值，请将其默认值设为 `None`：
+
+```Python
+q: Annotated[str | None, Query(min_length=3)] = None
+```
+
+与查询参数不同，JSON 请求体可以包含显式的 `null` 值。
+
## 查询参数列表 / 多个值 { #query-parameter-list-multiple-values }
当你用 `Query` 显式地定义查询参数时，你还可以声明它接收一个值列表，换句话说，接收多个值。
diff --git a/docs/zh/docs/tutorial/query-params.md b/docs/zh/docs/tutorial/query-params.md
index 971dbb0ede..02dda8dbdd 100644
--- a/docs/zh/docs/tutorial/query-params.md
+++ b/docs/zh/docs/tutorial/query-params.md
@@ -31,7 +31,7 @@ http://127.0.0.1:8000/items/?skip=0&limit=10
## 默认值 { #defaults }
-查询参数不是路径的固定内容，它是可选的，还支持默认值。
+查询参数不是路径的固定内容，它可以是可选的，还支持默认值。
上例用 `skip=0` 和 `limit=10` 设定默认值。
@@ -108,14 +108,20 @@ http://127.0.0.1:8000/items/foo?short=on
http://127.0.0.1:8000/items/foo?short=yes
```
-或其它任意大小写形式（大写、首字母大写等），函数接收的 `short` 参数都是布尔值 `True`。否则为 `False`。
+或其它任意大小写形式（大写、首字母大写等），函数接收的 `short` 参数都是布尔值 `True`。
+
+`0`、`false`、`off` 和 `no` 等值（包括大小写变体）会转换为 `False`。
+
+如果省略 `short`，**FastAPI** 会使用它的默认值，本例中为 `False`。
+
+空值（`?short=`）或无法识别的值（例如 `?short=maybe`）会导致 `422` 校验错误。
## 多个路径和查询参数 { #multiple-path-and-query-parameters }
**FastAPI** 可以识别同时声明的多个路径参数和查询参数。
-而且声明查询参数的顺序并不重要。
+而且声明这些参数的顺序并不重要。
FastAPI 通过参数名进行检测：
@@ -139,7 +145,7 @@ FastAPI 通过参数名进行检测：
http://127.0.0.1:8000/items/foo-item
```
-...因为路径中没有必选参数 `needy`，返回的响应中会显示如下错误信息：
+...因为没有添加必选参数 `needy`，返回的响应中会显示如下错误信息：
```JSON
{
diff --git a/docs/zh/docs/tutorial/request-form-models.md b/docs/zh/docs/tutorial/request-form-models.md
index 9b3de06179..8fe4387c53 100644
--- a/docs/zh/docs/tutorial/request-form-models.md
+++ b/docs/zh/docs/tutorial/request-form-models.md
@@ -28,6 +28,8 @@ $ uv add python-multipart
**FastAPI** 将从请求中的**表单数据**中**提取**出**每个字段**的数据，并提供你定义的 Pydantic 模型。
+对于 [HTML 复选框](request-forms.md#boolean-form-fields)，请将布尔字段的默认值声明为 `False`。
+
## 检查文档 { #check-the-docs }
你可以在文档 UI 中验证它，地址为 `/docs`：
@@ -73,6 +75,58 @@ $ uv add python-multipart
}
```
+## 组合表单模型 { #combine-form-models }
+
+你可以将多个表单模型与单独的 `Form` 参数组合使用。
+
+{* ../../docs_src/request_form_models/tutorial003_an_py310.py hl[9:14,19:21] *}
+
+客户端将 `name`、`tags` 和 `token` 作为表单字段发送。每个模型独立验证表单字段。
+
+每个模型的 `extra` 配置都适用于所有表单字段，包括在其他参数或依赖项中声明的字段和文件。使用 `extra="forbid"` 时，该模型之外的任何字段都会被拒绝。使用 `extra="allow"` 时，这些字段会作为模型的额外数据被包含进来。
+
+如果多个声明使用相同的表单字段名，每个声明都会验证该字段的值。请为共享字段使用兼容的类型和约束，以便 OpenAPI schema 能一致地描述它们。
+
+## 可选表单模型 { #optional-form-models }
+
+使用 `| None` 并将默认值设为 `None` 来声明表单模型，即可使这组字段变为可选。
+
+{* ../../docs_src/request_form_models/tutorial005_an_py310.py hl[17] *}
+
+如果既未发送 `name` 也未发送 `age`，则 `profile` 为 `None`。如果发送了其中任意一个字段，FastAPI 就会验证模型，并要求提供这两个字段。提交空值也算作提供了字段。
+
+使用 `| None` 但不设置默认值时，该参数仍然是必填的。
+
+额外字段遵循模型的 `extra` 配置。被忽略的额外字段不会使模型被视为已提供。
+
+仅包含未勾选复选框的可选模型会被省略。发送 `enabled=false` 这样的值可以显式提供该模型。
+
+## 可选的表单模型联合类型 { #optional-unions-of-form-models }
+
+你也可以使用可选的模型联合类型。
+
+{* ../../docs_src/request_form_models/tutorial006_an_py310.py hl[9:16,21] *}
+
+如果未发送任何表单字段，则 `contact` 为 `None`。发送 `kind=person` 和 `name`，或发送 `kind=company` 和 `company_name`。判别器会选择要验证的模型。
+
+## 组合表单模型联合类型 { #combine-unions-of-form-models }
+
+你可以将联合类型与其他表单模型、单独的 `Form` 参数以及 `File` 参数组合使用。每个联合类型都会独立验证。
+
+{* ../../docs_src/request_form_models/tutorial007_an_py310.py hl[31:35] *}
+
+在同一个表单中发送所有字段。例如，发送 `contact_type=person`、`name=Rick`、`notification_type=email`、`email=rick@example.com` 和 `token=secret`。
+
+省略通知字段即可让 `notification` 保持为 `None`。
+
+## 表单模型与文件 { #form-models-and-files }
+
+你也可以将表单模型与[文件参数](request-files.md)组合使用。
+
+{* ../../docs_src/request_form_models/tutorial004_an_py310.py hl[14] *}
+
+这里，客户端使用 `multipart/form-data` 发送 `name` 字段和 `avatar` 文件。
+
## 总结 { #summary }
你可以使用 Pydantic 模型在 FastAPI 中声明表单字段。😎
diff --git a/docs/zh/docs/tutorial/request-forms.md b/docs/zh/docs/tutorial/request-forms.md
index 6da128a83f..a7e5150890 100644
--- a/docs/zh/docs/tutorial/request-forms.md
+++ b/docs/zh/docs/tutorial/request-forms.md
@@ -44,6 +44,14 @@ $ uv add python-multipart
///
+## 布尔表单字段 { #boolean-form-fields }
+
+浏览器在提交 HTML 表单时会忽略未选中的复选框。将布尔表单参数的默认值声明为 `False`，即可在复选框未选中时接收到 `False`：
+
+{* ../../docs_src/request_forms/tutorial002_an_py310.py hl[9] *}
+
+选中的复选框会发送其值，默认值为 `"on"`。**FastAPI** 会将 `"on"` 解析为 `True`。
+
## 关于 "表单字段" { #about-form-fields }
HTML 表单（`
`）向服务器发送数据时通常会对数据使用一种“特殊”的编码方式，这与 JSON 不同。
@@ -56,6 +64,8 @@ HTML 表单（`
`）向服务器发送数据时通常会对数据使
但当表单包含文件时，会编码为 `multipart/form-data`。你将在下一章阅读如何处理文件。
+你可以使用 `Form(media_type="multipart/form-data")` 在 OpenAPI 中描述多部分表单。组合使用表单参数或模型时，只需在一个参数上设置即可。
+
如果你想了解更多关于这些编码和表单字段的信息，请参阅 [
MDN Web 文档的 `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)。
///
diff --git a/docs/zh/docs/tutorial/response-model.md b/docs/zh/docs/tutorial/response-model.md
index 5cdfee2176..afafe6bdfc 100644
--- a/docs/zh/docs/tutorial/response-model.md
+++ b/docs/zh/docs/tutorial/response-model.md
@@ -42,7 +42,7 @@ FastAPI 会使用这个返回类型来：
/// note | 注意
-注意，`response_model` 是「装饰器」方法（`get`、`post` 等）的一个参数。不是你的*路径操作函数*的参数，不像所有查询参数和请求体那样。
+注意，`response_model` 是「装饰器」方法（`get`、`post` 等）的一个参数。不是你的*路径操作函数*的参数，不像所有参数和请求体那样。
///
@@ -266,6 +266,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承
但是，如果你的数据在具有默认值的模型字段中有实际的值，例如 ID 为 `bar` 的项：
+
```Python hl_lines="3 5"
{
"name": "Bar",
@@ -274,6 +275,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承
"tax": 20.2
}
```
+
这些值将包含在响应中。
@@ -281,6 +283,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承
如果数据具有与默认值相同的值，例如 ID 为 `baz` 的项：
+
```Python hl_lines="3 5-6"
{
"name": "Baz",
@@ -290,6 +293,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承
"tags": []
}
```
+
FastAPI 足够聪明（实际上是 Pydantic 足够聪明）去认识到，即使 `description`、`tax` 和 `tags` 的值与默认值相同，它们也是被显式设置的（而不是取自默认值）。
diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md
index 92cf02dd25..4721595b43 100644
--- a/docs/zh/docs/tutorial/security/simple-oauth2.md
+++ b/docs/zh/docs/tutorial/security/simple-oauth2.md
@@ -136,11 +136,11 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。
```Python
UserInDB(
- username = user_dict["username"],
- email = user_dict["email"],
- full_name = user_dict["full_name"],
- disabled = user_dict["disabled"],
- hashed_password = user_dict["hashed_password"],
+ username=user_dict["username"],
+ email=user_dict["email"],
+ full_name=user_dict["full_name"],
+ disabled=user_dict["disabled"],
+ hashed_password=user_dict["hashed_password"],
)
```