```console
-$ uvicorn main:app --reload
+$ fastapi dev main.py
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -56,7 +56,7 @@ $ uvicorn main:app --reload
两个用户界面都可以正常运行，因为浏览器能够与每个指定的应用或子应用会话。
-### 技术细节：`root_path`
+### 技术细节：`root_path` { #technical-details-root-path }
以上述方式挂载子应用时，FastAPI 使用 ASGI 规范中的 `root_path` 机制处理挂载子应用路径之间的通信。
diff --git a/docs/zh/docs/advanced/testing-dependencies.md b/docs/zh/docs/advanced/testing-dependencies.md
index 8d53a6d49..54d5e8520 100644
--- a/docs/zh/docs/advanced/testing-dependencies.md
+++ b/docs/zh/docs/advanced/testing-dependencies.md
@@ -1,6 +1,6 @@
-# 测试依赖项
+# 测试依赖项 { #testing-dependencies-with-overrides }
-## 测试时覆盖依赖项
+## 测试时覆盖依赖项 { #overriding-dependencies-during-testing }
有些场景下，您可能需要在测试时覆盖依赖项。
@@ -8,7 +8,7 @@
反之，要在测试期间（或只是为某些特定测试）提供只用于测试的依赖项，并使用此依赖项的值替换原有依赖项的值。
-### 用例：外部服务
+### 用例：外部服务 { #use-cases-external-service }
常见实例是调用外部第三方身份验证应用。
@@ -20,7 +20,7 @@
此时，最好覆盖调用外部验证应用的依赖项，使用返回模拟测试用户的自定义依赖项就可以了。
-### 使用 `app.dependency_overrides` 属性
+### 使用 `app.dependency_overrides` 属性 { #use-the-app-dependency-overrides-attribute }
对于这些用例，**FastAPI** 应用支持 `app.dependency_overrides` 属性，该属性就是**字典**。
diff --git a/docs/zh/docs/advanced/using-request-directly.md b/docs/zh/docs/advanced/using-request-directly.md
index a9658c034..971c5b4cc 100644
--- a/docs/zh/docs/advanced/using-request-directly.md
+++ b/docs/zh/docs/advanced/using-request-directly.md
@@ -1,4 +1,4 @@
-# 直接使用请求
+# 直接使用请求 { #using-the-request-directly }
至此，我们已经使用多种类型声明了请求的各种组件。
@@ -13,7 +13,7 @@
但有时，我们也需要直接访问 `Request` 对象。
-## `Request` 对象的细节
+## `Request` 对象的细节 { #details-about-the-request-object }
实际上，**FastAPI** 的底层是 **Starlette**，**FastAPI** 只不过是在 **Starlette** 顶层提供了一些工具，所以能直接使用 Starlette 的
`Request` 对象。
@@ -23,13 +23,13 @@
但在某些特定情况下，还是需要提取 `Request` 对象。
-## 直接使用 `Request` 对象
+## 直接使用 `Request` 对象 { #use-the-request-object-directly }
假设要在*路径操作函数*中获取客户端 IP 地址和主机。
此时，需要直接访问请求。
-{* ../../docs_src/using_request_directly/tutorial001.py hl[1,7:8] *}
+{* ../../docs_src/using_request_directly/tutorial001_py39.py hl[1,7:8] *}
把*路径操作函数*的参数类型声明为 `Request`，**FastAPI** 就能把 `Request` 传递到参数里。
@@ -43,7 +43,7 @@
///
-## `Request` 文档
+## `Request` 文档 { #request-documentation }
更多细节详见
Starlette 官档 - `Request` 对象。
diff --git a/docs/zh/docs/advanced/wsgi.md b/docs/zh/docs/advanced/wsgi.md
index 363025a34..0c6878547 100644
--- a/docs/zh/docs/advanced/wsgi.md
+++ b/docs/zh/docs/advanced/wsgi.md
@@ -1,10 +1,10 @@
-# 包含 WSGI - Flask，Django，其它
+# 包含 WSGI - Flask，Django，其它 { #including-wsgi-flask-django-others }
您可以挂载多个 WSGI 应用，正如您在 [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank}, [Behind a Proxy](behind-a-proxy.md){.internal-link target=_blank} 中所看到的那样。
为此, 您可以使用 `WSGIMiddleware` 来包装你的 WSGI 应用，如：Flask，Django，等等。
-## 使用 `WSGIMiddleware`
+## 使用 `WSGIMiddleware` { #using-wsgimiddleware }
您需要导入 `WSGIMiddleware`。
@@ -12,9 +12,9 @@
之后将其挂载到某一个路径下。
-{* ../../docs_src/wsgi/tutorial001.py hl[2:3,22] *}
+{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *}
-## 检查
+## 检查 { #check-it }
现在，所有定义在 `/v1/` 路径下的请求将会被 Flask 应用处理。
diff --git a/docs/zh/docs/async.md b/docs/zh/docs/async.md
index 4028ed51a..ab982adf1 100644
--- a/docs/zh/docs/async.md
+++ b/docs/zh/docs/async.md
@@ -1,8 +1,8 @@
-# 并发 async / await
+# 并发 async / await { #concurrency-and-async-await }
有关路径操作函数的 `async def` 语法以及异步代码、并发和并行的一些背景知识。
-## 赶时间吗？
+## 赶时间吗？ { #in-a-hurry }
TL;DR:
@@ -54,7 +54,7 @@ def results():
但是，通过遵循上述步骤，它将能够进行一些性能优化。
-## 技术细节
+## 技术细节 { #technical-details }
Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 `await` 语法的东西来写**”异步代码“**。
@@ -64,7 +64,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
* **`async` 和 `await`**
* **协程**
-## 异步代码
+## 异步代码 { #asynchronous-code }
异步代码仅仅意味着编程语言 💬 有办法告诉计算机/程序 🤖 在代码中的某个点，它 🤖 将不得不等待在某些地方完成一些事情。让我们假设一些事情被称为 "慢文件"📝.
@@ -93,7 +93,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
对于"同步"（与"异步"相反），他们通常也使用"顺序"一词，因为计算机程序在切换到另一个任务之前是按顺序执行所有步骤，即使这些步骤涉及到等待。
-### 并发与汉堡
+### 并发与汉堡 { #concurrency-and-burgers }
上述异步代码的思想有时也被称为“并发”，它不同于“并行”。
@@ -103,7 +103,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
要了解差异，请想象以下关于汉堡的故事：
-### 并发汉堡
+### 并发汉堡 { #concurrent-burgers }
你和你的恋人一起去快餐店，你排队在后面，收银员从你前面的人接单。😍
@@ -163,7 +163,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
然后你去柜台🔀， 到现在初始任务已经完成⏯， 拿起汉堡，说声谢谢，然后把它们送到桌上。这就完成了与计数器交互的步骤/任务⏹. 这反过来又产生了一项新任务，即"吃汉堡"🔀 ⏯， 上一个"拿汉堡"的任务已经结束了⏹.
-### 并行汉堡
+### 并行汉堡 { #parallel-burgers }
现在让我们假设不是"并发汉堡"，而是"并行汉堡"。
@@ -233,7 +233,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
你可不会想带你的恋人 😍 和你一起去银行办事🏦.
-### 汉堡结论
+### 汉堡结论 { #burger-conclusion }
在"你与恋人一起吃汉堡"的这个场景中，因为有很多人在等待🕙， 使用并发系统更有意义⏸🔀⏯.
@@ -253,7 +253,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
你可以同时拥有并行性和异步性，你可以获得比大多数经过测试的 NodeJS 框架更高的性能，并且与 Go 不相上下， Go 是一种更接近于 C 的编译语言（
全部归功于 Starlette）。
-### 并发比并行好吗？
+### 并发比并行好吗？ { #is-concurrency-better-than-parallelism }
不！这不是故事的本意。
@@ -290,7 +290,7 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。
* **机器学习**: 它通常需要大量的"矩阵"和"向量"乘法。想象一个包含数字的巨大电子表格，并同时将所有数字相乘；
* **深度学习**: 这是机器学习的一个子领域，同样适用。只是没有一个数字的电子表格可以相乘，而是一个庞大的数字集合，在很多情况下，你需要使用一个特殊的处理器来构建和使用这些模型。
-### 并发 + 并行: Web + 机器学习
+### 并发 + 并行: Web + 机器学习 { #concurrency-parallelism-web-machine-learning }
使用 **FastAPI**，你可以利用 Web 开发中常见的并发机制的优势（NodeJS 的主要吸引力）。
@@ -300,7 +300,7 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。
了解如何在生产环境中实现这种并行性，可查看此文 [Deployment](deployment/index.md){.internal-link target=_blank}。
-## `async` 和 `await`
+## `async` 和 `await` { #async-and-await }
现代版本的 Python 有一种非常直观的方式来定义异步代码。这使它看起来就像正常的"顺序"代码，并在适当的时候"等待"。
@@ -349,7 +349,7 @@ async def read_burgers():
return burgers
```
-### 更多技术细节
+### 更多技术细节 { #more-technical-details }
你可能已经注意到，`await` 只能在 `async def` 定义的函数内部使用。
@@ -361,7 +361,7 @@ async def read_burgers():
但如果你想在没有 FastAPI 的情况下使用 `async` / `await`，则可以这样做。
-### 编写自己的异步代码
+### 编写自己的异步代码 { #write-your-own-async-code }
Starlette （和 **FastAPI**） 是基于
AnyIO 实现的，这使得它们可以兼容 Python 的标准库
asyncio 和
Trio。
@@ -371,7 +371,7 @@ Starlette （和 **FastAPI**） 是基于
Asyncer。如果你有**结合使用异步代码和常规**（阻塞/同步）代码的需求，这个库会特别有用。
-### 其他形式的异步代码
+### 其他形式的异步代码 { #other-forms-of-asynchronous-code }
这种使用 `async` 和 `await` 的风格在语言中相对较新。
@@ -385,13 +385,13 @@ Starlette （和 **FastAPI**） 是基于
I/O 的代码。
-在这两种情况下，与你之前的框架相比，**FastAPI** 可能[仍然很快](index.md#_11){.internal-link target=_blank}。
+在这两种情况下，与你之前的框架相比，**FastAPI** 可能[仍然很快](index.md#performance){.internal-link target=_blank}。
-### 依赖
+### 依赖 { #dependencies }
这同样适用于[依赖](tutorial/dependencies/index.md){.internal-link target=_blank}。如果一个依赖是标准的 `def` 函数而不是 `async def`，它将被运行在外部线程池中。
-### 子依赖
+### 子依赖 { #sub-dependencies }
你可以拥有多个相互依赖的依赖以及[子依赖](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} （作为函数的参数），它们中的一些可能是通过 `async def` 声明，也可能是通过 `def` 声明。它们仍然可以正常工作，这些通过 `def` 声明的函数将会在外部线程中调用（来自线程池），而不是"被等待"。
-### 其他函数
+### 其他函数 { #other-utility-functions }
你可直接调用通过 `def` 或 `async def` 创建的任何其他函数，FastAPI 不会影响你调用它们的方式。
@@ -441,4 +441,4 @@ Starlette （和 **FastAPI**） 是基于 赶时间吗？.
+否则，你最好应该遵守的指导原则
赶时间吗？.
diff --git a/docs/zh/docs/deployment/concepts.md b/docs/zh/docs/deployment/concepts.md
index f7208da7c..9ea6f7437 100644
--- a/docs/zh/docs/deployment/concepts.md
+++ b/docs/zh/docs/deployment/concepts.md
@@ -1,4 +1,4 @@
-# 部署概念
+# 部署概念 { #deployments-concepts }
在部署 **FastAPI** 应用程序或任何类型的 Web API 时，有几个概念值得了解，通过掌握这些概念您可以找到**最合适的**方法来**部署您的应用程序**。
@@ -23,7 +23,7 @@
但现在，让我们仔细看一下这些重要的**概念**。 这些概念也适用于任何其他类型的 Web API。 💡
-## 安全性 - HTTPS
+## 安全性 - HTTPS { #security-https }
在[上一章有关 HTTPS](https.md){.internal-link target=_blank} 中，我们了解了 HTTPS 如何为您的 API 提供加密。
@@ -32,7 +32,7 @@
并且必须有某个东西负责**更新 HTTPS 证书**，它可以是相同的组件，也可以是不同的组件。
-### HTTPS 示例工具
+### HTTPS 示例工具 { #example-tools-for-https }
您可以用作 TLS 终止代理的一些工具包括：
@@ -56,11 +56,11 @@
接下来要考虑的概念都是关于运行实际 API 的程序（例如 Uvicorn）。
-## 程序和进程
+## 程序和进程 { #program-and-process }
我们将讨论很多关于正在运行的“**进程**”的内容，因此弄清楚它的含义以及与“**程序**”这个词有什么区别是很有用的。
-### 什么是程序
+### 什么是程序 { #what-is-a-program }
**程序**这个词通常用来描述很多东西：
@@ -68,7 +68,7 @@
* 操作系统可以**执行**的**文件**，例如：`python`、`python.exe`或`uvicorn`。
* 在操作系统上**运行**、使用CPU 并将内容存储在内存上的特定程序。 这也被称为**进程**。
-### 什么是进程
+### 什么是进程 { #what-is-a-process }
**进程** 这个词通常以更具体的方式使用，仅指在操作系统中运行的东西（如上面的最后一点）：
@@ -89,11 +89,11 @@
现在我们知道了术语“进程”和“程序”之间的区别，让我们继续讨论部署。
-## 启动时运行
+## 启动时运行 { #running-on-startup }
在大多数情况下，当您创建 Web API 时，您希望它**始终运行**、不间断，以便您的客户端始终可以访问它。 这是当然的，除非您有特定原因希望它仅在某些情况下运行，但大多数时候您希望它不断运行并且**可用**。
-### 在远程服务器中
+### 在远程服务器中 { #in-a-remote-server }
当您设置远程服务器（云服务器、虚拟机等）时，您可以做的最简单的事情就是手动运行 Uvicorn（或类似的），就像本地开发时一样。
@@ -104,15 +104,15 @@
如果服务器重新启动（例如更新后或从云提供商迁移后），您可能**不会注意到它**。 因此，您甚至不知道必须手动重新启动该进程。 所以，你的 API 将一直处于挂掉的状态。 😱
-### 启动时自动运行
+### 启动时自动运行 { #run-automatically-on-startup }
一般来说，您可能希望服务器程序（例如 Uvicorn）在服务器启动时自动启动，并且不需要任何**人为干预**，让进程始终与您的 API 一起运行（例如 Uvicorn 运行您的 FastAPI 应用程序） 。
-### 单独的程序
+### 单独的程序 { #separate-program }
为了实现这一点，您通常会有一个**单独的程序**来确保您的应用程序在启动时运行。 在许多情况下，它还可以确保其他组件或应用程序也运行，例如数据库。
-### 启动时运行的示例工具
+### 启动时运行的示例工具 { #example-tools-to-run-at-startup }
可以完成这项工作的工具的一些示例是：
@@ -128,29 +128,29 @@
我将在接下来的章节中为您提供更具体的示例。
-## 重新启动
+## 重新启动 { #restarts }
与确保应用程序在启动时运行类似，您可能还想确保它在挂掉后**重新启动**。
-### 我们会犯错误
+### 我们会犯错误 { #we-make-mistakes }
作为人类，我们总是会犯**错误**。 软件几乎*总是*在不同的地方隐藏着**bug**。 🐛
作为开发人员，当我们发现这些bug并实现新功能（也可能添加新bug😅）时，我们会不断改进代码。
-### 自动处理小错误
+### 自动处理小错误 { #small-errors-automatically-handled }
使用 FastAPI 构建 Web API 时，如果我们的代码中存在错误，FastAPI 通常会将其包含到触发错误的单个请求中。 🛡
对于该请求，客户端将收到 **500 内部服务器错误**，但应用程序将继续处理下一个请求，而不是完全崩溃。
-### 更大的错误 - 崩溃
+### 更大的错误 - 崩溃 { #bigger-errors-crashes }
尽管如此，在某些情况下，我们编写的一些代码可能会导致整个应用程序崩溃，从而导致 Uvicorn 和 Python 崩溃。 💥
尽管如此，您可能不希望应用程序因为某个地方出现错误而保持死机状态，您可能希望它**继续运行**，至少对于未破坏的*路径操作*。
-### 崩溃后重新启动
+### 崩溃后重新启动 { #restart-after-crash }
但在那些严重错误导致正在运行的**进程**崩溃的情况下，您需要一个外部组件来负责**重新启动**进程，至少尝试几次......
@@ -164,7 +164,7 @@
您可能希望让这个东西作为 **外部组件** 负责重新启动您的应用程序，因为到那时，使用 Uvicorn 和 Python 的同一应用程序已经崩溃了，因此同一应用程序的相同代码中没有东西可以对此做出什么。
-### 自动重新启动的示例工具
+### 自动重新启动的示例工具 { #example-tools-to-restart-automatically }
在大多数情况下，用于**启动时运行程序**的同一工具也用于处理自动**重新启动**。
@@ -179,19 +179,19 @@
* 作为其服务的一部分由云提供商内部处理
* 其他的...
-## 复制 - 进程和内存
+## 复制 - 进程和内存 { #replication-processes-and-memory }
对于 FastAPI 应用程序，使用像 Uvicorn 这样的服务器程序，在**一个进程**中运行一次就可以同时为多个客户端提供服务。
但在许多情况下，您会希望同时运行多个工作进程。
-### 多进程 - Workers
+### 多进程 - Workers { #multiple-processes-workers }
如果您的客户端数量多于单个进程可以处理的数量（例如，如果虚拟机不是太大），并且服务器的 CPU 中有 **多个核心**，那么您可以让 **多个进程** 运行 同时处理同一个应用程序，并在它们之间分发所有请求。
当您运行同一 API 程序的**多个进程**时，它们通常称为 **workers**。
-### 工作进程和端口
+### 工作进程和端口 { #worker-processes-and-ports }
还记得文档 [About HTTPS](https.md){.internal-link target=_blank} 中只有一个进程可以侦听服务器中的端口和 IP 地址的一种组合吗？
@@ -199,20 +199,20 @@
因此，为了能够同时拥有**多个进程**，必须有一个**单个进程侦听端口**，然后以某种方式将通信传输到每个工作进程。
-### 每个进程的内存
+### 每个进程的内存 { #memory-per-process }
现在，当程序将内容加载到内存中时，例如，将机器学习模型加载到变量中，或者将大文件的内容加载到变量中，所有这些都会消耗服务器的一点内存 (RAM) 。
多个进程通常**不共享任何内存**。 这意味着每个正在运行的进程都有自己的东西、变量和内存。 如果您的代码消耗了大量内存，**每个进程**将消耗等量的内存。
-### 服务器内存
+### 服务器内存 { #server-memory }
例如，如果您的代码加载 **1 GB 大小**的机器学习模型，则当您使用 API 运行一个进程时，它将至少消耗 1 GB RAM。 如果您启动 **4 个进程**（4 个工作进程），每个进程将消耗 1 GB RAM。 因此，您的 API 总共将消耗 **4 GB RAM**。
如果您的远程服务器或虚拟机只有 3 GB RAM，尝试加载超过 4 GB RAM 将导致问题。 🚨
-### 多进程 - 一个例子
+### 多进程 - 一个例子 { #multiple-processes-an-example }
在此示例中，有一个 **Manager Process** 启动并控制两个 **Worker Processes**。
@@ -228,7 +228,7 @@
如果您有一个每次执行相当数量的计算的 API，并且您有很多客户端，那么 **CPU 利用率** 可能也会保持稳定（而不是不断快速上升和下降）。
-### 复制工具和策略示例
+### 复制工具和策略示例 { #examples-of-replication-tools-and-strategies }
可以通过多种方法来实现这一目标，我将在接下来的章节中向您详细介绍具体策略，例如在谈论 Docker 和容器时。
@@ -255,7 +255,7 @@
///
-## 启动之前的步骤
+## 启动之前的步骤 { #previous-steps-before-starting }
在很多情况下，您希望在**启动**应用程序之前执行一些步骤。
@@ -277,7 +277,7 @@
///
-### 前面步骤策略的示例
+### 前面步骤策略的示例 { #examples-of-previous-steps-strategies }
这将在**很大程度上取决于您部署系统的方式**，并且可能与您启动程序、处理重启等的方式有关。
@@ -293,7 +293,7 @@
///
-## 资源利用率
+## 资源利用率 { #resource-utilization }
您的服务器是一个**资源**，您可以通过您的程序消耗或**利用**CPU 上的计算时间以及可用的 RAM 内存。
@@ -314,7 +314,7 @@
您可以使用“htop”等简单工具来查看服务器中使用的 CPU 和 RAM 或每个进程使用的数量。 或者您可以使用更复杂的监控工具，这些工具可能分布在服务器等上。
-## 回顾
+## 回顾 { #recap }
您在这里阅读了一些在决定如何部署应用程序时可能需要牢记的主要概念：
diff --git a/docs/zh/docs/deployment/manually.md b/docs/zh/docs/deployment/manually.md
index 2c2784a64..32c06499e 100644
--- a/docs/zh/docs/deployment/manually.md
+++ b/docs/zh/docs/deployment/manually.md
@@ -1,6 +1,6 @@
-# 手动运行服务器
+# 手动运行服务器 { #run-a-server-manually }
-## 使用 `fastapi run` 命令
+## 使用 `fastapi run` 命令 { #use-the-fastapi-run-command }
简而言之，使用 `fastapi run` 来运行您的 FastAPI 应用程序：
@@ -42,7 +42,7 @@ $
fastapi run
Granian：基于 Rust 的 HTTP 服务器，专为 Python 应用设计。
* NGINX Unit：NGINX Unit 是一个轻量级且灵活的 Web 应用运行时环境。
-## 服务器主机和服务器程序
+## 服务器主机和服务器程序 { #server-machine-and-server-program }
关于名称，有一个小细节需要记住。 💡
@@ -69,7 +69,7 @@ FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称
当提到远程主机时，通常将其称为**服务器**，但也称为**机器**(machine)、**VM**（虚拟机）、**节点**。 这些都是指某种类型的远程计算机，通常运行 Linux，您可以在其中运行程序。
-## 安装服务器程序
+## 安装服务器程序 { #install-the-server-program }
当您安装 FastAPI 时，它自带一个生产环境服务器——Uvicorn，并且您可以使用 `fastapi run` 命令来启动它。
@@ -101,7 +101,7 @@ $ pip install "uvicorn[standard]"
///
-## 运行服务器程序
+## 运行服务器程序 { #run-the-server-program }
如果您手动安装了 ASGI 服务器，通常需要以特定格式传递一个导入字符串，以便服务器能够正确导入您的 FastAPI 应用：
@@ -142,7 +142,7 @@ Uvicorn 和其他服务器支持 `--reload` 选项，该选项在开发过程中
///
-## 部署概念
+## 部署概念 { #deployment-concepts }
这些示例运行服务器程序（例如 Uvicorn），启动**单个进程**，在所有 IP（`0.0.0.0`）上监听预定义端口（例如`80`）。
diff --git a/docs/zh/docs/deployment/versions.md b/docs/zh/docs/deployment/versions.md
index 228bb0765..a088d3e57 100644
--- a/docs/zh/docs/deployment/versions.md
+++ b/docs/zh/docs/deployment/versions.md
@@ -1,4 +1,4 @@
-# 关于 FastAPI 版本
+# 关于 FastAPI 版本 { #about-fastapi-versions }
**FastAPI** 已在许多应用程序和系统的生产环境中使用。 并且测试覆盖率保持在100%。 但其开发进度仍在快速推进。
@@ -8,7 +8,7 @@
你现在就可以使用 **FastAPI** 创建生产环境应用程序（你可能已经这样做了一段时间），你只需确保使用的版本可以与其余代码正确配合即可。
-## 固定你的 `fastapi` 版本
+## 固定你的 `fastapi` 版本 { #pin-your-fastapi-version }
你应该做的第一件事是将你正在使用的 **FastAPI** 版本“固定”到你知道适用于你的应用程序的特定最新版本。
@@ -16,27 +16,27 @@
如果你使用`requirements.txt`文件，你可以使用以下命令指定版本：
-````txt
-fastapi==0.45.0
-````
+```txt
+fastapi[standard]==0.112.0
+```
这意味着你将使用版本`0.45.0`。
或者你也可以将其固定为：
-````txt
-fastapi>=0.45.0,<0.46.0
-````
+```txt
+fastapi[standard]>=0.112.0,<0.113.0
+```
这意味着你将使用`0.45.0`或更高版本，但低于`0.46.0`，例如，版本`0.45.2`仍会被接受。
如果你使用任何其他工具来管理你的安装，例如 Poetry、Pipenv 或其他工具，它们都有一种定义包的特定版本的方法。
-## 可用版本
+## 可用版本 { #available-versions }
你可以在[发行说明](../release-notes.md){.internal-link target=_blank}中查看可用版本（例如查看当前最新版本）。
-## 关于版本
+## 关于版本 { #about-versions }
遵循语义版本控制约定，任何低于`1.0.0`的版本都可能会添加 breaking changes。
@@ -62,7 +62,7 @@ fastapi>=0.45.0,<0.46.0
///
-## 升级FastAPI版本
+## 升级FastAPI版本 { #upgrading-the-fastapi-versions }
你应该为你的应用程序添加测试。
@@ -72,7 +72,7 @@ fastapi>=0.45.0,<0.46.0
如果一切正常，或者在进行必要的更改之后，并且所有测试都通过了，那么你可以将`fastapi`固定到新的版本。
-## 关于Starlette
+## 关于Starlette { #about-starlette }
你不应该固定`starlette`的版本。
@@ -80,7 +80,7 @@ fastapi>=0.45.0,<0.46.0
因此，**FastAPI** 自己可以使用正确的 Starlette 版本。
-## 关于 Pydantic
+## 关于 Pydantic { #about-pydantic }
Pydantic 包含针对 **FastAPI** 的测试及其自己的测试，因此 Pydantic 的新版本（`1.0.0`以上）始终与 FastAPI 兼容。
@@ -88,6 +88,6 @@ Pydantic 包含针对 **FastAPI** 的测试及其自己的测试，因此 Pydant
例如：
-````txt
-pydantic>=1.2.0,<2.0.0
-````
+```txt
+pydantic>=2.7.0,<3.0.0
+```
diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md
index eaf8daff7..5a8152f21 100644
--- a/docs/zh/docs/features.md
+++ b/docs/zh/docs/features.md
@@ -1,10 +1,10 @@
-# 特性
+# 特性 { #features }
-## FastAPI 特性
+## FastAPI 特性 { #fastapi-features }
**FastAPI** 提供了以下内容：
-### 基于开放标准
+### 基于开放标准 { #based-on-open-standards }
* 用于创建 API 的 OpenAPI 包含了路径操作，请求参数，请求体，安全性等的声明。
@@ -12,7 +12,7 @@
* 经过了缜密的研究后围绕这些标准而设计。并非狗尾续貂。
* 这也允许了在很多语言中自动**生成客户端代码**。
-### 自动生成文档
+### 自动生成文档 { #automatic-docs }
交互式 API 文档以及具探索性 web 界面。因为该框架是基于 OpenAPI，所以有很多可选项，FastAPI 默认自带两个交互式 API 文档。
@@ -24,7 +24,7 @@
-### 更主流的 Python
+### 更主流的 Python { #just-modern-python }
全部都基于标准的 **Python 3.6 类型**声明（感谢 Pydantic ）。没有新的语法需要学习。只需要标准的 Python 。
@@ -73,7 +73,7 @@ my_second_user: User = User(**second_user_data)
///
-### 编辑器支持
+### 编辑器支持 { #editor-support }
整个框架都被设计得易于使用且直观，所有的决定都在开发之前就在多个编辑器上进行了测试，来确保最佳的开发体验。
@@ -99,13 +99,13 @@ my_second_user: User = User(**second_user_data)
-### 简洁
+### 简洁 { #short }
任何类型都有合理的**默认值**，任何和地方都有可选配置。所有的参数被微调，来满足你的需求，定义成你需要的 API。
但是默认情况下，一切都能**“顺利工作”**。
-### 验证
+### 验证 { #validation }
* 校验大部分（甚至所有？）的 Python **数据类型**，包括：
* JSON 对象 (`dict`).
@@ -121,7 +121,7 @@ my_second_user: User = User(**second_user_data)
所有的校验都由完善且强大的 **Pydantic** 处理。
-### 安全性及身份验证
+### 安全性及身份验证 { #security-and-authentication }
集成了安全性和身份认证。杜绝数据库或者数据模型的渗透风险。
@@ -140,7 +140,7 @@ OpenAPI 中定义的安全模式，包括：
-### 依赖注入
+### 依赖注入 { #dependency-injection }
FastAPI 有一个使用非常简单，但是非常强大的依赖注入系统。
@@ -151,19 +151,19 @@ FastAPI 有一个使用非常简单，但是非常强大的Pydantic 完全兼容(并基于)。所以，你有的其他的 Pydantic 代码也能正常工作。
diff --git a/docs/zh/docs/history-design-future.md b/docs/zh/docs/history-design-future.md
index 4db5c8472..ec9350eff 100644
--- a/docs/zh/docs/history-design-future.md
+++ b/docs/zh/docs/history-design-future.md
@@ -1,4 +1,4 @@
-# 历史、设计、未来
+# 历史、设计、未来 { #history-design-and-future }
不久前，曾有 **FastAPI** 用户问过：
@@ -6,7 +6,7 @@
在此，我们简单回顾一下 **FastAPI** 的历史。
-## 备选方案
+## 备选方案 { #alternatives }
有那么几年，我曾领导数个开发团队为诸多复杂需求创建各种 API，这些需求包括机器学习、分布系统、异步任务、NoSQL 数据库等领域。
@@ -27,7 +27,7 @@
-## 调研
+## 调研 { #investigation }
通过使用之前所有的备选方案，我有机会从它们之中学到了很多东西，获取了很多想法，并以我和我的开发团队能想到的最好方式把这些思路整合成一体。
@@ -37,7 +37,7 @@
因此，甚至在开发 **FastAPI** 前，我就花了几个月的时间研究 OpenAPI、JSON Schema、OAuth2 等规范。深入理解它们之间的关系、重叠及区别之处。
-## 设计
+## 设计 { #design }
然后，我又花了一些时间从用户角度（使用 FastAPI 的开发者）设计了开发者 **API**。
@@ -51,7 +51,7 @@
所有这些都是为了给开发者提供最佳的开发体验。
-## 需求项
+## 需求项 { #requirements }
经过测试多种备选方案，我最终决定使用 **Pydantic**，并充分利用它的优势。
@@ -59,11 +59,11 @@
在开发期间，我还为 **Starlette** 做了不少贡献，这是另一个关键需求项。
-## 开发
+## 开发 { #development }
当我启动 **FastAPI** 开发的时候，绝大多数部件都已经就位，设计已经定义，需求项和工具也已经准备就绪，相关标准与规范的知识储备也非常清晰而新鲜。
-## 未来
+## 未来 { #future }
至此，**FastAPI** 及其理念已经为很多人所用。
diff --git a/docs/zh/docs/how-to/configure-swagger-ui.md b/docs/zh/docs/how-to/configure-swagger-ui.md
index 108e0cb95..e9057a595 100644
--- a/docs/zh/docs/how-to/configure-swagger-ui.md
+++ b/docs/zh/docs/how-to/configure-swagger-ui.md
@@ -1,4 +1,4 @@
-# 配置 Swagger UI
+# 配置 Swagger UI { #configure-swagger-ui }
你可以配置一些额外的 Swagger UI 参数.
@@ -8,7 +8,7 @@
FastAPI会将这些配置转换为 **JSON**，使其与 JavaScript 兼容，因为这是 Swagger UI 需要的。
-## 不使用语法高亮
+## 不使用语法高亮 { #disable-syntax-highlighting }
比如，你可以禁用 Swagger UI 中的语法高亮。
@@ -18,41 +18,41 @@ FastAPI会将这些配置转换为 **JSON**，使其与 JavaScript 兼容，因
但是你可以通过设置 `syntaxHighlight` 为 `False` 来禁用 Swagger UI 中的语法高亮：
-{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *}
+{* ../../docs_src/configure_swagger_ui/tutorial001_py39.py hl[3] *}
...在此之后，Swagger UI 将不会高亮代码:
-## 改变主题
+## 改变主题 { #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 参数，请阅读 docs for Swagger UI parameters。
-## JavaScript-only 配置
+## JavaScript-only 配置 { #javascript-only-settings }
Swagger UI 同样允许使用 **JavaScript-only** 配置对象（例如，JavaScript 函数）。
diff --git a/docs/zh/docs/how-to/general.md b/docs/zh/docs/how-to/general.md
index e8b6dd3b2..caf94d9e0 100644
--- a/docs/zh/docs/how-to/general.md
+++ b/docs/zh/docs/how-to/general.md
@@ -1,39 +1,39 @@
-# 通用 - 如何操作 - 诀窍
+# 通用 - 如何操作 - 诀窍 { #general-how-to-recipes }
这里是一些指向文档中其他部分的链接，用于解答一般性或常见问题。
-## 数据过滤 - 安全性
+## 数据过滤 - 安全性 { #filter-data-security }
为确保不返回超过需要的数据，请阅读 [教程 - 响应模型 - 返回类型](../tutorial/response-model.md){.internal-link target=_blank} 文档。
-## 文档的标签 - OpenAPI
+## 文档的标签 - OpenAPI { #documentation-tags-openapi }
在文档界面中添加**路径操作**的标签和进行分组，请阅读 [教程 - 路径操作配置 - Tags 参数](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} 文档。
-## 文档的概要和描述 - OpenAPI
+## 文档的概要和描述 - OpenAPI { #documentation-summary-and-description-openapi }
-在文档界面中添加**路径操作**的概要和描述，请阅读 [教程 - 路径操作配置 - Summary 和 Description 参数](../tutorial/path-operation-configuration.md#summary-description){.internal-link target=_blank} 文档。
+在文档界面中添加**路径操作**的概要和描述，请阅读 [教程 - 路径操作配置 - Summary 和 Description 参数](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} 文档。
-## 文档的响应描述 - OpenAPI
+## 文档的响应描述 - OpenAPI { #documentation-response-description-openapi }
在文档界面中定义并显示响应描述，请阅读 [教程 - 路径操作配置 - 响应描述](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} 文档。
-## 文档弃用**路径操作** - OpenAPI
+## 文档弃用**路径操作** - OpenAPI { #documentation-deprecate-a-path-operation-openapi }
在文档界面中显示弃用的**路径操作**，请阅读 [教程 - 路径操作配置 - 弃用](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} 文档。
-## 将任何数据转换为 JSON 兼容格式
+## 将任何数据转换为 JSON 兼容格式 { #convert-any-data-to-json-compatible }
要将任何数据转换为 JSON 兼容格式，请阅读 [教程 - JSON 兼容编码器](../tutorial/encoder.md){.internal-link target=_blank} 文档。
-## OpenAPI 元数据 - 文档
+## OpenAPI 元数据 - 文档 { #openapi-metadata-docs }
要添加 OpenAPI 的元数据，包括许可证、版本、联系方式等，请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md){.internal-link target=_blank} 文档。
-## OpenAPI 自定义 URL
+## OpenAPI 自定义 URL { #openapi-custom-url }
要自定义 OpenAPI 的 URL（或删除它），请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} 文档。
-## OpenAPI 文档 URL
+## OpenAPI 文档 URL { #openapi-docs-urls }
要更改用于自动生成文档的 URL，请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}.
diff --git a/docs/zh/docs/how-to/index.md b/docs/zh/docs/how-to/index.md
index ac097618b..e3552fb2f 100644
--- a/docs/zh/docs/how-to/index.md
+++ b/docs/zh/docs/how-to/index.md
@@ -1,4 +1,4 @@
-# 如何操作 - 诀窍
+# 如何操作 - 诀窍 { #how-to-recipes }
在这里，你将看到关于**多个主题**的不同诀窍或“如何操作”指南。
diff --git a/docs/zh/docs/project-generation.md b/docs/zh/docs/project-generation.md
index 48eb990df..9ea1a3fcb 100644
--- a/docs/zh/docs/project-generation.md
+++ b/docs/zh/docs/project-generation.md
@@ -1,20 +1,20 @@
-# FastAPI全栈模板
+# FastAPI全栈模板 { #full-stack-fastapi-template }
模板通常带有特定的设置，而且被设计为灵活和可定制的。这允许您根据项目的需求修改和调整它们，使它们成为一个很好的起点。🏁
您可以使用此模板开始，因为它包含了许多已经为您完成的初始设置、安全性、数据库和一些API端点。
-代码仓： Full Stack FastAPI Template
+代码仓： Full Stack FastAPI Template
-## FastAPI全栈模板 - 技术栈和特性
+## FastAPI全栈模板 - 技术栈和特性 { #full-stack-fastapi-template-technology-stack-and-features }
-- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) 用于Python后端API.
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com/zh) 用于Python后端API.
- 🧰 [SQLModel](https://sqlmodel.tiangolo.com) 用于Python和SQL数据库的集成（ORM）。
- 🔍 [Pydantic](https://docs.pydantic.dev) FastAPI的依赖项之一，用于数据验证和配置管理。
- 💾 [PostgreSQL](https://www.postgresql.org) 作为SQL数据库。
- 🚀 [React](https://react.dev) 用于前端。
- - 💃 使用了TypeScript、hooks、[Vite](https://vitejs.dev)和其他一些现代化的前端技术栈。
- - 🎨 [Chakra UI](https://chakra-ui.com) 用于前端组件。
+ - 💃 使用了TypeScript、hooks、[Vite](https://tailwindcss.com)和其他一些现代化的前端技术栈。
+ - 🎨 [Chakra UI](https://ui.shadcn.com) 用于前端组件。
- 🤖 一个自动化生成的前端客户端。
- 🧪 [Playwright](https://playwright.dev)用于端到端测试。
- 🦇 支持暗黑主题（Dark mode）。
diff --git a/docs/zh/docs/tutorial/cookie-param-models.md b/docs/zh/docs/tutorial/cookie-param-models.md
index 6a7b09e25..4f9b323d1 100644
--- a/docs/zh/docs/tutorial/cookie-param-models.md
+++ b/docs/zh/docs/tutorial/cookie-param-models.md
@@ -1,4 +1,4 @@
-# Cookie 参数模型
+# Cookie 参数模型 { #cookie-parameter-models }
如果您有一组相关的 **cookie**，您可以创建一个 **Pydantic 模型**来声明它们。🍪
@@ -16,7 +16,7 @@
///
-## 带有 Pydantic 模型的 Cookie
+## 带有 Pydantic 模型的 Cookie { #cookies-with-a-pydantic-model }
在 **Pydantic** 模型中声明所需的 **cookie** 参数，然后将参数声明为 `Cookie` ：
@@ -24,7 +24,7 @@
**FastAPI** 将从请求中接收到的 **cookie** 中**提取**出**每个字段**的数据，并提供您定义的 Pydantic 模型。
-## 查看文档
+## 查看文档 { #check-the-docs }
您可以在文档 UI 的 `/docs` 中查看定义的 cookie：
@@ -42,7 +42,7 @@
///
-## 禁止额外的 Cookie
+## 禁止额外的 Cookie { #forbid-extra-cookies }
在某些特殊使用情况下（可能并不常见），您可能希望**限制**您想要接收的 cookie。
@@ -50,7 +50,7 @@
您可以使用 Pydantic 的模型配置来禁止（ `forbid` ）任何额外（ `extra` ）字段：
-{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *}
+{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *}
如果客户尝试发送一些**额外的 cookie**，他们将收到**错误**响应。
@@ -71,6 +71,6 @@
}
```
-## 总结
+## 总结 { #summary }
您可以使用 **Pydantic 模型**在 **FastAPI** 中声明 **cookie**。😎
diff --git a/docs/zh/docs/tutorial/cookie-params.md b/docs/zh/docs/tutorial/cookie-params.md
index 495600814..b5dc1b1f8 100644
--- a/docs/zh/docs/tutorial/cookie-params.md
+++ b/docs/zh/docs/tutorial/cookie-params.md
@@ -1,14 +1,14 @@
-# Cookie 参数
+# Cookie 参数 { #cookie-parameters }
定义 `Cookie` 参数与定义 `Query` 和 `Path` 参数一样。
-## 导入 `Cookie`
+## 导入 `Cookie` { #import-cookie }
首先，导入 `Cookie`：
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
-## 声明 `Cookie` 参数
+## 声明 `Cookie` 参数 { #declare-cookie-parameters }
声明 `Cookie` 参数的方式与声明 `Query` 和 `Path` 参数相同。
@@ -31,6 +31,6 @@
///
-## 小结
+## 小结 { #recap }
使用 `Cookie` 声明 cookie 参数的方式与 `Query` 和 `Path` 相同。
diff --git a/docs/zh/docs/tutorial/debugging.md b/docs/zh/docs/tutorial/debugging.md
index 734b85565..e08b51ed4 100644
--- a/docs/zh/docs/tutorial/debugging.md
+++ b/docs/zh/docs/tutorial/debugging.md
@@ -1,14 +1,14 @@
-# 调试
+# 调试 { #debugging }
你可以在编辑器中连接调试器，例如使用 Visual Studio Code 或 PyCharm。
-## 调用 `uvicorn`
+## 调用 `uvicorn` { #call-uvicorn }
在你的 FastAPI 应用中直接导入 `uvicorn` 并运行：
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
+{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *}
-### 关于 `__name__ == "__main__"`
+### 关于 `__name__ == "__main__"` { #about-name-main }
`__name__ == "__main__"` 的主要目的是使用以下代码调用文件时执行一些代码：
@@ -26,7 +26,7 @@ $ python myapp.py
from myapp import app
```
-#### 更多细节
+#### 更多细节 { #more-details }
假设你的文件命名为 `myapp.py`。
@@ -74,7 +74,7 @@ from myapp import app
///
-## 使用你的调试器运行代码
+## 使用你的调试器运行代码 { #run-your-code-with-your-debugger }
由于是从代码直接运行的 Uvicorn 服务器，所以你可以从调试器直接调用 Python 程序（你的 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 51b3e9fc3..879a0a14b 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,13 +8,13 @@
对于这种情况，不必在声明*路径操作函数*的参数时使用 `Depends`，而是可以在*路径操作装饰器*中添加一个由 `dependencies` 组成的 `list`。
-## 在*路径操作装饰器*中添加 `dependencies` 参数
+## 在*路径操作装饰器*中添加 `dependencies` 参数 { #add-dependencies-to-the-path-operation-decorator }
*路径操作装饰器*支持可选参数 ~ `dependencies`。
该参数的值是由 `Depends()` 组成的 `list`：
-{* ../../docs_src/dependencies/tutorial006.py hl[17] *}
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *}
路径操作装饰器依赖项（以下简称为**“路径装饰器依赖项”**）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给*路径操作函数*。
@@ -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/global-dependencies.md b/docs/zh/docs/tutorial/dependencies/global-dependencies.md
index 797fd76b7..5d8e41082 100644
--- a/docs/zh/docs/tutorial/dependencies/global-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/global-dependencies.md
@@ -1,4 +1,4 @@
-# 全局依赖项
+# 全局依赖项 { #global-dependencies }
有时，我们要为整个应用添加依赖项。
@@ -6,10 +6,10 @@
这样一来，就可以为所有*路径操作*应用该依赖项：
-{* ../../docs_src/dependencies/tutorial012.py hl[15] *}
+{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[17] *}
[*路径装饰器依赖项*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 一章的思路均适用于全局依赖项， 在本例中，这些依赖项可以用于应用中的所有*路径操作*。
-## 为一组路径操作定义依赖项
+## 为一组路径操作定义依赖项 { #dependencies-for-groups-of-path-operations }
稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。
diff --git a/docs/zh/docs/tutorial/encoder.md b/docs/zh/docs/tutorial/encoder.md
index e52aaa2ed..fed92b080 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兼容的数据。
diff --git a/docs/zh/docs/tutorial/extra-data-types.md b/docs/zh/docs/tutorial/extra-data-types.md
index b064ee551..97f1dc5e8 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 }
到目前为止，您一直在使用常见的数据类型，如:
@@ -17,7 +17,7 @@
* 数据验证。
* 自动补全和文档。
-## 其他数据类型
+## 其他数据类型 { #other-data-types }
下面是一些你可以使用的其他数据类型:
@@ -36,7 +36,7 @@
* `datetime.timedelta`:
* 一个 Python `datetime.timedelta`.
* 在请求和响应中将表示为 `float` 代表总秒数。
- * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", 查看文档了解更多信息。
+ * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", 查看文档了解更多信息。
* `frozenset`:
* 在请求和响应中，作为 `set` 对待：
* 在请求中，列表将被读取，消除重复，并将其转换为一个 `set`。
@@ -49,9 +49,9 @@
* `Decimal`:
* 标准的 Python `Decimal`。
* 在请求和响应中被当做 `float` 一样处理。
-* 您可以在这里检查所有有效的pydantic数据类型: Pydantic data types.
+* 您可以在这里检查所有有效的pydantic数据类型: Pydantic data types.
-## 例子
+## 例子 { #example }
下面是一个*路径操作*的示例，其中的参数使用了上面的一些类型。
diff --git a/docs/zh/docs/tutorial/header-params.md b/docs/zh/docs/tutorial/header-params.md
index 19bb455cf..9f14990da 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 参数。
@@ -30,7 +30,7 @@
///
-## 自动转换
+## 自动转换 { #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/query-param-models.md b/docs/zh/docs/tutorial/query-param-models.md
index c6a79a71a..13555b496 100644
--- a/docs/zh/docs/tutorial/query-param-models.md
+++ b/docs/zh/docs/tutorial/query-param-models.md
@@ -1,4 +1,4 @@
-# 查询参数模型
+# 查询参数模型 { #query-parameter-models }
如果你有一组具有相关性的**查询参数**，你可以创建一个 **Pydantic 模型**来声明它们。
@@ -10,7 +10,7 @@ FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓
///
-## 使用 Pydantic 模型的查询参数
+## 使用 Pydantic 模型的查询参数 { #query-parameters-with-a-pydantic-model }
在一个 **Pydantic 模型**中声明你需要的**查询参数**，然后将参数声明为 `Query`：
@@ -18,7 +18,7 @@ FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓
**FastAPI** 将会从请求的**查询参数**中**提取**出**每个字段**的数据，并将其提供给你定义的 Pydantic 模型。
-## 查看文档
+## 查看文档 { #check-the-docs }
你可以在 `/docs` 页面的 UI 中查看查询参数：
@@ -26,7 +26,7 @@ FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓
-## Support de l'éditeur
+## Support de l'éditeur { #editor-support }
Dans votre éditeur, vous aurez des annotations de types et de l'auto-complétion partout dans votre fonction (ce qui n'aurait pas été le cas si vous aviez utilisé un classique `dict` plutôt qu'un modèle Pydantic) :
@@ -121,27 +121,27 @@ Ce qui améliore le support pour les modèles Pydantic avec :
///
-## Utilisez le modèle
+## Utilisez le modèle { #use-the-model }
Dans la fonction, vous pouvez accéder à tous les attributs de l'objet du modèle directement :
-{* ../../docs_src/body/tutorial002.py hl[21] *}
+{* ../../docs_src/body/tutorial002_py310.py *}
-## Corps de la requête + paramètres de chemin
+## Corps de la requête + paramètres de chemin { #request-body-path-parameters }
Vous pouvez déclarer des paramètres de chemin et un corps de requête pour la même *opération de chemin*.
**FastAPI** est capable de reconnaître que les paramètres de la fonction qui correspondent aux paramètres de chemin doivent être **récupérés depuis le chemin**, et que les paramètres de fonctions déclarés comme modèles Pydantic devraient être **récupérés depuis le corps de la requête**.
-{* ../../docs_src/body/tutorial003.py hl[17:18] *}
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
-## Corps de la requête + paramètres de chemin et de requête
+## Corps de la requête + paramètres de chemin et de requête { #request-body-path-query-parameters }
Vous pouvez aussi déclarer un **corps**, et des paramètres de **chemin** et de **requête** dans la même *opération de chemin*.
**FastAPI** saura reconnaître chacun d'entre eux et récupérer la bonne donnée au bon endroit.
-{* ../../docs_src/body/tutorial004.py hl[18] *}
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
Les paramètres de la fonction seront reconnus comme tel :
@@ -157,6 +157,6 @@ Le type `Optional` dans `Optional[str]` n'est pas utilisé par **FastAPI**, mais
///
-## Sans Pydantic
+## Sans Pydantic { #without-pydantic }
-Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de **Corps**. Pour cela, allez voir la partie de la documentation sur [Corps de la requête - Paramètres multiples](body-multiple-params.md){.internal-link target=_blank}.
+Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de **Corps**. Pour cela, allez voir la partie de la documentation sur [Corps de la requête - Paramètres multiples](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
diff --git a/docs/fr/docs/tutorial/debugging.md b/docs/fr/docs/tutorial/debugging.md
index ab00fbdeb..e13022bbc 100644
--- a/docs/fr/docs/tutorial/debugging.md
+++ b/docs/fr/docs/tutorial/debugging.md
@@ -1,14 +1,14 @@
-# Débogage
+# Débogage { #debugging }
Vous pouvez connecter le débogueur dans votre éditeur, par exemple avec Visual Studio Code ou PyCharm.
-## Faites appel à `uvicorn`
+## Faites appel à `uvicorn` { #call-uvicorn }
Dans votre application FastAPI, importez et exécutez directement `uvicorn` :
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
+{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *}
-### À propos de `__name__ == "__main__"`
+### À propos de `__name__ == "__main__"` { #about-name-main }
Le but principal de `__name__ == "__main__"` est d'avoir du code qui est exécuté lorsque votre fichier est appelé avec :
@@ -26,7 +26,7 @@ mais qui n'est pas appelé lorsqu'un autre fichier l'importe, comme dans :
from myapp import app
```
-#### Pour davantage de détails
+#### Pour davantage de détails { #more-details }
Imaginons que votre fichier s'appelle `myapp.py`.
@@ -78,7 +78,7 @@ Pour plus d'informations, consultez 
-## 检查用户名
+## 检查用户名 { #check-the-username }
以下是更完整的示例。
@@ -52,7 +52,7 @@ if not (credentials.username == "stanleyjobson") or not (credentials.password ==
但使用 `secrets.compare_digest()`，可以防御**时差攻击**，更加安全。
-### 时差攻击
+### 时差攻击 { #timing-attacks }
什么是**时差攻击**？
@@ -80,19 +80,19 @@ 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()`。
@@ -100,7 +100,7 @@ if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
在代码中使用 `secrets.compare_digest()` ，就可以安全地防御全面攻击了。
-### 返回错误
+### 返回错误 { #return-the-error }
检测到凭证不正确后，返回 `HTTPException` 及状态码 401（与无凭证时返回的内容一样），并添加请求头 `WWW-Authenticate`，让浏览器再次显示登录提示：
diff --git a/docs/zh/docs/advanced/security/index.md b/docs/zh/docs/advanced/security/index.md
index 267e7ced7..01f456157 100644
--- a/docs/zh/docs/advanced/security/index.md
+++ b/docs/zh/docs/advanced/security/index.md
@@ -1,6 +1,6 @@
-# 高级安全
+# 高级安全 { #advanced-security }
-## 附加特性
+## 附加特性 { #additional-features }
除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank} 中涵盖的功能之外，还有一些额外的功能来处理安全性.
@@ -12,7 +12,7 @@
///
-## 先阅读教程
+## 先阅读教程 { #read-the-tutorial-first }
接下来的部分假设你已经阅读了主要的 [教程 - 用户指南: 安全性](../../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 784c38490..0ef738f92 100644
--- a/docs/zh/docs/advanced/security/oauth2-scopes.md
+++ b/docs/zh/docs/advanced/security/oauth2-scopes.md
@@ -1,4 +1,4 @@
-# OAuth2 作用域
+# OAuth2 作用域 { #oauth2-scopes }
**FastAPI** 无缝集成 OAuth2 作用域（`Scopes`），可以直接使用。
@@ -26,7 +26,7 @@ OAuth2 作用域不是必需的，没有它，您也可以处理身份验证与
///
-## OAuth2 作用域与 OpenAPI
+## OAuth2 作用域与 OpenAPI { #oauth2-scopes-and-openapi }
OAuth2 规范的**作用域**是由空格分割的字符串组成的列表。
@@ -58,21 +58,21 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
///
-## 全局纵览
+## 全局纵览 { #global-view }
首先，快速浏览一下以下代码与**用户指南**中 [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 安全方案。
`scopes` 参数接收**字典**，键是作用域、值是作用域的描述：
-{* ../../docs_src/security/tutorial005.py hl[62:65] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
因为声明了作用域，所以登录或授权时会在 API 文档中显示。
@@ -82,7 +82,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
-## JWT 令牌作用域
+## JWT 令牌作用域 { #jwt-token-with-scopes }
现在，修改令牌*路径操作*，返回请求的作用域。
@@ -98,9 +98,9 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
///
-{* ../../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`。
@@ -124,7 +124,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
///
-{* ../../docs_src/security/tutorial005.py hl[4,139,166] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
/// info | 技术细节
@@ -136,7 +136,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
///
-## 使用 `SecurityScopes`
+## 使用 `SecurityScopes` { #use-securityscopes }
修改依赖项 `get_current_user`。
@@ -150,9 +150,9 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
`SecuriScopes` 类与 `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`。
@@ -164,9 +164,9 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
该异常包含了作用域所需的（如有），以空格分割的字符串（使用 `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`，并抽取作用域。
@@ -180,17 +180,17 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
还可以使用用户名验证用户，如果没有用户，也会触发之前创建的异常。
-{* ../../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` 异常。
为此，要使用包含所有作用域**字符串列表**的 `security_scopes.scopes`， 。
-{* ../../docs_src/security/tutorial005.py hl[128:134] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *}
-## 依赖项树与作用域
+## 依赖项树与作用域 { #dependency-tree-and-scopes }
再次查看这个依赖项树与作用域。
@@ -223,7 +223,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
///
-## `SecurityScopes` 的更多细节
+## `SecurityScopes` 的更多细节 { #more-details-about-securityscopes }
您可以任何位置或多个位置使用 `SecurityScopes`，不一定非得在**根**依赖项中使用。
@@ -233,7 +233,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
它们会为每个*路径操作*进行单独检查。
-## 查看文档
+## 查看文档 { #check-it }
打开 API 文档，进行身份验证，并指定要授权的作用域。
@@ -245,7 +245,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
这就是通过用户提供的令牌使用第三方应用访问这些*路径操作*时会发生的情况，具体怎样取决于用户授予第三方应用的权限。
-## 关于第三方集成
+## 关于第三方集成 { #about-third-party-integrations }
本例使用 OAuth2 **密码**流。
@@ -269,6 +269,6 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。
**FastAPI** 的 `fastapi.security.oauth2` 里包含了所有 OAuth2 身份验证流工具。
-## 装饰器 `dependencies` 中的 `Security`
+## 装饰器 `dependencies` 中的 `Security` { #security-in-decorator-dependencies }
同样，您可以在装饰器的 `dependencies` 参数中定义 `Depends` 列表，（详见[路径操作装饰器依赖项](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank})），也可以把 `scopes` 与 `Security` 一起使用。
diff --git a/docs/zh/docs/advanced/sub-applications.md b/docs/zh/docs/advanced/sub-applications.md
index c42be2849..223060df8 100644
--- a/docs/zh/docs/advanced/sub-applications.md
+++ b/docs/zh/docs/advanced/sub-applications.md
@@ -1,41 +1,41 @@
-# 子应用 - 挂载
+# 子应用 - 挂载 { #sub-applications-mounts }
如果需要两个独立的 FastAPI 应用，拥有各自独立的 OpenAPI 与文档，则需设置一个主应用，并**挂载**一个（或多个）子应用。
-## 挂载 **FastAPI** 应用
+## 挂载 **FastAPI** 应用 { #mounting-a-fastapi-application }
**挂载**是指在特定路径中添加完全**独立**的应用，然后在该路径下使用*路径操作*声明的子应用处理所有事务。
-### 顶层应用
+### 顶层应用 { #top-level-application }
首先，创建主（顶层）**FastAPI** 应用及其*路径操作*：
-{* ../../docs_src/sub_applications/tutorial001.py hl[3,6:8] *}
+{* ../../docs_src/sub_applications/tutorial001_py39.py hl[3, 6:8] *}
-### 子应用
+### 子应用 { #sub-application }
接下来，创建子应用及其*路径操作*。
子应用只是另一个标准 FastAPI 应用，但这个应用是被**挂载**的应用：
-{* ../../docs_src/sub_applications/tutorial001.py hl[11,14:16] *}
+{* ../../docs_src/sub_applications/tutorial001_py39.py hl[11, 14:16] *}
-### 挂载子应用
+### 挂载子应用 { #mount-the-sub-application }
在顶层应用 `app` 中，挂载子应用 `subapi`。
本例的子应用挂载在 `/subapi` 路径下：
-{* ../../docs_src/sub_applications/tutorial001.py hl[11,19] *}
+{* ../../docs_src/sub_applications/tutorial001_py39.py hl[11, 19] *}
-### 查看文档
+### 查看文档 { #check-the-automatic-api-docs }
如果主文件是 `main.py`，则用以下 `uvicorn` 命令运行主应用：
-## 禁止额外的表单字段
+## 禁止额外的表单字段 { #forbid-extra-form-fields }
在某些特殊使用情况下（可能并不常见），您可能希望将表单字段**限制**为仅在 Pydantic 模型中声明过的字段，并**禁止**任何**额外**的字段。
@@ -73,6 +73,6 @@ $ pip install python-multipart
}
```
-## 总结
+## 总结 { #summary }
您可以使用 Pydantic 模型在 FastAPI 中声明表单字段。😎
diff --git a/docs/zh/docs/tutorial/response-status-code.md b/docs/zh/docs/tutorial/response-status-code.md
index aa8032ada..e3cf41227 100644
--- a/docs/zh/docs/tutorial/response-status-code.md
+++ b/docs/zh/docs/tutorial/response-status-code.md
@@ -1,4 +1,4 @@
-# 响应状态码
+# 响应状态码 { #response-status-code }
与指定响应模型的方式相同，在以下任意*路径操作*中，可以使用 `status_code` 参数声明用于响应的 HTTP 状态码：
@@ -8,7 +8,7 @@
* `@app.delete()`
* 等……
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
/// note | 笔记
@@ -39,7 +39,7 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。
///
-## 关于 HTTP 状态码
+## 关于 HTTP 状态码 { #about-http-status-codes }
/// note | 笔记
@@ -70,11 +70,11 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。
///
-## 状态码名称快捷方式
+## 状态码名称快捷方式 { #shortcut-to-remember-the-names }
再看下之前的例子：
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
`201` 表示**已创建**的状态码。
@@ -82,7 +82,7 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。
可以使用 `fastapi.status` 中的快捷变量。
-{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
+{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *}
这只是一种快捷方式，具有相同的数字代码，但它可以使用编辑器的自动补全功能：
@@ -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/security/get-current-user.md b/docs/zh/docs/tutorial/security/get-current-user.md
index 1f254a103..c14bba28a 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 1484b99fd..9d110e358 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 完全不同，并且更为复杂，因为它直接包含了有关如何加密通信的规范。
@@ -38,7 +38,7 @@ OAuth2 没有指定如何加密通信，它期望你为应用程序使用 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 的一部分）。
@@ -97,7 +97,7 @@ OpenAPI 定义了以下安全方案：
///
-## **FastAPI** 实用工具
+## **FastAPI** 实用工具 { #fastapi-utilities }
FastAPI 在 `fastapi.security` 模块中为每个安全方案提供了几种工具，这些工具简化了这些安全机制的使用方法。
diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md
index f70678df8..6b0e80626 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`**表单字段。
@@ -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` 是用以下几项内容声明表单请求体的类依赖项：
@@ -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)` 是指：
@@ -146,11 +146,11 @@ UserInDB(
/// 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 对象。
@@ -168,7 +168,7 @@ UserInDB(
///
-{* ../../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,7 +194,7 @@ 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 | 说明
@@ -214,11 +214,11 @@ UserInDB(
///
-## 实际效果
+## 实际效果 { #see-it-in-action }
打开 API 文档：
-### 获取当前用户数据
+### 获取当前用户数据 { #get-your-own-user-data }
使用 `/users/me` 路径的 `GET` 操作。
@@ -260,7 +260,7 @@ UserInDB(
}
```
-### 未激活用户
+### 未激活用户 { #inactive-user }
测试未激活用户，输入以下信息，进行身份验证：
@@ -278,7 +278,7 @@ UserInDB(
}
```
-## 小结
+## 小结 { #recap }
使用本章的工具实现基于 `username` 和 `password` 的完整 API 安全系统。
diff --git a/fastapi/security/http.py b/fastapi/security/http.py
index a8ddf0c16..ae25ad219 100644
--- a/fastapi/security/http.py
+++ b/fastapi/security/http.py
@@ -118,10 +118,8 @@ class HTTPBasic(HTTPBase):
self.realm = realm # keep for OpenAPI compatibility
self.auto_error = auto_error
-
def make_authenticate_headers(self) -> dict[str, str]:
return {"WWW-Authenticate": "Basic"}
-
async def __call__( # type: ignore
self, request: Request