但如果我们在“官方”URL（代理端口为 `9999`）的 `/api/v1/docs` 访问文档界面，它就能正常工作！🎉
-你可以在 
@@ -433,7 +433,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
///
-在 
@@ -461,6 +461,6 @@ OpenAPI 规范中的 `servers` 属性是可选的。
## 挂载子应用 { #mounting-a-sub-application }
-如果你需要在使用带有 `root_path` 的代理时挂载一个子应用（参见 [子应用 - 挂载](sub-applications.md){.internal-link target=_blank}），你可以像预期的那样正常操作。
+如果你需要在使用带有 `root_path` 的代理时挂载一个子应用（参见 [子应用 - 挂载](sub-applications.md)），你可以像预期的那样正常操作。
FastAPI 会在内部智能地使用 `root_path`，因此它可以直接正常工作。✨
diff --git a/docs/zh/docs/advanced/custom-response.md b/docs/zh/docs/advanced/custom-response.md
index 7c19b73fb..ce595572d 100644
--- a/docs/zh/docs/advanced/custom-response.md
+++ b/docs/zh/docs/advanced/custom-response.md
@@ -1,52 +1,36 @@
# 自定义响应 - HTML、流、文件等 { #custom-response-html-stream-file-others }
-**FastAPI** 默认会使用 `JSONResponse` 返回响应。
+默认情况下，**FastAPI** 会返回 JSON 响应。
-你可以通过直接返回 `Response` 来重载它，参见 [直接返回响应](response-directly.md){.internal-link target=_blank}。
+你可以像在 [直接返回响应](response-directly.md) 中那样，直接返回 `Response` 来重载它。
-但如果你直接返回一个 `Response`（或其任意子类，比如 `JSONResponse`），返回数据不会自动转换（即使你声明了 `response_model`），也不会自动生成文档（例如，在生成的 OpenAPI 中，HTTP 头 `Content-Type` 里的特定「媒体类型」不会被包含）。
+但如果你直接返回一个 `Response`（或其任意子类，比如 `JSONResponse`），返回的数据不会自动转换（即使你声明了 `response_model`），也不会自动生成文档（例如，在生成的 OpenAPI 中，HTTP 头 `Content-Type` 里的特定「媒体类型」不会被包含）。
你还可以在 *路径操作装饰器* 中通过 `response_class` 参数声明要使用的 `Response`（例如任意 `Response` 子类）。
你从 *路径操作函数* 中返回的内容将被放在该 `Response` 中。
-并且如果该 `Response` 有一个 JSON 媒体类型（`application/json`），比如使用 `JSONResponse` 或 `UJSONResponse` 的时候，返回的数据将使用你在路径操作装饰器中声明的任何 Pydantic 的 `response_model` 自动转换（和过滤）。
-
/// note | 注意
-如果你使用不带有任何媒体类型的响应类，FastAPI 会认为你的响应没有任何内容，所以不会在生成的 OpenAPI 文档中记录响应格式。
+如果你使用不带有媒体类型的响应类，FastAPI 会认为你的响应没有任何内容，所以不会在生成的 OpenAPI 文档中记录响应格式。
///
-## 使用 `ORJSONResponse` { #use-orjsonresponse }
+## JSON 响应 { #json-responses }
-例如，如果你需要压榨性能，你可以安装并使用
```console
-$ fastapi dev main.py
+$ fastapi dev
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
-然后在 http://127.0.0.1:8000/docs 打开文档。
+然后在 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) 打开文档。
下图显示的是主应用 API 文档，只包括其自有的*路径操作*。
-然后查看子应用文档 http://127.0.0.1:8000/subapi/docs。
+然后查看子应用文档 [http://127.0.0.1:8000/subapi/docs](http://127.0.0.1:8000/subapi/docs)。
下图显示的是子应用的 API 文档，也是只包括其自有的*路径操作*，所有这些路径操作都在 `/subapi` 子路径前缀下。
@@ -64,4 +64,4 @@ $ fastapi dev main.py
并且子应用还可以再挂载子应用，一切都会正常运行，FastAPI 可以自动处理所有 `root_path`。
-关于 `root_path` 及如何显式使用 `root_path` 的内容，详见[使用代理](behind-a-proxy.md){.internal-link target=_blank}一章。
+关于 `root_path` 及如何显式使用 `root_path` 的内容，详见[使用代理](behind-a-proxy.md)一章。
diff --git a/docs/zh/docs/advanced/templates.md b/docs/zh/docs/advanced/templates.md
index 37575aff2..952f438c7 100644
--- a/docs/zh/docs/advanced/templates.md
+++ b/docs/zh/docs/advanced/templates.md
@@ -8,7 +8,7 @@ Flask 等工具使用的 Jinja2 是最用的模板引擎。
## 安装依赖项 { #install-dependencies }
-确保你创建一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，激活它，并安装 `jinja2`：
+确保你创建一个[虚拟环境](../virtual-environments.md)，激活它，并安装 `jinja2`：
@@ -29,14 +29,14 @@ $ pip install jinja2
{* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *}
-/// note
+/// note | 注意
在 FastAPI 0.108.0，Starlette 0.29.0 之前，`name` 是第一个参数。
并且，在此之前，`request` 对象是作为 context 的一部分以键值对的形式传递的。
///
-/// tip
+/// tip | 提示
通过声明 `response_class=HTMLResponse`，API 文档就能识别响应的对象是 HTML。
@@ -122,4 +122,4 @@ Item ID: 42
## 更多说明 { #more-details }
-包括测试模板等更多详情，请参阅 Starlette 官方文档 - 模板。
+包括如何测试模板在内的更多详情，请查看 [Starlette 的模板文档](https://www.starlette.dev/templates/)。
diff --git a/docs/zh/docs/advanced/testing-websockets.md b/docs/zh/docs/advanced/testing-websockets.md
index e435e41e2..6d2e4b098 100644
--- a/docs/zh/docs/advanced/testing-websockets.md
+++ b/docs/zh/docs/advanced/testing-websockets.md
@@ -8,6 +8,6 @@
/// note | 注意
-更多细节请查看 Starlette 的文档：测试 WebSockets。
+更多细节请查看 Starlette 的文档：[测试 WebSockets](https://www.starlette.dev/testclient/#testing-websocket-sessions)。
///
diff --git a/docs/zh/docs/advanced/using-request-directly.md b/docs/zh/docs/advanced/using-request-directly.md
index 8cfad4203..519443d9d 100644
--- a/docs/zh/docs/advanced/using-request-directly.md
+++ b/docs/zh/docs/advanced/using-request-directly.md
@@ -15,7 +15,7 @@
## `Request` 对象的细节 { #details-about-the-request-object }
-实际上，**FastAPI** 的底层是 **Starlette**，**FastAPI** 只不过是在 **Starlette** 顶层提供了一些工具，所以能直接使用 Starlette 的 `Request` 对象。
+实际上，**FastAPI** 的底层是 **Starlette**，**FastAPI** 只不过是在 **Starlette** 顶层提供了一些工具，所以能直接使用 Starlette 的 [`Request`](https://www.starlette.dev/requests/) 对象。
但直接从 `Request` 对象提取数据时（例如，读取请求体），这些数据不会被 **FastAPI** 验证、转换或文档化（使用 OpenAPI，为自动的 API 用户界面）。
@@ -45,7 +45,7 @@
## `Request` 文档 { #request-documentation }
-更多细节详见 Starlette 官档 - `Request` 对象。
+你可以在[Starlette 官方文档站点的 `Request` 对象](https://www.starlette.dev/requests/)中阅读更多细节。
/// note | 技术细节
diff --git a/docs/zh/docs/advanced/websockets.md b/docs/zh/docs/advanced/websockets.md
index a4cdae3a2..d90ef8733 100644
--- a/docs/zh/docs/advanced/websockets.md
+++ b/docs/zh/docs/advanced/websockets.md
@@ -1,10 +1,10 @@
# WebSockets { #websockets }
-您可以在 **FastAPI** 中使用 WebSockets。
+您可以在 **FastAPI** 中使用 [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)。
## 安装 `websockets` { #install-websockets }
-请确保您创建一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}、激活它，并安装 `websockets`（一个让使用“WebSocket”协议更容易的 Python 库）：
+请确保您创建一个[虚拟环境](../virtual-environments.md)、激活它，并安装 `websockets`（一个让使用“WebSocket”协议更容易的 Python 库）：
@@ -64,19 +64,19 @@ $ pip install websockets
## 尝试一下 { #try-it }
-如果您的文件名为 `main.py`，请使用以下命令运行应用程序：
+将代码放在 `main.py`，然后运行你的应用程序：
-您的 **FastAPI** 应用程序将回复：
+您的 **FastAPI** 应用程序将通过 WebSockets 回复：
@@ -115,25 +115,25 @@ $ fastapi dev main.py
由于这是一个 WebSocket，抛出 `HTTPException` 并不是很合理，而是抛出 `WebSocketException`。
-您可以使用规范中定义的有效代码。
+您可以使用[规范中定义的有效代码](https://tools.ietf.org/html/rfc6455#section-7.4.1)。
///
### 尝试带有依赖项的 WebSockets { #try-the-websockets-with-dependencies }
-如果您的文件名为 `main.py`，请使用以下命令运行应用程序：
+运行你的应用程序：
```console
-$ fastapi dev main.py
+$ fastapi dev
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
-在浏览器中打开 http://127.0.0.1:8000。
+在浏览器中打开 [http://127.0.0.1:8000](http://127.0.0.1:8000)。
您将看到一个简单的页面，如下所示：
@@ -86,7 +86,7 @@ $ fastapi dev main.py
-您的 **FastAPI** 应用程序将回复：
+您的 **FastAPI** 应用程序将通过 WebSockets 回复：
@@ -115,25 +115,25 @@ $ fastapi dev main.py
由于这是一个 WebSocket，抛出 `HTTPException` 并不是很合理，而是抛出 `WebSocketException`。
-您可以使用规范中定义的有效代码。
+您可以使用[规范中定义的有效代码](https://tools.ietf.org/html/rfc6455#section-7.4.1)。
///
### 尝试带有依赖项的 WebSockets { #try-the-websockets-with-dependencies }
-如果您的文件名为 `main.py`，请使用以下命令运行应用程序：
+运行你的应用程序：
```console
-$ fastapi dev main.py
+$ fastapi dev
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
-在浏览器中打开 http://127.0.0.1:8000。
+在浏览器中打开 [http://127.0.0.1:8000](http://127.0.0.1:8000)。
在页面中，您可以设置：
@@ -174,7 +174,7 @@ Client #1596980209979 left the chat
但请记住，由于所有内容都在内存中以单个列表的形式处理，因此它只能在进程运行时工作，并且只能使用单个进程。
-如果您需要与 FastAPI 集成更简单但更强大的功能，支持 Redis、PostgreSQL 或其他功能，请查看 encode/broadcaster。
+如果您需要与 FastAPI 集成更简单但更强大的功能，支持 Redis、PostgreSQL 或其他功能，请查看 [encode/broadcaster](https://github.com/encode/broadcaster)。
///
@@ -182,5 +182,5 @@ Client #1596980209979 left the chat
要了解更多选项，请查看 Starlette 的文档：
-* `WebSocket` 类。
-* 基于类的 WebSocket 处理。
+* [`WebSocket` 类](https://www.starlette.dev/websockets/)。
+* [基于类的 WebSocket 处理](https://www.starlette.dev/endpoints/#websocketendpoint)。
diff --git a/docs/zh/docs/advanced/wsgi.md b/docs/zh/docs/advanced/wsgi.md
index 487fbf8dd..038b672f8 100644
--- a/docs/zh/docs/advanced/wsgi.md
+++ b/docs/zh/docs/advanced/wsgi.md
@@ -1,6 +1,6 @@
# 包含 WSGI - Flask，Django，其它 { #including-wsgi-flask-django-others }
-您可以挂载 WSGI 应用，正如您在 [子应用 - 挂载](sub-applications.md){.internal-link target=_blank}、[在代理之后](behind-a-proxy.md){.internal-link target=_blank} 中所看到的那样。
+您可以挂载 WSGI 应用，正如您在 [子应用 - 挂载](sub-applications.md)、[在代理之后](behind-a-proxy.md) 中所看到的那样。
为此, 您可以使用 `WSGIMiddleware` 来包装你的 WSGI 应用，如：Flask，Django，等等。
@@ -36,13 +36,13 @@
其余的请求则会被 **FastAPI** 处理。
-如果你运行它并访问 http://localhost:8000/v1/，你将会看到由 Flask 返回的响应：
+如果你运行它并访问 [http://localhost:8000/v1/](http://localhost:8000/v1/)，你将会看到由 Flask 返回的响应：
```txt
Hello, World from Flask!
```
-如果你访问 http://localhost:8000/v2，你将会看到由 FastAPI 返回的响应：
+如果你访问 [http://localhost:8000/v2](http://localhost:8000/v2)，你将会看到由 FastAPI 返回的响应：
```JSON
{
diff --git a/docs/zh/docs/alternatives.md b/docs/zh/docs/alternatives.md
index 8a552c91d..fe7aa9869 100644
--- a/docs/zh/docs/alternatives.md
+++ b/docs/zh/docs/alternatives.md
@@ -14,7 +14,7 @@
## 先前的工具 { #previous-tools }
-### Django { #django }
+### [Django](https://www.djangoproject.com/) { #django }
它是最流行且被广泛信任的 Python 框架。被用于构建 Instagram 等系统。
@@ -22,7 +22,7 @@
它最初用于在后端生成 HTML，而不是创建由现代前端（如 React、Vue.js、Angular）或与之通信的其他系统（如 IoT 设备）使用的 API。
-### Django REST Framework { #django-rest-framework }
+### [Django REST Framework](https://www.django-rest-framework.org/) { #django-rest-framework }
Django REST framework 作为一个灵活工具箱而创建，用于在底层使用 Django 构建 Web API，从而增强其 API 能力。
@@ -42,7 +42,7 @@ Django REST Framework 由 Tom Christie 创建。他也是 Starlette 和 Uvicorn
///
-### Flask { #flask }
+### [Flask](https://flask.palletsprojects.com) { #flask }
Flask 是一个“微框架”，它不包含数据库集成，也没有像 Django 那样的许多默认内建功能。
@@ -63,7 +63,7 @@ Flask 是一个“微框架”，它不包含数据库集成，也没有像 Djan
///
-### Requests { #requests }
+### [Requests](https://requests.readthedocs.io) { #requests }
**FastAPI** 实际上不是 **Requests** 的替代品。它们的作用范围完全不同。
@@ -99,13 +99,13 @@ def read_url():
/// check | 启发 **FastAPI**：
-- 提供简单直观的 API。
-- 直接、自然地使用 HTTP 方法名（操作）。
-- 具备合理默认值，同时支持强大定制能力。
+* 提供简单直观的 API。
+* 直接、自然地使用 HTTP 方法名（操作）。
+* 具备合理默认值，同时支持强大定制能力。
///
-### Swagger / OpenAPI { #swagger-openapi }
+### [Swagger](https://swagger.io/) / [OpenAPI](https://github.com/OAI/OpenAPI-Specification/) { #swagger-openapi }
我想从 Django REST Framework 得到的主要特性之一是自动 API 文档。
@@ -123,8 +123,8 @@ def read_url():
并集成基于标准的用户界面工具：
-- Swagger UI
-- ReDoc
+* [Swagger UI](https://github.com/swagger-api/swagger-ui)
+* [ReDoc](https://github.com/Rebilly/ReDoc)
选择这两者是因为它们相当流行且稳定；但稍作搜索，你就能找到数十种 OpenAPI 的替代用户界面（都可以与 **FastAPI** 搭配使用）。
@@ -134,7 +134,7 @@ def read_url():
有若干基于 Flask 的 REST 框架，但在投入时间精力深入调研后，我发现许多已停止维护或被弃用，并存在多处未解决问题，不太适合采用。
-### Marshmallow { #marshmallow }
+### [Marshmallow](https://marshmallow.readthedocs.io/en/stable/) { #marshmallow }
API 系统所需的主要特性之一是数据“序列化”，即将代码（Python）中的数据转换为可通过网络发送的形式。例如，将包含数据库数据的对象转换为 JSON 对象、将 `datetime` 对象转换为字符串等。
@@ -152,7 +152,7 @@ API 的另一个重要特性是数据校验，确保数据在给定约束下是
///
-### Webargs { #webargs }
+### [Webargs](https://webargs.readthedocs.io/en/latest/) { #webargs }
API 的另一个重要需求是从传入请求中解析数据。
@@ -174,7 +174,7 @@ Webargs 由与 Marshmallow 相同的开发者创建。
///
-### APISpec { #apispec }
+### [APISpec](https://apispec.readthedocs.io/en/stable/) { #apispec }
Marshmallow 与 Webargs 通过插件提供了校验、解析与序列化。
@@ -204,7 +204,7 @@ APISpec 由与 Marshmallow 相同的开发者创建。
///
-### Flask-apispec { #flask-apispec }
+### [Flask-apispec](https://flask-apispec.readthedocs.io/en/latest/) { #flask-apispec }
这是一个 Flask 插件，将 Webargs、Marshmallow 与 APISpec 结合在一起。
@@ -218,11 +218,11 @@ APISpec 由与 Marshmallow 相同的开发者创建。
使用它促成了若干 Flask 全栈脚手架的诞生。以下是我（以及若干外部团队）至今使用的主要技术栈：
-* https://github.com/tiangolo/full-stack
-* https://github.com/tiangolo/full-stack-flask-couchbase
-* https://github.com/tiangolo/full-stack-flask-couchdb
+* [https://github.com/tiangolo/full-stack](https://github.com/tiangolo/full-stack)
+* [https://github.com/tiangolo/full-stack-flask-couchbase](https://github.com/tiangolo/full-stack-flask-couchbase)
+* [https://github.com/tiangolo/full-stack-flask-couchdb](https://github.com/tiangolo/full-stack-flask-couchdb)
-这些全栈脚手架也成为了[**FastAPI** 项目脚手架](project-generation.md){.internal-link target=_blank}的基础。
+这些全栈脚手架也成为了[**FastAPI** 项目脚手架](project-generation.md)的基础。
/// info | 信息
@@ -236,7 +236,7 @@ Flask-apispec 由与 Marshmallow 相同的开发者创建。
///
-### NestJS（以及 Angular） { #nestjs-and-angular }
+### [NestJS](https://nestjs.com/)（以及 [Angular](https://angular.io/)） { #nestjs-and-angular }
这甚至不是 Python。NestJS 是一个 JavaScript（TypeScript）的 NodeJS 框架，受 Angular 启发。
@@ -258,13 +258,13 @@ Flask-apispec 由与 Marshmallow 相同的开发者创建。
///
-### Sanic { #sanic }
+### [Sanic](https://sanic.readthedocs.io/en/latest/) { #sanic }
它是最早的一批基于 `asyncio` 的极速 Python 框架之一，且做得与 Flask 很相似。
/// note | 技术细节
-它使用了 `uvloop` 来替代 Python 默认的 `asyncio` 循环。这正是它如此之快的原因。
+它使用了 [`uvloop`](https://github.com/MagicStack/uvloop) 来替代 Python 默认的 `asyncio` 循环。这正是它如此之快的原因。
它显然启发了 Uvicorn 和 Starlette；在公开的基准测试中，它们目前比 Sanic 更快。
@@ -278,7 +278,7 @@ Flask-apispec 由与 Marshmallow 相同的开发者创建。
///
-### Falcon { #falcon }
+### [Falcon](https://falconframework.org/) { #falcon }
Falcon 是另一个高性能 Python 框架，它被设计为精简且可作为 Hug 等其他框架的基础。
@@ -294,7 +294,7 @@ Falcon 是另一个高性能 Python 框架，它被设计为精简且可作为 H
///
-### Molten { #molten }
+### [Molten](https://moltenframework.com/) { #molten }
我在构建 **FastAPI** 的早期阶段发现了 Molten。它有不少相似的想法：
@@ -318,7 +318,7 @@ Falcon 是另一个高性能 Python 框架，它被设计为精简且可作为 H
///
-### Hug { #hug }
+### [Hug](https://github.com/hugapi/hug) { #hug }
Hug 是最早使用 Python 类型提示来声明 API 参数类型的框架之一。这一绝妙想法也启发了其他工具。
@@ -334,7 +334,7 @@ Hug 是最早使用 Python 类型提示来声明 API 参数类型的框架之一
/// info | 信息
-Hug 由 Timothy Crosley 创建，他也是 `isort` 的作者，这是一个能自动排序 Python 文件中导入的优秀工具。
+Hug 由 Timothy Crosley 创建，他也是 [`isort`](https://github.com/timothycrosley/isort) 的作者，这是一个能自动排序 Python 文件中导入的优秀工具。
///
@@ -348,7 +348,7 @@ Hug 启发 **FastAPI** 在函数中声明 `response` 参数，用于设置 heade
///
-### APIStar (<= 0.5) { #apistar-0-5 }
+### [APIStar](https://github.com/encode/apistar) (<= 0.5) { #apistar-0-5 }
就在决定动手构建 **FastAPI** 之前，我找到了 **APIStar** 服务器。它几乎具备我想要的一切，设计也很出色。
@@ -398,7 +398,7 @@ APIStar 由 Tom Christie 创建。他还创建了：
## **FastAPI** 所使用的组件 { #used-by-fastapi }
-### Pydantic { #pydantic }
+### [Pydantic](https://docs.pydantic.dev/) { #pydantic }
Pydantic 是一个基于 Python 类型提示来定义数据校验、序列化与文档（使用 JSON Schema）的库。
@@ -414,7 +414,7 @@ Pydantic 是一个基于 Python 类型提示来定义数据校验、序列化与
///
-### Starlette { #starlette }
+### [Starlette](https://www.starlette.dev/) { #starlette }
Starlette 是一个轻量级的 ASGI 框架/工具集，非常适合构建高性能的 asyncio 服务。
@@ -459,7 +459,7 @@ ASGI 是由 Django 核心团队成员推动的新“标准”。它尚不是正
///
-### Uvicorn { #uvicorn }
+### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn }
Uvicorn 是一个基于 uvloop 与 httptools 构建的极速 ASGI 服务器。
@@ -473,10 +473,10 @@ Uvicorn 是一个基于 uvloop 与 httptools 构建的极速 ASGI 服务器。
你也可以使用 `--workers` 命令行选项以获得异步的多进程服务器。
-更多细节见[部署](deployment/index.md){.internal-link target=_blank}一节。
+更多细节见[部署](deployment/index.md)一节。
///
## 基准与速度 { #benchmarks-and-speed }
-要理解、比较并查看 Uvicorn、Starlette 与 FastAPI 之间的差异，请查看[基准](benchmarks.md){.internal-link target=_blank}一节。
+要理解、比较并查看 Uvicorn、Starlette 与 FastAPI 之间的差异，请查看[基准](benchmarks.md)一节。
diff --git a/docs/zh/docs/async.md b/docs/zh/docs/async.md
index 36d875f51..92ee5ef22 100644
--- a/docs/zh/docs/async.md
+++ b/docs/zh/docs/async.md
@@ -141,7 +141,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
/// info | 信息
-漂亮的插画来自 Ketrina Thompson. 🎨
+漂亮的插画来自 [Ketrina Thompson](https://www.instagram.com/ketrinadrawsalot)。🎨
///
@@ -207,7 +207,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
/// info | 信息
-漂亮的插画来自 Ketrina Thompson. 🎨
+漂亮的插画来自 [Ketrina Thompson](https://www.instagram.com/ketrinadrawsalot)。🎨
///
@@ -251,7 +251,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
这与 **FastAPI** 的性能水平相同。
-你可以同时拥有并行性和异步性，你可以获得比大多数经过测试的 NodeJS 框架更高的性能，并且与 Go 不相上下， Go 是一种更接近于 C 的编译语言（全部归功于 Starlette）。
+你可以同时拥有并行性和异步性，你可以获得比大多数经过测试的 NodeJS 框架更高的性能，并且与 Go 不相上下， Go 是一种更接近于 C 的编译语言（[全部归功于 Starlette](https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1)）。
### 并发比并行好吗？ { #is-concurrency-better-than-parallelism }
@@ -298,7 +298,7 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。
这一点，再加上 Python 是**数据科学**、机器学习（尤其是深度学习）的主要语言这一简单事实，使得 **FastAPI** 与数据科学/机器学习 Web API 和应用程序（以及其他许多应用程序）非常匹配。
-了解如何在生产环境中实现这种并行性，可查看此文 [部署](deployment/index.md){.internal-link target=_blank}。
+了解如何在生产环境中实现这种并行性，可查看此文 [部署](deployment/index.md)。
## `async` 和 `await` { #async-and-await }
@@ -363,13 +363,13 @@ async def read_burgers():
### 编写自己的异步代码 { #write-your-own-async-code }
-Starlette （和 **FastAPI**） 是基于 AnyIO 实现的，这使得它们可以兼容 Python 的标准库 asyncio 和 Trio。
+Starlette （和 **FastAPI**） 是基于 [AnyIO](https://anyio.readthedocs.io/en/stable/) 实现的，这使得它们可以兼容 Python 的标准库 [asyncio](https://docs.python.org/3/library/asyncio-task.html) 和 [Trio](https://trio.readthedocs.io/en/stable/)。
-特别是，你可以直接使用 AnyIO 来处理高级的并发用例，这些用例需要在自己的代码中使用更高级的模式。
+特别是，你可以直接使用 [AnyIO](https://anyio.readthedocs.io/en/stable/) 来处理高级的并发用例，这些用例需要在自己的代码中使用更高级的模式。
-即使你没有使用 **FastAPI**，你也可以使用 AnyIO 编写自己的异步程序，使其拥有较高的兼容性并获得一些好处（例如， 结构化并发）。
+即使你没有使用 **FastAPI**，你也可以使用 [AnyIO](https://anyio.readthedocs.io/en/stable/) 编写自己的异步程序，使其拥有较高的兼容性并获得一些好处（例如， 结构化并发）。
-我基于 AnyIO 新建了一个库，作为一个轻量级的封装层，用来优化类型注解，同时提供了更好的**自动补全**、**内联错误提示**等功能。这个库还附带了一个友好的入门指南和教程，能帮助你**理解**并编写**自己的异步代码**：Asyncer。如果你有**结合使用异步代码和常规**（阻塞/同步）代码的需求，这个库会特别有用。
+我基于 AnyIO 新建了一个库，作为一个轻量级的封装层，用来优化类型注解，同时提供了更好的**自动补全**、**内联错误提示**等功能。这个库还附带了一个友好的入门指南和教程，能帮助你**理解**并编写**自己的异步代码**：[Asyncer](https://asyncer.tiangolo.com/)。如果你有**结合使用异步代码和常规**（阻塞/同步）代码的需求，这个库会特别有用。
### 其他形式的异步代码 { #other-forms-of-asynchronous-code }
@@ -381,7 +381,7 @@ Starlette （和 **FastAPI**） 是基于 Gevent。但代码的理解、调试和思考都要复杂许多。
+在以前版本的 Python，你可以使用多线程或者 [Gevent](https://www.gevent.org/)。但代码的理解、调试和思考都要复杂许多。
在以前版本的 NodeJS / 浏览器 JavaScript 中，你会使用"回调"，因此也可能导致“回调地狱”。
@@ -419,15 +419,15 @@ Starlette （和 **FastAPI**） 是基于 I/O 的代码。
-在这两种情况下，与你之前的框架相比，**FastAPI** 可能[仍然很快](index.md#performance){.internal-link target=_blank}。
+在这两种情况下，与你之前的框架相比，**FastAPI** 可能[仍然很快](index.md#performance)。
### 依赖 { #dependencies }
-这同样适用于[依赖](tutorial/dependencies/index.md){.internal-link target=_blank}。如果一个依赖是标准的 `def` 函数而不是 `async def`，它将被运行在外部线程池中。
+这同样适用于[依赖](tutorial/dependencies/index.md)。如果一个依赖是标准的 `def` 函数而不是 `async def`，它将被运行在外部线程池中。
### 子依赖 { #sub-dependencies }
-你可以拥有多个相互依赖的依赖以及[子依赖](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} （作为函数的参数），它们中的一些可能是通过 `async def` 声明，也可能是通过 `def` 声明。它们仍然可以正常工作，这些通过 `def` 声明的函数将会在外部线程中调用（来自线程池），而不是"被等待"。
+你可以拥有多个相互依赖的依赖以及[子依赖](tutorial/dependencies/sub-dependencies.md) （作为函数的参数），它们中的一些可能是通过 `async def` 声明，也可能是通过 `def` 声明。它们仍然可以正常工作，这些通过 `def` 声明的函数将会在外部线程中调用（来自线程池），而不是"被等待"。
### 其他函数 { #other-utility-functions }
diff --git a/docs/zh/docs/benchmarks.md b/docs/zh/docs/benchmarks.md
index a6e706dfa..d98d3de59 100644
--- a/docs/zh/docs/benchmarks.md
+++ b/docs/zh/docs/benchmarks.md
@@ -1,6 +1,6 @@
# 基准测试 { #benchmarks }
-第三方机构 TechEmpower 的基准测试表明在 Uvicorn 下运行的 **FastAPI** 应用程序是 可用的最快的 Python 框架之一，仅次于 Starlette 和 Uvicorn 本身（由 FastAPI 内部使用）。
+第三方机构 TechEmpower 的基准测试表明在 Uvicorn 下运行的 **FastAPI** 应用程序是 [可用的最快的 Python 框架之一](https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7)，仅次于 Starlette 和 Uvicorn 本身（由 FastAPI 内部使用）。
但是在查看基准得分和对比时，请注意以下几点。
diff --git a/docs/zh/docs/deployment/cloud.md b/docs/zh/docs/deployment/cloud.md
index 96883bd6b..025715f52 100644
--- a/docs/zh/docs/deployment/cloud.md
+++ b/docs/zh/docs/deployment/cloud.md
@@ -6,7 +6,7 @@
## FastAPI Cloud { #fastapi-cloud }
-**FastAPI Cloud** 由 **FastAPI** 背后的同一作者与团队打造。
+**[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 背后的同一作者与团队打造。
它简化了**构建**、**部署**和**访问** API 的流程，几乎不费力。
@@ -16,9 +16,9 @@ FastAPI Cloud 是 *FastAPI and friends* 开源项目的主要赞助方和资金
## 云服务商 - 赞助商 { #cloud-providers-sponsors }
-还有一些云服务商也会 ✨ [**赞助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨。🙇
+还有一些云服务商也会 ✨ [**赞助 FastAPI**](../help-fastapi.md#sponsor-the-author) ✨。🙇
你也可以考虑按照他们的指南尝试他们的服务：
-* Render
-* Railway
+* [Render](https://docs.render.com/deploy-fastapi?utm_source=deploydoc&utm_medium=referral&utm_campaign=fastapi)
+* [Railway](https://docs.railway.com/guides/fastapi?utm_medium=integration&utm_source=docs&utm_campaign=fastapi)
diff --git a/docs/zh/docs/deployment/concepts.md b/docs/zh/docs/deployment/concepts.md
index 76e967d7d..dd5ba2ba8 100644
--- a/docs/zh/docs/deployment/concepts.md
+++ b/docs/zh/docs/deployment/concepts.md
@@ -25,7 +25,7 @@
## 安全性 - HTTPS { #security-https }
-在[上一章有关 HTTPS](https.md){.internal-link target=_blank} 中，我们了解了 HTTPS 如何为您的 API 提供加密。
+在[上一章有关 HTTPS](https.md) 中，我们了解了 HTTPS 如何为您的 API 提供加密。
我们还看到，HTTPS 通常由应用程序服务器的**外部**组件（**TLS 终止代理**）提供。
@@ -149,7 +149,7 @@
### 崩溃后重新启动 { #restart-after-crash }
-但在那些严重错误导致正在运行的**进程**崩溃的情况下，您需要一个外部组件来负责**重新启动**进程，至少尝试几次......
+但在那些严重错误导致正在运行的**进程**崩溃的情况下，您需要一个外部组件来负责**重新启动**进程，至少尝试几次...
/// tip | 提示
@@ -190,7 +190,7 @@
### 工作进程和端口 { #worker-processes-and-ports }
-还记得文档 [关于 HTTPS](https.md){.internal-link target=_blank} 中只有一个进程可以侦听服务器中的端口和 IP 地址的一种组合吗？
+还记得文档 [关于 HTTPS](https.md) 中只有一个进程可以侦听服务器中的端口和 IP 地址的一种组合吗？
现在仍然是对的。
@@ -243,7 +243,7 @@
如果这些关于 **容器**、Docker 或 Kubernetes 的内容还没有多大意义，请不要担心。
-我将在以后的章节中向您详细介绍容器镜像、Docker、Kubernetes 等：[容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank}。
+我将在以后的章节中向您详细介绍容器镜像、Docker、Kubernetes 等：[容器中的 FastAPI - Docker](docker.md)。
///
@@ -281,7 +281,7 @@
/// tip | 提示
-我将在以后的章节中为您提供使用容器执行此操作的更具体示例：[容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank}。
+我将在以后的章节中为您提供使用容器执行此操作的更具体示例：[容器中的 FastAPI - Docker](docker.md)。
///
diff --git a/docs/zh/docs/deployment/docker.md b/docs/zh/docs/deployment/docker.md
index 4e7410587..aa7b60b50 100644
--- a/docs/zh/docs/deployment/docker.md
+++ b/docs/zh/docs/deployment/docker.md
@@ -1,6 +1,6 @@
# 容器中的 FastAPI - Docker { #fastapi-in-containers-docker }
-部署 FastAPI 应用时，常见做法是构建一个**Linux 容器镜像**。通常使用 **Docker** 实现。然后你可以用几种方式之一部署该镜像。
+部署 FastAPI 应用时，常见做法是构建一个**Linux 容器镜像**。通常使用 [**Docker**](https://www.docker.com/) 实现。然后你可以用几种方式之一部署该镜像。
使用 Linux 容器有多种优势，包括**安全性**、**可复制性**、**简单性**等。
@@ -26,7 +26,7 @@ COPY ./app /code/app
CMD ["fastapi", "run", "app/main.py", "--port", "80"]
-# If running behind a proxy like Nginx or Traefik add --proxy-headers
+# 如果在 Nginx 或 Traefik 等代理后运行，请添加 --proxy-headers
# CMD ["fastapi", "run", "app/main.py", "--port", "80", "--proxy-headers"]
```
@@ -60,16 +60,16 @@ Linux 容器复用宿主机（物理机、虚拟机、云服务器等）的同
Docker 一直是创建和管理**容器镜像**与**容器**的主要工具之一。
-还有一个公共的 Docker Hub，其中为许多工具、环境、数据库和应用提供了预制的**官方容器镜像**。
+还有一个公共的 [Docker Hub](https://hub.docker.com/)，其中为许多工具、环境、数据库和应用提供了预制的**官方容器镜像**。
-例如，有官方的 Python 镜像。
+例如，有官方的 [Python 镜像](https://hub.docker.com/_/python)。
还有许多用于不同目的（如数据库）的镜像，例如：
-* PostgreSQL
-* MySQL
-* MongoDB
-* Redis 等。
+* [PostgreSQL](https://hub.docker.com/_/postgres)
+* [MySQL](https://hub.docker.com/_/mysql)
+* [MongoDB](https://hub.docker.com/_/mongo)
+* [Redis](https://hub.docker.com/_/redis) 等。
通过使用预制的容器镜像，可以很容易地**组合**并使用不同工具。例如，试用一个新的数据库。在大多数情况下，你可以直接使用**官方镜像**，只需通过环境变量配置即可。
@@ -111,7 +111,7 @@ Docker 一直是创建和管理**容器镜像**与**容器**的主要工具之
最常见的方式是使用 `requirements.txt` 文件，每行一个包名及其版本范围。
-当然，你也可以参考你在[关于 FastAPI 版本](versions.md){.internal-link target=_blank}中读到的思路来设置版本范围。
+当然，你也可以参考你在[关于 FastAPI 版本](versions.md)中读到的思路来设置版本范围。
例如，你的 `requirements.txt` 可能是：
@@ -238,7 +238,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80"]
#### 使用 `CMD` - Exec 形式 { #use-cmd-exec-form }
-`CMD` 指令有两种写法：
+[`CMD`](https://docs.docker.com/reference/dockerfile/#cmd) 指令有两种写法：
✅ **Exec** 形式：
@@ -254,11 +254,11 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80"]
CMD fastapi run app/main.py --port 80
```
-务必使用**exec** 形式，以确保 FastAPI 可以优雅停机并触发[生命周期事件](../advanced/events.md){.internal-link target=_blank}。
+务必使用**exec** 形式，以确保 FastAPI 可以优雅停机并触发[生命周期事件](../advanced/events.md)。
-你可以在 Docker 文档（Shell 与 Exec 形式）中了解更多。
+你可以在 [Docker 文档（Shell 与 Exec 形式）](https://docs.docker.com/reference/dockerfile/#shell-and-exec-form)中了解更多。
-在使用 `docker compose` 时这一点尤为明显。更多技术细节参见该 FAQ：为什么我的服务需要 10 秒才能重新创建或停止？
+在使用 `docker compose` 时这一点尤为明显。更多技术细节参见该 FAQ：[为什么我的服务需要 10 秒才能重新创建或停止？](https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop)
#### 目录结构 { #directory-structure }
@@ -352,7 +352,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage
## 检查一下 { #check-it }
-你应该能在容器暴露的 URL 访问它，例如：http://192.168.99.100/items/5?q=somequery 或 http://127.0.0.1/items/5?q=somequery（或其他等价地址，取决于你的 Docker 主机）。
+你应该能在容器暴露的 URL 访问它，例如：[http://192.168.99.100/items/5?q=somequery](http://192.168.99.100/items/5?q=somequery) 或 [http://127.0.0.1/items/5?q=somequery](http://127.0.0.1/items/5?q=somequery)（或其他等价地址，取决于你的 Docker 主机）。
你会看到类似内容：
@@ -362,17 +362,17 @@ $ docker run -d --name mycontainer -p 80:80 myimage
## 交互式 API 文档 { #interactive-api-docs }
-现在你可以访问 http://192.168.99.100/docs 或 http://127.0.0.1/docs（或其他等价地址，取决于你的 Docker 主机）。
+现在你可以访问 [http://192.168.99.100/docs](http://192.168.99.100/docs) 或 [http://127.0.0.1/docs](http://127.0.0.1/docs)（或其他等价地址，取决于你的 Docker 主机）。
-你将看到自动生成的交互式 API 文档（由 Swagger UI 提供）：
+你将看到自动生成的交互式 API 文档（由 [Swagger UI](https://github.com/swagger-api/swagger-ui) 提供）：
## 备选 API 文档 { #alternative-api-docs }
-你还可以访问 http://192.168.99.100/redoc 或 http://127.0.0.1/redoc（或其他等价地址，取决于你的 Docker 主机）。
+你还可以访问 [http://192.168.99.100/redoc](http://192.168.99.100/redoc) 或 [http://127.0.0.1/redoc](http://127.0.0.1/redoc)（或其他等价地址，取决于你的 Docker 主机）。
-你将看到备选的自动文档（由 ReDoc 提供）：
+你将看到备选的自动文档（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）：
@@ -413,7 +413,7 @@ CMD ["fastapi", "run", "main.py", "--port", "80"]
## 部署概念 { #deployment-concepts }
-我们再从容器的角度讨论一些相同的[部署概念](concepts.md){.internal-link target=_blank}。
+我们再从容器的角度讨论一些相同的[部署概念](concepts.md)。
容器主要是简化应用**构建与部署**流程的工具，但它们并不强制采用某种特定方式来处理这些**部署概念**，可选策略有多种。
@@ -432,7 +432,7 @@ CMD ["fastapi", "run", "main.py", "--port", "80"]
如果我们只关注 FastAPI 应用的**容器镜像**（以及后续运行的**容器**），HTTPS 通常由**外部**的其他工具处理。
-它可以是另一个容器，例如使用 Traefik，处理 **HTTPS** 并**自动**获取**证书**。
+它可以是另一个容器，例如使用 [Traefik](https://traefik.io/)，处理 **HTTPS** 并**自动**获取**证书**。
/// tip | 提示
@@ -558,7 +558,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"]
/// info | 信息
-如果你使用 Kubernetes，这通常会是一个 Init Container。
+如果你使用 Kubernetes，这通常会是一个 [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)。
///
@@ -570,7 +570,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"]
### 基础 Docker 镜像 { #base-docker-image }
-曾经有一个官方的 FastAPI Docker 镜像：tiangolo/uvicorn-gunicorn-fastapi。但它现在已被弃用。⛔️
+曾经有一个官方的 FastAPI Docker 镜像：[tiangolo/uvicorn-gunicorn-fastapi](https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker)。但它现在已被弃用。⛔️
你大概率**不应该**使用这个基础镜像（或任何其它类似的镜像）。
@@ -600,7 +600,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"]
## 使用 `uv` 的 Docker 镜像 { #docker-image-with-uv }
-如果你使用 uv 来安装和管理项目，可以参考他们的 uv Docker 指南。
+如果你使用 [uv](https://github.com/astral-sh/uv) 来安装和管理项目，可以参考他们的 [uv Docker 指南](https://docs.astral.sh/uv/guides/integration/docker/)。
## 回顾 { #recap }
diff --git a/docs/zh/docs/deployment/fastapicloud.md b/docs/zh/docs/deployment/fastapicloud.md
index 0239a1512..d43870993 100644
--- a/docs/zh/docs/deployment/fastapicloud.md
+++ b/docs/zh/docs/deployment/fastapicloud.md
@@ -1,6 +1,6 @@
# FastAPI Cloud { #fastapi-cloud }
-你可以用**一条命令**将你的 FastAPI 应用部署到 FastAPI Cloud，如果还没有，去加入候补名单吧。🚀
+你可以用**一条命令**将你的 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)，如果还没有，去加入候补名单吧。🚀
## 登录 { #login }
@@ -40,7 +40,7 @@ Deploying to FastAPI Cloud...
## 关于 FastAPI Cloud { #about-fastapi-cloud }
-**FastAPI Cloud** 由 **FastAPI** 背后的作者与团队打造。
+**[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 背后的作者与团队打造。
它让你以最小的投入完成 API 的**构建**、**部署**与**访问**。
diff --git a/docs/zh/docs/deployment/https.md b/docs/zh/docs/deployment/https.md
index 591707f6d..916fb46da 100644
--- a/docs/zh/docs/deployment/https.md
+++ b/docs/zh/docs/deployment/https.md
@@ -10,7 +10,7 @@
///
-要从用户的视角**了解 HTTPS 的基础知识**，请查看 https://howhttps.works/。
+要从用户的视角**了解 HTTPS 的基础知识**，请查看 [https://howhttps.works/](https://howhttps.works/)。
现在，从**开发人员的视角**，在了解 HTTPS 时需要记住以下几点：
@@ -28,13 +28,13 @@
* **默认情况下**，这意味着你**每个 IP 地址只能拥有一个 HTTPS 证书**。
* 无论你的服务器有多大，或者服务器上的每个应用程序有多小。
* 不过，对此有一个**解决方案**。
-* **TLS** 协议（在 HTTP 之下的 TCP 层处理加密的协议）有一个**扩展**，称为 **SNI**。
+* **TLS** 协议（在 HTTP 之下的 TCP 层处理加密的协议）有一个**扩展**，称为 **[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication)**。
* SNI 扩展允许一台服务器（具有 **单个 IP 地址**）拥有 **多个 HTTPS 证书** 并提供 **多个 HTTPS 域名/应用程序**。
* 为此，服务器上会有**单独**的一个组件（程序）侦听**公共 IP 地址**，这个组件必须拥有服务器中的**所有 HTTPS 证书**。
* **获得安全连接后**，通信协议**仍然是HTTP**。
* 内容是 **加密过的**，即使它们是通过 **HTTP 协议** 发送的。
-通常的做法是在服务器上运行**一个程序/HTTP 服务器**并**管理所有 HTTPS 部分**：接收**加密的 HTTPS 请求**， 将 **解密的 HTTP 请求** 发送到在同一服务器中运行的实际 HTTP 应用程序（在本例中为 **FastAPI** 应用程序），从应用程序中获取 **HTTP 响应**， 使用适当的 **HTTPS 证书**对其进行加密并使用 **HTTPS** 将其发送回客户端。 此服务器通常被称为 **TLS 终止代理(TLS Termination Proxy)**。
+通常的做法是在服务器上运行**一个程序/HTTP 服务器**并**管理所有 HTTPS 部分**：接收**加密的 HTTPS 请求**， 将 **解密的 HTTP 请求** 发送到在同一服务器中运行的实际 HTTP 应用程序（在本例中为 **FastAPI** 应用程序），从应用程序中获取 **HTTP 响应**， 使用适当的 **HTTPS 证书**对其进行加密并使用 **HTTPS** 将其发送回客户端。 此服务器通常被称为 **[TLS 终止代理(TLS Termination Proxy)](https://en.wikipedia.org/wiki/TLS_termination_proxy)**。
你可以用作 TLS 终止代理的一些选项包括：
@@ -49,7 +49,7 @@
过去，获得这些证书的过程非常繁琐，需要大量的文书工作，而且证书非常昂贵。
-但随后 **Let's Encrypt** 创建了。
+但随后 **[Let's Encrypt](https://letsencrypt.org/)** 创建了。
它是 Linux 基金会的一个项目。 它以自动方式免费提供 **HTTPS 证书**。 这些证书可以使用所有符合标准的安全加密，并且有效期很短（大约 3 个月），因此**安全性实际上更好**，因为它们的生命周期缩短了。
@@ -201,9 +201,9 @@ TLS 终止代理将使用协商好的加密算法**解密请求**，并将**（
这些代理请求头包括：
-* X-Forwarded-For
-* X-Forwarded-Proto
-* X-Forwarded-Host
+* [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For)
+* [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto)
+* [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host)
///
@@ -219,7 +219,7 @@ TLS 终止代理将使用协商好的加密算法**解密请求**，并将**（
/// tip | 提示
-你可以在文档中了解更多：[在代理之后 - 启用代理转发请求头](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank}
+你可以在文档中了解更多：[在代理之后 - 启用代理转发请求头](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers)
///
diff --git a/docs/zh/docs/deployment/index.md b/docs/zh/docs/deployment/index.md
index 47dcede65..fa10019ad 100644
--- a/docs/zh/docs/deployment/index.md
+++ b/docs/zh/docs/deployment/index.md
@@ -16,7 +16,7 @@
你可以使用一些工具自行**部署服务器**，你也可以使用能为你完成部分工作的**云服务**，或其他可能的选项。
-例如，我们（FastAPI 团队）构建了 **FastAPI Cloud**，让将 FastAPI 应用部署到云端尽可能流畅，并且保持与使用 FastAPI 开发时相同的开发者体验。
+例如，我们（FastAPI 团队）构建了 [**FastAPI Cloud**](https://fastapicloud.com)，让将 FastAPI 应用部署到云端尽可能流畅，并且保持与使用 FastAPI 开发时相同的开发者体验。
我将向你展示在部署 **FastAPI** 应用程序时你可能应该记住的一些主要概念（尽管其中大部分适用于任何其他类型的 Web 应用程序）。
diff --git a/docs/zh/docs/deployment/manually.md b/docs/zh/docs/deployment/manually.md
index f519c1e87..c440aa924 100644
--- a/docs/zh/docs/deployment/manually.md
+++ b/docs/zh/docs/deployment/manually.md
@@ -52,11 +52,11 @@ FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称
除此之外，还有其他一些可选的 ASGI 服务器，例如：
-* Uvicorn：高性能 ASGI 服务器。
-* Hypercorn：与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。
-* Daphne：为 Django Channels 构建的 ASGI 服务器。
-* Granian：基于 Rust 的 HTTP 服务器，专为 Python 应用设计。
-* NGINX Unit：NGINX Unit 是一个轻量级且灵活的 Web 应用运行时环境。
+* [Uvicorn](https://www.uvicorn.dev/): 高性能 ASGI 服务器。
+* [Hypercorn](https://hypercorn.readthedocs.io/): 与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。
+* [Daphne](https://github.com/django/daphne): 为 Django Channels 构建的 ASGI 服务器。
+* [Granian](https://github.com/emmett-framework/granian): 基于 Rust 的 HTTP 服务器，专为 Python 应用设计。
+* [NGINX Unit](https://unit.nginx.org/howto/fastapi/): NGINX Unit 是一个轻量级且灵活的 Web 应用运行时环境。
## 服务器主机和服务器程序 { #server-machine-and-server-program }
@@ -74,7 +74,7 @@ FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称
不过，您也可以手动安装 ASGI 服务器。
-请确保您创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再安装服务器应用程序。
+请确保您创建并激活一个[虚拟环境](../virtual-environments.md)，然后再安装服务器应用程序。
例如，要安装 Uvicorn，可以运行以下命令：
diff --git a/docs/zh/docs/deployment/server-workers.md b/docs/zh/docs/deployment/server-workers.md
index 2bbd5d9b6..add83ac1a 100644
--- a/docs/zh/docs/deployment/server-workers.md
+++ b/docs/zh/docs/deployment/server-workers.md
@@ -13,13 +13,13 @@
部署应用程序时，您可能希望进行一些**进程复制**，以利用**多核** CPU 并能够处理更多请求。
-正如您在上一章有关[部署概念](concepts.md){.internal-link target=_blank}中看到的，您可以使用多种策略。
+正如您在上一章有关[部署概念](concepts.md)中看到的，您可以使用多种策略。
在本章节中，我将向您展示如何使用 `fastapi` 命令或直接使用 `uvicorn` 命令以**多工作进程模式**运行 **Uvicorn**。
/// info | 信息
-如果您正在使用容器，例如 Docker 或 Kubernetes，我将在下一章中告诉您更多相关信息：[容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank}。
+如果您正在使用容器，例如 Docker 或 Kubernetes，我将在下一章中告诉您更多相关信息：[容器中的 FastAPI - Docker](docker.md)。
比较特别的是，在 **Kubernetes** 环境中运行时，您通常**不需要**使用多个工作进程，而是**每个容器运行一个 Uvicorn 进程**。不过，我会在本章节的后续部分详细介绍这一点。
@@ -126,7 +126,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
## 容器和 Docker { #containers-and-docker }
-在关于 [容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank} 的下一章中，我将介绍一些可用于处理其他**部署概念**的策略。
+在关于 [容器中的 FastAPI - Docker](docker.md) 的下一章中，我将介绍一些可用于处理其他**部署概念**的策略。
我将向您展示如何**从零开始构建自己的镜像**，以运行一个单独的 Uvicorn 进程。这个过程相对简单，并且在使用 **Kubernetes** 等分布式容器管理系统时，这通常是您需要采取的方法。
diff --git a/docs/zh/docs/deployment/versions.md b/docs/zh/docs/deployment/versions.md
index 23c37f3b5..13af70556 100644
--- a/docs/zh/docs/deployment/versions.md
+++ b/docs/zh/docs/deployment/versions.md
@@ -4,7 +4,7 @@
经常添加新功能，定期修复错误，并且代码仍在持续改进。
-这就是为什么当前版本仍然是`0.x.x`，这反映出每个版本都可能有Breaking changes。 这遵循语义版本控制的约定。
+这就是为什么当前版本仍然是`0.x.x`，这反映出每个版本都可能有Breaking changes。 这遵循[语义版本控制](https://semver.org/)的约定。
你现在就可以使用 **FastAPI** 创建生产环境应用程序（你可能已经这样做了一段时间），你只需确保使用的版本可以与其余代码正确配合即可。
@@ -34,7 +34,7 @@ fastapi[standard]>=0.112.0,<0.113.0
## 可用版本 { #available-versions }
-你可以在[发行说明](../release-notes.md){.internal-link target=_blank}中查看可用版本（例如查看当前最新版本）。
+你可以在[发行说明](../release-notes.md)中查看可用版本（例如查看当前最新版本）。
## 关于版本 { #about-versions }
@@ -66,7 +66,7 @@ fastapi>=0.45.0,<0.46.0
你应该为你的应用程序添加测试。
-使用 **FastAPI** 编写测试非常简单（感谢 Starlette），请参考文档：[测试](../tutorial/testing.md){.internal-link target=_blank}
+使用 **FastAPI** 编写测试非常简单（感谢 Starlette），请参考文档：[测试](../tutorial/testing.md)
添加测试后，你可以将 **FastAPI** 版本升级到更新版本，并通过运行测试来确保所有代码都能正常工作。
diff --git a/docs/zh/docs/environment-variables.md b/docs/zh/docs/environment-variables.md
index 8729a6306..3a90ecde6 100644
--- a/docs/zh/docs/environment-variables.md
+++ b/docs/zh/docs/environment-variables.md
@@ -65,7 +65,7 @@ print(f"Hello {name} from Python")
/// tip | 提示
-第二个参数是 `os.getenv()` 的默认返回值。
+第二个参数是 [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) 的默认返回值。
如果没有提供，默认值为 `None`，这里我们提供 `"World"` 作为默认值。
@@ -153,7 +153,7 @@ Hello World from Python
/// tip | 提示
-你可以在 The Twelve-Factor App: 配置中了解更多信息。
+你可以在 [The Twelve-Factor App: 配置](https://12factor.net/config) 中了解更多信息。
///
@@ -163,7 +163,7 @@ Hello World from Python
这意味着从环境变量中读取的**任何值**在 Python 中都将是一个 `str`，任何类型转换或验证都必须在代码中完成。
-你将在[高级用户指南 - 设置和环境变量](./advanced/settings.md){.internal-link target=_blank}中了解更多关于使用环境变量处理**应用程序设置**的信息。
+你将在[高级用户指南 - 设置和环境变量](./advanced/settings.md)中了解更多关于使用环境变量处理**应用程序设置**的信息。
## `PATH` 环境变量 { #path-environment-variable }
@@ -285,13 +285,13 @@ $ C:\opt\custompython\bin\python
////
-当学习[虚拟环境](virtual-environments.md){.internal-link target=_blank}时，这些信息将会很有用。
+当学习[虚拟环境](virtual-environments.md)时，这些信息将会很有用。
## 结论 { #conclusion }
通过这个教程，你应该对**环境变量**是什么以及如何在 Python 中使用它们有了基本的了解。
-你也可以在环境变量 - 维基百科中了解更多关于它们的信息。
+你也可以在[环境变量 - 维基百科](https://en.wikipedia.org/wiki/Environment_variable)中了解更多关于它们的信息。
在许多情况下，环境变量的用途和适用性并不是很明显。但是在开发过程中，它们会在许多不同的场景中出现，因此了解它们是很有必要的。
diff --git a/docs/zh/docs/fastapi-cli.md b/docs/zh/docs/fastapi-cli.md
index 4d3b51a57..151b7e61e 100644
--- a/docs/zh/docs/fastapi-cli.md
+++ b/docs/zh/docs/fastapi-cli.md
@@ -1,15 +1,15 @@
# FastAPI CLI { #fastapi-cli }
-**FastAPI CLI** 是一个命令行程序，你可以用它来部署和运行你的 FastAPI 应用程序，管理你的 FastAPI 项目，等等。
+**FastAPI CLI** 是一个命令行程序，你可以用它来部署和运行你的 FastAPI 应用、管理 FastAPI 项目，等等。
-当你安装 FastAPI 时（例如使用 `pip install "fastapi[standard]"`），会包含一个名为 `fastapi-cli` 的软件包，该软件包在终端中提供 `fastapi` 命令。
+当你安装 FastAPI（例如使用 `pip install "fastapi[standard]"`）时，会附带一个可以在终端中运行的命令行程序。
-要在开发环境中运行你的 FastAPI 应用，你可以使用 `fastapi dev` 命令：
+要在开发环境中运行你的 FastAPI 应用，可以使用 `fastapi dev` 命令：
```console
-$ fastapi dev main.py
+$ fastapi dev
FastAPI Starting development server 🚀
@@ -46,13 +46,66 @@ $ fastapi dev Uvicorn，这是一个高性能、适用于生产环境的 ASGI 服务器。😎
+在内部，**FastAPI CLI** 使用 [Uvicorn](https://www.uvicorn.dev)，这是一个高性能、适用于生产环境的 ASGI 服务器。😎
+
+`fastapi` CLI 会尝试自动检测要运行的 FastAPI 应用，默认假设它是文件 `main.py` 中名为 `app` 的对象（或少数其他变体）。
+
+但你也可以显式配置要使用的应用。
+
+## 在 `pyproject.toml` 中配置应用的 `entrypoint` { #configure-the-app-entrypoint-in-pyproject-toml }
+
+你可以在 `pyproject.toml` 文件中配置应用的位置，例如：
+
+```toml
+[tool.fastapi]
+entrypoint = "main:app"
+```
+
+这个 `entrypoint` 会告诉 `fastapi` 命令按如下方式导入应用：
+
+```python
+from main import app
+```
+
+如果你的代码结构如下：
+
+```
+.
+├── backend
+│ ├── main.py
+│ ├── __init__.py
+```
+
+那么你可以将 `entrypoint` 设置为：
+
+```toml
+[tool.fastapi]
+entrypoint = "backend.main:app"
+```
+
+这等价于：
+
+```python
+from backend.main import app
+```
+
+### 带路径的 `fastapi dev` { #fastapi-dev-with-path }
+
+你也可以把文件路径传给 `fastapi dev` 命令，它会猜测要使用的 FastAPI 应用对象：
+
+```console
+$ fastapi dev main.py
+```
+
+但每次运行 `fastapi` 命令都需要记得传入正确的路径。
+
+另外，其他工具可能找不到它，例如 [VS Code 扩展](editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com)，因此推荐在 `pyproject.toml` 中使用 `entrypoint`。
## `fastapi dev` { #fastapi-dev }
@@ -70,6 +123,6 @@ FastAPI CLI 接收你的 Python 程序路径（例如 `main.py`），自动检
/// tip | 提示
-你可以在[部署文档](deployment/index.md){.internal-link target=_blank}中了解更多。
+你可以在[部署文档](deployment/index.md)中了解更多。
///
diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md
index 1414f7c6f..ad6b77f74 100644
--- a/docs/zh/docs/features.md
+++ b/docs/zh/docs/features.md
@@ -6,8 +6,8 @@
### 基于开放标准 { #based-on-open-standards }
-* 用于创建 API 的 OpenAPI，包含对路径 操作、参数、请求体、安全等的声明。
-* 使用 JSON Schema 自动生成数据模型文档（因为 OpenAPI 本身就是基于 JSON Schema 的）。
+* [**OpenAPI**](https://github.com/OAI/OpenAPI-Specification) 用于创建 API，包含对路径 操作、参数、请求体、安全等的声明。
+* 使用 [**JSON Schema**](https://json-schema.org/) 自动生成数据模型文档（因为 OpenAPI 本身就是基于 JSON Schema 的）。
* 经过了缜密的研究后围绕这些标准而设计。并非狗尾续貂。
* 这也允许了在很多语言中自动**生成客户端代码**。
@@ -15,11 +15,11 @@
交互式 API 文档以及具探索性 web 界面。因为该框架是基于 OpenAPI，所以有很多可选项，FastAPI 默认自带两个交互式 API 文档。
-* Swagger UI，可交互式操作，能在浏览器中直接调用和测试你的 API。
+* [**Swagger UI**](https://github.com/swagger-api/swagger-ui)，可交互式操作，能在浏览器中直接调用和测试你的 API。
-* 另外的 API 文档：ReDoc
+* 另外的 API 文档：[**ReDoc**](https://github.com/Rebilly/ReDoc)
@@ -27,7 +27,7 @@
全部都基于标准的 **Python 类型** 声明（感谢 Pydantic）。没有新的语法需要学习。只需要标准的现代 Python。
-如果你需要2分钟来学习如何使用 Python 类型（即使你不使用 FastAPI），看看这个简短的教程：[Python Types](python-types.md){.internal-link target=_blank}。
+如果你需要2分钟来学习如何使用 Python 类型（即使你不使用 FastAPI），看看这个简短的教程：[Python 类型](python-types.md)。
编写带有类型标注的标准 Python：
@@ -76,7 +76,7 @@ my_second_user: User = User(**second_user_data)
整个框架都被设计得易于使用且直观，所有的决定都在开发之前就在多个编辑器上进行了测试，来确保最佳的开发体验。
-在最近的 Python 开发者调查中，我们能看到 被使用最多的功能是“自动补全”。
+在 Python 开发者调查中，我们能看到[被使用最多的功能之一是“自动补全”](https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features)。
整个 **FastAPI** 框架就是基于这一点的。任何地方都可以进行自动补全。
@@ -84,11 +84,11 @@ my_second_user: User = User(**second_user_data)
在这里，你的编辑器可能会这样帮助你：
-* 在 Visual Studio Code 中:
+* 在 [Visual Studio Code](https://code.visualstudio.com/) 中:
-* 在 PyCharm 中:
+* 在 [PyCharm](https://www.jetbrains.com/pycharm/) 中:
@@ -125,7 +125,7 @@ my_second_user: User = User(**second_user_data)
OpenAPI 中定义的安全模式，包括：
* HTTP 基本认证。
-* **OAuth2**（也使用 **JWT tokens**）。在 [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}查看教程。
+* **OAuth2**（也使用 **JWT tokens**）。在 [使用 JWT 的 OAuth2](tutorial/security/oauth2-jwt.md) 查看教程。
* API 密钥，在:
* 请求头。
* 查询参数。
@@ -142,7 +142,7 @@ FastAPI 有一个使用非常简单，但是非常强大的Starlette 完全兼容（并基于）。所以，你有的其他的 Starlette 代码也能正常工作。`FastAPI` 实际上是 `Starlette` 的一个子类。所以，如果你已经知道或者使用 Starlette，大部分的功能会以相同的方式工作。
+**FastAPI** 和 [**Starlette**](https://www.starlette.dev/) 完全兼容（并基于）。所以，你有的其他的 Starlette 代码也能正常工作。`FastAPI` 实际上是 `Starlette` 的一个子类。所以，如果你已经知道或者使用 Starlette，大部分的功能会以相同的方式工作。
通过 **FastAPI** 你可以获得所有 **Starlette** 的特性（FastAPI 就像加强版的 Starlette）：
-* 令人惊叹的性能。它是 Python 可用的最快的框架之一，和 **NodeJS** 及 **Go** 相当。
+* 令人惊叹的性能。它是[Python 可用的最快的框架之一，和 **NodeJS** 及 **Go** 相当](https://github.com/encode/starlette#performance)。
* **支持 WebSocket**。
* 进程内后台任务。
* Startup 和 shutdown 事件。
@@ -176,7 +176,7 @@ FastAPI 有一个使用非常简单，但是非常强大的发推谈谈 **FastAPI**，告诉我和大家你为什么喜欢它。🎉
+[发推谈谈 **FastAPI**](https://x.com/compose/tweet?text=I'm loving @fastapi because... https://github.com/fastapi/fastapi)，告诉我和大家你为什么喜欢它。🎉
我很高兴听到 **FastAPI** 的使用情况、你喜欢它的哪些点、你在哪个项目/公司使用它，等等。
## 为 FastAPI 投票 { #vote-for-fastapi }
-* 在 Slant 上为 **FastAPI** 投票。
-* 在 AlternativeTo 上为 **FastAPI** 投票。
-* 在 StackShare 上标注你在用 **FastAPI**。
+* [在 Slant 上为 **FastAPI** 投票](https://www.slant.co/options/34241/~fastapi-review)。
+* [在 AlternativeTo 上为 **FastAPI** 投票](https://alternativeto.net/software/fastapi/about/)。
+* [在 StackShare 上标注你在用 **FastAPI**](https://stackshare.io/pypi-fastapi)。
## 在 GitHub 上帮别人解答问题 { #help-others-with-questions-in-github }
你可以尝试在以下地方帮助他人解答问题：
-* GitHub Discussions
-* GitHub Issues
+* [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered)
+* [GitHub Issues](https://github.com/fastapi/fastapi/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aquestion+-label%3Aanswered+)
很多情况下，你也许已经知道这些问题的答案了。🤓
-如果你帮助了很多人解答问题，你会成为官方的 [FastAPI 专家](fastapi-people.md#fastapi-experts){.internal-link target=_blank}。🎉
+如果你帮助了很多人解答问题，你会成为官方的 [FastAPI 专家](fastapi-people.md#fastapi-experts)。🎉
只要记住，最重要的一点是：尽量友善。人们带着挫败感而来，很多时候他们的提问方式并不理想，但请尽你所能地友好对待。🤗
@@ -104,7 +104,7 @@
很多时候他们只会粘贴一小段代码，但这不足以**复现问题**。
-* 你可以请他们提供一个可最小复现的示例，你可以**复制粘贴**并在本地运行，看到与他们相同的错误或行为，或者更好地理解他们的用例。
+* 你可以请他们提供一个[可最小复现的示例](https://stackoverflow.com/help/minimal-reproducible-example)，你可以**复制粘贴**并在本地运行，看到与他们相同的错误或行为，或者更好地理解他们的用例。
* 如果你非常热心，你也可以尝试仅根据问题描述自己**构造一个示例**。不过要记住，这可能会花很多时间，通常先请他们澄清问题会更好。
@@ -124,7 +124,7 @@
## 关注 GitHub 资源库 { #watch-the-github-repository }
-你可以在 GitHub 上「关注」FastAPI（点击右上角的「watch」按钮）：https://github.com/fastapi/fastapi。👀
+你可以在 GitHub 上「关注」FastAPI（点击右上角的「watch」按钮）：[https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi)。👀
如果你选择「Watching」而非「Releases only」，当有人创建新的 issue 或问题时你会收到通知。你也可以指定只通知新 issues、discussions、PR 等。
@@ -132,7 +132,7 @@
## 提问 { #ask-questions }
-你可以在 GitHub 资源库中创建一个新问题（Question），例如：
+你可以在 GitHub 资源库中[创建一个新问题（Question）](https://github.com/fastapi/fastapi/discussions/new?category=questions)，例如：
* 提出一个**问题**或关于某个**问题**的求助。
* 建议一个新的**功能**。
@@ -195,12 +195,12 @@
## 创建 Pull Request { #create-a-pull-request }
-你可以通过 Pull Request 为源代码[做贡献](contributing.md){.internal-link target=_blank}，例如：
+你可以通过 Pull Request 为源代码[做贡献](contributing.md)，例如：
* 修正文档中的一个错别字。
-* 通过编辑这个文件分享你创建或发现的关于 FastAPI 的文章、视频或播客。
+* 通过[编辑这个文件](https://github.com/fastapi/fastapi/edit/master/docs/en/data/external_links.yml)分享你创建或发现的关于 FastAPI 的文章、视频或播客。
* 请确保把你的链接添加到相应区块的开头。
-* 帮助把[文档翻译](contributing.md#translations){.internal-link target=_blank}成你的语言。
+* 帮助把[文档翻译](contributing.md#translations)成你的语言。
* 你也可以审阅他人创建的翻译。
* 提议新增文档章节。
* 修复现有 issue/bug。
@@ -217,8 +217,8 @@
你现在就能做的主要事情有：
-* [在 GitHub 上帮别人解答问题](#help-others-with-questions-in-github){.internal-link target=_blank}（见上面的章节）。
-* [审阅 Pull Request](#review-pull-requests){.internal-link target=_blank}（见上面的章节）。
+* [在 GitHub 上帮别人解答问题](#help-others-with-questions-in-github)（见上面的章节）。
+* [审阅 Pull Request](#review-pull-requests)（见上面的章节）。
这两项工作是**最耗时**的。这也是维护 FastAPI 的主要工作。
@@ -226,11 +226,11 @@
## 加入聊天 { #join-the-chat }
-加入 👥 Discord 聊天服务器 👥，和 FastAPI 社区的小伙伴们一起交流。
+加入 👥 [Discord 聊天服务器](https://discord.gg/VQjSZaeJmf) 👥，和 FastAPI 社区的小伙伴们一起交流。
/// tip | 提示
-关于提问，请在 GitHub Discussions 中发布，这样更有机会得到 [FastAPI 专家](fastapi-people.md#fastapi-experts){.internal-link target=_blank} 的帮助。
+关于提问，请在 [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/new?category=questions) 中发布，这样更有机会得到 [FastAPI 专家](fastapi-people.md#fastapi-experts) 的帮助。
聊天仅用于其他日常交流。
@@ -242,13 +242,13 @@
在 GitHub 中，模板会引导你写出恰当的问题，从而更容易获得好的回答，甚至在提问之前就能自己解决。而且在 GitHub 里，我能尽量确保最终回复每个问题，即使这需要一些时间。对聊天系统来说，我个人做不到这一点。😅
-聊天系统中的对话也不像 GitHub 那样容易搜索，因此问答可能在聊天中淹没。而且只有在 GitHub 中的问答才会计入成为 [FastAPI 专家](fastapi-people.md#fastapi-experts){.internal-link target=_blank} 的贡献，所以你在 GitHub 上更可能获得关注。
+聊天系统中的对话也不像 GitHub 那样容易搜索，因此问答可能在聊天中淹没。而且只有在 GitHub 中的问答才会计入成为 [FastAPI 专家](fastapi-people.md#fastapi-experts) 的贡献，所以你在 GitHub 上更可能获得关注。
另一方面，聊天系统里有成千上万的用户，你几乎随时都能在那里找到聊得来的人。😄
## 赞助作者 { #sponsor-the-author }
-如果你的**产品/公司**依赖或与 **FastAPI** 相关，并且你想触达它的用户，你可以通过 GitHub sponsors 赞助作者（我）。根据赞助层级，你还可能获得一些额外福利，比如在文档中展示徽章。🎁
+如果你的**产品/公司**依赖或与 **FastAPI** 相关，并且你想触达它的用户，你可以通过 [GitHub sponsors](https://github.com/sponsors/tiangolo) 赞助作者（我）。根据赞助层级，你还可能获得一些额外福利，比如在文档中展示徽章。🎁
---
diff --git a/docs/zh/docs/history-design-future.md b/docs/zh/docs/history-design-future.md
index 00945eab5..429eb8db0 100644
--- a/docs/zh/docs/history-design-future.md
+++ b/docs/zh/docs/history-design-future.md
@@ -1,6 +1,6 @@
# 历史、设计、未来 { #history-design-and-future }
-不久前，曾有 **FastAPI** 用户问过：
+不久前，[曾有 **FastAPI** 用户问过](https://github.com/fastapi/fastapi/issues/3#issuecomment-454956920)：
> 这个项目有怎样的历史？好像它只用了几周就从默默无闻变得众所周知...
@@ -14,7 +14,7 @@
**FastAPI** 其实只是延续了这些前辈的历史。
-正如[备选方案](alternatives.md){.internal-link target=_blank}一章所述：
+正如[备选方案](alternatives.md)一章所述：
没有大家之前所做的工作，**FastAPI** 就不会存在。 @@ -42,7 +42,7 @@ 同时，我还在最流行的 Python 代码编辑器中测试了很多思路，包括 PyCharm、VS Code、基于 Jedi 的编辑器。 -根据最新 Python 开发者调研报告显示，这几种编辑器覆盖了约 80% 的用户。 +根据最新 [Python 开发者调研报告](https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools)显示，这几种编辑器覆盖了约 80% 的用户。 也就是说，**FastAPI** 针对差不多 80% 的 Python 开发者使用的编辑器进行了测试，而且其它大多数编辑器的工作方式也与之类似，因此，**FastAPI** 的优势几乎能在所有编辑器上体现。 @@ -52,11 +52,11 @@ ## 需求项 { #requirements } -经过测试多种备选方案，我最终决定使用 **Pydantic**，并充分利用它的优势。 +经过测试多种备选方案，我最终决定使用 [**Pydantic**](https://docs.pydantic.dev/)，并充分利用它的优势。 我甚至为它做了不少贡献，让它完美兼容了 JSON Schema，支持多种方式定义约束声明，并基于多个编辑器，改进了它对编辑器支持（类型检查、自动补全）。 -在开发期间，我还为 **Starlette** 做了不少贡献，这是另一个关键需求项。 +在开发期间，我还为 [**Starlette**](https://www.starlette.dev/) 做了不少贡献，这是另一个关键需求项。 ## 开发 { #development } @@ -74,4 +74,4 @@ **FastAPI** 前景光明。 -在此，我们衷心感谢[您的帮助](help-fastapi.md){.internal-link target=_blank}。 +在此，我们衷心感谢[你的帮助](help-fastapi.md)。 diff --git a/docs/zh/docs/how-to/authentication-error-status-code.md b/docs/zh/docs/how-to/authentication-error-status-code.md index 466b90e15..6f8c0a67c 100644 --- a/docs/zh/docs/how-to/authentication-error-status-code.md +++ b/docs/zh/docs/how-to/authentication-error-status-code.md @@ -2,7 +2,7 @@ 在 FastAPI `0.122.0` 版本之前，当内置的安全工具在认证失败后向客户端返回错误时，会使用 HTTP 状态码 `403 Forbidden`。 -从 FastAPI `0.122.0` 版本开始，它们改用更合适的 HTTP 状态码 `401 Unauthorized`，并在响应中返回合理的 `WWW-Authenticate` 头，遵循 HTTP 规范，RFC 7235、RFC 9110。 +从 FastAPI `0.122.0` 版本开始，它们改用更合适的 HTTP 状态码 `401 Unauthorized`，并在响应中返回合理的 `WWW-Authenticate` 头，遵循 HTTP 规范，[RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-3.1)、[RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized)。 但如果由于某些原因你的客户端依赖旧行为，你可以在你的安全类中重写方法 `make_not_authenticated_error` 来回退到旧行为。 diff --git a/docs/zh/docs/how-to/conditional-openapi.md b/docs/zh/docs/how-to/conditional-openapi.md index d26b5f3bd..b0c5d521c 100644 --- a/docs/zh/docs/how-to/conditional-openapi.md +++ b/docs/zh/docs/how-to/conditional-openapi.md @@ -10,7 +10,7 @@ 如果你的代码里有安全漏洞，它仍然存在。 -隐藏文档只会让理解如何与 API 交互变得更困难，也可能让你在生产环境中调试更困难。这大体上可以被视为一种 通过隐藏实现安全 的做法。 +隐藏文档只会让理解如何与 API 交互变得更困难，也可能让你在生产环境中调试更困难。这大体上可以被视为一种 [通过隐藏实现安全](https://en.wikipedia.org/wiki/Security_through_obscurity) 的做法。 如果你想保护你的 API，有很多更好的措施，例如： diff --git a/docs/zh/docs/how-to/configure-swagger-ui.md b/docs/zh/docs/how-to/configure-swagger-ui.md index bf2624657..3dbc54911 100644 --- a/docs/zh/docs/how-to/configure-swagger-ui.md +++ b/docs/zh/docs/how-to/configure-swagger-ui.md @@ -1,10 +1,10 @@ # 配置 Swagger UI { #configure-swagger-ui } -你可以配置一些额外的 Swagger UI 参数. +你可以配置一些额外的 [Swagger UI 参数](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)。 如果需要配置它们，可以在创建 `FastAPI()` 应用对象时或调用 `get_swagger_ui_html()` 函数时传递 `swagger_ui_parameters` 参数。 -`swagger_ui_parameters` 接受一个直接传递给 Swagger UI的字典，包含配置参数键值对。 +`swagger_ui_parameters` 接受一个字典，该字典会直接传递给 Swagger UI。 FastAPI会将这些配置转换为 **JSON**，使其与 JavaScript 兼容，因为这是 Swagger UI 需要的。 @@ -50,7 +50,7 @@ FastAPI 包含了一些默认配置参数，适用于大多数用例。 ## 其他 Swagger UI 参数 { #other-swagger-ui-parameters } -查看所有其他可用的配置，请阅读 Swagger UI 参数文档。 +查看所有其他可用的配置，请阅读官方的 [Swagger UI 参数文档](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)。 ## JavaScript-only 配置 { #javascript-only-settings } diff --git a/docs/zh/docs/how-to/custom-docs-ui-assets.md b/docs/zh/docs/how-to/custom-docs-ui-assets.md index 9e6e5a66b..47b27b69c 100644 --- a/docs/zh/docs/how-to/custom-docs-ui-assets.md +++ b/docs/zh/docs/how-to/custom-docs-ui-assets.md @@ -54,7 +54,7 @@ Swagger UI 会在幕后为你处理这些，但它需要这个“重定向”辅 ### 测试 { #test-it } -现在，你应该可以访问 http://127.0.0.1:8000/docs，并刷新页面，页面会从新的 CDN 加载这些资源。 +现在，你应该可以访问 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)，并刷新页面，页面会从新的 CDN 加载这些资源。 ## 为文档自托管 JavaScript 和 CSS { #self-hosting-javascript-and-css-for-docs } @@ -93,12 +93,12 @@ Swagger UI 会在幕后为你处理这些，但它需要这个“重定向”辅 Swagger UI 使用以下文件： -- `swagger-ui-bundle.js` -- `swagger-ui.css` +- [`swagger-ui-bundle.js`](https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js) +- [`swagger-ui.css`](https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css) 而 ReDoc 使用以下文件： -- `redoc.standalone.js` +- [`redoc.standalone.js`](https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js) 之后，你的文件结构可能如下： @@ -122,7 +122,7 @@ Swagger UI 使用以下文件： ### 测试静态文件 { #test-the-static-files } -启动你的应用，并访问 http://127.0.0.1:8000/static/redoc.standalone.js。 +启动你的应用，并访问 [http://127.0.0.1:8000/static/redoc.standalone.js](http://127.0.0.1:8000/static/redoc.standalone.js)。 你应该会看到一个非常长的 **ReDoc** 的 JavaScript 文件。 @@ -180,6 +180,6 @@ Swagger UI 会在幕后为你处理这些，但它需要这个“重定向”辅 ### 测试静态文件 UI { #test-static-files-ui } -现在，你可以断开 WiFi，访问 http://127.0.0.1:8000/docs，并刷新页面。 +现在，你可以断开 WiFi，访问 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)，并刷新页面。 即使没有互联网，你也能看到 API 的文档并与之交互。 diff --git a/docs/zh/docs/how-to/custom-request-and-route.md b/docs/zh/docs/how-to/custom-request-and-route.md index 8b365987c..79860a562 100644 --- a/docs/zh/docs/how-to/custom-request-and-route.md +++ b/docs/zh/docs/how-to/custom-request-and-route.md @@ -18,7 +18,7 @@ 一些使用场景包括： -* 将非 JSON 的请求体转换为 JSON（例如 `msgpack`）。 +* 将非 JSON 的请求体转换为 JSON（例如 [`msgpack`](https://msgpack.org/index.html)）。 * 解压缩使用 gzip 压缩的请求体。 * 自动记录所有请求体日志。 @@ -32,7 +32,7 @@ /// tip | 提示 -这是一个演示工作原理的示例。如果你需要 Gzip 支持，可以直接使用提供的 [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}。 +这是一个演示工作原理的示例。如果你需要 Gzip 支持，可以直接使用提供的 [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware)。 /// @@ -66,7 +66,7 @@ 创建一个新的 `Request` 实例需要这两样：`scope` 和 `receive`。 -想了解更多关于 `Request` 的信息，请查看 Starlette 的 Request 文档。 +想了解更多关于 `Request` 的信息，请查看 [Starlette 的 Request 文档](https://www.starlette.dev/requests/)。 /// @@ -82,7 +82,7 @@ /// tip | 提示 -要解决类似问题，使用 `RequestValidationError` 的自定义处理器中的 `body` 往往更简单（[处理错误](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}）。 +要解决类似问题，使用 `RequestValidationError` 的自定义处理器中的 `body` 往往更简单（[处理错误](../tutorial/handling-errors.md#use-the-requestvalidationerror-body)）。 但本示例同样有效，并展示了如何与内部组件交互。 diff --git a/docs/zh/docs/how-to/extending-openapi.md b/docs/zh/docs/how-to/extending-openapi.md index ad8a1d698..fd39e439f 100644 --- a/docs/zh/docs/how-to/extending-openapi.md +++ b/docs/zh/docs/how-to/extending-openapi.md @@ -37,7 +37,7 @@ 基于以上信息，你可以用同一个工具函数生成 OpenAPI 架构，并按需覆盖其中的各个部分。 -例如，让我们添加 ReDoc 的 OpenAPI 扩展以包含自定义 Logo。 +例如，让我们添加 [ReDoc 的 OpenAPI 扩展以包含自定义 Logo](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo)。 ### 常规 **FastAPI** { #normal-fastapi } @@ -75,6 +75,6 @@ ### 验证 { #check-it } -当你访问 http://127.0.0.1:8000/redoc 时，你会看到已使用你的自定义 Logo（本例中为 **FastAPI** 的 Logo）： +当你访问 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) 时，你会看到已使用你的自定义 Logo（本例中为 **FastAPI** 的 Logo）：diff --git a/docs/zh/docs/how-to/general.md b/docs/zh/docs/how-to/general.md index 2c9f78179..1526ca187 100644 --- a/docs/zh/docs/how-to/general.md +++ b/docs/zh/docs/how-to/general.md @@ -4,36 +4,40 @@ ## 数据过滤 - 安全性 { #filter-data-security } -为确保不返回超过需要的数据，请阅读 [教程 - 响应模型 - 返回类型](../tutorial/response-model.md){.internal-link target=_blank} 文档。 +为确保不返回超过需要的数据，请阅读 [教程 - 响应模型 - 返回类型](../tutorial/response-model.md) 文档。 + +## 优化响应性能 - 响应模型 - 返回类型 { #optimize-response-performance-response-model-return-type } + +在返回 JSON 数据时优化性能，请使用返回类型或响应模型，这样 Pydantic 会在 Rust 侧处理到 JSON 的序列化，而无需经过 Python。更多内容请阅读 [教程 - 响应模型 - 返回类型](../tutorial/response-model.md) 文档。 ## 文档的标签 - OpenAPI { #documentation-tags-openapi } -在文档界面中添加**路径操作**的标签和进行分组，请阅读 [教程 - 路径操作配置 - Tags 参数](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} 文档。 +在文档界面中添加**路径操作**的标签和进行分组，请阅读 [教程 - 路径操作配置 - Tags](../tutorial/path-operation-configuration.md#tags) 文档。 ## 文档的概要和描述 - OpenAPI { #documentation-summary-and-description-openapi } -在文档界面中添加**路径操作**的概要和描述，请阅读 [教程 - 路径操作配置 - Summary 和 Description 参数](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} 文档。 +在文档界面中添加**路径操作**的概要和描述，请阅读 [教程 - 路径操作配置 - Summary 和 Description](../tutorial/path-operation-configuration.md#summary-and-description) 文档。 ## 文档的响应描述 - OpenAPI { #documentation-response-description-openapi } -在文档界面中定义并显示响应描述，请阅读 [教程 - 路径操作配置 - 响应描述](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} 文档。 +在文档界面中定义并显示响应描述，请阅读 [教程 - 路径操作配置 - 响应描述](../tutorial/path-operation-configuration.md#response-description) 文档。 ## 文档弃用**路径操作** - OpenAPI { #documentation-deprecate-a-path-operation-openapi } -在文档界面中显示弃用的**路径操作**，请阅读 [教程 - 路径操作配置 - 弃用](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} 文档。 +在文档界面中显示弃用的**路径操作**，请阅读 [教程 - 路径操作配置 - 弃用](../tutorial/path-operation-configuration.md#deprecate-a-path-operation) 文档。 ## 将任何数据转换为 JSON 兼容格式 { #convert-any-data-to-json-compatible } -要将任何数据转换为 JSON 兼容格式，请阅读 [教程 - JSON 兼容编码器](../tutorial/encoder.md){.internal-link target=_blank} 文档。 +要将任何数据转换为 JSON 兼容格式，请阅读 [教程 - JSON 兼容编码器](../tutorial/encoder.md) 文档。 ## OpenAPI 元数据 - 文档 { #openapi-metadata-docs } -要添加 OpenAPI 的元数据，包括许可证、版本、联系方式等，请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md){.internal-link target=_blank} 文档。 +要添加 OpenAPI 的元数据，包括许可证、版本、联系方式等，请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md) 文档。 ## OpenAPI 自定义 URL { #openapi-custom-url } -要自定义 OpenAPI 的 URL（或删除它），请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} 文档。 +要自定义 OpenAPI 的 URL（或删除它），请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md#openapi-url) 文档。 ## OpenAPI 文档 URL { #openapi-docs-urls } -要更改自动生成的文档用户界面所使用的 URL，请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}。 +要更改自动生成的文档用户界面所使用的 URL，请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md#docs-urls)。 diff --git a/docs/zh/docs/how-to/graphql.md b/docs/zh/docs/how-to/graphql.md index 5384f1513..b33d6759f 100644 --- a/docs/zh/docs/how-to/graphql.md +++ b/docs/zh/docs/how-to/graphql.md @@ -18,18 +18,18 @@ 以下是一些支持 **ASGI** 的 **GraphQL** 库。你可以将它们与 **FastAPI** 一起使用： -* Strawberry 🍓 - * 提供 面向 FastAPI 的文档 -* Ariadne - * 提供 面向 FastAPI 的文档 -* Tartiflette - * 提供用于 ASGI 集成的 Tartiflette ASGI -* Graphene - * 可配合 starlette-graphene3 使用 +* [Strawberry](https://strawberry.rocks/) 🍓 + * 提供 [面向 FastAPI 的文档](https://strawberry.rocks/docs/integrations/fastapi) +* [Ariadne](https://ariadnegraphql.org/) + * 提供 [面向 FastAPI 的文档](https://ariadnegraphql.org/docs/fastapi-integration) +* [Tartiflette](https://tartiflette.io/) + * 提供用于 ASGI 集成的 [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) +* [Graphene](https://graphene-python.org/) + * 可配合 [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3) 使用 ## 使用 Strawberry 的 GraphQL { #graphql-with-strawberry } -如果你需要或想要使用 **GraphQL**，**Strawberry** 是**推荐**的库，因为它的设计与 **FastAPI** 最为接近，全部基于**类型注解**。 +如果你需要或想要使用 **GraphQL**，[**Strawberry**](https://strawberry.rocks/) 是**推荐**的库，因为它的设计与 **FastAPI** 最为接近，全部基于**类型注解**。 根据你的用例，你可能会更喜欢其他库，但如果你问我，我大概率会建议你先试试 **Strawberry**。 @@ -37,24 +37,24 @@ {* ../../docs_src/graphql_/tutorial001_py310.py hl[3,22,25] *} -你可以在 Strawberry 文档中了解更多信息。 +你可以在 [Strawberry 文档](https://strawberry.rocks/) 中了解更多信息。 -还有关于 将 Strawberry 与 FastAPI 结合使用的文档。 +还有关于 [将 Strawberry 与 FastAPI 结合使用](https://strawberry.rocks/docs/integrations/fastapi) 的文档。 ## Starlette 中较早的 `GraphQLApp` { #older-graphqlapp-from-starlette } -早期版本的 Starlette 包含一个 `GraphQLApp` 类，用于与 Graphene 集成。 +早期版本的 Starlette 包含一个 `GraphQLApp` 类，用于与 [Graphene](https://graphene-python.org/) 集成。 -它已在 Starlette 中被弃用，但如果你的代码使用了它，你可以轻松**迁移**到 starlette-graphene3，它覆盖相同的用例，且接口**几乎完全一致**。 +它已在 Starlette 中被弃用，但如果你的代码使用了它，你可以轻松**迁移**到 [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3)，它覆盖相同的用例，且接口**几乎完全一致**。 /// tip | 提示 -如果你需要 GraphQL，我仍然建议看看 Strawberry，因为它基于类型注解而不是自定义类和类型。 +如果你需要 GraphQL，我仍然建议看看 [Strawberry](https://strawberry.rocks/)，因为它基于类型注解而不是自定义类和类型。 /// ## 了解更多 { #learn-more } -你可以在 GraphQL 官方文档中了解更多关于 **GraphQL** 的内容。 +你可以在 [GraphQL 官方文档](https://graphql.org/) 中了解更多关于 **GraphQL** 的内容。 你也可以通过上面的链接阅读各个库的更多信息。 diff --git a/docs/zh/docs/how-to/index.md b/docs/zh/docs/how-to/index.md index 980dcd1a6..ff3d8afa0 100644 --- a/docs/zh/docs/how-to/index.md +++ b/docs/zh/docs/how-to/index.md @@ -8,6 +8,6 @@ /// tip | 提示 -如果你想以系统的方式**学习 FastAPI**（推荐），请阅读 [教程 - 用户指南](../tutorial/index.md){.internal-link target=_blank} 的每一章节。 +如果你想以系统的方式**学习 FastAPI**（推荐），请阅读 [教程 - 用户指南](../tutorial/index.md) 的每一章节。 /// diff --git a/docs/zh/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/zh/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 2e5445200..3723eb032 100644 --- a/docs/zh/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/zh/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -22,7 +22,7 @@ FastAPI 0.126.0 移除了对 Pydantic v1 的支持，但在一段时间内仍支 ## 官方指南 { #official-guide } -Pydantic 有一份从 v1 迁移到 v2 的官方 迁移指南。 +Pydantic 有一份从 v1 迁移到 v2 的官方[迁移指南](https://docs.pydantic.dev/latest/migration/)。 其中包含变更内容、校验如何更准确更严格、可能的注意事项等。 @@ -30,7 +30,7 @@ Pydantic 有一份从 v1 迁移到 v2 的官方 `bump-pydantic`。 +你可以使用同一 Pydantic 团队提供的[`bump-pydantic`](https://github.com/pydantic/bump-pydantic)。 该工具会帮助你自动修改大部分需要变更的代码。 diff --git a/docs/zh/docs/how-to/testing-database.md b/docs/zh/docs/how-to/testing-database.md index e4a20d843..57219832b 100644 --- a/docs/zh/docs/how-to/testing-database.md +++ b/docs/zh/docs/how-to/testing-database.md @@ -1,7 +1,7 @@ # 测试数据库 { #testing-a-database } -你可以在 SQLModel 文档 中学习数据库、SQL 和 SQLModel。🤓 +你可以在[SQLModel 文档](https://sqlmodel.tiangolo.com/)中学习数据库、SQL 和 SQLModel。🤓 -这里有一个关于在 FastAPI 中使用 SQLModel 的小教程：使用 SQLModel 搭配 FastAPI 的教程。✨ +这里有一个[在 FastAPI 中使用 SQLModel 的小教程](https://sqlmodel.tiangolo.com/tutorial/fastapi/)。✨ -该教程包含一个关于 测试 SQL 数据库 的章节。😎 +该教程包含一个关于[测试 SQL 数据库](https://sqlmodel.tiangolo.com/tutorial/fastapi/tests/)的章节。😎 diff --git a/docs/zh/docs/index.md b/docs/zh/docs/index.md index 38e128bf1..a88c25efb 100644 --- a/docs/zh/docs/index.md +++ b/docs/zh/docs/index.md @@ -11,25 +11,25 @@ FastAPI 框架，高性能，易于学习，高效编码，生产可用 --- -**文档**： https://fastapi.tiangolo.com +**文档**： [https://fastapi.tiangolo.com/zh](https://fastapi.tiangolo.com/zh) -**源码**： https://github.com/fastapi/fastapi +**源码**： [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi) --- @@ -44,7 +44,7 @@ FastAPI 是一个用于构建 API 的现代、快速（高性能）的 Web 框 * **易用**：为易用和易学而设计。更少的文档阅读时间。 * **简短**：最小化代码重复。一次参数声明即可获得多种功能。更少的 bug。 * **健壮**：生产可用级代码。并带有自动生成的交互式文档。 -* **标准化**：基于（并完全兼容）API 的开放标准：OpenAPI（以前称为 Swagger）和 JSON Schema。 +* **标准化**：基于（并完全兼容）API 的开放标准：[OpenAPI](https://github.com/OAI/OpenAPI-Specification)（以前称为 Swagger）和 [JSON Schema](https://json-schema.org/)。 * 基于某内部开发团队在构建生产应用时的测试估算。 @@ -55,51 +55,51 @@ FastAPI 是一个用于构建 API 的现代、快速（高性能）的 Web 框 ### Keystone 赞助商 { #keystone-sponsor } {% for sponsor in sponsors.keystone -%} -
+
Kabir Khan - Microsoft (ref)+Kabir Khan - Microsoft (ref)--- 「_我们采用 **FastAPI** 来构建可查询以获取**预测结果**的 **REST** 服务器。[用于 Ludwig]_」 -Piero Molino，Yaroslav Dudin，Sai Sumanth Miryala - Uber (ref)+Piero Molino，Yaroslav Dudin，Sai Sumanth Miryala - Uber (ref)--- 「_**Netflix** 很高兴宣布开源我们的**危机管理**编排框架：**Dispatch**！[使用 **FastAPI** 构建]_」 -Kevin Glisson，Marc Vilanova，Forest Monsen - Netflix (ref)+Kevin Glisson，Marc Vilanova，Forest Monsen - Netflix (ref)--- 「_我对 **FastAPI** 兴奋到飞起。它太有趣了！_」 -Brian Okken - Python Bytes 播客主持人 (ref)+Brian Okken - [Python Bytes](https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855) 播客主持人 (ref)--- 「_老实说，你构建的东西非常稳健而且打磨得很好。从很多方面看，这就是我想让 **Hug** 成为的样子 —— 看到有人把它做出来真的很鼓舞人心。_」 - +Timothy Crosley - [Hug](https://github.com/hugapi/hug) 作者 (ref)--- @@ -107,27 +107,27 @@ FastAPI 是一个用于构建 API 的现代、快速（高性能）的 Web 框 「_我们已经把我们的 **API** 切换到 **FastAPI** [...] 我想你会喜欢它 [...]_」 - +Ines Montani - Matthew Honnibal - [Explosion AI](https://explosion.ai) 创始人 - [spaCy](https://spacy.io) 作者 (ref) - (ref)--- 「_如果有人正在构建生产级的 Python API，我强烈推荐 **FastAPI**。它**设计优雅**、**使用简单**且**高度可扩展**，已经成为我们 API 优先开发战略中的**关键组件**，并驱动了许多自动化和服务，比如我们的 Virtual TAC Engineer。_」 -Deon Pillsbury - Cisco (ref)+Deon Pillsbury - Cisco (ref)--- ## FastAPI 迷你纪录片 { #fastapi-mini-documentary } -在 2025 年末发布了一部FastAPI 迷你纪录片，你可以在线观看： +在 2025 年末发布了一部 [FastAPI 迷你纪录片](https://www.youtube.com/watch?v=mpR8ngthqiE)，你可以在线观看： -+
+
@@ -199,7 +199,7 @@ async def read_item(item_id: int, q: str | None = None): **Note**: -如果你不确定，请查看文档中 _"In a hurry?"_ 章节的`async` 和 `await`部分。 +如果你不确定，请查看文档中 _"In a hurry?"_ 章节的 [`async` 和 `await`](https://fastapi.tiangolo.com/zh/async/#in-a-hurry) 部分。 @@ -210,7 +210,7 @@ async def read_item(item_id: int, q: str | None = None):```console -$ fastapi dev main.py +$ fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -235,19 +235,19 @@ INFO: Application startup complete.-### 检查 { #check-it } -用浏览器打开 http://127.0.0.1:8000/items/5?q=somequery。 +用浏览器打开 [http://127.0.0.1:8000/items/5?q=somequery](http://127.0.0.1:8000/items/5?q=somequery)。 你会看到如下 JSON 响应： @@ -264,17 +264,17 @@ INFO: Application startup complete. ### 交互式 API 文档 { #interactive-api-docs } -现在访问 http://127.0.0.1:8000/docs。 +现在访问 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 -你会看到自动生成的交互式 API 文档（由 Swagger UI 提供）： +你会看到自动生成的交互式 API 文档（由 [Swagger UI](https://github.com/swagger-api/swagger-ui) 提供）：  ### 可选的 API 文档 { #alternative-api-docs } -然后访问 http://127.0.0.1:8000/redoc。 +然后访问 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 -你会看到另一个自动生成的文档（由 ReDoc 提供）： +你会看到另一个自动生成的文档（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）：  @@ -316,7 +316,7 @@ def update_item(item_id: int, item: Item): ### 交互式 API 文档升级 { #interactive-api-docs-upgrade } -现在访问 http://127.0.0.1:8000/docs。 +现在访问 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 * 交互式 API 文档会自动更新，并包含新的请求体： @@ -332,7 +332,7 @@ def update_item(item_id: int, item: Item): ### 可选文档升级 { #alternative-api-docs-upgrade } -再访问 http://127.0.0.1:8000/redoc。 +再访问 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 * 可选文档同样会体现新的查询参数和请求体： @@ -442,7 +442,7 @@ item: Item * 功能强大且易用的 **依赖注入** 系统。 * 安全与认证，包括对 **OAuth2**、**JWT tokens** 和 **HTTP Basic** 认证的支持。 * 更高级（但同样简单）的 **多层嵌套 JSON 模型** 声明技巧（得益于 Pydantic）。 -* 通过 Strawberry 等库进行 **GraphQL** 集成。 +* 通过 [Strawberry](https://strawberry.rocks) 等库进行 **GraphQL** 集成。 * 许多额外特性（归功于 Starlette），例如： * **WebSockets** * 基于 HTTPX 和 `pytest` 的极其简单的测试 @@ -452,24 +452,10 @@ item: Item ### 部署你的应用（可选） { #deploy-your-app-optional } -你可以选择把 FastAPI 应用部署到 FastAPI Cloud，如果还没有的话去加入候补名单吧。🚀 +你可以选择把 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)，如果还没有的话去加入候补名单吧。🚀 如果你已经有 **FastAPI Cloud** 账号（我们从候补名单邀请了你 😉），你可以用一个命令部署你的应用。 -部署前，先确认已登录： - -关于命令
+fastapi dev main.py...关于命令
-`fastapi dev` 命令会读取你的 `main.py` 文件，检测其中的 **FastAPI** 应用，并使用 Uvicorn 启动服务器。 +`fastapi dev` 命令会读取你的 `main.py` 文件，检测其中的 **FastAPI** 应用，并使用 [Uvicorn](https://www.uvicorn.dev) 启动服务器。 默认情况下，`fastapi dev` 会在本地开发时启用自动重载。 -你可以在 FastAPI CLI 文档中了解更多。 +你可以在 [FastAPI CLI 文档](https://fastapi.tiangolo.com/zh/fastapi-cli/) 中了解更多。fastapi dev...- -```console -$ fastapi login - -You are logged in to FastAPI Cloud 🚀 -``` - -- -然后部署你的应用： -```console @@ -488,7 +474,7 @@ Deploying to FastAPI Cloud... #### 关于 FastAPI Cloud { #about-fastapi-cloud } -**FastAPI Cloud** 由 **FastAPI** 的同一位作者和团队打造。 +**[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 的同一位作者和团队打造。 它让你以最小的工作量就能**构建**、**部署**并**访问**一个 API。 @@ -504,9 +490,9 @@ FastAPI 是开源且基于标准的。你可以部署 FastAPI 应用到你选择 ## 性能 { #performance } -独立机构 TechEmpower 的基准测试显示，运行在 Uvicorn 下的 **FastAPI** 应用是最快的 Python 框架之一，仅次于 Starlette 和 Uvicorn 本身（FastAPI 内部使用它们）。(*) +独立机构 TechEmpower 的基准测试显示，运行在 Uvicorn 下的 **FastAPI** 应用是 [最快的 Python 框架之一](https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7)，仅次于 Starlette 和 Uvicorn 本身（FastAPI 内部使用它们）。(*) -想了解更多，请参阅基准测试章节。 +想了解更多，请参阅 [基准测试](https://fastapi.tiangolo.com/zh/benchmarks/) 章节。 ## 依赖项 { #dependencies } @@ -518,19 +504,19 @@ FastAPI 依赖 Pydantic 和 Starlette。 Pydantic 使用： -*email-validator- 用于 email 校验。 +* [`email-validator`](https://github.com/JoshData/python-email-validator) - 用于 email 校验。 Starlette 使用： -*httpx- 使用 `TestClient` 时需要。 -*jinja2- 使用默认模板配置时需要。 -*python-multipart- 使用 `request.form()` 支持表单「解析」时需要。 +* [`httpx`](https://www.python-httpx.org) - 使用 `TestClient` 时需要。 +* [`jinja2`](https://jinja.palletsprojects.com) - 使用默认模板配置时需要。 +* [`python-multipart`](https://github.com/Kludex/python-multipart) - 使用 `request.form()` 支持表单「解析」时需要。 FastAPI 使用： -*uvicorn- 加载并提供你的应用的服务器。包含 `uvicorn[standard]`，其中包含高性能服务所需的一些依赖（例如 `uvloop`）。 +* [`uvicorn`](https://www.uvicorn.dev) - 加载并提供你的应用的服务器。包含 `uvicorn[standard]`，其中包含高性能服务所需的一些依赖（例如 `uvloop`）。 * `fastapi-cli[standard]` - 提供 `fastapi` 命令。 - * 其中包含 `fastapi-cloud-cli`，它允许你将 FastAPI 应用部署到 FastAPI Cloud。 + * 其中包含 `fastapi-cloud-cli`，它允许你将 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)。 ### 不包含 `standard` 依赖 { #without-standard-dependencies } @@ -546,13 +532,13 @@ FastAPI 使用： 额外的 Pydantic 可选依赖： -*pydantic-settings- 用于配置管理。 -*pydantic-extra-types- 用于在 Pydantic 中使用的额外类型。 +* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 用于配置管理。 +* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - 用于在 Pydantic 中使用的额外类型。 额外的 FastAPI 可选依赖： -*orjson- 使用 `ORJSONResponse` 时需要。 -*ujson- 使用 `UJSONResponse` 时需要。 +* [`orjson`](https://github.com/ijl/orjson) - 使用 `ORJSONResponse` 时需要。 +* [`ujson`](https://github.com/esnme/ultrajson) - 使用 `UJSONResponse` 时需要。 ## 许可协议 { #license } diff --git a/docs/zh/docs/project-generation.md b/docs/zh/docs/project-generation.md index a6ad9f94a..8cc50c096 100644 --- a/docs/zh/docs/project-generation.md +++ b/docs/zh/docs/project-generation.md @@ -4,7 +4,7 @@ 你可以使用此模板开始，它已经为你完成了大量的初始设置、安全性、数据库以及一些 API 端点。 -GitHub 仓库： Full Stack FastAPI Template +GitHub 仓库：[Full Stack FastAPI Template](https://github.com/tiangolo/full-stack-fastapi-template) ## FastAPI全栈模板 - 技术栈和特性 { #full-stack-fastapi-template-technology-stack-and-features } diff --git a/docs/zh/docs/python-types.md b/docs/zh/docs/python-types.md index 4824b7558..9b2fceb98 100644 --- a/docs/zh/docs/python-types.md +++ b/docs/zh/docs/python-types.md @@ -269,7 +269,7 @@ def some_function(data: Any): ## Pydantic 模型 { #pydantic-models } -Pydantic 是一个用于执行数据校验的 Python 库。 +[Pydantic](https://docs.pydantic.dev/) 是一个用于执行数据校验的 Python 库。 你将数据的“结构”声明为带有属性的类。 @@ -285,13 +285,13 @@ def some_function(data: Any): /// info | 信息 -想了解更多关于 Pydantic 的信息，请查看其文档。 +想了解更多关于 [Pydantic](https://docs.pydantic.dev/) 的信息，请查看其文档。 /// **FastAPI** 完全建立在 Pydantic 之上。 -你会在[教程 - 用户指南](tutorial/index.md){.internal-link target=_blank}中看到更多的实战示例。 +你会在[教程 - 用户指南](tutorial/index.md)中看到更多的实战示例。 ## 带元数据注解的类型提示 { #type-hints-with-metadata-annotations } @@ -337,12 +337,12 @@ Python 本身不会对这个 `Annotated` 做任何处理。对于编辑器和其 * 使用 OpenAPI 记录 API： * 然后用于自动生成交互式文档界面。 -这些听起来可能有点抽象。别担心。你会在[教程 - 用户指南](tutorial/index.md){.internal-link target=_blank}中看到所有这些的实际效果。 +这些听起来可能有点抽象。别担心。你会在[教程 - 用户指南](tutorial/index.md)中看到所有这些的实际效果。 重要的是，通过使用标准的 Python 类型，而且只在一个地方声明（而不是添加更多类、装饰器等），**FastAPI** 会为你完成大量工作。 /// info | 信息 -如果你已经读完所有教程，又回来想进一步了解类型，一个不错的资源是 `mypy` 的“速查表”。 +如果你已经读完所有教程，又回来想进一步了解类型，一个不错的资源是 [`mypy` 的“速查表”](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html)。 /// diff --git a/docs/zh/docs/tutorial/background-tasks.md b/docs/zh/docs/tutorial/background-tasks.md index d73fee429..975bb2688 100644 --- a/docs/zh/docs/tutorial/background-tasks.md +++ b/docs/zh/docs/tutorial/background-tasks.md @@ -61,7 +61,7 @@ ## 技术细节 { #technical-details } -`BackgroundTasks` 类直接来自 `starlette.background`。 +`BackgroundTasks` 类直接来自 [`starlette.background`](https://www.starlette.dev/background/)。 它被直接导入/包含到FastAPI以便你可以从 `fastapi` 导入，并避免意外从 `starlette.background` 导入备用的 `BackgroundTask` (后面没有 `s`)。 @@ -69,11 +69,11 @@ 在FastAPI中仍然可以单独使用 `BackgroundTask`，但您必须在代码中创建对象，并返回包含它的Starlette `Response`。 -更多细节查看 Starlette 后台任务的官方文档. +更多细节查看 [Starlette 后台任务的官方文档](https://www.starlette.dev/background/)。 ## 告诫 { #caveat } -如果您需要执行繁重的后台计算，并且不一定需要由同一进程运行（例如，您不需要共享内存、变量等），那么使用其他更大的工具（如 Celery）可能更好。 +如果您需要执行繁重的后台计算，并且不一定需要由同一进程运行（例如，您不需要共享内存、变量等），那么使用其他更大的工具（如 [Celery](https://docs.celeryq.dev)）可能更好。 它们往往需要更复杂的配置，即消息/作业队列管理器，如RabbitMQ或Redis，但它们允许您在多个进程中运行后台任务，甚至是在多个服务器中。 diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md index a667d596f..74522f838 100644 --- a/docs/zh/docs/tutorial/bigger-applications.md +++ b/docs/zh/docs/tutorial/bigger-applications.md @@ -123,7 +123,7 @@ from app.routers import items 我们正在使用虚构的请求首部来简化此示例。 -但在实际情况下，使用集成的[安全性实用工具](security/index.md){.internal-link target=_blank}会得到更好的效果。 +但在实际情况下，使用集成的[安全性实用工具](security/index.md)会得到更好的效果。 /// @@ -169,7 +169,7 @@ async def read_item(item_id: str): /// tip | 提示 -请注意，和[*路径操作装饰器*中的依赖项](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}很类似，没有值会被传递给你的*路径操作函数*。 +请注意，和[*路径操作装饰器*中的依赖项](dependencies/dependencies-in-path-operation-decorators.md)很类似，没有值会被传递给你的*路径操作函数*。 /// @@ -185,8 +185,8 @@ async def read_item(item_id: str): * 所有的路径操作都将包含预定义的 `responses`。 * 所有的这些*路径操作*都将在自身之前计算/执行 `dependencies` 列表。 * 如果你还在一个具体的*路径操作*中声明了依赖项，**它们也会被执行**。 - * 路由器的依赖项最先执行，然后是[装饰器中的 `dependencies`](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}，再然后是普通的参数依赖项。 - * 你还可以添加[具有 `scopes` 的 `Security` 依赖项](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}。 + * 路由器的依赖项最先执行，然后是[装饰器中的 `dependencies`](dependencies/dependencies-in-path-operation-decorators.md)，再然后是普通的参数依赖项。 + * 你还可以添加[具有 `scopes` 的 `Security` 依赖项](../advanced/security/oauth2-scopes.md)。 /// tip | 提示 @@ -303,7 +303,7 @@ from ...dependencies import get_token_header 你可以像平常一样导入并创建一个 `FastAPI` 类。 -我们甚至可以声明[全局依赖项](dependencies/global-dependencies.md){.internal-link target=_blank}，它会和每个 `APIRouter` 的依赖项组合在一起： +我们甚至可以声明[全局依赖项](dependencies/global-dependencies.md)，它会和每个 `APIRouter` 的依赖项组合在一起： {* ../../docs_src/bigger_applications/app_an_py310/main.py hl[1,3,7] title["app/main.py"] *} @@ -353,7 +353,7 @@ from .routers import items, users from app.routers import items, users ``` -要了解有关 Python 包和模块的更多信息，请查阅关于 Modules 的 Python 官方文档。 +要了解有关 Python 包和模块的更多信息，请查阅[关于 Modules 的 Python 官方文档](https://docs.python.org/3/tutorial/modules.html)。 /// @@ -451,7 +451,7 @@ from .routers.users import router 它将与通过 `app.include_router()` 添加的所有其他*路径操作*一起正常运行。 -/// info | 特别的技术细节 +/// info | 非常技术细节 **注意**：这是一个非常技术性的细节，你也许可以**直接跳过**。 @@ -465,6 +465,37 @@ from .routers.users import router /// +## 在 `pyproject.toml` 中配置 `entrypoint` { #configure-the-entrypoint-in-pyproject-toml } + +因为你的 FastAPI `app` 对象位于 `app/main.py` 中，你可以在 `pyproject.toml` 中这样配置 `entrypoint`： + +```toml +[tool.fastapi] +entrypoint = "app.main:app" +``` + +等价于像这样导入： + +```python +from app.main import app +``` + +这样 `fastapi` 命令就知道到哪里去找到你的应用了。 + +/// Note | 注意 + +你也可以把路径传给命令，比如： + +```console +$ fastapi dev app/main.py +``` + +但是每次调用 `fastapi` 命令时，你都需要记得传入正确的路径。 + +另外，其他工具可能找不到它，比如 [VS Code 扩展](../editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com)，因此推荐在 `pyproject.toml` 中使用 `entrypoint`。 + +/// + ## 查看自动化的 API 文档 { #check-the-automatic-api-docs } 现在，运行你的应用： @@ -472,14 +503,14 @@ from .routers.users import router```console -$ fastapi dev app/main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```-然后打开位于 http://127.0.0.1:8000/docs 的文档。 +然后打开位于 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) 的文档。 你将看到使用了正确路径（和前缀）和正确标签的自动化 API 文档，包括了来自所有子模块的路径： diff --git a/docs/zh/docs/tutorial/body-nested-models.md b/docs/zh/docs/tutorial/body-nested-models.md index fe6902e83..93a34da55 100644 --- a/docs/zh/docs/tutorial/body-nested-models.md +++ b/docs/zh/docs/tutorial/body-nested-models.md @@ -95,7 +95,7 @@ Pydantic 模型的每个属性都具有类型。 除了普通的单一值类型（如 `str`、`int`、`float` 等）外，你还可以使用从 `str` 继承的更复杂的单一值类型。 -要了解所有的可用选项，请查看 Pydantic 的类型概览。你将在下一章节中看到一些示例。 +要了解所有的可用选项，请查看 [Pydantic 的类型概览](https://docs.pydantic.dev/latest/concepts/types/)。你将在下一章节中看到一些示例。 例如，在 `Image` 模型中我们有一个 `url` 字段，我们可以把它声明为 Pydantic 的 `HttpUrl`，而不是 `str`： diff --git a/docs/zh/docs/tutorial/body-updates.md b/docs/zh/docs/tutorial/body-updates.md index 000201de9..5b181642c 100644 --- a/docs/zh/docs/tutorial/body-updates.md +++ b/docs/zh/docs/tutorial/body-updates.md @@ -2,7 +2,7 @@ ## 用 `PUT` 替换式更新 { #update-replacing-with-put } -更新数据可以使用 HTTP `PUT` 操作。 +更新数据可以使用 [HTTP `PUT`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) 操作。 把输入数据转换为以 JSON 格式存储的数据（比如，使用 NoSQL 数据库时），可以使用 `jsonable_encoder`。例如，把 `datetime` 转换为 `str`。 @@ -28,7 +28,7 @@ ## 用 `PATCH` 进行部分更新 { #partial-updates-with-patch } -也可以使用 HTTP `PATCH` 操作对数据进行*部分*更新。 +也可以使用 [HTTP `PATCH`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) 操作对数据进行*部分*更新。 也就是说，你只需发送想要更新的数据，其余数据保持不变。 @@ -95,6 +95,6 @@ 因此，如果希望接收的部分更新可以省略所有属性，则需要一个所有属性都标记为可选（带默认值或 `None`）的模型。 -为了区分用于**更新**（全部可选）和用于**创建**（必填）的模型，可以参考[更多模型](extra-models.md){.internal-link target=_blank} 中介绍的思路。 +为了区分用于**更新**（全部可选）和用于**创建**（必填）的模型，可以参考[更多模型](extra-models.md) 中介绍的思路。 /// diff --git a/docs/zh/docs/tutorial/body.md b/docs/zh/docs/tutorial/body.md index 4a72ba17c..0a4c9c5e5 100644 --- a/docs/zh/docs/tutorial/body.md +++ b/docs/zh/docs/tutorial/body.md @@ -6,7 +6,7 @@ 你的 API 几乎总是需要发送**响应体**。但客户端不一定总是要发送**请求体**，有时它们只请求某个路径，可能带一些查询参数，但不会发送请求体。 -使用 Pydantic 模型来声明**请求体**，能充分利用它的功能和优点。 +使用 [Pydantic](https://docs.pydantic.dev/) 模型来声明**请求体**，能充分利用它的功能和优点。 /// info | 信息 @@ -72,7 +72,7 @@ * 数据无效时返回清晰的错误信息，并指出错误数据的确切位置和内容。 * 把接收的数据赋值给参数 `item`。 * 因为你把函数中的参数类型声明为 `Item`，所以还能获得所有属性及其类型的编辑器支持（补全等）。 -* 为你的模型生成 JSON Schema 定义，如果对你的项目有意义，还可以在其他地方使用它们。 +* 为你的模型生成 [JSON Schema](https://json-schema.org) 定义，如果对你的项目有意义，还可以在其他地方使用它们。 * 这些 schema 会成为生成的 OpenAPI Schema 的一部分，并被自动文档的 UIs 使用。 ## 自动文档 { #automatic-docs } @@ -101,15 +101,15 @@ 我们甚至对 Pydantic 本身做了一些改动以支持这些功能。 -上面的截图来自 Visual Studio Code。 +上面的截图来自 [Visual Studio Code](https://code.visualstudio.com)。 -但使用 PyCharm 和大多数其他 Python 编辑器，你也会获得相同的编辑器支持： +但使用 [PyCharm](https://www.jetbrains.com/pycharm/) 和大多数其他 Python 编辑器，你也会获得相同的编辑器支持：/// tip | 提示 -如果你使用 PyCharm 作为编辑器，可以使用 Pydantic PyCharm 插件。 +如果你使用 [PyCharm](https://www.jetbrains.com/pycharm/) 作为编辑器，可以使用 [Pydantic PyCharm 插件](https://github.com/koxudaxi/pydantic-pycharm-plugin/)。 它能改进对 Pydantic 模型的编辑器支持，包括： @@ -161,4 +161,4 @@ FastAPI 会根据默认值 `= None` 知道 `q` 的值不是必填的。 ## 不使用 Pydantic { #without-pydantic } -即便不使用 Pydantic 模型也能使用 **Body** 参数。详见[请求体 - 多参数：请求体中的单值](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}。 +即便不使用 Pydantic 模型也能使用 **Body** 参数。详见[请求体 - 多参数：请求体中的单值](body-multiple-params.md#singular-values-in-body)。 diff --git a/docs/zh/docs/tutorial/cors.md b/docs/zh/docs/tutorial/cors.md index 2e271ec75..ebea43edb 100644 --- a/docs/zh/docs/tutorial/cors.md +++ b/docs/zh/docs/tutorial/cors.md @@ -1,6 +1,6 @@ # CORS（跨域资源共享） { #cors-cross-origin-resource-sharing } -CORS 或者「跨域资源共享」 指浏览器中运行的前端拥有与后端通信的 JavaScript 代码，而后端处于与前端不同的「源」的情况。 +[CORS 或者「跨域资源共享」](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 指浏览器中运行的前端拥有与后端通信的 JavaScript 代码，而后端处于与前端不同的「源」的情况。 ## 源 { #origin } @@ -55,10 +55,10 @@ * `allow_origins` - 一个允许跨域请求的源列表。例如 `['https://example.org', 'https://www.example.org']`。你可以使用 `['*']` 允许任何源。 * `allow_origin_regex` - 一个正则表达式字符串，匹配的源允许跨域请求。例如 `'https://.*\.example\.org'`。 * `allow_methods` - 一个允许跨域请求的 HTTP 方法列表。默认为 `['GET']`。你可以使用 `['*']` 来允许所有标准方法。 -* `allow_headers` - 一个允许跨域请求的 HTTP 请求头列表。默认为 `[]`。你可以使用 `['*']` 允许所有的请求头。`Accept`、`Accept-Language`、`Content-Language` 以及 `Content-Type` 这几个请求头在简单 CORS 请求中总是被允许。 +* `allow_headers` - 一个允许跨域请求的 HTTP 请求头列表。默认为 `[]`。你可以使用 `['*']` 允许所有的请求头。`Accept`、`Accept-Language`、`Content-Language` 以及 `Content-Type` 这几个请求头在[简单 CORS 请求](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests)中总是被允许。 * `allow_credentials` - 指示跨域请求支持 cookies。默认是 `False`。 - 当 `allow_credentials` 设为 `True` 时，`allow_origins`、`allow_methods` 和 `allow_headers` 都不能设为 `['*']`。它们必须显式指定。 + 当 `allow_credentials` 设为 `True` 时，`allow_origins`、`allow_methods` 和 `allow_headers` 都不能设为 `['*']`。它们必须[显式指定](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#credentialed_requests_and_wildcards)。 * `expose_headers` - 指示可以被浏览器访问的响应头。默认为 `[]`。 * `max_age` - 设定浏览器缓存 CORS 响应的最长时间，单位是秒。默认为 `600`。 @@ -77,7 +77,7 @@ ## 更多信息 { #more-info } -更多关于 CORS 的信息，请查看 Mozilla CORS 文档。 +更多关于 CORS 的信息，请查看 [Mozilla CORS 文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)。 /// note | 技术细节 diff --git a/docs/zh/docs/tutorial/debugging.md b/docs/zh/docs/tutorial/debugging.md index 1ff7d6127..19e6f8a61 100644 --- a/docs/zh/docs/tutorial/debugging.md +++ b/docs/zh/docs/tutorial/debugging.md @@ -70,7 +70,7 @@ from myapp import app /// info | 信息 -更多信息请检查 Python 官方文档. +更多信息请检查 [Python 官方文档](https://docs.python.org/3/library/__main__.html). /// 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 23412e465..a3b2e6a41 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 @@ -32,7 +32,7 @@ 本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。 -但实际开发中，尤其是在实现安全措施时，最好使用 FastAPI 内置的[安全工具](../security/index.md){.internal-link target=_blank}（详见下一章）。 +但实际开发中，尤其是在实现安全措施时，最好使用 FastAPI 内置的[安全工具（下一章）](../security/index.md)。 /// @@ -62,7 +62,7 @@ ## 为一组路径操作定义依赖项 { #dependencies-for-a-group-of-path-operations } -稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。 +稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md)一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。 ## 全局依赖项 { #global-dependencies } diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md index 413dedb96..a365bccf0 100644 --- a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md @@ -14,8 +14,8 @@ FastAPI 支持那些在完成后执行一些`@contextlib.contextmanager` 或 -* `@contextlib.asynccontextmanager` +* [`@contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) 或 +* [`@contextlib.asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager) 都可以作为 **FastAPI** 的依赖项。 @@ -87,7 +87,7 @@ FastAPI 支持那些在完成后执行一些上下文管理器。 +这要归功于 Python 的[上下文管理器](https://docs.python.org/3/library/contextlib.html)。 **FastAPI** 在内部使用它们来实现这一点。 @@ -111,7 +111,7 @@ FastAPI 支持那些在完成后执行一些你可以用 `with` 来读取文件： +例如，[你可以用 `with` 来读取文件](https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files)： ```Python with open("./somefile.txt") as f: @@ -265,7 +265,7 @@ with open("./somefile.txt") as f: /// -在 Python 中，你可以通过创建一个带有 `__enter__()` 和 `__exit__()` 方法的类来创建上下文管理器。 +在 Python 中，你可以通过[创建一个带有 `__enter__()` 和 `__exit__()` 方法的类](https://docs.python.org/3/reference/datamodel.html#context-managers)来创建上下文管理器。 你也可以在 **FastAPI** 的带有 `yield` 的依赖中，使用依赖函数内部的 `with` 或 `async with` 语句来使用它们： @@ -275,8 +275,8 @@ with open("./somefile.txt") as f: 另一种创建上下文管理器的方式是： -* `@contextlib.contextmanager` 或 -* `@contextlib.asynccontextmanager` +* [`@contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) 或 +* [`@contextlib.asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager) 用它们去装饰一个只包含单个 `yield` 的函数。 diff --git a/docs/zh/docs/tutorial/dependencies/global-dependencies.md b/docs/zh/docs/tutorial/dependencies/global-dependencies.md index e33aab65c..cf083f053 100644 --- a/docs/zh/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/zh/docs/tutorial/dependencies/global-dependencies.md @@ -2,14 +2,14 @@ 有时，我们要为整个应用添加依赖项。 -通过与[将 `dependencies` 添加到*路径操作装饰器*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 类似的方式，可以把依赖项添加至整个 `FastAPI` 应用。 +通过与[将 `dependencies` 添加到*路径操作装饰器*](dependencies-in-path-operation-decorators.md) 类似的方式，可以把依赖项添加至整个 `FastAPI` 应用。 这样一来，就可以为所有*路径操作*应用该依赖项： {* ../../docs_src/dependencies/tutorial012_an_py310.py hl[17] *} -[将 `dependencies` 添加到*路径操作装饰器*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 一章的思路均适用于全局依赖项， 在本例中，这些依赖项可以用于应用中的所有*路径操作*。 +[将 `dependencies` 添加到*路径操作装饰器*](dependencies-in-path-operation-decorators.md) 一章的思路均适用于全局依赖项， 在本例中，这些依赖项可以用于应用中的所有*路径操作*。 ## 为一组路径操作定义依赖项 { #dependencies-for-groups-of-path-operations } -稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。 +稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md)一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，你将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。 diff --git a/docs/zh/docs/tutorial/dependencies/index.md b/docs/zh/docs/tutorial/dependencies/index.md index 7db9ef9d9..939470f40 100644 --- a/docs/zh/docs/tutorial/dependencies/index.md +++ b/docs/zh/docs/tutorial/dependencies/index.md @@ -57,7 +57,7 @@ FastAPI 在 0.95.0 版本中新增了对 `Annotated` 的支持（并开始推荐 如果你的版本较旧，尝试使用 `Annotated` 会报错。 -在使用 `Annotated` 之前，请确保[升级 FastAPI 版本](../../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}到至少 0.95.1。 +在使用 `Annotated` 之前，请确保[升级 FastAPI 版本](../../deployment/versions.md#upgrading-the-fastapi-versions)到至少 0.95.1。 /// @@ -152,7 +152,7 @@ commons: Annotated[dict, Depends(common_parameters)] /// note | 注意 -如果不了解异步，请参阅文档中关于 `async` 和 `await` 的章节：[异步：*“着急了？”*](../../async.md#in-a-hurry){.internal-link target=_blank}。 +如果不了解异步，请参阅文档中关于 `async` 和 `await` 的章节：[异步：*“着急了？”*](../../async.md#in-a-hurry)。 /// diff --git a/docs/zh/docs/tutorial/encoder.md b/docs/zh/docs/tutorial/encoder.md index 88be49749..8327ab6c7 100644 --- a/docs/zh/docs/tutorial/encoder.md +++ b/docs/zh/docs/tutorial/encoder.md @@ -12,7 +12,7 @@ 例如，它不接收`datetime`这类的对象，因为这些对象与JSON不兼容。 -因此，`datetime`对象必须转换为包含ISO 格式的`str`类型对象。 +因此，`datetime`对象必须转换为包含[ISO 格式](https://en.wikipedia.org/wiki/ISO_8601)的`str`类型对象。 同样，这个数据库也不会接收Pydantic模型（带有属性的对象），而只接收`dict`。 @@ -24,7 +24,7 @@ 在这个例子中，它将Pydantic模型转换为`dict`，并将`datetime`转换为`str`。 -调用它的结果后就可以使用Python标准编码中的`json.dumps()`。 +调用它的结果后就可以使用Python标准编码中的[`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps)。 这个操作不会返回一个包含JSON格式（作为字符串）数据的庞大的`str`。它将返回一个Python标准数据结构（例如`dict`），其值和子值都与JSON兼容。 diff --git a/docs/zh/docs/tutorial/extra-data-types.md b/docs/zh/docs/tutorial/extra-data-types.md index 2cefd163d..76748a7a3 100644 --- a/docs/zh/docs/tutorial/extra-data-types.md +++ b/docs/zh/docs/tutorial/extra-data-types.md @@ -36,7 +36,7 @@ * `datetime.timedelta`: * 一个 Python `datetime.timedelta`. * 在请求和响应中将表示为 `float` 代表总秒数。 - * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", 查看文档了解更多信息。 + * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", [查看文档了解更多信息](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers)。 * `frozenset`: * 在请求和响应中，作为 `set` 对待： * 在请求中，列表将被读取，消除重复，并将其转换为一个 `set`。 @@ -49,7 +49,7 @@ * `Decimal`: * 标准的 Python `Decimal`。 * 在请求和响应中被当做 `float` 一样处理。 -* 您可以在这里检查所有有效的 Pydantic 数据类型: Pydantic data types. +* 您可以在这里检查所有有效的 Pydantic 数据类型: [Pydantic data types](https://docs.pydantic.dev/latest/usage/types/types/)。 ## 例子 { #example } diff --git a/docs/zh/docs/tutorial/extra-models.md b/docs/zh/docs/tutorial/extra-models.md index 09baa4731..0ad35cc4f 100644 --- a/docs/zh/docs/tutorial/extra-models.md +++ b/docs/zh/docs/tutorial/extra-models.md @@ -12,7 +12,7 @@ 不要存储用户的明文密码。始终只存储之后可用于校验的“安全哈希”。 -如果你还不了解，可以在[安全性章节](security/simple-oauth2.md#password-hashing){.internal-link target=_blank}中学习什么是“密码哈希”。 +如果你还不了解，可以在[安全性章节](security/simple-oauth2.md#password-hashing)中学习什么是“密码哈希”。 /// @@ -108,7 +108,7 @@ UserInDB(**user_dict) UserInDB(**user_in.model_dump()) ``` -……因为 `user_in.model_dump()` 是 `dict`，在传递给 `UserInDB` 时，把 `**` 加在 `user_in.model_dump()` 前，可以让 Python 进行解包。 +...因为 `user_in.model_dump()` 是 `dict`，在传递给 `UserInDB` 时，把 `**` 加在 `user_in.model_dump()` 前，可以让 Python 进行解包。 这样，就可以用其它 Pydantic 模型中的数据生成 Pydantic 模型。 @@ -120,7 +120,7 @@ UserInDB(**user_in.model_dump()) UserInDB(**user_in.model_dump(), hashed_password=hashed_password) ``` -……输出结果如下： +...输出结果如下： ```Python UserInDB( @@ -162,11 +162,11 @@ UserInDB( 在 OpenAPI 中会用 `anyOf` 表示。 -为此，请使用 Python 标准类型提示 `typing.Union`： +为此，请使用 Python 标准类型提示 [`typing.Union`](https://docs.python.org/3/library/typing.html#typing.Union)： /// note | 注意 -定义 `Union` 类型时，要把更具体的类型写在前面，然后是不太具体的类型。下例中，更具体的 `PlaneItem` 位于 `Union[PlaneItem, CarItem]` 中的 `CarItem` 之前。 +定义 [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) 类型时，要把更具体的类型写在前面，然后是不太具体的类型。下例中，更具体的 `PlaneItem` 位于 `Union[PlaneItem, CarItem]` 中的 `CarItem` 之前。 /// diff --git a/docs/zh/docs/tutorial/first-steps.md b/docs/zh/docs/tutorial/first-steps.md index 4c23807b8..78db1fefc 100644 --- a/docs/zh/docs/tutorial/first-steps.md +++ b/docs/zh/docs/tutorial/first-steps.md @@ -11,7 +11,7 @@
```console -$ fastapi dev main.py +$ fastapi dev FastAPI Starting development server 🚀 @@ -58,7 +58,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ### 查看 { #check-it } -打开浏览器访问 http://127.0.0.1:8000。 +打开浏览器访问 [http://127.0.0.1:8000](http://127.0.0.1:8000)。 你将看到如下的 JSON 响应： @@ -68,17 +68,17 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ### 交互式 API 文档 { #interactive-api-docs } -跳转到 http://127.0.0.1:8000/docs。 +跳转到 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 -你将会看到自动生成的交互式 API 文档（由 Swagger UI 提供）： +你将会看到自动生成的交互式 API 文档（由 [Swagger UI](https://github.com/swagger-api/swagger-ui) 提供）：  ### 可选的 API 文档 { #alternative-api-docs } -前往 http://127.0.0.1:8000/redoc。 +前往 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 -你将会看到可选的自动生成文档 （由 ReDoc 提供）： +你将会看到可选的自动生成文档 （由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）：  @@ -92,7 +92,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) #### API「模式」 { #api-schema } -在这种场景下，OpenAPI 是一种规定如何定义 API 模式的规范。 +在这种场景下，[OpenAPI](https://github.com/OAI/OpenAPI-Specification) 是一种规定如何定义 API 模式的规范。 「模式」的定义包括你的 API 路径，以及它们可能使用的参数等等。 @@ -110,7 +110,7 @@ OpenAPI 为你的 API 定义 API 模式。该模式中包含了你的 API 发送 如果你对原始的 OpenAPI 模式长什么样子感到好奇，FastAPI 自动生成了包含所有 API 描述的 JSON（模式）。 -你可以直接在：http://127.0.0.1:8000/openapi.json 看到它。 +你可以直接在：[http://127.0.0.1:8000/openapi.json](http://127.0.0.1:8000/openapi.json) 看到它。 它将显示以如下内容开头的 JSON： @@ -143,9 +143,58 @@ OpenAPI 为你的 API 定义 API 模式。该模式中包含了你的 API 发送 你还可以使用它自动生成与你的 API 进行通信的客户端代码。例如 web 前端，移动端或物联网嵌入程序。 +### 在 `pyproject.toml` 中配置应用 `entrypoint` { #configure-the-app-entrypoint-in-pyproject-toml } + +你可以在 `pyproject.toml` 文件中配置应用的位置，例如： + +```toml +[tool.fastapi] +entrypoint = "main:app" +``` + +该 `entrypoint` 会告诉 `fastapi` 命令按如下方式导入应用： + +```python +from main import app +``` + +如果你的代码结构如下： + +``` +. +├── backend +│ ├── main.py +│ ├── __init__.py +``` + +那么你可以将 `entrypoint` 设置为： + +```toml +[tool.fastapi] +entrypoint = "backend.main:app" +``` + +这等价于： + +```python +from backend.main import app +``` + +### `fastapi dev` 带路径 { #fastapi-dev-with-path } + +你也可以把文件路径传给 `fastapi dev` 命令，它会尝试推断要使用的 FastAPI 应用对象： + +```console +$ fastapi dev main.py +``` + +但这样每次调用 `fastapi` 命令时都需要记得传入正确的路径。 + +另外，其他工具可能无法找到它，例如 [VS Code 扩展](../editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com)，因此推荐在 `pyproject.toml` 中使用 `entrypoint`。 + ### 部署你的应用（可选） { #deploy-your-app-optional } -你可以选择将 FastAPI 应用部署到 FastAPI Cloud，如果还没有，先去加入候补名单。🚀 +你可以选择将 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)，如果还没有，先去加入候补名单。🚀 如果你已经拥有 **FastAPI Cloud** 账户（我们从候补名单邀请了你 😉），你可以用一条命令部署应用。 @@ -191,7 +240,7 @@ Deploying to FastAPI Cloud... `FastAPI` 是直接从 `Starlette` 继承的类。 -你可以通过 `FastAPI` 使用所有的 Starlette 的功能。 +你可以通过 `FastAPI` 使用所有的 [Starlette](https://www.starlette.dev/) 的功能。 /// @@ -273,7 +322,7 @@ https://example.com/items/foo * 请求路径为 `/` * 使用get操作 -/// info | `@decorator` Info +/// info | `@decorator` 信息 `@something` 语法在 Python 中被称为「装饰器」。 @@ -336,7 +385,7 @@ https://example.com/items/foo /// note -如果你不知道两者的区别，请查阅 [并发: *赶时间吗？*](../async.md#in-a-hurry){.internal-link target=_blank}。 +如果你不知道两者的区别，请查阅 [并发: *赶时间吗？*](../async.md#in-a-hurry)。 /// @@ -352,11 +401,11 @@ https://example.com/items/foo ### 步骤 6：部署 { #step-6-deploy-it } -用一条命令将你的应用部署到 **FastAPI Cloud**：`fastapi deploy`。🎉 +用一条命令将你的应用部署到 **[FastAPI Cloud](https://fastapicloud.com)**：`fastapi deploy`。🎉 #### 关于 FastAPI Cloud { #about-fastapi-cloud } -**FastAPI Cloud** 由 **FastAPI** 的作者和团队打造。 +**[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 的作者和团队打造。 它以最小的投入简化了 **构建**、**部署** 和 **访问** API 的流程。 diff --git a/docs/zh/docs/tutorial/handling-errors.md b/docs/zh/docs/tutorial/handling-errors.md index 9782f3d22..f3a23fab0 100644 --- a/docs/zh/docs/tutorial/handling-errors.md +++ b/docs/zh/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ ## 安装自定义异常处理器 { #install-custom-exception-handlers } -可以使用与 Starlette 相同的异常处理工具添加自定义异常处理器。 +可以使用[与 Starlette 相同的异常处理工具](https://www.starlette.dev/exceptions/)添加自定义异常处理器。 假设有一个自定义异常 `UnicornException`（你自己或你使用的库可能会 `raise` 它）。 diff --git a/docs/zh/docs/tutorial/index.md b/docs/zh/docs/tutorial/index.md index 793458302..8d6cbc7a6 100644 --- a/docs/zh/docs/tutorial/index.md +++ b/docs/zh/docs/tutorial/index.md @@ -10,12 +10,12 @@ 所有代码片段都可以复制后直接使用（它们实际上是经过测试的 Python 文件）。 -要运行任何示例，请将代码复制到 `main.py` 文件中，然后使用以下命令启动 `fastapi dev`： +要运行任何示例，请将代码复制到 `main.py` 文件中，然后启动 `fastapi dev`：```console -$ fastapi dev main.py +$ fastapi dev FastAPI Starting development server 🚀 @@ -62,7 +62,7 @@ $ fastapi dev @@ -76,7 +76,7 @@ $ pip install "fastapi[standard]" /// note | 注意 -当您使用 `pip install "fastapi[standard]"` 安装时，它会附带一些默认的可选标准依赖项，其中包括 `fastapi-cloud-cli`，它可以让您部署到 FastAPI Cloud。 +当您使用 `pip install "fastapi[standard]"` 安装时，它会附带一些默认的可选标准依赖项，其中包括 `fastapi-cloud-cli`，它可以让您部署到 [FastAPI Cloud](https://fastapicloud.com)。 如果您不想安装这些可选依赖，可以选择安装 `pip install fastapi`。 @@ -84,6 +84,12 @@ $ pip install "fastapi[standard]" /// +/// tip | 提示 + +FastAPI 提供了一个[VS Code 官方扩展](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（也支持 Cursor），包含众多功能，例如路径操作浏览器、路径操作搜索、测试中的 CodeLens 导航（从测试跳转到定义），以及从编辑器内进行 FastAPI Cloud 部署和查看日志。 + +/// + ## 进阶用户指南 { #advanced-user-guide } 在本**教程-用户指南**之后，您可以阅读**进阶用户指南**。 diff --git a/docs/zh/docs/tutorial/metadata.md b/docs/zh/docs/tutorial/metadata.md index 7ffaa070c..b761f0888 100644 --- a/docs/zh/docs/tutorial/metadata.md +++ b/docs/zh/docs/tutorial/metadata.md @@ -14,7 +14,7 @@ | `version` | `string` | API 的版本。这是您自己的应用程序的版本，而不是 OpenAPI 的版本。例如 `2.5.0`。 | | `terms_of_service` | `str` | API 服务条款的 URL。如果提供，则必须是 URL。 | | `contact` | `dict` | 公开的 API 的联系信息。它可以包含多个字段。| -| `license_info` | `dict` | 公开的 API 的许可证信息。它可以包含多个字段。
contact字段
参数 类型 描述 namestr联系人/组织的识别名称。 urlstr指向联系信息的 URL。必须采用 URL 格式。 str联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。 | +| `license_info` | `dict` | 公开的 API 的许可证信息。它可以包含多个字段。
license_info字段
参数 类型 描述 namestr必须（如果设置了 license_info）。用于 API 的许可证名称。identifierstrAPI 的 SPDX 许可证表达式。字段 identifier与字段url互斥。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。urlstr用于 API 的许可证的 URL。必须采用 URL 格式。 | 你可以按如下方式设置它们： @@ -76,7 +76,7 @@ /// info | 信息 -阅读更多关于标签的信息[路径操作配置](path-operation-configuration.md#tags){.internal-link target=_blank}。 +阅读更多关于标签的信息[路径操作配置](path-operation-configuration.md#tags)。 /// diff --git a/docs/zh/docs/tutorial/middleware.md b/docs/zh/docs/tutorial/middleware.md index a211a63bd..e7586132f 100644 --- a/docs/zh/docs/tutorial/middleware.md +++ b/docs/zh/docs/tutorial/middleware.md @@ -15,7 +15,7 @@ 如果你有使用 `yield` 的依赖，依赖中的退出代码会在中间件之后运行。 -如果有任何后台任务（会在[后台任务](background-tasks.md){.internal-link target=_blank}一节中介绍，你稍后会看到），它们会在所有中间件之后运行。 +如果有任何后台任务（会在[后台任务](background-tasks.md)一节中介绍，你稍后会看到），它们会在所有中间件之后运行。 /// @@ -35,9 +35,9 @@ /// tip -请记住可以使用 `X-` 前缀添加专有自定义请求头。 +请记住可以[使用 `X-` 前缀](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)添加专有自定义请求头。 -但是如果你有希望让浏览器中的客户端可见的自定义请求头，你需要把它们加到你的 CORS 配置（[CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}）的 `expose_headers` 参数中，参见 Starlette 的 CORS 文档。 +但是如果你有希望让浏览器中的客户端可见的自定义请求头，你需要把它们加到你的 CORS 配置（[CORS（跨域资源共享）](cors.md)）的 `expose_headers` 参数中，参见 [Starlette 的 CORS 文档](https://www.starlette.dev/middleware/#corsmiddleware)。 /// @@ -61,7 +61,7 @@ /// tip -这里我们使用 `time.perf_counter()` 而不是 `time.time()`，因为在这类场景中它可能更精确。🤓 +这里我们使用 [`time.perf_counter()`](https://docs.python.org/3/library/time.html#time.perf_counter) 而不是 `time.time()`，因为在这类场景中它可能更精确。🤓 /// @@ -90,6 +90,6 @@ app.add_middleware(MiddlewareB) ## 其他中间件 { #other-middlewares } -你可以稍后在[高级用户指南：高级中间件](../advanced/middleware.md){.internal-link target=_blank}中阅读更多关于其他中间件的内容。 +你可以稍后在[高级用户指南：高级中间件](../advanced/middleware.md)中阅读更多关于其他中间件的内容。 你将在下一节中了解如何使用中间件处理 CORS。 diff --git a/docs/zh/docs/tutorial/path-operation-configuration.md b/docs/zh/docs/tutorial/path-operation-configuration.md index b3e4ba95c..b9046a13b 100644 --- a/docs/zh/docs/tutorial/path-operation-configuration.md +++ b/docs/zh/docs/tutorial/path-operation-configuration.md @@ -58,7 +58,7 @@ OpenAPI 概图会自动添加标签，供 API 文档接口使用： 描述内容比较长且占用多行时，可以在函数的 docstring 中声明*路径操作*的描述，**FastAPI** 会从中读取。 -文档字符串支持 Markdown，能正确解析和显示 Markdown 的内容，但要注意文档字符串的缩进。 +文档字符串支持 [Markdown](https://en.wikipedia.org/wiki/Markdown)，能正确解析和显示 Markdown 的内容，但要注意文档字符串的缩进。 {* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *} diff --git a/docs/zh/docs/tutorial/path-params-numeric-validations.md b/docs/zh/docs/tutorial/path-params-numeric-validations.md index 608aa69a1..26b91c1d7 100644 --- a/docs/zh/docs/tutorial/path-params-numeric-validations.md +++ b/docs/zh/docs/tutorial/path-params-numeric-validations.md @@ -14,7 +14,7 @@ FastAPI 在 0.95.0 版本添加了对 `Annotated` 的支持（并开始推荐使 如果你使用的是更旧的版本，尝试使用 `Annotated` 会报错。 -请确保在使用 `Annotated` 之前，将 FastAPI 版本[升级](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}到至少 0.95.1。 +请确保在使用 `Annotated` 之前，将 FastAPI 版本[升级](../deployment/versions.md#upgrading-the-fastapi-versions)到至少 0.95.1。 /// @@ -122,7 +122,7 @@ Python 不会对这个 `*` 做任何事，但它会知道之后的所有参数 ## 总结 { #recap } -你能够以与[查询参数和字符串校验](query-params-str-validations.md){.internal-link target=_blank}相同的方式使用 `Query`、`Path`（以及其他你还没见过的类）声明元数据和字符串校验。 +你能够以与[查询参数和字符串校验](query-params-str-validations.md)相同的方式使用 `Query`、`Path`（以及其他你还没见过的类）声明元数据和字符串校验。 而且你还可以声明数值校验： @@ -139,7 +139,7 @@ Python 不会对这个 `*` 做任何事，但它会知道之后的所有参数 /// -/// note | 技术细节 +/// note | 注意 当你从 `fastapi` 导入 `Query`、`Path` 和其他对象时，它们实际上是函数。 diff --git a/docs/zh/docs/tutorial/path-params.md b/docs/zh/docs/tutorial/path-params.md index 06a9f1b44..df9210673 100644 --- a/docs/zh/docs/tutorial/path-params.md +++ b/docs/zh/docs/tutorial/path-params.md @@ -6,7 +6,7 @@ 路径参数 `item_id` 的值会作为参数 `item_id` 传递给你的函数。 -运行示例并访问 http://127.0.0.1:8000/items/foo，可获得如下响应： +运行示例并访问 [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo)，可获得如下响应： ```JSON {"item_id":"foo"} @@ -28,7 +28,7 @@ ## 数据转换 { #data-conversion } -运行示例并访问 http://127.0.0.1:8000/items/3，返回的响应如下： +运行示例并访问 [http://127.0.0.1:8000/items/3](http://127.0.0.1:8000/items/3)，返回的响应如下： ```JSON {"item_id":3} @@ -44,7 +44,7 @@ ## 数据校验 { #data-validation } -通过浏览器访问 http://127.0.0.1:8000/items/foo，接收如下 HTTP 错误信息： +通过浏览器访问 [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo)，接收如下 HTTP 错误信息： ```JSON { @@ -64,7 +64,7 @@ 这是因为路径参数 `item_id` 的值（`"foo"`）的类型不是 `int`。 -值的类型不是 `int` 而是浮点数（`float`）时也会显示同样的错误，比如： http://127.0.0.1:8000/items/4.2 +值的类型不是 `int` 而是浮点数（`float`）时也会显示同样的错误，比如： [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2) /// check | 检查 @@ -78,7 +78,7 @@ ## 文档 { #documentation } -访问 http://127.0.0.1:8000/docs，查看自动生成的交互式 API 文档： +访问 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)，查看自动生成的交互式 API 文档：
license_info字段
参数 类型 描述 namestr必须（如果设置了 license_info）。用于 API 的许可证名称。identifierstrAPI 的 [SPDX](https://spdx.org/licenses/) 许可证表达式。字段 identifier与字段url互斥。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。urlstr用于 API 的许可证的 URL。必须采用 URL 格式。 @@ -92,9 +92,9 @@ ## 基于标准的好处，备选文档 { #standards-based-benefits-alternative-documentation } -**FastAPI** 使用 OpenAPI 生成概图，所以能兼容很多工具。 +**FastAPI** 使用 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) 生成概图，所以能兼容很多工具。 -因此，**FastAPI** 还内置了 ReDoc 生成的备选 API 文档，可在此查看 http://127.0.0.1:8000/redoc： +因此，**FastAPI** 还内置了 ReDoc 生成的备选 API 文档，可在此查看 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)：
@@ -102,7 +102,7 @@ ## Pydantic { #pydantic } -FastAPI 充分地利用了 Pydantic 的优势，用它在后台校验数据。众所周知，Pydantic 擅长的就是数据校验。 +FastAPI 充分地利用了 [Pydantic](https://docs.pydantic.dev/) 的优势，用它在后台校验数据。众所周知，Pydantic 擅长的就是数据校验。 同样，`str`、`float`、`bool` 以及很多复合数据类型都可以使用类型声明。 diff --git a/docs/zh/docs/tutorial/query-params-str-validations.md b/docs/zh/docs/tutorial/query-params-str-validations.md index d41f30226..67a5b4000 100644 --- a/docs/zh/docs/tutorial/query-params-str-validations.md +++ b/docs/zh/docs/tutorial/query-params-str-validations.md @@ -35,13 +35,13 @@ FastAPI 在 0.95.0 版本中添加了对 `Annotated` 的支持（并开始推荐 如果你的版本更旧，使用 `Annotated` 会报错。 -在使用 `Annotated` 之前，请确保先[升级 FastAPI 版本](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}到至少 0.95.1。 +在使用 `Annotated` 之前，请确保先[升级 FastAPI 版本](../deployment/versions.md#upgrading-the-fastapi-versions)到至少 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` 给参数添加元数据吗？ +还记得我之前在[Python 类型简介](../python-types.md#type-hints-with-metadata-annotations)中说过可以用 `Annotated` 给参数添加元数据吗？ 现在正是与 FastAPI 搭配使用它的时候。🚀 @@ -105,7 +105,7 @@ FastAPI 现在会： q: str | None = Query(default=None) ``` -……会让参数变成可选，默认值为 `None`，等同于： +...会让参数变成可选，默认值为 `None`，等同于： ```Python q: str | None = None @@ -133,7 +133,7 @@ q: str | None = Query(default=None, max_length=50) q: Annotated[str, Query(default="rick")] = "morty" ``` -……因为不清楚默认值应该是 `"rick"` 还是 `"morty"`。 +...因为不清楚默认值应该是 `"rick"` 还是 `"morty"`。 因此，你应该这样用（推荐）： @@ -141,7 +141,7 @@ q: Annotated[str, Query(default="rick")] = "morty" q: Annotated[str, Query()] = "rick" ``` -……或者在旧代码库中你会见到： +...或者在旧代码库中你会见到： ```Python q: str = Query(default="rick") @@ -157,7 +157,7 @@ q: str = Query(default="rick") 当你不使用 `Annotated` 而是使用**（旧的）默认值风格**时，如果你在**其他地方**不通过 FastAPI 调用该函数，你必须**记得**给函数传参，否则得到的值会和预期不同（例如得到 `QueryInfo` 之类的对象而不是 `str`）。而你的编辑器不会报错，Python 也不会在调用时报错，只有在函数内部的操作出错时才会暴露问题。 -由于 `Annotated` 可以包含多个元数据标注，你甚至可以用同一个函数与其他工具配合，例如 Typer。🚀 +由于 `Annotated` 可以包含多个元数据标注，你甚至可以用同一个函数与其他工具配合，例如 [Typer](https://typer.tiangolo.com/)。🚀 ## 添加更多校验 { #add-more-validations } @@ -337,7 +337,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems 最接近的有效名称是 `item_query`。 -但你仍然需要它在 URL 中就是 `item-query`…… +但你仍然需要它在 URL 中就是 `item-query`... 这时可以用 `alias` 参数声明一个别名，FastAPI 会用该别名在 URL 中查找参数值： @@ -369,11 +369,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems 在这些情况下，你可以使用**自定义校验函数**，该函数会在正常校验之后应用（例如，在先校验值是 `str` 之后）。 -你可以在 `Annotated` 中使用 Pydantic 的 `AfterValidator` 来实现。 +你可以在 `Annotated` 中使用 [Pydantic 的 `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) 来实现。 /// tip | 提示 -Pydantic 还有 `BeforeValidator` 等。🤓 +Pydantic 还有 [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) 等。🤓 /// @@ -421,7 +421,7 @@ Pydantic 还有 `python-multipart`。 +要接收上传的文件，请先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -请确保你创建一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}、激活它，然后安装，例如： +请确保你创建一个[虚拟环境](../virtual-environments.md)、激活它，然后安装，例如： ```console $ pip install python-multipart @@ -63,8 +63,8 @@ $ pip install python-multipart * 文件会先存储在内存中，直到达到最大上限，超过该上限后会写入磁盘。 * 因此，非常适合处理图像、视频、大型二进制等大文件，而不会占用所有内存。 * 你可以获取上传文件的元数据。 -* 它提供 file-like 的 `async` 接口。 -* 它暴露了一个实际的 Python `SpooledTemporaryFile` 对象，你可以直接传给期望「file-like」对象的其他库。 +* 它提供 [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) 的 `async` 接口。 +* 它暴露了一个实际的 Python [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) 对象，你可以直接传给期望「file-like」对象的其他库。 ### `UploadFile` { #uploadfile } @@ -72,7 +72,7 @@ $ pip install python-multipart * `filename`：上传的原始文件名字符串（`str`），例如 `myimage.jpg`。 * `content_type`：内容类型（MIME 类型 / 媒体类型）的字符串（`str`），例如 `image/jpeg`。 -* `file`：`SpooledTemporaryFile`（一个 file-like 对象）。这是实际的 Python 文件对象，你可以直接传递给其他期望「file-like」对象的函数或库。 +* `file`：[`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile)（一个 [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) 对象）。这是实际的 Python 文件对象，你可以直接传递给其他期望「file-like」对象的函数或库。 `UploadFile` 具有以下 `async` 方法。它们都会在底层调用对应的文件方法（使用内部的 `SpooledTemporaryFile`）。 @@ -97,13 +97,13 @@ contents = await myfile.read() contents = myfile.file.read() ``` -/// note | 注意 +/// note | `async` 技术细节 当你使用这些 `async` 方法时，**FastAPI** 会在线程池中运行相应的文件方法并等待其完成。 /// -/// note | 注意 +/// note | Starlette 技术细节 **FastAPI** 的 `UploadFile` 直接继承自 **Starlette** 的 `UploadFile`，但添加了一些必要的部分，使其与 **Pydantic** 以及 FastAPI 的其他部分兼容。 @@ -115,13 +115,13 @@ HTML 表单（``）向服务器发送数据的方式通常会对数 **FastAPI** 会确保从正确的位置读取这些数据，而不是从 JSON 中读取。 -/// note | 注意 +/// note | 技术细节 当不包含文件时，来自表单的数据通常使用「媒体类型」`application/x-www-form-urlencoded` 编码。 但当表单包含文件时，会编码为 `multipart/form-data`。如果你使用 `File`，**FastAPI** 会知道需要从请求体的正确位置获取文件。 -如果你想进一步了解这些编码和表单字段，请参阅 MDN 关于
POST的 Web 文档。 +如果你想进一步了解这些编码和表单字段，请参阅 [MDN 关于 `POST` 的 Web 文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)。 /// @@ -135,13 +135,13 @@ HTML 表单（``）向服务器发送数据的方式通常会对数 ## 可选文件上传 { #optional-file-upload } -您可以通过使用标准类型注解并将 `None` 作为默认值的方式将一个文件参数设为可选: +你可以通过使用标准类型注解并将 `None` 作为默认值的方式将一个文件参数设为可选: {* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *} ## 带有额外元数据的 `UploadFile` { #uploadfile-with-additional-metadata } -您也可以将 `File()` 与 `UploadFile` 一起使用，例如，设置额外的元数据: +你也可以将 `File()` 与 `UploadFile` 一起使用，例如，设置额外的元数据: {* ../../docs_src/request_files/tutorial001_03_an_py310.py hl[9,15] *} @@ -157,7 +157,7 @@ FastAPI 支持同时上传多个文件。 接收的也是含 `bytes` 或 `UploadFile` 的列表（`list`）。 -/// note | 注意 +/// note | 技术细节 也可以使用 `from starlette.responses import HTMLResponse`。 diff --git a/docs/zh/docs/tutorial/request-form-models.md b/docs/zh/docs/tutorial/request-form-models.md index 63759df08..ec52710a8 100644 --- a/docs/zh/docs/tutorial/request-form-models.md +++ b/docs/zh/docs/tutorial/request-form-models.md @@ -4,9 +4,9 @@ /// info | 信息 -要使用表单，首先安装 `python-multipart`。 +要使用表单，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -确保你创建一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，激活它，然后再安装，例如： +确保你创建一个[虚拟环境](../virtual-environments.md)，激活它，然后再安装，例如： ```console $ pip install python-multipart diff --git a/docs/zh/docs/tutorial/request-forms-and-files.md b/docs/zh/docs/tutorial/request-forms-and-files.md index 484fcd5d6..8e092af0a 100644 --- a/docs/zh/docs/tutorial/request-forms-and-files.md +++ b/docs/zh/docs/tutorial/request-forms-and-files.md @@ -4,9 +4,9 @@ FastAPI 支持同时使用 `File` 和 `Form` 定义文件和表单字段。 /// info | 信息 -接收上传的文件和/或表单数据，首先安装 `python-multipart`。 +接收上传的文件和/或表单数据，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -请先创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再安装，例如： +请先创建并激活一个[虚拟环境](../virtual-environments.md)，然后再安装，例如： ```console $ pip install python-multipart diff --git a/docs/zh/docs/tutorial/request-forms.md b/docs/zh/docs/tutorial/request-forms.md index 1fc305a69..ab82a181a 100644 --- a/docs/zh/docs/tutorial/request-forms.md +++ b/docs/zh/docs/tutorial/request-forms.md @@ -4,9 +4,9 @@ /// info -要使用表单，首先安装 `python-multipart`。 +要使用表单，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -请先创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再进行安装，例如： +请先创建并激活一个[虚拟环境](../virtual-environments.md)，然后再进行安装，例如： ```console $ pip install python-multipart @@ -28,7 +28,7 @@ $ pip install python-multipart 例如，在 OAuth2 规范的一种使用方式（称为“密码流”）中，要求将 `username` 和 `password` 作为表单字段发送。 -规范 要求这些字段必须精确命名为 `username` 和 `password`，并且作为表单字段发送，而不是 JSON。 +规范要求这些字段必须精确命名为 `username` 和 `password`，并且作为表单字段发送，而不是 JSON。 使用 `Form` 可以像使用 `Body`（以及 `Query`、`Path`、`Cookie`）一样声明相同的配置，包括校验、示例、别名（例如将 `username` 写成 `user-name`）等。 @@ -56,7 +56,7 @@ HTML 表单（``）向服务器发送数据时通常会对数据使 但当表单包含文件时，会编码为 `multipart/form-data`。你将在下一章阅读如何处理文件。 -如果你想了解更多关于这些编码和表单字段的信息，请参阅 MDN Web 文档的POST。 +如果你想了解更多关于这些编码和表单字段的信息，请参阅 [MDN Web 文档的 `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)。 /// diff --git a/docs/zh/docs/tutorial/response-model.md b/docs/zh/docs/tutorial/response-model.md index df0afa66f..9b4e0382e 100644 --- a/docs/zh/docs/tutorial/response-model.md +++ b/docs/zh/docs/tutorial/response-model.md @@ -13,6 +13,7 @@ FastAPI 会使用这个返回类型来： * 在 OpenAPI 的*路径操作*中为响应添加**JSON Schema**。 * 它会被**自动文档**使用。 * 它也会被自动客户端代码生成工具使用。 +* 使用 Pydantic 将返回数据**序列化**为 JSON。Pydantic 使用**Rust**编写，因此会**快很多**。 但更重要的是： @@ -73,9 +74,9 @@ FastAPI 会使用这个 `response_model` 来完成数据文档、校验等，并 /// info | 信息 -要使用 `EmailStr`，首先安装 `email-validator`。 +要使用 `EmailStr`，首先安装 [`email-validator`](https://github.com/JoshData/python-email-validator)。 -请先创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后安装，例如： +请先创建并激活一个[虚拟环境](../virtual-environments.md)，然后安装，例如： ```console $ pip install email-validator @@ -181,7 +182,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承 ### 直接返回 Response { #return-a-response-directly } -最常见的情况是[直接返回 Response，详见进阶文档](../advanced/response-directly.md){.internal-link target=_blank}。 +最常见的情况是[直接返回 Response，详见进阶文档](../advanced/response-directly.md)。 {* ../../docs_src/response_model/tutorial003_02_py310.py hl[8,10:11] *} @@ -257,7 +258,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承 * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -详见 Pydantic 文档中对 `exclude_defaults` 和 `exclude_none` 的说明。 +详见 [Pydantic 文档](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict)中对 `exclude_defaults` 和 `exclude_none` 的说明。 /// diff --git a/docs/zh/docs/tutorial/response-status-code.md b/docs/zh/docs/tutorial/response-status-code.md index 266f919ba..e57c0e593 100644 --- a/docs/zh/docs/tutorial/response-status-code.md +++ b/docs/zh/docs/tutorial/response-status-code.md @@ -20,7 +20,7 @@ /// info | 信息 -`status_code` 还能接收 `IntEnum` 类型，比如 Python 的 `http.HTTPStatus`。 +`status_code` 还能接收 `IntEnum` 类型，比如 Python 的 [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus)。 /// @@ -66,7 +66,7 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 /// tip | 提示 -状态码及适用场景的详情，请参阅 MDN 的 HTTP 状态码文档。 +想了解每个状态码的更多信息以及适用场景，请参阅 [MDN 的 HTTP 状态码文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)。 /// @@ -98,4 +98,4 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 ## 更改默认状态码 { #changing-the-default } -[高级用户指南](../advanced/response-change-status-code.md){.internal-link target=_blank}中，将介绍如何返回与在此声明的默认状态码不同的状态码。 +稍后在[高级用户指南](../advanced/response-change-status-code.md)中，你将看到如何返回与此处声明的默认状态码不同的状态码。 diff --git a/docs/zh/docs/tutorial/schema-extra-example.md b/docs/zh/docs/tutorial/schema-extra-example.md index ec1fc29e5..482abd21d 100644 --- a/docs/zh/docs/tutorial/schema-extra-example.md +++ b/docs/zh/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ 这些额外信息会原样添加到该模型输出的 JSON Schema 中，并会在 API 文档中使用。 -你可以使用属性 `model_config`，它接收一个 `dict`，详见 Pydantic 文档：配置。 +你可以使用属性 `model_config`，它接收一个 `dict`，详见 [Pydantic 文档：配置](https://docs.pydantic.dev/latest/api/config/)。 你可以设置 `"json_schema_extra"`，其值为一个 `dict`，包含你希望出现在生成 JSON Schema 中的任意附加数据，包括 `examples`。 @@ -145,12 +145,12 @@ OpenAPI 3.1.0（自 FastAPI 0.99.0 起使用）增加了对 `examples` 的支持 OpenAPI 还在规范的其他部分添加了 `example` 和 `examples` 字段： -- `Parameter Object`（规范中），被 FastAPI 的以下内容使用： +- [`Parameter Object`（规范中）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object)，被 FastAPI 的以下内容使用： - `Path()` - `Query()` - `Header()` - `Cookie()` -- `Request Body Object` 中的 `content` 字段里的 `Media Type Object`（规范中），被 FastAPI 的以下内容使用： +- [`Request Body Object` 中的 `content` 字段里的 `Media Type Object`（规范中）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)，被 FastAPI 的以下内容使用： - `Body()` - `File()` - `Form()` @@ -163,7 +163,7 @@ OpenAPI 还在规范的其他部分添加了 `example` 和 `examples` 字段： ### JSON Schema 的 `examples` 字段 { #json-schemas-examples-field } -后来，JSON Schema 在新版本的规范中添加了 `examples` 字段。 +后来，JSON Schema 在新版本的规范中添加了 [`examples`](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5) 字段。 随后新的 OpenAPI 3.1.0 基于最新版本（JSON Schema 2020-12），其中包含了这个新的 `examples` 字段。 diff --git a/docs/zh/docs/tutorial/security/first-steps.md b/docs/zh/docs/tutorial/security/first-steps.md index 8b1aeb70b..6cc91211a 100644 --- a/docs/zh/docs/tutorial/security/first-steps.md +++ b/docs/zh/docs/tutorial/security/first-steps.md @@ -26,11 +26,11 @@ /// info | 信息 -当你使用命令 `pip install "fastapi[standard]"` 安装 **FastAPI** 时，`python-multipart` 包会自动安装。 +当你使用命令 `pip install "fastapi[standard]"` 安装 **FastAPI** 时，[`python-multipart`](https://github.com/Kludex/python-multipart) 包会自动安装。 但是，如果你使用 `pip install fastapi`，默认不会包含 `python-multipart` 包。 -如需手动安装，请先创建并激活[虚拟环境](../../virtual-environments.md){.internal-link target=_blank}，然后执行： +如需手动安装，请先创建并激活[虚拟环境](../../virtual-environments.md)，然后执行： ```console $ pip install python-multipart @@ -45,7 +45,7 @@ $ pip install python-multipart```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -54,7 +54,7 @@ $ fastapi dev main.py ## 查看 { #check-it } -打开交互式文档：http://127.0.0.1:8000/docs。 +打开交互式文档：[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 你会看到类似这样的界面： @@ -140,7 +140,7 @@ OAuth2 的设计目标是让后端或 API 与负责用户认证的服务器解 因为使用的是相对 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)等高级用例中依然正常工作。 /// diff --git a/docs/zh/docs/tutorial/security/oauth2-jwt.md b/docs/zh/docs/tutorial/security/oauth2-jwt.md index b5ccfd3e3..8a56137d3 100644 --- a/docs/zh/docs/tutorial/security/oauth2-jwt.md +++ b/docs/zh/docs/tutorial/security/oauth2-jwt.md @@ -24,13 +24,13 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 一周后令牌过期，用户将不再被授权，需要重新登录以获取新令牌。而如果用户（或第三方）尝试修改令牌来更改过期时间，你也能发现，因为签名将不匹配。 -如果你想动手体验 JWT 令牌并了解它的工作方式，请访问 https://jwt.io。 +如果你想动手体验 JWT 令牌并了解它的工作方式，请访问 [https://jwt.io](https://jwt.io/)。 ## 安装 `PyJWT` { #install-pyjwt } 我们需要安装 `PyJWT`，以便在 Python 中生成和校验 JWT 令牌。 -请确保创建并激活一个[虚拟环境](../../virtual-environments.md){.internal-link target=_blank}，然后安装 `pyjwt`： +请确保创建并激活一个[虚拟环境](../../virtual-environments.md)，然后安装 `pyjwt`：@@ -46,7 +46,7 @@ $ pip install pyjwt 如果你计划使用类似 RSA 或 ECDSA 的数字签名算法，你应该安装加密库依赖项 `pyjwt[crypto]`。 -可以在 PyJWT 安装文档中了解更多。 +可以在 [PyJWT 安装文档](https://pyjwt.readthedocs.io/en/latest/installation.html)中了解更多。 /// @@ -72,7 +72,7 @@ pwdlib 是一个用于处理密码哈希的优秀 Python 包。 推荐的算法是 “Argon2”。 -请确保创建并激活一个[虚拟环境](../../virtual-environments.md){.internal-link target=_blank}，然后安装带 Argon2 的 pwdlib： +请确保创建并激活一个[虚拟环境](../../virtual-environments.md)，然后安装带 Argon2 的 pwdlib：@@ -200,7 +200,7 @@ JWT 除了用于识别用户并允许其直接在你的 API 上执行操作之 ## 检查 { #check-it } -运行服务器并打开文档：http://127.0.0.1:8000/docs。 +运行服务器并打开文档：[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 你会看到这样的用户界面： diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md index 95f708ae6..d8d5b561e 100644 --- a/docs/zh/docs/tutorial/security/simple-oauth2.md +++ b/docs/zh/docs/tutorial/security/simple-oauth2.md @@ -146,7 +146,7 @@ UserInDB( /// info | 信息 -`user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#about-user-in-dict){.internal-link target=_blank}。 +`user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#about-user-in-dict)。 /// @@ -216,7 +216,7 @@ UserInDB( ## 实际效果 { #see-it-in-action } -打开 API 文档：http://127.0.0.1:8000/docs。 +打开交互式文档：[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 ### 身份验证 { #authenticate } diff --git a/docs/zh/docs/tutorial/sql-databases.md b/docs/zh/docs/tutorial/sql-databases.md index ef0b7c460..9004983b1 100644 --- a/docs/zh/docs/tutorial/sql-databases.md +++ b/docs/zh/docs/tutorial/sql-databases.md @@ -2,9 +2,9 @@ **FastAPI** 并不要求你使用 SQL（关系型）数据库。你可以使用你想用的**任何数据库**。 -这里，我们来看一个使用 SQLModel 的示例。 +这里，我们来看一个使用 [SQLModel](https://sqlmodel.tiangolo.com/) 的示例。 -**SQLModel** 基于 SQLAlchemy 和 Pydantic 构建。它由 **FastAPI** 的同一作者制作，旨在完美匹配需要使用**SQL 数据库**的 FastAPI 应用程序。 +**SQLModel** 基于 [SQLAlchemy](https://www.sqlalchemy.org/) 和 Pydantic 构建。它由 **FastAPI** 的同一作者制作，旨在完美匹配需要使用**SQL 数据库**的 FastAPI 应用程序。 /// tip | 提示 @@ -26,15 +26,15 @@ /// tip | 提示 -有一个使用 **FastAPI** 和 **PostgreSQL** 的官方项目生成器，其中包括了前端和更多工具： https://github.com/fastapi/full-stack-fastapi-template +有一个使用 **FastAPI** 和 **PostgreSQL** 的官方项目生成器，其中包括了前端和更多工具： [https://github.com/fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template) /// -这是一个非常简单和简短的教程。如果你想了解一般的数据库、SQL 或更高级的功能，请查看 SQLModel 文档。 +这是一个非常简单和简短的教程。如果你想了解一般的数据库、SQL 或更高级的功能，请查看 [SQLModel 文档](https://sqlmodel.tiangolo.com/)。 ## 安装 `SQLModel` { #install-sqlmodel } -首先，确保你创建并激活了[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后安装 `sqlmodel`： +首先，确保你创建并激活了[虚拟环境](../virtual-environments.md)，然后安装 `sqlmodel`：@@ -65,7 +65,7 @@ $ pip install sqlmodel * `Field(primary_key=True)` 会告诉 SQLModel `id` 是 SQL 数据库中的**主键**（你可以在 SQLModel 文档中了解更多关于 SQL 主键的信息）。 - **注意：** 我们为主键字段使用 `int | None`，这样在 Python 代码中我们可以在没有 `id`（`id=None`）的情况下创建对象，并假定数据库在保存时会生成它。SQLModel 会理解数据库会提供 `id`，并在数据库模式中将该列定义为非空的 `INTEGER`。详见 SQLModel 关于主键的文档。 + **注意：** 我们为主键字段使用 `int | None`，这样在 Python 代码中我们可以在没有 `id`（`id=None`）的情况下创建对象，并假定数据库在保存时会生成它。SQLModel 会理解数据库会提供 `id`，并在数据库模式中将该列定义为非空的 `INTEGER`。详见 [SQLModel 关于主键的文档](https://sqlmodel.tiangolo.com/tutorial/create-db-and-table/#primary-key-id)。 * `Field(index=True)` 会告诉 SQLModel 应该为此列创建一个 **SQL 索引**，这样在读取按此列过滤的数据时，程序能在数据库中进行更快的查找。 @@ -111,7 +111,7 @@ SQLModel 的 `engine`（实际上它是一个 SQLAlchemy 的 `engine`）是用 /// tip | 提示 -SQLModel 将会拥有封装 Alembic 的迁移工具，但目前你可以直接使用 Alembic。 +SQLModel 将会拥有封装 Alembic 的迁移工具，但目前你可以直接使用 [Alembic](https://alembic.sqlalchemy.org/en/latest/)。 /// @@ -152,7 +152,7 @@ SQLModel 将会拥有封装 Alembic 的迁移工具，但目前你可以直接```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ $ fastapi dev main.py```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -352,6 +352,6 @@ $ fastapi dev main.py ## 总结 { #recap } -你可以使用 **SQLModel** 与 SQL 数据库进行交互，并通过*数据模型*和*表模型*简化代码。 +你可以使用 [**SQLModel**](https://sqlmodel.tiangolo.com/) 与 SQL 数据库进行交互，并通过*数据模型*和*表模型*简化代码。 -你可以在 **SQLModel** 文档中学习到更多内容，其中有一个更详细的将 SQLModel 与 **FastAPI** 一起使用的迷你教程。🚀 +你可以在 **SQLModel** 文档中学习到更多内容，其中有一个更详细的[将 SQLModel 与 **FastAPI** 一起使用的迷你教程](https://sqlmodel.tiangolo.com/tutorial/fastapi/)。🚀 diff --git a/docs/zh/docs/tutorial/static-files.md b/docs/zh/docs/tutorial/static-files.md index 1f4ebae9a..65262bdb4 100644 --- a/docs/zh/docs/tutorial/static-files.md +++ b/docs/zh/docs/tutorial/static-files.md @@ -23,7 +23,7 @@ 这与使用 `APIRouter` 不同，因为挂载的应用是完全独立的。主应用的 OpenAPI 和文档不会包含已挂载应用的任何内容，等等。 -你可以在[高级用户指南](../advanced/index.md){.internal-link target=_blank}中了解更多。 +你可以在[高级用户指南](../advanced/index.md)中了解更多。 ## 细节 { #details } @@ -37,4 +37,4 @@ ## 更多信息 { #more-info } -更多细节和选项请查阅 Starlette 的静态文件文档。 +更多细节和选项请查阅 [Starlette 的静态文件文档](https://www.starlette.dev/staticfiles/)。 diff --git a/docs/zh/docs/tutorial/testing.md b/docs/zh/docs/tutorial/testing.md index 7eb32f19e..6607a1239 100644 --- a/docs/zh/docs/tutorial/testing.md +++ b/docs/zh/docs/tutorial/testing.md @@ -1,18 +1,18 @@ # 测试 { #testing } -感谢 Starlette，测试**FastAPI** 应用轻松又愉快。 +感谢 [Starlette](https://www.starlette.dev/testclient/)，测试**FastAPI** 应用轻松又愉快。 -它基于 HTTPX， 而HTTPX又是基于Requests设计的，所以很相似且易懂。 +它基于 [HTTPX](https://www.python-httpx.org)，而HTTPX又是基于Requests设计的，所以很相似且易懂。 -有了它，你可以直接与**FastAPI**一起使用 pytest。 +有了它，你可以直接与**FastAPI**一起使用 [pytest](https://docs.pytest.org/)。 ## 使用 `TestClient` { #using-testclient } /// info | 信息 -要使用 `TestClient`，先要安装 `httpx`。 +要使用 `TestClient`，先要安装 [`httpx`](https://www.python-httpx.org)。 -确保你创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再安装，例如： +确保你创建并激活一个[虚拟环境](../virtual-environments.md)，然后再安装，例如： ```console $ pip install httpx @@ -52,7 +52,7 @@ $ pip install httpx /// tip | 提示 -除了发送请求之外，如果你还想测试时在FastAPI应用中调用 `async` 函数（例如异步数据库函数）， 可以在高级教程中看下 [Async Tests](../advanced/async-tests.md){.internal-link target=_blank} 。 +除了发送请求之外，如果你还想测试时在FastAPI应用中调用 `async` 函数（例如异步数据库函数）， 可以在高级教程中看下 [Async Tests](../advanced/async-tests.md) 。 /// @@ -64,7 +64,7 @@ $ pip install httpx ### **FastAPI** app 文件 { #fastapi-app-file } -假设你有一个像 [更大的应用](bigger-applications.md){.internal-link target=_blank} 中所描述的文件结构: +假设你有一个像[更大的应用](bigger-applications.md)中所描述的文件结构: ``` . @@ -112,7 +112,7 @@ $ pip install httpx │ └── test_main.py ``` -假设现在包含**FastAPI** app的文件 `main.py` 有些其他**路径操作**。 +假设现在包含**FastAPI** app的文件 `main.py` 有些其他**路径操作**。 有个 `GET` 操作会返回错误。 @@ -128,7 +128,7 @@ $ pip install httpx {* ../../docs_src/app_testing/app_b_an_py310/test_main.py *} -每当你需要客户端在请求中传递信息，但你不知道如何传递时，你可以通过搜索（谷歌）如何用 `httpx`做，或者是用 `requests` 做，毕竟HTTPX的设计是基于Requests的设计的。 +每当你需要客户端在请求中传递信息，但你不知道如何传递时，你可以通过搜索（谷歌）如何用 `httpx` 做，或者是用 `requests` 做，毕竟HTTPX的设计是基于Requests的设计的。 接着只需在测试中同样操作。 @@ -140,13 +140,13 @@ $ pip install httpx * 要发送 *headers*，传 `dict` 给 `headers` 参数。 * 对于 *cookies*，传 `dict` 给 `cookies` 参数。 -关于如何传数据给后端的更多信息 (使用`httpx` 或 `TestClient`)，请查阅 HTTPX 文档. +关于如何传数据给后端的更多信息（使用 `httpx` 或 `TestClient`），请查阅 [HTTPX 文档](https://www.python-httpx.org)。 /// info | 信息 注意 `TestClient` 接收可以被转化为JSON的数据，而不是Pydantic模型。 -如果你在测试中有一个Pydantic模型，并且你想在测试时发送它的数据给应用，你可以使用在[JSON Compatible Encoder](encoder.md){.internal-link target=_blank}介绍的`jsonable_encoder` 。 +如果你在测试中有一个Pydantic模型，并且你想在测试时发送它的数据给应用，你可以使用在[JSON Compatible Encoder](encoder.md)介绍的`jsonable_encoder` 。 /// @@ -154,7 +154,7 @@ $ pip install httpx 之后，你只需要安装 `pytest`。 -确保你创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再安装，例如： +确保你创建并激活一个[虚拟环境](../virtual-environments.md)，然后再安装，例如：diff --git a/docs/zh/docs/virtual-environments.md b/docs/zh/docs/virtual-environments.md index 60fb9e23f..14ee53863 100644 --- a/docs/zh/docs/virtual-environments.md +++ b/docs/zh/docs/virtual-environments.md @@ -22,7 +22,7 @@ 这个页面将教你如何使用**虚拟环境**以及了解它们的工作原理。 -如果你计划使用一个**可以为你管理一切的工具**（包括安装 Python），试试 uv。 +如果你计划使用一个**可以为你管理一切的工具**（包括安装 Python），试试 [uv](https://github.com/astral-sh/uv)。 /// @@ -86,7 +86,7 @@ $ python -m venv .venv //// tab | `uv` -如果你安装了 `uv`，你也可以使用它来创建一个虚拟环境。 +如果你安装了 [`uv`](https://github.com/astral-sh/uv)，你也可以使用它来创建一个虚拟环境。@@ -150,7 +150,7 @@ $ .venv\Scripts\Activate.ps1 //// tab | Windows Bash -或者，如果你在 Windows 上使用 Bash（例如 Git Bash）： +或者，如果你在 Windows 上使用 Bash（例如 [Git Bash](https://gitforwindows.org/)）：@@ -216,7 +216,7 @@ C:\Users\user\code\awesome-project\.venv\Scripts\python /// tip | 提示 -如果你使用 `uv` 来安装内容，而不是 `pip`，那么你就不需要升级 `pip`。😎 +如果你使用 [`uv`](https://github.com/astral-sh/uv) 来安装内容，而不是 `pip`，那么你就不需要升级 `pip`。😎 /// @@ -268,7 +268,7 @@ $ python -m ensurepip --upgrade /// tip | 提示 -如果你使用 `uv` 来创建虚拟环境，它会自动为你完成这个操作，你可以跳过这一步。😎 +如果你使用 [`uv`](https://github.com/astral-sh/uv) 来创建虚拟环境，它会自动为你完成这个操作，你可以跳过这一步。😎 /// @@ -340,7 +340,7 @@ $ pip install "fastapi[standard]" //// tab | `uv` -如果你有 `uv`: +如果你有 [`uv`](https://github.com/astral-sh/uv):@@ -372,7 +372,7 @@ $ pip install -r requirements.txt //// tab | `uv` -如果你有 `uv`: +如果你有 [`uv`](https://github.com/astral-sh/uv):@@ -416,8 +416,8 @@ Hello World 例如： -* VS Code -* PyCharm +* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) +* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) /// tip | 提示 @@ -455,7 +455,7 @@ $ deactivate ## 为什么要使用虚拟环境 { #why-virtual-environments } -你需要安装 Python 才能使用 FastAPI。 +你需要安装 [Python](https://www.python.org/) 才能使用 FastAPI。 之后，你需要**安装** FastAPI 和你想要使用的任何其他**软件包**。 @@ -564,7 +564,7 @@ $ pip install "fastapi[standard]"-这将会从 PyPI 下载一个压缩文件，其中包含 FastAPI 代码。 +这将会从 [PyPI](https://pypi.org/project/fastapi/) 下载一个压缩文件，其中包含 FastAPI 代码。 它还会**下载** FastAPI 依赖的其他软件包的文件。 @@ -627,7 +627,7 @@ $ .venv\Scripts\Activate.ps1 //// tab | Windows Bash -或者如果你在 Windows 上使用 Bash（例如 Git Bash）： +或者如果你在 Windows 上使用 Bash（例如 [Git Bash](https://gitforwindows.org/)）：@@ -639,13 +639,13 @@ $ source .venv/Scripts/activate //// -这个命令会创建或修改一些[环境变量](environment-variables.md){.internal-link target=_blank}，这些环境变量将在接下来的命令中可用。 +这个命令会创建或修改一些[环境变量](environment-variables.md)，这些环境变量将在接下来的命令中可用。 其中之一是 `PATH` 变量。 /// tip | 提示 -你可以在 [环境变量](environment-variables.md#path-environment-variable){.internal-link target=_blank} 部分了解更多关于 `PATH` 环境变量的内容。 +你可以在 [环境变量](environment-variables.md#path-environment-variable) 部分了解更多关于 `PATH` 环境变量的内容。 /// @@ -846,7 +846,7 @@ I solemnly swear 🐺 有许多**替代方案**来管理虚拟环境、包依赖（requirements）、工程。 -一旦你准备好并想要使用一个工具来**管理整个工程**、包依赖、虚拟环境等，建议你尝试 uv。 +一旦你准备好并想要使用一个工具来**管理整个工程**、包依赖、虚拟环境等，建议你尝试 [uv](https://github.com/astral-sh/uv)。 `uv` 可以做很多事情，它可以：
