mirror
/
tiangolo.fastapi
mirror of https://github.com/tiangolo/fastapi
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Merge branch 'master' into fix-test-query

pull/13417/head
Valentyn 4 days ago
committed by GitHub
parent
2efdfce752 1d434dec47
commit
5a38ccf797
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
6 changed files with 250 additions and 211 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 2
      docs/en/data/external_links.yml
  2. 5
      docs/en/docs/release-notes.md
  3. 72
      docs/ru/docs/tutorial/header-param-models.md
  4. 158
      docs/zh/docs/deployment/manually.md
  5. 144
      docs/zh/docs/deployment/server-workers.md
  6. 80
      docs/zh/docs/tutorial/index.md

2
docs/en/data/external_links.yml
View File

@ -412,7 +412,7 @@ Talks:
link: https://www.youtube.com/watch?v=3DLwPcrE5mA
title: 'PyCon UK 2019: FastAPI from the ground up'
Taiwanese:
- author: Bluewen
- author: Blueswen
author_link: https://github.com/blueswen
link: https://www.youtube.com/watch?v=y3sumuoDq4w
title: 'PyCon TW 2024: 全方位強化 Python 服務可觀測性：以 FastAPI 和 Grafana Stack 為例'

5
docs/en/docs/release-notes.md
View File

