🌐 Update Chinese translation for `docs/zh/docs/tutorial/body.md` (#3481)

Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

diff --git a/docs/zh/docs/tutorial/body.md b/docs/zh/docs/tutorial/body.md
index 3d615be399d86616cae7e3c7a40574e368600632..fa8b54d0245eebc2c46ac3aa1f94a310e835b6fc 100644 (file)
--- a/docs/zh/docs/tutorial/body.md
+++ b/docs/zh/docs/tutorial/body.md
@@ -1,21 +1,24 @@
 # 请求体
 
-当你需要将数据从客户端（例如浏览器）发送给 API 时，你将其作为「请求体」发送。
+FastAPI 使用**请求体**从客户端（例如浏览器）向 API 发送数据。
 
-**请求**体是客户端发送给 API 的数据。**响应**体是 API 发送给客户端的数据。
+**请求体**是客户端发送给 API 的数据。**响应体**是 API 发送给客户端的数据。
 
-你的 API 几乎总是要发送**响应**体。但是客户端并不总是需要发送**请求**体。
+API 基本上肯定要发送**响应体**，但是客户端不一定发送**请求体**。
 
-我们使用 <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> 模型来声明**请求**体，并能够获得它们所具有的所有能力和优点。
+使用 <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> 模型声明**请求体**，能充分利用它的功能和优点。
 
-!!! info
-    你不能使用 `GET` 操作（HTTP 方法）发送请求体。
+!!! info "说明"
 
-    要发送数据，你必须使用下列方法之一：`POST`（较常见）、`PUT`、`DELETE` 或 `PATCH`。
+    发送数据使用 `POST`（最常用）、`PUT`、`DELETE`、`PATCH` 等操作。
+
+    规范中没有定义使用 `GET` 发送请求体的操作，但不管怎样，FastAPI 也支持这种方式，只不过仅用于非常复杂或极端的用例。
+
+    我们不建议使用 `GET`，因此，在 Swagger UI 交互文档中不会显示有关 `GET` 的内容，而且代理协议也不一定支持 `GET`。
 
 ## 导入 Pydantic 的 `BaseModel`
 
-首先，你需要从 `pydantic` 中导入 `BaseModel`：
+从 `pydantic` 中导入 `BaseModel`：
 
 === "Python 3.10+"
 
@@ -31,9 +34,9 @@
 
 ## 创建数据模型
 
-然后，将你的数据模型声明为继承自 `BaseModel` 的类。
+把数据模型声明为继承 `BaseModel` 的类。
 
-使用标准的 Python 类型来声明所有属性：
+使用 Python 标准类型声明所有属性：
 
 === "Python 3.10+"
 
@@ -47,9 +50,9 @@
     {!> ../../../docs_src/body/tutorial001.py!}
     ```
 
-和声明查询参数时一样，当一个模型属性具有默认值时，它不是必需的。否则它是一个必需属性。将默认值设为 `None` 可使其成为可选属性。
+与声明查询参数一样，包含默认值的模型属性是可选的，否则就是必选的。默认值为 `None` 的模型属性也是可选的。
 
-例如，上面的模型声明了一个这样的 JSON「`object`」（或 Python `dict`）：
+例如，上述模型声明如下 JSON **对象**（即 Python **字典**）：
 
 ```JSON
 {
@@ -60,7 +63,7 @@
 }
 ```
 
-...由于 `description` 和 `tax` 是可选的（它们的默认值为 `None`），下面的 JSON「`object`」也将是有效的：
+……由于 `description` 和 `tax` 是可选的（默认值为 `None`），下面的 JSON **对象**也有效：
 
 ```JSON
 {
@@ -69,9 +72,9 @@
 }
 ```
 
-## 声明为参数
+## 声明请求体参数
 
-使ç\94¨ä¸\8e声æ\98\8eè·¯å¾\84å\92\8cæ\9f¥è¯¢å\8f\82æ\95°ç\9a\84ç\9b¸å\90\8cæ\96¹å¼\8f声æ\98\8e请æ±\82ä½\93ï¼\8cå\8d³å\8f¯å°\86å\85¶æ·»å\8a å\88°ã\80\8cè·¯å¾\84æ\93\8dä½\9cã\80\8d中：
+使ç\94¨ä¸\8e声æ\98\8eè·¯å¾\84å\92\8cæ\9f¥è¯¢å\8f\82æ\95°ç\9b¸å\90\8cç\9a\84æ\96¹å¼\8f声æ\98\8e请æ±\82ä½\93ï¼\8cæ\8a\8a请æ±\82ä½\93æ·»å\8a è\87³*è·¯å¾\84æ\93\8dä½\9c*：
 
 === "Python 3.10+"
 
@@ -85,56 +88,68 @@
     {!> ../../../docs_src/body/tutorial001.py!}
     ```
 
-...并且将它的类型声明为你创建的 `Item` 模型。
+……此处，请求体参数的类型为 `Item` 模型。
 
-## 结果
+## 结论
 
-ä»\85ä»\85使ç\94¨äº\86 Python ç±»å\9e\8b声æ\98\8eï¼\8c**FastAPI** å°\86ä¼\9a：
+ä»\85使ç\94¨ Python ç±»å\9e\8b声æ\98\8eï¼\8c**FastAPI** å°±å\8f¯ä»¥：
 
-* 将请求体作为 JSON 读取。
-* 转换为相应的类型（在需要时）。
-* 校验数据。
-    * 如果数据无效，将返回一条清晰易读的错误信息，指出不正确数据的确切位置和内容。
-* 将接收的数据赋值到参数 `item` 中。
-    * 由于你已经在函数中将它声明为 `Item` 类型，你还将获得对于所有属性及其类型的一切编辑器支持（代码补全等）。
-* 为你的模型生成 <a href="https://json-schema.org" class="external-link" target="_blank">JSON 模式</a> 定义，你还可以在其他任何对你的项目有意义的地方使用它们。
-* è¿\99äº\9b模å¼\8få°\86æ\88\90为ç\94\9fæ\88\90ç\9a\84 OpenAPI 模å¼\8fç\9a\84ä¸\80é\83¨å\88\86ï¼\8c并ä¸\94被è\87ªå\8a¨å\8c\96æ\96\87æ¡£ <abbr title="ç\94¨æ\88·ç\95\8cé\9d¢">UI</abbr> æ\89\80使ç\94¨ã\80\82
+* 以 JSON 形式读取请求体
+* （在必要时）把请求体转换为对应的类型
+* 校验数据：
+    * 数据无效时返回错误信息，并指出错误数据的确切位置和内容
+* 把接收的数据赋值给参数 `item`
+    * 把函数中请求体参数的类型声明为 `Item`，还能获得代码补全等编辑器支持
+* 为模型生成 <a href="https://json-schema.org" class="external-link" target="_blank">JSON Schema</a>，在项目中所需的位置使用
+* è¿\99äº\9bæ¦\82å\9b¾æ\98¯ OpenAPI æ¦\82å\9b¾ç\9a\84é\83¨ä»¶ï¼\8cç\94¨äº\8e API æ\96\87æ¡£ <abbr title="ç\94¨æ\88·ç\95\8cé\9d¢">UI</abbr>
 
-## 自动化文档
+## API 文档
 
-你所定义模型的 JSON 模式将成为生成的 OpenAPI 模式的一部分，并且在交互式 API 文档中展示：
+Pydantic 模型的 JSON 概图是 OpenAPI 生成的概图部件，可在 API 文档中显示：
 
-<img src="https://fastapi.tiangolo.com/img/tutorial/body/image01.png">
+<img src="/img/tutorial/body/image01.png">
 
-而且还将在每一个需要它们的*路径操作*的 API 文档中使用：
+而且，还会用于 API 文档中使用了概图的*路径操作*：
 
-<img src="https://fastapi.tiangolo.com/img/tutorial/body/image02.png">
+<img src="/img/tutorial/body/image02.png">
 
 ## 编辑器支持
 
-在你的编辑器中，你会在函数内部的任意地方得到类型提示和代码补全（如果你接收的是一个 `dict` 而不是 Pydantic 模型，则不会发生这种情况）：
+在编辑器中，函数内部均可使用类型提示、代码补全（如果接收的不是 Pydantic 模型，而是**字典**，就没有这样的支持）：
+
+<img src="/img/tutorial/body/image03.png">
+
+还支持检查错误的类型操作：
+
+<img src="/img/tutorial/body/image04.png">
 
-<img src="https://fastapi.tiangolo.com/img/tutorial/body/image03.png">
+这并非偶然，整个 **FastAPI** 框架都是围绕这种思路精心设计的。
 
-你还会获得对不正确的类型操作的错误检查：
+并且，在 FastAPI 的设计阶段，我们就已经进行了全面测试，以确保 FastAPI 可以获得所有编辑器的支持。
 
-<img src="https://fastapi.tiangolo.com/img/tutorial/body/image04.png">
+我们还改进了 Pydantic，让它也支持这些功能。
 
-è¿\99并é\9d\9eå\81¶ç\84¶ï¼\8cæ\95´ä¸ªæ¡\86æ\9e¶é\83½æ\98¯å\9b´ç»\95该设计è\80\8cæ\9e\84建。
+è\99½ç\84¶ä¸\8aé\9d¢ç\9a\84æ\88ªå\9b¾å\8f\96è\87ª <a href="https://code.visualstudio.com" class="external-link" target="_blank">Visual Studio Code</a>。
 
-并且在进行任何实现之前，已经在设计阶段经过了全面测试，以确保它可以在所有的编辑器中生效。
+但 <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> 和大多数 Python 编辑器也支持同样的功能：
 
-Pydantic 本身甚至也进行了一些更改以支持此功能。
+<img src="/img/tutorial/body/image05.png">
 
-上面的截图取自 <a href="https://code.visualstudio.com" class="external-link" target="_blank">Visual Studio Code</a>。
+!!! tip "提示"
 
-但是在 <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> 和绝大多数其他 Python 编辑器中你也会获得同样的编辑器支持：
+    使用 <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> 编辑器时，推荐安装 <a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm 插件</a>。
 
-<img src="https://fastapi.tiangolo.com/img/tutorial/body/image05.png">
+    该插件用于完善 PyCharm 对 Pydantic 模型的支持，优化的功能如下：
+
+    * 自动补全
+    * 类型检查
+    * 代码重构
+    * 查找
+    * 代码审查
 
 ## 使用模型
 
-在函数内部，你可以直接访问模型对象的所有属性：
+在*路径操作*函数内部直接访问模型对象的属性：
 
 === "Python 3.10+"
 
@@ -150,9 +165,9 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
 
 ## 请求体 + 路径参数
 
-你可以同时声明路径参数和请求体。
+**FastAPI** 支持同时声明路径参数和请求体。
 
-**FastAPI** 将识别出与路径参数匹配的函数参数应**从路径中获取**，而声明为 Pydantic 模型的函数参数应**从请求体中获取**。
+**FastAPI** 能识别与**路径参数**匹配的函数参数，还能识别从**请求体**中获取的类型为 Pydantic 模型的函数参数。
 
 === "Python 3.10+"
 
@@ -168,9 +183,9 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
 
 ## 请求体 + 路径参数 + 查询参数
 
-你还可以同时声明**请求体**、**路径参数**和**查询参数**。
+**FastAPI** 支持同时声明**请求体**、**路径参数**和**查询参数**。
 
-**FastAPI** 会识别它们中的每一个，并从正确的位置获取数据。
+**FastAPI** 能够正确识别这三种参数，并从正确的位置获取数据。
 
 === "Python 3.10+"
 
@@ -184,12 +199,18 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
     {!> ../../../docs_src/body/tutorial004.py!}
     ```
 
-函数参数将依次按如下规则进行识别：
+函数参数按如下规则进行识别：
+
+- **路径**中声明了相同参数的参数，是路径参数
+- 类型是（`int`、`float`、`str`、`bool` 等）**单类型**的参数，是**查询**参数
+- 类型是 **Pydantic 模型**的参数，是**请求体**
+
+!!! note "笔记"
+
+    因为默认值是 `None`， FastAPI 会把 `q` 当作可选参数。
 
-* 如果在**路径**中也声明了该参数，它将被用作路径参数。
-* 如果参数属于**单一类型**（比如 `int`、`float`、`str`、`bool` 等）它将被解释为**查询**参数。
-* 如果参数的类型被声明为一个 **Pydantic 模型**，它将被解释为**请求体**。
+    FastAPI 不使用 `Optional[str]` 中的 `Optional`， 但 `Optional` 可以让编辑器提供更好的支持，并检测错误。
 
 ## 不使用 Pydantic
 
-å¦\82æ\9e\9cä½ ä¸\8dæ\83³ä½¿ç\94¨ Pydantic 模å\9e\8bï¼\8cä½ è¿\98å\8f¯ä»¥ä½¿ç\94¨ **Body** å\8f\82æ\95°ã\80\82请å\8f\82é\98\85æ\96\87æ¡£ [请æ±\82ä½\93 - å¤\9a个å\8f\82æ\95°ï¼\9a请æ±\82ä½\93中ç\9a\84å\8d\95ä¸\80å\80¼](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}。
+å\8d³ä¾¿ä¸\8d使ç\94¨ Pydantic 模å\9e\8bä¹\9fè\83½ä½¿ç\94¨ **Body** å\8f\82æ\95°ã\80\82详è§\81[请æ±\82ä½\93 - å¤\9aå\8f\82æ\95°ï¼\9a请æ±\82ä½\93中ç\9a\84å\8d\95å\80¼](body-multiple-params.md#singular-values-in-body){.internal-link target=\_blank}。