diff --git a/docs/zh/docs/_llm-test.md b/docs/zh/docs/_llm-test.md index 2e9e7816e..0da76d43c 100644 --- a/docs/zh/docs/_llm-test.md +++ b/docs/zh/docs/_llm-test.md @@ -37,7 +37,7 @@ 昨天，我的朋友写道："如果你把 incorrectly 拼对了，你就把它拼错了"。我回答："没错，但 'incorrectly' 错的不是 '"incorrectly"'"。 -/// note | 注意 +/// note LLM 很可能会把这段翻错。我们只关心在重新翻译时它是否能保持修正后的译文。 @@ -95,7 +95,7 @@ $ fastapi run 模式都需要使用 Marshmallow 提供的特定工具和类。 -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 使用代码定义“模式”，自动提供数据类型与校验。 @@ -162,13 +162,13 @@ Webargs 是一个在多个框架（包括 Flask）之上提供该功能的工具 在拥有 **FastAPI** 之前，我也大量使用过它，这是个很棒的工具。 -/// info | 信息 +/// note | 注意 Webargs 由与 Marshmallow 相同的开发者创建。 /// -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 对传入请求数据进行自动校验。 @@ -192,13 +192,13 @@ Marshmallow 与 Webargs 通过插件提供了校验、解析与序列化。 编辑器很难为此提供帮助；而且如果我们修改了参数或 Marshmallow 模式，却忘了同步更新那个 YAML 文档字符串，生成的模式就会过时。 -/// info | 信息 +/// note | 注意 APISpec 由与 Marshmallow 相同的开发者创建。 /// -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 支持开放的 API 标准 OpenAPI。 @@ -224,13 +224,13 @@ APISpec 由与 Marshmallow 相同的开发者创建。 这些全栈脚手架也成为了[**FastAPI** 项目脚手架](project-generation.md)的基础。 -/// info | 信息 +/// note | 注意 Flask-apispec 由与 Marshmallow 相同的开发者创建。 /// -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 从定义序列化与校验的同一份代码自动生成 OpenAPI 模式。 @@ -250,7 +250,7 @@ Flask-apispec 由与 Marshmallow 相同的开发者创建。 它对嵌套模型的支持并不好。如果请求的 JSON 体是包含嵌套 JSON 对象的 JSON 对象，则无法被正确文档化和校验。 -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 使用 Python 类型以获得出色的编辑器支持。 @@ -270,7 +270,7 @@ Flask-apispec 由与 Marshmallow 相同的开发者创建。 /// -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 找到实现疯狂性能的路径。 @@ -286,7 +286,7 @@ Falcon 是另一个高性能 Python 框架，它被设计为精简且可作为 H 因此，数据校验、序列化与文档要么需要手写完成，无法自动化；要么需要在 Falcon 之上实现一个框架，例如 Hug。其他受 Falcon 设计启发、采用“一个 request 对象 + 一个 response 对象作为参数”的框架也有同样的区别。 -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 寻找获得卓越性能的方法。 @@ -310,7 +310,7 @@ Falcon 是另一个高性能 Python 框架，它被设计为精简且可作为 H 路由在一个地方集中声明，使用在其他地方声明的函数（而不是使用可以直接放在处理端点函数之上的装饰器）。这更接近 Django 的做法，而不是 Flask（和 Starlette）。它在代码中割裂了相对紧耦合的内容。 -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 通过模型属性的“默认值”为数据类型定义额外校验。这提升了编辑器支持，而这在当时的 Pydantic 中尚不可用。 @@ -332,13 +332,13 @@ Hug 是最早使用 Python 类型提示来声明 API 参数类型的框架之一 由于基于同步 Python Web 框架的上一代标准（WSGI），它无法处理 WebSocket 等，尽管它的性能仍然很高。 -/// info | 信息 +/// note | 注意 Hug 由 Timothy Crosley 创建，他也是 [`isort`](https://github.com/timothycrosley/isort) 的作者，这是一个能自动排序 Python 文件中导入的优秀工具。 /// -/// check | 启发 **FastAPI** 的想法： +/// tip | 启发 **FastAPI** 的想法： Hug 启发了 APIStar 的部分设计，也是我当时最看好的工具之一，与 APIStar 并列。 @@ -372,7 +372,7 @@ Hug 启发 **FastAPI** 在函数中声明 `response` 参数，用于设置 heade 现在 APIStar 是一组用于校验 OpenAPI 规范的工具，而不是 Web 框架。 -/// info | 信息 +/// note | 注意 APIStar 由 Tom Christie 创建。他还创建了： @@ -382,7 +382,7 @@ APIStar 由 Tom Christie 创建。他还创建了： /// -/// check | 启发 **FastAPI**： +/// tip | 启发 **FastAPI**： 诞生。 @@ -406,7 +406,7 @@ Pydantic 是一个基于 Python 类型提示来定义数据校验、序列化与 它可与 Marshmallow 类比。尽管在基准测试中它比 Marshmallow 更快。并且由于同样基于 Python 类型提示，编辑器支持优秀。 -/// check | **FastAPI** 用它来： +/// tip | **FastAPI** 用它来： 处理所有数据校验、数据序列化与自动模型文档（基于 JSON Schema）。 @@ -449,7 +449,7 @@ ASGI 是由 Django 核心团队成员推动的新“标准”。它尚不是正 /// -/// check | **FastAPI** 用它来： +/// tip | **FastAPI** 用它来： 处理所有核心 Web 部分，并在其之上扩展功能。 @@ -467,7 +467,7 @@ Uvicorn 是一个基于 uvloop 与 httptools 构建的极速 ASGI 服务器。 它是 Starlette 与 **FastAPI** 推荐的服务器。 -/// check | **FastAPI** 推荐将其作为： +/// tip | **FastAPI** 推荐将其作为： 运行 **FastAPI** 应用的主要 Web 服务器。 diff --git a/docs/zh/docs/async.md b/docs/zh/docs/async.md index 92ee5ef22..bee98fc8b 100644 --- a/docs/zh/docs/async.md +++ b/docs/zh/docs/async.md @@ -23,13 +23,13 @@ async def read_results(): /// note | 注意 -你只能在被 `async def` 创建的函数内使用 `await` +你只能在被 `async def` 创建的函数内使用 `await`。 /// --- -如果你正在使用一个第三方库和某些组件（比如：数据库、API、文件系统...）进行通信，第三方库又不支持使用 `await` （目前大多数数据库三方库都是这样），这种情况你可以像平常那样使用 `def` 声明一个路径操作函数，就像这样： +如果你正在使用一个第三方库和某些组件（比如：数据库、API、文件系统等）进行通信，而该第三方库不支持使用 `await`（目前大多数数据库库都是这样），这种情况你可以像平常那样使用 `def` 声明一个路径操作函数，就像这样： ```Python hl_lines="2" @app.get('/') @@ -40,15 +40,15 @@ def results(): --- -如果你的应用程序不需要与其他任何东西通信而等待其响应，请使用 `async def`，即使函数内部不需要使用 `await`。 +如果你的应用程序（以某种方式）不需要与其他任何东西通信而等待其响应，请使用 `async def`，即使函数内部不需要使用 `await`。 --- -如果你不清楚，使用 `def` 就好. +如果你不清楚，使用 `def` 就好。 --- -**注意**：你可以根据需要在路径操作函数中混合使用 `def` 和 `async def`，并使用最适合你的方式去定义每个函数。FastAPI 将为他们做正确的事情。 +**注意**：你可以根据需要在路径操作函数中混合使用 `def` 和 `async def`，并使用最适合你的方式去定义每个函数。FastAPI 将为它们做正确的事情。 无论如何，在上述任何情况下，FastAPI 仍将异步工作，速度也非常快。 @@ -56,7 +56,7 @@ def results(): ## 技术细节 { #technical-details } -Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 `await` 语法的东西来写**”异步代码“**。 +Python 的现代版本支持通过一种叫**“协程”**——使用 `async` 和 `await` 语法的东西来写**“异步代码”**。 让我们在下面的部分中逐一介绍： @@ -66,24 +66,24 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 ## 异步代码 { #asynchronous-code } -异步代码仅仅意味着编程语言 💬 有办法告诉计算机/程序 🤖 在代码中的某个点，它 🤖 将不得不等待在某些地方完成一些事情。让我们假设一些事情被称为 "慢文件"📝. +异步代码仅仅意味着编程语言 💬 有办法告诉计算机/程序 🤖 在代码中的某个点，它 🤖 将不得不等待在某些地方完成一些事情。让我们假设一些事情被称为 "慢文件"📝。 所以，在等待"慢文件"📝完成的这段时间，计算机可以做一些其他工作。 然后计算机/程序 🤖 每次有机会都会回来，因为它又在等待，或者它 🤖 完成了当前所有的工作。而且它 🤖 将查看它等待的所有任务中是否有已经完成的，做它必须做的任何事情。 -接下来，它 🤖 完成第一个任务（比如是我们的"慢文件"📝) 并继续与之相关的一切。 +接下来，它 🤖 取第一个完成的任务（比如是我们的"慢文件"📝）并继续与之相关的一切。 -这个"等待其他事情"通常指的是一些相对较慢（与处理器和 RAM 存储器的速度相比）的 I/O 操作，比如说： +这个"等待其他事情"通常指的是一些相对较慢（与处理器和 RAM 存储器的速度相比）的 I/O 操作，比如说等待： * 通过网络发送来自客户端的数据 -* 客户端接收来自网络中的数据 -* 磁盘中要由系统读取并提供给程序的文件的内容 -* 程序提供给系统的要写入磁盘的内容 +* 客户端通过网络接收由你的程序发送的数据 +* 磁盘中文件的内容被系统读取并提供给你的程序 +* 你的程序提供给系统的内容被写入磁盘 * 一个 API 的远程调用 * 一个数据库操作，直到完成 * 一个数据库查询，直到返回结果 -* 等等. +* 等等。 这个执行的时间大多是在等待 I/O 操作，因此它们被叫做 "I/O 密集型" 操作。 @@ -139,7 +139,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 -/// info | 信息 +/// note | 注意 漂亮的插画来自 [Ketrina Thompson](https://www.instagram.com/ketrinadrawsalot)。🎨 @@ -147,31 +147,31 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 --- -在那个故事里，假设你是计算机程序 🤖 。 +在那个故事里，假设你是计算机程序 🤖。 -当你在排队时，你只是闲着😴， 轮到你前不做任何事情（仅排队）。但排队很快，因为收银员只接订单（不准备订单），所以这一切都还好。 +当你在排队时，你只是闲着😴，等待轮到你，不做任何非常“有成效”的事情。但排队很快，因为收银员只接订单（不准备订单），所以这一切都还好。 -然后，当轮到你时，需要你做一些实际性的工作，比如查看菜单，决定你想要什么，让你的恋人选择，支付，检查你是否提供了正确的账单或卡，检查你的收费是否正确，检查订单是否有正确的项目，等等。 +然后，当轮到你时，需要你做一些实际性的“有成效”的工作，比如查看菜单，决定你想要什么，让你的恋人选择，支付，检查你是否提供了正确的账单或卡，检查你的收费是否正确，检查订单是否有正确的项目，等等。 -此时，即使你仍然没有汉堡，你和收银员的工作也"暂停"了⏸， 因为你必须等待一段时间 🕙 让你的汉堡做好。 +此时，即使你仍然没有汉堡，你和收银员的工作也“暂停”了⏸，因为你必须等待一段时间 🕙 让你的汉堡做好。 -但是，当你离开柜台并坐在桌子旁，在轮到你的号码前的这段时间，你可以将焦点切换到 🔀 你的恋人上，并做一些"工作"⏯ 🤓。你可以做一些非常"有成效"的事情，比如和你的恋人调情😍. +但是，当你离开柜台并坐在桌子旁，手里拿着你的号码时，你可以将焦点切换到 🔀 你的恋人上，并在这上面“工作”⏯ 🤓。你可以做一些非常“有成效”的事情，比如和你的恋人调情😍。 -之后，收银员 💁 把号码显示在显示屏上，并说到 "汉堡做好了"，而当显示的号码是你的号码时，你不会立刻疯狂地跳起来。因为你知道没有人会偷你的汉堡，因为你有你的号码，而其他人又有他们自己的号码。 +之后，收银员 💁 把号码显示在显示屏上，并说到“汉堡做好了”，而当显示的号码变成你的号码时，你不会立刻疯狂地跳起来。因为你知道没有人会偷你的汉堡，因为你有你的号码，而其他人又有他们自己的号码。 -所以你要等待你的恋人完成故事（完成当前的工作⏯ /正在做的事🤓)， 轻轻微笑，说你要吃汉堡⏸. +所以你要等待你的恋人完成故事（完成当前的工作 ⏯ / 正在处理的任务 🤓)，轻轻微笑，说你要去拿汉堡 ⏸。 -然后你去柜台🔀， 到现在初始任务已经完成⏯， 拿起汉堡，说声谢谢，然后把它们送到桌上。这就完成了与计数器交互的步骤/任务⏹. 这反过来又产生了一项新任务，即"吃汉堡"🔀 ⏯， 上一个"拿汉堡"的任务已经结束了⏹. +然后你去柜台 🔀，回到现在已经完成 ⏯ 的初始任务，拿起汉堡，说声谢谢，然后把它们送到桌上。这就完成了与柜台交互的那个步骤/任务 ⏹。这反过来又产生了一项新任务，即“吃汉堡”🔀 ⏯，而上一个“拿汉堡”的任务已经结束了 ⏹。 ### 并行汉堡 { #parallel-burgers } -现在让我们假设不是"并发汉堡"，而是"并行汉堡"。 +现在让我们假设不是“并发汉堡”，而是“并行汉堡”。 你和你的恋人一起去吃并行快餐。 -你站在队伍中，同时是厨师的几个收银员（比方说8个）从前面的人那里接单。 +你站在队伍中，同时是厨师的几个收银员（比方说 8 个）从前面的人那里接单。 -你之前的每个人都在等待他们的汉堡准备好后才离开柜台，因为8名收银员都会在下一份订单前马上准备好汉堡。 +你之前的每个人都在等待他们的汉堡准备好后才离开柜台，因为 8 名收银员都会在下一份订单前马上准备好汉堡。 @@ -183,29 +183,29 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 收银员去厨房。 -你站在柜台前 🕙等待着，这样就不会有人在你之前抢走你的汉堡，因为没有轮流的号码。 +你站在柜台前 🕙 等待着，这样就不会有人在你之前抢走你的汉堡，因为没有轮流的号码。 -当你和你的恋人忙于不让任何人出现在你面前，并且在他们到来的时候拿走你的汉堡时，你无法关注到你的恋人。😞 +当你和你的恋人忙于不让任何人出现在你面前，并且在它们到来的时候拿走你的汉堡时，你无法关注到你的恋人。😞 -这是"同步"的工作，你被迫与服务员/厨师 👨‍🍳"同步"。你在此必须等待 🕙 ，在收银员/厨师 👨‍🍳 完成汉堡并将它们交给你的确切时间到达之前一直等待，否则其他人可能会拿走它们。 +这是“同步”的工作，你被迫与收银员/厨师 👨‍🍳“同步”。你必须 🕙 等待，并在收银员/厨师 👨‍🍳 完成汉堡并将它们交给你的确切时刻出现在那儿，否则其他人可能会拿走它们。 -你经过长时间的等待 🕙 ，收银员/厨师 👨‍🍳终于带着汉堡回到了柜台。 +你经过长时间的等待 🕙，收银员/厨师 👨‍🍳 终于带着汉堡回到了柜台。 -你拿着汉堡，和你的情人一起上桌。 +你拿着汉堡，和你的恋人一起上桌。 你们仅仅是吃了它们，就结束了。⏹ -没有太多的交谈或调情，因为大部分时间 🕙 都在柜台前等待😞。 +没有太多的交谈或调情，因为大部分时间 🕙 都在柜台前等待。😞 -/// info | 信息 +/// note | 注意 漂亮的插画来自 [Ketrina Thompson](https://www.instagram.com/ketrinadrawsalot)。🎨 @@ -213,7 +213,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 --- -在这个并行汉堡的场景中，你是一个计算机程序 🤖 且有两个处理器（你和你的恋人），都在等待 🕙 ，并投入他们的注意力 ⏯ 在柜台上等待了很长一段时间。 +在这个并行汉堡的场景中，你是一个计算机程序 🤖 且有两个处理器（你和你的恋人），都在等待 🕙，并将他们的注意力 ⏯ 投入到长时间“在柜台前等待”🕙 上。 这家快餐店有 8 个处理器（收银员/厨师）。而并发汉堡店可能只有 2 个（一个收银员和一个厨师）。 @@ -223,35 +223,35 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 这将是与汉堡的类似故事。🍔 -一种更"贴近生活"的例子，想象一家银行。 +一种更“贴近生活”的例子，想象一家银行。 -直到最近，大多数银行都有多个出纳员 👨‍💼👨‍💼👨‍💼👨‍💼 还有一条长长排队队伍🕙🕙🕙🕙🕙🕙🕙🕙。 +直到最近，大多数银行都有多个出纳员 👨‍💼👨‍💼👨‍💼👨‍💼 还有一条长长排队队伍 🕙🕙🕙🕙🕙🕙🕙🕙。 -所有收银员都是一个接一个的在客户面前做完所有的工作👨‍💼⏯. +所有收银员都是一个接一个地在客户面前做完所有的工作 👨‍💼⏯。 -你必须经过 🕙 较长时间排队，否则你就没机会了。 +你必须在队伍里 🕙 排很久，否则就会错过你的顺序。 -你可不会想带你的恋人 😍 和你一起去银行办事🏦. +你可不会想带你的恋人 😍 和你一起去银行办事 🏦。 ### 汉堡结论 { #burger-conclusion } -在"你与恋人一起吃汉堡"的这个场景中，因为有很多人在等待🕙， 使用并发系统更有意义⏸🔀⏯. +在“你与恋人一起吃汉堡”的这个场景中，因为有很多人在等待 🕙，使用并发系统更有意义 ⏸🔀⏯。 大多数 Web 应用都是这样的。 -你的服务器正在等待很多很多用户通过他们不太好的网络发送来的请求。 +你的服务器正在等待 🕙 很多很多用户通过他们不太好的网络发送来的请求。 然后再次等待 🕙 响应回来。 -这个"等待" 🕙 是以微秒为单位测量的，但总的来说，最后还是等待很久。 +这个“等待”🕙 是以微秒为单位测量的，但总的来说，最后还是等待很久。 -这就是为什么使用异步对于 Web API 很有意义的原因 ⏸🔀⏯。 +这就是为什么为 Web API 使用异步 ⏸🔀⏯ 很有意义。 -这种异步机制正是 NodeJS 受到欢迎的原因（尽管 NodeJS 不是并行的），以及 Go 作为编程语言的优势所在。 +这种异步机制正是 NodeJS 受到欢迎的原因（尽管 NodeJS 不是并行的），也是 Go 作为编程语言的优势所在。 这与 **FastAPI** 的性能水平相同。 -你可以同时拥有并行性和异步性，你可以获得比大多数经过测试的 NodeJS 框架更高的性能，并且与 Go 不相上下， Go 是一种更接近于 C 的编译语言（[全部归功于 Starlette](https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1)）。 +你可以同时拥有并行性和异步性，你可以获得比大多数经过测试的 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 } @@ -267,17 +267,17 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 --- -在任何地方， 都不需要等待 🕙 ，只需要在房子的多个地方做着很多工作。 +在任何地方，都不需要等待 🕙，只需要在房子的多个地方做着很多工作。 -你可以像汉堡的例子那样轮流执行，先是客厅，然后是厨房，但因为你不需要等待 🕙 ，对于任何事情都是清洁，清洁，还是清洁，轮流不会影响任何事情。 +你可以像汉堡的例子那样轮流执行，先是客厅，然后是厨房，但因为你不需要等待 🕙，对于任何事情都是清洁，清洁，还是清洁，轮流不会影响任何事情。 无论是否轮流执行（并发），都需要相同的时间来完成，而你也会完成相同的工作量。 -但在这种情况下，如果你能带上 8 名前收银员/厨师，现在是清洁工一起清扫，他们中的每一个人（加上你）都能占据房子的一个区域来清扫，你就可以在额外的帮助下并行的更快地完成所有工作。 +但在这种情况下，如果你能带上 8 名前收银员/厨师，现在是清洁工一起清扫，他们中的每一个人（加上你）都能占据房子的一个区域来清扫，你就可以在额外的帮助下并行地更快地完成所有工作。 在这个场景中，每个清洁工（包括你）都将是一个处理器，完成这个工作的一部分。 -由于大多数执行时间是由实际工作（而不是等待）占用的，并且计算机中的工作是由 CPU 完成的，所以他们称这些问题为"CPU 密集型"。 +由于大多数执行时间是由实际工作（而不是等待）占用的，并且计算机中的工作是由 CPU 完成的，所以他们称这些问题为“CPU 密集型”。 --- @@ -286,9 +286,9 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。 例如： * **音频**或**图像**处理； -* **计算机视觉**: 一幅图像由数百万像素组成，每个像素有3种颜色值，处理通常需要同时对这些像素进行计算； -* **机器学习**: 它通常需要大量的"矩阵"和"向量"乘法。想象一个包含数字的巨大电子表格，并同时将所有数字相乘； -* **深度学习**: 这是机器学习的一个子领域，同样适用。只是没有一个数字的电子表格可以相乘，而是一个庞大的数字集合，在很多情况下，你需要使用一个特殊的处理器来构建和使用这些模型。 +* **计算机视觉**：一幅图像由数百万像素组成，每个像素有 3 种颜色值，处理通常需要同时对这些像素进行计算； +* **机器学习**：它通常需要大量的“矩阵”和“向量”乘法。想象一个包含数字的巨大电子表格，并同时将所有数字相乘； +* **深度学习**：这是机器学习的一个子领域，同样适用。只是没有一个数字的电子表格可以相乘，而是一个庞大的数字集合，在很多情况下，你需要使用一个特殊的处理器来构建和/或使用这些模型。 ### 并发 + 并行: Web + 机器学习 { #concurrency-parallelism-web-machine-learning } @@ -302,7 +302,7 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。 ## `async` 和 `await` { #async-and-await } -现代版本的 Python 有一种非常直观的方式来定义异步代码。这使它看起来就像正常的"顺序"代码，并在适当的时候"等待"。 +现代版本的 Python 有一种非常直观的方式来定义异步代码。这使它看起来就像正常的“顺序”代码，并在适当的时候为你“等待”。 当有一个操作需要等待才能给出结果，且支持这个新的 Python 特性时，你可以编写如下代码： @@ -310,7 +310,7 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。 burgers = await get_burgers(2) ``` -这里的关键是 `await`。它告诉 Python 它必须等待 ⏸ `get_burgers(2)` 完成它的工作 🕙 ，然后将结果存储在 `burgers` 中。这样，Python 就会知道此时它可以去做其他事情 🔀 ⏯ （比如接收另一个请求）。 +这里的关键是 `await`。它告诉 Python 它必须等待 ⏸ `get_burgers(2)` 完成它的工作 🕙，然后将结果存储在 `burgers` 中。这样，Python 就会知道此时它可以去做其他事情 🔀 ⏯（比如接收另一个请求）。 要使 `await` 工作，它必须位于支持这种异步机制的函数内。因此，只需使用 `async def` 声明它： @@ -329,9 +329,9 @@ def get_sequential_burgers(number: int): return burgers ``` -使用 `async def`，Python 就知道在该函数中，它将遇上 `await`，并且它可以"暂停" ⏸ 执行该函数，直至执行其他操作 🔀 后回来。 +使用 `async def`，Python 就知道在该函数中，它将遇上 `await`，并且它可以“暂停”⏸ 执行该函数，直至执行其他操作 🔀 后回来。 -当你想调用一个 `async def` 函数时，你必须"等待"它。因此，这不会起作用： +当你想调用一个 `async def` 函数时，你必须“等待”它。因此，这不会起作用： ```Python # 这样不行，因为 get_burgers 是用 async def 定义的 @@ -340,7 +340,7 @@ burgers = get_burgers(2) --- -因此，如果你使用的库告诉你可以使用 `await` 调用它，则需要使用 `async def` 创建路径操作函数 ，如： +因此，如果你使用的库告诉你可以使用 `await` 调用它，则需要使用 `async def` 创建路径操作函数，如： ```Python hl_lines="2-3" @app.get('/burgers') @@ -353,21 +353,21 @@ async def read_burgers(): 你可能已经注意到，`await` 只能在 `async def` 定义的函数内部使用。 -但与此同时，必须"等待"通过 `async def` 定义的函数。因此，带 `async def` 的函数也只能在 `async def` 定义的函数内部调用。 +但与此同时，必须“等待”通过 `async def` 定义的函数。因此，带 `async def` 的函数也只能在 `async def` 定义的函数内部调用。 那么，这关于先有鸡还是先有蛋的问题，如何调用第一个 `async` 函数？ -如果你使用 **FastAPI**，你不必担心这一点，因为"第一个"函数将是你的路径操作函数，FastAPI 将知道如何做正确的事情。 +如果你使用 **FastAPI**，你不必担心这一点，因为“第一个”函数将是你的路径操作函数，FastAPI 将知道如何做正确的事情。 但如果你想在没有 FastAPI 的情况下使用 `async` / `await`，则可以这样做。 ### 编写自己的异步代码 { #write-your-own-async-code } -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/)。 +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](https://anyio.readthedocs.io/en/stable/) 来处理高级的并发用例，这些用例需要在自己的代码中使用更高级的模式。 -即使你没有使用 **FastAPI**，你也可以使用 [AnyIO](https://anyio.readthedocs.io/en/stable/) 编写自己的异步程序，使其拥有较高的兼容性并获得一些好处（例如， 结构化并发）。 +即使你没有使用 **FastAPI**，你也可以使用 [AnyIO](https://anyio.readthedocs.io/en/stable/) 编写自己的异步程序，使其拥有较高的兼容性并获得一些好处（例如，结构化并发）。 我基于 AnyIO 新建了一个库，作为一个轻量级的封装层，用来优化类型注解，同时提供了更好的**自动补全**、**内联错误提示**等功能。这个库还附带了一个友好的入门指南和教程，能帮助你**理解**并编写**自己的异步代码**：[Asyncer](https://asyncer.tiangolo.com/)。如果你有**结合使用异步代码和常规**（阻塞/同步）代码的需求，这个库会特别有用。 @@ -383,13 +383,13 @@ Starlette （和 **FastAPI**） 是基于 [AnyIO](https://anyio.readthedocs.io/e 在以前版本的 Python，你可以使用多线程或者 [Gevent](https://www.gevent.org/)。但代码的理解、调试和思考都要复杂许多。 -在以前版本的 NodeJS / 浏览器 JavaScript 中，你会使用"回调"，因此也可能导致“回调地狱”。 +在以前版本的 NodeJS / 浏览器 JavaScript 中，你会使用“回调”，因此也可能导致“回调地狱”。 ## 协程 { #coroutines } -**协程**只是 `async def` 函数返回的一个非常奇特的东西的称呼。Python 知道它有点像一个函数，它可以启动，也会在某个时刻结束，而且它可能会在内部暂停 ⏸ ，只要内部有一个 `await`。 +**协程**只是 `async def` 函数返回的一个非常奇特的东西的称呼。Python 知道它有点像一个函数，它可以启动，也会在某个时刻结束，而且它可能会在内部暂停 ⏸，只要内部有一个 `await`。 -通过使用 `async` 和 `await` 的异步代码的所有功能大多数被概括为"协程"。它可以与 Go 的主要关键特性 "Goroutines" 相媲美。 +通过使用 `async` 和 `await` 的异步代码的所有功能大多数被概括为“协程”。它可以与 Go 的主要关键特性 “Goroutines” 相媲美。 ## 结论 { #conclusion } @@ -417,9 +417,9 @@ Starlette （和 **FastAPI**） 是基于 [AnyIO](https://anyio.readthedocs.io/e 当你使用 `def` 而不是 `async def` 来声明一个*路径操作函数*时，它运行在外部的线程池中并等待其结果，而不是直接调用（因为它会阻塞服务器）。 -如果你使用过另一个不以上述方式工作的异步框架，并且你习惯于用普通的 `def` 定义普通的仅计算路径操作函数，以获得微小的性能增益（大约100纳秒），请注意，在 FastAPI 中，效果将完全相反。在这些情况下，最好使用 `async def`，除非路径操作函数内使用执行阻塞 I/O 的代码。 +如果你使用过另一个不以上述方式工作的异步框架，并且你习惯于用普通的 `def` 定义普通的仅计算路径操作函数，以获得微小的性能增益（大约 100 纳秒），请注意，在 FastAPI 中，效果将完全相反。在这些情况下，最好使用 `async def`，除非路径操作函数内使用执行阻塞 I/O 的代码。 -在这两种情况下，与你之前的框架相比，**FastAPI** 可能[仍然很快](index.md#performance)。 +在这两种情况下，**FastAPI** [仍然会更快](index.md#performance)（或至少与之前的框架相当）。 ### 依赖 { #dependencies } @@ -427,7 +427,7 @@ Starlette （和 **FastAPI**） 是基于 [AnyIO](https://anyio.readthedocs.io/e ### 子依赖 { #sub-dependencies } -你可以拥有多个相互依赖的依赖以及[子依赖](tutorial/dependencies/sub-dependencies.md) （作为函数的参数），它们中的一些可能是通过 `async def` 声明，也可能是通过 `def` 声明。它们仍然可以正常工作，这些通过 `def` 声明的函数将会在外部线程中调用（来自线程池），而不是"被等待"。 +你可以拥有多个相互依赖的依赖以及[子依赖](tutorial/dependencies/sub-dependencies.md)（作为函数的参数），它们中的一些可能是通过 `async def` 声明，也可能是通过 `def` 声明。它们仍然可以正常工作，这些通过 `def` 声明的函数将会在外部线程中调用（来自线程池），而不是“被等待”。 ### 其他函数 { #other-utility-functions } @@ -435,10 +435,10 @@ Starlette （和 **FastAPI**） 是基于 [AnyIO](https://anyio.readthedocs.io/e 这与 FastAPI 为你调用*路径操作函数*和依赖项的逻辑相反。 -如果你的函数是通过 `def` 声明的，它将被直接调用（在代码中编写的地方），而不会在线程池中，如果这个函数通过 `async def` 声明，当在代码中调用时，你就应该使用 `await` 等待函数的结果。 +如果你的函数是通过 `def` 声明的，它将被直接调用（在代码中编写的地方），而不会在线程池中；如果这个函数通过 `async def` 声明，当在代码中调用时，你就应该使用 `await` 等待函数的结果。 --- 再次提醒，这些是非常技术性的细节，如果你来搜索它可能对你有用。 -否则，你最好应该遵守的指导原则赶时间吗？. +否则，你最好应该遵守的指导原则赶时间吗？。 diff --git a/docs/zh/docs/fastapi-cli.md b/docs/zh/docs/fastapi-cli.md index 151b7e61e..ff05e1bfb 100644 --- a/docs/zh/docs/fastapi-cli.md +++ b/docs/zh/docs/fastapi-cli.md @@ -95,7 +95,7 @@ entrypoint = "backend.main:app" from backend.main import app ``` -### 带路径的 `fastapi dev` { #fastapi-dev-with-path } +### 带路径或使用 `--entrypoint` CLI 选项的 `fastapi dev` { #fastapi-dev-with-path-or-with-entrypoint-cli-option } 你也可以把文件路径传给 `fastapi dev` 命令，它会猜测要使用的 FastAPI 应用对象： @@ -103,7 +103,13 @@ from backend.main import app $ fastapi dev main.py ``` -但每次运行 `fastapi` 命令都需要记得传入正确的路径。 +或者，你也可以给 `fastapi dev` 命令传入 `--entrypoint` 选项： + +```console +$ fastapi dev --entrypoint main:app +``` + +但每次运行 `fastapi` 命令都需要记得传入正确的路径或 entrypoint。 另外，其他工具可能找不到它，例如 [VS Code 扩展](editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com)，因此推荐在 `pyproject.toml` 中使用 `entrypoint`。 diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md index ad6b77f74..5fd9d48c4 100644 --- a/docs/zh/docs/features.md +++ b/docs/zh/docs/features.md @@ -64,7 +64,7 @@ my_second_user: User = User(**second_user_data) ``` -/// info | 信息 +/// note | 注意 `**second_user_data` 意思是： diff --git a/docs/zh/docs/help-fastapi.md b/docs/zh/docs/help-fastapi.md index 65ef2959d..2ff9752eb 100644 --- a/docs/zh/docs/help-fastapi.md +++ b/docs/zh/docs/help-fastapi.md @@ -1,14 +1,8 @@ -# 帮助 FastAPI - 获取帮助 { #help-fastapi-get-help } +# 帮助 { #help } -你喜欢 **FastAPI** 吗？ +你想帮助 FastAPI，或获取 FastAPI 的帮助吗？ -想帮助 FastAPI、其他用户和作者吗？ - -或者你想获取 **FastAPI** 的帮助？ - -有很多非常简单的方式可以帮忙（有些只需点一两下）。 - -同样，也有多种途径可以获得帮助。 +有很多非常简单的方式可以帮忙并获得帮助。 ## 订阅新闻邮件 { #subscribe-to-the-newsletter } @@ -20,15 +14,19 @@ * 破坏性更改 🚨 * 使用技巧 ✅ -## 在 X (Twitter) 上关注 FastAPI { #follow-fastapi-on-x-twitter } +## 在线关注 FastAPI { #follow-fastapi-online } -[在 **X (Twitter)** 上关注 @fastapi](https://x.com/fastapi) 获取 **FastAPI** 的最新动态。🐦 +你可以在以下平台关注 **FastAPI**： + +* [**X / Twitter** 上的 @fastapi](https://x.com/fastapi) +* [**Bluesky** 上的 @fastapi.tiangolo.com](https://bsky.app/profile/fastapi.tiangolo.com) +* [**LinkedIn** 上的 FastAPI](https://www.linkedin.com/company/fastapi/) ## 在 GitHub 上为 **FastAPI** 加星 { #star-fastapi-in-github } 你可以在 GitHub 上为 FastAPI 点亮「星标」（点击右上角的星形按钮）：[https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi)。⭐️ -点亮星标后，其他用户更容易发现它，并看到它已经对许多人有帮助。 +加星后，其他用户更容易发现它，并看到它已经对许多人有帮助。 ## 关注 GitHub 资源库的版本发布 { #watch-the-github-repository-for-releases } @@ -38,97 +36,28 @@ 这样做之后，每当 **FastAPI** 发布新版本（包含修复和新功能），你都会收到通知（邮件）。 -## 联系作者 { #connect-with-the-author } +## 关注作者 { #follow-the-author } -你可以联系[我（Sebastián Ramírez / `tiangolo`）](https://tiangolo.com)，作者本人。 +你可以关注[我（Sebastián Ramírez / `tiangolo`）](https://tiangolo.com)，作者本人，在以下平台，获取我发布的关于 FastAPI 及其小伙伴的消息： -你可以： - -* [在 **GitHub** 上关注我](https://github.com/tiangolo)。 - * 了解我创建的其他开源项目，也许对你有帮助。 - * 关注我何时创建新的开源项目。 -* 关注我在 [**X (Twitter)**](https://x.com/tiangolo) 或 [Mastodon](https://fosstodon.org/@tiangolo)。 - * 告诉我你如何使用 FastAPI（我很喜欢听这些）。 - * 获取我发布公告或新工具的消息。 - * 你也可以[在 X (Twitter) 上关注 @fastapi](https://x.com/fastapi)（独立账号）。 -* [在 **LinkedIn** 上关注我](https://www.linkedin.com/in/tiangolo/)。 - * 获取我发布公告或新工具的消息（不过我更常用 X (Twitter) 🤷‍♂）。 -* 阅读我在 [**Dev.to**](https://dev.to/tiangolo) 或 [**Medium**](https://medium.com/@tiangolo) 上的文章（或关注我）。 - * 阅读我的其他想法、文章，以及我创建的工具。 - * 关注我，这样当我发布新文章时你会第一时间看到。 - -## 发推谈谈 **FastAPI** { #tweet-about-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** 投票](https://www.slant.co/options/34241/~fastapi-review)。 -* [在 AlternativeTo 上为 **FastAPI** 投票](https://alternativeto.net/software/fastapi/about/)。 -* [在 StackShare 上标注你在用 **FastAPI**](https://stackshare.io/pypi-fastapi)。 +* [@tiangolo 在 **GitHub** 上](https://github.com/tiangolo)。 +* [@tiangolo 在 **X (Twitter)** 上](https://x.com/tiangolo) +* [@tiangolo.com 在 **Bluesky** 上](https://bsky.app/profile/tiangolo.com) +* [@tiangolo 在 **LinkedIn** 上](https://www.linkedin.com/in/tiangolo/)。 ## 在 GitHub 上帮别人解答问题 { #help-others-with-questions-in-github } -你可以尝试在以下地方帮助他人解答问题： - -* [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+) +你可以尝试在 [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) 中帮助他人解答问题。 很多情况下，你也许已经知道这些问题的答案了。🤓 如果你帮助了很多人解答问题，你会成为官方的 [FastAPI 专家](fastapi-people.md#fastapi-experts)。🎉 -只要记住，最重要的一点是：尽量友善。人们带着挫败感而来，很多时候他们的提问方式并不理想，但请尽你所能地友好对待。🤗 +只要记住，最重要的是：尽量友善。🤗 -我们的目标是让 **FastAPI** 社区友好且包容。同时，也不要接受对他人的霸凌或不尊重。我们需要彼此照顾。 +### 如何提供帮助 { #how-to-help } ---- - -以下是如何帮助他人解答问题（在 Discussions 或 Issues 中）： - -### 理解问题 { #understand-the-question } - -* 看看你是否能理解提问者的**目的**和使用场景。 - -* 然后检查问题（绝大多数是提问）是否**清晰**。 - -* 很多时候，问题是围绕提问者想象中的解决方案，但可能有**更好的**方案。如果你更好地理解了问题和使用场景，你就可能提出更**合适的替代方案**。 - -* 如果你没能理解问题，请请求更多**细节**。 - -### 复现问题 { #reproduce-the-problem } - -在大多数情况下与问题相关的都是提问者的**原始代码**。 - -很多时候他们只会粘贴一小段代码，但这不足以**复现问题**。 - -* 你可以请他们提供一个[可最小复现的示例](https://stackoverflow.com/help/minimal-reproducible-example)，你可以**复制粘贴**并在本地运行，看到与他们相同的错误或行为，或者更好地理解他们的用例。 - -* 如果你非常热心，你也可以尝试仅根据问题描述自己**构造一个示例**。不过要记住，这可能会花很多时间，通常先请他们澄清问题会更好。 - -### 提出解决方案 { #suggest-solutions } - -* 在能够理解问题之后，你可以给出一个可能的**答案**。 - -* 很多情况下，更好的是去理解他们**底层的问题或场景**，因为可能存在比他们尝试的方法更好的解决方式。 - -### 请求关闭问题 { #ask-to-close } - -如果他们回复了，很有可能你已经解决了他们的问题，恭喜，**你是英雄**！🦸 - -* 现在，如果问题已解决，你可以请他们： - * 在 GitHub Discussions 中：将你的评论标记为**答案**。 - * 在 GitHub Issues 中：**关闭**该 issue。 - -## 关注 GitHub 资源库 { #watch-the-github-repository } - -你可以在 GitHub 上「关注」FastAPI（点击右上角的「watch」按钮）：[https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi)。👀 - -如果你选择「Watching」而非「Releases only」，当有人创建新的 issue 或问题时你会收到通知。你也可以指定只通知新 issues、discussions、PR 等。 - -然后你就可以尝试帮助他们解决这些问题。 +请参照这里的[帮助指南](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github)。 ## 提问 { #ask-questions } @@ -137,100 +66,13 @@ * 提出一个**问题**或关于某个**问题**的求助。 * 建议一个新的**功能**。 -**注意**：如果你这么做了，我也会请你去帮助其他人。😉 - -## 审阅 Pull Request { #review-pull-requests } - -你可以帮我审阅他人的 Pull Request。 - -再次提醒，请尽力保持友善。🤗 - ---- - -下面是需要注意的点，以及如何审阅一个 Pull Request： - -### 理解问题 { #understand-the-problem } - -* 首先，确保你**理解这个 PR 要解决的问题**。它可能在 GitHub Discussion 或 issue 中有更长的讨论。 - -* 也有很大可能这个 PR 实际上并不需要，因为问题可以用**不同方式**解决。这种情况下你可以提出或询问该方案。 - -### 不用过分担心风格 { #dont-worry-about-style } - -* 不用太在意提交信息风格等，我会在合并时 squash 并手动调整提交信息。 - -* 也不用过分担心代码风格规则，已经有自动化工具在检查。 - -如果还有其他风格或一致性需求，我会直接提出，或者我会在其上追加提交做必要修改。 - -### 检查代码 { #check-the-code } - -* 检查并阅读代码，看看是否说得通，**在本地运行**并确认它确实解决了问题。 - -* 然后**评论**说明你已经这样做了，这样我就知道你确实检查过。 - -/// info | 信息 - -不幸的是，我不能仅仅信任那些有很多人批准的 PR。 - -多次发生过这样的情况：PR 有 3、5 个甚至更多的批准，可能是因为描述很吸引人，但当我检查时，它们实际上是坏的、有 bug，或者并没有解决它声称要解决的问题。😅 - -所以，真正重要的是你确实读过并运行过代码，并在评论里告诉我你做过这些。🤓 - -/// - -* 如果 PR 可以在某些方面简化，你可以提出建议，但没必要过分挑剔，很多东西比较主观（我也会有我自己的看法 🙈），因此尽量关注关键点更好。 - -### 测试 { #tests } - -* 帮我检查 PR 是否包含**测试**。 - -* 确认在合并 PR 之前，测试**会失败**。🚨 - -* 然后确认合并 PR 之后，测试**能通过**。✅ - -* 很多 PR 没有测试，你可以**提醒**他们添加测试，或者你甚至可以自己**建议**一些测试。这是最耗时的部分之一，你能在这方面帮上大忙。 - -* 然后也请评论你做了哪些验证，这样我就知道你检查过。🤓 - -## 创建 Pull Request { #create-a-pull-request } - -你可以通过 Pull Request 为源代码[做贡献](contributing.md)，例如： - -* 修正文档中的一个错别字。 -* 通过[编辑这个文件](https://github.com/fastapi/fastapi/edit/master/docs/en/data/external_links.yml)分享你创建或发现的关于 FastAPI 的文章、视频或播客。 - * 请确保把你的链接添加到相应区块的开头。 -* 帮助把[文档翻译](contributing.md#translations)成你的语言。 - * 你也可以审阅他人创建的翻译。 -* 提议新增文档章节。 -* 修复现有 issue/bug。 - * 记得添加测试。 -* 添加新功能。 - * 记得添加测试。 - * 如果相关，记得补充文档。 - -## 帮忙维护 FastAPI { #help-maintain-fastapi } - -帮我一起维护 **FastAPI** 吧！🤓 - -有很多工作要做，其中大部分其实**你**都能做。 - -你现在就能做的主要事情有： - -* [在 GitHub 上帮别人解答问题](#help-others-with-questions-in-github)（见上面的章节）。 -* [审阅 Pull Request](#review-pull-requests)（见上面的章节）。 - -这两项工作是**最耗时**的。这也是维护 FastAPI 的主要工作。 - -如果你能在这方面帮我，**你就是在帮我维护 FastAPI**，并确保它**更快更好地前进**。🚀 - ## 加入聊天 { #join-the-chat } 加入 👥 [Discord 聊天服务器](https://discord.gg/VQjSZaeJmf) 👥，和 FastAPI 社区的小伙伴们一起交流。 /// tip | 提示 -关于提问，请在 [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/new?category=questions) 中发布，这样更有机会得到 [FastAPI 专家](fastapi-people.md#fastapi-experts) 的帮助。 +关于问题，请在 GitHub Discussions 中提问，这样更有机会得到帮助。 聊天仅用于其他日常交流。 @@ -240,16 +82,6 @@ 请记住，聊天更偏向“自由交流”，很容易提出过于笼统、难以回答的问题，因此你可能收不到解答。 -在 GitHub 中，模板会引导你写出恰当的问题，从而更容易获得好的回答，甚至在提问之前就能自己解决。而且在 GitHub 里，我能尽量确保最终回复每个问题，即使这需要一些时间。对聊天系统来说，我个人做不到这一点。😅 +在 GitHub 中，模板会引导你写出恰当的问题，从而更容易获得好的回答，甚至在提问之前就能自己解决。 -聊天系统中的对话也不像 GitHub 那样容易搜索，因此问答可能在聊天中淹没。而且只有在 GitHub 中的问答才会计入成为 [FastAPI 专家](fastapi-people.md#fastapi-experts) 的贡献，所以你在 GitHub 上更可能获得关注。 - -另一方面，聊天系统里有成千上万的用户，你几乎随时都能在那里找到聊得来的人。😄 - -## 赞助作者 { #sponsor-the-author } - -如果你的**产品/公司**依赖或与 **FastAPI** 相关，并且你想触达它的用户，你可以通过 [GitHub sponsors](https://github.com/sponsors/tiangolo) 赞助作者（我）。根据赞助层级，你还可能获得一些额外福利，比如在文档中展示徽章。🎁 - ---- - -谢谢！🚀 +聊天系统中的对话也不像 GitHub 那样容易搜索，它们会淹没消失。 diff --git a/docs/zh/docs/python-types.md b/docs/zh/docs/python-types.md index 9b2fceb98..7901f9702 100644 --- a/docs/zh/docs/python-types.md +++ b/docs/zh/docs/python-types.md @@ -135,7 +135,7 @@ John Doe {* ../../docs_src/python_types/tutorial005_py310.py hl[1] *} -### typing 模块 { #typing-module } +### `typing` 模块 { #typing-module } 在一些额外的用例中，你可能需要从标准库的 `typing` 模块导入内容。比如当你想声明“任意类型”时，可以使用 `typing` 中的 `Any`： @@ -172,7 +172,7 @@ def some_function(data: Any): {* ../../docs_src/python_types/tutorial006_py310.py hl[1] *} -/// info | 信息 +/// note | 注意 方括号中的这些内部类型称为“类型参数”（type parameters）。 @@ -283,7 +283,7 @@ def some_function(data: Any): {* ../../docs_src/python_types/tutorial011_py310.py *} -/// info | 信息 +/// note | 注意 想了解更多关于 [Pydantic](https://docs.pydantic.dev/) 的信息，请查看其文档。 @@ -341,7 +341,7 @@ Python 本身不会对这个 `Annotated` 做任何处理。对于编辑器和其 重要的是，通过使用标准的 Python 类型，而且只在一个地方声明（而不是添加更多类、装饰器等），**FastAPI** 会为你完成大量工作。 -/// info | 信息 +/// note | 注意 如果你已经读完所有教程，又回来想进一步了解类型，一个不错的资源是 [`mypy` 的“速查表”](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html)。 diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md index 74522f838..cbee84f35 100644 --- a/docs/zh/docs/tutorial/bigger-applications.md +++ b/docs/zh/docs/tutorial/bigger-applications.md @@ -4,7 +4,7 @@ **FastAPI** 提供了一个方便的工具，可以在保持所有灵活性的同时构建你的应用程序。 -/// info | 信息 +/// note | 注意 如果你来自 Flask，那这将相当于 Flask 的 Blueprints。 @@ -194,7 +194,7 @@ async def read_item(item_id: str): /// -/// check | 检查 +/// tip | 提示 `prefix`、`tags`、`responses` 以及 `dependencies` 参数只是（和其他很多情况一样）**FastAPI** 的一个用于帮助你避免代码重复的功能。 @@ -339,7 +339,7 @@ from .routers import items, users from app.routers import items, users ``` -/// info | 信息 +/// note | 注意 第一个版本是「相对导入」： @@ -382,7 +382,7 @@ from .routers.users import router {* ../../docs_src/bigger_applications/app_an_py310/main.py hl[10:11] title["app/main.py"] *} -/// info | 信息 +/// note | 注意 `users.router` 包含了 `app/routers/users.py` 文件中的 `APIRouter`。 @@ -402,7 +402,7 @@ from .routers.users import router /// -/// check | 检查 +/// tip | 提示 包含路由器时，你不必担心性能问题。 @@ -451,7 +451,7 @@ from .routers.users import router 它将与通过 `app.include_router()` 添加的所有其他*路径操作*一起正常运行。 -/// info | 非常技术细节 +/// note | 非常技术细节 **注意**：这是一个非常技术性的细节，你也许可以**直接跳过**。 diff --git a/docs/zh/docs/tutorial/header-params.md b/docs/zh/docs/tutorial/header-params.md index ccb88ae7f..e197a3c7b 100644 --- a/docs/zh/docs/tutorial/header-params.md +++ b/docs/zh/docs/tutorial/header-params.md @@ -24,7 +24,7 @@ /// -/// info | 信息 +/// note 必须使用 `Header` 声明 header 参数，否则该参数会被解释为查询参数。 @@ -48,7 +48,7 @@ {* ../../docs_src/header_params/tutorial002_an_py310.py hl[10] *} -/// warning | 警告 +/// warning 注意，使用 `convert_underscores = False` 要慎重，有些 HTTP 代理和服务器不支持使用带有下划线的请求头。 diff --git a/docs/zh/docs/virtual-environments.md b/docs/zh/docs/virtual-environments.md index 7a96170d3..d10251dbe 100644 --- a/docs/zh/docs/virtual-environments.md +++ b/docs/zh/docs/virtual-environments.md @@ -2,7 +2,7 @@ 当你在 Python 工程中工作时，你可能会有必要用到一个**虚拟环境**（或类似的机制）来隔离你为每个工程安装的包。 -/// info | 信息 +/// note | 注意 如果你已经了解虚拟环境，知道如何创建和使用它们，你可以考虑跳过这一部分。🤓 @@ -18,7 +18,7 @@ /// -/// info | 信息 +/// note | 注意 这个页面将教你如何使用**虚拟环境**以及了解它们的工作原理。