From 69a8996a92767842b8d7207acb9f1448428a9850 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 20 Mar 2026 16:41:07 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20for=20zh?= =?UTF-8?q?=20(update-outdated)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../docs/advanced/additional-status-codes.md | 6 +-- docs/zh/docs/advanced/generate-clients.md | 16 +++---- docs/zh/docs/advanced/response-cookies.md | 4 +- docs/zh/docs/advanced/response-directly.md | 29 ++++++++++-- .../docs/advanced/security/http-basic-auth.md | 2 +- docs/zh/docs/advanced/security/index.md | 4 +- .../docs/advanced/using-request-directly.md | 4 +- docs/zh/docs/deployment/cloud.md | 8 ++-- docs/zh/docs/deployment/concepts.md | 10 ++-- docs/zh/docs/deployment/docker.md | 46 +++++++++---------- docs/zh/docs/deployment/fastapicloud.md | 4 +- docs/zh/docs/deployment/https.md | 16 +++---- docs/zh/docs/deployment/index.md | 2 +- docs/zh/docs/deployment/manually.md | 12 ++--- docs/zh/docs/deployment/server-workers.md | 22 ++++----- docs/zh/docs/deployment/versions.md | 6 +-- .../authentication-error-status-code.md | 2 +- docs/zh/docs/how-to/conditional-openapi.md | 2 +- docs/zh/docs/how-to/configure-swagger-ui.md | 6 +-- docs/zh/docs/how-to/custom-docs-ui-assets.md | 12 ++--- .../docs/how-to/custom-request-and-route.md | 8 ++-- docs/zh/docs/how-to/extending-openapi.md | 4 +- docs/zh/docs/how-to/general.md | 22 +++++---- docs/zh/docs/how-to/graphql.md | 30 ++++++------ docs/zh/docs/how-to/index.md | 2 +- ...migrate-from-pydantic-v1-to-pydantic-v2.md | 6 +-- docs/zh/docs/how-to/testing-database.md | 6 +-- 27 files changed, 157 insertions(+), 134 deletions(-) diff --git a/docs/zh/docs/advanced/additional-status-codes.md b/docs/zh/docs/advanced/additional-status-codes.md index 7eeffaf532..af212ad8b1 100644 --- a/docs/zh/docs/advanced/additional-status-codes.md +++ b/docs/zh/docs/advanced/additional-status-codes.md @@ -16,7 +16,7 @@ {* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *} -/// warning | 警告 +/// warning 当你直接返回一个像上面例子中的 `Response` 对象时，它会直接返回。 @@ -26,7 +26,7 @@ /// -/// note | 注意 +/// note | 技术细节 你也可以使用 `from starlette.responses import JSONResponse`。　 @@ -38,4 +38,4 @@ 如果你直接返回额外的状态码和响应，它们不会包含在 OpenAPI 方案（API 文档）中，因为 FastAPI 没办法预先知道你要返回什么。 -但是你可以使用 [额外的响应](additional-responses.md){.internal-link target=_blank} 在代码中记录这些内容。 +但是你可以使用 [额外的响应](additional-responses.md) 在代码中记录这些内容。 diff --git a/docs/zh/docs/advanced/generate-clients.md b/docs/zh/docs/advanced/generate-clients.md index e8a3b20558..5f53aa4347 100644 --- a/docs/zh/docs/advanced/generate-clients.md +++ b/docs/zh/docs/advanced/generate-clients.md @@ -8,11 +8,11 @@ ## 开源 SDK 生成器 { #open-source-sdk-generators } -一个功能多样的选择是 OpenAPI Generator，它支持**多种编程语言**，可以根据你的 OpenAPI 规范生成 SDK。 +一个功能多样的选择是 [OpenAPI Generator](https://openapi-generator.tech/)，它支持**多种编程语言**，可以根据你的 OpenAPI 规范生成 SDK。 -对于 **TypeScript 客户端**，Hey API 是为 TypeScript 生态打造的专用方案，提供优化的使用体验。 +对于 **TypeScript 客户端**，[Hey API](https://heyapi.dev/) 是为 TypeScript 生态打造的专用方案，提供优化的使用体验。 -你还可以在 OpenAPI.Tools 上发现更多 SDK 生成器。 +你还可以在 [OpenAPI.Tools](https://openapi.tools/#sdk) 上发现更多 SDK 生成器。 /// tip | 提示 @@ -24,15 +24,15 @@ FastAPI 会自动生成 **OpenAPI 3.1** 规范，因此你使用的任何工具 本节介绍的是由赞助 FastAPI 的公司提供的、具备**风险投资背景**或**公司支持**的方案。这些产品在高质量生成的 SDK 之上，提供了**更多特性**和**集成**。 -通过 ✨ [**赞助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨，这些公司帮助确保框架及其**生态**保持健康并且**可持续**。 +通过 ✨ [**赞助 FastAPI**](../help-fastapi.md#sponsor-the-author) ✨，这些公司帮助确保框架及其**生态**保持健康并且**可持续**。 他们的赞助也体现了对 FastAPI **社区**（也就是你）的高度承诺，不仅关注提供**优秀的服务**，也支持一个**健壮且繁荣的框架**——FastAPI。🙇 例如，你可以尝试： -* Speakeasy -* Stainless -* liblab +* [Speakeasy](https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship) +* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral) +* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi) 其中一些方案也可能是开源的或提供免费层级，你可以不花钱就先试用。其他商业 SDK 生成器也可在网上找到。🤓 @@ -66,7 +66,7 @@ npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client 这会在 `./src/client` 生成一个 TypeScript SDK。 -你可以在其官网了解如何安装 `@hey-api/openapi-ts`，以及阅读生成结果的说明。 +你可以在其官网了解如何[安装 `@hey-api/openapi-ts`](https://heyapi.dev/openapi-ts/get-started)，以及阅读[生成结果](https://heyapi.dev/openapi-ts/output)的说明。 ### 使用 SDK { #using-the-sdk } diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md index c618cd0f0a..7fad89e5c6 100644 --- a/docs/zh/docs/advanced/response-cookies.md +++ b/docs/zh/docs/advanced/response-cookies.md @@ -18,7 +18,7 @@ 你还可以在直接响应`Response`时直接创建cookies。 -你可以参考[直接返回 Response](response-directly.md){.internal-link target=_blank}来创建response +为此，你可以按照[直接返回 Response](response-directly.md)中的说明创建一个响应。 然后设置Cookies，并返回： @@ -46,4 +46,4 @@ /// -如果你想查看所有可用的参数和选项，可以参考 Starlette帮助文档 +如果你想查看所有可用的参数和选项，可以参考 [Starlette 文档](https://www.starlette.dev/responses/#set-cookie)。 diff --git a/docs/zh/docs/advanced/response-directly.md b/docs/zh/docs/advanced/response-directly.md index a97992d249..1966221467 100644 --- a/docs/zh/docs/advanced/response-directly.md +++ b/docs/zh/docs/advanced/response-directly.md @@ -2,19 +2,24 @@ 当你创建一个 **FastAPI** *路径操作* 时，你可以正常返回以下任意一种数据：`dict`，`list`，Pydantic 模型，数据库模型等等。 -**FastAPI** 默认会使用 `jsonable_encoder` 将这些类型的返回值转换成 JSON 格式，`jsonable_encoder` 在 [JSON 兼容编码器](../tutorial/encoder.md){.internal-link target=_blank} 中有阐述。 +如果你声明了 [响应模型](../tutorial/response-model.md)，FastAPI 会使用它通过 Pydantic 将数据序列化为 JSON。 +如果你没有声明响应模型，**FastAPI** 会使用在 [JSON 兼容编码器](../tutorial/encoder.md) 中阐述的 `jsonable_encoder`。 然后，**FastAPI** 会在后台将这些兼容 JSON 的数据（比如字典）放到一个 `JSONResponse` 中，该 `JSONResponse` 会用来发送响应给客户端。 但是你可以在你的 *路径操作* 中直接返回一个 `JSONResponse`。 -直接返回响应可能会有用处，比如返回自定义的响应头和 cookies。 +/// tip | 提示 + +通常使用 [响应模型](../tutorial/response-model.md) 会比直接返回 `JSONResponse` 拥有更好的性能，因为它会在 Rust 中使用 Pydantic 序列化数据。 + +/// ## 返回 `Response` { #return-a-response } 事实上，你可以返回任意 `Response` 或者任意 `Response` 的子类。 -/// tip | 提示 +/// info | 信息 `JSONResponse` 本身是一个 `Response` 的子类。 @@ -26,6 +31,8 @@ 这种特性给你极大的可扩展性。你可以返回任何数据类型，重写任何数据声明或者校验，等等。 +这也带来了很大的责任。你必须确保你返回的数据是正确的、格式正确、可被序列化，等等。 + ## 在 `Response` 中使用 `jsonable_encoder` { #using-the-jsonable-encoder-in-a-response } 由于 **FastAPI** 并未对你返回的 `Response` 做任何改变，你必须确保你已经准备好响应内容。 @@ -50,16 +57,28 @@ 现在，让我们看看你如何才能返回一个自定义的响应。 -假设你想要返回一个 XML 响应。 +假设你想要返回一个 [XML](https://en.wikipedia.org/wiki/XML) 响应。 你可以把你的 XML 内容放到一个字符串中，放到一个 `Response` 中，然后返回： {* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *} +## 响应模型如何工作 { #how-a-response-model-works } + +当你在路径操作中声明一个 [响应模型 - 返回类型](../tutorial/response-model.md) 时，**FastAPI** 会使用它通过 Pydantic 将数据序列化为 JSON。 + +{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} + +由于这些工作会在 Rust 侧完成，性能将比在常规 Python 中配合 `JSONResponse` 类完成要好得多。 + +当使用 `response_model` 或返回类型时，FastAPI 不会使用 `jsonable_encoder` 来转换数据（那样会更慢），也不会使用 `JSONResponse` 类。 + +相反，它会采用使用该响应模型（或返回类型）由 Pydantic 生成的 JSON 字节，并直接返回一个具有正确 JSON 媒体类型（`application/json`）的 `Response`。 + ## 说明 { #notes } 当你直接返回 `Response` 时，它的数据既没有校验，又不会进行转换（序列化），也不会自动生成文档。 -但是你仍可以参考 [OpenAPI 中的额外响应](additional-responses.md){.internal-link target=_blank} 给响应编写文档。 +但是你仍可以参考 [OpenAPI 中的额外响应](additional-responses.md) 给响应编写文档。 在后续的章节中你可以了解到如何使用/声明这些自定义的 `Response` 的同时还保留自动化的数据转换和文档等。 diff --git a/docs/zh/docs/advanced/security/http-basic-auth.md b/docs/zh/docs/advanced/security/http-basic-auth.md index 9128a49753..37e4b5abcb 100644 --- a/docs/zh/docs/advanced/security/http-basic-auth.md +++ b/docs/zh/docs/advanced/security/http-basic-auth.md @@ -32,7 +32,7 @@ HTTP 基础授权让浏览器显示内置的用户名与密码提示。 使用依赖项检查用户名与密码是否正确。 -为此要使用 Python 标准模块 `secrets` 检查用户名与密码。 +为此要使用 Python 标准模块 [`secrets`](https://docs.python.org/3/library/secrets.html) 检查用户名与密码。 `secrets.compare_digest()` 需要仅包含 ASCII 字符（英语字符）的 `bytes` 或 `str`，这意味着它不适用于像`á`一样的字符，如 `Sebastián`。 diff --git a/docs/zh/docs/advanced/security/index.md b/docs/zh/docs/advanced/security/index.md index 84fec7aab8..e3a3ba9cea 100644 --- a/docs/zh/docs/advanced/security/index.md +++ b/docs/zh/docs/advanced/security/index.md @@ -2,7 +2,7 @@ ## 附加特性 { #additional-features } -除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank} 中涵盖的功能之外，还有一些额外的功能来处理安全性。 +除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md) 中涵盖的功能之外，还有一些额外的功能来处理安全性。 /// tip | 提示 @@ -14,6 +14,6 @@ ## 先阅读教程 { #read-the-tutorial-first } -接下来的部分假设你已经阅读了主要的 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank}。 +接下来的部分假设你已经阅读了主要的 [教程 - 用户指南: 安全性](../../tutorial/security/index.md)。 它们都基于相同的概念，但支持一些额外的功能。 diff --git a/docs/zh/docs/advanced/using-request-directly.md b/docs/zh/docs/advanced/using-request-directly.md index 8cfad4203a..519443d9d2 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/deployment/cloud.md b/docs/zh/docs/deployment/cloud.md index 96883bd6bf..025715f523 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 76e967d7de..dd5ba2ba80 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 4e7410587e..aa7b60b508 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) 提供）： ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) ## 备选 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) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -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 0239a15128..d438709935 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 591707f6dd..916fb46da2 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 47dcede653..fa10019adf 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 f519c1e87a..c440aa924b 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 2bbd5d9b6a..c98d55f273 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 进程**。不过，我会在本章节的后续部分详细介绍这一点。 @@ -64,14 +64,14 @@ $ fastapi run --workers 4 INFO Started server process [27368] INFO Started server process [27369] INFO Started server process [27370] - INFO Started server process [27367] - INFO Waiting for application startup. - INFO Waiting for application startup. - INFO Waiting for application startup. - INFO Waiting for application startup. - INFO Application startup complete. - INFO Application startup complete. - INFO Application startup complete. + INFO Started server process [27367] + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Application startup complete. + INFO Application startup complete. + INFO Application startup complete. INFO Application startup complete. ``` @@ -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 23c37f3b5b..13af705568 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/how-to/authentication-error-status-code.md b/docs/zh/docs/how-to/authentication-error-status-code.md index 466b90e15a..6f8c0a67cd 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 d26b5f3bd0..b0c5d521c1 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 bf26246573..3dbc54911b 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 9e6e5a66b8..47b27b69ca 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 8b365987ce..79860a5623 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 ad8a1d6981..fd39e439fa 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 2c9f781791..1526ca1872 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 5384f15137..b33d6759fa 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 980dcd1a65..ff3d8afa0c 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 2e5445200a..3723eb0327 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 e4a20d8436..57219832bb 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/)的章节。😎