```console
-$ pip install passlib[bcrypt]
+$ pip install "pwdlib[argon2]"
---> 100%
```
@@ -84,51 +86,51 @@ $ pip install passlib[bcrypt]
/// tip | 提示
-`passlib` 甚至可以读取 Django、Flask 的安全插件等工具创建的密码。
+使用 `pwdlib`，你甚至可以把它配置为能够读取由 **Django**、**Flask** 安全插件或其他许多工具创建的密码。
-例如，把 Django 应用的数据共享给 FastAPI 应用的数据库。或利用同一个数据库，可以逐步把应用从 Django 迁移到 FastAPI。
+例如，你可以在数据库中让一个 Django 应用和一个 FastAPI 应用共享同一份数据。或者在使用同一个数据库的前提下，逐步迁移一个 Django 应用到 FastAPI。
-并且，用户可以同时从 Django 应用或 FastAPI 应用登录。
+同时，你的用户既可以从 Django 应用登录，也可以从 **FastAPI** 应用登录。
///
-## 密码哈希与校验
+## 哈希并校验密码 { #hash-and-verify-the-passwords }
-从 `passlib` 导入所需工具。
+从 `pwdlib` 导入所需工具。
-创建用于密码哈希和身份校验的 PassLib **上下文**。
+用推荐设置创建一个 PasswordHash 实例——它将用于哈希与校验密码。
/// tip | 提示
-PassLib 上下文还支持使用不同哈希算法的功能，包括只能校验的已弃用旧算法等。
+pwdlib 也支持 bcrypt 哈希算法，但不包含遗留算法——如果需要处理过时的哈希，建议使用 passlib 库。
-例如，用它读取和校验其它系统（如 Django）生成的密码，但要使用其它算法，如 Bcrypt，生成新的哈希密码。
+例如，你可以用它读取并校验其他系统（如 Django）生成的密码，但对任何新密码使用不同的算法（如 Argon2 或 Bcrypt）进行哈希。
-同时，这些功能都是兼容的。
+并且能够同时与它们全部兼容。
///
-接下来，创建三个工具函数，其中一个函数用于哈希用户的密码。
+创建一个工具函数来哈希用户传入的密码。
-第一个函数用于校验接收的密码是否匹配存储的哈希值。
+再创建一个工具函数来校验接收的密码是否匹配已存储的哈希。
-第三个函数用于身份验证，并返回用户。
+再创建一个工具函数来进行身份验证并返回用户。
{* ../../docs_src/security/tutorial004_an_py310.py hl[8,49,56:57,60:61,70:76] *}
-/// note | 笔记
+/// note | 注意
-查看新的（伪）数据库 `fake_users_db`，就能看到哈希后的密码：`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`。
+如果你查看新的（伪）数据库 `fake_users_db`，现在你会看到哈希后的密码类似这样：`"$argon2id$v=19$m=65536,t=3,p=4$wagCPXjifgvUFBzq4hqe3w$CYaIb8sB+wtD+Vu/P4uod1+Qof8h+1g7bbDlBID48Rc"`。
///
-## 处理 JWT 令牌
+## 处理 JWT 令牌 { #handle-jwt-tokens }
导入已安装的模块。
-创建用于 JWT 令牌签名的随机密钥。
+创建一个用于对 JWT 令牌进行签名的随机密钥。
-使用以下命令，生成安全的随机密钥：
+使用下列命令生成一个安全的随机密钥：
@@ -140,81 +142,82 @@ $ openssl rand -hex 32
-然后，把生成的密钥复制到变量**SECRET_KEY**，注意，不要使用本例所示的密钥。
+把输出复制到变量 `SECRET_KEY`（不要使用示例中的那个）。
-创建指定 JWT 令牌签名算法的变量 **ALGORITHM**，本例中的值为 `"HS256"`。
+创建变量 `ALGORITHM`，设置用于签名 JWT 令牌的算法，这里设为 `"HS256"`。
-创建设置令牌过期时间的变量。
+创建一个变量用于设置令牌的过期时间。
-定义令牌端点响应的 Pydantic 模型。
+定义一个用于令牌端点响应的 Pydantic 模型。
-创建生成新的访问令牌的工具函数。
+创建一个生成新访问令牌的工具函数。
-{* ../../docs_src/security/tutorial004.py hl[6,12:14,28:30,78:86] *}
+{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *}
-## 更新依赖项
+## 更新依赖项 { #update-the-dependencies }
-更新 `get_current_user` 以接收与之前相同的令牌，但这里用的是 JWT 令牌。
+更新 `get_current_user` 以接收与之前相同的令牌，但这次使用的是 JWT 令牌。
-解码并校验接收到的令牌，然后，返回当前用户。
+解码接收到的令牌，进行校验，并返回当前用户。
-如果令牌无效，则直接返回 HTTP 错误。
+如果令牌无效，立即返回一个 HTTP 错误。
-{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *}
+{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *}
-## 更新 `/token` *路径操作*
+## 更新 `/token` 路径操作 { #update-the-token-path-operation }
-用令牌过期时间创建 `timedelta` 对象。
+用令牌的过期时间创建一个 `timedelta`。
-创建并返回真正的 JWT 访问令牌。
+创建一个真正的 JWT 访问令牌并返回它。
{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *}
-### JWT `sub` 的技术细节
+### 关于 JWT “主题” `sub` 的技术细节 { #technical-details-about-the-jwt-subject-sub }
-JWT 规范还包括 `sub` 键，值是令牌的主题。
+JWT 规范中有一个 `sub` 键，表示令牌的“主题”（subject）。
-该键是可选的，但要把用户标识放在这个键里，所以本例使用了该键。
+使用它是可选的，但通常会把用户的标识放在这里，所以本例中我们使用它。
-除了识别用户与许可用户在 API 上直接执行操作之外，JWT 还可能用于其它事情。
+JWT 除了用于识别用户并允许其直接在你的 API 上执行操作之外，还可能用于其他场景。
-例如，识别**汽车**或**博客**。
+例如，你可以用它来标识一辆“车”或一篇“博客文章”。
-接着，为实体添加权限，比如**驾驶**（汽车）或**编辑**（博客）。
+然后你可以为该实体添加权限，比如“drive”（用于车）或“edit”（用于博客）。
-然后，把 JWT 令牌交给用户（或机器人），他们就可以执行驾驶汽车，或编辑博客等操作。无需注册账户，只要有 API 生成的 JWT 令牌就可以。
+接着，你可以把这个 JWT 令牌交给一个用户（或机器人），他们就可以在没有账户的前提下，仅凭你的 API 生成的 JWT 令牌来执行这些操作（开车、编辑文章）。
-同理，JWT 可以用于更复杂的场景。
+基于这些想法，JWT 可以用于更复杂的场景。
-在这些情况下，多个实体的 ID 可能是相同的，以 ID `foo` 为例，用户的 ID 是 `foo`，车的 ID 是 `foo`，博客的 ID 也是 `foo`。
+在这些情况下，多个实体可能会有相同的 ID，比如都叫 `foo`（用户 `foo`、车 `foo`、博客文章 `foo`）。
-为了避免 ID 冲突，在给用户创建 JWT 令牌时，可以为 `sub` 键的值加上前缀，例如 `username:`。因此，在本例中，`sub` 的值可以是：`username:johndoe`。
+因此，为了避免 ID 冲突，在为用户创建 JWT 令牌时，你可以给 `sub` 键的值加一个前缀，例如 `username:`。所以在这个例子中，`sub` 的值可以是：`username:johndoe`。
-注意，划重点，`sub` 键在整个应用中应该只有一个唯一的标识符，而且应该是字符串。
+需要牢记的一点是，`sub` 键在整个应用中应该是一个唯一标识符，并且它应该是字符串。
-## 检查
+## 检查 { #check-it }
-运行服务器并访问文档：
http://127.0.0.1:8000/docs。
+运行服务器并打开文档：
http://127.0.0.1:8000/docs。
-可以看到如下用户界面：
+你会看到这样的用户界面：
-
+
-用与上一章同样的方式实现应用授权。
+像之前一样进行授权。
-使用如下凭证：
+使用以下凭证：
-用户名: `johndoe` 密码: `secret`
+用户名: `johndoe`
+密码: `secret`
/// check | 检查
-注意，代码中没有明文密码**`secret`**，只保存了它的哈希值。
+注意，代码中的任何地方都没有明文密码 “`secret`”，我们只有它的哈希版本。
///
-
+
-调用 `/users/me/` 端点，收到下面的响应：
+调用 `/users/me/` 端点，你将得到如下响应：
```JSON
{
@@ -225,46 +228,46 @@ JWT 规范还包括 `sub` 键，值是令牌的主题。
}
```
-
+
-打开浏览器的开发者工具，查看数据是怎么发送的，而且数据里只包含了令牌，只有验证用户的第一个请求才发送密码，并获取访问令牌，但之后不会再发送密码：
+如果你打开开发者工具，你会看到发送的数据只包含令牌。密码只会在第一个请求中用于认证用户并获取访问令牌，之后就不会再发送密码了：
-
+
-/// note | 笔记
+/// note | 注意
-注意，请求中 `Authorization` 响应头的值以 `Bearer` 开头。
+注意 `Authorization` 请求头，其值以 `Bearer ` 开头。
///
-## `scopes` 高级用法
+## 使用 `scopes` 的高级用法 { #advanced-usage-with-scopes }
-OAuth2 支持**`scopes`**（作用域）。
+OAuth2 支持 “scopes”（作用域）。
-**`scopes`**为 JWT 令牌添加指定权限。
+你可以用它们为 JWT 令牌添加一组特定的权限。
-让持有令牌的用户或第三方在指定限制条件下与 API 交互。
+然后你可以把这个令牌直接交给用户或第三方，在一组限制条件下与 API 交互。
-**高级用户指南**中将介绍如何使用 `scopes`，及如何把 `scopes` 集成至 **FastAPI**。
+在**高级用户指南**中你将学习如何使用它们，以及它们如何集成进 **FastAPI**。
-## 小结
+## 小结 { #recap }
-至此，您可以使用 OAuth2 和 JWT 等标准配置安全的 **FastAPI** 应用。
+通过目前所学内容，你可以使用 OAuth2 和 JWT 等标准来搭建一个安全的 **FastAPI** 应用。
-几乎在所有框架中，处理安全问题很快都会变得非常复杂。
+在几乎任何框架中，处理安全问题都会很快变得相当复杂。
-有些包为了简化安全流，不得不在数据模型、数据库和功能上做出妥协。而有些过于简化的软件包其实存在了安全隐患。
+许多把安全流程大幅简化的包，往往要在数据模型、数据库和可用特性上做出大量妥协。而有些过度简化的包实际上在底层存在安全隐患。
---
-**FastAPI** 不向任何数据库、数据模型或工具做妥协。
+**FastAPI** 不会在任何数据库、数据模型或工具上做妥协。
-开发者可以灵活选择最适合项目的安全机制。
+它给予你完全的灵活性，选择最适合你项目的方案。
-还可以直接使用 `passlib` 和 `PyJWT` 等维护良好、使用广泛的包，这是因为 **FastAPI** 不需要任何复杂机制，就能集成外部的包。
+而且你可以直接使用许多维护良好、广泛使用的包，比如 `pwdlib` 和 `PyJWT`，因为 **FastAPI** 不需要复杂机制来集成外部包。
-而且，**FastAPI** 还提供了一些工具，在不影响灵活、稳定和安全的前提下，尽可能地简化安全机制。
+同时它也为你提供尽可能简化流程的工具，而不牺牲灵活性、健壮性或安全性。
-**FastAPI** 还支持以相对简单的方式，使用 OAuth2 等安全、标准的协议。
+你可以以相对简单的方式使用和实现像 OAuth2 这样的安全、标准协议。
-**高级用户指南**中详细介绍了 OAuth2**`scopes`**的内容，遵循同样的标准，实现更精密的权限系统。OAuth2 的作用域是脸书、谷歌、GitHub、微软、推特等第三方身份验证应用使用的机制，让用户授权第三方应用与 API 交互。
+在**高级用户指南**中，你可以进一步了解如何使用 OAuth2 的 “scopes”，以遵循相同标准实现更细粒度的权限系统。带作用域的 OAuth2 是许多大型身份认证提供商（如 Facebook、Google、GitHub、Microsoft、X（Twitter）等）用来授权第三方应用代表其用户与其 API 交互的机制。
diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md
index f70678df8f..3037a983b3 100644
--- a/docs/zh/docs/tutorial/security/simple-oauth2.md
+++ b/docs/zh/docs/tutorial/security/simple-oauth2.md
@@ -1,8 +1,8 @@
-# OAuth2 实现简单的 Password 和 Bearer 验证
+# OAuth2 实现简单的 Password 和 Bearer 验证 { #simple-oauth2-with-password-and-bearer }
本章添加上一章示例中欠缺的部分，实现完整的安全流。
-## 获取 `username` 和 `password`
+## 获取 `username` 和 `password` { #get-the-username-and-password }
首先，使用 **FastAPI** 安全工具获取 `username` 和 `password`。
@@ -18,7 +18,7 @@ OAuth2 规范要求使用**密码流**时，客户端或用户必须以表单数
该规范要求必须以表单数据形式发送 `username` 和 `password`，因此，不能使用 JSON 对象。
-### `Scope`（作用域）
+### `scope` { #scope }
OAuth2 还支持客户端发送**`scope`**表单字段。
@@ -32,7 +32,7 @@ OAuth2 还支持客户端发送**`scope`**表单字段。
* 脸书和 Instagram 使用 `instagram_basic`
* 谷歌使用 `https://www.googleapis.com/auth/drive`
-/// info | 说明
+/// info | 信息
OAuth2 中，**作用域**只是声明指定权限的字符串。
@@ -44,15 +44,15 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。
///
-## 获取 `username` 和 `password` 的代码
+## 获取 `username` 和 `password` 的代码 { #code-to-get-the-username-and-password }
接下来，使用 **FastAPI** 工具获取用户名与密码。
-### `OAuth2PasswordRequestForm`
+### `OAuth2PasswordRequestForm` { #oauth2passwordrequestform }
首先，导入 `OAuth2PasswordRequestForm`，然后，在 `/token` *路径操作* 中，用 `Depends` 把该类作为依赖项。
-{* ../../docs_src/security/tutorial003.py hl[4,76] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
`OAuth2PasswordRequestForm` 是用以下几项内容声明表单请求体的类依赖项：
@@ -72,7 +72,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。
* 可选的 `client_id`（本例未使用）
* 可选的 `client_secret`（本例未使用）
-/// info | 说明
+/// info | 信息
`OAuth2PasswordRequestForm` 与 `OAuth2PasswordBearer` 一样，都不是 FastAPI 的特殊类。
@@ -84,7 +84,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。
///
-### 使用表单数据
+### 使用表单数据 { #use-the-form-data }
/// tip | 提示
@@ -100,9 +100,9 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。
本例使用 `HTTPException` 异常显示此错误：
-{* ../../docs_src/security/tutorial003.py hl[3,77:79] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
-### 校验密码
+### 校验密码 { #check-the-password }
至此，我们已经从数据库中获取了用户数据，但尚未校验密码。
@@ -112,7 +112,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。
如果密码不匹配，则返回与上面相同的错误。
-#### 密码哈希
+#### 密码哈希 { #password-hashing }
**哈希**是指，将指定内容（本例中为密码）转换为形似乱码的字节序列（其实就是字符串）。
@@ -120,15 +120,15 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。
但这个乱码无法转换回传入的密码。
-##### 为什么使用密码哈希
+##### 为什么使用密码哈希 { #why-use-password-hashing }
原因很简单，假如数据库被盗，窃贼无法获取用户的明文密码，得到的只是哈希值。
这样一来，窃贼就无法在其它应用中使用窃取的密码，要知道，很多用户在所有系统中都使用相同的密码，风险超大。
-{* ../../docs_src/security/tutorial003.py hl[80:83] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
-#### 关于 `**user_dict`
+#### 关于 `**user_dict` { #about-user-dict }
`UserInDB(**user_dict)` 是指：
@@ -144,13 +144,13 @@ UserInDB(
)
```
-/// info | 说明
+/// info | 信息
-`user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#user_indict){.internal-link target=_blank}。
+`user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#about-user-in-dict){.internal-link target=_blank}。
///
-## 返回 Token
+## 返回 Token { #return-the-token }
`token` 端点的响应必须是 JSON 对象。
@@ -162,13 +162,13 @@ UserInDB(
/// tip | 提示
-下一章介绍使用哈希密码和
JWT Token 的真正安全机制。
+下一章介绍使用哈希密码和
JWT Token 的真正安全机制。
但现在，仅关注所需的特定细节。
///
-{* ../../docs_src/security/tutorial003.py hl[85] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
/// tip | 提示
@@ -182,7 +182,7 @@ UserInDB(
///
-## 更新依赖项
+## 更新依赖项 { #update-the-dependencies }
接下来，更新依赖项。
@@ -194,9 +194,9 @@ UserInDB(
因此，在端点中，只有当用户存在、通过身份验证、且状态为激活时，才能获得该用户：
-{* ../../docs_src/security/tutorial003.py hl[58:67,69:72,90] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
-/// info | 说明
+/// info | 信息
此处返回值为 `Bearer` 的响应头 `WWW-Authenticate` 也是规范的一部分。
@@ -210,15 +210,15 @@ UserInDB(
说不定什么时候，就有工具用得上它，而且，开发者或用户也可能用得上。
-这就是遵循标准的好处……
+这就是遵循标准的好处...
///
-## 实际效果
+## 实际效果 { #see-it-in-action }
打开 API 文档：
http://127.0.0.1:8000/docs。
-### 身份验证
+### 身份验证 { #authenticate }
点击**Authorize**按钮。
@@ -228,13 +228,13 @@ UserInDB(
密码：`secret`
-
+
通过身份验证后，显示下图所示的内容：
-
+
-### 获取当前用户数据
+### 获取当前用户数据 { #get-your-own-user-data }
使用 `/users/me` 路径的 `GET` 操作。
@@ -250,7 +250,7 @@ UserInDB(
}
```
-
+
点击小锁图标，注销后，再执行同样的操作，则会得到 HTTP 401 错误：
@@ -260,7 +260,7 @@ UserInDB(
}
```
-### 未激活用户
+### 未激活用户 { #inactive-user }
测试未激活用户，输入以下信息，进行身份验证：
@@ -278,7 +278,7 @@ UserInDB(
}
```
-## 小结
+## 小结 { #recap }
使用本章的工具实现基于 `username` 和 `password` 的完整 API 安全系统。
@@ -286,4 +286,4 @@ UserInDB(
唯一欠缺的是，它仍然不是真的**安全**。
-下一章，介绍使用密码哈希支持库与
JWT 令牌实现真正的安全机制。
+下一章，介绍使用密码哈希支持库与
JWT 令牌实现真正的安全机制。
diff --git a/docs/zh/docs/tutorial/sql-databases.md b/docs/zh/docs/tutorial/sql-databases.md
index fbdf3be6cc..944e960a76 100644
--- a/docs/zh/docs/tutorial/sql-databases.md
+++ b/docs/zh/docs/tutorial/sql-databases.md
@@ -1,40 +1,40 @@
-# SQL（关系型）数据库
+# SQL（关系型）数据库 { #sql-relational-databases }
-**FastAPI** 并不要求您使用 SQL（关系型）数据库。您可以使用**任何**想用的数据库。
+**FastAPI** 并不要求你使用 SQL（关系型）数据库。你可以使用你想用的**任何数据库**。
这里，我们来看一个使用
SQLModel 的示例。
-**SQLModel** 是基于
SQLAlchemy 和 Pydantic 构建的。它由 **FastAPI** 的同一作者制作，旨在完美匹配需要使用 **SQL 数据库**的 FastAPI 应用程序。
+**SQLModel** 基于
SQLAlchemy 和 Pydantic 构建。它由 **FastAPI** 的同一作者制作，旨在完美匹配需要使用**SQL 数据库**的 FastAPI 应用程序。
-/// tip
+/// tip | 提示
-您可以使用任何其他您想要的 SQL 或 NoSQL 数据库（在某些情况下称为
“ORM”），FastAPI 不会强迫您使用任何东西。😎
+你可以使用任意其他你想要的 SQL 或 NoSQL 数据库库（在某些情况下称为
"ORMs"），FastAPI 不会强迫你使用任何东西。😎
///
-由于 SQLModel 基于 SQLAlchemy，因此您可以轻松使用任何由 SQLAlchemy **支持的数据库**（这也让它们被 SQLModel 支持），例如：
+由于 SQLModel 基于 SQLAlchemy，因此你可以轻松使用任何由 SQLAlchemy **支持的数据库**（这也让它们被 SQLModel 支持），例如：
* PostgreSQL
* MySQL
* SQLite
* Oracle
-* Microsoft SQL Server 等.
+* Microsoft SQL Server 等
-在这个例子中，我们将使用 **SQLite**，因为它使用单个文件，并且 Python 对其有集成支持。因此，您可以直接复制这个例子并运行。
+在这个示例中，我们将使用 **SQLite**，因为它使用单个文件，并且 Python 对其有集成支持。因此，你可以直接复制这个示例并运行。
-之后，对于您的生产应用程序，您可能会想要使用像 PostgreSQL 这样的数据库服务器。
+之后，对于你的生产应用程序，你可能会想要使用像 **PostgreSQL** 这样的数据库服务器。
-/// tip
+/// tip | 提示
-有一个使用 **FastAPI** 和 **PostgreSQL** 的官方的项目生成器，其中包括了前端和更多工具：
https://github.com/fastapi/full-stack-fastapi-template
+有一个使用 **FastAPI** 和 **PostgreSQL** 的官方项目生成器，其中包括了前端和更多工具：
https://github.com/fastapi/full-stack-fastapi-template
///
-这是一个非常简单和简短的教程。如果您想了解一般的数据库、SQL 或更高级的功能，请查看
SQLModel 文档。
+这是一个非常简单和简短的教程。如果你想了解一般的数据库、SQL 或更高级的功能，请查看
SQLModel 文档。
-## 安装 `SQLModel`
+## 安装 `SQLModel` { #install-sqlmodel }
-首先，确保您创建并激活了[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后安装了 `sqlmodel` :
+首先，确保你创建并激活了[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后安装 `sqlmodel`：
@@ -45,61 +45,61 @@ $ pip install sqlmodel
-## 创建含有单一模型的应用程序
+## 创建含有单一模型的应用 { #create-the-app-with-a-single-model }
-我们首先创建应用程序的最简单的第一个版本，只有一个 **SQLModel** 模型。
+我们先创建应用的最简单的第一个版本，只有一个 **SQLModel** 模型。
稍后我们将通过下面的**多个模型**提高其安全性和多功能性。🤓
-### 创建模型
+### 创建模型 { #create-models }
导入 `SQLModel` 并创建一个数据库模型：
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[1:11] hl[7:11] *}
-`Hero` 类与 Pydantic 模型非常相似（实际上，从底层来看，它确实*就是一个 Pydantic 模型*）。
+`Hero` 类与 Pydantic 模型非常相似（实际上，从底层来看，它确实就是一个 Pydantic 模型）。
有一些区别：
-* `table=True` 会告诉 SQLModel 这是一个*表模型*，它应该表示 SQL 数据库中的一个*表*，而不仅仅是一个*数据模型*（就像其他常规的 Pydantic 类一样）。
+* `table=True` 会告诉 SQLModel 这是一个*表模型*，它应该表示 SQL 数据库中的一个**表**，而不仅仅是一个*数据模型*（就像其他常规的 Pydantic 类一样）。
-* `Field(primary_key=True)` 会告诉 SQLModel `id` 是 SQL 数据库中的**主键**（您可以在 SQLModel 文档中了解更多关于 SQL 主键的信息）。
+* `Field(primary_key=True)` 会告诉 SQLModel `id` 是 SQL 数据库中的**主键**（你可以在 SQLModel 文档中了解更多关于 SQL 主键的信息）。
- 把类型设置为 `int | None` ，SQLModel 就能知道该列在 SQL 数据库中应该是 `INTEGER` 类型，并且应该是 `NULLABLE` 。
+ **注意：** 我们为主键字段使用 `int | None`，这样在 Python 代码中我们可以在没有 `id`（`id=None`）的情况下创建对象，并假定数据库在保存时会生成它。SQLModel 会理解数据库会提供 `id`，并在数据库模式中将该列定义为非空的 `INTEGER`。详见
SQLModel 关于主键的文档。
* `Field(index=True)` 会告诉 SQLModel 应该为此列创建一个 **SQL 索引**，这样在读取按此列过滤的数据时，程序能在数据库中进行更快的查找。
- SQLModel 会知道声明为 `str` 的内容将是类型为 `TEXT` （或 `VARCHAR` ，具体取决于数据库）的 SQL 列。
+ SQLModel 会知道声明为 `str` 的内容将是类型为 `TEXT`（或 `VARCHAR`，具体取决于数据库）的 SQL 列。
-### 创建引擎（Engine）
+### 创建引擎（Engine） { #create-an-engine }
-SQLModel 的引擎 `engine`（实际上它是一个 SQLAlchemy `engine` ）是用来与数据库**保持连接**的。
+SQLModel 的 `engine`（实际上它是一个 SQLAlchemy 的 `engine`）是用来与数据库**保持连接**的。
-您只需构建**一个 `engine`**，来让您的所有代码连接到同一个数据库。
+你只需构建**一个 `engine` 对象**，让你的所有代码连接到同一个数据库。
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[14:18] hl[14:15,17:18] *}
使用 `check_same_thread=False` 可以让 FastAPI 在不同线程中使用同一个 SQLite 数据库。这很有必要，因为**单个请求**可能会使用**多个线程**（例如在依赖项中）。
-不用担心，我们会按照代码结构确保**每个请求使用一个单独的 SQLModel *会话***，这实际上就是 `check_same_thread` 想要实现的。
+不用担心，我们会按照代码结构确保**每个请求使用一个单独的 SQLModel 会话（session）**，这实际上就是 `check_same_thread` 想要实现的。
-### 创建表
+### 创建表 { #create-the-tables }
然后，我们来添加一个函数，使用 `SQLModel.metadata.create_all(engine)` 为所有*表模型***创建表**。
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[21:22] hl[21:22] *}
-### 创建会话（Session）依赖项
+### 创建会话（Session）依赖项 { #create-a-session-dependency }
**`Session`** 会存储**内存中的对象**并跟踪数据中所需更改的内容，然后它**使用 `engine`** 与数据库进行通信。
-我们会使用 `yield` 创建一个 FastAPI **依赖项**，为每个请求提供一个新的 `Session` 。这确保我们每个请求使用一个单独的会话。🤓
+我们会使用 `yield` 创建一个 FastAPI **依赖项**，为每个请求提供一个新的 `Session`。这确保我们每个请求使用一个单独的会话。🤓
然后我们创建一个 `Annotated` 的依赖项 `SessionDep` 来简化其他也会用到此依赖的代码。
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *}
-### 在启动时创建数据库表
+### 在启动时创建数据库表 { #create-database-tables-on-startup }
我们会在应用程序启动时创建数据库表。
@@ -107,49 +107,47 @@ SQLModel 的引擎 `engine`（实际上它是一个 SQLAlchemy `engine` ）是
此处，在应用程序启动事件中，我们创建了表。
-而对于生产环境，您可能会用一个能够在启动应用程序之前运行的迁移脚本。🤓
+在生产环境中，你可能会使用一个在启动应用程序之前运行的迁移脚本。🤓
-/// tip
+/// tip | 提示
-SQLModel 将会拥有封装 Alembic 的迁移工具，但目前您可以直接使用
Alembic。
+SQLModel 将会拥有封装 Alembic 的迁移工具，但目前你可以直接使用
Alembic。
///
-### 创建 Hero 类
+### 创建 Hero { #create-a-hero }
-因为每个 SQLModel 模型同时也是一个 Pydantic 模型，所以您可以在与 Pydantic 模型相同的**类型注释**中使用它。
+因为每个 SQLModel 模型同时也是一个 Pydantic 模型，所以你可以在与 Pydantic 模型相同的**类型注解**中使用它。
-例如，如果您声明一个类型为 `Hero` 的参数，它将从 **JSON 主体**中读取数据。
+例如，如果你声明一个类型为 `Hero` 的参数，它将从 **JSON 主体**中读取数据。
-同样，您可以将其声明为函数的**返回类型**，然后数据的结构就会显示在自动生成的 API 文档界面中。
+同样，你可以将其声明为函数的**返回类型**，然后数据的结构就会显示在自动生成的 API 文档界面中。
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[40:45] hl[40:45] *}
-
+这里，我们使用 `SessionDep` 依赖项（一个 `Session`）将新的 `Hero` 添加到 `Session` 实例中，提交更改到数据库，刷新 `hero` 中的数据，并返回它。
-这里，我们使用 `SessionDep` 依赖项（一个 `Session` ）将新的 `Hero` 添加到 `Session` 实例中，提交更改到数据库，刷新 hero 中的数据，并返回它。
+### 读取 Hero { #read-heroes }
-### 读取 Hero 类
-
-我们可以使用 `select()` 从数据库中**读取** `Hero` 类，并利用 `limit` 和 `offset` 来对结果进行分页。
+我们可以使用 `select()` 从数据库中**读取** `Hero`，并利用 `limit` 和 `offset` 来对结果进行分页。
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[48:55] hl[51:52,54] *}
-### 读取单个 Hero
+### 读取单个 Hero { #read-one-hero }
-我们可以**读取**单个 `Hero` 。
+我们可以**读取**单个 `Hero`。
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[58:63] hl[60] *}
-### 删除单个 Hero
+### 删除单个 Hero { #delete-a-hero }
-我们也可以**删除**单个 `Hero` 。
+我们也可以**删除**一个 `Hero`。
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[66:73] hl[71] *}
-### 运行应用程序
+### 运行应用 { #run-the-app }
-您可以运行这个应用程序：
+你可以运行这个应用：
@@ -161,25 +159,25 @@ $ fastapi dev main.py
-然后在 `/docs` UI 中，您能够看到 **FastAPI** 会用这些**模型**来**记录** API，并且还会用它们来**序列化**和**验证**数据。
+然后在 `/docs` UI 中，你能够看到 **FastAPI** 会用这些**模型**来**记录** API，并且还会用它们来**序列化**和**验证**数据。
-## 更新应用程序以支持多个模型
+## 使用多个模型更新应用 { #update-the-app-with-multiple-models }
现在让我们稍微**重构**一下这个应用，以提高**安全性**和**多功能性**。
-如果您查看之前的应用程序，您可以在 UI 界面中看到，到目前为止，由客户端决定要创建的 `Hero` 的 `id` 值。😱
+如果你查看之前的应用程序，你可以在 UI 界面中看到，到目前为止，它允许客户端决定要创建的 `Hero` 的 `id`。😱
-我们不应该允许这样做，因为他们可能会覆盖我们在数据库中已经分配的 `id` 。决定 `id` 的行为应该由**后端**或**数据库**来完成，**而非客户端**。
+我们不应该允许这样做，因为他们可能会覆盖我们在数据库中已经分配的 `id`。决定 `id` 的行为应该由**后端**或**数据库**来完成，**而非客户端**。
-此外，我们为 hero 创建了一个 `secret_name` ，但到目前为止，我们在各处都返回了它，这就不太**秘密**了……😅
+此外，我们为 hero 创建了一个 `secret_name`，但到目前为止，我们在各处都返回了它，这就不太**秘密**了……😅
我们将通过添加一些**额外的模型**来解决这些问题，而 SQLModel 将在这里大放异彩。✨
-### 创建多个模型
+### 创建多个模型 { #create-multiple-models }
在 **SQLModel** 中，任何含有 `table=True` 属性的模型类都是一个**表模型**。
@@ -187,7 +185,7 @@ $ fastapi dev main.py
有了 SQLModel，我们就可以利用**继承**来在所有情况下**避免重复**所有字段。
-#### `HeroBase` - 基类
+#### `HeroBase` - 基类 { #herobase-the-base-class }
我们从一个 `HeroBase` 模型开始，该模型具有所有模型**共享的字段**：
@@ -196,14 +194,14 @@ $ fastapi dev main.py
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:9] hl[7:9] *}
-#### `Hero` - *表模型*
+#### `Hero` - *表模型* { #hero-the-table-model }
-接下来，我们创建 `Hero` ，实际的*表模型*，并添加那些不总是在其他模型中的**额外字段**：
+接下来，我们创建 `Hero`，实际的*表模型*，并添加那些不总是在其他模型中的**额外字段**：
* `id`
* `secret_name`
-因为 `Hero` 继承自 HeroBase ，所以它**也**包含了在 `HeroBase` 中声明过的**字段**。因此 `Hero` 的所有字段为：
+因为 `Hero` 继承自 `HeroBase`，所以它**也**包含了在 `HeroBase` 中声明过的**字段**。因此 `Hero` 的所有字段为：
* `id`
* `name`
@@ -212,46 +210,45 @@ $ fastapi dev main.py
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:14] hl[12:14] *}
-#### `HeroPublic` - 公共*数据模型*
+#### `HeroPublic` - 公共*数据模型* { #heropublic-the-public-data-model }
接下来，我们创建一个 `HeroPublic` 模型，这是将**返回**给 API 客户端的模型。
-它包含与 `HeroBase` 相同的字段，因此不会包括 `secret_name` 。
+它包含与 `HeroBase` 相同的字段，因此不会包括 `secret_name`。
-终于，我们英雄（hero）的身份得到了保护！ 🥷
+终于，我们英雄（hero）的身份得到了保护！🥷
-它还重新声明了 `id: int` 。这样我们便与 API 客户端建立了一种**约定**，使他们始终可以期待 `id` 存在并且是一个整数 `int`（永远不会是 `None` ）。
+它还重新声明了 `id: int`。这样我们便与 API 客户端建立了一种**约定**，使他们始终可以期待 `id` 存在并且是一个整数 `int`（永远不会是 `None`）。
-/// tip
+/// tip | 提示
-确保返回模型始终提供一个值并且始终是 `int` （而不是 `None` ）对 API 客户端非常有用，他们可以在这种确定性下编写更简单的代码。
+确保返回模型始终提供一个值并且始终是 `int`（而不是 `None`）对 API 客户端非常有用，他们可以在这种确定性下编写更简单的代码。
-此外，**自动生成的客户端**将拥有更简洁的接口，这样与您的 API 交互的开发者就能更轻松地使用您的 API。😎
+此外，**自动生成的客户端**将拥有更简洁的接口，这样与你的 API 交互的开发者就能更轻松地使用你的 API。😎
///
-`HeroPublic` 中的所有字段都与 `HeroBase` 中的相同，其中 `id` 声明为 `int` （不是 `None` ）：
+`HeroPublic` 中的所有字段都与 `HeroBase` 中的相同，其中 `id` 声明为 `int`（不是 `None`）：
* `id`
* `name`
* `age`
-* `secret_name`
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:18] hl[17:18] *}
-#### `HeroCreate` - 用于创建 hero 的*数据模型*
+#### `HeroCreate` - 用于创建 hero 的*数据模型* { #herocreate-the-data-model-to-create-a-hero }
-现在我们创建一个 `HeroCreate` 模型，这是用于**验证**客户数据的模型。
+现在我们创建一个 `HeroCreate` 模型，这是用于**验证**客户端数据的模型。
-它不仅拥有与 `HeroBase` 相同的字段，还有 `secret_name` 。
+它不仅拥有与 `HeroBase` 相同的字段，还有 `secret_name`。
-现在，当客户端**创建一个新的 hero** 时，他们会发送 `secret_name` ，它会被存储到数据库中，但这些 `secret_name` 不会通过 API 返回给客户端。
+现在，当客户端**创建一个新的 hero** 时，他们会发送 `secret_name`，它会被存储到数据库中，但这些 `secret_name` 不会通过 API 返回给客户端。
-/// tip
+/// tip | 提示
这应当是**密码**被处理的方式：接收密码，但不要通过 API 返回它们。
-在存储密码之前，您还应该对密码的值进行**哈希**处理，**绝不要以明文形式存储它们**。
+在存储密码之前，你还应该对密码的值进行**哈希**处理，**绝不要以明文形式存储它们**。
///
@@ -263,17 +260,17 @@ $ fastapi dev main.py
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:22] hl[21:22] *}
-#### `HeroUpdate` - 用于更新 hero 的*数据模型*
+#### `HeroUpdate` - 用于更新 hero 的*数据模型* { #heroupdate-the-data-model-to-update-a-hero }
在之前的应用程序中，我们没有办法**更新 hero**，但现在有了**多个模型**，我们便能做到这一点了。🎉
-`HeroUpdate` *数据模型*有些特殊，它包含创建新 hero 所需的**所有相同字段**，但所有字段都是**可选的**（它们都有默认值）。这样，当您更新一个 hero 时，您可以只发送您想要更新的字段。
+`HeroUpdate` *数据模型*有些特殊，它包含创建新 hero 所需的**所有相同字段**，但所有字段都是**可选的**（它们都有默认值）。这样，当你更新一个 hero 时，你可以只发送你想要更新的字段。
-因为所有**字段实际上**都发生了**变化**（类型现在包括 `None` ，并且它们现在有一个默认值 `None` ），我们需要**重新声明**它们。
+因为所有**字段实际上**都发生了**变化**（类型现在包括 `None`，并且它们现在有一个默认值 `None`），我们需要**重新声明**它们。
-我们会重新声明所有字段，因此我们并不是真的需要从 `HeroBase` 继承。我会让它继承只是为了保持一致，但这并不必要。这更多是个人喜好的问题。🤷
+我们并不真的需要从 `HeroBase` 继承，因为我们会重新声明所有字段。我会让它继承只是为了保持一致，但这并不必要。这更多是个人喜好的问题。🤷
-`HeroUpdate` 的字段包括:
+`HeroUpdate` 的字段包括：
* `name`
* `age`
@@ -281,51 +278,51 @@ $ fastapi dev main.py
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:28] hl[25:28] *}
-### 使用 `HeroCreate` 创建并返回 `HeroPublic`
+### 使用 `HeroCreate` 创建并返回 `HeroPublic` { #create-with-herocreate-and-return-a-heropublic }
既然我们有了**多个模型**，我们就可以对使用它们的应用程序部分进行更新。
我们在请求中接收到一个 `HeroCreate` *数据模型*，然后从中创建一个 `Hero` *表模型*。
-这个新的*表模型* `Hero` 会包含客户端发送的字段，以及一个由数据库生成的 `id` 。
+这个新的*表模型* `Hero` 会包含客户端发送的字段，以及一个由数据库生成的 `id`。
-然后我们将与函数中相同的*表模型* `Hero` 原样返回。但是由于我们使用 `HeroPublic` *数据模型*声明了 `response_model` ，**FastAPI** 会使用 `HeroPublic` 来验证和序列化数据。
+然后我们将与函数中相同的*表模型* `Hero` 原样返回。但是由于我们使用 `HeroPublic` *数据模型*声明了 `response_model`，**FastAPI** 会使用 `HeroPublic` 来验证和序列化数据。
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[56:62] hl[56:58] *}
-/// tip
+/// tip | 提示
-现在我们使用 `response_model=HeroPublic` 来代替**返回类型注释** `-> HeroPublic` ，因为我们返回的值实际上**并不是** `HeroPublic` 类型。
+现在我们使用 `response_model=HeroPublic` 来代替**返回类型注解** `-> HeroPublic`，因为我们返回的值实际上并不是 `HeroPublic`。
-如果我们声明了 `-> HeroPublic` ，您的编辑器和代码检查工具会抱怨（但也确实理所应当）您返回了一个 `Hero` 而不是一个 `HeroPublic` 。
+如果我们声明了 `-> HeroPublic`，你的编辑器和代码检查工具会（理所应当地）抱怨你返回了一个 `Hero` 而不是一个 `HeroPublic`。
通过 `response_model` 的声明，我们让 **FastAPI** 按照它自己的方式处理，而不会干扰类型注解以及编辑器和其他工具提供的帮助。
///
-### 用 `HeroPublic` 读取 Hero
+### 使用 `HeroPublic` 读取 Hero { #read-heroes-with-heropublic }
-我们可以像之前一样**读取** `Hero` 。同样，使用 `response_model=list[HeroPublic]` 确保正确地验证和序列化数据。
+我们可以像之前一样**读取** `Hero`，同样，使用 `response_model=list[HeroPublic]` 确保正确地验证和序列化数据。
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[65:72] hl[65] *}
-### 用 `HeroPublic` 读取单个 Hero
+### 使用 `HeroPublic` 读取单个 Hero { #read-one-hero-with-heropublic }
-我们可以**读取**单个 `hero` 。
+我们可以**读取**单个 hero：
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[75:80] hl[77] *}
-### 用 `HeroUpdate` 更新单个 Hero
+### 使用 `HeroUpdate` 更新单个 Hero { #update-a-hero-with-heroupdate }
-我们可以**更新**单个 `hero` 。为此，我们会使用 HTTP 的 `PATCH` 操作。
+我们可以**更新**单个 hero。为此，我们会使用 HTTP 的 `PATCH` 操作。
-在代码中，我们会得到一个 `dict` ，其中包含客户端发送的所有数据，**只有客户端发送的数据**，并排除了任何一个仅仅作为默认值存在的值。为此，我们使用 `exclude_unset=True` 。这是最主要的技巧。🪄
+在代码中，我们会得到一个 `dict`，其中包含客户端发送的所有数据，**只有客户端发送的数据**，并排除了任何一个仅仅作为默认值存在的值。为此，我们使用 `exclude_unset=True`。这是最主要的技巧。🪄
-然后我们会使用 `hero_db.sqlmodel_update(hero_data)` ，来利用 `hero_data` 的数据更新 `hero_db` 。
+然后我们会使用 `hero_db.sqlmodel_update(hero_data)`，来利用 `hero_data` 的数据更新 `hero_db`。
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[83:93] hl[83:84,88:89] *}
-### （又一次）删除单个 Hero
+### （再次）删除单个 Hero { #delete-a-hero-again }
**删除**一个 hero 基本保持不变。
@@ -333,9 +330,9 @@ $ fastapi dev main.py
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[96:103] hl[101] *}
-### （又一次）运行应用程序
+### （再次）运行应用 { #run-the-app-again }
-您可以再运行一次应用程序：
+你可以再运行一次应用程序：
@@ -347,14 +344,14 @@ $ fastapi dev main.py
-您会在 `/docs` API UI 看到它现在已经更新，并且在进行创建 hero 等操作时，它不会再期望从客户端接收 `id` 数据。
+如果你进入 `/docs` API UI，你会看到它现在已经更新，并且在创建 hero 时，它不会再期望从客户端接收 `id` 数据等。
-## 总结
+## 总结 { #recap }
-您可以使用
**SQLModel** 与 SQL 数据库进行交互，并通过*数据模型*和*表模型*简化代码。
+你可以使用
**SQLModel** 与 SQL 数据库进行交互，并通过*数据模型*和*表模型*简化代码。
-您可以在 SQLModel 的文档中学习到更多内容，其中有一个更详细的关于
如何将 SQLModel 与 FastAPI 一起使用的教程。🚀
+你可以在 **SQLModel** 文档中学习到更多内容，其中有一个更详细的
将 SQLModel 与 **FastAPI** 一起使用的迷你教程。🚀
diff --git a/docs/zh/docs/tutorial/static-files.md b/docs/zh/docs/tutorial/static-files.md
index 1a0d4504cc..5b2f920b2c 100644
--- a/docs/zh/docs/tutorial/static-files.md
+++ b/docs/zh/docs/tutorial/static-files.md
@@ -1,40 +1,40 @@
-# 静态文件
+# 静态文件 { #static-files }
-您可以使用 `StaticFiles`从目录中自动提供静态文件。
+你可以使用 `StaticFiles` 从目录中自动提供静态文件。
-## 使用`StaticFiles`
+## 使用 `StaticFiles` { #use-staticfiles }
-* 导入`StaticFiles`。
-* "挂载"(Mount) 一个 `StaticFiles()` 实例到一个指定路径。
+* 导入 `StaticFiles`。
+* 将一个 `StaticFiles()` 实例“挂载”（Mount）到指定路径。
-{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
+{* ../../docs_src/static_files/tutorial001_py39.py hl[2,6] *}
-/// note | 技术细节
+/// note | 注意
你也可以用 `from starlette.staticfiles import StaticFiles`。
-**FastAPI** 提供了和 `starlette.staticfiles` 相同的 `fastapi.staticfiles` ，只是为了方便你，开发者。但它确实来自Starlette。
+**FastAPI** 提供了和 `starlette.staticfiles` 相同的 `fastapi.staticfiles`，只是为了方便你这个开发者。但它确实直接来自 Starlette。
///
-### 什么是"挂载"(Mounting)
+### 什么是“挂载”（Mounting） { #what-is-mounting }
-"挂载" 表示在特定路径添加一个完全"独立的"应用，然后负责处理所有子路径。
+“挂载”表示在特定路径添加一个完全“独立”的应用，然后负责处理所有子路径。
-这与使用`APIRouter`不同，因为安装的应用程序是完全独立的。OpenAPI和来自你主应用的文档不会包含已挂载应用的任何东西等等。
+这与使用 `APIRouter` 不同，因为挂载的应用是完全独立的。主应用的 OpenAPI 和文档不会包含已挂载应用的任何内容，等等。
-你可以在**高级用户指南**中了解更多。
+你可以在[高级用户指南](../advanced/index.md){.internal-link target=_blank}中了解更多。
-## 细节
+## 细节 { #details }
-这个 "子应用" 会被 "挂载" 到第一个 `"/static"` 指向的子路径。因此，任何以`"/static"`开头的路径都会被它处理。
+第一个 `"/static"` 指的是这个“子应用”将被“挂载”到的子路径。因此，任何以 `"/static"` 开头的路径都会由它处理。
- `directory="static"` 指向包含你的静态文件的目录名字。
+`directory="static"` 指的是包含你的静态文件的目录名称。
-`name="static"` 提供了一个能被**FastAPI**内部使用的名字。
+`name="static"` 为它提供了一个可被 **FastAPI** 内部使用的名称。
-所有这些参数可以不同于"`static`"，根据你应用的需要和具体细节调整它们。
+这些参数都可以不是“`static`”，请根据你的应用需求和具体细节进行调整。
-## 更多信息
+## 更多信息 { #more-info }
-更多细节和选择查阅
Starlette's docs about Static Files.
+更多细节和选项请查阅
Starlette 的静态文件文档。
diff --git a/docs/zh/docs/tutorial/testing.md b/docs/zh/docs/tutorial/testing.md
index 3877adbac6..1aff9f799c 100644
--- a/docs/zh/docs/tutorial/testing.md
+++ b/docs/zh/docs/tutorial/testing.md
@@ -1,4 +1,4 @@
-# 测试
+# 测试 { #testing }
感谢
Starlette，测试**FastAPI** 应用轻松又愉快。
@@ -6,17 +6,21 @@
有了它，你可以直接与**FastAPI**一起使用
pytest。
-## 使用 `TestClient`
+## 使用 `TestClient` { #using-testclient }
/// info | 信息
-要使用 `TestClient`，先要安装
`httpx`.
+要使用 `TestClient`，先要安装
`httpx`。
-例：`pip install httpx`.
+确保你创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再安装，例如：
+
+```console
+$ pip install httpx
+```
///
-导入 `TestClient`.
+导入 `TestClient`。
通过传入你的**FastAPI**应用创建一个 `TestClient` 。
@@ -26,7 +30,7 @@
为你需要检查的地方用标准的Python表达式写个简单的 `assert` 语句（重申，标准的`pytest`）。
-{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
+{* ../../docs_src/app_testing/tutorial001_py39.py hl[2,12,15:18] *}
/// tip | 提示
@@ -52,13 +56,13 @@
///
-## 分离测试
+## 分离测试 { #separating-tests }
在实际应用中，你可能会把你的测试放在另一个文件里。
您的**FastAPI**应用程序也可能由一些文件/模块组成等等。
-### **FastAPI** app 文件
+### **FastAPI** app 文件 { #fastapi-app-file }
假设你有一个像 [更大的应用](bigger-applications.md){.internal-link target=_blank} 中所描述的文件结构:
@@ -72,9 +76,9 @@
在 `main.py` 文件中你有一个 **FastAPI** app:
-{* ../../docs_src/app_testing/main.py *}
+{* ../../docs_src/app_testing/app_a_py39/main.py *}
-### 测试文件
+### 测试文件 { #testing-file }
然后你会有一个包含测试的文件 `test_main.py` 。app可以像Python包那样存在（一样是目录，但有个 `__init__.py` 文件）：
@@ -88,15 +92,15 @@
因为这文件在同一个包中，所以你可以通过相对导入从 `main` 模块（`main.py`）导入`app`对象：
-{* ../../docs_src/app_testing/test_main.py hl[3] *}
+{* ../../docs_src/app_testing/app_a_py39/test_main.py hl[3] *}
...然后测试代码和之前一样的。
-## 测试：扩展示例
+## 测试：扩展示例 { #testing-extended-example }
现在让我们扩展这个例子，并添加更多细节，看下如何测试不同部分。
-### 扩展后的 **FastAPI** app 文件
+### 扩展后的 **FastAPI** app 文件 { #extended-fastapi-app-file }
让我们继续之前的文件结构：
@@ -116,63 +120,13 @@
所有*路径操作* 都需要一个`X-Token` 头。
-//// tab | Python 3.10+
-
-```Python
-{!> ../../docs_src/app_testing/app_b_an_py310/main.py!}
-```
-
-////
-
-//// tab | Python 3.9+
-
-```Python
-{!> ../../docs_src/app_testing/app_b_an_py39/main.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-```Python
-{!> ../../docs_src/app_testing/app_b_an/main.py!}
-```
-
-////
-
-//// tab | Python 3.10+ non-Annotated
-
-/// tip | 提示
+{* ../../docs_src/app_testing/app_b_an_py310/main.py *}
-Prefer to use the `Annotated` version if possible.
-
-///
-
-```Python
-{!> ../../docs_src/app_testing/app_b_py310/main.py!}
-```
-
-////
-
-//// tab | Python 3.8+ non-Annotated
-
-/// tip | 提示
-
-Prefer to use the `Annotated` version if possible.
-
-///
-
-```Python
-{!> ../../docs_src/app_testing/app_b/main.py!}
-```
-
-////
-
-### 扩展后的测试文件
+### 扩展后的测试文件 { #extended-testing-file }
然后您可以使用扩展后的测试更新`test_main.py`：
-{* ../../docs_src/app_testing/app_b/test_main.py *}
+{* ../../docs_src/app_testing/app_b_an_py310/test_main.py *}
每当你需要客户端在请求中传递信息，但你不知道如何传递时，你可以通过搜索（谷歌）如何用 `httpx`做，或者是用 `requests` 做，毕竟HTTPX的设计是基于Requests的设计的。
@@ -196,9 +150,11 @@ Prefer to use the `Annotated` version if possible.
///
-## 运行起来
+## 运行起来 { #run-it }
+
+之后，你只需要安装 `pytest`。
-之后，你只需要安装 `pytest`:
+确保你创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再安装，例如：
diff --git a/docs/zh/docs/virtual-environments.md b/docs/zh/docs/virtual-environments.md
index 9b3c0340a6..29e272b59a 100644
--- a/docs/zh/docs/virtual-environments.md
+++ b/docs/zh/docs/virtual-environments.md
@@ -1,14 +1,14 @@
-# 虚拟环境
+# 虚拟环境 { #virtual-environments }
当你在 Python 工程中工作时，你可能会有必要用到一个**虚拟环境**（或类似的机制）来隔离你为每个工程安装的包。
-/// info
+/// info | 信息
如果你已经了解虚拟环境，知道如何创建和使用它们，你可以考虑跳过这一部分。🤓
///
-/// tip
+/// tip | 提示
**虚拟环境**和**环境变量**是不同的。
@@ -18,7 +18,7 @@
///
-/// info
+/// info | 信息
这个页面将教你如何使用**虚拟环境**以及了解它们的工作原理。
@@ -26,7 +26,7 @@
///
-## 创建一个工程
+## 创建一个工程 { #create-a-project }
首先，为你的工程创建一个目录。
@@ -51,11 +51,11 @@ $ cd awesome-project
-## 创建一个虚拟环境
+## 创建一个虚拟环境 { #create-a-virtual-environment }
在开始一个 Python 工程的**第一时间**，**
在你的工程内部**创建一个虚拟环境。
-/// tip
+/// tip | 提示
你只需要 **在每个工程中操作一次**，而不是每次工作时都操作。
@@ -96,7 +96,7 @@ $ uv venv
-## 联合预定义响应和自定义响应
+## 组合预定义响应和自定义响应 { #combine-predefined-responses-and-custom-ones }
+
+你可能希望有一些适用于许多*路径操作*的预定义响应，但同时又想把它们与每个*路径操作*所需的自定义响应组合在一起。
+
+在这些情况下，你可以使用 Python 的“解包”`dict` 的技巧 `**dict_to_unpack`：
-您可能希望有一些应用于许多路径操作的预定义响应，但是你想将不同的路径和自定义的相应组合在一块。
-对于这些情况，你可以使用Python的技术，将 `dict` 与 `**dict_to_unpack` 解包：
```Python
old_dict = {
"old key": "old value",
@@ -203,19 +223,25 @@ old_dict = {
new_dict = {**old_dict, "new key": "new value"}
```
-这里， new_dict 将包含来自 old_dict 的所有键值对加上新的键值对：
-```python
+这里，`new_dict` 将包含来自 `old_dict` 的所有键值对，再加上新的键值对：
+
+```Python
{
"old key": "old value",
"second old key": "second old value",
"new key": "new value",
}
```
-您可以使用该技术在路径操作中重用一些预定义的响应，并将它们与其他自定义响应相结合。
-**例如：**
-{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
-## 有关OpenAPI响应的更多信息
-
-要了解您可以在响应中包含哪些内容，您可以查看OpenAPI规范中的以下部分：
- + [OpenAPI响应对象](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responsesObject)，它包括 Response Object 。
- + [OpenAPI响应对象](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responseObject)，您可以直接在 `responses` 参数中的每个响应中包含任何内容。包括 `description` 、 `headers` 、 `content` （其中是声明不同的媒体类型和JSON Schemas）和 `links` 。
+
+你可以使用该技巧在*路径操作*中重用一些预定义响应，并把它们与额外的自定义响应组合在一起。
+
+例如：
+
+{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *}
+
+## 关于 OpenAPI 响应的更多信息 { #more-information-about-openapi-responses }
+
+要查看响应中究竟可以包含什么，你可以查看 OpenAPI 规范中的以下部分：
+
+* 
-但输入**官方**链接 `/api/v1/docs`，并使用端口 `9999` 访问 API 文档，就能正常运行了！🎉
+但如果我们在“官方”URL（代理端口为 `9999`）的 `/api/v1/docs` 访问文档界面，它就能正常工作！🎉
-输入 
-一切正常。 ✔️
+完全符合我们的预期。✔️
-这是因为 FastAPI 在 OpenAPI 里使用 `root_path` 提供的 URL 创建默认 `server`。
+这是因为 FastAPI 使用该 `root_path` 在 OpenAPI 中创建默认的 `server`，其 URL 来自 `root_path`。
-## 附加的服务器
+## 附加的服务器 { #additional-servers }
/// warning | 警告
-此用例较难，可以跳过。
+这是一个更高级的用例，可以跳过。
///
-默认情况下，**FastAPI** 使用 `root_path` 的链接在 OpenAPI 概图中创建 `server`。
+默认情况下，**FastAPI** 会在 OpenAPI 模式中使用 `root_path` 的 URL 创建一个 `server`。
-但也可以使用其它备选 `servers`，例如，需要同一个 API 文档与 staging 和生产环境交互。
+但你也可以提供其他备选的 `servers`，例如你希望让“同一个”文档界面同时与预发布环境和生产环境交互。
-如果传递自定义 `servers` 列表，并有 `root_path`（ 因为 API 使用了代理），**FastAPI** 会在列表开头使用这个 `root_path` 插入**服务器**。
+如果你传入了自定义的 `servers` 列表，并且存在 `root_path`（因为你的 API 位于代理后面），**FastAPI** 会在列表开头插入一个使用该 `root_path` 的“server”。
例如：
-{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
+{* ../../docs_src/behind_a_proxy/tutorial003_py39.py hl[4:7] *}
-这段代码生产如下 OpenAPI 概图：
+会生成如下的 OpenAPI 模式：
```JSON hl_lines="5-7"
{
- "openapi": "3.0.2",
+ "openapi": "3.1.0",
// More stuff here
"servers": [
{
@@ -328,30 +429,38 @@ $ uvicorn main:app --root-path /api/v1
/// tip | 提示
-注意，自动生成服务器时，`url` 的值 `/api/v1` 提取自 `roog_path`。
+注意这个自动生成的服务器，`url` 的值为 `/api/v1`，取自 `root_path`。
///
-
/// tip | 提示
-API 文档与所选的服务器进行交互。
+文档界面会与你所选择的服务器交互。
+
+///
+
+/// note | 技术细节
+
+OpenAPI 规范中的 `servers` 属性是可选的。
+
+如果你没有指定 `servers` 参数，并且 `root_path` 等于 `/`，则默认情况下，生成的 OpenAPI 模式中会完全省略 `servers` 属性，这等价于只有一个 `url` 值为 `/` 的服务器。
///
-### 从 `root_path` 禁用自动服务器
+### 从 `root_path` 禁用自动服务器 { #disable-automatic-server-from-root-path }
-如果不想让 **FastAPI** 包含使用 `root_path` 的自动服务器，则要使用参数 `root_path_in_servers=False`：
+如果你不希望 **FastAPI** 包含一个使用 `root_path` 的自动服务器，可以使用参数 `root_path_in_servers=False`：
-{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
+{* ../../docs_src/behind_a_proxy/tutorial004_py39.py hl[9] *}
-这样，就不会在 OpenAPI 概图中包含服务器了。
+这样它就不会被包含到 OpenAPI 模式中。
-## 挂载子应用
+## 挂载子应用 { #mounting-a-sub-application }
-如需挂载子应用（详见 [子应用 - 挂载](sub-applications.md){.internal-link target=_blank}），也要通过 `root_path` 使用代理，这与正常应用一样，别无二致。
+如果你需要在使用带有 `root_path` 的代理时挂载一个子应用（参见 [子应用 - 挂载](sub-applications.md){.internal-link target=_blank}），你可以像预期的那样正常操作。
-FastAPI 在内部使用 `root_path`，因此子应用也可以正常运行。✨
+FastAPI 会在内部智能地使用 `root_path`，因此它可以直接正常工作。✨
diff --git a/docs/zh/docs/advanced/custom-response.md b/docs/zh/docs/advanced/custom-response.md
index 22a9b4b510..f5bec5fdcf 100644
--- a/docs/zh/docs/advanced/custom-response.md
+++ b/docs/zh/docs/advanced/custom-response.md
@@ -1,32 +1,38 @@
-# 自定义响应 - HTML，流，文件和其他
+# 自定义响应 - HTML、流、文件等 { #custom-response-html-stream-file-others }
**FastAPI** 默认会使用 `JSONResponse` 返回响应。
你可以通过直接返回 `Response` 来重载它，参见 [直接返回响应](response-directly.md){.internal-link target=_blank}。
-但如果你直接返回 `Response`，返回数据不会自动转换，也不会自动生成文档（例如，在 HTTP 头 `Content-Type` 中包含特定的「媒体类型」作为生成的 OpenAPI 的一部分）。
+但如果你直接返回一个 `Response`（或其任意子类，比如 `JSONResponse`），返回数据不会自动转换（即使你声明了 `response_model`），也不会自动生成文档（例如，在生成的 OpenAPI 中，HTTP 头 `Content-Type` 里的特定「媒体类型」不会被包含）。
-你还可以在 *路径操作装饰器* 中声明你想用的 `Response`。
+你还可以在 *路径操作装饰器* 中通过 `response_class` 参数声明要使用的 `Response`（例如任意 `Response` 子类）。
你从 *路径操作函数* 中返回的内容将被放在该 `Response` 中。
-并且如果该 `Response` 有一个 JSON 媒体类型（`application/json`），比如使用 `JSONResponse` 或者 `UJSONResponse` 的时候，返回的数据将使用你在路径操作装饰器中声明的任何 Pydantic 的 `response_model` 自动转换（和过滤）。
+并且如果该 `Response` 有一个 JSON 媒体类型（`application/json`），比如使用 `JSONResponse` 或 `UJSONResponse` 的时候，返回的数据将使用你在路径操作装饰器中声明的任何 Pydantic 的 `response_model` 自动转换（和过滤）。
-/// note | 说明
+/// note | 注意
-如果你使用不带有任何媒体类型的响应类，FastAPI 认为你的响应没有任何内容，所以不会在生成的OpenAPI文档中记录响应格式。
+如果你使用不带有任何媒体类型的响应类，FastAPI 会认为你的响应没有任何内容，所以不会在生成的 OpenAPI 文档中记录响应格式。
///
-## 使用 `ORJSONResponse`
+## 使用 `ORJSONResponse` { #use-orjsonresponse }
例如，如果你需要压榨性能，你可以安装并使用 
-## 可用响应
+## 可用响应 { #available-responses }
这里有一些可用的响应。
@@ -115,7 +121,7 @@
///
-### `Response`
+### `Response` { #response }
其他全部的响应都继承自主类 `Response`。
@@ -128,77 +134,115 @@
* `headers` - 一个由字符串组成的 `dict`。
* `media_type` - 一个给出媒体类型的 `str`，比如 `"text/html"`。
-FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它还将包含一个基于 media_type 的 Content-Type 头，并为文本类型附加一个字符集。
+FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它还将包含一个基于 `media_type` 的 Content-Type 头，并为文本类型附加一个字符集。
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
-{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
-
-### `HTMLResponse`
+### `HTMLResponse` { #htmlresponse }
如上文所述，接受文本或字节并返回 HTML 响应。
-### `PlainTextResponse`
+### `PlainTextResponse` { #plaintextresponse }
接受文本或字节并返回纯文本响应。
-{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial005_py39.py hl[2,7,9] *}
-### `JSONResponse`
+### `JSONResponse` { #jsonresponse }
接受数据并返回一个 `application/json` 编码的响应。
如上文所述，这是 **FastAPI** 中使用的默认响应。
-### `ORJSONResponse`
+### `ORJSONResponse` { #orjsonresponse }
如上文所述，`ORJSONResponse` 是一个使用 
-## 在嵌套数据结构中使用数据类
+## 在嵌套数据结构中使用数据类 { #dataclasses-in-nested-data-structures }
-您还可以把 `dataclasses` 与其它类型注解组合在一起，创建嵌套数据结构。
+你也可以把 `dataclasses` 与其它类型注解组合在一起，创建嵌套数据结构。
-还有一些情况也可以使用 Pydantic 的 `dataclasses`。例如，在 API 文档中显示错误。
+在某些情况下，你可能仍然需要使用 Pydantic 的 `dataclasses` 版本。例如，如果自动生成的 API 文档出现错误。
-本例把标准的 `dataclasses` 直接替换为 `pydantic.dataclasses`：
+在这种情况下，你可以直接把标准的 `dataclasses` 替换为 `pydantic.dataclasses`，它是一个可直接替换的实现：
-```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" }
-{!../../docs_src/dataclasses_/tutorial003.py!}
-```
+{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *}
-1. 本例依然要从标准的 `dataclasses` 中导入 `field`；
+1. 我们仍然从标准库的 `dataclasses` 导入 `field`。
+2. `pydantic.dataclasses` 是 `dataclasses` 的可直接替换版本。
+3. `Author` 数据类包含一个由 `Item` 数据类组成的列表。
+4. `Author` 数据类被用作 `response_model` 参数。
+5. 你可以将其它标准类型注解与数据类一起用作请求体。
-2. 使用 `pydantic.dataclasses` 直接替换 `dataclasses`；
+ 在本例中，它是一个 `Item` 数据类列表。
+6. 这里我们返回一个字典，里面的 `items` 是一个数据类列表。
-3. `Author` 数据类包含 `Item` 数据类列表；
+ FastAPI 仍然能够将数据序列化为 JSON。
+7. 这里的 `response_model` 使用了 “`Author` 数据类列表” 的类型注解。
-4. `Author` 数据类用于 `response_model` 参数；
+ 同样，你可以将 `dataclasses` 与标准类型注解组合使用。
+8. 注意，这个 *路径操作函数* 使用的是常规的 `def` 而不是 `async def`。
-5. 其它带有数据类的标准类型注解也可以作为请求体；
+ 一如既往，在 FastAPI 中你可以按需组合 `def` 和 `async def`。
- 本例使用的是 `Item` 数据类列表；
+ 如果需要回顾何时用哪一个，请查看关于 [`async` 和 `await`](../async.md#in-a-hurry){.internal-link target=_blank} 的文档中的 _“急不可待？”_ 一节。
+9. 这个 *路径操作函数* 返回的不是数据类（当然也可以返回数据类），而是包含内部数据的字典列表。
-6. 这行代码返回的是包含 `items` 的字典，`items` 是数据类列表；
+ FastAPI 会使用（包含数据类的）`response_model` 参数来转换响应。
- FastAPI 仍能把数据序列化为 JSON；
+你可以将 `dataclasses` 与其它类型注解以多种不同方式组合，来构建复杂的数据结构。
-7. 这行代码中，`response_model` 的类型注解是 `Author` 数据类列表；
+更多细节请参考上面代码中的内联注释提示。
- 再一次，可以把 `dataclasses` 与标准类型注解一起使用；
+## 深入学习 { #learn-more }
-8. 注意，*路径操作函数*使用的是普通函数，不是异步函数；
+你还可以把 `dataclasses` 与其它 Pydantic 模型组合、从它们继承、把它们包含到你自己的模型中等。
- 与往常一样，在 FastAPI 中，可以按需组合普通函数与异步函数；
+想了解更多，请查看 
+///
-您可以看到这些模式，因为它们是用程序中的模型声明的。
+## 来自 FastAPI 赞助商的 SDK 生成器 { #sdk-generators-from-fastapi-sponsors }
-那些信息可以在应用的 **OpenAPI模式** 被找到，然后显示在API文档中（通过Swagger UI）。
+本节介绍的是由赞助 FastAPI 的公司提供的、具备**风险投资背景**或**公司支持**的方案。这些产品在高质量生成的 SDK 之上，提供了**更多特性**和**集成**。
-OpenAPI中所包含的模型里有相同的信息可以用于 **生成客户端代码**。
+通过 ✨ [**赞助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨，这些公司帮助确保框架及其**生态**保持健康并且**可持续**。
-### 生成一个TypeScript 客户端
+他们的赞助也体现了对 FastAPI **社区**（也就是你）的高度承诺，不仅关注提供**优秀的服务**，也支持一个**健壮且繁荣的框架**——FastAPI。🙇
-现在我们有了带有模型的应用，我们可以为前端生成客户端代码。
+例如，你可以尝试：
-#### 安装 `openapi-ts`
+* 
-您还将自动补全要发送的数据：
+要发送的载荷也会有自动补全：
-/// tip
+/// tip | 提示
-请注意， `name` 和 `price` 的自动补全，是通过其在`Item`模型(FastAPI)中的定义实现的。
+请注意 `name` 和 `price` 的自动补全，它们是在 FastAPI 应用中的 `Item` 模型里定义的。
///
-如果发送的数据字段不符，你也会看到编辑器的错误提示:
+你发送的数据如果不符合要求，会在编辑器中显示内联错误：
-响应(response)对象也拥有自动补全:
+响应对象同样有自动补全：
-## 带有标签的 FastAPI 应用
+## 带有标签的 FastAPI 应用 { #fastapi-app-with-tags }
-在许多情况下，你的FastAPI应用程序会更复杂，你可能会使用标签来分隔不同组的*路径操作(path operations)*。
+很多情况下，你的 FastAPI 应用会更大，你可能会用标签来划分不同组的*路径操作*。
-例如，您可以有一个用 `items` 的部分和另一个用于 `users` 的部分，它们可以用标签来分隔：
+例如，你可以有一个 **items** 相关的部分和另一个 **users** 相关的部分，它们可以用标签来分隔：
{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
-### 生成带有标签的 TypeScript 客户端
+### 生成带标签的 TypeScript 客户端 { #generate-a-typescript-client-with-tags }
-如果您使用标签为FastAPI应用生成客户端，它通常也会根据标签分割客户端代码。
+如果你为使用了标签的 FastAPI 应用生成客户端，通常也会根据标签来拆分客户端代码。
-通过这种方式，您将能够为客户端代码进行正确地排序和分组：
+这样你就可以在客户端代码中把内容正确地组织和分组：
-在这个案例中，您有：
+在这个例子中，你会有：
* `ItemsService`
* `UsersService`
-### 客户端方法名称
+### 客户端方法名 { #client-method-names }
-现在生成的方法名像 `createItemItemsPost` 看起来不太简洁:
+现在，像 `createItemItemsPost` 这样的生成方法名看起来不太简洁：
```TypeScript
ItemsService.createItemItemsPost({name: "Plumbus", price: 5})
```
-...这是因为客户端生成器为每个 *路径操作* 使用OpenAPI的内部 **操作 ID(operation ID)**。
+……这是因为客户端生成器会把每个*路径操作*的 OpenAPI 内部**操作 ID（operation ID）**用作方法名的一部分。
-OpenAPI要求每个操作 ID 在所有 *路径操作* 中都是唯一的，因此 FastAPI 使用**函数名**、**路径**和**HTTP方法/操作**来生成此操作ID，因为这样可以确保这些操作 ID 是唯一的。
+OpenAPI 要求每个操作 ID 在所有*路径操作*中都是唯一的，因此 FastAPI 会使用**函数名**、**路径**和**HTTP 方法/操作**来生成操作 ID，以确保其唯一性。
-但接下来我会告诉你如何改进。 🤓
+接下来我会告诉你如何改进。🤓
-## 自定义操作ID和更好的方法名
+## 自定义操作 ID 与更好的方法名 { #custom-operation-ids-and-better-method-names }
-您可以**修改**这些操作ID的**生成**方式，以使其更简洁，并在客户端中具有**更简洁的方法名称**。
+你可以**修改**这些操作 ID 的**生成**方式，使之更简单，从而在客户端中得到**更简洁的方法名**。
-在这种情况下，您必须确保每个操作ID在其他方面是**唯一**的。
+在这种情况下，你需要用其他方式确保每个操作 ID 依然是**唯一**的。
-例如，您可以确保每个*路径操作*都有一个标签，然后根据**标签**和*路径操作***名称**（函数名）来生成操作ID。
+例如，你可以确保每个*路径操作*都有一个标签，然后基于**标签**和*路径操作***名称**（函数名）来生成操作 ID。
-### 自定义生成唯一ID函数
+### 自定义唯一 ID 生成函数 { #custom-generate-unique-id-function }
-FastAPI为每个*路径操作*使用一个**唯一ID**，它用于**操作ID**，也用于任何所需自定义模型的名称，用于请求或响应。
+FastAPI 为每个*路径操作*使用一个**唯一 ID**，它既用于**操作 ID**，也用于请求或响应里任何需要的自定义模型名称。
-你可以自定义该函数。它接受一个 `APIRoute` 对象作为输入，并输出一个字符串。
+你可以自定义这个函数。它接收一个 `APIRoute` 并返回一个字符串。
-例如，以下是一个示例，它使用第一个标签（你可能只有一个标签）和*路径操作*名称（函数名）。
+例如，这里使用第一个标签（你很可能只有一个标签）和*路径操作*名称（函数名）。
-然后，你可以将这个自定义函数作为 `generate_unique_id_function` 参数传递给 **FastAPI**:
+然后你可以把这个自定义函数通过 `generate_unique_id_function` 参数传给 **FastAPI**：
{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
-### 使用自定义操作ID生成TypeScript客户端
+### 使用自定义操作 ID 生成 TypeScript 客户端 { #generate-a-typescript-client-with-custom-operation-ids }
-现在，如果你再次生成客户端，你会发现它具有改善的方法名称：
+现在再次生成客户端，你会看到方法名已经改进：
-正如你所见，现在方法名称中只包含标签和函数名，不再包含URL路径和HTTP操作的信息。
+如你所见，方法名现在由标签和函数名组成，不再包含 URL 路径和 HTTP 操作的信息。
+
+### 为客户端生成器预处理 OpenAPI 规范 { #preprocess-the-openapi-specification-for-the-client-generator }
-### 预处理用于客户端生成器的OpenAPI规范
+生成的代码中仍有一些**重复信息**。
-生成的代码仍然存在一些**重复的信息**。
+我们已经知道这个方法与 **items** 有关，因为它位于 `ItemsService`（来自标签），但方法名里仍然带有标签名前缀。😕
-我们已经知道该方法与 **items** 相关，因为它在 `ItemsService` 中（从标签中获取），但方法名中仍然有标签名作为前缀。😕
+通常我们仍然希望在 OpenAPI 中保留它，以确保操作 ID 的**唯一性**。
-一般情况下对于OpenAPI，我们可能仍然希望保留它，因为这将确保操作ID是**唯一的**。
+但对于生成的客户端，我们可以在生成之前**修改** OpenAPI 的操作 ID，只是为了让方法名更美观、更**简洁**。
-但对于生成的客户端，我们可以在生成客户端之前**修改** OpenAPI 操作ID，以使方法名称更加美观和**简洁**。
+我们可以把 OpenAPI JSON 下载到 `openapi.json` 文件中，然后用如下脚本**移除这个标签前缀**：
-我们可以将 OpenAPI JSON 下载到一个名为`openapi.json`的文件中，然后使用以下脚本**删除此前缀的标签**：
+{* ../../docs_src/generate_clients/tutorial004_py39.py *}
+
+//// tab | Node.js
+
+```Javascript
+{!> ../../docs_src/generate_clients/tutorial004.js!}
+```
-{* ../../docs_src/generate_clients/tutorial004.py *}
+////
-通过这样做，操作ID将从类似于 `items-get_items` 的名称重命名为 `get_items` ，这样客户端生成器就可以生成更简洁的方法名称。
+这样，操作 ID 会从 `items-get_items` 之类的名字重命名为 `get_items`，从而让客户端生成器生成更简洁的方法名。
-### 使用预处理的OpenAPI生成TypeScript客户端
+### 使用预处理后的 OpenAPI 生成 TypeScript 客户端 { #generate-a-typescript-client-with-the-preprocessed-openapi }
-现在，由于最终结果保存在文件openapi.json中，你可以修改 package.json 文件以使用此本地文件，例如：
+因为最终结果现在保存在 `openapi.json` 中，你需要更新输入位置：
-```JSON hl_lines="7"
-{
- "name": "frontend-app",
- "version": "1.0.0",
- "description": "",
- "main": "index.js",
- "scripts": {
- "generate-client": "openapi-ts --input ./openapi.json --output ./src/client --client axios"
- },
- "author": "",
- "license": "",
- "devDependencies": {
- "@hey-api/openapi-ts": "^0.27.38",
- "typescript": "^4.6.2"
- }
-}
+```sh
+npx @hey-api/openapi-ts -i ./openapi.json -o src/client
```
-生成新的客户端之后，你现在将拥有**清晰的方法名称**，具备**自动补全**、**错误提示**等功能：
+生成新客户端后，你将拥有**简洁的方法名**，并具备**自动补全**、**内联错误**等功能：
-## 优点
+## 优点 { #benefits }
-当使用自动生成的客户端时，你将获得以下的自动补全功能：
+使用自动生成的客户端时，你会获得以下内容的**自动补全**：
-* 方法。
-* 请求体中的数据、查询参数等。
-* 响应数据。
+* 方法
+* 请求体中的数据、查询参数等
+* 响应数据
-你还将获得针对所有内容的错误提示。
+你还会为所有内容获得**内联错误**。
-每当你更新后端代码并**重新生成**前端代码时，新的*路径操作*将作为方法可用，旧的方法将被删除，并且其他任何更改将反映在生成的代码中。 🤓
+每当你更新后端代码并**重新生成**前端时，新的*路径操作*会作为方法可用，旧的方法会被移除，其他任何更改都会反映到生成的代码中。🤓
-这也意味着如果有任何更改，它将自动**反映**在客户端代码中。如果你**构建**客户端，在使用的数据上存在**不匹配**时，它将报错。
+这也意味着如果有任何变更，它会自动**反映**到客户端代码中。而当你**构建**客户端时，如果所用数据存在任何**不匹配**，它会直接报错。
-因此，你将在开发周期的早期**检测到许多错误**，而不必等待错误在生产环境中向最终用户展示，然后尝试调试问题所在。 ✨
+因此，你可以在开发周期的早期就**发现许多错误**，而不必等到错误在生产环境中暴露给最终用户后再去调试问题所在。✨
diff --git a/docs/zh/docs/advanced/index.md b/docs/zh/docs/advanced/index.md
index 6525802fca..610c187137 100644
--- a/docs/zh/docs/advanced/index.md
+++ b/docs/zh/docs/advanced/index.md
@@ -1,21 +1,21 @@
-# 高级用户指南
+# 高级用户指南 { #advanced-user-guide }
-## 额外特性
+## 附加功能 { #additional-features }
-主要的教程 [教程 - 用户指南](../tutorial/index.md){.internal-link target=_blank} 应该足以让你了解 **FastAPI** 的所有主要特性。
+主要的[教程 - 用户指南](../tutorial/index.md){.internal-link target=_blank}足以带你了解 **FastAPI** 的所有主要特性。
-你会在接下来的章节中了解到其他的选项、配置以及额外的特性。
+在接下来的章节中，你将看到其他选项、配置和附加功能。
-/// tip
+/// tip | 提示
-接下来的章节**并不一定是**「高级的」。
+接下来的章节不一定是“高级”的。
-而且对于你的使用场景来说，解决方案很可能就在其中。
+对于你的用例，解决方案很可能就在其中之一。
///
-## 先阅读教程
+## 先阅读教程 { #read-the-tutorial-first }
-你可能仍会用到 **FastAPI** 主教程 [教程 - 用户指南](../tutorial/index.md){.internal-link target=_blank} 中的大多数特性。
+仅凭主要[教程 - 用户指南](../tutorial/index.md){.internal-link target=_blank}中的知识，你已经可以使用 **FastAPI** 的大多数功能。
-接下来的章节我们认为你已经读过 [教程 - 用户指南](../tutorial/index.md){.internal-link target=_blank}，并且假设你已经知晓其中主要思想。
+接下来的章节默认你已经读过它，并理解其中的核心概念。
diff --git a/docs/zh/docs/advanced/middleware.md b/docs/zh/docs/advanced/middleware.md
index 65e8c183f2..108bbbb5c1 100644
--- a/docs/zh/docs/advanced/middleware.md
+++ b/docs/zh/docs/advanced/middleware.md
@@ -1,4 +1,4 @@
-# 高级中间件
+# 高级中间件 { #advanced-middleware }
用户指南介绍了如何为应用添加[自定义中间件](../tutorial/middleware.md){.internal-link target=_blank} 。
@@ -6,9 +6,9 @@
本章学习如何使用其它中间件。
-## 添加 ASGI 中间件
+## 添加 ASGI 中间件 { #adding-asgi-middlewares }
-因为 **FastAPI** 基于 Starlette，且执行 ASGI 规范，所以可以使用任意 ASGI 中间件。
+因为 **FastAPI** 基于 Starlette，且执行 ASGI 规范，所以可以使用任意 ASGI 中间件。
中间件不必是专为 FastAPI 或 Starlette 定制的，只要遵循 ASGI 规范即可。
@@ -39,11 +39,11 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
`app.add_middleware()` 的第一个参数是中间件的类，其它参数则是要传递给中间件的参数。
-## 集成中间件
+## 集成中间件 { #integrated-middlewares }
**FastAPI** 为常见用例提供了一些中间件，下面介绍怎么使用这些中间件。
-/// note | 技术细节
+/// note | 注意
以下几个示例中也可以使用 `from starlette.middleware.something import SomethingMiddleware`。
@@ -51,45 +51,47 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
///
-## `HTTPSRedirectMiddleware`
+## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware }
强制所有传入请求必须是 `https` 或 `wss`。
任何传向 `http` 或 `ws` 的请求都会被重定向至安全方案。
-{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
+{* ../../docs_src/advanced_middleware/tutorial001_py39.py hl[2,6] *}
-## `TrustedHostMiddleware`
+## `TrustedHostMiddleware` { #trustedhostmiddleware }
强制所有传入请求都必须正确设置 `Host` 请求头，以防 HTTP 主机头攻击。
-{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
+{* ../../docs_src/advanced_middleware/tutorial002_py39.py hl[2,6:8] *}
支持以下参数：
-* `allowed_hosts` - 允许的域名（主机名）列表。`*.example.com` 等通配符域名可以匹配子域名，或使用 `allowed_hosts=["*"]` 允许任意主机名，或省略中间件。
+* `allowed_hosts` - 允许的域名（主机名）列表。`*.example.com` 等通配符域名可以匹配子域名。若要允许任意主机名，可使用 `allowed_hosts=["*"]` 或省略此中间件。
+* `www_redirect` - 若设置为 `True`，对允许主机的非 www 版本的请求将被重定向到其 www 版本。默认为 `True`。
如果传入的请求没有通过验证，则发送 `400` 响应。
-## `GZipMiddleware`
+## `GZipMiddleware` { #gzipmiddleware }
-处理 `Accept-Encoding` 请求头中包含 `gzip` 请求的 GZip 响应。
+处理 `Accept-Encoding` 请求头中包含 `"gzip"` 请求的 GZip 响应。
中间件会处理标准响应与流响应。
-{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
+{* ../../docs_src/advanced_middleware/tutorial003_py39.py hl[2,6] *}
支持以下参数：
-* `minimum_size` - 小于最小字节的响应不使用 GZip。 默认值是 `500`。
+* `minimum_size` - 小于该最小字节数的响应不使用 GZip。默认值是 `500`。
+* `compresslevel` - GZip 压缩使用的级别，为 1 到 9 的整数。默认为 `9`。值越低压缩越快但文件更大，值越高压缩越慢但文件更小。
-## 其它中间件
+## 其它中间件 { #other-middlewares }
除了上述中间件外，FastAPI 还支持其它ASGI 中间件。
例如：
-* 
+
+如果你查看最终生成的 OpenAPI（在你的 API 的 `/openapi.json`），你也会看到你的扩展作为该 *路径操作* 的一部分：
+
+```JSON hl_lines="22"
+{
+ "openapi": "3.1.0",
+ "info": {
+ "title": "FastAPI",
+ "version": "0.1.0"
+ },
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ }
+ }
+ },
+ "x-aperture-labs-portal": "blue"
+ }
+ }
+ }
+}
+```
+
+### 自定义 OpenAPI 路径操作方案 { #custom-openapi-path-operation-schema }
+
+`openapi_extra` 中的字典会与该 *路径操作* 自动生成的 OpenAPI 方案进行深度合并。
+
+因此，你可以在自动生成的方案上添加额外数据。
+
+例如，你可以决定用自己的代码读取并验证请求，而不使用 FastAPI 与 Pydantic 的自动功能，但你仍然希望在 OpenAPI 方案中定义该请求。
+
+你可以用 `openapi_extra` 来做到：
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.py hl[19:36, 39:40] *}
+
+在这个示例中，我们没有声明任何 Pydantic 模型。事实上，请求体甚至没有被 解析 为 JSON，而是直接以 `bytes` 读取，并由函数 `magic_data_reader()` 以某种方式负责解析。
+
+尽管如此，我们仍然可以声明请求体的预期方案。
+
+### 自定义 OpenAPI 内容类型 { #custom-openapi-content-type }
+
+使用同样的技巧，你可以用一个 Pydantic 模型来定义 JSON Schema，然后把它包含到该 *路径操作* 的自定义 OpenAPI 方案部分中。
+
+即使请求中的数据类型不是 JSON，你也可以这样做。
+
+例如，在这个应用中我们不使用 FastAPI 集成的从 Pydantic 模型提取 JSON Schema 的功能，也不使用对 JSON 的自动校验。实际上，我们将请求的内容类型声明为 YAML，而不是 JSON：
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *}
+
+尽管我们没有使用默认的集成功能，我们仍然使用 Pydantic 模型手动生成我们想以 YAML 接收的数据的 JSON Schema。
+
+然后我们直接使用请求并将请求体提取为 `bytes`。这意味着 FastAPI 甚至不会尝试将请求负载解析为 JSON。
+
+接着在我们的代码中，我们直接解析该 YAML 内容，然后再次使用同一个 Pydantic 模型来验证该 YAML 内容：
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *}
+
+/// tip
+
+这里我们复用了同一个 Pydantic 模型。
+
+但同样地，我们也可以用其他方式对其进行验证。
+
+///
diff --git a/docs/zh/docs/advanced/response-change-status-code.md b/docs/zh/docs/advanced/response-change-status-code.md
index cc1f2a73eb..cdcd39f50c 100644
--- a/docs/zh/docs/advanced/response-change-status-code.md
+++ b/docs/zh/docs/advanced/response-change-status-code.md
@@ -1,10 +1,10 @@
-# 响应 - 更改状态码
+# 响应 - 更改状态码 { #response-change-status-code }
你可能之前已经了解到，你可以设置默认的[响应状态码](../tutorial/response-status-code.md){.internal-link target=_blank}。
但在某些情况下，你需要返回一个不同于默认值的状态码。
-## 使用场景
+## 使用场景 { #use-case }
例如，假设你想默认返回一个HTTP状态码为“OK”`200`。
@@ -14,16 +14,16 @@
对于这些情况，你可以使用一个`Response`参数。
-## 使用 `Response` 参数
+## 使用 `Response` 参数 { #use-a-response-parameter }
你可以在你的*路径操作函数*中声明一个`Response`类型的参数（就像你可以为cookies和头部做的那样）。
然后你可以在这个*临时*响应对象中设置`status_code`。
-{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
+{* ../../docs_src/response_change_status_code/tutorial001_py39.py hl[1,9,12] *}
然后你可以像平常一样返回任何你需要的对象（例如一个`dict`或者一个数据库模型）。如果你声明了一个`response_model`，它仍然会被用来过滤和转换你返回的对象。
-**FastAPI**将使用这个临时响应来提取状态码（也包括cookies和头部），并将它们放入包含你返回的值的最终响应中，该响应由任何`response_model`过滤。
+**FastAPI**将使用这个*临时*响应来提取状态码（也包括cookies和头部），并将它们放入包含你返回的值的最终响应中，该响应由任何`response_model`过滤。
你也可以在依赖项中声明`Response`参数，并在其中设置状态码。但请注意，最后设置的状态码将会生效。
diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md
index d5f2fe6fc5..cc311a2708 100644
--- a/docs/zh/docs/advanced/response-cookies.md
+++ b/docs/zh/docs/advanced/response-cookies.md
@@ -1,10 +1,10 @@
-# 响应Cookies
+# 响应Cookies { #response-cookies }
-## 使用 `Response` 参数
+## 使用 `Response` 参数 { #use-a-response-parameter }
-你可以在 *路径函数* 中定义一个类型为 `Response`的参数，这样你就可以在这个临时响应对象中设置cookie了。
+你可以在 *路径操作函数* 中定义一个类型为 `Response` 的参数，这样你就可以在这个临时响应对象中设置cookie了。
-{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *}
+{* ../../docs_src/response_cookies/tutorial002_py39.py hl[1, 8:9] *}
而且你还可以根据你的需要响应不同的对象，比如常用的 `dict`，数据库model等。
@@ -12,17 +12,17 @@
**FastAPI** 会使用这个 *临时* 响应对象去装在这些cookies信息 (同样还有headers和状态码等信息), 最终会将这些信息和通过`response_model`转化过的数据合并到最终的响应里。
-你也可以在depend中定义`Response`参数，并设置cookie和header。
+你也可以在依赖中定义`Response`参数，并设置cookie和header。
-## 直接响应 `Response`
+## 直接响应 `Response` { #return-a-response-directly }
你还可以在直接响应`Response`时直接创建cookies。
-你可以参考[Return a Response Directly](response-directly.md){.internal-link target=_blank}来创建response
+你可以参考[直接返回 Response](response-directly.md){.internal-link target=_blank}来创建response
然后设置Cookies，并返回：
-{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
+{* ../../docs_src/response_cookies/tutorial001_py39.py hl[10:12] *}
/// tip
@@ -34,7 +34,7 @@
///
-### 更多信息
+### 更多信息 { #more-info }
/// note | 技术细节
diff --git a/docs/zh/docs/advanced/response-directly.md b/docs/zh/docs/advanced/response-directly.md
index 4d9cd53f2f..8a9cf6ab89 100644
--- a/docs/zh/docs/advanced/response-directly.md
+++ b/docs/zh/docs/advanced/response-directly.md
@@ -1,4 +1,4 @@
-# 直接返回响应
+# 直接返回响应 { #return-a-response-directly }
当你创建一个 **FastAPI** *路径操作* 时，你可以正常返回以下任意一种数据：`dict`，`list`，Pydantic 模型，数据库模型等等。
@@ -10,11 +10,11 @@
直接返回响应可能会有用处，比如返回自定义的响应头和 cookies。
-## 返回 `Response`
+## 返回 `Response` { #return-a-response }
事实上，你可以返回任意 `Response` 或者任意 `Response` 的子类。
-/// tip | 小贴士
+/// tip | 提示
`JSONResponse` 本身是一个 `Response` 的子类。
@@ -26,18 +26,17 @@
这种特性给你极大的可扩展性。你可以返回任何数据类型，重写任何数据声明或者校验，等等。
-## 在 `Response` 中使用 `jsonable_encoder`
+## 在 `Response` 中使用 `jsonable_encoder` { #using-the-jsonable-encoder-in-a-response }
由于 **FastAPI** 并未对你返回的 `Response` 做任何改变，你必须确保你已经准备好响应内容。
-例如，如果不首先将 Pydantic 模型转换为 `dict`，并将所有数据类型（如 `datetime`、`UUID` 等）转换为兼容 JSON 的类型，则不能将其放入JSONResponse中。
+例如，如果不首先将 Pydantic 模型转换为 `dict`，并将所有数据类型（如 `datetime`、`UUID` 等）转换为兼容 JSON 的类型，则不能将其放入 `JSONResponse` 中。
-对于这些情况，在将数据传递给响应之前，你可以使用 `jsonable_encoder` 来转换你的数据。
+对于这些情况，在将数据传递给响应之前，你可以使用 `jsonable_encoder` 来转换你的数据：
+{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *}
-{* ../../docs_src/response_directly/tutorial001.py hl[4,6,20,21] *}
-
-/// note | 技术细节
+/// note | 注意
你也可以使用 `from starlette.responses import JSONResponse`。
@@ -45,22 +44,22 @@
///
-## 返回自定义 `Response`
+## 返回自定义 `Response` { #returning-a-custom-response }
-上面的例子展示了需要的所有部分，但还不够实用，因为你本可以只是直接返回 `item`，而**FastAPI** 默认帮你把这个 `item` 放到 `JSONResponse` 中，又默认将其转换成了 `dict`等等。
+上面的例子展示了需要的所有部分，但还不够实用，因为你本可以只是直接返回 `item`，而 **FastAPI** 默认帮你把这个 `item` 放到 `JSONResponse` 中，又默认将其转换成了 `dict` 等等。
现在，让我们看看你如何才能返回一个自定义的响应。
假设你想要返回一个 
-## 检查用户名
+## 检查用户名 { #check-the-username }
以下是更完整的示例。
@@ -52,13 +52,13 @@ if not (credentials.username == "stanleyjobson") or not (credentials.password ==
但使用 `secrets.compare_digest()`，可以防御**时差攻击**，更加安全。
-### 时差攻击
+### 时差攻击 { #timing-attacks }
什么是**时差攻击**？
假设攻击者试图猜出用户名与密码。
-他们发送用户名为 `johndoe`，密码为 `love123` 的请求。
+他们发送用户名为 `johndoe`，密码为 `love123` 的请求。
然后，Python 代码执行如下操作：
@@ -80,28 +80,28 @@ if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
此时，Python 要对比 `stanleyjobsox` 与 `stanleyjobson` 中的 `stanleyjobso`，才能知道这两个字符串不一样。因此会多花费几微秒来返回**错误的用户或密码**。
-#### 反应时间对攻击者的帮助
+#### 反应时间对攻击者的帮助 { #the-time-to-answer-helps-the-attackers }
通过服务器花费了更多微秒才发送**错误的用户或密码**响应，攻击者会知道猜对了一些内容，起码开头字母是正确的。
然后，他们就可以放弃 `johndoe`，再用类似 `stanleyjobsox` 的内容进行尝试。
-#### **专业**攻击
+#### **专业**攻击 { #a-professional-attack }
当然，攻击者不用手动操作，而是编写每秒能执行成千上万次测试的攻击程序，每次都会找到更多正确字符。
但是，在您的应用的**帮助**下，攻击者利用时间差，就能在几分钟或几小时内，以这种方式猜出正确的用户名和密码。
-#### 使用 `secrets.compare_digest()` 修补
+#### 使用 `secrets.compare_digest()` 修补 { #fix-it-with-secrets-compare-digest }
在此，代码中使用了 `secrets.compare_digest()`。
简单的说，它使用相同的时间对比 `stanleyjobsox` 和 `stanleyjobson`，还有 `johndoe` 和 `stanleyjobson`。对比密码时也一样。
-在代码中使用 `secrets.compare_digest()` ，就可以安全地防御全面攻击了。
+在代码中使用 `secrets.compare_digest()` ，就可以安全地防御这整类安全攻击。
-### 返回错误
+### 返回错误 { #return-the-error }
-检测到凭证不正确后，返回 `HTTPException` 及状态码 401（与无凭证时返回的内容一样），并添加请求头 `WWW-Authenticate`，让浏览器再次显示登录提示：
+检测到凭证不正确后，返回 `HTTPException` 及状态码 401（与无凭证时返回的内容一样），并添加响应头 `WWW-Authenticate`，让浏览器再次显示登录提示：
{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}
diff --git a/docs/zh/docs/advanced/security/index.md b/docs/zh/docs/advanced/security/index.md
index 267e7ced70..84fec7aab8 100644
--- a/docs/zh/docs/advanced/security/index.md
+++ b/docs/zh/docs/advanced/security/index.md
@@ -1,19 +1,19 @@
-# 高级安全
+# 高级安全 { #advanced-security }
-## 附加特性
+## 附加特性 { #additional-features }
-除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank} 中涵盖的功能之外，还有一些额外的功能来处理安全性.
+除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank} 中涵盖的功能之外，还有一些额外的功能来处理安全性。
-/// tip | 小贴士
+/// tip | 提示
-接下来的章节 **并不一定是 "高级的"**.
+接下来的章节**并不一定是 "高级的"**。
而且对于你的使用场景来说，解决方案很可能就在其中。
///
-## 先阅读教程
+## 先阅读教程 { #read-the-tutorial-first }
-接下来的部分假设你已经阅读了主要的 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank}.
+接下来的部分假设你已经阅读了主要的 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank}。
-它们都基于相同的概念，但支持一些额外的功能.
+它们都基于相同的概念，但支持一些额外的功能。
diff --git a/docs/zh/docs/advanced/security/oauth2-scopes.md b/docs/zh/docs/advanced/security/oauth2-scopes.md
index 784c384901..ce7facf4be 100644
--- a/docs/zh/docs/advanced/security/oauth2-scopes.md
+++ b/docs/zh/docs/advanced/security/oauth2-scopes.md
@@ -1,274 +1,274 @@
-# OAuth2 作用域
+# OAuth2 作用域 { #oauth2-scopes }
-**FastAPI** 无缝集成 OAuth2 作用域（`Scopes`），可以直接使用。
+你可以在 **FastAPI** 中直接使用 OAuth2 作用域（Scopes），它们已无缝集成。
-作用域是更精密的权限系统，遵循 OAuth2 标准，与 OpenAPI 应用（和 API 自动文档）集成。
+这样你就可以按照 OAuth2 标准，构建更精细的权限系统，并将其集成进你的 OpenAPI 应用（以及 API 文档）中。
-OAuth2 也是脸书、谷歌、GitHub、微软、推特等第三方身份验证应用使用的机制。这些身份验证应用在用户登录应用时使用 OAuth2 提供指定权限。
+带作用域的 OAuth2 是很多大型身份验证提供商使用的机制，例如 Facebook、Google、GitHub、Microsoft、X (Twitter) 等。它们用它来为用户和应用授予特定权限。
-脸书、谷歌、GitHub、微软、推特就是 OAuth2 作用域登录。
+每次你“使用” Facebook、Google、GitHub、Microsoft、X (Twitter) “登录”时，该应用就在使用带作用域的 OAuth2。
-本章介绍如何在 **FastAPI** 应用中使用 OAuth2 作用域管理验证与授权。
+本节将介绍如何在你的 **FastAPI** 应用中，使用相同的带作用域的 OAuth2 管理认证与授权。
/// warning | 警告
-本章内容较难，刚接触 FastAPI 的新手可以跳过。
+本节内容相对进阶，如果你刚开始，可以先跳过。
-OAuth2 作用域不是必需的，没有它，您也可以处理身份验证与授权。
+你并不一定需要 OAuth2 作用域，你也可以用你自己的方式处理认证与授权。
-但 OAuth2 作用域与 API（通过 OpenAPI）及 API 文档集成地更好。
+但带作用域的 OAuth2 能很好地集成进你的 API（通过 OpenAPI）和 API 文档。
-不管怎么说，**FastAPI** 支持在代码中使用作用域或其它安全/授权需求项。
+不过，无论如何，你都可以在代码中按需强制这些作用域，或任何其它安全/授权需求。
-很多情况下，OAuth2 作用域就像一把牛刀。
+很多情况下，带作用域的 OAuth2 可能有点“大材小用”。
-但如果您确定要使用作用域，或对它有兴趣，请继续阅读。
+但如果你确实需要它，或者只是好奇，请继续阅读。
///
-## OAuth2 作用域与 OpenAPI
+## OAuth2 作用域与 OpenAPI { #oauth2-scopes-and-openapi }
-OAuth2 规范的**作用域**是由空格分割的字符串组成的列表。
+OAuth2 规范将“作用域”定义为由空格分隔的字符串列表。
-这些字符串支持任何格式，但不能包含空格。
+这些字符串的内容可以是任意格式，但不应包含空格。
-作用域表示的是**权限**。
+这些作用域表示“权限”。
-OpenAPI 中（例如 API 文档）可以定义**安全方案**。
+在 OpenAPI（例如 API 文档）中，你可以定义“安全方案”（security schemes）。
-这些安全方案在使用 OAuth2 时，还可以声明和使用作用域。
+当这些安全方案使用 OAuth2 时，你还可以声明并使用作用域。
-**作用域**只是（不带空格的）字符串。
+每个“作用域”只是一个（不带空格的）字符串。
-常用于声明特定安全权限，例如：
+它们通常用于声明特定的安全权限，例如：
-* 常见用例为，`users:read` 或 `users:write`
-* 脸书和 Instagram 使用 `instagram_basic`
-* 谷歌使用 `https://www.googleapis.com/auth/drive`
+* 常见示例：`users:read` 或 `users:write`
+* Facebook / Instagram 使用 `instagram_basic`
+* Google 使用 `https://www.googleapis.com/auth/drive`
-/// info | 说明
+/// info | 信息
-OAuth2 中，**作用域**只是声明特定权限的字符串。
+在 OAuth2 中，“作用域”只是一个声明所需特定权限的字符串。
-是否使用冒号 `:` 等符号，或是不是 URL 并不重要。
+是否包含像 `:` 这样的字符，或者是不是一个 URL，并不重要。
-这些细节只是特定的实现方式。
+这些细节取决于具体实现。
-对 OAuth2 来说，它们都只是字符串而已。
+对 OAuth2 而言，它们都只是字符串。
///
-## 全局纵览
+## 全局纵览 { #global-view }
-首先，快速浏览一下以下代码与**用户指南**中 [OAuth2 实现密码哈希与 Bearer JWT 令牌验证](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}一章中代码的区别。以下代码使用 OAuth2 作用域：
+首先，让我们快速看看与**用户指南**中 [OAuth2 实现密码（含哈希）、Bearer + JWT 令牌](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank} 示例相比有哪些变化。现在开始使用 OAuth2 作用域：
-{* ../../docs_src/security/tutorial005.py hl[2,4,8,12,46,64,105,107:115,121:124,128:134,139,153] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *}
-下面，我们逐步说明修改的代码内容。
+下面我们逐步回顾这些更改。
-## OAuth2 安全方案
+## OAuth2 安全方案 { #oauth2-security-scheme }
-第一个修改的地方是，使用两个作用域 `me` 和 `items ` 声明 OAuth2 安全方案。
+第一个变化是：我们在声明 OAuth2 安全方案时，添加了两个可用的作用域 `me` 和 `items`。
-`scopes` 参数接收**字典**，键是作用域、值是作用域的描述：
+参数 `scopes` 接收一个 `dict`，以作用域为键、描述为值：
-{* ../../docs_src/security/tutorial005.py hl[62:65] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
-因为声明了作用域，所以登录或授权时会在 API 文档中显示。
+因为我们现在声明了这些作用域，所以当你登录/授权时，它们会显示在 API 文档里。
-此处，选择给予访问权限的作用域： `me` 和 `items`。
+你可以选择要授予访问权限的作用域：`me` 和 `items`。
-这也是使用脸书、谷歌、GitHub 登录时的授权机制。
+这与使用 Facebook、Google、GitHub 等登录时授予权限的机制相同：
-## JWT 令牌作用域
+## 带作用域的 JWT 令牌 { #jwt-token-with-scopes }
-现在，修改令牌*路径操作*，返回请求的作用域。
+现在，修改令牌的*路径操作*以返回请求的作用域。
-此处仍然使用 `OAuth2PasswordRequestForm`。它包含类型为**字符串列表**的 `scopes` 属性，且`scopes` 属性中包含要在请求里接收的每个作用域。
+我们仍然使用 `OAuth2PasswordRequestForm`。它包含 `scopes` 属性，其值是 `list[str]`，包含请求中接收到的每个作用域。
-这样，返回的 JWT 令牌中就包含了作用域。
+我们把这些作用域作为 JWT 令牌的一部分返回。
/// danger | 危险
-为了简明起见，本例把接收的作用域直接添加到了令牌里。
+为简单起见，此处我们只是把接收到的作用域直接添加到了令牌中。
-但在您的应用中，为了安全，应该只把作用域添加到确实需要作用域的用户，或预定义的用户。
+但在你的应用里，为了安全起见，你应该只添加该用户实际能够拥有的作用域，或你预先定义的作用域。
///
-{* ../../docs_src/security/tutorial005.py hl[153] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *}
-## 在*路径操作*与依赖项中声明作用域
+## 在*路径操作*与依赖项中声明作用域 { #declare-scopes-in-path-operations-and-dependencies }
-接下来，为*路径操作* `/users/me/items/` 声明作用域 `items`。
+现在我们声明，路径操作 `/users/me/items/` 需要作用域 `items`。
-为此，要从 `fastapi` 中导入并使用 `Security` 。
+为此，从 `fastapi` 导入并使用 `Security`。
-`Security` 声明依赖项的方式和 `Depends` 一样，但 `Security` 还能接收作用域（字符串）列表类型的参数 `scopes`。
+你可以用 `Security` 来声明依赖（就像 `Depends` 一样），但 `Security` 还接收一个 `scopes` 参数，其值是作用域（字符串）列表。
-此处使用与 `Depends` 相同的方式，把依赖项函数 `get_current_active_user` 传递给 `Security`。
+在这里，我们把依赖函数 `get_current_active_user` 传给 `Security`（就像用 `Depends` 一样）。
-同时，还传递了作用域**列表**，本例中只传递了一个作用域：`items`（此处支持传递更多作用域）。
+同时还传入一个作用域 `list`，此处仅包含一个作用域：`items`（也可以包含更多）。
-依赖项函数 `get_current_active_user` 还能声明子依赖项，不仅可以使用 `Depends`，也可以使用 `Security`。声明子依赖项函数（`get_current_user`）及更多作用域。
+依赖函数 `get_current_active_user` 也可以声明子依赖，不仅可以用 `Depends`，也可以用 `Security`。它声明了自己的子依赖函数（`get_current_user`），并添加了更多的作用域需求。
-本例要求使用作用域 `me`（还可以使用更多作用域）。
+在这个例子里，它需要作用域 `me`（也可以需要多个作用域）。
-/// note | 笔记
+/// note | 注意
不必在不同位置添加不同的作用域。
-本例使用的这种方式只是为了展示 **FastAPI** 如何处理在不同层级声明的作用域。
+这里这样做，是为了演示 **FastAPI** 如何处理在不同层级声明的作用域。
///
-{* ../../docs_src/security/tutorial005.py hl[4,139,166] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
/// info | 技术细节
-`Security` 实际上是 `Depends` 的子类，而且只比 `Depends` 多一个参数。
+`Security` 实际上是 `Depends` 的子类，它只多了一个我们稍后会看到的参数。
-但使用 `Security` 代替 `Depends`，**FastAPI** 可以声明安全作用域，并在内部使用这些作用域，同时，使用 OpenAPI 存档 API。
+但当你使用 `Security` 而不是 `Depends` 时，**FastAPI** 会知道它可以声明安全作用域，在内部使用它们，并用 OpenAPI 文档化 API。
-但实际上，从 `fastapi` 导入的 `Query`、`Path`、`Depends`、`Security` 等对象，只是返回特殊类的函数。
+另外，从 `fastapi` 导入的 `Query`、`Path`、`Depends`、`Security` 等，实际上都是返回特殊类的函数。
///
-## 使用 `SecurityScopes`
+## 使用 `SecurityScopes` { #use-securityscopes }
-修改依赖项 `get_current_user`。
+现在更新依赖项 `get_current_user`。
-这是上面的依赖项使用的依赖项。
+上面那些依赖会用到它。
-这里使用的也是之前创建的 OAuth2 方案，并把它声明为依赖项：`oauth2_scheme`。
+这里我们使用之前创建的同一个 OAuth2 方案，并把它声明为依赖：`oauth2_scheme`。
-该依赖项函数本身不需要作用域，因此，可以使用 `Depends` 和 `oauth2_scheme`。不需要指定安全作用域时，不必使用 `Security`。
+因为这个依赖函数本身没有任何作用域需求，所以我们可以用 `Depends(oauth2_scheme)`，当不需要指定安全作用域时，不必使用 `Security`。
-此处还声明了从 `fastapi.security` 导入的 `SecurityScopes` 类型的特殊参数。
+我们还声明了一个从 `fastapi.security` 导入的特殊参数 `SecurityScopes` 类型。
-`SecuriScopes` 类与 `Request` 类似（`Request` 用于直接提取请求对象）。
+这个 `SecurityScopes` 类类似于 `Request`（`Request` 用来直接获取请求对象）。
-{* ../../docs_src/security/tutorial005.py hl[8,105] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
-## 使用 `scopes`
+## 使用 `scopes` { #use-the-scopes }
参数 `security_scopes` 的类型是 `SecurityScopes`。
-它的属性 `scopes` 是作用域列表，所有依赖项都把它作为子依赖项。也就是说所有**依赖**……这听起来有些绕，后文会有解释。
+它会有一个 `scopes` 属性，包含一个列表，里面是它自身以及所有把它作为子依赖的依赖项所需要的所有作用域。也就是说，所有“依赖者”……这可能有点绕，下面会再次解释。
-（类 `SecurityScopes` 的）`security_scopes` 对象还提供了单字符串类型的属性 `scope_str`，该属性是（要在本例中使用的）用空格分割的作用域。
+`security_scopes` 对象（类型为 `SecurityScopes`）还提供了一个 `scope_str` 属性，它是一个用空格分隔这些作用域的单个字符串（我们将会用到它）。
-此处还创建了后续代码中要复用（`raise`）的 `HTTPException` 。
+我们创建一个 `HTTPException`，后面可以在多个位置复用（`raise`）它。
-该异常包含了作用域所需的（如有），以空格分割的字符串（使用 `scope_str`）。该字符串要放到包含作用域的 `WWW-Authenticate` 请求头中（这也是规范的要求）。
+在这个异常中，我们包含所需的作用域（如果有的话），以空格分隔的字符串（使用 `scope_str`）。我们把这个包含作用域的字符串放在 `WWW-Authenticate` 响应头中（这是规范要求的一部分）。
-{* ../../docs_src/security/tutorial005.py hl[105,107:115] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
-## 校验 `username` 与数据形状
+## 校验 `username` 与数据形状 { #verify-the-username-and-data-shape }
-我们可以校验是否获取了 `username`，并抽取作用域。
+我们校验是否获取到了 `username`，并提取作用域。
-然后，使用 Pydantic 模型校验数据（捕获 `ValidationError` 异常），如果读取 JWT 令牌或使用 Pydantic 模型验证数据时出错，就会触发之前创建的 `HTTPException` 异常。
+然后使用 Pydantic 模型验证这些数据（捕获 `ValidationError` 异常），如果读取 JWT 令牌或用 Pydantic 验证数据时出错，就抛出我们之前创建的 `HTTPException`。
-对此，要使用新的属性 `scopes` 更新 Pydantic 模型 `TokenData`。
+为此，我们给 Pydantic 模型 `TokenData` 添加了一个新属性 `scopes`。
-使用 Pydantic 验证数据可以确保数据中含有由作用域组成的**字符串列表**，以及 `username` 字符串等内容。
+通过用 Pydantic 验证数据，我们可以确保确实得到了例如一个由作用域组成的 `list[str]`，以及一个 `str` 类型的 `username`。
-反之，如果使用**字典**或其它数据结构，就有可能在后面某些位置破坏应用，形成安全隐患。
+而不是，例如得到一个 `dict` 或其它什么，这可能会在后续某个时刻破坏应用，形成安全风险。
-还可以使用用户名验证用户，如果没有用户，也会触发之前创建的异常。
+我们还验证是否存在该用户名的用户，如果没有，就抛出前面创建的同一个异常。
-{* ../../docs_src/security/tutorial005.py hl[46,116:127] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *}
-## 校验 `scopes`
+## 校验 `scopes` { #verify-the-scopes }
-接下来，校验所有依赖项和依赖要素（包括*路径操作*）所需的作用域。这些作用域包含在令牌的 `scopes` 里，如果不在其中就会触发 `HTTPException` 异常。
+现在我们要验证，这个依赖以及所有依赖者（包括*路径操作*）所需的所有作用域，是否都包含在接收到的令牌里的作用域中，否则就抛出 `HTTPException`。
-为此，要使用包含所有作用域**字符串列表**的 `security_scopes.scopes`， 。
+为此，我们使用 `security_scopes.scopes`，它包含一个由这些作用域组成的 `list[str]`。
-{* ../../docs_src/security/tutorial005.py hl[128:134] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *}
-## 依赖项树与作用域
+## 依赖树与作用域 { #dependency-tree-and-scopes }
-再次查看这个依赖项树与作用域。
+再次回顾这个依赖树与作用域。
-`get_current_active_user` 依赖项包含子依赖项 `get_current_user`，并在 `get_current_active_user`中声明了作用域 `"me"` 包含所需作用域列表 ，在 `security_scopes.scopes` 中传递给 `get_current_user`。
+由于 `get_current_active_user` 依赖把 `get_current_user` 作为子依赖，因此在 `get_current_active_user` 中声明的作用域 `"me"` 会被包含在传给 `get_current_user` 的 `security_scopes.scopes` 所需作用域列表中。
-*路径操作*自身也声明了作用域，`"items"`，这也是 `security_scopes.scopes` 列表传递给 `get_current_user` 的。
+*路径操作*本身也声明了一个作用域 `"items"`，它也会包含在传给 `get_current_user` 的 `security_scopes.scopes` 列表中。
-依赖项与作用域的层级架构如下：
+依赖与作用域的层级结构如下：
* *路径操作* `read_own_items` 包含：
- * 依赖项所需的作用域 `["items"]`：
- * `get_current_active_user`:
- * 依赖项函数 `get_current_active_user` 包含：
- * 所需的作用域 `"me"` 包含依赖项：
- * `get_current_user`:
- * 依赖项函数 `get_current_user` 包含：
- * 没有作用域需求其自身
- * 依赖项使用 `oauth2_scheme`
- * `security_scopes` 参数的类型是 `SecurityScopes`：
- * `security_scopes` 参数的属性 `scopes` 是包含上述声明的所有作用域的**列表**，因此：
- * `security_scopes.scopes` 包含用于*路径操作*的 `["me", "items"]`
- * `security_scopes.scopes` 包含*路径操作* `read_users_me` 的 `["me"]`，因为它在依赖项里被声明
- * `security_scopes.scopes` 包含用于*路径操作* `read_system_status` 的 `[]`（空列表），并且它的依赖项 `get_current_user` 也没有声明任何 `scope`
+ * 带有依赖的必需作用域 `["items"]`：
+ * `get_current_active_user`：
+ * 依赖函数 `get_current_active_user` 包含：
+ * 带有依赖的必需作用域 `["me"]`：
+ * `get_current_user`：
+ * 依赖函数 `get_current_user` 包含：
+ * 自身不需要任何作用域。
+ * 一个使用 `oauth2_scheme` 的依赖。
+ * 一个类型为 `SecurityScopes` 的 `security_scopes` 参数：
+ * 该 `security_scopes` 参数有一个 `scopes` 属性，它是一个包含上面所有已声明作用域的 `list`，因此：
+ * 对于*路径操作* `read_own_items`，`security_scopes.scopes` 将包含 `["me", "items"]`。
+ * 对于*路径操作* `read_users_me`，`security_scopes.scopes` 将包含 `["me"]`，因为它在依赖 `get_current_active_user` 中被声明。
+ * 对于*路径操作* `read_system_status`，`security_scopes.scopes` 将包含 `[]`（空列表），因为它既没有声明任何带 `scopes` 的 `Security`，其依赖 `get_current_user` 也没有声明任何 `scopes`。
/// tip | 提示
-此处重要且**神奇**的事情是，`get_current_user` 检查每个*路径操作*时可以使用不同的 `scopes` 列表。
+这里重要且“神奇”的地方是，`get_current_user` 在检查每个*路径操作*时会得到不同的 `scopes` 列表。
-所有这些都依赖于在每个*路径操作*和指定*路径操作*的依赖树中的每个依赖项。
+这一切都取决于为该特定*路径操作*在其自身以及依赖树中的每个依赖里声明的 `scopes`。
///
-## `SecurityScopes` 的更多细节
+## 关于 `SecurityScopes` 的更多细节 { #more-details-about-securityscopes }
-您可以任何位置或多个位置使用 `SecurityScopes`，不一定非得在**根**依赖项中使用。
+你可以在任意位置、多个位置使用 `SecurityScopes`，不一定非得在“根”依赖里。
-它总是在当前 `Security` 依赖项中和所有依赖因子对于**特定** *路径操作*和**特定**依赖树中安全作用域
+它总会包含当前 `Security` 依赖中以及所有依赖者在“该特定”*路径操作*和“该特定”依赖树里声明的安全作用域。
-因为 `SecurityScopes` 包含所有由依赖项声明的作用域，可以在核心依赖函数中用它验证所需作用域的令牌，然后再在不同的*路径操作*中声明不同作用域需求。
+因为 `SecurityScopes` 会包含依赖者声明的所有作用域，你可以在一个核心依赖函数里用它验证令牌是否具有所需作用域，然后在不同的*路径操作*里声明不同的作用域需求。
-它们会为每个*路径操作*进行单独检查。
+它们会针对每个*路径操作*分别检查。
-## 查看文档
+## 查看文档 { #check-it }
-打开 API 文档，进行身份验证，并指定要授权的作用域。
+打开 API 文档，你可以进行身份验证，并指定要授权的作用域。
-然后查看子应用文档 
-所有这些消息都将使用同一个 WebSocket 连
+所有这些消息都将使用同一个 WebSocket 连接。
-接。
-
-## 使用 `Depends` 和其他依赖项
+## 使用 `Depends` 和其他依赖项 { #using-depends-and-others }
在 WebSocket 端点中，您可以从 `fastapi` 导入并使用以下内容：
@@ -101,7 +107,7 @@ $ uvicorn main:app --reload
* `Path`
* `Query`
-它们的工作方式与其他 FastAPI 端点/ *路径操作* 相同：
+它们的工作方式与其他 FastAPI 端点/*路径操作* 相同：
{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *}
@@ -113,16 +119,20 @@ $ uvicorn main:app --reload
///
-### 尝试带有依赖项的 WebSockets
+### 尝试带有依赖项的 WebSockets { #try-the-websockets-with-dependencies }
如果您的文件名为 `main.py`，请使用以下命令运行应用程序：
+
-## 处理断开连接和多个客户端
+## 处理断开连接和多个客户端 { #handling-disconnections-and-multiple-clients }
当 WebSocket 连接关闭时，`await websocket.receive_text()` 将引发 `WebSocketDisconnect` 异常，您可以捕获并处理该异常，就像本示例中的示例一样。
@@ -164,13 +174,13 @@ Client #1596980209979 left the chat
但请记住，由于所有内容都在内存中以单个列表的形式处理，因此它只能在进程运行时工作，并且只能使用单个进程。
-如果您需要与 FastAPI 集成更简单但更强大的功能，支持 Redis、PostgreSQL 或其他功能，请查看 [encode/broadcaster](https://github.com/encode/broadcaster)。
+如果您需要与 FastAPI 集成更简单但更强大的功能，支持 Redis、PostgreSQL 或其他功能，请查看 
-/// info
+/// info | 信息
漂亮的插画来自 
-### TLS 握手开始
+### TLS 握手开始 { #tls-handshake-start }
然后，浏览器将在**端口 443**（HTTPS 端口）上与该 IP 地址进行通信。
@@ -98,7 +97,7 @@ DNS 服务器会告诉浏览器使用某个特定的 **IP 地址**。 这将是
客户端和服务器之间建立 TLS 连接的过程称为 **TLS 握手**。
-### 带有 SNI 扩展的 TLS
+### 带有 SNI 扩展的 TLS { #tls-with-sni-extension }
**服务器中只有一个进程**可以侦听特定 **IP 地址**的特定 **端口**。 可能有其他进程在同一 IP 地址的其他端口上侦听，但每个 IP 地址和端口组合只有一个进程。
@@ -128,7 +127,7 @@ TLS 终止代理可以访问一个或多个 **TLS 证书**（HTTPS 证书）。
///
-### HTTPS 请求
+### HTTPS 请求 { #https-request }
现在客户端和服务器（特别是浏览器和 TLS 终止代理）具有 **加密的 TCP 连接**，它们可以开始 **HTTP 通信**。
@@ -136,19 +135,19 @@ TLS 终止代理可以访问一个或多个 **TLS 证书**（HTTPS 证书）。
-### 解密请求
+### 解密请求 { #decrypt-the-request }
TLS 终止代理将使用协商好的加密算法**解密请求**，并将**（解密的）HTTP 请求**传输到运行应用程序的进程（例如运行 FastAPI 应用的 Uvicorn 进程）。
-### HTTP 响应
+### HTTP 响应 { #http-response }
应用程序将处理请求并向 TLS 终止代理发送**（未加密）HTTP 响应**。
-### HTTPS 响应
+### HTTPS 响应 { #https-response }
然后，TLS 终止代理将使用之前协商的加密算法（以`someapp.example.com`的证书开头）对响应进行加密，并将其发送回浏览器。
@@ -158,7 +157,7 @@ TLS 终止代理将使用协商好的加密算法**解密请求**，并将**（
客户端（浏览器）将知道响应来自正确的服务器，因为它使用了他们之前使用 **HTTPS 证书** 协商出的加密算法。
-### 多个应用程序
+### 多个应用程序 { #multiple-applications }
在同一台（或多台）服务器中，可能存在**多个应用程序**，例如其他 API 程序或数据库。
@@ -168,7 +167,7 @@ TLS 终止代理将使用协商好的加密算法**解密请求**，并将**（
这样，TLS 终止代理就可以为多个应用程序处理**多个域名**的 HTTPS 和证书，然后在每种情况下将请求传输到正确的应用程序。
-### 证书更新
+### 证书更新 { #certificate-renewal }
在未来的某个时候，每个证书都会**过期**（大约在获得证书后 3 个月）。
@@ -183,16 +182,48 @@ TLS 终止代理将使用协商好的加密算法**解密请求**，并将**（
有多种方法可以做到这一点。 一些流行的方式是：
* **修改一些DNS记录**。
- * 为此，续订程序需要支持 DNS 提供商的 API，因此，要看你使用的 DNS 提供商是否提供这一功能。
+ * 为此，续订程序需要支持 DNS 提供商的 API，因此，要看你使用的 DNS 提供商是否提供这一功能。
* **在与域名关联的公共 IP 地址上作为服务器运行**（至少在证书获取过程中）。
- * 正如我们上面所说，只有一个进程可以监听特定的 IP 和端口。
- * 这就是当同一个 TLS 终止代理还负责证书续订过程时它非常有用的原因之一。
- * 否则，你可能需要暂时停止 TLS 终止代理，启动续订程序以获取证书，然后使用 TLS 终止代理配置它们，然后重新启动 TLS 终止代理。 这并不理想，因为你的应用程序在 TLS 终止代理关闭期间将不可用。
+ * 正如我们上面所说，只有一个进程可以监听特定的 IP 和端口。
+ * 这就是当同一个 TLS 终止代理还负责证书续订过程时它非常有用的原因之一。
+ * 否则，你可能需要暂时停止 TLS 终止代理，启动续订程序以获取证书，然后使用 TLS 终止代理配置它们，然后重新启动 TLS 终止代理。 这并不理想，因为你的应用程序在 TLS 终止代理关闭期间将不可用。
通过拥有一个**单独的系统来使用 TLS 终止代理来处理 HTTPS**, 而不是直接将 TLS 证书与应用程序服务器一起使用 （例如 Uvicorn）,你可以在
更新证书的过程中同时保持提供服务。
-## 回顾
+## 代理转发请求头 { #proxy-forwarded-headers }
+
+当使用代理来处理 HTTPS 时，你的**应用服务器**（例如通过 FastAPI CLI 运行的 Uvicorn）对 HTTPS 过程并不了解，它只通过纯 HTTP 与 **TLS 终止代理**通信。
+
+这个**代理**通常会在将请求转发给**应用服务器**之前，临时设置一些 HTTP 请求头，以便让应用服务器知道该请求是由代理**转发**过来的。
+
+/// note | 技术细节
+
+这些代理请求头包括：
+
+* 
-## 改变主题
+## 改变主题 { #change-the-theme }
同样地，你也可以通过设置键 `"syntaxHighlight.theme"` 来设置语法高亮主题（注意中间有一个点）：
-{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *}
+{* ../../docs_src/configure_swagger_ui/tutorial002_py39.py hl[3] *}
这个配置会改变语法高亮主题：
-## 改变默认 Swagger UI 参数
+## 改变默认 Swagger UI 参数 { #change-default-swagger-ui-parameters }
FastAPI 包含了一些默认配置参数，适用于大多数用例。
其包括这些默认配置参数：
-{* ../../fastapi/openapi/docs.py ln[7:23] *}
+{* ../../fastapi/openapi/docs.py ln[9:24] hl[18:24] *}
你可以通过在 `swagger_ui_parameters` 中设置不同的值来覆盖它们。
比如，如果要禁用 `deepLinking`，你可以像这样传递设置到 `swagger_ui_parameters` 中：
-{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
+{* ../../docs_src/configure_swagger_ui/tutorial003_py39.py hl[3] *}
-## 其他 Swagger UI 参数
+## 其他 Swagger UI 参数 { #other-swagger-ui-parameters }
-查看其他 Swagger UI 参数，请阅读 
+
-### 添加类型
+### 添加类型 { #add-types }
-让我们来修改上面例子的一行代码。
+我们来改前一个版本的一行代码。
-我们将把下面这段代码中的函数参数从：
+把函数参数从：
```Python
first_name, last_name
@@ -78,227 +76,389 @@ John Doe
就是这样。
-这些就是"类型提示"：
-
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+这些就是“类型提示”：
+{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *}
-这和声明默认值是不同的，例如：
+这和声明默认值不同，比如：
```Python
first_name="john", last_name="doe"
```
-这两者不一样。
+这是两码事。
我们用的是冒号（`:`），不是等号（`=`）。
-而且添加类型提示一般不会改变原来的运行结果。
+而且添加类型提示通常不会改变代码本来的行为。
-现在假设我们又一次正在创建这个函数，这次添加了类型提示。
+现在，再想象你又在编写这个函数了，不过这次加上了类型提示。
-在同样的地方，通过 `Ctrl+Space` 触发自动补全，你会发现：
+在同样的位置，你用 `Ctrl+Space` 触发自动补全，就能看到：
-
+
-这样，你可以滚动查看选项，直到你找到看起来眼熟的那个：
+这样，你可以滚动查看选项，直到找到那个“看着眼熟”的：
-
+
-## 更多动机
+## 更多动机 { #more-motivation }
-下面是一个已经有类型提示的函数：
+看这个已经带有类型提示的函数：
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *}
+因为编辑器知道变量的类型，你不仅能得到补全，还能获得错误检查：
-因为编辑器已经知道了这些变量的类型，所以不仅能对代码进行补全，还能检查其中的错误：
+
-
+现在你知道需要修复它，用 `str(age)` 把 `age` 转成字符串：
-现在你知道了必须先修复这个问题，通过 `str(age)` 把 `age` 转换成字符串：
+{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *}
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+## 声明类型 { #declaring-types }
+你刚刚看到的是声明类型提示的主要位置：函数参数。
-## 声明类型
+这也是你在 **FastAPI** 中使用它们的主要场景。
-你刚刚看到的就是声明类型提示的主要场景。用于函数的参数。
+### 简单类型 { #simple-types }
-这也是你将在 **FastAPI** 中使用它们的主要场景。
+你不仅可以声明 `str`，还可以声明所有标准的 Python 类型。
-### 简单类型
-
-不只是 `str`，你能够声明所有的标准 Python 类型。
-
-比如以下类型：
+例如：
* `int`
* `float`
* `bool`
* `bytes`
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *}
+
+### 带类型参数的泛型类型 { #generic-types-with-type-parameters }
+有些数据结构可以包含其他值，比如 `dict`、`list`、`set` 和 `tuple`。而内部的值也会有自己的类型。
-### 嵌套类型
+这些带有内部类型的类型称为“泛型”（generic）类型。可以把它们连同内部类型一起声明出来。
-有些容器数据结构可以包含其他的值，比如 `dict`、`list`、`set` 和 `tuple`。它们内部的值也会拥有自己的类型。
+要声明这些类型以及内部类型，你可以使用 Python 标准库模块 `typing`。它就是为支持这些类型提示而存在的。
-你可以使用 Python 的 `typing` 标准库来声明这些类型以及子类型。
+#### 更新的 Python 版本 { #newer-versions-of-python }
-它专门用来支持这些类型提示。
+使用 `typing` 的语法与所有版本兼容，从 Python 3.6 到最新版本（包括 Python 3.9、Python 3.10 等）。
-#### 列表
+随着 Python 的发展，更新的版本对这些类型注解的支持更好，在很多情况下你甚至不需要导入和使用 `typing` 模块来声明类型注解。
-例如，让我们来定义一个由 `str` 组成的 `list` 变量。
+如果你可以为项目选择更高版本的 Python，你将能享受到这种额外的简化。
-从 `typing` 模块导入 `List`（注意是大写的 `L`）：
+在整个文档中，会根据不同 Python 版本提供相应的示例（当存在差异时）。
-{* ../../docs_src/python_types/tutorial006.py hl[1] *}
+比如“Python 3.6+”表示兼容 Python 3.6 及以上（包括 3.7、3.8、3.9、3.10 等）。而“Python 3.9+”表示兼容 Python 3.9 及以上（包括 3.10 等）。
+如果你可以使用最新的 Python 版本，请使用最新版本的示例，它们将拥有最简洁的语法，例如“Python 3.10+”。
-同样以冒号（`:`）来声明这个变量。
+#### 列表 { #list }
-输入 `List` 作为类型。
+例如，我们来定义一个由 `str` 组成的 `list` 变量。
-由于列表是带有"子类型"的类型，所以我们把子类型放在方括号中：
+用同样的冒号（`:`）语法声明变量。
-{* ../../docs_src/python_types/tutorial006.py hl[4] *}
+类型写 `list`。
+因为 list 是一种包含内部类型的类型，把内部类型写在方括号里：
-这表示："变量 `items` 是一个 `list`，并且这个列表里的每一个元素都是 `str`"。
+{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *}
-这样，即使在处理列表中的元素时，你的编辑器也可以提供支持。
+/// info | 信息
-没有类型，几乎是不可能实现下面这样：
+方括号中的这些内部类型称为“类型参数”（type parameters）。
-
+在这个例子中，`str` 是传给 `list` 的类型参数。
-注意，变量 `item` 是列表 `items` 中的元素之一。
+///
-而且，编辑器仍然知道它是一个 `str`，并为此提供了支持。
+这表示：“变量 `items` 是一个 `list`，并且列表中的每一个元素都是 `str`”。
-#### 元组和集合
+这样，即使是在处理列表中的元素时，编辑器也能给你提供支持：
-声明 `tuple` 和 `set` 的方法也是一样的：
+
-{* ../../docs_src/python_types/tutorial007.py hl[1,4] *}
+没有类型的话，这几乎是不可能做到的。
+注意，变量 `item` 是列表 `items` 中的一个元素。
-这表示：
+即便如此，编辑器仍然知道它是 `str`，并为此提供支持。
+
+#### 元组和集合 { #tuple-and-set }
-* 变量 `items_t` 是一个 `tuple`，其中的前两个元素都是 `int` 类型, 最后一个元素是 `str` 类型。
-* 变量 `items_s` 是一个 `set`，其中的每个元素都是 `bytes` 类型。
+声明 `tuple` 和 `set` 的方式类似：
+
+{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *}
+
+这表示：
-#### 字典
+* 变量 `items_t` 是一个含有 3 个元素的 `tuple`，分别是一个 `int`、另一个 `int`，以及一个 `str`。
+* 变量 `items_s` 是一个 `set`，其中每个元素的类型是 `bytes`。
-定义 `dict` 时，需要传入两个子类型，用逗号进行分隔。
+#### 字典 { #dict }
-第一个子类型声明 `dict` 的所有键。
+定义 `dict` 时，需要传入 2 个类型参数，用逗号分隔。
-第二个子类型声明 `dict` 的所有值：
+第一个类型参数用于字典的键。
-{* ../../docs_src/python_types/tutorial008.py hl[1,4] *}
+第二个类型参数用于字典的值：
+{* ../../docs_src/python_types/tutorial008_py39.py hl[1] *}
这表示：
* 变量 `prices` 是一个 `dict`：
- * 这个 `dict` 的所有键为 `str` 类型（可以看作是字典内每个元素的名称）。
- * 这个 `dict` 的所有值为 `float` 类型（可以看作是字典内每个元素的价格）。
+ * 这个 `dict` 的键是 `str` 类型（比如，每个条目的名称）。
+ * 这个 `dict` 的值是 `float` 类型（比如，每个条目的价格）。
-### 类作为类型
+#### Union { #union }
-你也可以将类声明为变量的类型。
+你可以声明一个变量可以是若干种类型中的任意一种，比如既可以是 `int` 也可以是 `str`。
-假设你有一个名为 `Person` 的类，拥有 name 属性：
+在 Python 3.6 及以上（包括 Python 3.10），你可以使用 `typing` 中的 `Union`，把可能的类型放到方括号里。
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+在 Python 3.10 中还有一种新的语法，可以用竖线（`|`）把可能的类型分隔开。
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
-接下来，你可以将一个变量声明为 `Person` 类型：
+////
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+//// tab | Python 3.9+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b_py39.py!}
+```
-然后，你将再次获得所有的编辑器支持：
+////
-
+两种方式的含义一致：`item` 可以是 `int` 或 `str`。
-## Pydantic 模型
+#### 可能为 `None` { #possibly-none }
-
+
+注意，这表示“`one_person` 是类 `Person` 的一个实例（instance）”。
+
+它并不表示“`one_person` 是名为 `Person` 的类本身（class）”。
+
+## Pydantic 模型 { #pydantic-models }
+
+
+
带有注释的同一文件结构：
-```
+```bash
.
├── app # 「app」是一个 Python 包
│ ├── __init__.py # 这个文件使「app」成为一个 Python 包
@@ -71,7 +71,7 @@ from app.routers import items
│ └── admin.py # 「admin」子模块，例如 import app.internal.admin
```
-## `APIRouter`
+## `APIRouter` { #apirouter }
假设专门用于处理用户逻辑的文件是位于 `/app/routers/users.py` 的子模块。
@@ -81,23 +81,19 @@ from app.routers import items
你可以使用 `APIRouter` 为该模块创建*路径操作*。
-### 导入 `APIRouter`
+### 导入 `APIRouter` { #import-apirouter }
你可以导入它并通过与 `FastAPI` 类相同的方式创建一个「实例」：
-```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *}
-### 使用 `APIRouter` 的*路径操作*
+### 使用 `APIRouter` 的*路径操作* { #path-operations-with-apirouter }
然后你可以使用它来声明*路径操作*。
使用方式与 `FastAPI` 类相同：
-```Python hl_lines="6 11 16" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *}
你可以将 `APIRouter` 视为一个「迷你 `FastAPI`」类。
@@ -105,7 +101,7 @@ from app.routers import items
所有相同的 `parameters`、`responses`、`dependencies`、`tags` 等等。
-/// tip
+/// tip | 提示
在此示例中，该变量被命名为 `router`，但你可以根据你的想法自由命名。
@@ -113,7 +109,7 @@ from app.routers import items
我们将在主 `FastAPI` 应用中包含该 `APIRouter`，但首先，让我们来看看依赖项和另一个 `APIRouter`。
-## 依赖项
+## 依赖项 { #dependencies }
我们了解到我们将需要一些在应用程序的好几个地方所使用的依赖项。
@@ -121,11 +117,9 @@ from app.routers import items
现在我们将使用一个简单的依赖项来读取一个自定义的 `X-Token` 请求首部：
-```Python hl_lines="1 4-6" title="app/dependencies.py"
-{!../../docs_src/bigger_applications/app/dependencies.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *}
-/// tip
+/// tip | 提示
我们正在使用虚构的请求首部来简化此示例。
@@ -133,7 +127,7 @@ from app.routers import items
///
-## 其他使用 `APIRouter` 的模块
+## 其他使用 `APIRouter` 的模块 { #another-module-with-apirouter }
假设你在位于 `app/routers/items.py` 的模块中还有专门用于处理应用程序中「项目」的端点。
@@ -155,9 +149,7 @@ from app.routers import items
因此，我们可以将其添加到 `APIRouter` 中，而不是将其添加到每个路径操作中。
-```Python hl_lines="5-10 16 21" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *}
由于每个*路径操作*的路径都必须以 `/` 开头，例如：
@@ -175,7 +167,7 @@ async def read_item(item_id: str):
我们可以添加一个 `dependencies` 列表，这些依赖项将被添加到路由器中的所有*路径操作*中，并将针对向它们发起的每个请求执行/解决。
-/// tip
+/// tip | 提示
请注意，和[*路径操作装饰器*中的依赖项](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}很类似，没有值会被传递给你的*路径操作函数*。
@@ -196,19 +188,19 @@ async def read_item(item_id: str):
* 路由器的依赖项最先执行，然后是[装饰器中的 `dependencies`](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}，再然后是普通的参数依赖项。
* 你还可以添加[具有 `scopes` 的 `Security` 依赖项](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}。
-/// tip
+/// tip | 提示
在 `APIRouter`中具有 `dependencies` 可以用来，例如，对一整组的*路径操作*要求身份认证。即使这些依赖项并没有分别添加到每个路径操作中。
///
-/// check
+/// check | 检查
`prefix`、`tags`、`responses` 以及 `dependencies` 参数只是（和其他很多情况一样）**FastAPI** 的一个用于帮助你避免代码重复的功能。
///
-### 导入依赖项
+### 导入依赖项 { #import-the-dependencies }
这些代码位于 `app.routers.items` 模块，`app/routers/items.py` 文件中。
@@ -216,13 +208,11 @@ async def read_item(item_id: str):
因此，我们通过 `..` 对依赖项使用了相对导入：
-```Python hl_lines="3" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *}
-#### 相对导入如何工作
+#### 相对导入如何工作 { #how-relative-imports-work }
-/// tip
+/// tip | 提示
如果你完全了解导入的工作原理，请从下面的下一部分继续。
@@ -244,7 +234,7 @@ from .dependencies import get_token_header
请记住我们的程序/文件结构是怎样的：
-
+
-## 多次使用不同的 `prefix` 包含同一个路由器
+## 多次使用不同的 `prefix` 包含同一个路由器 { #include-the-same-router-multiple-times-with-different-prefix }
你也可以在*同一*路由器上使用不同的前缀来多次使用 `.include_router()`。
@@ -519,7 +493,7 @@ $ uvicorn app.main:app --reload
这是一个你可能并不真正需要的高级用法，但万一你有需要了就能够用上。
-## 在另一个 `APIRouter` 中包含一个 `APIRouter`
+## 在另一个 `APIRouter` 中包含一个 `APIRouter` { #include-an-apirouter-in-another }
与在 `FastAPI` 应用程序中包含 `APIRouter` 的方式相同，你也可以在另一个 `APIRouter` 中包含 `APIRouter`，通过：
@@ -527,4 +501,4 @@ $ uvicorn app.main:app --reload
router.include_router(other_router)
```
-请确保在你将 `router` 包含到 `FastAPI` 应用程序之前进行此操作，以便 `other_router` 中的`路径操作`也能被包含进来。
+请确保在你将 `router` 包含到 `FastAPI` 应用程序之前进行此操作，以便 `other_router` 中的*路径操作*也能被包含进来。
diff --git a/docs/zh/docs/tutorial/body-fields.md b/docs/zh/docs/tutorial/body-fields.md
index 4cff58bfc5..36be7c4191 100644
--- a/docs/zh/docs/tutorial/body-fields.md
+++ b/docs/zh/docs/tutorial/body-fields.md
@@ -1,8 +1,8 @@
-# 请求体 - 字段
+# 请求体 - 字段 { #body-fields }
与在*路径操作函数*中使用 `Query`、`Path` 、`Body` 声明校验与元数据的方式一样，可以使用 Pydantic 的 `Field` 在 Pydantic 模型内部声明校验和元数据。
-## 导入 `Field`
+## 导入 `Field` { #import-field }
首先，从 Pydantic 中导入 `Field`：
@@ -14,7 +14,7 @@
///
-## 声明模型属性
+## 声明模型属性 { #declare-model-attributes }
然后，使用 `Field` 定义模型的属性：
@@ -24,7 +24,7 @@
/// note | 技术细节
-实际上，`Query`、`Path` 都是 `Params` 的子类，而 `Params` 类又是 Pydantic 中 `FieldInfo` 的子类。
+实际上，`Query`、`Path` 以及你接下来会看到的其它对象，会创建公共 `Param` 类的子类的对象，而 `Param` 本身是 Pydantic 中 `FieldInfo` 的子类。
Pydantic 的 `Field` 返回也是 `FieldInfo` 的类实例。
@@ -40,13 +40,20 @@ Pydantic 的 `Field` 返回也是 `FieldInfo` 的类实例。
///
-## 添加更多信息
+## 添加更多信息 { #add-extra-information }
`Field`、`Query`、`Body` 等对象里可以声明更多信息，并且 JSON Schema 中也会集成这些信息。
*声明示例*一章中将详细介绍添加更多信息的知识。
-## 小结
+/// warning | 警告
+
+传递给 `Field` 的额外键也会出现在你的应用生成的 OpenAPI 架构中。
+由于这些键不一定属于 OpenAPI 规范的一部分，某些 OpenAPI 工具（例如 [OpenAPI 验证器](https://validator.swagger.io/)）可能无法处理你生成的架构。
+
+///
+
+## 小结 { #recap }
Pydantic 的 `Field` 可以为模型属性声明更多校验和元数据。
diff --git a/docs/zh/docs/tutorial/body-multiple-params.md b/docs/zh/docs/tutorial/body-multiple-params.md
index b4356fdcb4..7d0ddfc1ec 100644
--- a/docs/zh/docs/tutorial/body-multiple-params.md
+++ b/docs/zh/docs/tutorial/body-multiple-params.md
@@ -1,8 +1,8 @@
-# 请求体 - 多个参数
+# 请求体 - 多个参数 { #body-multiple-parameters }
既然我们已经知道了如何使用 `Path` 和 `Query`，下面让我们来了解一下请求体声明的更高级用法。
-## 混合使用 `Path`、`Query` 和请求体参数
+## 混合使用 `Path`、`Query` 和请求体参数 { #mix-path-query-and-body-parameters }
首先，毫无疑问地，你可以随意地混合使用 `Path`、`Query` 和请求体参数声明，**FastAPI** 会知道该如何处理。
@@ -10,13 +10,13 @@
{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
-/// note
+/// note | 注意
请注意，在这种情况下，将从请求体获取的 `item` 是可选的。因为它的默认值为 `None`。
///
-## 多个请求体参数
+## 多个请求体参数 { #multiple-body-parameters }
在上面的示例中，*路径操作*将期望一个具有 `Item` 的属性的 JSON 请求体，就像：
@@ -52,7 +52,7 @@
}
```
-/// note
+/// note | 注意
请注意，即使 `item` 的声明方式与之前相同，但现在它被期望通过 `item` 键内嵌在请求体中。
@@ -62,7 +62,7 @@
它将执行对复合数据的校验，并且像现在这样为 OpenAPI 模式和自动化文档对其进行记录。
-## 请求体中的单一值
+## 请求体中的单一值 { #singular-values-in-body }
与使用 `Query` 和 `Path` 为查询参数和路径参数定义额外数据的方式相同，**FastAPI** 提供了一个同等的 `Body`。
@@ -72,12 +72,10 @@
但是你可以使用 `Body` 指示 **FastAPI** 将其作为请求体的另一个键进行处理。
-
{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
在这种情况下，**FastAPI** 将期望像这样的请求体：
-
```JSON
{
"item": {
@@ -96,27 +94,33 @@
同样的，它将转换数据类型，校验，生成文档等。
-## 多个请求体参数和查询参数
+## 多个请求体参数和查询参数 { #multiple-body-params-and-query }
当然，除了请求体参数外，你还可以在任何需要的时候声明额外的查询参数。
-由于默认情况下单一值被解释为查询参数，因此你不必显式地添加 `Query`，你可以仅执行以下操作：
+由于默认情况下单一值会被解释为查询参数，因此你不必显式地添加 `Query`，你可以这样写：
+
+```Python
+q: str | None = None
+```
+
+或者在 Python 3.9 中：
```Python
-q: str = None
+q: Union[str, None] = None
```
比如：
-{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[27] *}
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
-/// info
+/// info | 信息
`Body` 同样具有与 `Query`、`Path` 以及其他后面将看到的类完全相同的额外校验和元数据参数。
///
-## 嵌入单个请求体参数
+## 嵌入单个请求体参数 { #embed-a-single-body-parameter }
假设你只有一个来自 Pydantic 模型 `Item` 的请求体参数 `item`。
@@ -156,7 +160,7 @@ item: Item = Body(embed=True)
}
```
-## 总结
+## 总结 { #recap }
你可以添加多个请求体参数到*路径操作函数*中，即使一个请求只能有一个请求体。
diff --git a/docs/zh/docs/tutorial/body-nested-models.md b/docs/zh/docs/tutorial/body-nested-models.md
index df96d96b4b..242aa5822c 100644
--- a/docs/zh/docs/tutorial/body-nested-models.md
+++ b/docs/zh/docs/tutorial/body-nested-models.md
@@ -1,53 +1,42 @@
-# 请求体 - 嵌套模型
+# 请求体 - 嵌套模型 { #body-nested-models }
使用 **FastAPI**，你可以定义、校验、记录文档并使用任意深度嵌套的模型（归功于Pydantic）。
-## List 字段
+## List 字段 { #list-fields }
-你可以将一个属性定义为拥有子元素的类型。例如 Python `list`：
+你可以将一个属性定义为一个子类型。例如，Python `list`：
{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
这将使 `tags` 成为一个由元素组成的列表。不过它没有声明每个元素的类型。
-## 具有子类型的 List 字段
+## 带类型参数的 List 字段 { #list-fields-with-type-parameter }
-但是 Python 有一种特定的方法来声明具有子类型的列表：
+不过，Python 有一种用于声明具有内部类型（类型参数）的列表的特定方式：
-### 从 typing 导入 `List`
+### 声明带类型参数的 `list` { #declare-a-list-with-a-type-parameter }
-首先，从 Python 的标准库 `typing` 模块中导入 `List`：
-
-{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
-
-### 声明具有子类型的 List
-
-要声明具有子类型的类型，例如 `list`、`dict`、`tuple`：
-
-* 从 `typing` 模块导入它们
-* 使用方括号 `[` 和 `]` 将子类型作为「类型参数」传入
+要声明具有类型参数（内部类型）的类型，例如 `list`、`dict`、`tuple`，使用方括号 `[` 和 `]` 传入内部类型作为「类型参数」：
```Python
-from typing import List
-
-my_list: List[str]
+my_list: list[str]
```
这完全是用于类型声明的标准 Python 语法。
-对具有子类型的模型属性也使用相同的标准语法。
+对具有内部类型的模型属性也使用相同的标准语法。
因此，在我们的示例中，我们可以将 `tags` 明确地指定为一个「字符串列表」：
{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
-## Set 类型
+## Set 类型 { #set-types }
但是随后我们考虑了一下，意识到标签不应该重复，它们很大可能会是唯一的字符串。
-Python 具有一种特殊的数据类型来保存一组唯一的元素，即 `set`。
+而 Python 有一种用于保存唯一元素集合的特殊数据类型 `set`。
-然后我们可以导入 `Set` 并将 `tag` 声明为一个由 `str` 组成的 `set`：
+然后我们可以将 `tags` 声明为一个由字符串组成的 set：
{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
@@ -57,7 +46,7 @@ Python 具有一种特殊的数据类型来保存一组唯一的元素，即 `se
并且还会被相应地标注 / 记录文档。
-## 嵌套模型
+## 嵌套模型 { #nested-models }
Pydantic 模型的每个属性都具有类型。
@@ -67,13 +56,13 @@ Pydantic 模型的每个属性都具有类型。
上述这些都可以任意的嵌套。
-### 定义子模型
+### 定义子模型 { #define-a-submodel }
例如，我们可以定义一个 `Image` 模型：
{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
-### 将子模型用作类型
+### 将子模型用作类型 { #use-the-submodel-as-a-type }
然后我们可以将其用作一个属性的类型：
@@ -102,11 +91,11 @@ Pydantic 模型的每个属性都具有类型。
* 数据校验
* 自动生成文档
-## 特殊的类型和校验
+## 特殊的类型和校验 { #special-types-and-validation }
除了普通的单一值类型（如 `str`、`int`、`float` 等）外，你还可以使用从 `str` 继承的更复杂的单一值类型。
-要了解所有的可用选项，请查看关于 
+
如果你直接使用 `dict` 而不是 Pydantic 模型，那你将无法获得这种编辑器支持。
但是你根本不必担心这两者，传入的字典会自动被转换，你的输出也会自动被转换为 JSON。
-## 任意 `dict` 构成的请求体
+## 任意 `dict` 构成的请求体 { #bodies-of-arbitrary-dicts }
你也可以将请求体声明为使用某类型的键和其他类型值的 `dict`。
@@ -206,7 +195,7 @@ images: List[Image]
{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
-/// tip
+/// tip | 提示
请记住 JSON 仅支持将 `str` 作为键。
@@ -218,7 +207,7 @@ images: List[Image]
///
-## 总结
+## 总结 { #recap }
使用 **FastAPI** 你可以拥有 Pydantic 模型提供的极高灵活性，同时保持代码的简单、简短和优雅。
diff --git a/docs/zh/docs/tutorial/body-updates.md b/docs/zh/docs/tutorial/body-updates.md
index 87f88f2553..000201de99 100644
--- a/docs/zh/docs/tutorial/body-updates.md
+++ b/docs/zh/docs/tutorial/body-updates.md
@@ -1,18 +1,18 @@
-# 请求体 - 更新数据
+# 请求体 - 更新数据 { #body-updates }
-## 用 `PUT` 更新数据
+## 用 `PUT` 替换式更新 { #update-replacing-with-put }
-更新数据请用 
-而且，还会用于 API 文档中使用了概图的*路径操作*：
+并且，还会用于需要它们的每个*路径操作*的 API 文档中：
-## 编辑器支持
+## 编辑器支持 { #editor-support }
-在编辑器中，函数内部均可使用类型提示、代码补全（如果接收的不是 Pydantic 模型，而是**字典**，就没有这样的支持）：
+在编辑器中，函数内部你会在各处得到类型提示与补全（如果接收的不是 Pydantic 模型，而是 `dict`，就不会有这样的支持）：
@@ -95,23 +95,23 @@ Pydantic 模型的 JSON 概图是 OpenAPI 生成的概图部件，可在 API 文
-这并非偶然，整个 **FastAPI** 框架都是围绕这种思路精心设计的。
+这并非偶然，整个框架都是围绕这种设计构建的。
-并且，在 FastAPI 的设计阶段，我们就已经进行了全面测试，以确保 FastAPI 可以获得所有编辑器的支持。
+并且在设计阶段、实现之前就进行了全面测试，以确保它能在所有编辑器中正常工作。
-我们还改进了 Pydantic，让它也支持这些功能。
+我们甚至对 Pydantic 本身做了一些改动以支持这些功能。
-虽然上面的截图取自 
/// tip | 提示
-使用 
-## 快捷方式
+## 快捷方式 { #shortcut }
-但是您可以看到，我们在这里有一些代码重复了，编写了`CommonQueryParams`两次：
+但是你可以看到，我们在这里有一些代码重复了，编写了`CommonQueryParams`两次：
+
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.9+ 未使用 Annotated
+
+/// tip | 提示
+
+尽可能使用 `Annotated` 版本。
+
+///
```Python
commons: CommonQueryParams = Depends(CommonQueryParams)
```
+////
+
**FastAPI** 为这些情况提供了一个快捷方式，在这些情况下，依赖项 *明确地* 是一个类，**FastAPI** 将 "调用" 它来创建类本身的一个实例。
-对于这些特定的情况，您可以跟随以下操作：
+对于这些特定的情况，你可以按如下操作：
不是写成这样：
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.9+ 未使用 Annotated
+
+/// tip | 提示
+
+尽可能使用 `Annotated` 版本。
+
+///
+
```Python
commons: CommonQueryParams = Depends(CommonQueryParams)
```
+////
+
...而是这样写:
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends()]
+```
+
+////
+
+//// tab | Python 3.9+ 未使用 Annotated
+
+/// tip | 提示
+
+尽可能使用 `Annotated` 版本。
+
+///
+
```Python
commons: CommonQueryParams = Depends()
```
-您声明依赖项作为参数的类型，并使用 `Depends()` 作为该函数的参数的 "默认" 值(在 `=` 之后)，而在 `Depends()` 中没有任何参数，而不是在 `Depends(CommonQueryParams)` 编写完整的类。
+////
+
+你声明依赖项作为参数的类型，并使用 `Depends()` 作为该函数的参数的 "默认" 值(在 `=` 之后)，而在 `Depends()` 中没有任何参数，而不是在 `Depends(CommonQueryParams)` 中*再次*编写完整的类。
同样的例子看起来像这样：
-{* ../../docs_src/dependencies/tutorial004_py310.py hl[17] *}
+{* ../../docs_src/dependencies/tutorial004_an_py310.py hl[19] *}
... **FastAPI** 会知道怎么处理。
-/// tip
+/// tip | 提示
如果这看起来更加混乱而不是更加有帮助，那么请忽略它，你不*需要*它。
-这只是一个快捷方式。因为 **FastAPI** 关心的是帮助您减少代码重复。
+这只是一个快捷方式。因为 **FastAPI** 关心的是帮助你减少代码重复。
///
diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index 51b3e9fc39..02fcf62a0a 100644
--- a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -1,4 +1,4 @@
-# 路径操作装饰器依赖项
+# 路径操作装饰器依赖项 { #dependencies-in-path-operation-decorators }
有时，我们并不需要在*路径操作函数*中使用依赖项的返回值。
@@ -8,15 +8,15 @@
对于这种情况，不必在声明*路径操作函数*的参数时使用 `Depends`，而是可以在*路径操作装饰器*中添加一个由 `dependencies` 组成的 `list`。
-## 在*路径操作装饰器*中添加 `dependencies` 参数
+## 在*路径操作装饰器*中添加 `dependencies` 参数 { #add-dependencies-to-the-path-operation-decorator }
-*路径操作装饰器*支持可选参数 ~ `dependencies`。
+*路径操作装饰器*支持可选参数 `dependencies`。
该参数的值是由 `Depends()` 组成的 `list`：
-{* ../../docs_src/dependencies/tutorial006.py hl[17] *}
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *}
-路径操作装饰器依赖项（以下简称为**“路径装饰器依赖项”**）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给*路径操作函数*。
+路径操作装饰器依赖项的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给*路径操作函数*。
/// tip | 提示
@@ -36,34 +36,34 @@
///
-## 依赖项错误和返回值
+## 依赖项错误和返回值 { #dependencies-errors-and-return-values }
路径装饰器依赖项也可以使用普通的依赖项*函数*。
-### 依赖项的需求项
+### 依赖项的需求项 { #dependency-requirements }
路径装饰器依赖项可以声明请求的需求项（比如响应头）或其他子依赖项：
-{* ../../docs_src/dependencies/tutorial006.py hl[6,11] *}
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
-### 触发异常
+### 触发异常 { #raise-exceptions }
路径装饰器依赖项与正常的依赖项一样，可以 `raise` 异常：
-{* ../../docs_src/dependencies/tutorial006.py hl[8,13] *}
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
-### 返回值
+### 返回值 { #return-values }
无论路径装饰器依赖项是否返回值，路径操作都不会使用这些值。
因此，可以复用在其他位置使用过的、（能返回值的）普通依赖项，即使没有使用这个值，也会执行该依赖项：
-{* ../../docs_src/dependencies/tutorial006.py hl[9,14] *}
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
-## 为一组路径操作定义依赖项
+## 为一组路径操作定义依赖项 { #dependencies-for-a-group-of-path-operations }
-稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=\_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。
+稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。
-## 全局依赖项
+## 全局依赖项 { #global-dependencies }
接下来，我们将学习如何为 `FastAPI` 应用程序添加全局依赖项，创建应用于每个*路径操作*的依赖项。
diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
index a863bb861e..bf495c9f39 100644
--- a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -1,136 +1,139 @@
-# 使用yield的依赖项
+# 使用 yield 的依赖项 { #dependencies-with-yield }
-FastAPI支持在完成后执行一些额外步骤的依赖项.
+FastAPI 支持那些在完成后执行一些额外步骤的依赖项。
-为此，你需要使用 `yield` 而不是 `return`，然后再编写这些额外的步骤（代码）。
+为此，使用 `yield` 而不是 `return`，并把这些额外步骤（代码）写在后面。
/// tip | 提示
-确保在每个依赖中只使用一次 `yield`。
+确保在每个依赖里只使用一次 `yield`。
///
/// note | 技术细节
-任何一个可以与以下内容一起使用的函数：
+任何可以与以下装饰器一起使用的函数：
-* 
-## 简单用法
+## 简单用法 { #simple-usage }
-观察一下就会发现，只要*路径* 和*操作*匹配，就可以使用声明的路径操作函数。然后，**FastAPI** 会用正确的参数调用函数，并提取请求中的数据。
+观察一下就会发现，只要*路径*和*操作*匹配，就会使用声明的*路径操作函数*。随后，**FastAPI** 会用正确的参数调用该函数，并从请求中提取数据。
-实际上，所有（或大多数）网络框架的工作方式都是这样的。
+事实上，所有（或大多数）Web 框架的工作方式都是这样的。
-开发人员永远都不需要直接调用这些函数，这些函数是由框架（在此为 **FastAPI** ）调用的。
+你从不会直接调用这些函数。它们由你的框架（此处为 **FastAPI**）调用。
-通过依赖注入系统，只要告诉 **FastAPI** *路径操作函数* 还要「依赖」其他在*路径操作函数*之前执行的内容，**FastAPI** 就会执行函数代码，并「注入」函数返回的结果。
+通过依赖注入系统，你还可以告诉 **FastAPI**，你的*路径操作函数*还“依赖”某些应在*路径操作函数*之前执行的内容，**FastAPI** 会负责执行它并“注入”结果。
-其他与「依赖注入」概念相同的术语为：
+“依赖注入”的其他常见术语包括：
-* 资源（Resource）
-* 提供方（Provider）
-* 服务（Service）
-* 可注入（Injectable）
-* 组件（Component）
+* 资源（resources）
+* 提供方（providers）
+* 服务（services）
+* 可注入（injectables）
+* 组件（components）
-## **FastAPI** 插件
+## **FastAPI** 插件 { #fastapi-plug-ins }
-**依赖注入**系统支持构建集成和「插件」。但实际上，FastAPI 根本**不需要创建「插件」**，因为使用依赖项可以声明不限数量的、可用于*路径操作函数*的集成与交互。
+可以使用**依赖注入**系统构建集成和“插件”。但实际上，根本**不需要创建“插件”**，因为通过依赖项可以声明无限多的集成与交互，使其可用于*路径操作函数*。
-创建依赖项非常简单、直观，并且还支持导入 Python 包。毫不夸张地说，只要几行代码就可以把需要的 Python 包与 API 函数集成在一起。
+依赖项可以用非常简单直观的方式创建，你只需导入所需的 Python 包，用*字面意义上的*几行代码就能把它们与你的 API 函数集成起来。
-下一章将详细介绍在关系型数据库、NoSQL 数据库、安全等方面使用依赖项的例子。
+在接下来的章节中，你会看到关于关系型数据库、NoSQL 数据库、安全等方面的示例。
-## **FastAPI** 兼容性
+## **FastAPI** 兼容性 { #fastapi-compatibility }
-依赖注入系统如此简洁的特性，让 **FastAPI** 可以与下列系统兼容：
+依赖注入系统的简洁让 **FastAPI** 能与以下内容兼容：
-* 关系型数据库
+* 各类关系型数据库
* NoSQL 数据库
-* 外部支持库
+* 外部包
* 外部 API
-* 认证和鉴权系统
+* 认证与授权系统
* API 使用监控系统
* 响应数据注入系统
-* 等等……
+* 等等...
-## 简单而强大
+## 簡单而强大 { #simple-and-powerful }
-虽然，**层级式依赖注入系统**的定义与使用十分简单，但它却非常强大。
+虽然**层级式依赖注入系统**的定义与使用非常简单，但它依然非常强大。
-比如，可以定义依赖其他依赖项的依赖项。
+你可以定义依赖其他依赖项的依赖项。
-最后，依赖项层级树构建后，**依赖注入系统**会处理所有依赖项及其子依赖项，并为每一步操作提供（注入）结果。
+最终会构建出一个依赖项的层级树，**依赖注入**系统会处理所有这些依赖（及其子依赖），并在每一步提供（注入）相应的结果。
-比如，下面有 4 个 API 路径操作（*端点*）：
+例如，假设你有 4 个 API 路径操作（*端点*）：
* `/items/public/`
* `/items/private/`
* `/users/{user_id}/activate`
* `/items/pro/`
-开发人员可以使用依赖项及其子依赖项为这些路径操作添加不同的权限：
+你可以仅通过依赖项及其子依赖项为它们添加不同的权限要求：
```mermaid
graph TB
@@ -205,8 +243,8 @@ admin_user --> activate_user
paying_user --> pro_items
```
-## 与 **OpenAPI** 集成
+## 与 **OpenAPI** 集成 { #integrated-with-openapi_1 }
-在声明需求时，所有这些依赖项还会把参数、验证等功能添加至路径操作。
+在声明需求的同时，所有这些依赖项也会为你的*路径操作*添加参数、验证等内容。
-**FastAPI** 负责把上述内容全部添加到 OpenAPI 概图，并显示在交互文档中。
+**FastAPI** 会负责把这些全部添加到 OpenAPI 模式中，以便它们显示在交互式文档系统里。
diff --git a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
index 2e77464335..0b73c392d8 100644
--- a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
@@ -1,4 +1,4 @@
-# 子依赖项
+# 子依赖项 { #sub-dependencies }
FastAPI 支持创建含**子依赖项**的依赖项。
@@ -6,34 +6,34 @@ FastAPI 支持创建含**子依赖项**的依赖项。
**FastAPI** 负责处理解析不同深度的子依赖项。
-### 第一层依赖项
+## 第一层依赖项 “dependable” { #first-dependency-dependable }
-下列代码创建了第一层依赖项：
+你可以创建一个第一层依赖项（“dependable”），如下：
-{* ../../docs_src/dependencies/tutorial005.py hl[8:9] *}
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *}
这段代码声明了类型为 `str` 的可选查询参数 `q`，然后返回这个查询参数。
这个函数很简单（不过也没什么用），但却有助于让我们专注于了解子依赖项的工作方式。
-### 第二层依赖项
+## 第二层依赖项，“dependable”和“dependant” { #second-dependency-dependable-and-dependant }
-接下来，创建另一个依赖项函数，并同时用该依赖项自身再声明一个依赖项（所以这也是一个「依赖项」）：
+接下来，创建另一个依赖项函数（一个“dependable”），并同时为它自身再声明一个依赖项（因此它同时也是一个“dependant”）：
-{* ../../docs_src/dependencies/tutorial005.py hl[13] *}
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *}
这里重点说明一下声明的参数：
-* 尽管该函数自身是依赖项，但还声明了另一个依赖项（它「依赖」于其他对象）
+* 尽管该函数自身是依赖项（“dependable”），但还声明了另一个依赖项（它“依赖”于其他对象）
* 该函数依赖 `query_extractor`, 并把 `query_extractor` 的返回值赋给参数 `q`
* 同时，该函数还声明了类型是 `str` 的可选 cookie（`last_query`）
* 用户未提供查询参数 `q` 时，则使用上次使用后保存在 cookie 中的查询
-### 使用依赖项
+## 使用依赖项 { #use-the-dependency }
接下来，就可以使用依赖项：
-{* ../../docs_src/dependencies/tutorial005.py hl[22] *}
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
/// info | 信息
@@ -54,20 +54,39 @@ read_query["/items/"]
query_extractor --> query_or_cookie_extractor --> read_query
```
-## 多次使用同一个依赖项
+## 多次使用同一个依赖项 { #using-the-same-dependency-multiple-times }
如果在同一个*路径操作* 多次声明了同一个依赖项，例如，多个依赖项共用一个子依赖项，**FastAPI** 在处理同一请求时，只调用一次该子依赖项。
FastAPI 不会为同一个请求多次调用同一个依赖项，而是把依赖项的返回值进行「缓存」，并把它传递给同一请求中所有需要使用该返回值的「依赖项」。
-在高级使用场景中，如果不想使用「缓存」值，而是为需要在同一请求的每一步操作（多次）中都实际调用依赖项，可以把 `Depends` 的参数 `use_cache` 的值设置为 `False` :
+在高级使用场景中，如果不想使用「缓存」值，而是为需要在同一请求的每一步操作（多次）中都实际调用依赖项，可以把 `Depends` 的参数 `use_cache` 的值设置为 `False`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_cache=False)]):
+ return {"fresh_value": fresh_value}
+```
+
+////
+
+//// tab | Python 3.9+ 非 Annotated
+
+/// tip | 提示
+
+尽可能优先使用 `Annotated` 版本。
+
+///
```Python hl_lines="1"
async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):
return {"fresh_value": fresh_value}
```
-## 小结
+////
+
+## 小结 { #recap }
千万别被本章里这些花里胡哨的词藻吓倒了，其实**依赖注入**系统非常简单。
diff --git a/docs/zh/docs/tutorial/encoder.md b/docs/zh/docs/tutorial/encoder.md
index e52aaa2ed2..f47a092010 100644
--- a/docs/zh/docs/tutorial/encoder.md
+++ b/docs/zh/docs/tutorial/encoder.md
@@ -1,4 +1,4 @@
-# JSON 兼容编码器
+# JSON 兼容编码器 { #json-compatible-encoder }
在某些情况下，您可能需要将数据类型（如Pydantic模型）转换为与JSON兼容的数据类型（如`dict`、`list`等）。
@@ -6,7 +6,7 @@
对于这种要求， **FastAPI**提供了`jsonable_encoder()`函数。
-## 使用`jsonable_encoder`
+## 使用`jsonable_encoder` { #using-the-jsonable-encoder }
让我们假设你有一个数据库名为`fake_db`，它只能接收与JSON兼容的数据。
@@ -28,7 +28,7 @@
这个操作不会返回一个包含JSON格式（作为字符串）数据的庞大的`str`。它将返回一个Python标准数据结构（例如`dict`），其值和子值都与JSON兼容。
-/// note
+/// note | 注意
`jsonable_encoder`实际上是FastAPI内部用来转换数据的。但是它在许多其他场景中也很有用。
diff --git a/docs/zh/docs/tutorial/extra-data-types.md b/docs/zh/docs/tutorial/extra-data-types.md
index b064ee551e..2cefd163d3 100644
--- a/docs/zh/docs/tutorial/extra-data-types.md
+++ b/docs/zh/docs/tutorial/extra-data-types.md
@@ -1,4 +1,4 @@
-# 额外数据类型
+# 额外数据类型 { #extra-data-types }
到目前为止，您一直在使用常见的数据类型，如:
@@ -15,9 +15,9 @@
* 传入请求的数据转换。
* 响应数据转换。
* 数据验证。
-* 自动补全和文档。
+* 自动注解和文档。
-## 其他数据类型
+## 其他数据类型 { #other-data-types }
下面是一些你可以使用的其他数据类型:
@@ -36,12 +36,12 @@
* `datetime.timedelta`:
* 一个 Python `datetime.timedelta`.
* 在请求和响应中将表示为 `float` 代表总秒数。
- * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", 
-## 禁止额外的 Headers
+## 禁止额外的 Headers { #forbid-extra-headers }
在某些特殊使用情况下（可能并不常见），您可能希望**限制**您想要接收的 headers。
@@ -51,6 +51,22 @@
}
```
-## 总结
+## 禁用下划线转换 { #disable-convert-underscores }
+
+与常规的 header 参数相同，当参数名中包含下划线时，会**自动转换为连字符**。
+
+例如，如果你的代码中有一个名为 `save_data` 的 header 参数，那么预期的 HTTP 头将是 `save-data`，并且在文档中也会以这种形式显示。
+
+如果由于某些原因你需要禁用这种自动转换，你也可以在用于 header 参数的 Pydantic 模型中进行设置。
+
+{* ../../docs_src/header_param_models/tutorial003_an_py310.py hl[19] *}
+
+/// warning | 警告
+
+在将 `convert_underscores` 设为 `False` 之前，请注意某些 HTTP 代理和服务器不允许使用带下划线的 headers。
+
+///
+
+## 总结 { #summary }
您可以使用 **Pydantic 模型**在 **FastAPI** 中声明 **headers**。😎
diff --git a/docs/zh/docs/tutorial/header-params.md b/docs/zh/docs/tutorial/header-params.md
index 19bb455cf4..ccb88ae7fa 100644
--- a/docs/zh/docs/tutorial/header-params.md
+++ b/docs/zh/docs/tutorial/header-params.md
@@ -1,14 +1,14 @@
-# Header 参数
+# Header 参数 { #header-parameters }
定义 `Header` 参数的方式与定义 `Query`、`Path`、`Cookie` 参数相同。
-## 导入 `Header`
+## 导入 `Header` { #import-header }
首先，导入 `Header`：
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *}
-## 声明 `Header` 参数
+## 声明 `Header` 参数 { #declare-header-parameters }
然后，使用和 `Path`、`Query`、`Cookie` 一样的结构定义 header 参数。
@@ -24,13 +24,13 @@
///
-/// info | 说明
+/// info | 信息
必须使用 `Header` 声明 header 参数，否则该参数会被解释为查询参数。
///
-## 自动转换
+## 自动转换 { #automatic-conversion }
`Header` 比 `Path`、`Query` 和 `Cookie` 提供了更多功能。
@@ -54,7 +54,7 @@
///
-## 重复的请求头
+## 重复的请求头 { #duplicate-headers }
有时，可能需要接收重复的请求头。即同一个请求头有多个值。
@@ -84,7 +84,7 @@ X-Token: bar
}
```
-## 小结
+## 小结 { #recap }
使用 `Header` 声明请求头的方式与 `Query`、`Path` 、`Cookie` 相同。
diff --git a/docs/zh/docs/tutorial/index.md b/docs/zh/docs/tutorial/index.md
index 3ca927337f..7934583023 100644
--- a/docs/zh/docs/tutorial/index.md
+++ b/docs/zh/docs/tutorial/index.md
@@ -1,12 +1,12 @@
-# 教程 - 用户指南
+# 教程 - 用户指南 { #tutorial-user-guide }
本教程将一步步向您展示如何使用 **FastAPI** 的绝大部分特性。
-各个章节的内容循序渐进，但是又围绕着单独的主题，所以您可以直接跳转到某个章节以解决您的特定需求。
+各个章节的内容循序渐进，但是又围绕着单独的主题，所以您可以直接跳转到某个章节以解决您的特定 API 需求。
本教程同样可以作为将来的参考手册，所以您可以随时回到本教程并查阅您需要的内容。
-## 运行代码
+## 运行代码 { #run-the-code }
所有代码片段都可以复制后直接使用（它们实际上是经过测试的 Python 文件）。
@@ -58,7 +58,7 @@ $ fastapi dev
-/// note
+/// note | 注意
-当您使用 `pip install "fastapi[standard]"` 进行安装时，它会附带一些默认的可选标准依赖项。
+当您使用 `pip install "fastapi[standard]"` 安装时，它会附带一些默认的可选标准依赖项，其中包括 `fastapi-cloud-cli`，它可以让您部署到 
-## 标签元数据
+## 许可证标识符 { #license-identifier }
+
+自 OpenAPI 3.1.0 和 FastAPI 0.99.0 起，你还可以在 `license_info` 中使用 `identifier` 而不是 `url`。
+
+例如：
+
+{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *}
+
+## 标签元数据 { #metadata-for-tags }
+
+你也可以通过参数 `openapi_tags` 为用于分组路径操作的不同标签添加额外的元数据。
+
+它接收一个列表，列表中每个标签对应一个字典。
+
+每个字典可以包含：
+
+- `name`（必填）：一个 `str`，与在你的*路径操作*和 `APIRouter` 的 `tags` 参数中使用的标签名相同。
+- `description`：一个 `str`，该标签的简短描述。可以使用 Markdown，并会显示在文档 UI 中。
+- `externalDocs`：一个 `dict`，描述外部文档，包含：
+ - `description`：一个 `str`，该外部文档的简短描述。
+ - `url`（必填）：一个 `str`，该外部文档的 URL。
-### 创建标签元数据
+### 创建标签元数据 { #create-metadata-for-tags }
让我们在带有标签的示例中为 `users` 和 `items` 试一下。
创建标签元数据并把它传递给 `openapi_tags` 参数：
-{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *}
注意你可以在描述内使用 Markdown，例如「login」会显示为粗体（**login**）以及「fancy」会显示为斜体（_fancy_）。
@@ -48,11 +68,11 @@
///
-### 使用你的标签
+### 使用你的标签 { #use-your-tags }
将 `tags` 参数和*路径操作*（以及 `APIRouter`）一起使用，将其分配给不同的标签：
-{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *}
/// info | 信息
@@ -60,19 +80,19 @@
///
-### 查看文档
+### 查看文档 { #check-the-docs }
如果你现在查看文档，它们会显示所有附加的元数据：
-### 标签顺序
+### 标签顺序 { #order-of-tags }
每个标签元数据字典的顺序也定义了在文档用户界面显示的顺序。
例如按照字母顺序，即使 `users` 排在 `items` 之后，它也会显示在前面，因为我们将它的元数据添加为列表内的第一个字典。
-## OpenAPI URL
+## OpenAPI URL { #openapi-url }
默认情况下，OpenAPI 模式服务于 `/openapi.json`。
@@ -80,21 +100,21 @@
例如，将其设置为服务于 `/api/v1/openapi.json`：
-{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *}
如果你想完全禁用 OpenAPI 模式，可以将其设置为 `openapi_url=None`，这样也会禁用使用它的文档用户界面。
-## 文档 URLs
+## 文档 URLs { #docs-urls }
你可以配置两个文档用户界面，包括：
-* **Swagger UI**：服务于 `/docs`。
- * 可以使用参数 `docs_url` 设置它的 URL。
- * 可以通过设置 `docs_url=None` 禁用它。
-* ReDoc：服务于 `/redoc`。
- * 可以使用参数 `redoc_url` 设置它的 URL。
- * 可以通过设置 `redoc_url=None` 禁用它。
+- **Swagger UI**：服务于 `/docs`。
+ - 可以使用参数 `docs_url` 设置它的 URL。
+ - 可以通过设置 `docs_url=None` 禁用它。
+- **ReDoc**：服务于 `/redoc`。
+ - 可以使用参数 `redoc_url` 设置它的 URL。
+ - 可以通过设置 `redoc_url=None` 禁用它。
例如，设置 Swagger UI 服务于 `/documentation` 并禁用 ReDoc：
-{* ../../docs_src/metadata/tutorial003.py hl[3] *}
+{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *}
diff --git a/docs/zh/docs/tutorial/middleware.md b/docs/zh/docs/tutorial/middleware.md
index 5608c4ee15..a3f833d78c 100644
--- a/docs/zh/docs/tutorial/middleware.md
+++ b/docs/zh/docs/tutorial/middleware.md
@@ -1,66 +1,95 @@
-# 中间件
+# 中间件 { #middleware }
-你可以向 **FastAPI** 应用添加中间件.
+你可以向 **FastAPI** 应用添加中间件。
-"中间件"是一个函数,它在每个**请求**被特定的*路径操作*处理之前,以及在每个**响应**返回之前工作.
+“中间件”是一个函数，它会在每个特定的*路径操作*处理每个**请求**之前运行，也会在返回每个**响应**之前运行。
-* 它接收你的应用程序的每一个**请求**.
-* 然后它可以对这个**请求**做一些事情或者执行任何需要的代码.
-* 然后它将**请求**传递给应用程序的其他部分 (通过某种*路径操作*).
-* 然后它获取应用程序生产的**响应** (通过某种*路径操作*).
-* 它可以对该**响应**做些什么或者执行任何需要的代码.
-* 然后它返回这个 **响应**.
+* 它接收你的应用的每一个**请求**。
+* 然后它可以对这个**请求**做一些事情或者执行任何需要的代码。
+* 然后它将这个**请求**传递给应用程序的其他部分（某个*路径操作*）处理。
+* 之后它获取应用程序生成的**响应**（由某个*路径操作*产生）。
+* 它可以对该**响应**做一些事情或者执行任何需要的代码。
+* 然后它返回这个**响应**。
/// note | 技术细节
-如果你使用了 `yield` 关键字依赖, 依赖中的退出代码将在执行中间件*后*执行.
+如果你有使用 `yield` 的依赖，依赖中的退出代码会在中间件之后运行。
-如果有任何后台任务(稍后记录), 它们将在执行中间件*后*运行.
+如果有任何后台任务（会在[后台任务](background-tasks.md){.internal-link target=_blank}一节中介绍，你稍后会看到），它们会在所有中间件之后运行。
///
-## 创建中间件
+## 创建中间件 { #create-a-middleware }
-要创建中间件你可以在函数的顶部使用装饰器 `@app.middleware("http")`.
+要创建中间件，你可以在函数的顶部使用装饰器 `@app.middleware("http")`。
-中间件参数接收如下参数:
+中间件函数会接收：
-* `request`.
-* 一个函数 `call_next` 它将接收 `request` 作为参数.
- * 这个函数将 `request` 传递给相应的 *路径操作*.
- * 然后它将返回由相应的*路径操作*生成的 `response`.
-* 然后你可以在返回 `response` 前进一步修改它.
+* `request`。
+* 一个函数 `call_next`，它会把 `request` 作为参数接收。
+ * 这个函数会把 `request` 传递给相应的*路径操作*。
+ * 然后它返回由相应*路径操作*生成的 `response`。
+* 在返回之前，你可以进一步修改 `response`。
-{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *}
/// tip
-请记住可以 
-## `summary` 和 `description` 参数
+### 使用 Enum 的标签 { #tags-with-enums }
-路径装饰器还支持 `summary` 和 `description` 这两个参数：
+如果你的应用很大，可能会积累出很多标签，你会希望确保相关的*路径操作*始终使用相同的标签。
-{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *}
+这种情况下，把标签存放在 `Enum` 中会更合适。
-## 文档字符串（`docstring`）
+**FastAPI** 对此的支持与使用普通字符串相同：
-描述内容比较长且占用多行时，可以在函数的 docstring 中声明*路径操作*的描述，**FastAPI** 支持从文档字符串中读取描述内容。
+{* ../../docs_src/path_operation_configuration/tutorial002b_py39.py hl[1,8:10,13,18] *}
+
+## 摘要和描述 { #summary-and-description }
+
+可以添加 `summary` 和 `description`：
+
+{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[17:18] *}
+
+## 从 docstring 获取描述 { #description-from-docstring }
+
+描述内容比较长且占用多行时，可以在函数的 docstring 中声明*路径操作*的描述，**FastAPI** 会从中读取。
文档字符串支持 
-## 响应描述
+## 响应描述 { #response-description }
`response_description` 参数用于定义响应的描述说明：
-{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *}
+{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *}
/// info | 说明
@@ -78,11 +88,11 @@ OpenAPI 规定每个*路径操作*都要有响应描述。
-## 弃用*路径操作*
+## 弃用*路径操作* { #deprecate-a-path-operation }
`deprecated` 参数可以把*路径操作*标记为弃用，无需直接删除：
-{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
+{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *}
API 文档会把该路径操作标记为弃用：
@@ -92,6 +102,6 @@ API 文档会把该路径操作标记为弃用：
-## 小结
+## 小结 { #recap }
-通过传递参数给*路径操作装饰器* ，即可轻松地配置*路径操作*、添加元数据。
+通过传递参数给*路径操作装饰器*，即可轻松地配置*路径操作*、添加元数据。
diff --git a/docs/zh/docs/tutorial/path-params-numeric-validations.md b/docs/zh/docs/tutorial/path-params-numeric-validations.md
index ff62428359..ff8b1762cf 100644
--- a/docs/zh/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/zh/docs/tutorial/path-params-numeric-validations.md
@@ -1,91 +1,128 @@
-# 路径参数和数值校验
+# 路径参数和数值校验 { #path-parameters-and-numeric-validations }
与使用 `Query` 为查询参数声明更多的校验和元数据的方式相同，你也可以使用 `Path` 为路径参数声明相同类型的校验和元数据。
-## 导入 Path
+## 导入 `Path` { #import-path }
-首先，从 `fastapi` 导入 `Path`：
+首先，从 `fastapi` 导入 `Path`，并导入 `Annotated`：
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
-## 声明元数据
+/// info | 信息
+
+FastAPI 在 0.95.0 版本添加了对 `Annotated` 的支持（并开始推荐使用它）。
+
+如果你使用的是更旧的版本，尝试使用 `Annotated` 会报错。
+
+请确保在使用 `Annotated` 之前，将 FastAPI 版本[升级](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}到至少 0.95.1。
+
+///
+
+## 声明元数据 { #declare-metadata }
你可以声明与 `Query` 相同的所有参数。
-例如，要声明路径参数 `item_id`的 `title` 元数据值，你可以输入：
+例如，要为路径参数 `item_id` 声明 `title` 元数据值，你可以这样写：
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
-/// note
+/// note | 注意
-路径参数总是必需的，因为它必须是路径的一部分。
+路径参数总是必需的，因为它必须是路径的一部分。即使你将其声明为 `None` 或设置了默认值，也不会产生任何影响，它依然始终是必需参数。
-所以，你应该在声明时使用 `...` 将其标记为必需参数。
+///
-然而，即使你使用 `None` 声明路径参数或设置一个其他默认值也不会有任何影响，它依然会是必需参数。
+## 按需对参数排序 { #order-the-parameters-as-you-need }
-///
+/// tip | 提示
-## 按需对参数排序
+如果你使用 `Annotated`，这点可能不那么重要或必要。
-假设你想要声明一个必需的 `str` 类型查询参数 `q`。
+///
-而且你不需要为该参数声明任何其他内容，所以实际上你并不需要使用 `Query`。
+假设你想要将查询参数 `q` 声明为必需的 `str`。
-但是你仍然需要使用 `Path` 来声明路径参数 `item_id`。
+并且你不需要为该参数声明其他内容，所以实际上不需要用到 `Query`。
-如果你将带有「默认值」的参数放在没有「默认值」的参数之前，Python 将会报错。
+但是你仍然需要为路径参数 `item_id` 使用 `Path`。并且出于某些原因你不想使用 `Annotated`。
-但是你可以对其重新排序，并将不带默认值的值（查询参数 `q`）放到最前面。
+如果你将带有“默认值”的参数放在没有“默认值”的参数之前，Python 会报错。
-对 **FastAPI** 来说这无关紧要。它将通过参数的名称、类型和默认值声明（`Query`、`Path` 等）来检测参数，而不在乎参数的顺序。
+不过你可以重新排序，让没有默认值的参数（查询参数 `q`）放在最前面。
+
+对 **FastAPI** 来说这无关紧要。它会通过参数的名称、类型和默认值声明（`Query`、`Path` 等）来检测参数，而不关心顺序。
因此，你可以将函数声明为：
-{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.py hl[7] *}
+
+但请记住，如果你使用 `Annotated`，你就不会遇到这个问题，因为你没有使用 `Query()` 或 `Path()` 作为函数参数的默认值。
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
+
+## 按需对参数排序的技巧 { #order-the-parameters-as-you-need-tricks }
+
+/// tip | 提示
+
+如果你使用 `Annotated`，这点可能不那么重要或必要。
+
+///
+
+这里有一个小技巧，可能会很方便，但你并不会经常需要它。
+
+如果你想要：
+
+* 在没有 `Query` 且没有任何默认值的情况下声明查询参数 `q`
+* 使用 `Path` 声明路径参数 `item_id`
+* 让它们的顺序与上面不同
+* 不使用 `Annotated`
+
+...Python 为此有一个小的特殊语法。
+
+在函数的第一个参数位置传入 `*`。
-## 按需对参数排序的技巧
+Python 不会对这个 `*` 做任何事，但它会知道之后的所有参数都应该作为关键字参数（键值对）来调用，也被称为 
/// check | 检查
-还是使用 Python 类型声明，**FastAPI** 提供了（集成 Swagger UI 的）API 文档。
+还是使用 Python 类型声明，**FastAPI** 提供了（集成 Swagger UI 的）自动交互式文档。
注意，路径参数的类型是整数。
///
-## 基于标准的好处，备选文档
+## 基于标准的好处，备选文档 { #standards-based-benefits-alternative-documentation }
-**FastAPI** 使用 
-### 使用 Python _枚举类型_
+### 使用 Python 枚举 { #working-with-python-enumerations }
-*路径参数*的值是枚举的元素。
+路径参数的值是一个枚举成员。
-#### 比较*枚举元素*
+#### 比较枚举成员 { #compare-enumeration-members }
-枚举类 `ModelName` 中的*枚举元素*支持比较操作：
+可以将其与枚举类 `ModelName` 中的枚举成员进行比较：
-{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *}
-#### 获取*枚举值*
+#### 获取枚举值 { #get-the-enumeration-value }
-使用 `model_name.value` 或 `your_enum_member.value` 获取实际的值（本例中为**字符串**）：
+使用 `model_name.value` 或通用的 `your_enum_member.value` 获取实际的值（本例中为 `str`）：
-{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *}
/// tip | 提示
@@ -181,13 +182,13 @@ Python 3.4 及之后版本支持
-## 禁止额外的查询参数
+## 禁止额外的查询参数 { #forbid-extra-query-parameters }
在一些特殊的使用场景中（可能不是很常见），你可能希望**限制**你要接收的查询参数。
-你可以使用 Pydantic 的模型配置来 `forbid`（意为禁止 —— 译者注）任何 `extra`（意为额外的 —— 译者注）字段：
+你可以使用 Pydantic 的模型配置来 `forbid` 任何 `extra` 字段：
{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}
@@ -57,11 +57,11 @@ https://example.com/items/?limit=10&tool=plumbus
}
```
-## 总结
+## 总结 { #summary }
你可以使用 **Pydantic 模型**在 **FastAPI** 中声明**查询参数**。😎
-/// tip
+/// tip | 提示
剧透警告：你也可以使用 Pydantic 模型来声明 cookie 和 headers，但你将在本教程的后面部分阅读到这部分内容。🤫
diff --git a/docs/zh/docs/tutorial/query-params-str-validations.md b/docs/zh/docs/tutorial/query-params-str-validations.md
index c2f9a7e9f0..62552e6d08 100644
--- a/docs/zh/docs/tutorial/query-params-str-validations.md
+++ b/docs/zh/docs/tutorial/query-params-str-validations.md
@@ -1,142 +1,271 @@
-# 查询参数和字符串校验
+# 查询参数和字符串校验 { #query-parameters-and-string-validations }
**FastAPI** 允许你为参数声明额外的信息和校验。
-让我们以下面的应用程序为例：
+让我们以下面的应用为例：
{* ../../docs_src/query_params_str_validations/tutorial001_py310.py hl[7] *}
-查询参数 `q` 的类型为 `str`，默认值为 `None`，因此它是可选的。
+查询参数 `q` 的类型为 `str | None`，这意味着它是 `str` 类型，但也可以是 `None`。其默认值确实为 `None`，所以 FastAPI 会知道它不是必填的。
-## 额外的校验
+/// note | 注意
-我们打算添加约束条件：即使 `q` 是可选的，但只要提供了该参数，则该参数值**不能超过50个字符的长度**。
+FastAPI 会因为默认值 `= None` 而知道 `q` 的值不是必填的。
-### 导入 `Query`
+将类型标注为 `str | None` 能让你的编辑器提供更好的辅助和错误检测。
-为此，首先从 `fastapi` 导入 `Query`：
+///
-{* ../../docs_src/query_params_str_validations/tutorial002.py hl[1] *}
+## 额外校验 { #additional-validation }
-## 使用 `Query` 作为默认值
+我们打算添加约束：即使 `q` 是可选的，但只要提供了该参数，**其长度不能超过 50 个字符**。
-现在，将 `Query` 用作查询参数的默认值，并将它的 `max_length` 参数设置为 50：
+### 导入 `Query` 和 `Annotated` { #import-query-and-annotated }
-{* ../../docs_src/query_params_str_validations/tutorial002.py hl[9] *}
+为此，先导入：
-由于我们必须用 `Query(default=None)` 替换默认值 `None`，`Query` 的第一个参数同样也是用于定义默认值。
+- 从 `fastapi` 导入 `Query`
+- 从 `typing` 导入 `Annotated`
-所以：
+{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *}
+
+/// info | 信息
+
+FastAPI 在 0.95.0 版本中添加了对 `Annotated` 的支持（并开始推荐使用）。
+
+如果你的版本更旧，使用 `Annotated` 会报错。
+
+在使用 `Annotated` 之前，请确保先[升级 FastAPI 版本](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}到至少 0.95.1。
+
+///
+
+## 在 `q` 参数的类型中使用 `Annotated` { #use-annotated-in-the-type-for-the-q-parameter }
+
+还记得我之前在[Python 类型简介](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}中说过可以用 `Annotated` 给参数添加元数据吗？
+
+现在正是与 FastAPI 搭配使用它的时候。🚀
+
+我们之前的类型标注是：
+
+//// tab | Python 3.10+
+
+```Python
+q: str | None = None
+```
+
+////
+
+//// tab | Python 3.9+
```Python
-q: Union[str, None] = Query(default=None)
+q: Union[str, None] = None
```
-...使得参数可选，等同于：
+////
+
+我们要做的是用 `Annotated` 把它包起来，变成：
+
+//// tab | Python 3.10+
```Python
-q: str = None
+q: Annotated[str | None] = None
```
-但是 `Query` 显式地将其声明为查询参数。
+////
-然后，我们可以将更多的参数传递给 `Query`。在本例中，适用于字符串的 `max_length` 参数：
+//// tab | Python 3.9+
```Python
-q: Union[str, None] = Query(default=None, max_length=50)
+q: Annotated[Union[str, None]] = None
```
-将会校验数据，在数据无效时展示清晰的错误信息，并在 OpenAPI 模式的*路径操作*中记录该参数。
+////
-## 添加更多校验
+这两种写法含义相同，`q` 是一个可以是 `str` 或 `None` 的参数，默认是 `None`。
-你还可以添加 `min_length` 参数：
+现在进入更有趣的部分。🎉
-{* ../../docs_src/query_params_str_validations/tutorial003.py hl[10] *}
+## 在 `q` 的 `Annotated` 中添加 `Query` { #add-query-to-annotated-in-the-q-parameter }
-## 添加正则表达式
+有了 `Annotated` 之后，我们就可以放入更多信息（本例中是额外的校验）。在 `Annotated` 中添加 `Query`，并把参数 `max_length` 设为 `50`：
-你可以定义一个参数值必须匹配的正则表达式：
+{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[9] *}
-{* ../../docs_src/query_params_str_validations/tutorial004.py hl[11] *}
+注意默认值依然是 `None`，所以该参数仍是可选的。
-这个指定的正则表达式通过以下规则检查接收到的参数值：
+但现在把 `Query(max_length=50)` 放到 `Annotated` 里，我们就在告诉 FastAPI，这个值需要**额外校验**，最大长度为 50 个字符。😎
-* `^`：以该符号之后的字符开头，符号之前没有字符。
-* `fixedquery`: 值精确地等于 `fixedquery`。
-* `$`: 到此结束，在 `fixedquery` 之后没有更多字符。
+/// tip | 提示
-如果你对所有的这些**「正则表达式」**概念感到迷茫，请不要担心。对于许多人来说这都是一个困难的主题。你仍然可以在无需正则表达式的情况下做很多事情。
+这里用的是 `Query()`，因为这是一个**查询参数**。稍后我们还会看到 `Path()`、`Body()`、`Header()` 和 `Cookie()`，它们也接受与 `Query()` 相同的参数。
-但是，一旦你需要用到并去学习它们时，请了解你已经可以在 **FastAPI** 中直接使用它们。
+///
-## 默认值
+FastAPI 现在会：
-你可以向 `Query` 的第一个参数传入 `None` 用作查询参数的默认值，以同样的方式你也可以传递其他默认值。
+- 对数据进行**校验**，确保最大长度为 50 个字符
+- 当数据无效时向客户端展示**清晰的错误**
+- 在 OpenAPI 模式的*路径操作*中**记录**该参数（因此会出现在**自动文档 UI** 中）
-假设你想要声明查询参数 `q`，使其 `min_length` 为 `3`，并且默认值为 `fixedquery`：
+## 另一种（旧的）方式：把 `Query` 作为默认值 { #alternative-old-query-as-the-default-value }
-{* ../../docs_src/query_params_str_validations/tutorial005.py hl[7] *}
+早期版本的 FastAPI（0.95.0 之前）要求你把 `Query` 作为参数的默认值，而不是放在 `Annotated` 里。你很可能会在别处看到这种写法，所以我也给你解释一下。
-/// note
+/// tip | 提示
-具有默认值还会使该参数成为可选参数。
+对于新代码以及在可能的情况下，请按上文所述使用 `Annotated`。它有多项优势（如下所述），没有劣势。🍰
///
-## 声明为必需参数
+像这样把 `Query()` 作为函数参数的默认值，并把参数 `max_length` 设为 50：
-当我们不需要声明额外的校验或元数据时，只需不声明默认值就可以使 `q` 参数成为必需参数，例如：
+{* ../../docs_src/query_params_str_validations/tutorial002_py310.py hl[7] *}
+
+由于这种情况下（不使用 `Annotated`）我们必须把函数中的默认值 `None` 替换为 `Query()`，因此需要通过参数 `Query(default=None)` 来设置默认值，它起到同样的作用（至少对 FastAPI 来说）。
+
+所以：
```Python
-q: str
+q: str | None = Query(default=None)
```
-代替：
+……会让参数变成可选，默认值为 `None`，等同于：
```Python
-q: Union[str, None] = None
+q: str | None = None
+```
+
+但使用 `Query` 的版本会显式把它声明为一个查询参数。
+
+然后，我们可以向 `Query` 传入更多参数。本例中是适用于字符串的 `max_length` 参数：
+
+```Python
+q: str | None = Query(default=None, max_length=50)
+```
+
+这会校验数据、在数据无效时展示清晰的错误，并在 OpenAPI 模式的*路径操作*中记录该参数。
+
+### 在默认值中使用 `Query` 或在 `Annotated` 中使用 `Query` { #query-as-the-default-value-or-in-annotated }
+
+注意，当你在 `Annotated` 中使用 `Query` 时，不能再给 `Query` 传 `default` 参数。
+
+相反，应使用函数参数本身的实际默认值。否则会不一致。
+
+例如，下面这样是不允许的：
+
+```Python
+q: Annotated[str, Query(default="rick")] = "morty"
+```
+
+……因为不清楚默认值应该是 `"rick"` 还是 `"morty"`。
+
+因此，你应该这样用（推荐）：
+
+```Python
+q: Annotated[str, Query()] = "rick"
```
-但是现在我们正在用 `Query` 声明它，例如：
+……或者在旧代码库中你会见到：
```Python
-q: Union[str, None] = Query(default=None, min_length=3)
+q: str = Query(default="rick")
```
-因此，当你在使用 `Query` 且需要声明一个值是必需的时，只需不声明默认参数：
+### `Annotated` 的优势 { #advantages-of-annotated }
+
+**推荐使用 `Annotated`**，而不是把 `Query` 放在函数参数的默认值里，这样做在多方面都**更好**。🤓
+
+函数参数的**默认值**就是**真正的默认值**，这与 Python 的直觉更一致。😌
+
+你可以在**其他地方**不通过 FastAPI **直接调用**这个函数，而且它会**按预期工作**。如果有**必填**参数（没有默认值），你的**编辑器**会报错提示；如果在运行时没有传入必填参数，**Python** 也会报错。
+
+当你不使用 `Annotated` 而是使用**（旧的）默认值风格**时，如果你在**其他地方**不通过 FastAPI 调用该函数，你必须**记得**给函数传参，否则得到的值会和预期不同（例如得到 `QueryInfo` 之类的对象而不是 `str`）。而你的编辑器不会报错，Python 也不会在调用时报错，只有在函数内部的操作出错时才会暴露问题。
+
+由于 `Annotated` 可以包含多个元数据标注，你甚至可以用同一个函数与其他工具配合，例如 
+
-### 具有默认值的查询参数列表 / 多个值
+### 具有默认值的查询参数列表 / 多个值 { #query-parameter-list-multiple-values-with-defaults }
-你还可以定义在没有任何给定值时的默认 `list` 值：
+你还可以定义在没有给定值时的默认 `list`：
-{* ../../docs_src/query_params_str_validations/tutorial012.py hl[9] *}
+{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
如果你访问：
@@ -182,93 +311,163 @@ http://localhost:8000/items/
}
```
-#### 使用 `list`
+#### 只使用 `list` { #using-just-list }
-你也可以直接使用 `list` 代替 `List [str]`：
+你也可以直接使用 `list`，而不是 `list[str]`：
-{* ../../docs_src/query_params_str_validations/tutorial013.py hl[7] *}
+{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
-/// note
+/// note | 注意
-请记住，在这种情况下 FastAPI 将不会检查列表的内容。
+请记住，在这种情况下 FastAPI 不会检查列表的内容。
-例如，`List[int]` 将检查（并记录到文档）列表的内容必须是整数。但是单独的 `list` 不会。
+例如，`list[int]` 会检查（并记录到文档）列表的内容必须是整数。但仅用 `list` 不会。
///
-## 声明更多元数据
+## 声明更多元数据 { #declare-more-metadata }
你可以添加更多有关该参数的信息。
-这些信息将包含在生成的 OpenAPI 模式中，并由文档用户界面和外部工具所使用。
+这些信息会包含在生成的 OpenAPI 中，并被文档用户界面和外部工具使用。
-/// note
+/// note | 注意
请记住，不同的工具对 OpenAPI 的支持程度可能不同。
-其中一些可能不会展示所有已声明的额外信息，尽管在大多数情况下，缺少的这部分功能已经计划进行开发。
+其中一些可能还不会展示所有已声明的额外信息，尽管在大多数情况下，缺失的功能已经在计划开发中。
///
你可以添加 `title`：
-{* ../../docs_src/query_params_str_validations/tutorial007.py hl[10] *}
+{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
以及 `description`：
-{* ../../docs_src/query_params_str_validations/tutorial008.py hl[13] *}
+{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
-## 别名参数
+## 别名参数 { #alias-parameters }
-假设你想要查询参数为 `item-query`。
+假设你想要参数名为 `item-query`。
-像下面这样：
+像这样：
```
http://127.0.0.1:8000/items/?item-query=foobaritems
```
-但是 `item-query` 不是一个有效的 Python 变量名称。
+但 `item-query` 不是有效的 Python 变量名。
最接近的有效名称是 `item_query`。
-但是你仍然要求它在 URL 中必须是 `item-query`...
+但你仍然需要它在 URL 中就是 `item-query`……
-这时你可以用 `alias` 参数声明一个别名，该别名将用于在 URL 中查找查询参数值：
+这时可以用 `alias` 参数声明一个别名，FastAPI 会用该别名在 URL 中查找参数值：
-{* ../../docs_src/query_params_str_validations/tutorial009.py hl[9] *}
+{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
-## 弃用参数
+## 弃用参数 { #deprecating-parameters }
-现在假设你不再喜欢此参数。
+现在假设你不再喜欢这个参数了。
-你不得不将其保留一段时间，因为有些客户端正在使用它，但你希望文档清楚地将其展示为已弃用。
+由于还有客户端在使用它，你不得不保留一段时间，但你希望文档清楚地将其展示为已弃用。
-那么将参数 `deprecated=True` 传入 `Query`：
+那么将参数 `deprecated=True` 传给 `Query`：
-{* ../../docs_src/query_params_str_validations/tutorial010.py hl[18] *}
+{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
文档将会像下面这样展示它：
-
+
+
+## 从 OpenAPI 中排除参数 { #exclude-parameters-from-openapi }
+
+要把某个查询参数从生成的 OpenAPI 模式中排除（从而也不会出现在自动文档系统中），将 `Query` 的参数 `include_in_schema` 设为 `False`：
-## 总结
+{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
-你可以为查询参数声明额外的校验和元数据。
+## 自定义校验 { #custom-validation }
+
+有些情况下你需要做一些无法通过上述参数完成的**自定义校验**。
+
+在这些情况下，你可以使用**自定义校验函数**，该函数会在正常校验之后应用（例如，在先校验值是 `str` 之后）。
+
+你可以在 `Annotated` 中使用 
+### 类型注解与工具链 { #type-annotations-and-tooling }
-并且两种模型都将在交互式 API 文档中使用：
+先看看编辑器、mypy 和其他工具会如何看待它。
-
+`BaseUser` 有基础字段。然后 `UserIn` 继承自 `BaseUser` 并新增了 `password` 字段，因此它包含了两个模型的全部字段。
-## 响应模型编码参数
+我们把函数返回类型注解为 `BaseUser`，但实际上返回的是一个 `UserIn` 实例。
+
+编辑器、mypy 和其他工具不会对此抱怨，因为在类型系统里，`UserIn` 是 `BaseUser` 的子类，这意味着当期望 `BaseUser` 时，返回 `UserIn` 是*合法*的。
+
+### FastAPI 的数据过滤 { #fastapi-data-filtering }
+
+对于 FastAPI，它会查看返回类型并确保你返回的内容**只**包含该类型中声明的字段。
+
+FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承的这些规则用于返回数据的过滤，否则你可能会返回比预期多得多的数据。
+
+这样，你就能兼得两方面的优势：带有**工具支持**的类型注解和**数据过滤**。
+
+## 在文档中查看 { #see-it-in-the-docs }
+
+当你查看自动文档时，你会看到输入模型和输出模型都会有各自的 JSON Schema：
+
+
+
+并且两个模型都会用于交互式 API 文档：
+
+
+
+## 其他返回类型注解 { #other-return-type-annotations }
+
+有些情况下你会返回一些不是有效 Pydantic 字段的内容，并在函数上做了相应注解，只是为了获得工具链（编辑器、mypy 等）的支持。
+
+### 直接返回 Response { #return-a-response-directly }
+
+最常见的情况是[直接返回 Response，详见进阶文档](../advanced/response-directly.md){.internal-link target=_blank}。
+
+{* ../../docs_src/response_model/tutorial003_02_py39.py hl[8,10:11] *}
+
+这个简单场景 FastAPI 会自动处理，因为返回类型注解是 `Response`（或其子类）。
+
+工具也会满意，因为 `RedirectResponse` 和 `JSONResponse` 都是 `Response` 的子类，所以类型注解是正确的。
+
+### 注解 Response 的子类 { #annotate-a-response-subclass }
+
+你也可以在类型注解中使用 `Response` 的子类：
+
+{* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *}
+
+这同样可行，因为 `RedirectResponse` 是 `Response` 的子类，FastAPI 会自动处理这个简单场景。
+
+### 无效的返回类型注解 { #invalid-return-type-annotations }
+
+但当你返回其他任意对象（如数据库对象）而它不是有效的 Pydantic 类型，并在函数中按此进行了注解时，FastAPI 会尝试基于该类型注解创建一个 Pydantic 响应模型，但会失败。
+
+如果你有一个在多个类型之间的联合类型，其中一个或多个不是有效的 Pydantic 类型，也会发生同样的情况，例如这个会失败 💥：
+
+{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
+
+……它失败是因为该类型注解不是 Pydantic 类型，也不只是单个 `Response` 类或其子类，而是 `Response` 与 `dict` 的联合类型（任意其一）。
+
+### 禁用响应模型 { #disable-response-model }
+
+延续上面的例子，你可能不想要 FastAPI 执行默认的数据校验、文档、过滤等。
+
+但你可能仍然想在函数上保留返回类型注解，以获得编辑器和类型检查器（如 mypy）的支持。
+
+在这种情况下，你可以通过设置 `response_model=None` 来禁用响应模型生成：
+
+{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
+
+这会让 FastAPI 跳过响应模型的生成，这样你就可以按需使用任意返回类型注解，而不会影响你的 FastAPI 应用。🤓
+
+## 响应模型的编码参数 { #response-model-encoding-parameters }
你的响应模型可以具有默认值，例如：
-{* ../../docs_src/response_model/tutorial004.py hl[11,13:14] *}
+{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
-* `description: Union[str, None] = None` 具有默认值 `None`。
-* `tax: float = 10.5` 具有默认值 `10.5`.
-* `tags: List[str] = []` 具有一个空列表作为默认值： `[]`.
+* `description: Union[str, None] = None`（或在 Python 3.10 中的 `str | None = None`）默认值为 `None`。
+* `tax: float = 10.5` 默认值为 `10.5`。
+* `tags: List[str] = []` 默认值为一个空列表：`[]`。
-但如果它们并没有存储实际的值，你可能想从结果中忽略它们的默认值。
+但如果它们并没有被实际存储，你可能希望在结果中省略这些默认值。
-举个例子，当你在 NoSQL 数据库中保存了具有许多可选属性的模型，但你又不想发送充满默认值的很长的 JSON 响应。
+例如，当你在 NoSQL 数据库中保存了具有许多可选属性的模型，但又不想发送充满默认值的冗长 JSON 响应。
-### 使用 `response_model_exclude_unset` 参数
+### 使用 `response_model_exclude_unset` 参数 { #use-the-response-model-exclude-unset-parameter }
-你可以设置*路径操作装饰器*的 `response_model_exclude_unset=True` 参数：
+你可以设置*路径操作装饰器*参数 `response_model_exclude_unset=True`：
-{* ../../docs_src/response_model/tutorial004.py hl[24] *}
+{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
-然后响应中将不会包含那些默认值，而是仅有实际设置的值。
+这样响应中将不会包含那些默认值，而只包含实际设置的值。
-因此，如果你向*路径操作*发送 ID 为 `foo` 的商品的请求，则响应（不包括默认值）将为：
+因此，如果你向该*路径操作*请求 ID 为 `foo` 的商品，响应（不包括默认值）将为：
```JSON
{
@@ -114,24 +250,18 @@ FastAPI 将使用此 `response_model` 来：
}
```
-/// info
-
-FastAPI 通过 Pydantic 模型的 `.dict()` 配合 
-/// note | 笔记
+/// note | 注意
某些响应状态码表示响应没有响应体（参阅下一章）。
@@ -39,9 +39,9 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。
///
-## 关于 HTTP 状态码
+## 关于 HTTP 状态码 { #about-http-status-codes }
-/// note | 笔记
+/// note | 注意
如果已经了解 HTTP 状态码，请跳到下一章。
@@ -53,40 +53,40 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。
简言之：
-* `100` 及以上的状态码用于返回**信息**。这类状态码很少直接使用。具有这些状态码的响应不能包含响应体
-* **`200`** 及以上的状态码用于表示**成功**。这些状态码是最常用的
- * `200` 是默认状态代码，表示一切**正常**
- * `201` 表示**已创建**，通常在数据库中创建新记录后使用
- * `204` 是一种特殊的例子，表示**无内容**。该响应在没有为客户端返回内容时使用，因此，该响应不能包含响应体
-* **`300`** 及以上的状态码用于**重定向**。具有这些状态码的响应不一定包含响应体，但 `304`**未修改**是个例外，该响应不得包含响应体
-* **`400`** 及以上的状态码用于表示**客户端错误**。这些可能是第二常用的类型
- * `404`，用于**未找到**响应
+* `100 - 199` 用于返回“信息”。这类状态码很少直接使用。具有这些状态码的响应不能包含响应体
+* **`200 - 299`** 用于表示“成功”。这些状态码是最常用的
+ * `200` 是默认状态码，表示一切“OK”
+ * `201` 表示“已创建”，通常在数据库中创建新记录后使用
+ * `204` 是一种特殊的例子，表示“无内容”。该响应在没有为客户端返回内容时使用，因此，该响应不能包含响应体
+* **`300 - 399`** 用于“重定向”。具有这些状态码的响应不一定包含响应体，但 `304`“未修改”是个例外，该响应不得包含响应体
+* **`400 - 499`** 用于表示“客户端错误”。这些可能是第二常用的类型
+ * `404`，用于“未找到”响应
* 对于来自客户端的一般错误，可以只使用 `400`
-* `500` 及以上的状态码用于表示服务器端错误。几乎永远不会直接使用这些状态码。应用代码或服务器出现问题时，会自动返回这些状态代码
+* `500 - 599` 用于表示服务器端错误。几乎永远不会直接使用这些状态码。应用代码或服务器出现问题时，会自动返回这些状态码
/// tip | 提示
-状态码及适用场景的详情，请参阅 
+
/// note | 技术细节
@@ -96,6 +96,6 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。
///
-## 更改默认状态码
+## 更改默认状态码 { #changing-the-default }
[高级用户指南](../advanced/response-change-status-code.md){.internal-link target=_blank}中，将介绍如何返回与在此声明的默认状态码不同的状态码。
diff --git a/docs/zh/docs/tutorial/schema-extra-example.md b/docs/zh/docs/tutorial/schema-extra-example.md
index 6c132eed3f..818ff5087b 100644
--- a/docs/zh/docs/tutorial/schema-extra-example.md
+++ b/docs/zh/docs/tutorial/schema-extra-example.md
@@ -1,55 +1,202 @@
-# 模式的额外信息 - 例子
+# 声明请求示例数据 { #declare-request-example-data }
-您可以在JSON模式中定义额外的信息。
+你可以为你的应用将接收的数据声明示例。
-一个常见的用例是添加一个将在文档中显示的`example`。
+这里有几种实现方式。
-有几种方法可以声明额外的 JSON 模式信息。
+## Pydantic 模型中的额外 JSON Schema 数据 { #extra-json-schema-data-in-pydantic-models }
-## Pydantic `schema_extra`
+你可以为一个 Pydantic 模型声明 `examples`，它们会被添加到生成的 JSON Schema 中。
-您可以使用 `Config` 和 `schema_extra` 为Pydantic模型声明一个示例，如
-## 技术细节
+### 带有多个 `examples` 的 `Body` { #body-with-multiple-examples }
+
+当然，你也可以传入多个 `examples`：
+
+{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
+
+这样做时，这些示例会成为该请求体数据内部 JSON Schema 的一部分。
+
+不过，在撰写本文时，用于展示文档 UI 的 Swagger UI 并不支持显示 JSON Schema 中数据的多个示例。但请继续阅读，下面有一种变通方法。
+
+### OpenAPI 特定的 `examples` { #openapi-specific-examples }
+
+在 JSON Schema 支持 `examples` 之前，OpenAPI 就已支持一个同名但不同的字段 `examples`。
+
+这个面向 OpenAPI 的 `examples` 位于 OpenAPI 规范的另一处。它放在每个路径操作的详细信息中，而不是每个 JSON Schema 里。
+
+而 Swagger UI 早就支持这个特定的 `examples` 字段。因此，你可以用它在文档 UI 中展示不同的示例。
+
+这个 OpenAPI 特定字段 `examples` 的结构是一个包含多个示例的 `dict`（而不是一个 `list`），每个示例都包含会被添加到 OpenAPI 的额外信息。
+
+这不放在 OpenAPI 内部包含的各个 JSON Schema 里，而是直接放在路径操作上。
+
+### 使用 `openapi_examples` 参数 { #using-the-openapi-examples-parameter }
+
+你可以在 FastAPI 中通过参数 `openapi_examples` 来声明这个 OpenAPI 特定的 `examples`，适用于：
+
+- `Path()`
+- `Query()`
+- `Header()`
+- `Cookie()`
+- `Body()`
+- `Form()`
+- `File()`
+
+这个 `dict` 的键用于标识每个示例，每个值是另一个 `dict`。
+
+`examples` 中每个具体示例的 `dict` 可以包含：
+
+- `summary`：该示例的简短描述。
+- `description`：较长描述，可以包含 Markdown 文本。
+- `value`：实际展示的示例，例如一个 `dict`。
+- `externalValue`：`value` 的替代项，指向该示例的 URL。不过它的工具支持度可能不如 `value`。
+
+你可以这样使用：
+
+{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
+
+### 文档 UI 中的 OpenAPI 示例 { #openapi-examples-in-the-docs-ui }
+
+当把 `openapi_examples` 添加到 `Body()` 后，`/docs` 会如下所示：
+
+
+
+## 技术细节 { #technical-details }
+
+/// tip | 提示
+
+如果你已经在使用 FastAPI 版本 0.99.0 或更高版本，你大概率可以跳过这些细节。
+
+它们对更早版本（OpenAPI 3.1.0 尚不可用之前）更相关。
+
+你可以把这当作一堂简短的 OpenAPI 和 JSON Schema 历史课。🤓
+
+///
+
+/// warning | 警告
+
+以下是关于 JSON Schema 和 OpenAPI 标准的非常技术性的细节。
+
+如果上面的思路对你已经足够可用，你可能不需要这些细节，可以直接跳过。
+
+///
+
+在 OpenAPI 3.1.0 之前，OpenAPI 使用的是一个更旧且经过修改的 JSON Schema 版本。
+
+当时 JSON Schema 没有 `examples`，所以 OpenAPI 在它修改过的版本中添加了自己的 `example` 字段。
+
+OpenAPI 还在规范的其他部分添加了 `example` 和 `examples` 字段：
+
+- 
/// check | Authorize 按钮！
-页面右上角出现了一个「**Authorize**」按钮。
+页面右上角已经有一个崭新的“Authorize”按钮。
-*路径操作*的右上角也出现了一个可以点击的小锁图标。
+你的*路径操作*右上角还有一个可点击的小锁图标。
///
-点击 **Authorize** 按钮，弹出授权表单，输入 `username` 与 `password` 及其它可选字段：
+点击它，会弹出一个授权表单，可输入 `username` 和 `password`（以及其它可选字段）：
-/// note | 笔记
+/// note | 注意
-目前，在表单中输入内容不会有任何反应，后文会介绍相关内容。
+目前无论在表单中输入什么都不会生效，我们稍后就会实现它。
///
-虽然此文档不是给前端最终用户使用的，但这个自动工具非常实用，可在文档中与所有 API 交互。
+这当然不是面向最终用户的前端，但它是一个很棒的自动化工具，可交互式地为整个 API 提供文档。
-前端团队（可能就是开发者本人）可以使用本工具。
+前端团队（也可能就是你自己）可以使用它。
-第三方应用与系统也可以调用本工具。
+第三方应用和系统也可以使用它。
-开发者也可以用它来调试、检查、测试应用。
+你也可以用它来调试、检查和测试同一个应用。
-## 密码流
+## `password` 流 { #the-password-flow }
-现在，我们回过头来介绍这段代码的原理。
+现在回过头来理解这些内容。
-`Password` **流**是 OAuth2 定义的，用于处理安全与身份验证的方式（**流**）。
+`password` “流”（flow）是 OAuth2 定义的处理安全与身份验证的一种方式。
-OAuth2 的设计目标是为了让后端或 API 独立于服务器验证用户身份。
+OAuth2 的设计目标是让后端或 API 与负责用户认证的服务器解耦。
-但在本例中，**FastAPI** 应用会处理 API 与身份验证。
+但在这个例子中，**FastAPI** 应用同时处理 API 和认证。
-下面，我们来看一下简化的运行流程：
+从这个简化的角度来看看流程：
-- 用户在前端输入 `username` 与`password`，并点击**回车**
-- （用户浏览器中运行的）前端把 `username` 与`password` 发送至 API 中指定的 URL（使用 `tokenUrl="token"` 声明）
-- API 检查 `username` 与`password`，并用令牌（`Token`） 响应（暂未实现此功能）：
- - 令牌只是用于验证用户的字符串
- - 一般来说，令牌会在一段时间后过期
- - 过时后，用户要再次登录
- - 这样一来，就算令牌被人窃取，风险也较低。因为它与永久密钥不同，**在绝大多数情况下**不会长期有效
-- 前端临时将令牌存储在某个位置
-- 用户点击前端，前往前端应用的其它部件
-- 前端需要从 API 中提取更多数据：
- - 为指定的端点（Endpoint）进行身份验证
- - 因此，用 API 验证身份时，要发送值为 `Bearer` + 令牌的请求头 `Authorization`
- - 假如令牌为 `foobar`，`Authorization` 请求头就是： `Bearer foobar`
+* 用户在前端输入 `username` 和 `password`，然后按下 `Enter`。
+* 前端（运行在用户浏览器中）把 `username` 和 `password` 发送到我们 API 中的特定 URL（使用 `tokenUrl="token"` 声明）。
+* API 校验 `username` 和 `password`，并返回一个“令牌”（这些我们尚未实现）。
+ * “令牌”只是一个字符串，包含一些内容，之后可用来验证该用户。
+ * 通常，令牌会在一段时间后过期。
+ * 因此，用户过一段时间需要重新登录。
+ * 如果令牌被窃取，风险也更小。它不像一把永久有效的钥匙（在大多数情况下）。
+* 前端会把令牌临时存储在某处。
+* 用户在前端中点击跳转到前端应用的其他部分。
+* 前端需要从 API 获取更多数据。
+ * 但该端点需要身份验证。
+ * 因此，为了与我们的 API 进行身份验证，它会发送一个 `Authorization` 请求头，值为 `Bearer ` 加上令牌。
+ * 如果令牌内容是 `foobar`，`Authorization` 请求头的内容就是：`Bearer foobar`。
-## **FastAPI** 的 `OAuth2PasswordBearer`
+## **FastAPI** 的 `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer }
-**FastAPI** 提供了不同抽象级别的安全工具。
+**FastAPI** 在不同抽象层级提供了多种安全工具。
-本例使用 **OAuth2** 的 **Password** 流以及 **Bearer** 令牌（`Token`）。为此要使用 `OAuth2PasswordBearer` 类。
+本示例将使用 **OAuth2** 的 **Password** 流程并配合 **Bearer** 令牌，通过 `OAuth2PasswordBearer` 类来实现。
-/// info | 说明
+/// info | 信息
-`Bearer` 令牌不是唯一的选择。
+“Bearer” 令牌并非唯一选项。
-但它是最适合这个用例的方案。
+但它非常适合我们的用例。
-甚至可以说，它是适用于绝大多数用例的最佳方案，除非您是 OAuth2 的专家，知道为什么其它方案更合适。
+对于大多数用例，它也可能是最佳选择，除非你是 OAuth2 专家，并明确知道为何其他方案更适合你的需求。
-本例中，**FastAPI** 还提供了构建工具。
+在那种情况下，**FastAPI** 同样提供了相应的构建工具。
///
-创建 `OAuth2PasswordBearer` 的类实例时，要传递 `tokenUrl` 参数。该参数包含客户端（用户浏览器中运行的前端） 的 URL，用于发送 `username` 与 `password`，并获取令牌。
+创建 `OAuth2PasswordBearer` 类实例时，需要传入 `tokenUrl` 参数。该参数包含客户端（运行在用户浏览器中的前端）用来发送 `username` 和 `password` 以获取令牌的 URL。
-{* ../../docs_src/security/tutorial001.py hl[6] *}
+{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
/// tip | 提示
-在此，`tokenUrl="token"` 指向的是暂未创建的相对 URL `token`。这个相对 URL 相当于 `./token`。
+这里的 `tokenUrl="token"` 指向的是尚未创建的相对 URL `token`，等价于 `./token`。
-因为使用的是相对 URL，如果 API 位于 `https://example.com/`，则指向 `https://example.com/token`。但如果 API 位于 `https://example.com/api/v1/`，它指向的就是`https://example.com/api/v1/token`。
+因为使用的是相对 URL，若你的 API 位于 `https://example.com/`，它将指向 `https://example.com/token`；若你的 API 位于 `https://example.com/api/v1/`，它将指向 `https://example.com/api/v1/token`。
-使用相对 URL 非常重要，可以确保应用在遇到[使用代理](../../advanced/behind-a-proxy.md){.internal-link target=_blank}这样的高级用例时，也能正常运行。
+使用相对 URL 很重要，这能确保你的应用在诸如[使用代理](../../advanced/behind-a-proxy.md){.internal-link target=_blank}等高级用例中依然正常工作。
///
-该参数不会创建端点或*路径操作*，但会声明客户端用来获取令牌的 URL `/token` 。此信息用于 OpenAPI 及 API 文档。
+这个参数不会创建该端点/*路径操作*，而是声明客户端应使用 `/token` 这个 URL 来获取令牌。这些信息会用于 OpenAPI，进而用于交互式 API 文档系统。
-接下来，学习如何创建实际的路径操作。
+我们很快也会创建对应的实际路径操作。
-/// info | 说明
+/// info | 信息
-严苛的 **Pythonista** 可能不喜欢用 `tokenUrl` 这种命名风格代替 `token_url`。
+如果你是非常严格的 “Pythonista”，可能不喜欢使用参数名 `tokenUrl` 而不是 `token_url`。
-这种命名方式是因为要使用与 OpenAPI 规范中相同的名字。以便在深入校验安全方案时，能通过复制粘贴查找更多相关信息。
+这是因为它使用了与 OpenAPI 规范中相同的名称。这样当你需要深入了解这些安全方案时，可以直接复制粘贴去查找更多信息。
///
-`oauth2_scheme` 变量是 `OAuth2PasswordBearer` 的实例，也是**可调用项**。
+`oauth2_scheme` 变量是 `OAuth2PasswordBearer` 的一个实例，同时它也是“可调用”的。
-以如下方式调用：
+可以像这样调用：
```Python
oauth2_scheme(some, parameters)
```
-因此，`Depends` 可以调用 `oauth2_scheme` 变量。
+因此，它可以与 `Depends` 一起使用。
-### 使用
+### 使用 { #use-it }
-接下来，使用 `Depends` 把 `oauth2_scheme` 传入依赖项。
+现在你可以通过 `Depends` 将 `oauth2_scheme` 作为依赖传入。
-{* ../../docs_src/security/tutorial001.py hl[10] *}
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
-该依赖项使用字符串（`str`）接收*路径操作函数*的参数 `token` 。
+该依赖会提供一个 `str`，赋值给*路径操作函数*的参数 `token`。
-**FastAPI** 使用依赖项在 OpenAPI 概图（及 API 文档）中定义**安全方案**。
+**FastAPI** 会据此在 OpenAPI 架构（以及自动生成的 API 文档）中定义一个“安全方案”。
/// info | 技术细节
-**FastAPI** 使用（在依赖项中声明的）类 `OAuth2PasswordBearer` 在 OpenAPI 中定义安全方案，这是因为它继承自 `fastapi.security.oauth2.OAuth2`，而该类又是继承自`fastapi.security.base.SecurityBase`。
+**FastAPI** 之所以知道可以使用（在依赖中声明的）`OAuth2PasswordBearer` 在 OpenAPI 中定义安全方案，是因为它继承自 `fastapi.security.oauth2.OAuth2`，而后者又继承自 `fastapi.security.base.SecurityBase`。
-所有与 OpenAPI（及 API 文档）集成的安全工具都继承自 `SecurityBase`， 这就是为什么 **FastAPI** 能把它们集成至 OpenAPI 的原因。
+所有与 OpenAPI（以及自动 API 文档）集成的安全工具都继承自 `SecurityBase`，这就是 **FastAPI** 能将它们集成到 OpenAPI 的方式。
///
-## 实现的操作
+## 它做了什么 { #what-it-does }
-FastAPI 校验请求中的 `Authorization` 请求头，核对请求头的值是不是由 `Bearer ` ＋ 令牌组成， 并返回令牌字符串（`str`）。
+它会在请求中查找 `Authorization` 请求头，检查其值是否为 `Bearer ` 加上一些令牌，并将该令牌作为 `str` 返回。
-如果没有找到 `Authorization` 请求头，或请求头的值不是 `Bearer ` ＋ 令牌。FastAPI 直接返回 401 错误状态码（`UNAUTHORIZED`）。
+如果没有 `Authorization` 请求头，或者其值不包含 `Bearer ` 令牌，它会直接返回 401 状态码错误（`UNAUTHORIZED`）。
-开发者不需要检查错误信息，查看令牌是否存在，只要该函数能够执行，函数中就会包含令牌字符串。
+你甚至无需检查令牌是否存在即可返回错误；只要你的函数被执行，就可以确定会拿到一个 `str` 类型的令牌。
-正如下图所示，API 文档已经包含了这项功能：
+你已经可以在交互式文档中试试了：
-目前，暂时还没有实现验证令牌是否有效的功能，不过后文很快就会介绍的。
+我们还没有验证令牌是否有效，但这已经是一个良好的开端。
-## 小结
+## 小结 { #recap }
-看到了吧，只要多写三四行代码，就可以添加基础的安全表单。
+只需增加三四行代码，你就已经拥有了一种初步的安全机制。
diff --git a/docs/zh/docs/tutorial/security/get-current-user.md b/docs/zh/docs/tutorial/security/get-current-user.md
index 1f254a1037..c14bba28af 100644
--- a/docs/zh/docs/tutorial/security/get-current-user.md
+++ b/docs/zh/docs/tutorial/security/get-current-user.md
@@ -1,23 +1,23 @@
-# 获取当前用户
+# 获取当前用户 { #get-current-user }
上一章中，（基于依赖注入系统的）安全系统向*路径操作函数*传递了 `str` 类型的 `token`：
-{* ../../docs_src/security/tutorial001.py hl[10] *}
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
但这并不实用。
接下来，我们学习如何返回当前用户。
-## 创建用户模型
+## 创建用户模型 { #create-a-user-model }
首先，创建 Pydantic 用户模型。
与使用 Pydantic 声明请求体相同，并且可在任何位置使用：
-{* ../../docs_src/security/tutorial002.py hl[5,12:16] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
-## 创建 `get_current_user` 依赖项
+## 创建 `get_current_user` 依赖项 { #create-a-get-current-user-dependency }
创建 `get_current_user` 依赖项。
@@ -27,19 +27,19 @@
与之前直接在路径操作中的做法相同，新的 `get_current_user` 依赖项从子依赖项 `oauth2_scheme` 中接收 `str` 类型的 `token`：
-{* ../../docs_src/security/tutorial002.py hl[25] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
-## 获取用户
+## 获取用户 { #get-the-user }
`get_current_user` 使用创建的（伪）工具函数，该函数接收 `str` 类型的令牌，并返回 Pydantic 的 `User` 模型：
-{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
-## 注入当前用户
+## 注入当前用户 { #inject-the-current-user }
在*路径操作* 的 `Depends` 中使用 `get_current_user`：
-{* ../../docs_src/security/tutorial002.py hl[31] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
注意，此处把 `current_user` 的类型声明为 Pydantic 的 `User` 模型。
@@ -61,7 +61,7 @@
///
-## 其它模型
+## 其它模型 { #other-models }
接下来，直接在*路径操作函数*中获取当前用户，并用 `Depends` 在**依赖注入**系统中处理安全机制。
@@ -78,7 +78,7 @@
尽管使用应用所需的任何模型、类、数据库。**FastAPI** 通过依赖注入系统都能帮您搞定。
-## 代码大小
+## 代码大小 { #code-size }
这个示例看起来有些冗长。毕竟这个文件同时包含了安全、数据模型的工具函数，以及路径操作等代码。
@@ -94,9 +94,9 @@
所有*路径操作*只需 3 行代码就可以了：
-{* ../../docs_src/security/tutorial002.py hl[30:32] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
-## 小结
+## 小结 { #recap }
现在，我们可以直接在*路径操作函数*中获取当前用户。
diff --git a/docs/zh/docs/tutorial/security/index.md b/docs/zh/docs/tutorial/security/index.md
index 1484b99fd8..589f93c3e9 100644
--- a/docs/zh/docs/tutorial/security/index.md
+++ b/docs/zh/docs/tutorial/security/index.md
@@ -1,4 +1,4 @@
-# 安全性
+# 安全性 { #security }
有许多方法可以处理安全性、身份认证和授权等问题。
@@ -10,11 +10,11 @@
但首先，让我们来看一些小的概念。
-## 没有时间？
+## 没有时间？ { #in-a-hurry }
-如果你不关心这些术语，而只需要*立即*通过基于用户名和密码的身份认证来增加安全性，请跳转到下一章。
+如果你不关心这些术语，而只需要*立即*通过基于用户名和密码的身份认证来增加安全性，请跳转到接下来的章节。
-## OAuth2
+## OAuth2 { #oauth2 }
OAuth2是一个规范，它定义了几种处理身份认证和授权的方法。
@@ -24,7 +24,7 @@ OAuth2是一个规范，它定义了几种处理身份认证和授权的方法
这就是所有带有「使用 Facebook，Google，X (Twitter)，GitHub 登录」的系统背后所使用的机制。
-### OAuth 1
+### OAuth 1 { #oauth-1 }
有一个 OAuth 1，它与 OAuth2 完全不同，并且更为复杂，因为它直接包含了有关如何加密通信的规范。
@@ -32,13 +32,13 @@ OAuth2是一个规范，它定义了几种处理身份认证和授权的方法
OAuth2 没有指定如何加密通信，它期望你为应用程序使用 HTTPS 进行通信。
-/// tip
+/// tip | 提示
在有关**部署**的章节中，你将了解如何使用 Traefik 和 Let's Encrypt 免费设置 HTTPS。
///
-## OpenID Connect
+## OpenID Connect { #openid-connect }
OpenID Connect 是另一个基于 **OAuth2** 的规范。
@@ -48,7 +48,7 @@ OpenID Connect 是另一个基于 **OAuth2** 的规范。
但是 Facebook 登录不支持 OpenID Connect。它具有自己的 OAuth2 风格。
-### OpenID（非「OpenID Connect」）
+### OpenID（非「OpenID Connect」） { #openid-not-openid-connect }
还有一个「OpenID」规范。它试图解决与 **OpenID Connect** 相同的问题，但它不是基于 OAuth2。
@@ -56,7 +56,7 @@ OpenID Connect 是另一个基于 **OAuth2** 的规范。
如今它已经不是很流行，没有被广泛使用了。
-## OpenAPI
+## OpenAPI { #openapi }
OpenAPI（以前称为 Swagger）是用于构建 API 的开放规范（现已成为 Linux Foundation 的一部分）。
@@ -75,7 +75,7 @@ OpenAPI 定义了以下安全方案：
* 请求头。
* cookie。
* `http`：标准的 HTTP 身份认证系统，包括：
- * `bearer`: 一个值为 `Bearer` 加令牌字符串的 `Authorization` 请求头。这是从 OAuth2 继承的。
+ * `bearer`: 一个值为 `Bearer ` 加令牌字符串的 `Authorization` 请求头。这是从 OAuth2 继承的。
* HTTP Basic 认证方式。
* HTTP Digest，等等。
* `oauth2`：所有的 OAuth2 处理安全性的方式（称为「流程」）。
@@ -89,7 +89,7 @@ OpenAPI 定义了以下安全方案：
* 此自动发现机制是 OpenID Connect 规范中定义的内容。
-/// tip
+/// tip | 提示
集成其他身份认证/授权提供者（例如Google，Facebook，X (Twitter)，GitHub等）也是可能的，而且较为容易。
@@ -97,10 +97,10 @@ OpenAPI 定义了以下安全方案：
///
-## **FastAPI** 实用工具
+## **FastAPI** 实用工具 { #fastapi-utilities }
FastAPI 在 `fastapi.security` 模块中为每个安全方案提供了几种工具，这些工具简化了这些安全机制的使用方法。
-在下一章中，你将看到如何使用 **FastAPI** 所提供的这些工具为你的 API 增加安全性。
+在接下来的章节中，你将看到如何使用 **FastAPI** 所提供的这些工具为你的 API 增加安全性。
而且你还将看到它如何自动地被集成到交互式文档系统中。
diff --git a/docs/zh/docs/tutorial/security/oauth2-jwt.md b/docs/zh/docs/tutorial/security/oauth2-jwt.md
index 7d338419b5..c7eb9bd907 100644
--- a/docs/zh/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/zh/docs/tutorial/security/oauth2-jwt.md
@@ -1,34 +1,36 @@
-# OAuth2 实现密码哈希与 Bearer JWT 令牌验证
+# 使用密码（及哈希）的 OAuth2，基于 JWT 的 Bearer 令牌 { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }
-至此，我们已经编写了所有安全流，本章学习如何使用 JWT 令牌（Token）和安全密码哈希（Hash）实现真正的安全机制。
+现在我们已经有了完整的安全流程，接下来用 JWT 令牌和安全的密码哈希，让应用真正安全起来。
-本章的示例代码真正实现了在应用的数据库中保存哈希密码等功能。
+这些代码可以直接用于你的应用，你可以把密码哈希保存到数据库中，等等。
-接下来，我们紧接上一章，继续完善安全机制。
+我们将从上一章结束的地方继续，逐步完善。
-## JWT 简介
+## 关于 JWT { #about-jwt }
-JWT 即**JSON 网络令牌**（JSON Web Tokens）。
+JWT 意为 “JSON Web Tokens”。
-JWT 是一种将 JSON 对象编码为没有空格，且难以理解的长字符串的标准。JWT 的内容如下所示：
+它是一种标准，把一个 JSON 对象编码成没有空格、很密集的一长串字符串。看起来像这样：
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```
-JWT 字符串没有加密，任何人都能用它恢复原始信息。
+它不是加密的，所以任何人都可以从内容中恢复信息。
-但 JWT 使用了签名机制。接受令牌时，可以用签名校验令牌。
+但它是“签名”的。因此，当你收到一个自己签发的令牌时，你可以验证它确实是你签发的。
-使用 JWT 创建有效期为一周的令牌。第二天，用户持令牌再次访问时，仍为登录状态。
+这样你就可以创建一个例如有效期为 1 周的令牌。然后当用户第二天带着这个令牌回来时，你能知道该用户仍然处于登录状态。
-令牌于一周后过期，届时，用户身份验证就会失败。只有再次登录，才能获得新的令牌。如果用户（或第三方）篡改令牌的过期时间，因为签名不匹配会导致身份验证失败。
+一周后令牌过期，用户将不再被授权，需要重新登录以获取新令牌。而如果用户（或第三方）尝试修改令牌来更改过期时间，你也能发现，因为签名将不匹配。
-如需深入了解 JWT 令牌，了解它的工作方式，请参阅 
+
+
+
+