From 12bbd9453fe1255a0ff17632afdf0dfac8d9a86d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Fri, 20 Mar 2026 18:06:37 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20for=20zh?= =?UTF-8?q?=20(update-outdated)=20(#15177)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] Co-authored-by: Yurii Motov --- docs/zh/docs/_llm-test.md | 266 +----------------- docs/zh/docs/advanced/additional-responses.md | 4 +- .../docs/advanced/additional-status-codes.md | 6 +- .../zh/docs/advanced/advanced-dependencies.md | 4 +- docs/zh/docs/advanced/async-tests.md | 8 +- docs/zh/docs/advanced/behind-a-proxy.md | 26 +- docs/zh/docs/advanced/custom-response.md | 116 +++----- docs/zh/docs/advanced/dataclasses.md | 8 +- docs/zh/docs/advanced/events.md | 6 +- docs/zh/docs/advanced/generate-clients.md | 16 +- docs/zh/docs/advanced/index.md | 6 +- docs/zh/docs/advanced/middleware.md | 12 +- docs/zh/docs/advanced/openapi-callbacks.md | 14 +- docs/zh/docs/advanced/openapi-webhooks.md | 4 +- .../path-operation-advanced-configuration.md | 6 +- .../advanced/response-change-status-code.md | 2 +- docs/zh/docs/advanced/response-cookies.md | 4 +- docs/zh/docs/advanced/response-directly.md | 29 +- docs/zh/docs/advanced/response-headers.md | 6 +- .../docs/advanced/security/http-basic-auth.md | 2 +- docs/zh/docs/advanced/security/index.md | 4 +- .../docs/advanced/security/oauth2-scopes.md | 4 +- docs/zh/docs/advanced/settings.md | 16 +- docs/zh/docs/advanced/sub-applications.md | 10 +- docs/zh/docs/advanced/templates.md | 8 +- docs/zh/docs/advanced/testing-websockets.md | 2 +- .../docs/advanced/using-request-directly.md | 4 +- docs/zh/docs/advanced/websockets.md | 26 +- docs/zh/docs/advanced/wsgi.md | 6 +- docs/zh/docs/alternatives.md | 62 ++-- docs/zh/docs/async.md | 24 +- docs/zh/docs/benchmarks.md | 2 +- 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 | 6 +- docs/zh/docs/deployment/versions.md | 6 +- docs/zh/docs/environment-variables.md | 10 +- docs/zh/docs/fastapi-cli.md | 71 ++++- docs/zh/docs/features.md | 26 +- docs/zh/docs/help-fastapi.md | 58 ++-- docs/zh/docs/history-design-future.md | 12 +- .../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 +- docs/zh/docs/index.md | 118 ++++---- docs/zh/docs/project-generation.md | 2 +- docs/zh/docs/python-types.md | 10 +- docs/zh/docs/tutorial/background-tasks.md | 6 +- docs/zh/docs/tutorial/bigger-applications.md | 49 +++- docs/zh/docs/tutorial/body-nested-models.md | 2 +- docs/zh/docs/tutorial/body-updates.md | 6 +- docs/zh/docs/tutorial/body.md | 12 +- docs/zh/docs/tutorial/cors.md | 8 +- docs/zh/docs/tutorial/debugging.md | 2 +- ...pendencies-in-path-operation-decorators.md | 4 +- .../dependencies/dependencies-with-yield.md | 18 +- .../dependencies/global-dependencies.md | 6 +- docs/zh/docs/tutorial/dependencies/index.md | 4 +- docs/zh/docs/tutorial/encoder.md | 4 +- docs/zh/docs/tutorial/extra-data-types.md | 4 +- docs/zh/docs/tutorial/extra-models.md | 10 +- docs/zh/docs/tutorial/first-steps.md | 77 ++++- docs/zh/docs/tutorial/handling-errors.md | 2 +- docs/zh/docs/tutorial/index.md | 14 +- docs/zh/docs/tutorial/metadata.md | 4 +- docs/zh/docs/tutorial/middleware.md | 10 +- .../tutorial/path-operation-configuration.md | 2 +- .../path-params-numeric-validations.md | 6 +- docs/zh/docs/tutorial/path-params.md | 16 +- .../tutorial/query-params-str-validations.md | 20 +- docs/zh/docs/tutorial/query-params.md | 14 +- docs/zh/docs/tutorial/request-files.md | 24 +- docs/zh/docs/tutorial/request-form-models.md | 4 +- .../docs/tutorial/request-forms-and-files.md | 4 +- docs/zh/docs/tutorial/request-forms.md | 8 +- docs/zh/docs/tutorial/response-model.md | 9 +- docs/zh/docs/tutorial/response-status-code.md | 6 +- docs/zh/docs/tutorial/schema-extra-example.md | 8 +- docs/zh/docs/tutorial/security/first-steps.md | 10 +- docs/zh/docs/tutorial/security/oauth2-jwt.md | 10 +- .../docs/tutorial/security/simple-oauth2.md | 4 +- docs/zh/docs/tutorial/sql-databases.md | 22 +- docs/zh/docs/tutorial/static-files.md | 4 +- docs/zh/docs/tutorial/testing.md | 24 +- docs/zh/docs/virtual-environments.md | 30 +- 98 files changed, 777 insertions(+), 920 deletions(-) diff --git a/docs/zh/docs/_llm-test.md b/docs/zh/docs/_llm-test.md index 05c512e99..2e9e7816e 100644 --- a/docs/zh/docs/_llm-test.md +++ b/docs/zh/docs/_llm-test.md @@ -11,7 +11,7 @@ * 检查翻译是否正确。 * 如有需要，改进你的语言特定提示、通用提示，或英文文档。 * 然后手动修正翻译中剩余的问题，确保这是一个优秀的译文。 -* 重新翻译，在已有的优秀译文基础上进行。理想情况是 LLM 不再对译文做任何更改。这意味着通用提示和你的语言特定提示已经尽可能完善（有时它仍会做一些看似随机的改动，原因是LLM 不是确定性算法）。 +* 重新翻译，在已有的优秀译文基础上进行。理想情况是 LLM 不再对译文做任何更改。这意味着通用提示和你的语言特定提示已经尽可能完善（有时它仍会做一些看似随机的改动，原因是[LLM 不是确定性算法](https://doublespeak.chat/#/handbook#deterministic-output)）。 测试如下： @@ -169,15 +169,15 @@ Some text 链接文本应被翻译，链接地址应保持不变： * [链接到上面的标题](#code-snippets) -* [内部链接](index.md#installation){.internal-link target=_blank} -* 外部链接 -* 样式链接 -* 脚本链接 -* 图片链接 +* [内部链接](index.md#installation) +* [外部链接](https://sqlmodel.tiangolo.com/) +* [样式链接](https://fastapi.tiangolo.com/css/styles.css) +* [脚本链接](https://fastapi.tiangolo.com/js/logic.js) +* [图片链接](https://fastapi.tiangolo.com/img/foo.jpg) 链接文本应被翻译，且链接地址应指向对应的译文页面： -* FastAPI 链接 +* [FastAPI 链接](https://fastapi.tiangolo.com/zh/) //// @@ -501,255 +501,3 @@ Hello again. 参见例如 `docs/de/llm-prompt.md` 中的 `### List of English terms and their preferred German translations` 部分。 //// - -//// - -翻译（术语）对照： - -//// tab | 测试（译文） - -* 你 -* 你的 - -* 例如 -* 等等 - -* 将 `foo` 作为 `int` -* 将 `bar` 作为 `str` -* 将 `baz` 作为 `list` - -* 教程 - 用户指南 -* 高级用户指南 -* SQLModel 文档 -* API 文档 -* 自动文档 - -* 数据科学 -* 深度学习 -* 机器学习 -* 依赖注入 -* HTTP 基本认证 -* HTTP 摘要认证 -* ISO 格式 -* JSON Schema 标准 -* JSON 模式 -* 模式定义 -* 密码流 -* 移动端 - -* 已弃用 -* 设计的 -* 无效 -* 即时 -* 标准的 -* 默认的 -* 区分大小写 -* 不区分大小写 - -* 为应用提供服务 -* 为页面提供服务 - -* 应用 -* 应用程序 - -* 请求 -* 响应 -* 错误响应 - -* 路径操作 -* 路径操作装饰器 -* 路径操作函数 - -* 主体 -* 请求体 -* 响应体 -* JSON 体 -* 表单体 -* 文件体 -* 函数体 - -* 参数 -* 请求体参数 -* 路径参数 -* 查询参数 -* Cookie 参数 -* Header 参数 -* 表单参数 -* 函数参数 - -* 事件 -* 启动事件 -* 服务器的启动 -* 关闭事件 -* 生命周期事件 - -* 处理器 -* 事件处理器 -* 异常处理器 -* 处理 - -* 模型 -* Pydantic 模型 -* 数据模型 -* 数据库模型 -* 表单模型 -* 模型对象 - -* 类 -* 基类 -* 父类 -* 子类 -* 子类 -* 兄弟类 -* 类方法 - -* 请求头 -* 请求头 -* 授权头 -* `Authorization` 头 -* 转发头 - -* 依赖注入系统 -* 依赖 -* 可依赖对象 -* 依赖项 - -* I/O 受限 -* CPU 受限 -* 并发 -* 并行 -* 多进程 - -* 环境变量 -* 环境变量 -* `PATH` -* `PATH` 变量 - -* 认证 -* 认证提供方 -* 授权 -* 授权表单 -* 授权提供方 -* 用户进行认证 -* 系统对用户进行认证 - -* CLI -* 命令行界面 - -* 服务器 -* 客户端 - -* 云服务提供商 -* 云服务 - -* 开发 -* 开发阶段 - -* dict -* 字典 -* 枚举 -* 枚举 -* 枚举成员 - -* 编码器 -* 解码器 -* 编码 -* 解码 - -* 异常 -* 抛出 - -* 表达式 -* 语句 - -* 前端 -* 后端 - -* GitHub 讨论 -* GitHub Issue - -* 性能 -* 性能优化 - -* 返回类型 -* 返回值 - -* 安全 -* 安全方案 - -* 任务 -* 后台任务 -* 任务函数 - -* 模板 -* 模板引擎 - -* 类型注解 -* 类型提示 - -* 服务器 worker -* Uvicorn worker -* Gunicorn worker -* worker 进程 -* worker 类 -* 工作负载 - -* 部署 -* 部署 - -* SDK -* 软件开发工具包 - -* `APIRouter` -* `requirements.txt` -* Bearer Token -* 破坏性变更 -* Bug -* 按钮 -* 可调用对象 -* 代码 -* 提交 -* 上下文管理器 -* 协程 -* 数据库会话 -* 磁盘 -* 域名 -* 引擎 -* 假 X -* HTTP GET 方法 -* 项 -* 库 -* 生命周期 -* 锁 -* 中间件 -* 移动应用 -* 模块 -* 挂载 -* 网络 -* 源 -* 覆盖 -* 负载 -* 处理器 -* 属性 -* 代理 -* Pull Request -* 查询 -* RAM -* 远程机器 -* 状态码 -* 字符串 -* 标签 -* Web 框架 -* 通配符 -* 返回 -* 校验 - -//// - -//// tab | 信息（译文） - -此清单是不完整且非规范性的，列出（主要是）文档中出现的技术术语。它有助于提示词设计者确定哪些术语需要额外的指引。例如当 LLM 总是把更好的译法改回次优译法，或在你的语言中难以正确变形时。 - -也可参见 `docs/de/llm-prompt.md` 中的 `### List of English terms and their preferred German translations` 部分。 - -//// diff --git a/docs/zh/docs/advanced/additional-responses.md b/docs/zh/docs/advanced/additional-responses.md index aa3d22d1c..365ba3db4 100644 --- a/docs/zh/docs/advanced/additional-responses.md +++ b/docs/zh/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} 要查看响应中究竟可以包含什么，你可以查看 OpenAPI 规范中的以下部分： -* OpenAPI Responses 对象，它包含 `Response Object`。 -* OpenAPI Response 对象，你可以把这里的任何内容直接包含到 `responses` 参数中的每个响应里。包括 `description`、`headers`、`content`（在这里声明不同的媒体类型和 JSON Schemas），以及 `links`。 +* [OpenAPI Responses 对象](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object)，它包含 `Response Object`。 +* [OpenAPI Response 对象](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object)，你可以把这里的任何内容直接包含到 `responses` 参数中的每个响应里。包括 `description`、`headers`、`content`（在这里声明不同的媒体类型和 JSON Schemas），以及 `links`。 diff --git a/docs/zh/docs/advanced/additional-status-codes.md b/docs/zh/docs/advanced/additional-status-codes.md index 7eeffaf53..af212ad8b 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/advanced-dependencies.md b/docs/zh/docs/advanced/advanced-dependencies.md index a547e8881..edaf964c9 100644 --- a/docs/zh/docs/advanced/advanced-dependencies.md +++ b/docs/zh/docs/advanced/advanced-dependencies.md @@ -132,7 +132,7 @@ checker(q="somequery") 这样会话会释放数据库连接，让其他请求可以使用。 -如果你还有其他需要在 `yield` 依赖项中提前退出的用例，请创建一个 GitHub 讨论问题，说明你的具体用例以及为何提前关闭会对你有帮助。 +如果你还有其他需要在 `yield` 依赖项中提前退出的用例，请创建一个 [GitHub 讨论问题](https://github.com/fastapi/fastapi/discussions/new?category=questions)，说明你的具体用例以及为何提前关闭会对你有帮助。 如果确有有力的用例需要提前关闭，我会考虑新增一种选择性启用提前关闭的方式。 @@ -144,7 +144,7 @@ checker(q="somequery") ### 后台任务与带 `yield` 的依赖项（技术细节） { #background-tasks-and-dependencies-with-yield-technical-details } -在 FastAPI 0.106.0 之前，`yield` 之后抛出异常是不可行的，因为带 `yield` 的依赖项中的退出代码会在响应发送之后才执行，此时[异常处理器](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}已经运行完毕。 +在 FastAPI 0.106.0 之前，`yield` 之后抛出异常是不可行的，因为带 `yield` 的依赖项中的退出代码会在响应发送之后才执行，此时[异常处理器](../tutorial/handling-errors.md#install-custom-exception-handlers)已经运行完毕。 之所以这样设计，主要是为了允许在后台任务中继续使用依赖项通过 `yield`“产出”的对象，因为退出代码会在后台任务完成之后才执行。 diff --git a/docs/zh/docs/advanced/async-tests.md b/docs/zh/docs/advanced/async-tests.md index 16b8a8c81..2030bb11e 100644 --- a/docs/zh/docs/advanced/async-tests.md +++ b/docs/zh/docs/advanced/async-tests.md @@ -16,11 +16,11 @@ `TestClient` 在内部通过一些“魔法”操作，使得您可以在普通的 `def` 测试函数中调用异步的 FastAPI 应用程序，并使用标准的 pytest。但当我们在异步函数中使用它时，这种“魔法”就不再生效了。由于测试以异步方式运行，我们无法在测试函数中继续使用 `TestClient`。 -`TestClient` 是基于 HTTPX 的。幸运的是，我们可以直接使用它来测试API。 +`TestClient` 是基于 [HTTPX](https://www.python-httpx.org) 的。幸运的是，我们可以直接使用它来测试 API。 ## 示例 { #example } -举个简单的例子，让我们来看一个[更大的应用](../tutorial/bigger-applications.md){.internal-link target=_blank}和[测试](../tutorial/testing.md){.internal-link target=_blank}中描述的类似文件结构： +举个简单的例子，让我们来看一个与[更大的应用](../tutorial/bigger-applications.md)和[测试](../tutorial/testing.md)中描述的类似文件结构： ``` . @@ -84,7 +84,7 @@ response = client.get('/') /// warning | 警告 -如果您的应用程序依赖于生命周期事件， `AsyncClient` 将不会触发这些事件。为了确保它们被触发，请使用 florimondmanca/asgi-lifespan 中的 `LifespanManager` 。 +如果您的应用程序依赖于生命周期事件， `AsyncClient` 将不会触发这些事件。为了确保它们被触发，请使用 [florimondmanca/asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan#usage) 中的 `LifespanManager` 。 /// @@ -94,6 +94,6 @@ response = client.get('/') /// tip | 提示 -如果您在测试程序中集成异步函数调用的时候遇到一个 `RuntimeError: Task attached to a different loop` 的报错（例如，使用 MongoDB 的 MotorClient 时），请记住，只能在异步函数中实例化需要事件循环的对象，例如在 `@app.on_event("startup")` 回调中初始化。 +如果您在测试程序中集成异步函数调用的时候遇到一个 `RuntimeError: Task attached to a different loop` 的报错（例如，使用 [MongoDB 的 MotorClient](https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop) 时），请记住，只能在异步函数中实例化需要事件循环的对象，例如在 `@app.on_event("startup")` 回调中初始化。 /// diff --git a/docs/zh/docs/advanced/behind-a-proxy.md b/docs/zh/docs/advanced/behind-a-proxy.md index 3ccc65f29..b3c91eb06 100644 --- a/docs/zh/docs/advanced/behind-a-proxy.md +++ b/docs/zh/docs/advanced/behind-a-proxy.md @@ -16,9 +16,9 @@ 这些代理相关的请求头包括： -- 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) /// @@ -60,7 +60,7 @@ https://mysuperapp.com/items/ /// tip | 提示 -如果你想了解更多关于 HTTPS 的内容，查看指南：[关于 HTTPS](../deployment/https.md){.internal-link target=_blank}。 +如果你想了解更多关于 HTTPS 的内容，查看指南：[关于 HTTPS](../deployment/https.md)。 /// @@ -228,7 +228,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 请注意，服务器（Uvicorn）不会用这个 `root_path` 做别的事情，只会把它传给应用。 -但是，如果你用浏览器打开 http://127.0.0.1:8000/app，你会看到正常的响应： +但是，如果你用浏览器打开 [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app)，你会看到正常的响应： ```JSON { @@ -251,9 +251,9 @@ Uvicorn 会期望代理以 `http://127.0.0.1:8000/app` 访问 Uvicorn，而在 ## 使用 Traefik 进行本地测试 { #testing-locally-with-traefik } -你可以很容易地使用 Traefik 在本地运行一个移除路径前缀的实验。 +你可以很容易地使用 [Traefik](https://docs.traefik.io/) 在本地运行一个移除路径前缀的实验。 -下载 Traefik，它是一个单独的二进制文件，你可以解压压缩包并直接在终端中运行。 +[下载 Traefik](https://github.com/containous/traefik/releases)，它是一个单独的二进制文件，你可以解压压缩包并直接在终端中运行。 然后创建一个 `traefik.toml` 文件，内容如下： @@ -330,7 +330,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 ### 查看响应 { #check-the-responses } -现在，如果你访问 Uvicorn 端口对应的 URL：http://127.0.0.1:8000/app，你会看到正常响应： +现在，如果你访问 Uvicorn 端口对应的 URL：[http://127.0.0.1:8000/app](http://127.0.0.1:8000/app)，你会看到正常响应： ```JSON { @@ -345,7 +345,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 /// -现在打开包含路径前缀、使用 Traefik 端口的 URL：http://127.0.0.1:9999/api/v1/app。 +现在打开包含路径前缀、使用 Traefik 端口的 URL：[http://127.0.0.1:9999/api/v1/app](http://127.0.0.1:9999/api/v1/app)。 我们得到相同的响应： @@ -370,13 +370,13 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 访问应用的“官方”方式应该是通过我们定义的带有路径前缀的代理。因此，正如预期的那样，如果你尝试不带路径前缀、直接由 Uvicorn 提供的文档界面，它将无法工作，因为它期望通过代理访问。 -你可以在 http://127.0.0.1:8000/docs 查看： +你可以在 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) 查看： 但如果我们在“官方”URL（代理端口为 `9999`）的 `/api/v1/docs` 访问文档界面，它就能正常工作！🎉 -你可以在 http://127.0.0.1:9999/api/v1/docs 查看： +你可以在 [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs) 查看： @@ -433,7 +433,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 /// -在 http://127.0.0.1:9999/api/v1/docs 的文档界面中，它看起来是这样的： +在文档界面 [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs) 中，它看起来是这样的： @@ -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 } -例如，如果你需要压榨性能，你可以安装并使用 `orjson` 并将响应设置为 `ORJSONResponse`。 +默认情况下 FastAPI 返回 JSON 响应。 -导入你想要使用的 `Response` 类（子类）然后在 *路径操作装饰器* 中声明它。 +如果你声明了一个[响应模型](../tutorial/response-model.md)，FastAPI 会使用 Pydantic 将数据序列化为 JSON。 -对于较大的响应，直接返回一个 `Response` 会比返回一个字典快得多。 +如果你没有声明响应模型，FastAPI 会使用 [JSON 兼容编码器](../tutorial/encoder.md) 中解释的 `jsonable_encoder`，并把结果放进一个 `JSONResponse`。 -这是因为默认情况下，FastAPI 会检查其中的每一项并确保它可以被序列化为 JSON，使用教程中解释的相同 [JSON 兼容编码器](../tutorial/encoder.md){.internal-link target=_blank}。这正是它允许你返回「任意对象」的原因，例如数据库模型。 +如果你在 `response_class` 中声明了一个 JSON 媒体类型（`application/json`）的类（比如 `JSONResponse`），你返回的数据会使用你在 *路径操作装饰器* 中声明的任意 Pydantic `response_model` 自动转换（和过滤）。但数据不会由 Pydantic 序列化为 JSON 字节；而是先用 `jsonable_encoder` 转换后传给 `JSONResponse`，由它使用 Python 标准 JSON 库序列化为字节。 -但如果你确定你返回的内容是「可以用 JSON 序列化」的，你可以将它直接传给响应类，从而避免在传给响应类之前先通过 `jsonable_encoder` 带来的额外开销。 +### JSON 性能 { #json-performance } -{* ../../docs_src/custom_response/tutorial001b_py310.py hl[2,7] *} +简而言之，如果你想要获得最大性能，请使用[响应模型](../tutorial/response-model.md)，并且不要在 *路径操作装饰器* 中声明 `response_class`。 -/// info | 信息 - -参数 `response_class` 也会用来定义响应的「媒体类型」。 - -在这个例子中，HTTP 头的 `Content-Type` 会被设置成 `application/json`。 - -并且在 OpenAPI 文档中也会这样记录。 - -/// - -/// tip | 提示 - -`ORJSONResponse` 目前只在 FastAPI 中可用，而在 Starlette 中不可用。 - -/// +{* ../../docs_src/response_model/tutorial001_01_py310.py ln[15:17] hl[16] *} ## HTML 响应 { #html-response } @@ -69,7 +53,7 @@ ### 返回一个 `Response` { #return-a-response } -正如你在 [直接返回响应](response-directly.md){.internal-link target=_blank} 中了解到的，你也可以通过直接返回响应在 *路径操作* 中直接重载响应。 +正如你在 [直接返回响应](response-directly.md) 中了解到的，你也可以通过直接返回响应在 *路径操作* 中直接重载响应。 和上面一样的例子，返回一个 `HTMLResponse` 看起来可能是这样： @@ -154,37 +138,11 @@ FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它 如上文所述，这是 **FastAPI** 中使用的默认响应。 -### `ORJSONResponse` { #orjsonresponse } +/// note | 技术细节 -如上文所述，`ORJSONResponse` 是一个使用 `orjson` 的快速的可选 JSON 响应。 +但如果你声明了响应模型或返回类型，将直接使用它来把数据序列化为 JSON，并直接返回一个具备正确 JSON 媒体类型的响应，而不会使用 `JSONResponse` 类。 -/// info | 信息 - -这需要先安装 `orjson`，例如使用 `pip install orjson`。 - -/// - -### `UJSONResponse` { #ujsonresponse } - -`UJSONResponse` 是一个使用 `ujson` 的可选 JSON 响应。 - -/// info | 信息 - -这需要先安装 `ujson`，例如使用 `pip install ujson`。 - -/// - -/// warning | 警告 - -在处理某些边缘情况时，`ujson` 不如 Python 的内置实现那么谨慎。 - -/// - -{* ../../docs_src/custom_response/tutorial001_py310.py hl[2,7] *} - -/// tip | 提示 - -`ORJSONResponse` 可能是一个更快的选择。 +这是获得最佳性能的理想方式。 /// @@ -214,31 +172,25 @@ FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它 ### `StreamingResponse` { #streamingresponse } -采用异步生成器或普通生成器/迭代器，然后流式传输响应主体。 +采用异步生成器或普通生成器/迭代器（带有 `yield` 的函数），然后流式传输响应主体。 -{* ../../docs_src/custom_response/tutorial007_py310.py hl[2,14] *} +{* ../../docs_src/custom_response/tutorial007_py310.py hl[3,16] *} -#### 对类似文件的对象使用 `StreamingResponse` { #using-streamingresponse-with-file-like-objects } +/// note | 技术细节 -如果您有一个类文件对象（例如由 `open()` 返回的对象），你可以创建一个生成器函数来迭代该类文件对象。 +一个 `async` 任务只有在到达 `await` 时才能被取消。如果没有 `await`，生成器（带有 `yield` 的函数）无法被正确取消，即使已请求取消也可能继续运行。 -这样，你就不必先把它全部读入内存，可以将该生成器函数传给 `StreamingResponse` 并返回它。 +由于这个小示例不需要任何 `await` 语句，我们添加 `await anyio.sleep(0)`，给事件循环一个处理取消的机会。 -这也包括许多与云存储、视频处理等交互的库。 +对于大型或无限流，这一点更为重要。 -{* ../../docs_src/custom_response/tutorial008_py310.py hl[2,10:12,14] *} - -1. 这是生成器函数。之所以是「生成器函数」，是因为它内部包含 `yield` 语句。 -2. 通过使用 `with` 代码块，我们可以确保在生成器函数完成后关闭类文件对象。因此，在它完成发送响应之后会被关闭。 -3. 这个 `yield from` 告诉函数去迭代名为 `file_like` 的那个对象。然后，对于每个被迭代出来的部分，都把该部分作为来自这个生成器函数（`iterfile`）的值再 `yield` 出去。 - - 因此，它是一个把「生成」工作内部转交给其他东西的生成器函数。 - - 通过这种方式，我们可以把它放在 `with` 代码块中，从而确保类文件对象在结束后被关闭。 +/// /// tip | 提示 -注意在这里，因为我们使用的是不支持 `async` 和 `await` 的标准 `open()`，我们使用普通的 `def` 声明了路径操作。 +与其直接返回 `StreamingResponse`，更推荐遵循 [流式数据](./stream-data.md) 的写法，它更方便并在幕后为你处理取消。 + +如果你在流式传输 JSON Lines，请参阅教程：[流式传输 JSON Lines](../tutorial/stream-json-lines.md)。 /// @@ -267,11 +219,11 @@ FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它 你可以创建你自己的自定义响应类，继承自 `Response` 并使用它。 -例如，假设你想使用 `orjson`，但要使用内置 `ORJSONResponse` 类没有启用的一些自定义设置。 +例如，假设你想用一些设置来使用 [`orjson`](https://github.com/ijl/orjson)。 假设你想让它返回带缩进、格式化的 JSON，因此你想使用 orjson 选项 `orjson.OPT_INDENT_2`。 -你可以创建一个 `CustomORJSONResponse`。你需要做的主要事情是实现一个返回 `bytes` 的 `Response.render(content)` 方法： +你可以创建一个 `CustomORJSONResponse`。你需要做的主要事情是实现一个 `Response.render(content)` 方法，并返回 `bytes`： {* ../../docs_src/custom_response/tutorial009c_py310.py hl[9:14,17] *} @@ -291,13 +243,21 @@ FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它 当然，你很可能会找到比格式化 JSON 更好的方式来利用这一点。😉 +### `orjson` 或响应模型 { #orjson-or-response-model } + +如果你追求的是性能，使用[响应模型](../tutorial/response-model.md) 往往比返回 `orjson` 响应更好。 + +使用响应模型时，FastAPI 会使用 Pydantic 直接把数据序列化为 JSON，不需要诸如通过 `jsonable_encoder` 转换这样的中间步骤（其他情况下会发生）。 + +并且在底层，Pydantic 使用与 `orjson` 相同的 Rust 机制来序列化 JSON，所以使用响应模型你已经可以获得最佳性能。 + ## 默认响应类 { #default-response-class } 在创建 **FastAPI** 类实例或 `APIRouter` 时，你可以指定默认要使用的响应类。 用于定义它的参数是 `default_response_class`。 -在下面的示例中，**FastAPI** 会在所有 *路径操作* 中默认使用 `ORJSONResponse`，而不是 `JSONResponse`。 +在下面的示例中，**FastAPI** 会在所有 *路径操作* 中默认使用 `HTMLResponse`，而不是 JSON。 {* ../../docs_src/custom_response/tutorial010_py310.py hl[2,4] *} @@ -309,4 +269,4 @@ FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它 ## 额外文档 { #additional-documentation } -你还可以使用 `responses` 在 OpenAPI 中声明媒体类型和许多其他详细信息：[OpenAPI 中的额外文档](additional-responses.md){.internal-link target=_blank}。 +你还可以使用 `responses` 在 OpenAPI 中声明媒体类型和许多其他详细信息：[OpenAPI 中的额外响应](additional-responses.md)。 diff --git a/docs/zh/docs/advanced/dataclasses.md b/docs/zh/docs/advanced/dataclasses.md index f552d779f..42b4e4cc4 100644 --- a/docs/zh/docs/advanced/dataclasses.md +++ b/docs/zh/docs/advanced/dataclasses.md @@ -2,11 +2,11 @@ FastAPI 基于 **Pydantic** 构建，我已经向你展示过如何使用 Pydantic 模型声明请求与响应。 -但 FastAPI 也支持以相同方式使用 `dataclasses`： +但 FastAPI 也支持以相同方式使用 [`dataclasses`](https://docs.python.org/3/library/dataclasses.html)： {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -这仍然得益于 **Pydantic**，因为它对 `dataclasses` 的内置支持。 +这仍然得益于 **Pydantic**，因为它对 [`dataclasses` 的内置支持](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel)。 因此，即便上面的代码没有显式使用 Pydantic，FastAPI 也会使用 Pydantic 将那些标准数据类转换为 Pydantic 风格的 dataclasses。 @@ -67,7 +67,7 @@ FastAPI 基于 **Pydantic** 构建，我已经向你展示过如何使用 Pydant 一如既往，在 FastAPI 中你可以按需组合 `def` 和 `async def`。 - 如果需要回顾何时用哪一个，请查看关于 [`async` 和 `await`](../async.md#in-a-hurry){.internal-link target=_blank} 的文档中的 _“急不可待？”_ 一节。 + 如果需要回顾何时用哪一个，请查看关于 [`async` 和 `await`](../async.md#in-a-hurry) 的文档中的 _“急不可待？”_ 一节。 9. 这个 *路径操作函数* 返回的不是数据类（当然也可以返回数据类），而是包含内部数据的字典列表。 FastAPI 会使用（包含数据类的）`response_model` 参数来转换响应。 @@ -80,7 +80,7 @@ FastAPI 基于 **Pydantic** 构建，我已经向你展示过如何使用 Pydant 你还可以把 `dataclasses` 与其它 Pydantic 模型组合、从它们继承、把它们包含到你自己的模型中等。 -想了解更多，请查看 Pydantic 关于 dataclasses 的文档。 +想了解更多，请查看 [Pydantic 关于 dataclasses 的文档](https://docs.pydantic.dev/latest/concepts/dataclasses/)。 ## 版本 { #version } diff --git a/docs/zh/docs/advanced/events.md b/docs/zh/docs/advanced/events.md index 71ad1ae38..0b647a438 100644 --- a/docs/zh/docs/advanced/events.md +++ b/docs/zh/docs/advanced/events.md @@ -150,11 +150,11 @@ async with lifespan(app): 只是为好奇者提供的技术细节。🤓 -在底层，这部分是 ASGI 技术规范中的 Lifespan 协议的一部分，定义了称为 `startup` 和 `shutdown` 的事件。 +在底层，这部分是 ASGI 技术规范中的 [Lifespan 协议](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)的一部分，定义了称为 `startup` 和 `shutdown` 的事件。 /// info | 信息 -你可以在 Starlette 的 Lifespan 文档 中阅读更多关于 `lifespan` 处理器的内容。 +你可以在 [Starlette 的 Lifespan 文档](https://www.starlette.dev/lifespan/) 中阅读更多关于 `lifespan` 处理器的内容。 包括如何处理生命周期状态，以便在代码的其他部分使用。 @@ -162,4 +162,4 @@ async with lifespan(app): ## 子应用 { #sub-applications } -🚨 请注意，这些生命周期事件（startup 和 shutdown）只会在主应用上执行，不会在[子应用 - 挂载](sub-applications.md){.internal-link target=_blank}上执行。 +🚨 请注意，这些生命周期事件（startup 和 shutdown）只会在主应用上执行，不会在[子应用 - 挂载](sub-applications.md)上执行。 diff --git a/docs/zh/docs/advanced/generate-clients.md b/docs/zh/docs/advanced/generate-clients.md index e8a3b2055..5f53aa434 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/index.md b/docs/zh/docs/advanced/index.md index 610c18713..24b4d076f 100644 --- a/docs/zh/docs/advanced/index.md +++ b/docs/zh/docs/advanced/index.md @@ -2,13 +2,13 @@ ## 附加功能 { #additional-features } -主要的[教程 - 用户指南](../tutorial/index.md){.internal-link target=_blank}足以带你了解 **FastAPI** 的所有主要特性。 +主要的[教程 - 用户指南](../tutorial/index.md)足以带你了解 **FastAPI** 的所有主要特性。 在接下来的章节中，你将看到其他选项、配置和附加功能。 /// tip | 提示 -接下来的章节不一定是“高级”的。 +接下来的章节**不一定是“高级”的**。 对于你的用例，解决方案很可能就在其中之一。 @@ -16,6 +16,6 @@ ## 先阅读教程 { #read-the-tutorial-first } -仅凭主要[教程 - 用户指南](../tutorial/index.md){.internal-link target=_blank}中的知识，你已经可以使用 **FastAPI** 的大多数功能。 +仅凭主要[教程 - 用户指南](../tutorial/index.md)中的知识，你已经可以使用 **FastAPI** 的大多数功能。 接下来的章节默认你已经读过它，并理解其中的核心概念。 diff --git a/docs/zh/docs/advanced/middleware.md b/docs/zh/docs/advanced/middleware.md index de4a3fcb1..4077ec094 100644 --- a/docs/zh/docs/advanced/middleware.md +++ b/docs/zh/docs/advanced/middleware.md @@ -1,8 +1,8 @@ # 高级中间件 { #advanced-middleware } -用户指南介绍了如何为应用添加[自定义中间件](../tutorial/middleware.md){.internal-link target=_blank} 。 +用户指南介绍了如何为应用添加[自定义中间件](../tutorial/middleware.md)。 -以及如何[使用 `CORSMiddleware` 处理 CORS](../tutorial/cors.md){.internal-link target=_blank}。 +以及如何[使用 `CORSMiddleware` 处理 CORS](../tutorial/cors.md)。 本章学习如何使用其它中间件。 @@ -87,11 +87,11 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") ## 其它中间件 { #other-middlewares } -除了上述中间件外，FastAPI 还支持其它ASGI 中间件。 +除了上述中间件外，FastAPI 还支持其它 ASGI 中间件。 例如： -* Uvicorn 的 `ProxyHeadersMiddleware` -* MessagePack +* [Uvicorn 的 `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +* [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -其它可用中间件详见 Starlette 官档 - 中间件 及 ASGI Awesome 列表。 +其它可用中间件详见 [Starlette 官档 - 中间件](https://www.starlette.dev/middleware/) 及 [ASGI Awesome 列表](https://github.com/florimondmanca/awesome-asgi)。 diff --git a/docs/zh/docs/advanced/openapi-callbacks.md b/docs/zh/docs/advanced/openapi-callbacks.md index cc9f5c28e..49cef3648 100644 --- a/docs/zh/docs/advanced/openapi-callbacks.md +++ b/docs/zh/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ API 的用户（外部开发者）要在您的 API 内使用 POST 请求创建 /// tip | 提示 -`callback_url` 查询参数使用 Pydantic 的 Url 类型。 +`callback_url` 查询参数使用 Pydantic 的 [Url](https://docs.pydantic.dev/latest/api/networks/) 类型。 /// @@ -66,7 +66,7 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 实际的回调只是 HTTP 请求。 -实现回调时，要使用 HTTPX 或 Requests。 +实现回调时，要使用 [HTTPX](https://www.python-httpx.org) 或 [Requests](https://requests.readthedocs.io/)。 /// @@ -106,13 +106,13 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 回调*路径操作*与常规*路径操作*有两点主要区别： * 它不需要任何实际的代码，因为应用不会调用这段代码。它只是用于存档*外部 API*。因此，函数的内容只需要 `pass` 就可以了 -* *路径*可以包含 OpenAPI 3 表达式（详见下文），可以使用带参数的变量，以及发送至您的 API 的原始请求的部分 +* *路径*可以包含 [OpenAPI 3 表达式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)（详见下文），可以使用带参数的变量，以及发送至您的 API 的原始请求的部分 ### 回调路径表达式 { #the-callback-path-expression } -回调*路径*支持包含发送给您的 API 的原始请求的部分的 OpenAPI 3 表达式。 +回调*路径*支持包含发送给您的 API 的原始请求的部分的 [OpenAPI 3 表达式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)。 -本例中是**字符串**： +本例中是 `str`： ```Python "{$callback_url}/invoices/{$request.body.id}" @@ -173,13 +173,13 @@ JSON 请求体包含如下内容： /// tip | 提示 -注意，不能把路由本身（`invoices_callback_router`）传递给 `callback=`，要传递 `invoices_callback_router.routes` 中的 `.routes` 属性。 +注意，不能把路由本身（`invoices_callback_router`）传递给 `callbacks=`，要传递 `invoices_callback_router.routes` 中的 `.routes` 属性。 /// ### 查看文档 { #check-the-docs } -现在，启动应用并打开 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/advanced/openapi-webhooks.md b/docs/zh/docs/advanced/openapi-webhooks.md index d23fbcf88..3d6bcc9bc 100644 --- a/docs/zh/docs/advanced/openapi-webhooks.md +++ b/docs/zh/docs/advanced/openapi-webhooks.md @@ -2,7 +2,7 @@ 有些情况下，您可能想告诉您的 API **用户**，您的应用程序可以携带一些数据调用*他们的*应用程序（给它们发送请求），通常是为了**通知**某种**事件**。 -这意味着，除了您的用户向您的 API 发送请求的一般情况，**您的 API**（或您的应用）也可以向**他们的系统**（他们的 API、他们的应用）**发送请求**。 +这意味着，与通常由您的用户向您的 API 发送请求的流程相反，是**您的 API**（或您的应用）可以**向他们的系统**（他们的 API、他们的应用）**发送请求**。 这通常被称为**网络钩子**（Webhook）。 @@ -48,7 +48,7 @@ ### 查看文档 { #check-the-docs } -现在您可以启动您的应用程序并访问 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/advanced/path-operation-advanced-configuration.md b/docs/zh/docs/advanced/path-operation-advanced-configuration.md index 588d4f09c..67f3bd7e9 100644 --- a/docs/zh/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/zh/docs/advanced/path-operation-advanced-configuration.md @@ -60,7 +60,7 @@ 你也可以为它声明带有各自模型、状态码等的附加响应。 -文档中有一个完整章节，你可以阅读这里的[OpenAPI 中的附加响应](additional-responses.md){.internal-link target=_blank}。 +文档中有一个完整章节，你可以阅读这里的[OpenAPI 中的附加响应](additional-responses.md)。 ## OpenAPI Extra { #openapi-extra } @@ -68,7 +68,7 @@ /// note | 技术细节 -在 OpenAPI 规范中，这被称为 Operation 对象。 +在 OpenAPI 规范中，这被称为 [Operation 对象](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object)。 /// @@ -82,7 +82,7 @@ 这是一个较低层级的扩展点。 -如果你只需要声明附加响应，更方便的方式是使用[OpenAPI 中的附加响应](additional-responses.md){.internal-link target=_blank}。 +如果你只需要声明附加响应，更方便的方式是使用[OpenAPI 中的附加响应](additional-responses.md)。 /// diff --git a/docs/zh/docs/advanced/response-change-status-code.md b/docs/zh/docs/advanced/response-change-status-code.md index 0b004bf4e..379afd4eb 100644 --- a/docs/zh/docs/advanced/response-change-status-code.md +++ b/docs/zh/docs/advanced/response-change-status-code.md @@ -1,6 +1,6 @@ # 响应 - 更改状态码 { #response-change-status-code } -你可能之前已经了解到，你可以设置默认的[响应状态码](../tutorial/response-status-code.md){.internal-link target=_blank}。 +你可能之前已经了解到，你可以设置默认的[响应状态码](../tutorial/response-status-code.md)。 但在某些情况下，你需要返回一个不同于默认值的状态码。 diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md index c618cd0f0..7fad89e5c 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 a97992d24..196622146 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/response-headers.md b/docs/zh/docs/advanced/response-headers.md index 01bde56d2..ab99a4ece 100644 --- a/docs/zh/docs/advanced/response-headers.md +++ b/docs/zh/docs/advanced/response-headers.md @@ -20,7 +20,7 @@ 你也可以在直接返回 `Response` 时添加头部。 -按照[直接返回响应](response-directly.md){.internal-link target=_blank}中所述创建响应，并将头部作为附加参数传递： +按照[直接返回响应](response-directly.md)中所述创建响应，并将头部作为附加参数传递： {* ../../docs_src/response_headers/tutorial001_py310.py hl[10:12] *} @@ -36,6 +36,6 @@ ## 自定义头部 { #custom-headers } -请注意，可以通过使用 `X-` 前缀添加自定义专有头部。 +请注意，可以通过[使用 `X-` 前缀](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)添加自定义专有头部。 -但是，如果你有自定义头部，并希望浏览器中的客户端能够看到它们，你需要将它们添加到你的 CORS 配置中（在 [CORS（跨源资源共享）](../tutorial/cors.md){.internal-link target=_blank} 中阅读更多），使用在 Starlette 的 CORS 文档中记录的 `expose_headers` 参数。 +但是，如果你有自定义头部，并希望浏览器中的客户端能够看到它们，你需要将它们添加到你的 CORS 配置中（在 [CORS（跨源资源共享）](../tutorial/cors.md) 中阅读更多），使用在 [Starlette 的 CORS 文档](https://www.starlette.dev/middleware/#corsmiddleware)中记录的 `expose_headers` 参数。 diff --git a/docs/zh/docs/advanced/security/http-basic-auth.md b/docs/zh/docs/advanced/security/http-basic-auth.md index 9128a4975..37e4b5abc 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 84fec7aab..e3a3ba9ce 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/security/oauth2-scopes.md b/docs/zh/docs/advanced/security/oauth2-scopes.md index ce7facf4b..a1ecc641c 100644 --- a/docs/zh/docs/advanced/security/oauth2-scopes.md +++ b/docs/zh/docs/advanced/security/oauth2-scopes.md @@ -60,7 +60,7 @@ OAuth2 规范将“作用域”定义为由空格分隔的字符串列表。 ## 全局纵览 { #global-view } -首先，让我们快速看看与**用户指南**中 [OAuth2 实现密码（含哈希）、Bearer + JWT 令牌](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank} 示例相比有哪些变化。现在开始使用 OAuth2 作用域： +首先，让我们快速看看与**用户指南**中 [OAuth2 实现密码（含哈希）、Bearer + JWT 令牌](../../tutorial/security/oauth2-jwt.md) 示例相比有哪些变化。现在开始使用 OAuth2 作用域： {* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *} @@ -271,4 +271,4 @@ OAuth2 规范将“作用域”定义为由空格分隔的字符串列表。 ## 装饰器 `dependencies` 中的 `Security` { #security-in-decorator-dependencies } -就像你可以在装饰器的 `dependencies` 参数中定义 `Depends` 的 `list`（详见[路径操作装饰器依赖项](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}），你也可以在那儿配合 `Security` 使用 `scopes`。 +就像你可以在装饰器的 `dependencies` 参数中定义 `Depends` 的 `list`（详见[路径操作装饰器依赖项](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md)），你也可以在那儿配合 `Security` 使用 `scopes`。 diff --git a/docs/zh/docs/advanced/settings.md b/docs/zh/docs/advanced/settings.md index b4def73eb..31a7cc82d 100644 --- a/docs/zh/docs/advanced/settings.md +++ b/docs/zh/docs/advanced/settings.md @@ -8,7 +8,7 @@ /// tip | 提示 -要理解环境变量，你可以阅读[环境变量](../environment-variables.md){.internal-link target=_blank}。 +要理解环境变量，你可以阅读[环境变量](../environment-variables.md)。 /// @@ -20,11 +20,11 @@ ## Pydantic 的 `Settings` { #pydantic-settings } -幸运的是，Pydantic 提供了一个很好的工具来处理来自环境变量的这些设置：Pydantic: Settings management。 +幸运的是，Pydantic 提供了一个很好的工具来处理来自环境变量的这些设置：[Pydantic：Settings 管理](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)。 ### 安装 `pydantic-settings` { #install-pydantic-settings } -首先，确保你创建并激活了[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后安装 `pydantic-settings` 包： +首先，确保你创建并激活了[虚拟环境](../virtual-environments.md)，然后安装 `pydantic-settings` 包：
@@ -100,7 +100,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p ## 在另一个模块中放置设置 { #settings-in-another-module } -你可以把这些设置放在另一个模块文件中，就像你在[更大的应用 - 多个文件](../tutorial/bigger-applications.md){.internal-link target=_blank}中看到的那样。 +你可以把这些设置放在另一个模块文件中，就像你在[更大的应用 - 多个文件](../tutorial/bigger-applications.md)中看到的那样。 例如，可以有一个 `config.py` 文件： @@ -112,7 +112,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// tip | 提示 -你还需要一个 `__init__.py` 文件，就像你在[更大的应用 - 多个文件](../tutorial/bigger-applications.md){.internal-link target=_blank}中看到的那样。 +你还需要一个 `__init__.py` 文件，就像你在[更大的应用 - 多个文件](../tutorial/bigger-applications.md)中看到的那样。 /// @@ -172,7 +172,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic 支持使用一个外部库来从这类文件中读取。你可以在 Pydantic Settings: Dotenv (.env) support 中阅读更多信息。 +Pydantic 支持使用一个外部库来从这类文件中读取。你可以在 [Pydantic Settings：Dotenv（.env）支持](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support) 中阅读更多信息。 /// tip | 提示 @@ -197,7 +197,7 @@ APP_NAME="ChimichangApp" /// tip | 提示 -`model_config` 属性仅用于 Pydantic 配置。你可以在 Pydantic: Concepts: Configuration 中阅读更多信息。 +`model_config` 属性仅用于 Pydantic 配置。你可以在 [Pydantic：概念：配置](https://docs.pydantic.dev/latest/concepts/config/) 中阅读更多信息。 /// @@ -291,7 +291,7 @@ participant execute as Execute function 这样，它的行为几乎就像是一个全局变量。但由于它使用了依赖项函数，我们可以在测试时很容易地覆盖它。 -`@lru_cache` 是 `functools` 的一部分，它属于 Python 标准库。你可以在 Python 文档中关于 `@lru_cache` 的章节阅读更多信息。 +`@lru_cache` 是 `functools` 的一部分，它属于 Python 标准库。你可以在 [Python 文档中关于 `@lru_cache` 的章节](https://docs.python.org/3/library/functools.html#functools.lru_cache)阅读更多信息。 ## 小结 { #recap } diff --git a/docs/zh/docs/advanced/sub-applications.md b/docs/zh/docs/advanced/sub-applications.md index 3e61610a3..b0230402b 100644 --- a/docs/zh/docs/advanced/sub-applications.md +++ b/docs/zh/docs/advanced/sub-applications.md @@ -30,25 +30,25 @@ ### 查看自动 API 文档 { #check-the-automatic-api-docs } -现在，使用你的文件运行 `fastapi` 命令： +现在，运行 `fastapi` 命令：
```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`，然后运行你的应用程序：
```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) 提供）： ![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 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。 ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* 另外的 API 文档：ReDoc +* 另外的 API 文档：[**ReDoc**](https://github.com/Rebilly/ReDoc) ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -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/) 中: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) -* 在 PyCharm 中: +* 在 [PyCharm](https://www.jetbrains.com/pycharm/) 中: ![editor support](https://fastapi.tiangolo.com/img/pycharm-completion.png) @@ -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 框架，高性能，易于学习，高效编码，生产可用

- + Test - + Coverage - + Package version - + Supported Python versions

--- -**文档**： 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 -%} - + {% endfor -%} ### 金牌和银牌赞助商 { #gold-and-silver-sponsors } {% for sponsor in sponsors.gold -%} - + {% endfor -%} {%- for sponsor in sponsors.silver -%} - + {% endfor %} -其他赞助商 +[其他赞助商](https://fastapi.tiangolo.com/zh/fastapi-people/#sponsors) ## 评价 { #opinions } 「_[...] 最近我大量使用 **FastAPI**。[...] 我实际上计划把它用于我团队在 **微软** 的所有 **机器学习服务**。其中一些正在集成进核心 **Windows** 产品以及一些 **Office** 产品。_」 -
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 作者 (ref)
+
Timothy Crosley - [Hug](https://github.com/hugapi/hug) 作者 (ref)
--- @@ -107,27 +107,27 @@ FastAPI 是一个用于构建 API 的现代、快速（高性能）的 Web 框 「_我们已经把我们的 **API** 切换到 **FastAPI** [...] 我想你会喜欢它 [...]_」 -
Ines Montani - Matthew Honnibal - Explosion AI 创始人 - spaCy 作者 (ref) - (ref)
+
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)，你可以在线观看： -FastAPI Mini Documentary +FastAPI Mini Documentary ## **Typer**，命令行中的 FastAPI { #typer-the-fastapi-of-clis } - + -如果你要开发一个用于终端的 命令行应用而不是 Web API，看看 **Typer**。 +如果你要开发一个用于终端的 命令行应用而不是 Web API，看看 [**Typer**](https://typer.tiangolo.com/)。 **Typer** 是 FastAPI 的小同胞。它的目标是成为**命令行中的 FastAPI**。⌨️ 🚀 @@ -135,12 +135,12 @@ FastAPI 是一个用于构建 API 的现代、快速（高性能）的 Web 框 FastAPI 站在巨人的肩膀之上： -* Starlette 负责 Web 部分。 -* Pydantic 负责数据部分。 +* [Starlette](https://www.starlette.dev/) 负责 Web 部分。 +* [Pydantic](https://docs.pydantic.dev/) 负责数据部分。 ## 安装 { #installation } -创建并激活一个虚拟环境，然后安装 FastAPI： +创建并激活一个 [虚拟环境](https://fastapi.tiangolo.com/zh/virtual-environments/)，然后安装 FastAPI：
@@ -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.
-关于命令 fastapi dev main.py... +关于命令 fastapi dev... -`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/) 中了解更多。
### 检查 { #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) 提供）： ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) ### 可选的 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) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -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** 账号（我们从候补名单邀请了你 😉），你可以用一个命令部署你的应用。 -部署前，先确认已登录： - -
- -```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) 提供）： ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) ### 可选的 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) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -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 的联系信息。它可以包含多个字段。
contact 字段
参数类型描述
namestr联系人/组织的识别名称。
urlstr指向联系信息的 URL。必须采用 URL 格式。
emailstr联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。
| -| `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 格式。
| +| `license_info` | `dict` | 公开的 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 格式。
| 你可以按如下方式设置它们： @@ -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 文档： @@ -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` 可以做很多事情，它可以：