@ -9,10 +9,15 @@ hide:
### Docs
* ✏️ Fix talk information typo. PR [#13544](https://github.com/fastapi/fastapi/pull/13544) by [@blueswen](https://github.com/blueswen).
* 📝 Add External Link: Taiwanese talk on FastAPI with observability . PR [#13527](https://github.com/fastapi/fastapi/pull/13527) by [@blueswen](https://github.com/blueswen).
### Translations
* 🌐 Add Russian translation for `docs/ru/docs/tutorial/header-param-models.md`. PR [#13526](https://github.com/fastapi/fastapi/pull/13526) by [@minaton-ru](https://github.com/minaton-ru).
* 🌐 Update Chinese translation for `docs/zh/docs/tutorial/index.md`. PR [#13374](https://github.com/fastapi/fastapi/pull/13374) by [@Zhongheng-Cheng](https://github.com/Zhongheng-Cheng).
* 🌐 Update Chinese translation for `docs/zh/docs/deployment/manually.md`. PR [#13324](https://github.com/fastapi/fastapi/pull/13324) by [@Zhongheng-Cheng](https://github.com/Zhongheng-Cheng).
* 🌐 Update Chinese translation for `docs/zh/docs/deployment/server-workers.md`. PR [#13292](https://github.com/fastapi/fastapi/pull/13292) by [@Zhongheng-Cheng](https://github.com/Zhongheng-Cheng).
* 🌐 Update Chinese translation for `docs/zh/docs/tutorial/first-steps.md`. PR [#13348](https://github.com/fastapi/fastapi/pull/13348) by [@Zhongheng-Cheng](https://github.com/Zhongheng-Cheng).
### Internal

72
docs/ru/docs/tutorial/header-param-models.md
View File

@ -0,0 +1,72 @@
# Модели Header-параметров
Если у вас есть группа связанных **header-параметров**, то вы можете объединить их в одну **Pydantic-модель**.
Это позволит вам **переиспользовать модель** в **разных местах**, а также задать валидацию и метаданные сразу для всех параметров. 😎
/// note | Заметка
Этот функционал доступен в FastAPI начиная с версии `0.115.0`. 🤓
///
## Header-параметры в виде Pydantic-модели
Объявите нужные **header-параметры** в **Pydantic-модели** и затем аннотируйте параметр как `Header`:
{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
**FastAPI** **извлечёт** данные для **каждого поля** из **заголовков** запроса и выдаст заданную вами Pydantic-модель.
## Проверьте документацию
Вы можете посмотреть нужные header-параметры в графическом интерфейсе сгенерированной документации по пути `/docs`:
<div class="screenshot">
<img src="/img/tutorial/header-param-models/image01.png">
</div>
## Как запретить дополнительные заголовки
В некоторых случаях (не особо часто встречающихся) вам может понадобиться **ограничить** заголовки, которые вы хотите получать.
Вы можете использовать возможности конфигурации Pydantic-модели для того, чтобы запретить (`forbid`) любые дополнительные (`extra`) поля:
{* ../../docs_src/header_param_models/tutorial002_an_py310.py hl[10] *}
Если клиент попробует отправить **дополнительные заголовки**, то в ответ он получит **ошибку**.
Например, если клиент попытается отправить заголовок `tool` со значением `plumbus`, то в ответ он получит ошибку, сообщающую ему, что header-параметр `tool` не разрешен:
```json
{
"detail": [
{
"type": "extra_forbidden",
"loc": ["header", "tool"],
"msg": "Extra inputs are not permitted",
"input": "plumbus",
}
]
}
```
## Как отключить автоматическое преобразование подчеркиваний
Как и в случае с обычными заголовками, если у вас в именах параметров имеются символы подчеркивания, они **автоматически преобразовываются в дефис**.
Например, если в коде есть header-параметр `save_data`, то ожидаемый HTTP-заголовок будет `save-data` и именно так он будет отображаться в документации.
Если по каким-то причинам вам нужно отключить данное автоматическое преобразование, это можно сделать и для Pydantic-моделей для header-параметров.
{* ../../docs_src/header_param_models/tutorial003_an_py310.py hl[19] *}
/// warning | Внимание
Перед тем как устанавливать для параметра `convert_underscores` значение `False`, имейте в виду, что некоторые HTTP-прокси и серверы не разрешают использовать заголовки с символами подчеркивания.
///
## Резюме
Вы можете использовать **Pydantic-модели** для объявления **header-параметров** в **FastAPI**. 😎

158
docs/zh/docs/deployment/manually.md
View File

@ -1,159 +1,157 @@
# 手动运行服务器 - Uvicorn
# 手动运行服务器
在远程服务器计算机上运行 **FastAPI** 应用程序所需的主要东西是 ASGI 服务器程序，例如 **Uvicorn**。
## 使用 `fastapi run` 命令
有 3 个主要可选方案：
简而言之，使用 `fastapi run` 来运行您的 FastAPI 应用程序：
* <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>：高性能 ASGI 服务器。
* <a href="https://hypercorn.readthedocs.io/" class="external-link" target="_blank">Hypercorn</a>：与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。
* <a href="https://github.com/django/daphne" class="external-link" target="_blank">Daphne</a>：为 Django Channels 构建的 ASGI 服务器。
## 服务器主机和服务器程序
关于名称，有一个小细节需要记住。 💡
“**服务器**”一词通常用于指远程/云计算机（物理机或虚拟机）以及在该计算机上运行的程序（例如 Uvicorn）。
<div class="termy">
请记住，当您一般读到“服务器”这个名词时，它可能指的是这两者之一。
```console
$ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:solid">main.py</u>
当提到远程主机时，通常将其称为**服务器**，但也称为**机器**(machine)、**VM**（虚拟机）、**节点**。 这些都是指某种类型的远程计算机，通常运行 Linux，您可以在其中运行程序。
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting production server 🚀
Searching for package file structure from directories
with <font color="#3465A4">__init__.py</font> files
Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
## 安装服务器程序
<span style="background-color:#007166"><font color="#D3D7CF"> module </font></span> 🐍 main.py
您可以使用以下命令安装 ASGI 兼容服务器：
<span style="background-color:#007166"><font color="#D3D7CF"> code </font></span> Importing the FastAPI app object from the module with
the following code:
//// tab | Uvicorn
<u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>
* <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>，一个快如闪电 ASGI 服务器，基于 uvloop 和 httptools 构建。
<span style="background-color:#007166"><font color="#D3D7CF"> app </font></span> Using import string: <font color="#3465A4">main:app</font>
<div class="termy">
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Server started at <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000</u></font>
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Documentation at <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000/docs</u></font>
```console
$ pip install "uvicorn[standard]"
Logs:
---> 100%
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started server process <b>[</b><font color="#34E2E2"><b>2306215</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Waiting for application startup.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Application startup complete.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Uvicorn running on <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000</u></font> <b>(</b>Press CTRL+C
to quit<b>)</b>
```
</div>
/// tip
这在大多数情况下都能正常运行。😎
通过添加`standard`，Uvicorn 将安装并使用一些推荐的额外依赖项。
例如，您可以使用该命令在容器、服务器等环境中启动您的 **FastAPI** 应用。
其中包括`uvloop`，它是`asyncio`的高性能替代品，它提供了巨大的并发性能提升。
## ASGI 服务器
///
让我们深入了解一些细节。
////
FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称为 <abbr title="Asynchronous Server Gateway Interface，异步服务器网关接口">ASGI</abbr>。FastAPI 本质上是一个 ASGI Web 框架。
//// tab | Hypercorn
要在远程服务器上运行 **FastAPI** 应用（或任何其他 ASGI 应用），您需要一个 ASGI 服务器程序，例如 **Uvicorn**。它是 `fastapi` 命令默认使用的 ASGI 服务器。
* <a href="https://github.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>，一个也与 HTTP/2 兼容的 ASGI 服务器。
<div class="termy">
除此之外，还有其他一些可选的 ASGI 服务器，例如：
```console
$ pip install hypercorn
---> 100%
```
</div>
* <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>：高性能 ASGI 服务器。
* <a href="https://hypercorn.readthedocs.io/" class="external-link" target="_blank">Hypercorn</a>：与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。
* <a href="https://github.com/django/daphne" class="external-link" target="_blank">Daphne</a>：为 Django Channels 构建的 ASGI 服务器。
* <a href="https://github.com/emmett-framework/granian" class="external-link" target="_blank">Granian</a>：基于 Rust 的 HTTP 服务器，专为 Python 应用设计。
* <a href="https://unit.nginx.org/howto/fastapi/" class="external-link" target="_blank">NGINX Unit</a>：NGINX Unit 是一个轻量级且灵活的 Web 应用运行时环境。
...或任何其他 ASGI 服务器。
## 服务器主机和服务器程序
////
关于名称，有一个小细节需要记住。 💡
## 运行服务器程序
“**服务器**”一词通常用于指远程/云计算机（物理机或虚拟机）以及在该计算机上运行的程序（例如 Uvicorn）。
您可以按照之前教程中的相同方式运行应用程序，但不使用`--reload`选项，例如：
请记住，当您一般读到“服务器”这个名词时，它可能指的是这两者之一。
//// tab | Uvicorn
当提到远程主机时，通常将其称为**服务器**，但也称为**机器**(machine)、**VM**（虚拟机）、**节点**。 这些都是指某种类型的远程计算机，通常运行 Linux，您可以在其中运行程序。
<div class="termy">
```console
$ uvicorn main:app --host 0.0.0.0 --port 80
## 安装服务器程序
<span style="color: green;">INFO</span>: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
```
当您安装 FastAPI 时，它自带一个生产环境服务器——Uvicorn，并且您可以使用 `fastapi run` 命令来启动它。
</div>
不过，您也可以手动安装 ASGI 服务器。
////
请确保您创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再安装服务器应用程序。
//// tab | Hypercorn
例如，要安装 Uvicorn，可以运行以下命令：
<div class="termy">
```console
$ hypercorn main:app --bind 0.0.0.0:80
$ pip install "uvicorn[standard]"
Running on 0.0.0.0:8080 over http (CTRL + C to quit)
---> 100%
```
</div>
////
类似的流程也适用于任何其他 ASGI 服务器程序。
/// warning
/// tip
如果您正在使用`--reload`选项，请记住删除它。
通过添加 `standard` 选项，Uvicorn 将安装并使用一些推荐的额外依赖项。
`--reload` 选项消耗更多资源，并且更不稳定。
其中包括 `uvloop`，这是 `asyncio` 的高性能替代方案，能够显著提升并发性能。
它在**开发**期间有很大帮助，但您**不应该**在**生产环境**中使用它。
当您使用 `pip install "fastapi[standard]"` 安装 FastAPI 时，实际上也会安装 `uvicorn[standard]`。
///
## Hypercorn with Trio
Starlette 和 **FastAPI** 基于 <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a>， 所以它们才能同时与 Python 的标准库 <a href="https://docs.python.org/3/library/asyncio-task.html" class="external-link" target="_blank">asyncio</a> 和<a href="https://trio.readthedocs.io/en/stable/" class="external-link" target="_blank">Trio</a> 兼容。
尽管如此，Uvicorn 目前仅与 asyncio 兼容，并且通常使用 <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a >, 它是`asyncio`的高性能替代品。
但如果你想直接使用**Trio**，那么你可以使用**Hypercorn**，因为它支持它。 ✨
### 安装具有 Trio 的 Hypercorn
## 运行服务器程序
首先，您需要安装具有 Trio 支持的 Hypercorn：
如果您手动安装了 ASGI 服务器，通常需要以特定格式传递一个导入字符串，以便服务器能够正确导入您的 FastAPI 应用：
<div class="termy">
```console
$ pip install "hypercorn[trio]"
---> 100%
$ uvicorn main:app --host 0.0.0.0 --port 80
<span style="color: green;">INFO</span>: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
```
</div>
### Run with Trio
/// note
然后你可以传递值`trio`给命令行选项`--worker-class`:
命令 `uvicorn main:app` 的含义如下：
<div class="termy">
* `main`：指的是 `main.py` 文件（即 Python “模块”）。
* `app`：指的是 `main.py` 文件中通过 `app = FastAPI()` 创建的对象。
```console
$ hypercorn main:app --worker-class trio
它等价于以下导入语句：
```Python
from main import app
```
</div>
///
每种 ASGI 服务器程序通常都会有类似的命令，您可以在它们的官方文档中找到更多信息。
/// warning
Uvicorn 和其他服务器支持 `--reload` 选项，该选项在开发过程中非常有用。
这将通过您的应用程序启动 Hypercorn，并使用 Trio 作为后端。
但 `--reload` 选项会消耗更多资源，且相对不稳定。
现在您可以在应用程序内部使用 Trio。 或者更好的是，您可以使用 AnyIO，使您的代码与 Trio 和 asyncio 兼容。 🎉
它对于**开发阶段**非常有帮助，但在**生产环境**中**不应该**使用。
///
## 部署概念
这些示例运行服务器程序（例如 Uvicorn），启动**单个进程**，在所有 IP（`0.0.0.0`)上监听预定义端口（例如`80`)。
这些示例运行服务器程序（例如 Uvicorn），启动**单个进程**，在所有 IP（`0.0.0.0`）上监听预定义端口（例如`80`）。
这是基本思路。 但您可能需要处理一些其他事情，例如：
* 安全性 - HTTPS
* 启动时运行
* 重新启动
* Replication（运行的进程数）
* 复制（运行的进程数）
* 内存
* 开始前的步骤

144
docs/zh/docs/deployment/server-workers.md
View File

@ -1,4 +1,4 @@
# Server Workers - Gunicorn with Uvicorn
# 服务器工作进程（Workers） - 使用 Uvicorn 的多工作进程模式
让我们回顾一下之前的部署概念：
@ -9,125 +9,79 @@
* 内存
* 启动前的先前步骤
到目前为止，通过文档中的所有教程，您可能已经在**单个进程**上运行了像 Uvicorn 这样的**服务器程序**。
到目前为止，在文档中的所有教程中，您可能一直是在运行一个**服务器程序**，例如使用 `fastapi` 命令来启动 Uvicorn，而它默认运行的是**单进程模式**。
部署应用程序时，您可能希望进行一些**进程复制**，以利用**多核**并能够处理更多请求。
部署应用程序时，您可能希望进行一些**进程复制**，以利用**多核** CPU 并能够处理更多请求。
正如您在上一章有关[部署概念](concepts.md){.internal-link target=_blank}中看到的，您可以使用多种策略。
在这里我将向您展示如何将 <a href="https://gunicorn.org/" class="external-link" target="_blank">**Gunicorn**</a> 与 **Uvicorn worker 进程** 一起使用。
在本章节中，我将向您展示如何使用 `fastapi` 命令或直接使用 `uvicorn` 命令以**多工作进程模式**运行 **Uvicorn**。
/// info
如果您正在使用容器，例如 Docker 或 Kubernetes，我将在下一章中告诉您更多相关信息：[容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank}。
特别是，当在 **Kubernetes** 上运行时，您可能**不想**使用 Gunicorn，而是运行 **每个容器一个 Uvicorn 进程**，但我将在本章后面告诉您这一点。
比较特别的是，在 **Kubernetes** 环境中运行时，您通常**不需要**使用多个工作进程，而是**每个容器运行一个 Uvicorn 进程**。不过，我会在本章节的后续部分详细介绍这一点。
///
## Gunicorn with Uvicorn Workers
## 多个工作进程
**Gunicorn**主要是一个使用**WSGI标准**的应用服务器。 这意味着 Gunicorn 可以为 Flask 和 Django 等应用程序提供服务。 Gunicorn 本身与 **FastAPI** 不兼容，因为 FastAPI 使用最新的 **<a href="https://asgi.readthedocs.io/en/latest/" class="external-link" target=" _blank">ASGI 标准</a>**。
您可以使用 `--workers` 命令行选项来启动多个工作进程：
但 Gunicorn 支持充当 **进程管理器** 并允许用户告诉它要使用哪个特定的 **worker类**。 然后 Gunicorn 将使用该类启动一个或多个 **worker进程**。
//// tab | `fastapi`
**Uvicorn** 有一个 Gunicorn 兼容的worker类。
使用这种组合，Gunicorn 将充当 **进程管理器**，监听 **端口** 和 **IP**。 它会将通信**传输**到运行**Uvicorn类**的worker进程。
然后与Gunicorn兼容的**Uvicorn worker**类将负责将Gunicorn发送的数据转换为ASGI标准以供FastAPI使用。
## 安装 Gunicorn 和 Uvicorn
如果您使用 `fastapi` 命令：
<div class="termy">
```console
$ pip install "uvicorn[standard]" gunicorn
---> 100%
```
</div>
$ <font color="#4E9A06">fastapi</font> run --workers 4 <u style="text-decoration-style:solid">main.py</u>
这将安装带有`standard`扩展包（以获得高性能）的 Uvicorn 和 Gunicorn。
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting production server 🚀
## Run Gunicorn with Uvicorn Workers
Searching for package file structure from directories with
<font color="#3465A4">__init__.py</font> files
Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
接下来你可以通过以下命令运行Gunicorn:
<div class="termy">
```console
$ gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:80
[19499] [INFO] Starting gunicorn 20.1.0
[19499] [INFO] Listening at: http://0.0.0.0:80 (19499)
[19499] [INFO] Using worker: uvicorn.workers.UvicornWorker
[19511] [INFO] Booting worker with pid: 19511
[19513] [INFO] Booting worker with pid: 19513
[19514] [INFO] Booting worker with pid: 19514
[19515] [INFO] Booting worker with pid: 19515
[19511] [INFO] Started server process [19511]
[19511] [INFO] Waiting for application startup.
[19511] [INFO] Application startup complete.
[19513] [INFO] Started server process [19513]
[19513] [INFO] Waiting for application startup.
[19513] [INFO] Application startup complete.
[19514] [INFO] Started server process [19514]
[19514] [INFO] Waiting for application startup.
[19514] [INFO] Application startup complete.
[19515] [INFO] Started server process [19515]
[19515] [INFO] Waiting for application startup.
[19515] [INFO] Application startup complete.
```
</div>
<span style="background-color:#007166"><font color="#D3D7CF"> module </font></span> 🐍 main.py
<span style="background-color:#007166"><font color="#D3D7CF"> code </font></span> Importing the FastAPI app object from the module with the
following code:
让我们看看每个选项的含义：
<u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>
* `main:app`：这与 Uvicorn 使用的语法相同，`main` 表示名为"`main`"的 Python 模块，因此是文件 `main.py`。 `app` 是 **FastAPI** 应用程序的变量名称。
* 你可以想象 `main:app` 相当于一个 Python `import` 语句，例如：
<span style="background-color:#007166"><font color="#D3D7CF"> app </font></span> Using import string: <font color="#3465A4">main:app</font>
```Python
from main import app
```
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Server started at <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000</u></font>
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Documentation at <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000/docs</u></font>
* 因此，`main:app` 中的冒号相当于 `from main import app` 中的 Python `import` 部分。
Logs:
* `--workers`：要使用的worker进程数量，每个进程将运行一个 Uvicorn worker进程，在本例中为 4 个worker进程。
* `--worker-class`：在worker进程中使用的与 Gunicorn 兼容的工作类。
* 这里我们传递了 Gunicorn 可以导入和使用的类：
```Python
import uvicorn.workers.UvicornWorker
```
* `--bind`：这告诉 Gunicorn 要监听的 IP 和端口，使用冒号 (`:`) 分隔 IP 和端口。
* 如果您直接运行 Uvicorn，则可以使用`--host 0.0.0.0`和`--port 80`，而不是`--bind 0.0.0.0:80`（Gunicorn 选项）。
在输出中，您可以看到它显示了每个进程的 **PID**（进程 ID）（它只是一个数字）。
你可以看到：
* Gunicorn **进程管理器** 以 PID `19499` 开头（在您的情况下，它将是一个不同的数字）。
* 然后它开始`Listening at: http://0.0.0.0:80`。
* 然后它检测到它必须使用 `uvicorn.workers.UvicornWorker` 处的worker类。
* 然后它启动**4个worker**，每个都有自己的PID：`19511`、`19513`、`19514`和`19515`。
Gunicorn 还将负责管理**死进程**和**重新启动**新进程（如果需要保持worker数量）。 因此，这在一定程度上有助于上面列表中**重启**的概念。
尽管如此，您可能还希望有一些外部的东西，以确保在必要时**重新启动 Gunicorn**，并且**在启动时运行它**等。
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Uvicorn running on <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000</u></font> <b>(</b>Press CTRL+C to
quit<b>)</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started parent process <b>[</b><font color="#34E2E2"><b>27365</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started server process <b>[</b><font color="#34E2E2"><b>27368</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started server process <b>[</b><font color="#34E2E2"><b>27369</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started server process <b>[</b><font color="#34E2E2"><b>27370</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started server process <b>[</b><font color="#34E2E2"><b>27367</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Waiting for application startup.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Waiting for application startup.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Waiting for application startup.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Waiting for application startup.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Application startup complete.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Application startup complete.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Application startup complete.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Application startup complete.
```
## Uvicorn with Workers
</div>
Uvicorn 也有一个选项可以启动和运行多个 **worker进程**。
////
然而，到目前为止，Uvicorn 处理worker进程的能力比 Gunicorn 更有限。 因此，如果您想拥有这个级别（Python 级别）的进程管理器，那么最好尝试使用 Gunicorn 作为进程管理器。
//// tab | `uvicorn`
无论如何，您都可以像这样运行它：
如果您更想要直接使用 `uvicorn` 命令：
<div class="termy">
@ -151,13 +105,15 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
</div>
////
这里唯一的新选项是 `--workers` 告诉 Uvicorn 启动 4 个工作进程。
您还可以看到它显示了每个进程的 **PID**，父进程（这是 **进程管理器**）的 PID 为`27365`，每个工作进程的 PID 为：`27368`、`27369`， `27370`和`27367`。
您还可以看到它显示了每个进程的 **PID**，父进程（这是**进程管理器**）的 PID 为`27365`，每个工作进程的 PID 为：`27368`、`27369`， `27370`和`27367`。
## 部署概念
在这里，您了解了如何使用 **Gunicorn**（或 Uvicorn）管理 **Uvicorn 工作进程**来**并行**应用程序的执行，利用 CPU 中的 **多核**，并 能够满足**更多请求**。
在这里，您学习了如何使用多个**工作进程（workers）**来让应用程序的执行**并行化**，充分利用 CPU 的**多核性能**，并能够处理**更多的请求**。
从上面的部署概念列表来看，使用worker主要有助于**复制**部分，并对**重新启动**有一点帮助，但您仍然需要照顾其他部分：
@ -170,15 +126,13 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
## 容器和 Docker
在关于 [容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank} 的下一章中，我将介绍一些可用于处理其他 **部署概念** 的策略。
我还将向您展示 **官方 Docker 镜像**，其中包括 **Gunicorn 和 Uvicorn worker** 以及一些对简单情况有用的默认配置。
在关于 [容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank} 的下一章中，我将介绍一些可用于处理其他**部署概念**的策略。
在那里，我还将向您展示如何 **从头开始构建自己的镜像** 以运行单个 Uvicorn 进程（没有 Gunicorn）。 这是一个简单的过程，并且可能是您在使用像 **Kubernetes** 这样的分布式容器管理系统时想要做的事情。
我将向您展示如何**从零开始构建自己的镜像**，以运行一个单独的 Uvicorn 进程。这个过程相对简单，并且在使用 **Kubernetes** 等分布式容器管理系统时，这通常是您需要采取的方法。
## 回顾
您可以使用**Gunicorn**（或Uvicorn）作为Uvicorn工作进程的进程管理器，以利用**多核CPU**，**并行运行多个进程**。
您可以在使用 `fastapi` 或 `uvicorn` 命令时，通过 `--workers` CLI 选项启用多个工作进程（workers），以充分利用**多核 CPU**，以**并行运行多个进程**。
如果您要设置**自己的部署系统**，同时自己处理其他部署概念，则可以使用这些工具和想法。

80
docs/zh/docs/tutorial/index.md
View File

@ -1,34 +1,58 @@
# 教程 - 用户指南
本教程将一步步向你展示如何使用 **FastAPI** 的绝大部分特性。
本教程将一步步向您展示如何使用 **FastAPI** 的绝大部分特性。
各个章节的内容循序渐进，但是又围绕着单独的主题，所以你可以直接跳转到某个章节以解决你的特定需求。
各个章节的内容循序渐进，但是又围绕着单独的主题，所以您可以直接跳转到某个章节以解决您的特定需求。
本教程同样可以作为将来的参考手册。
你可以随时回到本教程并查阅你需要的内容。
本教程同样可以作为将来的参考手册，所以您可以随时回到本教程并查阅您需要的内容。
## 运行代码
所有代码片段都可以复制后直接使用（它们实际上是经过测试的 Python 文件）。
要运行任何示例，请将代码复制到 `main.py` 文件中，然后使用以下命令启动 `uvicorn`：
要运行任何示例，请将代码复制到 `main.py` 文件中，然后使用以下命令启动 `fastapi dev`：
<div class="termy">
```console
$ uvicorn main:app --reload
$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid">main.py</u>
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
Searching for package file structure from directories
with <font color="#3465A4">__init__.py</font> files
Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
<span style="background-color:#007166"><font color="#D3D7CF"> module </font></span> 🐍 main.py
<span style="background-color:#007166"><font color="#D3D7CF"> code </font></span> Importing the FastAPI app object from the module with
the following code:
<u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>
<span style="background-color:#007166"><font color="#D3D7CF"> app </font></span> Using import string: <font color="#3465A4">main:app</font>
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Server started at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font>
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Documentation at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000/docs</u></font>
<span style="background-color:#007166"><font color="#D3D7CF"> tip </font></span> Running in development mode, for production use:
<b>fastapi run</b>
Logs:
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
<span style="color: green;">INFO</span>: Started reloader process [28720]
<span style="color: green;">INFO</span>: Started server process [28722]
<span style="color: green;">INFO</span>: Waiting for application startup.
<span style="color: green;">INFO</span>: Application startup complete.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Will watch for changes in these directories:
<b>[</b><font color="#4E9A06">&apos;/home/user/code/awesomeapp&apos;</font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Uvicorn running on <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font> <b>(</b>Press CTRL+C
to quit<b>)</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started reloader process <b>[</b><font color="#34E2E2"><b>383138</b></font><b>]</b> using WatchFiles
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started server process <b>[</b><font color="#34E2E2"><b>383153</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Waiting for application startup.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Application startup complete.
```
</div>
强烈建议你在本地编写或复制代码，对其进行编辑并运行。
**强烈建议**您在本地编写或复制代码，对其进行编辑并运行。
在编辑器中使用 FastAPI 会真正地展现出它的优势：只需要编写很少的代码，所有的类型检查，代码补全等等。
@ -36,48 +60,34 @@ $ uvicorn main:app --reload
## 安装 FastAPI
第一个步骤是安装 FastAPI。
第一个步骤是安装 FastAPI.
为了使用本教程，你可能需要安装所有的可选依赖及对应功能：
请确保您创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后**安装 FastAPI**：
<div class="termy">
```console
$ pip install "fastapi[all]"
$ pip install "fastapi[standard]"
---> 100%
```
</div>
......以上安装还包括了 `uvicorn`，你可以将其用作运行代码的服务器。
/// note
你也可以分开来安装。
假如你想将应用程序部署到生产环境，你可能要执行以下操作：
```
pip install fastapi
```
并且安装`uvicorn`来作为服务器：
```
pip install "uvicorn[standard]"
```
当您使用 `pip install "fastapi[standard]"` 进行安装时，它会附带一些默认的可选标准依赖项。
然后对你想使用的每个可选依赖项也执行相同的操作。
如果您不想安装这些可选依赖，可以选择安装 `pip install fastapi`。
///
## 进阶用户指南
在本**教程-用户指南**之后，你可以阅读**进阶用户指南**。
在本**教程-用户指南**之后，您可以阅读**进阶用户指南**。
**进阶用户指南**以本教程为基础，使用相同的概念，并教授一些额外的特性。
但是你应该先阅读**教程-用户指南**（即你现在正在阅读的内容）。
但是您应该先阅读**教程-用户指南**（即您现在正在阅读的内容）。
教程经过精心设计，使你可以仅通过**教程-用户指南**来开发一个完整的应用程序，然后根据你的需要，使用**进阶用户指南**中的一些其他概念，以不同的方式来扩展它。
教程经过精心设计，使您可以仅通过**教程-用户指南**来开发一个完整的应用程序，然后根据您的需要，使用**进阶用户指南**中的一些其他概念，以不同的方式来扩展它。

Write Preview
Loading…
Cancel
Save