From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Tue, 30 Sep 2025 11:24:39 +0000 (+0200) Subject: 🌐 Update Russian translations for existing pages (LLM-generated) (#14123) X-Git-Tag: 0.118.1~36 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=977abe239662203ab0ea3b089092f94d3526e8fd;p=thirdparty%2Ffastapi%2Ffastapi.git 🌐 Update Russian translations for existing pages (LLM-generated) (#14123) * Update Russian translations for modified pages * docs: fix translation for multiprocessing * Update Russian translations for other existing pages * Apply changes from latest PRs: 13917 and 14099 --------- Co-authored-by: vldmrdev <70532790+vldmrdev@users.noreply.github.com> --- diff --git a/docs/ru/docs/about/index.md b/docs/ru/docs/about/index.md index 1015b667a8..4f48266a7a 100644 --- a/docs/ru/docs/about/index.md +++ b/docs/ru/docs/about/index.md @@ -1,3 +1,3 @@ -# О проекте +# О проекте { #about } -FastAPI: внутреннее устройство, повлиявшие технологии и всё такое прочее. 🤓 +О FastAPI, его дизайне, источниках вдохновения и многом другом. 🤓 diff --git a/docs/ru/docs/advanced/additional-status-codes.md b/docs/ru/docs/advanced/additional-status-codes.md index aab1f8ee38..7c73cf5d5d 100644 --- a/docs/ru/docs/advanced/additional-status-codes.md +++ b/docs/ru/docs/advanced/additional-status-codes.md @@ -1,28 +1,28 @@ -# Дополнительные статус коды +# Дополнительные статус-коды { #additional-status-codes } -По умолчанию **FastAPI** возвращает ответы, используя `JSONResponse`, помещая содержимое, которое вы возвращаете из вашей *операции пути*, внутрь этого `JSONResponse`. +По умолчанию **FastAPI** будет возвращать ответы, используя `JSONResponse`, помещая содержимое, которое вы возвращаете из вашей *операции пути*, внутрь этого `JSONResponse`. -Он будет использовать код статуса по умолчанию или тот, который вы укажете в вашей *операции пути*. +Он будет использовать статус-код по умолчанию или тот, который вы укажете в вашей *операции пути*. -## Дополнительные статус коды +## Дополнительные статус-коды { #additional-status-codes_1 } -Если вы хотите возвращать дополнительный статус код помимо основного, вы можете сделать это, возвращая объект `Response` напрямую, как `JSONResponse`, и устанавливая нужный статус код напрямую. +Если вы хотите возвращать дополнительные статус-коды помимо основного, вы можете сделать это, возвращая `Response` напрямую, например `JSONResponse`, и устанавливая дополнительный статус-код напрямую. -Например, скажем, вы хотите создать *операцию пути*, которая позволяет обновлять элементы и возвращает HTTP-код 200 "OK" при успешном выполнении. +Например, предположим, что вы хотите иметь *операцию пути*, которая позволяет обновлять элементы и возвращает HTTP статус-код 200 «OK» при успешном выполнении. -Но вы также хотите, чтобы она принимала новые элементы. И если элемент ранее не существовал, он создаётся, и возвращался HTTP-код 201 "Created". +Но вы также хотите, чтобы она принимала новые элементы. И если элементы ранее не существовали, она создаёт их и возвращает HTTP статус-код 201 «Created». -Чтобы реализовать это, импортируйте `JSONResponse` и возвращайте ваш контент напрямую, устанавливая нужный `status_code`: +Чтобы добиться этого, импортируйте `JSONResponse` и верните туда свой контент напрямую, установив нужный вам `status_code`: {* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *} /// warning | Внимание -Когда вы возвращаете объект `Response` напрямую, как в примере выше, он будет возвращён как есть. +Когда вы возвращаете `Response` напрямую, как в примере выше, он будет возвращён как есть. -Он не будет сериализован при помощи модели и т.д. +Он не будет сериализован с помощью модели и т.п. -Убедитесь, что в нём содержатся именно те данные, которые вы хотите, и что значения являются валидным JSON (если вы используете `JSONResponse`). +Убедитесь, что в нём именно те данные, которые вы хотите, и что значения являются валидным JSON (если вы используете `JSONResponse`). /// @@ -30,12 +30,12 @@ Вы также можете использовать `from starlette.responses import JSONResponse`. -**FastAPI** предоставляет тот же `starlette.responses` через `fastapi.responses` просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette. То же самое касается и `status`. +**FastAPI** предоставляет тот же `starlette.responses` через `fastapi.responses` просто для вашего удобства как разработчика. Но большинство доступных Response-классов приходят напрямую из Starlette. То же самое со `status`. /// -## OpenAPI и документация API +## OpenAPI и документация API { #openapi-and-api-docs } -Если вы возвращаете дополнительные коды статусов и ответы напрямую, они не будут включены в схему OpenAPI (документацию API), потому что FastAPI не может заранее знать, что вы собираетесь вернуть. +Если вы возвращаете дополнительные статус-коды и ответы напрямую, они не будут включены в схему OpenAPI (документацию API), потому что у FastAPI нет способа заранее знать, что вы собираетесь вернуть. -Но вы можете задокументировать это в вашем коде, используя: [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. +Но вы можете задокументировать это в своём коде, используя: [Дополнительные ответы](additional-responses.md){.internal-link target=_blank}. diff --git a/docs/ru/docs/advanced/async-tests.md b/docs/ru/docs/advanced/async-tests.md index 7849ad1090..5062bc52e7 100644 --- a/docs/ru/docs/advanced/async-tests.md +++ b/docs/ru/docs/advanced/async-tests.md @@ -1,4 +1,4 @@ -# Асинхронное тестирование +# Асинхронное тестирование { #async-tests } Вы уже видели как тестировать **FastAPI** приложение, используя имеющийся класс `TestClient`. К этому моменту вы видели только как писать тесты в синхронном стиле без использования `async` функций. @@ -6,11 +6,11 @@ Давайте рассмотрим, как мы можем это реализовать. -## pytest.mark.anyio +## pytest.mark.anyio { #pytest-mark-anyio } Если мы хотим вызывать асинхронные функции в наших тестах, то наши тестовые функции должны быть асинхронными. AnyIO предоставляет для этого отличный плагин, который позволяет нам указывать, какие тестовые функции должны вызываться асинхронно. -## HTTPX +## HTTPX { #httpx } Даже если **FastAPI** приложение использует обычные функции `def` вместо `async def`, это все равно `async` приложение 'под капотом'. @@ -18,7 +18,7 @@ `TestClient` основан на HTTPX, и, к счастью, мы можем использовать его (`HTTPX`) напрямую для тестирования API. -## Пример +## Пример { #example } В качестве простого примера, давайте рассмотрим файловую структуру, схожую с описанной в [Большие приложения](../tutorial/bigger-applications.md){.internal-link target=_blank} и [Тестирование](../tutorial/testing.md){.internal-link target=_blank}: @@ -38,7 +38,7 @@ {* ../../docs_src/async_tests/test_main.py *} -## Запуск тестов +## Запуск тестов { #run-it } Вы можете запустить свои тесты как обычно: @@ -52,7 +52,7 @@ $ pytest -## Подробнее +## Подробнее { #in-detail } Маркер `@pytest.mark.anyio` говорит pytest, что тестовая функция должна быть вызвана асинхронно: @@ -88,7 +88,7 @@ response = client.get('/') /// -## Вызов других асинхронных функций +## Вызов других асинхронных функций { #other-asynchronous-function-calls } Теперь тестовая функция стала асинхронной, поэтому внутри нее вы можете вызывать также и другие `async` функции, не связанные с отправлением запросов в ваше FastAPI приложение. Как если бы вы вызывали их в любом другом месте вашего кода. diff --git a/docs/ru/docs/advanced/index.md b/docs/ru/docs/advanced/index.md index b5cb733e7b..c0a52c6c14 100644 --- a/docs/ru/docs/advanced/index.md +++ b/docs/ru/docs/advanced/index.md @@ -1,12 +1,12 @@ -# Расширенное руководство пользователя +# Расширенное руководство пользователя { #advanced-user-guide } -## Дополнительные возможности +## Дополнительные возможности { #additional-features } Основное [Учебник - Руководство пользователя](../tutorial/index.md){.internal-link target=_blank} должно быть достаточно, чтобы познакомить вас со всеми основными функциями **FastAPI**. В следующих разделах вы увидите другие варианты, конфигурации и дополнительные возможности. -/// tip +/// tip | Совет Следующие разделы **не обязательно являются "продвинутыми"**. @@ -14,7 +14,7 @@ /// -## Сначала прочитайте Учебник - Руководство пользователя +## Сначала прочитайте Учебник - Руководство пользователя { #read-the-tutorial-first } Вы все еще можете использовать большинство функций **FastAPI** со знаниями из [Учебник - Руководство пользователя](../tutorial/index.md){.internal-link target=_blank}. diff --git a/docs/ru/docs/advanced/response-change-status-code.md b/docs/ru/docs/advanced/response-change-status-code.md index 37dade99f8..e9e1c9470f 100644 --- a/docs/ru/docs/advanced/response-change-status-code.md +++ b/docs/ru/docs/advanced/response-change-status-code.md @@ -1,22 +1,22 @@ -# Response - Изменение cтатус кода +# Response - Изменение статус-кода { #response-change-status-code } -Вы, вероятно, уже читали о том, что можно установить [Состояние ответа по умолчанию](../tutorial/response-status-code.md){.internal-link target=_blank}. +Вы, вероятно, уже читали о том, что можно установить [статус-код ответа по умолчанию](../tutorial/response-status-code.md){.internal-link target=_blank}. -Но в некоторых случаях вам нужно вернуть код состояния, отличный от установленного по умолчанию. +Но в некоторых случаях нужно вернуть другой статус-код, отличный от значения по умолчанию. -## Пример использования +## Пример использования { #use-case } -Например, представьте, что вы хотите возвращать HTTP код состояния "OK" `200` по умолчанию. +Например, представьте, что вы хотите по умолчанию возвращать HTTP статус-код «OK» `200`. -Но если данные не существовали, вы хотите создать их и вернуть HTTP код состояния "CREATED" `201`. +Но если данные не существовали, вы хотите создать их и вернуть HTTP статус-код «CREATED» `201`. При этом вы всё ещё хотите иметь возможность фильтровать и преобразовывать возвращаемые данные с помощью `response_model`. Для таких случаев вы можете использовать параметр `Response`. -## Использование параметра `Response` +## Использование параметра `Response` { #use-a-response-parameter } -Вы можете объявить параметр типа `Response` в вашей *функции обработки пути* (так же как для cookies и headers). +Вы можете объявить параметр типа `Response` в вашей *функции обработки пути* (как и для cookies и HTTP-заголовков). И затем вы можете установить `status_code` в этом *временном* объекте ответа. @@ -26,6 +26,6 @@ И если вы объявили `response_model`, он всё равно будет использоваться для фильтрации и преобразования возвращаемого объекта. -**FastAPI** будет использовать этот *временный* ответ для извлечения кода состояния (а также cookies и headers) и поместит их в финальный ответ, который содержит возвращаемое вами значение, отфильтрованное любым `response_model`. +**FastAPI** будет использовать этот *временный* ответ для извлечения статус-кода (а также cookies и HTTP-заголовков) и поместит их в финальный ответ, который содержит возвращаемое вами значение, отфильтрованное любым `response_model`. -Вы также можете объявить параметр `Response` в зависимостях и установить код состояния в них. Но помните, что последнее установленное значение будет иметь приоритет. +Вы также можете объявить параметр `Response` в зависимостях и установить в них статус-код. Но помните, что последнее установленное значение будет иметь приоритет. diff --git a/docs/ru/docs/advanced/response-cookies.md b/docs/ru/docs/advanced/response-cookies.md index e04ff577c9..3aa32b9bb7 100644 --- a/docs/ru/docs/advanced/response-cookies.md +++ b/docs/ru/docs/advanced/response-cookies.md @@ -1,9 +1,8 @@ +# Cookies в ответе { #response-cookies } -# Cookies в ответе +## Использование параметра `Response` { #use-a-response-parameter } -## Использование параметра `Response` - -Вы можете объявить параметр типа `Response` в вашей функции эндпоинта. +Вы можете объявить параметр типа `Response` в вашей функции-обработчике пути. Затем установить cookies в этом временном объекте ответа. @@ -13,36 +12,40 @@ Если вы указали `response_model`, он всё равно будет использоваться для фильтрации и преобразования возвращаемого объекта. -**FastAPI** извлечет cookies (а также заголовки и коды состояния) из временного ответа и включит их в окончательный ответ, содержащий ваше возвращаемое значение, отфильтрованное через `response_model`. +**FastAPI** извлечет cookies (а также HTTP-заголовки и статус-код) из временного ответа и включит их в окончательный ответ, содержащий ваше возвращаемое значение, отфильтрованное через `response_model`. -Вы также можете объявить параметр типа Response в зависимостях и устанавливать cookies (и заголовки) там. +Вы также можете объявить параметр типа `Response` в зависимостях и устанавливать cookies (и HTTP-заголовки) там. -## Возвращение `Response` напрямую +## Возвращение `Response` напрямую { #return-a-response-directly } -Вы также можете установить cookies, если возвращаете `Response` напрямую в вашем коде. +Вы также можете установить Cookies, если возвращаете `Response` напрямую в вашем коде. -Для этого создайте объект `Response`, как описано в разделе [Возвращение ответа напрямую](response-directly.md){.target=_blank}. +Для этого создайте объект `Response`, как описано в разделе [Возвращение ответа напрямую](response-directly.md){.internal-link target=_blank}. Затем установите cookies и верните этот объект: {* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *} -/// tip | Примечание -Имейте в виду, что если вы возвращаете ответ напрямую, вместо использования параметра `Response`, **FastAPI** отправит его без дополнительной обработки. +/// tip | Совет + +Имейте в виду, что если вы возвращаете ответ напрямую, вместо использования параметра `Response`, FastAPI вернёт его напрямую. -Убедитесь, что ваши данные имеют корректный тип. Например, они должны быть совместимы с JSON, если вы используете `JSONResponse`. +Убедитесь, что ваши данные имеют корректный тип. Например, они должны быть совместимы с JSON, если вы возвращаете `JSONResponse`. Также убедитесь, что вы не отправляете данные, которые должны были быть отфильтрованы через `response_model`. + /// -### Дополнительная информация +### Дополнительная информация { #more-info } /// note | Технические детали + Вы также можете использовать `from starlette.responses import Response` или `from starlette.responses import JSONResponse`. **FastAPI** предоставляет `fastapi.responses`, которые являются теми же объектами, что и `starlette.responses`, просто для удобства. Однако большинство доступных типов ответов поступает непосредственно из **Starlette**. -Для установки заголовков и cookies `Response` используется часто, поэтому **FastAPI** также предоставляет его через `fastapi.responses`. +И так как `Response` часто используется для установки HTTP-заголовков и cookies, **FastAPI** также предоставляет его как `fastapi.Response`. + /// Чтобы увидеть все доступные параметры и настройки, ознакомьтесь с документацией Starlette. diff --git a/docs/ru/docs/advanced/response-directly.md b/docs/ru/docs/advanced/response-directly.md index ee83d22b10..febd40ed4a 100644 --- a/docs/ru/docs/advanced/response-directly.md +++ b/docs/ru/docs/advanced/response-directly.md @@ -1,4 +1,4 @@ -# Возврат ответа напрямую +# Возврат ответа напрямую { #return-a-response-directly } Когда вы создаёте **FastAPI** *операцию пути*, вы можете возвращать из неё любые данные: `dict`, `list`, Pydantic-модель, модель базы данных и т.д. @@ -8,9 +8,9 @@ Но вы можете возвращать `JSONResponse` напрямую из ваших *операций пути*. -Это может быть полезно, например, если нужно вернуть пользовательские заголовки или куки. +Это может быть полезно, например, если нужно вернуть пользовательские HTTP-заголовки или cookie. -## Возврат `Response` +## Возврат `Response` { #return-a-response } На самом деле, вы можете возвращать любой объект `Response` или его подкласс. @@ -26,7 +26,7 @@ Это даёт вам большую гибкость. Вы можете возвращать любые типы данных, переопределять любые объявления или валидацию данных и т.д. -## Использование `jsonable_encoder` в `Response` +## Использование `jsonable_encoder` в `Response` { #using-the-jsonable-encoder-in-a-response } Поскольку **FastAPI** не изменяет объект `Response`, который вы возвращаете, вы должны убедиться, что его содержимое готово к отправке. @@ -44,7 +44,7 @@ /// -## Возврат пользовательского `Response` +## Возврат пользовательского `Response` { #returning-a-custom-response } Пример выше показывает все необходимые части, но он пока не очень полезен, так как вы могли бы просто вернуть `item` напрямую, и **FastAPI** поместил бы его в `JSONResponse`, преобразовав в `dict` и т.д. Всё это происходит по умолчанию. @@ -56,7 +56,7 @@ {* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} -## Примечания +## Примечания { #notes } Когда вы возвращаете объект `Response` напрямую, его данные не валидируются, не преобразуются (не сериализуются) и не документируются автоматически. diff --git a/docs/ru/docs/advanced/websockets.md b/docs/ru/docs/advanced/websockets.md index bc9dfcbffb..b73fa1ddba 100644 --- a/docs/ru/docs/advanced/websockets.md +++ b/docs/ru/docs/advanced/websockets.md @@ -1,10 +1,10 @@ -# Веб-сокеты +# Веб-сокеты { #websockets } Вы можете использовать веб-сокеты в **FastAPI**. -## Установка `WebSockets` +## Установка `websockets` { #install-websockets } -Убедитесь, что [виртуальная среда](../virtual-environments.md){.internal-link target=_blank} создана, активируйте её и установите `websockets`: +Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его и установили `websockets` (библиотека Python, упрощающая работу с протоколом "WebSocket"):
@@ -16,31 +16,31 @@ $ pip install websockets
-## Клиент WebSockets +## Клиент WebSockets { #websockets-client } -### Рабочее приложение +### В продакшн { #in-production } -Скорее всего, в вашей реальной продуктовой системе есть фронтенд, реализованный при помощи современных фреймворков React, Vue.js или Angular. +В продакшн у вас, вероятно, есть фронтенд, созданный с помощью современного фреймворка вроде React, Vue.js или Angular. -И наверняка для взаимодействия с бекендом через веб-сокеты вы будете использовать средства фронтенда. +И для взаимодействия с бекендом по WebSocket вы, скорее всего, будете использовать инструменты вашего фронтенда. -Также у вас может быть нативное мобильное приложение, коммуницирующее непосредственно с веб-сокетами на бекенд-сервере. +Также у вас может быть нативное мобильное приложение, которое напрямую, нативным кодом, взаимодействует с вашим WebSocket-бекендом. -Либо вы можете сделать какой-либо другой способ взаимодействия с веб-сокетами. +Либо у вас может быть любой другой способ взаимодействия с WebSocket-эндпоинтом. --- -Но для этого примера мы воспользуемся очень простым HTML документом с небольшими вставками JavaScript кода. +Но для этого примера мы воспользуемся очень простым HTML‑документом с небольшим JavaScript, всё внутри одной длинной строки. -Конечно же это неоптимально, и на практике так делать не стоит. +Конечно же, это неоптимально, и вы бы не использовали это в продакшн. -В реальных приложениях стоит воспользоваться одним из вышеупомянутых способов. +В продакшн у вас был бы один из вариантов выше. -Для примера нам нужен наиболее простой способ, который позволит сосредоточиться на серверной части веб-сокетов и получить рабочий код: +Для примера нам нужен наиболее простой способ, который позволит сосредоточиться на серверной части веб‑сокетов и получить рабочий код: {* ../../docs_src/websockets/tutorial001.py hl[2,6:38,41:43] *} -## Создание `websocket` +## Создание `websocket` { #create-a-websocket } Создайте `websocket` в своем **FastAPI** приложении: @@ -54,7 +54,7 @@ $ pip install websockets /// -## Ожидание и отправка сообщений +## Ожидание и отправка сообщений { #await-for-messages-and-send-messages } Через эндпоинт веб-сокета вы можете получать и отправлять сообщения. @@ -62,7 +62,7 @@ $ pip install websockets Вы можете получать и отправлять двоичные, текстовые и JSON данные. -## Проверка в действии +## Проверка в действии { #try-it } Если ваш файл называется `main.py`, то запустите приложение командой: @@ -96,7 +96,7 @@ $ fastapi dev main.py И все они будут использовать одно и то же веб-сокет соединение. -## Использование `Depends` и не только +## Использование `Depends` и не только { #using-depends-and-others } Вы можете импортировать из `fastapi` и использовать в эндпоинте вебсокета: @@ -119,7 +119,7 @@ $ fastapi dev main.py /// -### Веб-сокеты с зависимостями: проверка в действии +### Веб-сокеты с зависимостями: проверка в действии { #try-the-websockets-with-dependencies } Если ваш файл называется `main.py`, то запустите приложение командой: @@ -150,7 +150,7 @@ $ fastapi dev main.py -## Обработка отключений и работа с несколькими клиентами +## Обработка отключений и работа с несколькими клиентами { #handling-disconnections-and-multiple-clients } Если веб-сокет соединение закрыто, то `await websocket.receive_text()` вызовет исключение `WebSocketDisconnect`, которое можно поймать и обработать как в этом примере: @@ -168,7 +168,7 @@ $ fastapi dev main.py Client #1596980209979 left the chat ``` -/// tip | Примечание +/// tip | Подсказка Приложение выше - это всего лишь простой минимальный пример, демонстрирующий обработку и передачу сообщений нескольким веб-сокет соединениям. @@ -178,7 +178,7 @@ Client #1596980209979 left the chat /// -## Дополнительная информация +## Дополнительная информация { #more-info } Для более глубокого изучения темы воспользуйтесь документацией Starlette: diff --git a/docs/ru/docs/alternatives.md b/docs/ru/docs/alternatives.md index 3c5147e793..6380bcc45c 100644 --- a/docs/ru/docs/alternatives.md +++ b/docs/ru/docs/alternatives.md @@ -1,104 +1,94 @@ -# Альтернативы, источники вдохновения и сравнения +# Альтернативы, источники вдохновения и сравнения { #alternatives-inspiration-and-comparisons } -Что вдохновило на создание **FastAPI**, сравнение его с альтернативами и чему он научился у них. +Что вдохновило **FastAPI**, сравнение с альтернативами и чему он у них научился. -## Введение +## Введение { #intro } -**FastAPI** не существовал бы, если б не было более ранних работ других людей. +**FastAPI** не существовал бы без предыдущих работ других людей. -Они создали большое количество инструментов, которые вдохновили меня на создание **FastAPI**. +Было создано множество инструментов, которые вдохновили на его появление. -Я всячески избегал создания нового фреймворка в течение нескольких лет. -Сначала я пытался собрать все нужные функции, которые ныне есть в **FastAPI**, используя множество различных фреймворков, плагинов и инструментов. +Я несколько лет избегал создания нового фреймворка. Сначала пытался закрыть все возможности, которые сейчас предоставляет **FastAPI**, с помощью множества разных фреймворков, плагинов и инструментов. -Но в какой-то момент не осталось другого выбора, кроме как создать что-то, что предоставляло бы все эти функции сразу. -Взять самые лучшие идеи из предыдущих инструментов и, используя новые возможности Python (которых не было до версии 3.6, то есть подсказки типов), объединить их. +Но в какой-то момент не осталось другого варианта, кроме как создать что-то, что включает все эти возможности, взяв лучшие идеи из прежних инструментов и совместив их максимально удачным образом, используя возможности языка, которых прежде не было (аннотации типов в Python 3.6+). -## Предшествующие инструменты +## Предшествующие инструменты { #previous-tools } -### Django +### Django { #django } -Это самый популярный Python-фреймворк, и он пользуется доверием. -Он используется для создания проектов типа Instagram. +Это самый популярный Python-фреймворк, ему широко доверяют. Он используется для построения систем вроде Instagram. -Django довольно тесно связан с реляционными базами данных (такими как MySQL или PostgreSQL), потому использовать NoSQL базы данных (например, Couchbase, MongoDB, Cassandra и т.п.) в качестве основного хранилища данных - непросто. +Он относительно тесно связан с реляционными базами данных (например, MySQL или PostgreSQL), поэтому использовать NoSQL-базу данных (например, Couchbase, MongoDB, Cassandra и т. п.) в качестве основного хранилища не очень просто. -Он был создан для генерации HTML-страниц на сервере, а не для создания API, используемых современными веб-интерфейсами (React, Vue.js, Angular и т.п.) или другими системами (например, IoT) взаимодействующими с сервером. +Он был создан для генерации HTML на бэкенде, а не для создания API, используемых современным фронтендом (например, React, Vue.js и Angular) или другими системами (например, устройствами IoT), которые с ним общаются. -### Django REST Framework +### Django REST Framework { #django-rest-framework } -Фреймворк Django REST был создан, как гибкий инструментарий для создания веб-API на основе Django. +Django REST Framework был создан как гибкий набор инструментов для построения веб-API поверх Django, чтобы улучшить его возможности в части API. -DRF использовался многими компаниями, включая Mozilla, Red Hat и Eventbrite. +Он используется многими компаниями, включая Mozilla, Red Hat и Eventbrite. -Это был один из первых примеров **автоматического документирования API** и это была одна из первых идей, вдохновивших на создание **FastAPI**. +Это был один из первых примеров **автоматической документации API**, и именно эта идея одной из первых вдохновила на «поиск» **FastAPI**. /// note | Заметка -Django REST Framework был создан Tom Christie. -Он же создал Starlette и Uvicorn, на которых основан **FastAPI**. +Django REST Framework был создан Томом Кристи. Он же создал Starlette и Uvicorn, на которых основан **FastAPI**. /// -/// check | Идея для **FastAPI** +/// check | Вдохновило **FastAPI** на -Должно быть автоматическое создание документации API с пользовательским веб-интерфейсом. +Наличие пользовательского веб-интерфейса с автоматической документацией API. /// -### Flask +### Flask { #flask } -Flask - это "микрофреймворк", в нём нет интеграции с базами данных и многих других вещей, которые предустановлены в Django. +Flask — это «микрофреймворк», он не включает интеграции с базами данных и многие другие вещи, которые в Django идут «из коробки». -Его простота и гибкость дают широкие возможности, такие как использование баз данных NoSQL в качестве основной системы хранения данных. +Эта простота и гибкость позволяет, например, использовать NoSQL-базы в качестве основной системы хранения данных. -Он очень прост, его изучение интуитивно понятно, хотя в некоторых местах документация довольно техническая. +Он очень прост, его относительно легко интуитивно освоить, хотя местами документация довольно техническая. -Flask часто используется и для приложений, которым не нужна база данных, настройки прав доступа для пользователей и прочие из множества функций, предварительно встроенных в Django. -Хотя многие из этих функций могут быть добавлены с помощью плагинов. +Его также часто используют для приложений, которым не нужна база данных, управление пользователями или многие другие функции, предварительно встроенные в Django. Хотя многие из этих возможностей можно добавить плагинами. -Такое разделение на части и то, что это "микрофреймворк", который можно расширить, добавляя необходимые возможности, было ключевой особенностью, которую я хотел сохранить. +Такое разбиение на части и то, что это «микрофреймворк», который можно расширять ровно под нужды, — ключевая особенность, которую хотелось сохранить. -Простота Flask, показалась мне подходящей для создания API. -Но ещё нужно было найти "Django REST Framework" для Flask. +С учётом простоты Flask он казался хорошим вариантом для создания API. Следующим было найти «Django REST Framework» для Flask. -/// check | Идеи для **FastAPI** +/// check | Вдохновило **FastAPI** на -Это будет микрофреймворк. К нему легко будет добавить необходимые инструменты и части. +Быть микро-фреймворком. Облегчить комбинирование необходимых инструментов и компонентов. -Должна быть простая и лёгкая в использовании система маршрутизации запросов. +Иметь простую и удобную систему маршрутизации. /// -### Requests +### Requests { #requests } -На самом деле **FastAPI** не является альтернативой **Requests**. -Их область применения очень разная. +**FastAPI** на самом деле не альтернатива **Requests**. Их области применения очень различны. -В принципе, можно использовать Requests *внутри* приложения FastAPI. +Обычно Requests используют даже внутри приложения FastAPI. -Но всё же я использовал в FastAPI некоторые идеи из Requests. +И всё же **FastAPI** во многом вдохновлялся Requests. -**Requests** - это библиотека для взаимодействия с API в качестве клиента, -в то время как **FastAPI** - это библиотека для *создания* API (то есть сервера). +**Requests** — это библиотека для взаимодействия с API (как клиент), а **FastAPI** — библиотека для создания API (как сервер). -Они, так или иначе, диаметрально противоположны и дополняют друг друга. +Они, в каком-то смысле, находятся на противоположных концах и дополняют друг друга. -Requests имеет очень простой и понятный дизайн, очень прост в использовании и имеет разумные значения по умолчанию. -И в то же время он очень мощный и настраиваемый. +Requests имеет очень простой и понятный дизайн, им очень легко пользоваться, есть разумные значения по умолчанию. И при этом он очень мощный и настраиваемый. -Вот почему на официальном сайте написано: +Именно поэтому на официальном сайте сказано: -> Requests - один из самых загружаемых пакетов Python всех времен +> Requests — один из самых загружаемых Python-пакетов всех времён - -Использовать его очень просто. Например, чтобы выполнить запрос `GET`, Вы бы написали: +Пользоваться им очень просто. Например, чтобы сделать запрос `GET`, вы бы написали: ```Python response = requests.get("http://example.com/some/url") ``` -Противоположная *операция пути* в FastAPI может выглядеть следующим образом: +Соответствующая в FastAPI API-операция пути могла бы выглядеть так: ```Python hl_lines="1" @app.get("/some/url") @@ -106,428 +96,390 @@ def read_url(): return {"message": "Hello World"} ``` -Глядите, как похоже `requests.get(...)` и `@app.get(...)`. +Посмотрите, насколько похожи `requests.get(...)` и `@app.get(...)`. -/// check | Идеи для **FastAPI** +/// check | Вдохновило **FastAPI** на -* Должен быть простой и понятный API. -* Нужно использовать названия HTTP-методов (операций) для упрощения понимания происходящего. -* Должны быть разумные настройки по умолчанию и широкие возможности их кастомизации. +* Иметь простой и понятный API. +* Использовать названия HTTP-методов (операций) напрямую, простым и интуитивным образом. +* Иметь разумные значения по умолчанию, но и мощные настройки. /// -### Swagger / OpenAPI +### Swagger / OpenAPI { #swagger-openapi } -Главной функцией, которую я хотел унаследовать от Django REST Framework, была автоматическая документация API. +Главной возможностью, которую хотелось взять из Django REST Framework, была автоматическая документация API. -Но потом я обнаружил, что существует стандарт документирования API, использующий JSON (или YAML, расширение JSON) под названием Swagger. +Затем я обнаружил, что есть стандарт для документирования API с использованием JSON (или YAML — расширения JSON), под названием Swagger. -И к нему уже был создан пользовательский веб-интерфейс. -Таким образом, возможность генерировать документацию Swagger для API позволила бы использовать этот интерфейс. +И уже существовал веб-интерфейс для Swagger API. Поэтому возможность генерировать документацию Swagger для API позволила бы автоматически использовать этот веб-интерфейс. В какой-то момент Swagger был передан Linux Foundation и переименован в OpenAPI. -Вот почему, когда говорят о версии 2.0, обычно говорят "Swagger", а для версии 3+ "OpenAPI". +Вот почему, говоря о версии 2.0, обычно говорят «Swagger», а о версии 3+ — «OpenAPI». -/// check | Идеи для **FastAPI** +/// check | Вдохновило **FastAPI** на -Использовать открытые стандарты для спецификаций API вместо самодельных схем. +Использовать открытый стандарт для спецификаций API вместо самодельной схемы. -Совместимость с основанными на стандартах пользовательскими интерфейсами: +И интегрировать основанные на стандартах инструменты пользовательского интерфейса: * Swagger UI * ReDoc -Они были выбраны за популярность и стабильность. -Но сделав беглый поиск, Вы можете найти десятки альтернативных пользовательских интерфейсов для OpenAPI, которые Вы можете использовать с **FastAPI**. +Эти два инструмента выбраны за популярность и стабильность, но даже при беглом поиске можно найти десятки альтернативных интерфейсов для OpenAPI (которые можно использовать с **FastAPI**). /// -### REST фреймворки для Flask +### REST-фреймворки для Flask { #flask-rest-frameworks } -Существует несколько REST фреймворков для Flask, но потратив время и усилия на их изучение, я обнаружил, что многие из них не обновляются или заброшены и имеют нерешённые проблемы из-за которых они непригодны к использованию. +Существует несколько REST-фреймворков для Flask, но, вложив время и усилия в исследование, я обнаружил, что многие из них прекращены или заброшены, с несколькими нерешёнными Issue (тикет\обращение), из-за которых они непригодны. -### Marshmallow +### Marshmallow { #marshmallow } -Одной из основных функций, необходимых системам API, является "сериализация" данных, то есть преобразование данных из кода (Python) во что-то, что может быть отправлено по сети. -Например, превращение объекта содержащего данные из базы данных в объект JSON, конвертация объекта `datetime` в строку и т.п. +Одна из основных возможностей, нужных системам API, — «сериализация» данных, то есть преобразование данных из кода (Python) во что-то, что можно отправить по сети. Например, преобразование объекта с данными из базы в JSON-объект. Преобразование объектов `datetime` в строки и т. п. -Еще одна важная функция, необходимая API — проверка данных, позволяющая убедиться, что данные действительны и соответствуют заданным параметрам. -Как пример, можно указать, что ожидаются данные типа `int`, а не какая-то произвольная строка. -Это особенно полезно для входящих данных. +Ещё одна важная возможность, востребованная API, — валидация данных: убеждаться, что данные валидны с учётом заданных параметров. Например, что какое-то поле — `int`, а не произвольная строка. Это особенно полезно для входящих данных. -Без системы проверки данных Вам пришлось бы прописывать все проверки вручную. +Без системы валидации данных вам пришлось бы выполнять все проверки вручную в коде. -Именно для обеспечения этих функций и была создана Marshmallow. -Это отличная библиотека и я много раз пользовался ею раньше. +Именно для этих возможностей и был создан Marshmallow. Это отличная библиотека, я много ей пользовался раньше. -Но она была создана до того, как появились подсказки типов Python. -Итак, чтобы определить каждую схему, -Вам нужно использовать определенные утилиты и классы, предоставляемые Marshmallow. +Но она появилась до того, как в Python появились аннотации типов. Поэтому для определения каждой схемы нужно использовать специальные утилиты и классы, предоставляемые Marshmallow. -/// check | Идея для **FastAPI** +/// check | Вдохновило **FastAPI** на -Использовать код программы для автоматического создания "схем", определяющих типы данных и их проверку. +Использовать код для автоматического определения «схем», задающих типы данных и их валидацию. /// -### Webargs +### Webargs { #webargs } -Другая немаловажная функция API - парсинг данных из входящих запросов. +Ещё одна важная возможность для API — парсинг данных из входящих HTTP-запросов. -Webargs - это инструмент, который был создан для этого и поддерживает несколько фреймворков, включая Flask. +Webargs — это инструмент, созданный для этого поверх нескольких фреймворков, включая Flask. -Для проверки данных он использует Marshmallow и создан теми же авторами. +Он использует Marshmallow для валидации данных. И создан теми же разработчиками. -Это превосходный инструмент и я тоже часто пользовался им до **FastAPI**. +Это отличный инструмент, и я тоже много им пользовался до появления **FastAPI**. /// info | Информация -Webargs бы создан разработчиками Marshmallow. +Webargs был создан теми же разработчиками, что и Marshmallow. /// -/// check | Идея для **FastAPI** +/// check | Вдохновило **FastAPI** на -Должна быть автоматическая проверка входных данных. +Автоматическую валидацию входящих данных HTTP-запроса. /// -### APISpec +### APISpec { #apispec } -Marshmallow и Webargs осуществляют проверку, анализ и сериализацию данных как плагины. +Marshmallow и Webargs предоставляют валидацию, парсинг и сериализацию как плагины. -Но документации API всё ещё не было. Тогда был создан APISpec. +Но документации всё ещё не было. Тогда появился APISpec. -Это плагин для множества фреймворков, в том числе и для Starlette. +Это плагин для многих фреймворков (есть плагин и для Starlette). -Он работает так - Вы записываете определение схем, используя формат YAML, внутри докстринга каждой функции, обрабатывающей маршрут. +Он работает так: вы пишете определение схемы в формате YAML внутри докстринга каждой функции, обрабатывающей маршрут. -Используя эти докстринги, он генерирует схему OpenAPI. +И он генерирует схемы OpenAPI. -Так это работает для Flask, Starlette, Responder и т.п. +Так это работает во Flask, Starlette, Responder и т. д. -Но теперь у нас возникает новая проблема - наличие постороннего микро-синтаксиса внутри кода Python (большие YAML). +Но у нас снова возникает проблема: появляется микро-синтаксис внутри строки Python (большой YAML). -Редактор кода не особо может помочь в такой парадигме. -А изменив какие-то параметры или схемы для Marshmallow можно забыть отредактировать докстринг с YAML и сгенерированная схема становится недействительной. +Редактор кода мало чем может помочь. И если мы изменим параметры или схемы Marshmallow и забудем также изменить YAML в докстринге, сгенерированная схема устареет. /// info | Информация -APISpec тоже был создан авторами Marshmallow. +APISpec был создан теми же разработчиками, что и Marshmallow. /// -/// check | Идея для **FastAPI** +/// check | Вдохновило **FastAPI** на -Необходима поддержка открытого стандарта для API - OpenAPI. +Поддержку открытого стандарта для API — OpenAPI. /// -### Flask-apispec +### Flask-apispec { #flask-apispec } -Это плагин для Flask, который связан с Webargs, Marshmallow и APISpec. +Это плагин для Flask, который связывает Webargs, Marshmallow и APISpec. -Он получает информацию от Webargs и Marshmallow, а затем использует APISpec для автоматического создания схемы OpenAPI. +Он использует информацию из Webargs и Marshmallow, чтобы автоматически генерировать схемы OpenAPI с помощью APISpec. -Это отличный, но крайне недооценённый инструмент. -Он должен быть более популярен, чем многие плагины для Flask. -Возможно, это связано с тем, что его документация слишком скудна и абстрактна. +Отличный и недооценённый инструмент. Он заслуживает большей популярности, чем многие плагины для Flask. Возможно, из-за слишком краткой и абстрактной документации. -Он избавил от необходимости писать чужеродный синтаксис YAML внутри докстрингов. +Это решило проблему необходимости писать YAML (ещё один синтаксис) в докстрингах Python. -Такое сочетание Flask, Flask-apispec, Marshmallow и Webargs было моим любимым стеком при построении бэкенда до появления **FastAPI**. +Комбинация Flask, Flask-apispec с Marshmallow и Webargs была моим любимым бэкенд-стеком до создания **FastAPI**. -Использование этого стека привело к созданию нескольких генераторов проектов. Я и некоторые другие команды до сих пор используем их: +Его использование привело к созданию нескольких full-stack генераторов на Flask. Это основные стеки, которые я (и несколько внешних команд) использовали до сих пор: * https://github.com/tiangolo/full-stack * https://github.com/tiangolo/full-stack-flask-couchbase * https://github.com/tiangolo/full-stack-flask-couchdb -Эти генераторы проектов также стали основой для [Генераторов проектов с **FastAPI**](project-generation.md){.internal-link target=_blank}. +И эти же full-stack генераторы стали основой для [Генераторов проектов **FastAPI**](project-generation.md){.internal-link target=_blank}. /// info | Информация -Как ни странно, но Flask-apispec тоже создан авторами Marshmallow. +Flask-apispec был создан теми же разработчиками, что и Marshmallow. /// -/// check | Идея для **FastAPI** +/// check | Вдохновило **FastAPI** на -Схема OpenAPI должна создаваться автоматически и использовать тот же код, который осуществляет сериализацию и проверку данных. +Автоматическую генерацию схемы OpenAPI из того же кода, который определяет сериализацию и валидацию. /// -### NestJS (и Angular) +### NestJS (и Angular) { #nestjs-and-angular } -Здесь даже не используется Python. NestJS - этот фреймворк написанный на JavaScript (TypeScript), основанный на NodeJS и вдохновлённый Angular. +Это даже не Python. NestJS — это JavaScript/TypeScript-фреймворк на NodeJS, вдохновлённый Angular. -Он позволяет получить нечто похожее на то, что можно сделать с помощью Flask-apispec. +Он достигает чего-то отчасти похожего на то, что можно сделать с Flask-apispec. -В него встроена система внедрения зависимостей, ещё одна идея взятая от Angular. -Однако требуется предварительная регистрация "внедрений" (как и во всех других известных мне системах внедрения зависимостей), что увеличивает количество и повторяемость кода. +В нём встроена система внедрения зависимостей, вдохновлённая Angular 2. Требуется предварительная регистрация «инжектируемых» компонентов (как и во всех известных мне системах внедрения зависимостей), что добавляет многословности и повторяемости кода. -Так как параметры в нём описываются с помощью типов TypeScript (аналогично подсказкам типов в Python), поддержка редактора работает довольно хорошо. +Поскольку параметры описываются с помощью типов TypeScript (аналог аннотаций типов в Python), поддержка редактора весьма хороша. -Но поскольку данные из TypeScript не сохраняются после компиляции в JavaScript, он не может полагаться на подсказки типов для определения проверки данных, сериализации и документации. -Из-за этого и некоторых дизайнерских решений, для валидации, сериализации и автоматической генерации схем, приходится во многих местах добавлять декораторы. -Таким образом, это становится довольно многословным. +Но так как данные о типах TypeScript не сохраняются после компиляции в JavaScript, он не может полагаться на типы для одновременного определения валидации, сериализации и документации. Из‑за этого и некоторых проектных решений для получения валидации, сериализации и автоматической генерации схем приходится добавлять декораторы во многих местах. В итоге это становится довольно многословным. -Кроме того, он не очень хорошо справляется с вложенными моделями. -Если в запросе имеется объект JSON, внутренние поля которого, в свою очередь, являются вложенными объектами JSON, это не может быть должным образом задокументировано и проверено. +Он плохо справляется с вложенными моделями. Если JSON-тело запроса — это объект JSON, содержащий внутренние поля, которые сами являются вложенными объектами JSON, это нельзя как следует задокументировать и провалидировать. -/// check | Идеи для **FastAPI** +/// check | Вдохновило **FastAPI** на -Нужно использовать подсказки типов, чтоб воспользоваться поддержкой редактора кода. +Использовать типы Python для отличной поддержки в редакторе кода. -Нужна мощная система внедрения зависимостей. Необходим способ для уменьшения повторов кода. +Иметь мощную систему внедрения зависимостей. Найти способ минимизировать повторение кода. /// -### Sanic +### Sanic { #sanic } -Sanic был одним из первых чрезвычайно быстрых Python-фреймворков основанных на `asyncio`. -Он был сделан очень похожим на Flask. +Это был один из первых чрезвычайно быстрых Python-фреймворков на основе `asyncio`. Он был сделан очень похожим на Flask. /// note | Технические детали -В нём использован `uvloop` вместо стандартного цикла событий `asyncio`, что и сделало его таким быстрым. +Он использовал `uvloop` вместо стандартного цикла `asyncio` в Python. Это и сделало его таким быстрым. -Он явно вдохновил создателей Uvicorn и Starlette, которые в настоящее время быстрее Sanic в открытых бенчмарках. +Он явно вдохновил Uvicorn и Starlette, которые сейчас быстрее Sanic в открытых бенчмарках. /// -/// check | Идеи для **FastAPI** +/// check | Вдохновило **FastAPI** на -Должна быть сумасшедшая производительность. +Поиск способа достичь сумасшедшей производительности. -Для этого **FastAPI** основан на Starlette, самом быстром из доступных фреймворков (по замерам незаинтересованных лиц). +Именно поэтому **FastAPI** основан на Starlette, так как это самый быстрый доступный фреймворк (по данным сторонних бенчмарков). /// -### Falcon +### Falcon { #falcon } -Falcon - ещё один высокопроизводительный Python-фреймворк. -В нём минимум функций и он создан, чтоб быть основой для других фреймворков, например, Hug. +Falcon — ещё один высокопроизводительный Python-фреймворк, он минималистичен и служит основой для других фреймворков, таких как Hug. -Функции в нём получают два параметра - "запрос к серверу" и "ответ сервера". -Затем Вы "читаете" часть запроса и "пишите" часть ответа. -Из-за такой конструкции невозможно объявить параметры запроса и тела сообщения со стандартными подсказками типов Python в качестве параметров функции. +Он спроектирован так, что функции получают два параметра: «request» и «response». Затем вы «читаете» части из запроса и «пишете» части в ответ. Из‑за такого дизайна невозможно объявить параметры запроса и тело запроса стандартными аннотациями типов Python как параметры функции. -Таким образом, и валидацию данных, и их сериализацию, и документацию нужно прописывать вручную. -Либо эти функции должны быть встроены во фреймворк, сконструированный поверх Falcon, как в Hug. -Такая же особенность присутствует и в других фреймворках, вдохновлённых идеей Falcon, использовать только один объект запроса и один объект ответа. +Поэтому валидация данных, сериализация и документация должны выполняться в коде вручную, не автоматически. Либо должны быть реализованы во фреймворке поверх Falcon, как в Hug. Та же особенность есть и в других фреймворках, вдохновлённых дизайном Falcon — с одним объектом запроса и одним объектом ответа в параметрах. -/// check | Идея для **FastAPI** +/// check | Вдохновило **FastAPI** на -Найдите способы добиться отличной производительности. +Поиск способов получить отличную производительность. -Объявлять параметры `ответа сервера` в функциях, как в Hug. +Вместе с Hug (так как Hug основан на Falcon) вдохновило **FastAPI** объявлять параметр `response` в функциях. -Хотя в FastAPI это необязательно и используется в основном для установки заголовков, куки и альтернативных кодов состояния. +Хотя в FastAPI это необязательно, и используется в основном для установки HTTP-заголовков, cookie и альтернативных статус-кодов. /// -### Molten +### Molten { #molten } -Molten мне попался на начальной стадии написания **FastAPI**. В нём были похожие идеи: +Я обнаружил Molten на ранних этапах создания **FastAPI**. И у него были очень похожие идеи: -* Использование подсказок типов. -* Валидация и документация исходя из этих подсказок. +* Основан на аннотациях типов Python. +* Валидация и документация из этих типов. * Система внедрения зависимостей. -В нём не используются сторонние библиотеки (такие, как Pydantic) для валидации, сериализации и документации. -Поэтому переиспользовать эти определения типов непросто. +Он не использует стороннюю библиотеку для валидации, сериализации и документации, такую как Pydantic, — у него своя. Поэтому такие определения типов данных будет сложнее переиспользовать. -Также требуется более подробная конфигурация и используется стандарт WSGI, который не предназначен для использования с высокопроизводительными инструментами, такими как Uvicorn, Starlette и Sanic, в отличие от ASGI. +Требуются более многословные конфигурации. И так как он основан на WSGI (вместо ASGI), он не предназначен для использования преимуществ высокой производительности инструментов вроде Uvicorn, Starlette и Sanic. -Его система внедрения зависимостей требует предварительной регистрации, и зависимости определяются, как объявления типов. -Из-за этого невозможно объявить более одного "компонента" (зависимости), который предоставляет определенный тип. +Система внедрения зависимостей требует предварительной регистрации зависимостей, а зависимости разрешаются по объявленным типам. Поэтому невозможно объявить более одного «компонента», предоставляющего определённый тип. -Маршруты объявляются в единственном месте с использованием функций, объявленных в других местах (вместо использования декораторов, в которые могут быть обёрнуты функции, обрабатывающие конкретные ресурсы). -Это больше похоже на Django, чем на Flask и Starlette. -Он разделяет в коде вещи, которые довольно тесно связаны. +Маршруты объявляются в одном месте, используя функции, объявленные в других местах (вместо декораторов, которые можно разместить прямо над функцией, обрабатывающей эндпоинт). Это ближе к тому, как это делает Django, чем Flask (и Starlette). Это разделяет в коде вещи, которые довольно тесно связаны. -/// check | Идея для **FastAPI** +/// check | Вдохновило **FastAPI** на -Определить дополнительные проверки типов данных, используя значения атрибутов модели "по умолчанию". -Это улучшает помощь редактора и раньше это не было доступно в Pydantic. +Определять дополнительные проверки типов данных, используя значение «по умолчанию» атрибутов модели. Это улучшает поддержку в редакторе кода, и раньше этого не было в Pydantic. -Фактически это подтолкнуло на обновление Pydantic для поддержки одинакового стиля проверок (теперь этот функционал уже доступен в Pydantic). +Фактически это вдохновило на обновление частей Pydantic, чтобы поддерживать такой же стиль объявления валидации (вся эта функциональность теперь уже есть в Pydantic). /// -### Hug +### Hug { #hug } -Hug был одним из первых фреймворков, реализовавших объявление параметров API с использованием подсказок типов Python. -Эта отличная идея была использована и другими инструментами. +Hug был одним из первых фреймворков, реализовавших объявление типов параметров API с использованием аннотаций типов Python. Это была отличная идея, которая вдохновила и другие инструменты. -При объявлении параметров вместо стандартных типов Python использовались собственные типы, но всё же это был огромный шаг вперед. +Он использовал собственные типы в объявлениях вместо стандартных типов Python, но это всё равно был огромный шаг вперёд. -Это также был один из первых фреймворков, генерировавших полную API-схему в формате JSON. +Он также был одним из первых фреймворков, генерировавших собственную схему, описывающую весь API в JSON. -Данная схема не придерживалась стандартов вроде OpenAPI и JSON Schema. -Поэтому было бы непросто совместить её с другими инструментами, такими как Swagger UI. -Но опять же, это была очень инновационная идея. +Он не был основан на стандартах вроде OpenAPI и JSON Schema. Поэтому интегрировать его с другими инструментами, такими как Swagger UI, было бы непросто. Но, опять же, это была очень инновационная идея. -Ещё у него есть интересная и необычная функция: используя один и тот же фреймворк можно создавать и API, и CLI. +У него есть интересная и необычная особенность: с помощью одного и того же фреймворка можно создавать и API, и CLI. -Поскольку он основан на WSGI, старом стандарте для синхронных веб-фреймворков, он не может работать с веб-сокетами и другими модными штуками, но всё равно обладает высокой производительностью. +Так как он основан на предыдущем стандарте для синхронных веб-фреймворков Python (WSGI), он не может работать с WebSocket и прочим, хотя также демонстрирует высокую производительность. /// info | Информация -Hug создан Timothy Crosley, автором `isort`, отличного инструмента для автоматической сортировки импортов в Python-файлах. +Hug был создан Тимоти Кросли, тем же автором `isort`, отличного инструмента для автоматической сортировки импортов в файлах Python. /// -/// check | Идеи для **FastAPI** +/// check | Идеи, вдохновившие **FastAPI** -Hug повлиял на создание некоторых частей APIStar и был одним из инструментов, которые я счел наиболее многообещающими, наряду с APIStar. +Hug вдохновил части APIStar и был одним из наиболее многообещающих инструментов, которые я нашёл, наряду с APIStar. -Hug натолкнул на мысли использовать в **FastAPI** подсказки типов Python для автоматического создания схемы, определяющей API и его параметры. +Hug помог вдохновить **FastAPI** использовать аннотации типов Python для объявления параметров и автоматически генерировать схему, определяющую API. -Hug вдохновил **FastAPI** объявить параметр `ответа` в функциях для установки заголовков и куки. +Hug вдохновил **FastAPI** объявлять параметр `response` в функциях для установки HTTP-заголовков и cookie. /// -### APIStar (<= 0.5) +### APIStar (<= 0.5) { #apistar-0-5 } -Непосредственно перед тем, как принять решение о создании **FastAPI**, я обнаружил **APIStar**. -В нем было почти все, что я искал и у него был отличный дизайн. +Прямо перед решением строить **FastAPI** я нашёл сервер **APIStar**. В нём было почти всё, что я искал, и отличный дизайн. -Это была одна из первых реализаций фреймворка, использующего подсказки типов для объявления параметров и запросов, которые я когда-либо видел (до NestJS и Molten). -Я нашёл его примерно в то же время, что и Hug, но APIStar использовал стандарт OpenAPI. +Это была одна из первых реализаций фреймворка, использующего аннотации типов Python для объявления параметров и запросов (до NestJS и Molten), которые я видел. Я обнаружил его примерно в то же время, что и Hug. Но APIStar использовал стандарт OpenAPI. -В нём были автоматические проверка и сериализация данных и генерация схемы OpenAPI основанные на подсказках типов в нескольких местах. +В нём были автоматические валидация данных, сериализация данных и генерация схемы OpenAPI на основе тех же аннотаций типов в нескольких местах. -При определении схемы тела сообщения не использовались подсказки типов, как в Pydantic, это больше похоже на Marshmallow, поэтому помощь редактора была недостаточно хорошей, но всё же APIStar был лучшим доступным вариантом. +Определение схемы тела запроса не использовало те же аннотации типов Python, как в Pydantic, — это было ближе к Marshmallow, поэтому поддержка редактора была бы хуже, но всё равно APIStar оставался лучшим доступным вариантом. -На тот момент у него были лучшие показатели производительности (проигрывающие только Starlette). +На тот момент у него были лучшие показатели в бенчмарках (его превосходил только Starlette). -Изначально у него не было автоматической документации API для веб-интерфейса, но я знал, что могу добавить к нему Swagger UI. +Сначала у него не было веб‑UI для автоматической документации API, но я знал, что могу добавить к нему Swagger UI. -В APIStar была система внедрения зависимостей, которая тоже требовала предварительную регистрацию компонентов, как и ранее описанные инструменты. -Но, тем не менее, это была отличная штука. +У него была система внедрения зависимостей. Она требовала предварительной регистрации компонентов, как и другие инструменты, обсуждавшиеся выше. Но всё же это была отличная возможность. -Я не смог использовать его в полноценном проекте, так как были проблемы со встраиванием функций безопасности в схему OpenAPI, из-за которых невозможно было встроить все функции, применяемые в генераторах проектов на основе Flask-apispec. -Я добавил в свой список задач создание пул-реквеста, добавляющего эту функциональность. +Мне так и не удалось использовать его в полном проекте, поскольку не было интеграции с системой безопасности, поэтому я не мог заменить все возможности, которые имел с full-stack генераторами на основе Flask-apispec. В моём бэклоге было создать пулл-реквест (запрос на изменение), добавляющий эту функциональность. -В дальнейшем фокус проекта сместился. +Затем фокус проекта сместился. -Это больше не был API-фреймворк, так как автор сосредоточился на Starlette. +Это перестал быть веб-фреймворк для API, так как автору нужно было сосредоточиться на Starlette. -Ныне APIStar - это набор инструментов для проверки спецификаций OpenAPI. +Сейчас APIStar — это набор инструментов для валидации спецификаций OpenAPI, а не веб-фреймворк. /// info | Информация -APIStar был создан Tom Christie. Тот самый парень, который создал: +APIStar был создан Томом Кристи. Тем самым человеком, который создал: * Django REST Framework * Starlette (на котором основан **FastAPI**) -* Uvicorn (используемый в Starlette и **FastAPI**) +* Uvicorn (используется Starlette и **FastAPI**) /// -/// check | Идеи для **FastAPI** +/// check | Вдохновило **FastAPI** на -Воплощение. +Существование. -Мне казалось блестящей идеей объявлять множество функций (проверка данных, сериализация, документация) с помощью одних и тех же типов Python, которые при этом обеспечивают ещё и помощь редактора кода. +Идея объявлять сразу несколько вещей (валидацию данных, сериализацию и документацию) с помощью одних и тех же типов Python, которые одновременно обеспечивают отличную поддержку в редакторе кода, показалась мне блестящей. -После долгих поисков среди похожих друг на друга фреймворков и сравнения их различий, APIStar стал самым лучшим выбором. +После долгих поисков похожего фреймворка и тестирования множества альтернатив APIStar был лучшим доступным вариантом. -Но APIStar перестал быть фреймворком для создания веб-сервера, зато появился Starlette, новая и лучшая основа для построения подобных систем. -Это была последняя капля, сподвигнувшая на создание **FastAPI**. +Затем APIStar перестал существовать как сервер, а был создан Starlette — новая и лучшая основа для такой системы. Это стало окончательным вдохновением для создания **FastAPI**. -Я считаю **FastAPI** "духовным преемником" APIStar, улучившим его возможности благодаря урокам, извлечённым из всех упомянутых выше инструментов. +Я считаю **FastAPI** «духовным преемником» APIStar, который улучшает и расширяет возможности, систему типов и другие части, опираясь на уроки от всех этих предыдущих инструментов. /// -## Что используется в **FastAPI** +## Что используется в **FastAPI** { #used-by-fastapi } + +### Pydantic { #pydantic } -### Pydantic +Pydantic — это библиотека для определения валидации данных, сериализации и документации (с использованием JSON Schema) на основе аннотаций типов Python. -Pydantic - это библиотека для валидации данных, сериализации и документирования (используя JSON Schema), основываясь на подсказках типов Python, что делает его чрезвычайно интуитивным. +Благодаря этому он чрезвычайно интуитивен. -Его можно сравнить с Marshmallow, хотя в бенчмарках Pydantic быстрее, чем Marshmallow. -И он основан на тех же подсказках типов, которые отлично поддерживаются редакторами кода. +Его можно сравнить с Marshmallow. Хотя в бенчмарках он быстрее Marshmallow. И поскольку он основан на тех же аннотациях типов Python, поддержка в редакторе кода отличная. -/// check | **FastAPI** использует Pydantic +/// check | **FastAPI** использует его для -Для проверки данных, сериализации данных и автоматической документации моделей (на основе JSON Schema). +Обработки всей валидации данных, сериализации данных и автоматической документации моделей (на основе JSON Schema). -Затем **FastAPI** берёт эти схемы JSON и помещает их в схему OpenAPI, не касаясь других вещей, которые он делает. +Затем **FastAPI** берёт эти данные JSON Schema и помещает их в OpenAPI, помимо всех прочих функций. /// -### Starlette +### Starlette { #starlette } -Starlette - это легковесный ASGI фреймворк/набор инструментов, который идеален для построения высокопроизводительных асинхронных сервисов. +Starlette — это лёгкий ASGI фреймворк/набор инструментов, идеально подходящий для создания высокопроизводительных asyncio‑сервисов. -Starlette очень простой и интуитивный. -Он разработан таким образом, чтобы быть легко расширяемым и иметь модульные компоненты. +Он очень простой и интуитивный. Спроектирован так, чтобы его было легко расширять, и чтобы компоненты были модульными. В нём есть: * Впечатляющая производительность. -* Поддержка веб-сокетов. -* Фоновые задачи. -* Обработка событий при старте и финише приложения. -* Тестовый клиент на основе HTTPX. -* Поддержка CORS, сжатие GZip, статические файлы, потоковая передача данных. -* Поддержка сессий и куки. +* Поддержка WebSocket. +* Фоновые задачи, выполняемые в том же процессе. +* События запуска и завершения. +* Тестовый клиент на базе HTTPX. +* CORS, GZip, статические файлы, потоковые ответы. +* Поддержка сессий и cookie. * 100% покрытие тестами. -* 100% аннотированный код. -* Несколько жёстких зависимостей. +* 100% кодовой базы с аннотациями типов. +* Мало жёстких зависимостей. + +В настоящее время Starlette — самый быстрый из протестированных Python-фреймворков. Его превосходит только Uvicorn, который не фреймворк, а сервер. -В настоящее время Starlette показывает самую высокую скорость среди Python-фреймворков в тестовых замерах. -Быстрее только Uvicorn, который является сервером, а не фреймворком. +Starlette предоставляет весь базовый функционал веб-микрофреймворка. -Starlette обеспечивает весь функционал микрофреймворка, но не предоставляет автоматическую валидацию данных, сериализацию и документацию. +Но он не предоставляет автоматическую валидацию данных, сериализацию или документацию. -**FastAPI** добавляет эти функции используя подсказки типов Python и Pydantic. -Ещё **FastAPI** добавляет систему внедрения зависимостей, утилиты безопасности, генерацию схемы OpenAPI и т.д. +Это одна из главных вещей, которые **FastAPI** добавляет поверх, всё на основе аннотаций типов Python (с использованием Pydantic). Плюс система внедрения зависимостей, утилиты безопасности, генерация схемы OpenAPI и т. д. /// note | Технические детали -ASGI - это новый "стандарт" разработанный участниками команды Django. -Он пока что не является "стандартом в Python" (то есть принятым PEP), но процесс принятия запущен. +ASGI — это новый «стандарт», разрабатываемый участниками core-команды Django. Он всё ещё не является «стандартом Python» (PEP), хотя процесс идёт. -Тем не менее он уже используется в качестве "стандарта" несколькими инструментами. -Это значительно улучшает совместимость, поскольку Вы можете переключиться с Uvicorn на любой другой ASGI-сервер (например, Daphne или Hypercorn) или Вы можете добавить ASGI-совместимые инструменты, такие как `python-socketio`. +Тем не менее его уже используют как «стандарт» несколько инструментов. Это сильно улучшает совместимость: вы можете заменить Uvicorn на любой другой ASGI-сервер (например, Daphne или Hypercorn) или добавить совместимые с ASGI инструменты, такие как `python-socketio`. /// -/// check | **FastAPI** использует Starlette +/// check | **FastAPI** использует его для -В качестве ядра веб-сервиса для обработки запросов, добавив некоторые функции сверху. +Обработки всех основных веб-частей. Добавляя возможности поверх. -Класс `FastAPI` наследуется напрямую от класса `Starlette`. +Класс `FastAPI` напрямую наследуется от класса `Starlette`. -Таким образом, всё что Вы могли делать со Starlette, Вы можете делать с **FastAPI**, по сути это прокачанный Starlette. +Так что всё, что вы можете сделать со Starlette, вы можете сделать напрямую с **FastAPI**, по сути это «Starlette на стероидах». /// -### Uvicorn +### Uvicorn { #uvicorn } -Uvicorn - это молниеносный ASGI-сервер, построенный на uvloop и httptools. +Uvicorn — молниеносный ASGI-сервер, построенный на uvloop и httptools. -Uvicorn является сервером, а не фреймворком. -Например, он не предоставляет инструментов для маршрутизации запросов по ресурсам. -Для этого нужна надстройка, такая как Starlette (или **FastAPI**). +Это не веб-фреймворк, а сервер. Например, он не предоставляет инструменты для маршрутизации по путям. Это предоставляет сверху фреймворк, такой как Starlette (или **FastAPI**). -Он рекомендуется в качестве сервера для Starlette и **FastAPI**. +Это рекомендуемый сервер для Starlette и **FastAPI**. -/// check | **FastAPI** рекомендует его +/// check | **FastAPI** рекомендует его как -Как основной сервер для запуска приложения **FastAPI**. +Основной веб-сервер для запуска приложений **FastAPI**. -Вы можете объединить его с Gunicorn, чтобы иметь асинхронный многопроцессный сервер. +Также вы можете использовать опцию командной строки `--workers`, чтобы получить асинхронный многопроцессный сервер. -Узнать больше деталей можно в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}. +Подробнее см. раздел [Развёртывание](deployment/index.md){.internal-link target=_blank}. /// -## Тестовые замеры и скорость +## Бенчмарки и скорость { #benchmarks-and-speed } -Чтобы понять, сравнить и увидеть разницу между Uvicorn, Starlette и FastAPI, ознакомьтесь с разделом [Тестовые замеры](benchmarks.md){.internal-link target=_blank}. +Чтобы понять, сравнить и увидеть разницу между Uvicorn, Starlette и FastAPI, см. раздел о [Бенчмарках](benchmarks.md){.internal-link target=_blank}. diff --git a/docs/ru/docs/async.md b/docs/ru/docs/async.md index 813836d360..15d4e108ab 100644 --- a/docs/ru/docs/async.md +++ b/docs/ru/docs/async.md @@ -1,18 +1,18 @@ -# Конкурентность и async / await +# Конкурентность и async / await { #concurrency-and-async-await } -Здесь приведена подробная информация об использовании синтаксиса `async def` при написании *функций обработки пути*, а также рассмотрены основы асинхронного программирования, конкурентности и параллелизма. +Подробности о синтаксисе `async def` для *функций-обработчиков пути* и немного фона об асинхронном коде, конкурентности и параллелизме. -## Нет времени? +## Нет времени? { #in-a-hurry } -TL;DR: +TL;DR: -Допустим, вы используете сторонюю библиотеку, которая требует вызова с ключевым словом `await`: +Если вы используете сторонние библиотеки, которые нужно вызывать с `await`, например: ```Python results = await some_library() ``` -В этом случае *функции обработки пути* необходимо объявлять с использованием синтаксиса `async def`: +Тогда объявляйте *функции-обработчики пути* с `async def`, например: ```Python hl_lines="2" @app.get('/') @@ -21,18 +21,15 @@ async def read_results(): return results ``` -/// note +/// note | Примечание -`await` можно использовать только внутри функций, объявленных с использованием `async def`. +`await` можно использовать только внутри функций, объявленных с `async def`. /// --- -Если вы обращаетесь к сторонней библиотеке, которая с чем-то взаимодействует -(с базой данных, API, файловой системой и т. д.), и не имеет поддержки синтаксиса `await` -(что относится сейчас к большинству библиотек для работы с базами данных), то -объявляйте *функции обработки пути* обычным образом с помощью `def`, например: +Если вы используете стороннюю библиотеку, которая взаимодействует с чем-то (база данных, API, файловая система и т.д.) и не поддерживает использование `await` (сейчас это относится к большинству библиотек для БД), тогда объявляйте *функции-обработчики пути* как обычно, просто с `def`, например: ```Python hl_lines="2" @app.get('/') @@ -43,310 +40,283 @@ def results(): --- -Если вашему приложению (странным образом) не нужно ни с чем взаимодействовать и, соответственно, -ожидать ответа, используйте `async def`. +Если вашему приложению (по какой-то причине) не нужно ни с чем взаимодействовать и ждать ответа, используйте `async def`, даже если внутри не нужен `await`. --- -Если вы не уверены, используйте обычный синтаксис `def`. +Если вы просто не уверены, используйте обычный `def`. --- -**Примечание**: при необходимости можно смешивать `def` и `async def` в *функциях обработки пути* -и использовать в каждом случае наиболее подходящий синтаксис. А FastAPI сделает с этим всё, что нужно. +**Примечание**: вы можете смешивать `def` и `async def` в *функциях-обработчиках пути* столько, сколько нужно, и объявлять каждую так, как лучше для вашего случая. FastAPI сделает с ними всё как надо. -В любом из описанных случаев FastAPI работает асинхронно и очень быстро. +В любом из случаев выше FastAPI всё равно работает асинхронно и очень быстро. -Однако придерживаясь указанных советов, можно получить дополнительную оптимизацию производительности. +Но следуя этим шагам, он сможет выполнить некоторые оптимизации производительности. -## Технические подробности +## Технические подробности { #technical-details } -Современные версии Python поддерживают разработку так называемого **"асинхронного кода"** посредством написания **"сопрограмм"** с использованием синтаксиса **`async` и `await`**. +Современные версии Python поддерживают **«асинхронный код»** с помощью **«сопрограмм»** (coroutines) и синтаксиса **`async` и `await`**. -Ниже разберём эту фразу по частям: +Разберём эту фразу по частям в разделах ниже: * **Асинхронный код** * **`async` и `await`** * **Сопрограммы** -## Асинхронный код +## Асинхронный код { #asynchronous-code } -Асинхронный код означает, что в языке 💬 есть возможность сообщить машине / программе 🤖, -что в определённой точке кода ей 🤖 нужно будет ожидать завершения выполнения *чего-то ещё* в другом месте. Допустим это *что-то ещё* называется "медленный файл" 📝. +Асинхронный код значит, что в языке 💬 есть способ сказать компьютеру/программе 🤖, что в некоторый момент кода ему 🤖 придётся подождать, пока *что-то ещё* где-то в другом месте завершится. Назовём это *что-то ещё* «медленный файл» 📝. -И пока мы ждём завершения работы с "медленным файлом" 📝, компьютер может переключиться для выполнения других задач. +И пока мы ждём завершения работы с «медленныи файлом» 📝, компьютер может заняться другой работой. -Но при каждой возможности компьютер / программа 🤖 будет возвращаться обратно. Например, если он 🤖 опять окажется в режиме ожидания, или когда закончит всю работу. В этом случае компьютер 🤖 проверяет, не завершена ли какая-нибудь из текущих задач. +Затем компьютер/программа 🤖 будет возвращаться каждый раз, когда появится возможность (пока снова где-то идёт ожидание), или когда 🤖 завершит всю текущую работу. И он 🤖 проверит, не завершилась ли какая-либо из задач, которых он ждал, и сделает то, что нужно. -Потом он 🤖 берёт первую выполненную задачу (допустим, наш "медленный файл" 📝) и продолжает работу, производя с ней необходимые действия. +Далее он 🤖 возьмёт первую завершившуюся задачу (скажем, наш «медленный файл» 📝) и продолжит делать с ней то, что требуется. -Вышеупомянутое "что-то ещё", завершения которого приходится ожидать, обычно относится к достаточно "медленным" операциям I/O (по сравнению со скоростью работы процессора и оперативной памяти), например: +Это «ожидание чего-то ещё» обычно относится к операциям I/O, которые относительно «медленные» (по сравнению со скоростью процессора и оперативной памяти), например ожидание: -* отправка данных от клиента по сети -* получение клиентом данных, отправленных вашей программой по сети -* чтение системой содержимого файла с диска и передача этих данных программе -* запись на диск данных, которые программа передала системе -* обращение к удалённому API -* ожидание завершения операции с базой данных -* получение результатов запроса к базе данных -* и т. д. +* отправки данных клиентом по сети +* получения клиентом данных, отправленных вашей программой по сети +* чтения системой содержимого файла на диске и передачи этих данных вашей программе +* записи на диск содержимого, которое ваша программа передала системе +* операции удалённого API +* завершения операции базы данных +* возврата результатов запроса к базе данных +* и т.д. -Поскольку в основном время тратится на ожидание выполнения операций I/O, -их обычно называют операциями, ограниченными скоростью ввода-вывода. +Поскольку основное время выполнения уходит на ожидание операций I/O, их называют операциями, «ограниченными вводом-выводом» (I/O bound). -Код называют "асинхронным", потому что компьютеру / программе не требуется "синхронизироваться" с медленной задачей и, -будучи в простое, ожидать момента её завершения, с тем чтобы забрать результат и продолжить работу. +Это называется «асинхронным», потому что компьютеру/программе не нужно «синхронизироваться» с медленной задачей, простаивая и выжидая точный момент её завершения, чтобы забрать результат и продолжить работу. -Вместо этого в "асинхронной" системе завершённая задача может немного подождать (буквально несколько микросекунд), -пока компьютер / программа занимается другими важными вещами, с тем чтобы потом вернуться, -забрать результаты выполнения и начать их обрабатывать. +Вместо этого, в «асинхронной» системе, уже завершившаяся задача может немного подождать (несколько микросекунд) в очереди, пока компьютер/программа завершит то, чем занимался, и затем вернётся, чтобы забрать результаты и продолжить работу с ними. -"Синхронное" исполнение (в противовес "асинхронному") также называют "последовательным", -потому что компьютер / программа последовательно выполняет все требуемые шаги перед тем, как перейти к следующей задаче, -даже если в процессе приходится ждать. +Для «синхронного» (в противоположность «асинхронному») исполнения часто используют термин «последовательный», потому что компьютер/программа выполняет все шаги по порядку, прежде чем переключиться на другую задачу, даже если эти шаги включают ожидание. -### Конкурентность и бургеры +### Конкурентность и бургеры { #concurrency-and-burgers } -Тот **асинхронный** код, о котором идёт речь выше, иногда называют **"конкурентностью"**. Она отличается от **"параллелизма"**. +Та идея **асинхронного** кода, описанная выше, иногда также называется **«конкурентностью»**. Она отличается от **«параллелизма»**. -Да, **конкурентность** и **параллелизм** подразумевают, что разные вещи происходят примерно в одно время. +И **конкурентность**, и **параллелизм** относятся к «разным вещам, происходящим примерно одновременно». -Но внутреннее устройство **конкурентности** и **параллелизма** довольно разное. +Но различия между *конкурентностью* и *параллелизмом* довольно существенные. -Чтобы это понять, представьте такую картину: +Чтобы их увидеть, представьте следующую историю про бургеры: -### Конкурентные бургеры +### Конкурентные бургеры { #concurrent-burgers } - +Вы идёте со своей возлюбленной за фастфудом, вы стоите в очереди, пока кассир принимает заказы у людей перед вами. 😍 -Вы идёте со своей возлюбленной 😍 в фастфуд 🍔 и становитесь в очередь, в это время кассир 💁 принимает заказы у посетителей перед вами. + -Когда наконец подходит очередь, вы заказываете парочку самых вкусных и навороченных бургеров 🍔, один для своей возлюбленной 😍, а другой себе. +Наконец ваша очередь: вы заказываете 2 очень «навороченных» бургера — для вашей возлюбленной и для себя. 🍔🍔 -Отдаёте деньги 💸. + -Кассир 💁 что-то говорит поварам на кухне 👨‍🍳, теперь они знают, какие бургеры нужно будет приготовить 🍔 -(но пока они заняты бургерами предыдущих клиентов). +Кассир говорит что-то повару на кухне, чтобы они знали, что нужно приготовить ваши бургеры (хотя сейчас они готовят бургеры для предыдущих клиентов). -Кассир 💁 отдаёт вам чек с номером заказа. + -В ожидании еды вы идёте со своей возлюбленной 😍 выбрать столик, садитесь и довольно продолжительное время общаетесь 😍 -(поскольку ваши бургеры самые навороченные, готовятся они не так быстро ✨🍔✨). +Вы платите. 💸 -Сидя за столиком с возлюбленной 😍 в ожидании бургеров 🍔, вы отлично проводите время, -восхищаясь её великолепием, красотой и умом ✨😍✨. +Кассир выдаёт вам номер вашей очереди. -Всё ещё ожидая заказ и болтая со своей возлюбленной 😍, время от времени вы проверяете, -какой номер горит над прилавком, и не подошла ли уже ваша очередь. + -И вот наконец настаёт этот момент, и вы идёте к стойке, чтобы забрать бургеры 🍔 и вернуться за столик. +Пока вы ждёте, вы вместе со своей возлюбленной идёте и выбираете столик, садитесь и долго болтаете (ваши бургеры очень «навороченные», поэтому им нужно время на приготовление). -Вы со своей возлюбленной 😍 едите бургеры 🍔 и отлично проводите время ✨. +Сидя за столиком со своей возлюбленной в ожидании бургеров, вы можете провести это время, восхищаясь тем, какая она классная, милая и умная ✨😍✨. + + + +Пока вы ждёте и разговариваете, время от времени вы поглядываете на номер на табло, чтобы понять, не подошла ли уже ваша очередь. + +И вот в какой-то момент ваша очередь наступает. Вы подходите к стойке, забираете свои бургеры и возвращаетесь к столику. + + + +Вы со своей возлюбленной едите бургеры и отлично проводите время. ✨ + + + +/// info | Информация + +Прекрасные иллюстрации от Ketrina Thompson. 🎨 + +/// --- -А теперь представьте, что в этой небольшой истории вы компьютер / программа 🤖. +Представьте, что в этой истории вы — компьютер/программа 🤖. -В очереди вы просто глазеете по сторонам 😴, ждёте и ничего особо "продуктивного" не делаете. -Но очередь движется довольно быстро, поскольку кассир 💁 только принимает заказы (а не занимается приготовлением еды), так что ничего страшного. +Пока вы стоите в очереди, вы просто бездействуете 😴, ждёте своей очереди и не делаете ничего особо «продуктивного». Но очередь движется быстро, потому что кассир только принимает заказы (а не готовит их), так что это нормально. -Когда подходит очередь вы наконец предпринимаете "продуктивные" действия 🤓: просматриваете меню, выбираете в нём что-то, узнаёте, что хочет ваша возлюбленная 😍, собираетесь оплатить 💸, смотрите, какую достали карту, проверяете, чтобы с вас списали верную сумму, и что в заказе всё верно и т. д. +Когда приходит ваша очередь, вы выполняете действительно «продуктивную» работу: просматриваете меню, решаете, чего хотите, учитываете выбор своей возлюбленной, платите, проверяете, что дали правильную купюру/карту, что сумма списана корректно, что в заказе верные позиции и т.д. -И хотя вы всё ещё не получили бургеры 🍔, ваша работа с кассиром 💁 ставится "на паузу" ⏸, -поскольку теперь нужно ждать 🕙, когда заказ приготовят. +Но затем, хотя у вас ещё нет бургеров, ваша «работа» с кассиром поставлена «на паузу» ⏸, потому что нужно подождать 🕙, пока бургеры будут готовы. -Но отойдя с номерком от прилавка, вы садитесь за столик и можете переключить 🔀 внимание -на свою возлюбленную 😍 и "работать" ⏯ 🤓 уже над этим. И вот вы снова очень -"продуктивны" 🤓, мило болтаете вдвоём и всё такое 😍. +Но, отойдя от стойки и сев за столик с номерком, вы можете переключить 🔀 внимание на свою возлюбленную и «поработать» ⏯ 🤓 над этим. Снова очень «продуктивно» — флирт с вашей возлюбленной 😍. -В какой-то момент кассир 💁 поместит на табло ваш номер, подразумевая, что бургеры готовы 🍔, но вы не станете подскакивать как умалишённый, лишь только увидев на экране свою очередь. Вы уверены, что ваши бургеры 🍔 никто не утащит, ведь у вас свой номерок, а у других свой. +Потом кассир 💁 «говорит»: «Я закончил делать бургеры», — выводя ваш номер на табло, но вы не подпрыгиваете как сумасшедший в ту же секунду, как только номер сменился на ваш. Вы знаете, что ваши бургеры никто не украдёт, потому что у вас есть номер вашей очереди, а у других — их. -Поэтому вы подождёте, пока возлюбленная 😍 закончит рассказывать историю (закончите текущую работу ⏯ / задачу в обработке 🤓), -и мило улыбнувшись, скажете, что идёте забирать заказ ⏸. +Поэтому вы дожидаетесь, пока ваша возлюбленная закончит историю (завершится текущая работа ⏯ / выполняемая задача 🤓), мягко улыбаетесь и говорите, что идёте за бургерами ⏸. -И вот вы подходите к стойке 🔀, к первоначальной задаче, которая уже завершена ⏯, берёте бургеры 🍔, говорите спасибо и относите заказ за столик. На этом заканчивается этап / задача взаимодействия с кассой ⏹. -В свою очередь порождается задача "поедание бургеров" 🔀 ⏯, но предыдущая ("получение бургеров") завершена ⏹. +Затем вы идёте к стойке 🔀, к исходной задаче, которая теперь завершена ⏯, забираете бургеры, благодарите и несёте их к столику. На этом шаг/задача взаимодействия со стойкой завершён ⏹. Это, в свою очередь, создаёт новую задачу — «есть бургеры» 🔀 ⏯, но предыдущая «получить бургеры» — завершена ⏹. -### Параллельные бургеры +### Параллельные бургеры { #parallel-burgers } -Теперь представим, что вместо бургерной "Конкурентные бургеры" вы решили сходить в "Параллельные бургеры". +Теперь представим, что это не «Конкурентные бургеры», а «Параллельные бургеры». -И вот вы идёте со своей возлюбленной 😍 отведать параллельного фастфуда 🍔. +Вы идёте со своей возлюбленной за параллельным фастфудом. -Вы становитесь в очередь пока несколько (пусть будет 8) кассиров, которые по совместительству ещё и повары 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳, принимают заказы у посетителей перед вами. +Вы стоите в очереди, пока несколько (скажем, 8) кассиров, которые одновременно являются поварами, принимают заказы у людей перед вами. -При этом клиенты не отходят от стойки и ждут 🕙 получения еды, поскольку каждый -из 8 кассиров идёт на кухню готовить бургеры 🍔, а только потом принимает следующий заказ. +Все перед вами ждут, пока их бургеры будут готовы, не отходя от стойки, потому что каждый из 8 кассиров сразу идёт готовить бургер перед тем, как принять следующий заказ. -Наконец настаёт ваша очередь, и вы просите два самых навороченных бургера 🍔, один для дамы сердца 😍, а другой себе. + -Ни о чём не жалея, расплачиваетесь 💸. +Наконец ваша очередь: вы заказываете 2 очень «навороченных» бургера — для вашей возлюбленной и для себя. -И кассир уходит на кухню 👨‍🍳. +Вы платите 💸. -Вам приходится ждать перед стойкой 🕙, чтобы никто по случайности не забрал ваши бургеры 🍔, ведь никаких номерков у вас нет. + -Поскольку вы с возлюбленной 😍 хотите получить заказ вовремя 🕙, и следите за тем, чтобы никто не вклинился в очередь, -у вас не получается уделять должного внимание своей даме сердца 😞. +Кассир уходит на кухню. -Это "синхронная" работа, вы "синхронизированы" с кассиром/поваром 👨‍🍳. Приходится ждать 🕙 у стойки, -когда кассир/повар 👨‍🍳 закончит делать бургеры 🍔 и вручит вам заказ, иначе его случайно может забрать кто-то другой. +Вы ждёте, стоя у стойки 🕙, чтобы никто не забрал ваши бургеры раньше вас, так как никаких номерков нет. -Наконец кассир/повар 👨‍🍳 возвращается с бургерами 🍔 после невыносимо долгого ожидания 🕙 за стойкой. + -Вы скорее забираете заказ 🍔 и идёте с возлюбленной 😍 за столик. +Так как вы со своей возлюбленной заняты тем, чтобы никто не встал перед вами и не забрал ваши бургеры, как только они появятся, вы не можете уделить внимание своей возлюбленной. 😞 -Там вы просто едите эти бургеры, и на этом всё 🍔 ⏹. +Это «синхронная» работа, вы «синхронизированы» с кассиром/поваром 👨‍🍳. Вам нужно ждать 🕙 и находиться там в точный момент, когда кассир/повар 👨‍🍳 закончит бургеры и вручит их вам, иначе их может забрать кто-то другой. -Вам не особо удалось пообщаться, потому что большую часть времени 🕙 пришлось провести у кассы 😞. + ---- +Затем ваш кассир/повар 👨‍🍳 наконец возвращается с вашими бургерами, после долгого ожидания 🕙 у стойки. -В описанном сценарии вы компьютер / программа 🤖 с двумя исполнителями (вы и ваша возлюбленная 😍), -на протяжении долгого времени 🕙 вы оба уделяете всё внимание ⏯ задаче "ждать на кассе". + -В этом ресторане быстрого питания 8 исполнителей (кассиров/поваров) 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳. -Хотя в бургерной конкурентного типа было всего два (один кассир и один повар) 💁 👨‍🍳. +Вы берёте бургеры и идёте со своей возлюбленной к столику. -Несмотря на обилие работников, опыт в итоге получился не из лучших 😞. +Вы просто их съедаете — и всё. ⏹ + + + +Разговоров и флирта было немного, потому что большую часть времени вы ждали 🕙 у стойки. 😞 + +/// info | Информация + +Прекрасные иллюстрации от Ketrina Thompson. 🎨 + +/// --- -Так бы выглядел аналог истории про бургерную 🍔 в "параллельном" мире. +В этом сценарии «параллельных бургеров» вы — компьютер/программа 🤖 с двумя процессорами (вы и ваша возлюбленная), оба ждут 🕙 и уделяют внимание ⏯ тому, чтобы «ждать у стойки» 🕙 долгое время. + +В ресторане 8 процессоров (кассиров/поваров). Тогда как в «конкурентных бургерах» могло быть только 2 (один кассир и один повар). -Вот более реалистичный пример. Представьте себе банк. +И всё же финальный опыт — не самый лучший. 😞 -До недавних пор в большинстве банков было несколько кассиров 👨‍💼👨‍💼👨‍💼👨‍💼 и длинные очереди 🕙🕙🕙🕙🕙🕙🕙🕙. +--- -Каждый кассир обслуживал одного клиента, потом следующего 👨‍💼⏯. +Это была параллельная версия истории про бургеры. 🍔 -Нужно было долгое время 🕙 стоять перед окошком вместе со всеми, иначе пропустишь свою очередь. +Для более «жизненного» примера представьте банк. -Сомневаюсь, что у вас бы возникло желание прийти с возлюбленной 😍 в банк 🏦 оплачивать налоги. +До недавнего времени в большинстве банков было несколько кассиров 👨‍💼👨‍💼👨‍💼👨‍💼 и длинная очередь 🕙🕙🕙🕙🕙🕙🕙🕙. -### Выводы о бургерах +Все кассиры делают всю работу с одним клиентом за другим 👨‍💼⏯. -В нашей истории про поход в фастфуд за бургерами приходится много ждать 🕙, -поэтому имеет смысл организовать конкурентную систему ⏸🔀⏯. +И вам приходится долго 🕙 стоять в очереди, иначе вы потеряете свою очередь. -И то же самое с большинством веб-приложений. +Вы вряд ли захотите взять свою возлюбленную 😍 с собой, чтобы заняться делами в банке 🏦. -Пользователей очень много, но ваш сервер всё равно вынужден ждать 🕙 запросы по их слабому интернет-соединению. +### Вывод про бургеры { #burger-conclusion } -Потом снова ждать 🕙, пока вернётся ответ. +В этом сценарии «фастфуда с вашей возлюбленной», так как много ожидания 🕙, гораздо логичнее иметь конкурентную систему ⏸🔀⏯. - -Это ожидание 🕙 измеряется микросекундами, но если всё сложить, то набегает довольно много времени. +Так обстоит дело и с большинством веб-приложений. -Вот почему есть смысл использовать асинхронное ⏸🔀⏯ программирование при построении веб-API. +Очень много пользователей, но ваш сервер ждёт 🕙, пока их не самое хорошее соединение отправит их запросы. -Большинство популярных фреймворков (включая Flask и Django) создавались -до появления в Python новых возможностей асинхронного программирования. Поэтому -их можно разворачивать с поддержкой параллельного исполнения или асинхронного -программирования старого типа, которое не настолько эффективно. +А затем снова ждёт 🕙, пока отправятся ответы. -При том, что основная спецификация асинхронного взаимодействия Python с веб-сервером -(ASGI) -была разработана командой Django для внедрения поддержки веб-сокетов. +Это «ожидание» 🕙 измеряется микросекундами, но если всё сложить, то в сумме получается много ожидания. -Именно асинхронность сделала NodeJS таким популярным (несмотря на то, что он не параллельный), -и в этом преимущество Go как языка программирования. +Вот почему асинхронный ⏸🔀⏯ код очень уместен для веб-API. -И тот же уровень производительности даёт **FastAPI**. +Именно такая асинхронность сделала NodeJS популярным (хотя NodeJS — не параллельный), и это сильная сторона Go как языка программирования. -Поскольку можно использовать преимущества параллелизма и асинхронности вместе, -вы получаете производительность лучше, чем у большинства протестированных NodeJS фреймворков -и на уровне с Go, который является компилируемым языком близким к C (всё благодаря Starlette). +Того же уровня производительности вы получаете с **FastAPI**. -### Получается, конкурентность лучше параллелизма? +А так как можно одновременно использовать параллелизм и асинхронность, вы получаете производительность выше, чем у большинства протестированных фреймворков на NodeJS и на уровне Go, который — компилируемый язык, ближе к C (всё благодаря Starlette). -Нет! Мораль истории совсем не в этом. +### Конкурентность лучше параллелизма? { #is-concurrency-better-than-parallelism } -Конкурентность отличается от параллелизма. Она лучше в **конкретных** случаях, где много времени приходится на ожидание. -Вот почему она зачастую лучше параллелизма при разработке веб-приложений. Но это не значит, что конкурентность лучше в любых сценариях. +Нет! Мораль истории не в этом. -Давайте посмотрим с другой стороны, представьте такую картину: +Конкурентность отличается от параллелизма. И она лучше в **конкретных** сценариях, где много ожидания. Поэтому при разработке веб-приложений она обычно намного лучше параллелизма. Но не во всём. -> Вам нужно убраться в большом грязном доме. +Чтобы уравновесить это, представьте такую короткую историю: + +> Вам нужно убрать большой грязный дом. *Да, это вся история*. --- -Тут не нужно нигде ждать 🕙, просто есть куча работы в разных частях дома. +Здесь нигде нет ожидания 🕙, просто очень много работы в разных местах дома. -Можно организовать очередь как в примере с бургерами, сначала гостиная, потом кухня, -но это ни на что не повлияет, поскольку вы нигде не ждёте 🕙, а просто трёте да моете. +Можно организовать «очереди» как в примере с бургерами — сначала гостиная, потом кухня, — но так как вы ничего не ждёте 🕙, а просто убираете и убираете, очереди ни на что не повлияют. -И понадобится одинаковое количество времени с очередью (конкурентностью) и без неё, -и работы будет сделано тоже одинаковое количество. +На завершение уйдёт одинаковое время — с очередями (конкурентностью) и без них — и объём выполненной работы будет одинаковым. -Однако в случае, если бы вы могли привести 8 бывших кассиров/поваров, а ныне уборщиков 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳, -и каждый из них (вместе с вами) взялся бы за свой участок дома, -с такой помощью вы бы закончили намного быстрее, делая всю работу **параллельно**. +Но в этом случае, если бы вы могли привести 8 бывших кассиров/поваров, а теперь — уборщиков, и каждый из них (плюс вы) взял бы свою зону дома для уборки, вы могли бы сделать всю работу **параллельно**, с дополнительной помощью, и завершить гораздо быстрее. -В описанном сценарии каждый уборщик (включая вас) был бы исполнителем, занятым на своём участке работы. +В этом сценарии каждый уборщик (включая вас) был бы процессором, выполняющим свою часть работы. -И поскольку большую часть времени выполнения занимает реальная работа (а не ожидание), -а работу в компьютере делает ЦП, -такие задачи называют ограниченными производительностью процессора. +И так как основное время выполнения уходит на реальную работу (а не ожидание), а работу в компьютере выполняет CPU, такие задачи называют «ограниченными процессором» (CPU bound). --- -Ограничение по процессору проявляется в операциях, где требуется выполнять сложные математические вычисления. +Типичные примеры CPU-bound операций — те, которые требуют сложной математической обработки. Например: -* Обработка **звука** или **изображений**. -* **Компьютерное зрение**: изображение состоит из миллионов пикселей, в каждом пикселе 3 составляющих цвета, -обработка обычно требует проведения расчётов по всем пикселям сразу. -* **Машинное обучение**: здесь обычно требуется умножение "матриц" и "векторов". -Представьте гигантскую таблицу с числами в Экселе, и все их надо одновременно перемножить. -* **Глубокое обучение**: это область *машинного обучения*, поэтому сюда подходит то же описание. -Просто у вас будет не одна таблица в Экселе, а множество. В ряде случаев используется -специальный процессор для создания и / или использования построенных таким образом моделей. +* Обработка **аудио** или **изображений**. +* **Компьютерное зрение**: изображение состоит из миллионов пикселей, каждый пиксель имеет 3 значения/цвета; обычно требуется вычислить что-то для всех этих пикселей одновременно. +* **Машинное обучение**: обычно требует множества умножений «матриц» и «векторов». Представьте огромную таблицу с числами и умножение всех этих чисел «одновременно». +* **Глубокое обучение**: это подполе Машинного обучения, так что всё вышесказанное применимо. Просто это не одна таблица чисел, а их огромный набор, и во многих случаях вы используете специальный процессор, чтобы строить и/или использовать такие модели. -### Конкурентность + параллелизм: Веб + машинное обучение +### Конкурентность + параллелизм: Веб + Машинное обучение { #concurrency-parallelism-web-machine-learning } -**FastAPI** предоставляет возможности конкуретного программирования, -которое очень распространено в веб-разработке (именно этим славится NodeJS). +С **FastAPI** вы можете использовать преимущества конкурентности, что очень распространено в веб-разработке (это та же основная «фишка» NodeJS). -Кроме того вы сможете использовать все преимущества параллелизма и -многопроцессорности (когда несколько процессов работают параллельно), -если рабочая нагрузка предполагает **ограничение по процессору**, -как, например, в системах машинного обучения. +Но вы также можете использовать выгоды параллелизма и многопроцессности (когда несколько процессов работают параллельно) для рабочих нагрузок, **ограниченных процессором** (CPU bound), как в системах Машинного обучения. -Необходимо также отметить, что Python является главным языком в области -**дата-сайенс**, -машинного обучения и, особенно, глубокого обучения. Всё это делает FastAPI -отличным вариантом (среди многих других) для разработки веб-API и приложений -в области дата-сайенс / машинного обучения. +Плюс к этому простой факт, что Python — основной язык для **Data Science**, Машинного обучения и особенно Глубокого обучения, делает FastAPI очень хорошим выбором для веб-API и приложений в области Data Science / Машинного обучения (среди многих других). -Как добиться такого параллелизма в эксплуатации описано в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}. +Как добиться такого параллелизма в продакшн, см. раздел [Развёртывание](deployment/index.md){.internal-link target=_blank}. -## `async` и `await` +## `async` и `await` { #async-and-await } -В современных версиях Python разработка асинхронного кода реализована очень интуитивно. -Он выглядит как обычный "последовательный" код и самостоятельно выполняет "ожидание", когда это необходимо. +В современных версиях Python есть очень интуитивный способ определять асинхронный код. Это делает его похожим на обычный «последовательный» код, а «ожидание» выполняется за вас в нужные моменты. -Если некая операция требует ожидания перед тем, как вернуть результат, и -поддерживает современные возможности Python, код можно написать следующим образом: +Когда есть операция, которой нужно подождать перед тем, как вернуть результат, и она поддерживает эти новые возможности Python, вы можете написать так: ```Python burgers = await get_burgers(2) ``` -Главное здесь слово `await`. Оно сообщает интерпретатору, что необходимо дождаться ⏸ -пока `get_burgers(2)` закончит свои дела 🕙, и только после этого сохранить результат в `burgers`. -Зная это, Python может пока переключиться на выполнение других задач 🔀 ⏯ -(например получение следующего запроса). +Ключ здесь — `await`. Он говорит Python, что нужно подождать ⏸, пока `get_burgers(2)` закончит своё дело 🕙, прежде чем сохранять результат в `burgers`. Благодаря этому Python будет знать, что за это время можно заняться чем-то ещё 🔀 ⏯ (например, принять другой запрос). -Чтобы ключевое слово `await` сработало, оно должно находиться внутри функции, -которая поддерживает асинхронность. Для этого вам просто нужно объявить её как `async def`: +Чтобы `await` работал, он должен находиться внутри функции, которая поддерживает такую асинхронность. Для этого просто объявите её с `async def`: ```Python hl_lines="1" async def get_burgers(number: int): - # Готовим бургеры по специальному асинхронному рецепту + # Сделать что-то асинхронное, чтобы приготовить бургеры return burgers ``` @@ -355,26 +325,22 @@ async def get_burgers(number: int): ```Python hl_lines="2" # Это не асинхронный код def get_sequential_burgers(number: int): - # Готовим бургеры последовательно по шагам + # Сделать что-то последовательное, чтобы приготовить бургеры return burgers ``` -Объявление `async def` указывает интерпретатору, что внутри этой функции -следует ожидать выражений `await`, и что можно поставить выполнение такой функции на "паузу" ⏸ и -переключиться на другие задачи 🔀, с тем чтобы вернуться сюда позже. +С `async def` Python знает, что внутри этой функции нужно учитывать выражения `await` и что выполнение такой функции можно «приостанавливать» ⏸ и идти делать что-то ещё 🔀, чтобы потом вернуться. -Если вы хотите вызвать функцию с `async def`, вам нужно "ожидать" её. -Поэтому такое не сработает: +Когда вы хотите вызвать функцию, объявленную с `async def`, нужно её «ожидать». Поэтому вот так не сработает: ```Python -# Это не заработает, поскольку get_burgers объявлена с использованием async def +# Это не сработает, потому что get_burgers определена с: async def burgers = get_burgers(2) ``` --- -Если сторонняя библиотека требует вызывать её с ключевым словом `await`, -необходимо писать *функции обработки пути* с использованием `async def`, например: +Итак, если вы используете библиотеку, которую можно вызывать с `await`, вам нужно создать *функцию-обработчик пути*, которая её использует, с `async def`, например: ```Python hl_lines="2-3" @app.get('/burgers') @@ -383,129 +349,96 @@ async def read_burgers(): return burgers ``` -### Технические подробности +### Более технические подробности { #more-technical-details } + +Вы могли заметить, что `await` можно использовать только внутри функций, определённых с `async def`. -Как вы могли заметить, `await` может применяться только в функциях, объявленных с использованием `async def`. +Но при этом функции, определённые с `async def`, нужно «ожидать». Значит, функции с `async def` тоже можно вызывать только из функций, определённых с `async def`. - -Но выполнение такой функции необходимо "ожидать" с помощью `await`. -Это означает, что её можно вызвать только из другой функции, которая тоже объявлена с `async def`. +Так что же с «яйцом и курицей» — как вызвать первую `async` функцию? -Но как же тогда появилась первая курица? В смысле... как нам вызвать первую асинхронную функцию? +Если вы работаете с **FastAPI**, вам не о чем беспокоиться, потому что этой «первой» функцией будет ваша *функция-обработчик пути*, а FastAPI знает, как сделать всё правильно. -При работе с **FastAPI** просто не думайте об этом, потому что "первой" функцией является ваша *функция обработки пути*, -и дальше с этим разберётся FastAPI. +Но если вы хотите использовать `async` / `await` без FastAPI, вы тоже можете это сделать. -Кроме того, если хотите, вы можете использовать синтаксис `async` / `await` и без FastAPI. +### Пишите свой асинхронный код { #write-your-own-async-code } -### Пишите свой асинхронный код +Starlette (и **FastAPI**) основаны на AnyIO, что делает их совместимыми и со стандартной библиотекой Python asyncio, и с Trio. -Starlette (и **FastAPI**) основаны на AnyIO, что делает их совместимыми как со стандартной библиотекой asyncio в Python, так и с Trio. +В частности, вы можете напрямую использовать AnyIO для продвинутых сценариев конкурентности, где в вашем коде нужны более сложные паттерны. -В частности, вы можете напрямую использовать AnyIO в тех проектах, где требуется более сложная логика работы с конкурентностью. +И даже если вы не используете FastAPI, вы можете писать свои асинхронные приложения с AnyIO, чтобы они были максимально совместимыми и получали его преимущества (например, *структурную конкурентность*). -Даже если вы не используете FastAPI, вы можете писать асинхронные приложения с помощью AnyIO, чтобы они были максимально совместимыми и получали его преимущества (например *структурную конкурентность*). +Я создал ещё одну библиотеку поверх AnyIO, тонкий слой, чтобы немного улучшить аннотации типов и получить более качественное **автозавершение**, **ошибки прямо в редакторе** и т.д. Там также есть дружелюбное введение и руководство, чтобы помочь вам **понять** и писать **свой собственный асинхронный код**: Asyncer. Она особенно полезна, если вам нужно **комбинировать асинхронный код с обычным** (блокирующим/синхронным) кодом. -### Другие виды асинхронного программирования +### Другие формы асинхронного кода { #other-forms-of-asynchronous-code } -Стиль написания кода с `async` и `await` появился в языке Python относительно недавно. +Такой стиль использования `async` и `await` относительно новый в языке. -Но он сильно облегчает работу с асинхронным кодом. +Но он сильно упрощает работу с асинхронным кодом. -Ровно такой же синтаксис (ну или почти такой же) недавно был включён в современные версии JavaScript (в браузере и NodeJS). +Такой же (или почти такой же) синтаксис недавно появился в современных версиях JavaScript (в браузере и NodeJS). -До этого поддержка асинхронного кода была реализована намного сложнее, и его было труднее воспринимать. +До этого работа с асинхронным кодом была заметно сложнее и труднее для понимания. -В предыдущих версиях Python для этого использовались потоки или Gevent. Но такой код намного сложнее понимать, отлаживать и мысленно представлять. +В предыдущих версиях Python можно было использовать потоки или Gevent. Но такой код гораздо сложнее понимать, отлаживать и держать в голове. -Что касается JavaScript (в браузере и NodeJS), раньше там использовали для этой цели -"обратные вызовы". Что выливалось в -"ад обратных вызовов". +В прежних версиях NodeJS/браузерного JavaScript вы бы использовали «callbacks» (обратные вызовы), что приводит к «callback hell» (ад обратных вызовов). -## Сопрограммы +## Сопрограммы { #coroutines } -**Корути́на** (или же сопрограмма) — это крутое словечко для именования той сущности, -которую возвращает функция `async def`. Python знает, что её можно запустить, как и обычную функцию, -но кроме того сопрограмму можно поставить на паузу ⏸ в том месте, где встретится слово `await`. +**Сопрограмма** (coroutine) — это просто «навороченное» слово для того, что возвращает функция `async def`. Python знает, что это похоже на функцию: её можно запустить, она когда-нибудь завершится, но её выполнение может приостанавливаться ⏸ внутри, когда встречается `await`. -Всю функциональность асинхронного программирования с использованием `async` и `await` -часто обобщают словом "корутины". Они аналогичны "горутинам", ключевой особенности -языка Go. +Часто всю функциональность использования асинхронного кода с `async` и `await` кратко называют «сопрограммами». Это сопоставимо с ключевой особенностью Go — «goroutines». -## Заключение +## Заключение { #conclusion } -В самом начале была такая фраза: +Вернёмся к той же фразе: -> Современные версии Python поддерживают разработку так называемого -**"асинхронного кода"** посредством написания **"сопрограмм"** с использованием -синтаксиса **`async` и `await`**. +> Современные версии Python поддерживают **«асинхронный код»** с помощью **«сопрограмм»** (coroutines) и синтаксиса **`async` и `await`**. -Теперь всё должно звучать понятнее. ✨ +Теперь это должно звучать понятнее. ✨ -На этом основана работа FastAPI (посредством Starlette), и именно это -обеспечивает его высокую производительность. +Именно это «движет» FastAPI (через Starlette) и обеспечивает столь впечатляющую производительность. -## Очень технические подробности +## Очень технические подробности { #very-technical-details } -/// warning +/// warning | Предупреждение -Этот раздел читать не обязательно. +Скорее всего, этот раздел можно пропустить. -Здесь приводятся подробности внутреннего устройства **FastAPI**. +Здесь — очень технические подробности о том, как **FastAPI** работает «под капотом». -Но если вы обладаете техническими знаниями (корутины, потоки, блокировка и т. д.) -и вам интересно, как FastAPI обрабатывает `async def` в отличие от обычных `def`, -читайте дальше. +Если у вас есть достаточно технических знаний (сопрограммы, потоки, блокировки и т.д.) и вам интересно, как FastAPI обрабатывает `async def` по сравнению с обычным `def`, — вперёд. /// -### Функции обработки пути +### Функции-обработчики пути { #path-operation-functions } -Когда вы объявляете *функцию обработки пути* обычным образом с ключевым словом `def` -вместо `async def`, FastAPI ожидает её выполнения, запустив функцию во внешнем -пуле потоков, а не напрямую (это бы заблокировало сервер). +Когда вы объявляете *функцию-обработчик пути* обычным `def` вместо `async def`, она запускается во внешнем пуле потоков, который затем «ожидается», вместо прямого вызова (прямой вызов заблокировал бы сервер). -Если ранее вы использовали другой асинхронный фреймворк, который работает иначе, -и привыкли объявлять простые вычислительные *функции* через `def` ради -незначительного прироста скорости (порядка 100 наносекунд), обратите внимание, -что с **FastAPI** вы получите противоположный эффект. В таком случае больше подходит -`async def`, если только *функция обработки пути* не использует код, приводящий -к блокировке I/O. - +Если вы пришли из другого async-фреймворка, который работает иначе, и привыкли объявлять тривиальные *функции-обработчики пути*, выполняющие только вычисления, через простой `def` ради крошечной выгоды в производительности (около 100 наносекунд), обратите внимание: в **FastAPI** эффект будет противоположным. В таких случаях лучше использовать `async def`, если только ваши *функции-обработчики пути* не используют код, выполняющий блокирующий I/O. - -Но в любом случае велика вероятность, что **FastAPI** [окажется быстрее](index.md#_11){.internal-link target=_blank} -другого фреймворка (или хотя бы на уровне с ним). +Тем не менее, в обоих случаях велика вероятность, что **FastAPI** [всё равно будет быстрее](index.md#performance){.internal-link target=_blank} (или как минимум сопоставим) с вашим предыдущим фреймворком. -### Зависимости +### Зависимости { #dependencies } -То же относится к зависимостям. Если это обычная функция `def`, а не `async def`, -она запускается во внешнем пуле потоков. +То же относится к [зависимостям](tutorial/dependencies/index.md){.internal-link target=_blank}. Если зависимость — это обычная функция `def`, а не `async def`, она запускается во внешнем пуле потоков. -### Подзависимости +### Подзависимости { #sub-dependencies } -Вы можете объявить множество ссылающихся друг на друга зависимостей и подзависимостей -(в виде параметров при определении функции). Какие-то будут созданы с помощью `async def`, -другие обычным образом через `def`, и такая схема вполне работоспособна. Функции, -объявленные с помощью `def` будут запускаться на внешнем потоке (из пула), -а не с помощью `await`. +У вас может быть несколько зависимостей и [подзависимостей](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank}, которые требуют друг друга (в виде параметров определений функций): часть из них может быть объявлена с `async def`, а часть — обычным `def`. Всё будет работать, а те, что объявлены обычным `def`, будут вызываться во внешнем потоке (из пула), а не «ожидаться». -### Другие служебные функции +### Другие служебные функции { #other-utility-functions } -Любые другие служебные функции, которые вы вызываете напрямую, можно объявлять -с использованием `def` или `async def`. FastAPI не будет влиять на то, как вы -их запускаете. +Любые другие служебные функции, которые вы вызываете напрямую, можно объявлять обычным `def` или `async def`, и FastAPI не будет влиять на то, как вы их вызываете. -Этим они отличаются от функций, которые FastAPI вызывает самостоятельно: -*функции обработки пути* и зависимости. +В отличие от функций, которые FastAPI вызывает за вас: *функции-обработчики пути* и зависимости. -Если служебная функция объявлена с помощью `def`, она будет вызвана напрямую -(как вы и написали в коде), а не в отдельном потоке. Если же она объявлена с -помощью `async def`, её вызов должен осуществляться с ожиданием через `await`. +Если служебная функция — обычная функция с `def`, она будет вызвана напрямую (как вы и пишете в коде), не в пуле потоков; если функция объявлена с `async def`, тогда при её вызове в вашем коде вы должны использовать `await`. --- - -Ещё раз повторим, что все эти технические подробности полезны, только если вы специально их искали. +Снова: это очень технические подробности, полезные, вероятно, только если вы целенаправленно их ищете. -В противном случае просто ознакомьтесь с основными принципами в разделе выше: Нет времени?. +Иначе вам достаточно руководствоваться рекомендациями из раздела выше: Нет времени?. diff --git a/docs/ru/docs/benchmarks.md b/docs/ru/docs/benchmarks.md index 259dca8e67..612b39f708 100644 --- a/docs/ru/docs/benchmarks.md +++ b/docs/ru/docs/benchmarks.md @@ -1,37 +1,34 @@ -# Замеры производительности +# Бенчмарки (тесты производительности) { #benchmarks } -Независимые тесты производительности приложений от TechEmpower показывают, что **FastAPI** под управлением Uvicorn один из самых быстрых Python-фреймворков и уступает только Starlette и Uvicorn (которые используются в FastAPI). (*) +Независимые бенчмарки TechEmpower показывают, что приложения **FastAPI** под управлением Uvicorn — одни из самых быстрых Python‑фреймворков, уступающие только Starlette и самому Uvicorn (используются внутри FastAPI). -Но при просмотре и сравнении замеров производительности следует иметь в виду нижеописанное. +Но при просмотре бенчмарков и сравнений следует иметь в виду следующее. -## Замеры производительности и скорости +## Бенчмарки и скорость { #benchmarks-and-speed } -В подобных тестах часто можно увидеть, что инструменты разного типа сравнивают друг с другом, как аналогичные. +При проверке бенчмарков часто можно увидеть, что инструменты разных типов сравнивают как эквивалентные. -В частности, сравнивают вместе Uvicorn, Starlette и FastAPI (среди многих других инструментов). +В частности, часто сравнивают вместе Uvicorn, Starlette и FastAPI (среди многих других инструментов). -Чем проще проблема, которую решает инструмент, тем выше его производительность. И большинство тестов не проверяют дополнительные функции, предоставляемые инструментом. +Чем проще задача, которую решает инструмент, тем выше его производительность. И большинство бенчмарков не тестируют дополнительные возможности, предоставляемые инструментом. -Иерархия инструментов имеет следующий вид: +Иерархия выглядит так: * **Uvicorn**: ASGI-сервер - * **Starlette** (использует Uvicorn): веб-микрофреймворк - * **FastAPI** (использует Starlette): API-микрофреймворк с дополнительными функциями для создания API, с валидацией данных и т.д. + * **Starlette**: (использует Uvicorn) веб-микрофреймворк + * **FastAPI**: (использует Starlette) API-микрофреймворк с рядом дополнительных возможностей для создания API, включая валидацию данных и т. п. * **Uvicorn**: - * Будет иметь наилучшую производительность, так как не имеет большого количества дополнительного кода, кроме самого сервера. - * Вы не будете писать приложение на Uvicorn напрямую. Это означало бы, что Ваш код должен включать как минимум весь - код, предоставляемый Starlette (или **FastAPI**). И если Вы так сделаете, то в конечном итоге Ваше приложение будет иметь те же накладные расходы, что и при использовании фреймворка, минимизирующего код Вашего приложения и Ваши ошибки. - * Uvicorn подлежит сравнению с Daphne, Hypercorn, uWSGI и другими веб-серверами. - + * Будет иметь наилучшую производительность, так как помимо самого сервера у него немного дополнительного кода. + * Вы не будете писать приложение непосредственно на Uvicorn. Это означало бы, что Ваш код должен включать как минимум весь код, предоставляемый Starlette (или **FastAPI**). И если Вы так сделаете, то в конечном итоге Ваше приложение будет иметь те же накладные расходы, что и при использовании фреймворка, минимизирующего код Вашего приложения и Ваши ошибки. + * Если Вы сравниваете Uvicorn, сравнивайте его с Daphne, Hypercorn, uWSGI и т. д. — серверами приложений. * **Starlette**: - * Будет уступать Uvicorn по производительности. Фактически Starlette управляется Uvicorn и из-за выполнения большего количества кода он не может быть быстрее, чем Uvicorn. - * Зато он предоставляет Вам инструменты для создания простых веб-приложений с обработкой маршрутов URL и т.д. - * Starlette следует сравнивать с Sanic, Flask, Django и другими веб-фреймворками (или микрофреймворками). - + * Будет на следующем месте по производительности после Uvicorn. Фактически Starlette запускается под управлением Uvicorn, поэтому он может быть только «медленнее» Uvicorn из‑за выполнения большего объёма кода. + * Зато он предоставляет Вам инструменты для создания простых веб‑приложений с маршрутизацией по путям и т. п. + * Если Вы сравниваете Starlette, сравнивайте его с Sanic, Flask, Django и т. д. — веб‑фреймворками (или микрофреймворками). * **FastAPI**: - * Так же как Starlette использует Uvicorn и не может быть быстрее него, **FastAPI** использует Starlette, то есть он не может быть быстрее Starlette. - * FastAPI предоставляет больше возможностей поверх Starlette, которые наверняка Вам понадобятся при создании API, такие как проверка данных и сериализация. В довесок Вы ещё и получаете автоматическую документацию (автоматическая документация даже не увеличивает накладные расходы при работе приложения, так как она создается при запуске). - * Если Вы не используете FastAPI, а используете Starlette напрямую (или другой инструмент вроде Sanic, Flask, Responder и т.д.), Вам пришлось бы самостоятельно реализовать валидацию и сериализацию данных. То есть, в итоге, Ваше приложение имело бы такие же накладные расходы, как если бы оно было создано с использованием FastAPI. И во многих случаях валидация и сериализация данных представляют собой самый большой объём кода, написанного в приложениях. - * Таким образом, используя FastAPI Вы потратите меньше времени на разработку, уменьшите количество ошибок, строк кода и, вероятно, получите ту же производительность (или лучше), как и если бы не использовали его (поскольку Вам пришлось бы реализовать все его возможности в своем коде). - * FastAPI должно сравнивать с фреймворками веб-приложений (или наборами инструментов), которые обеспечивают валидацию и сериализацию данных, а также предоставляют автоматическую документацию, такими как Flask-apispec, NestJS, Molten и им подобные. + * Точно так же, как Starlette использует Uvicorn и не может быть быстрее него, **FastAPI** использует Starlette, поэтому не может быть быстрее его. + * FastAPI предоставляет больше возможностей поверх Starlette — те, которые почти всегда нужны при создании API, такие как валидация и сериализация данных. В довесок Вы ещё и получаете автоматическую документацию (автоматическая документация даже не увеличивает накладные расходы при работе приложения, так как она создаётся при запуске). + * Если бы Вы не использовали FastAPI, а использовали Starlette напрямую (или другой инструмент вроде Sanic, Flask, Responder и т. д.), Вам пришлось бы самостоятельно реализовать валидацию и сериализацию данных. То есть, в итоге, Ваше приложение имело бы такие же накладные расходы, как если бы оно было создано с использованием FastAPI. И во многих случаях валидация и сериализация данных представляют собой самый большой объём кода, написанного в приложениях. + * Таким образом, используя FastAPI, Вы экономите время разработки, уменьшаете количество ошибок, строк кода и, вероятно, получите ту же производительность (или лучше), как и если бы не использовали его (поскольку Вам пришлось бы реализовать все его возможности в своём коде). + * Если Вы сравниваете FastAPI, сравнивайте его с фреймворком веб‑приложений (или набором инструментов), который обеспечивает валидацию данных, сериализацию и документацию, такими как Flask-apispec, NestJS, Molten и им подобные. Фреймворки с интегрированной автоматической валидацией данных, сериализацией и документацией. diff --git a/docs/ru/docs/deployment/concepts.md b/docs/ru/docs/deployment/concepts.md index acfa1f4fe6..207d1604d7 100644 --- a/docs/ru/docs/deployment/concepts.md +++ b/docs/ru/docs/deployment/concepts.md @@ -1,323 +1,321 @@ -# Концепции развёртывания +# Концепции развёртывания { #deployments-concepts } -Существует несколько концепций, применяемых для развёртывания приложений **FastAPI**, равно как и для любых других типов веб-приложений, среди которых вы можете выбрать **наиболее подходящий** способ. +При развёртывании приложения **FastAPI** (и вообще любого веб‑API) есть несколько концепций, о которых стоит думать — с их помощью можно выбрать **наиболее подходящий** способ **развёртывания вашего приложения**. -Самые важные из них: +Некоторые из важных концепций: -* Использование более безопасного протокола HTTPS -* Настройки запуска приложения -* Перезагрузка приложения -* Запуск нескольких экземпляров приложения -* Управление памятью -* Использование перечисленных функций перед запуском приложения. +* Безопасность — HTTPS +* Запуск при старте +* Перезапуски +* Репликация (количество запущенных процессов) +* Память +* Предварительные шаги перед запуском -Рассмотрим ниже влияние каждого из них на процесс **развёртывания**. +Посмотрим, как они влияют на **развёртывания**. -Наша конечная цель - **обслуживать клиентов вашего API безопасно** и **бесперебойно**, с максимально эффективным использованием **вычислительных ресурсов** (например, удалённых серверов/виртуальных машин). 🚀 +В конечном итоге цель — **обслуживать клиентов вашего API** безопасно, **избегать перебоев** и максимально эффективно использовать **вычислительные ресурсы** (например, удалённые серверы/виртуальные машины). 🚀 -Здесь я немного расскажу Вам об этих **концепциях** и надеюсь, что у вас сложится **интуитивное понимание**, какой способ выбрать при развертывании вашего API в различных окружениях, возможно, даже **ещё не существующих**. +Здесь я немного расскажу о этих **концепциях**, чтобы у вас появилась **интуиция**, как развёртывать ваш API в разных окружениях, возможно даже в **будущих**, которых ещё не существует. -Ознакомившись с этими концепциями, вы сможете **оценить и выбрать** лучший способ развёртывании **Вашего API**. +Учитывая эти концепции, вы сможете **оценить и спроектировать** лучший способ развёртывания **своих API**. -В последующих главах я предоставлю Вам **конкретные рецепты** развёртывания приложения FastAPI. +В следующих главах я дам более **конкретные рецепты** по развёртыванию приложений FastAPI. -А сейчас давайте остановимся на важных **идеях этих концепций**. Эти идеи можно также применить и к другим типам веб-приложений. 💡 +А пока давайте разберём важные **идеи**. Эти концепции применимы и к другим типам веб‑API. 💡 -## Использование более безопасного протокола HTTPS +## Безопасность — HTTPS { #security-https } -В [предыдущей главе об HTTPS](https.md){.internal-link target=_blank} мы рассмотрели, как HTTPS обеспечивает шифрование для вашего API. +В [предыдущей главе про HTTPS](https.md){.internal-link target=_blank} мы разобрались, как HTTPS обеспечивает шифрование для вашего API. -Также мы заметили, что обычно для работы с HTTPS вашему приложению нужен **дополнительный** компонент - **прокси-сервер завершения работы TLS**. +Также мы увидели, что HTTPS обычно обеспечивает компонент, **внешний** по отношению к серверу вашего приложения — **TLS Termination Proxy**. -И если прокси-сервер не умеет сам **обновлять сертификаты HTTPS**, то нужен ещё один компонент для этого действия. +И должен быть компонент, отвечающий за **обновление HTTPS‑сертификатов** — это может быть тот же самый компонент или отдельный. -### Примеры инструментов для работы с HTTPS +### Примеры инструментов для HTTPS { #example-tools-for-https } -Вот некоторые инструменты, которые вы можете применять как прокси-серверы: +Некоторые инструменты, которые можно использовать как TLS Termination Proxy: * Traefik - * С автоматическим обновлением сертификатов ✨ + * Автоматически обновляет сертификаты ✨ * Caddy - * С автоматическим обновлением сертификатов ✨ + * Автоматически обновляет сертификаты ✨ * Nginx - * С дополнительным компонентом типа Certbot для обновления сертификатов + * С внешним компонентом (например, Certbot) для обновления сертификатов * HAProxy - * С дополнительным компонентом типа Certbot для обновления сертификатов -* Kubernetes с Ingress Controller похожим на Nginx - * С дополнительным компонентом типа cert-manager для обновления сертификатов -* Использование услуг облачного провайдера (читайте ниже 👇) + * С внешним компонентом (например, Certbot) для обновления сертификатов +* Kubernetes с Ingress Controller (например, Nginx) + * С внешним компонентом (например, cert-manager) для обновления сертификатов +* Обрабатывается внутри облачного провайдера как часть его услуг (см. ниже 👇) -В последнем варианте вы можете воспользоваться услугами **облачного сервиса**, который сделает большую часть работы, включая настройку HTTPS. Это может наложить дополнительные ограничения или потребовать дополнительную плату и т.п. Зато Вам не понадобится самостоятельно заниматься настройками прокси-сервера. +Другой вариант — использовать **облачный сервис**, который возьмёт на себя больше задач, включая настройку HTTPS. Там могут быть ограничения или дополнительная стоимость и т.п., но в таком случае вам не придётся самим настраивать TLS Termination Proxy. -В дальнейшем я покажу Вам некоторые конкретные примеры их применения. +В следующих главах я покажу конкретные примеры. --- -Следующие концепции рассматривают применение программы, запускающей Ваш API (такой как Uvicorn). +Далее рассмотрим концепции, связанные с программой, которая запускает ваш реальный API (например, Uvicorn). -## Программа и процесс +## Программа и процесс { #program-and-process } -Мы часто будем встречать слова **процесс** и **программа**, потому следует уяснить отличия между ними. +Мы часто будем говорить о работающем "**процессе**", поэтому полезно чётко понимать, что это значит и чем отличается от "**программы**". -### Что такое программа +### Что такое программа { #what-is-a-program } -Термином **программа** обычно описывают множество вещей: +Словом **программа** обычно называют разные вещи: -* **Код**, который вы написали, в нашем случае **Python-файлы**. -* **Файл**, который может быть **исполнен** операционной системой, например `python`, `python.exe` или `uvicorn`. -* Конкретная программа, **запущенная** операционной системой и использующая центральный процессор и память. В таком случае это также называется **процесс**. +* **Код**, который вы пишете, то есть **Python‑файлы**. +* **Файл**, который может быть **запущен** операционной системой, например: `python`, `python.exe` или `uvicorn`. +* Конкретную программу в момент, когда она **работает** в операционной системе, используя CPU и память. Это также называют **процессом**. -### Что такое процесс +### Что такое процесс { #what-is-a-process } -Термин **процесс** имеет более узкое толкование, подразумевая что-то, запущенное операционной системой (как в последнем пункте из вышестоящего абзаца): +Слово **процесс** обычно используют более конкретно — только для того, что реально выполняется в операционной системе (как в последнем пункте выше): -* Конкретная программа, **запущенная** операционной системой. - * Это не имеет отношения к какому-либо файлу или коду, но нечто **определённое**, управляемое и **выполняемое** операционной системой. -* Любая программа, любой код, **могут делать что-то** только когда они **выполняются**. То есть, когда являются **работающим процессом**. -* Процесс может быть **прерван** (или "убит") Вами или вашей операционной системой. В результате чего он перестанет исполняться и **не будет продолжать делать что-либо**. -* Каждое приложение, которое вы запустили на своём компьютере, каждая программа, каждое "окно" запускает какой-то процесс. И обычно на включенном компьютере **одновременно** запущено множество процессов. -* И **одна программа** может запустить **несколько параллельных процессов**. +* Конкретная программа в момент, когда она **запущена** в операционной системе. + * Речь не о файле и не о коде, а **конкретно** о том, что **исполняется** и управляется операционной системой. +* Любая программа, любой код **могут что‑то делать** только когда **исполняются**, то есть когда есть **работающий процесс**. +* Процесс можно **завершить** (или «убить») вами или операционной системой. В этот момент он перестаёт выполняться и **больше ничего делать не может**. +* У каждого запущенного приложения на вашем компьютере есть свой процесс; у каждой программы, у каждого окна и т.д. Обычно одновременно **работает много процессов**, пока компьютер включён. +* Могут **одновременно** работать **несколько процессов** одной и той же **программы**. -Если вы заглянете в "диспетчер задач" или "системный монитор" (или аналогичные инструменты) вашей операционной системы, то увидите множество работающих процессов. +Если вы посмотрите «диспетчер задач» или «системный монитор» (или аналогичные инструменты) в вашей операционной системе, то увидите множество работающих процессов. -Вполне вероятно, что вы увидите несколько процессов с одним и тем же названием браузерной программы (Firefox, Chrome, Edge и т. Д.). Обычно браузеры запускают один процесс на вкладку и вдобавок некоторые дополнительные процессы. +Например, вы, скорее всего, увидите несколько процессов одного и того же браузера (Firefox, Chrome, Edge и т.д.). Обычно браузеры запускают один процесс на вкладку плюс дополнительные процессы. --- -Теперь, когда нам известна разница между **процессом** и **программой**, давайте продолжим обсуждение развёртывания. +Теперь, когда мы понимаем разницу между **процессом** и **программой**, продолжим разговор о развёртываниях. -## Настройки запуска приложения +## Запуск при старте { #running-on-startup } -В большинстве случаев когда вы создаёте веб-приложение, то желаете, чтоб оно **работало постоянно** и непрерывно, предоставляя клиентам доступ в любое время. Хотя иногда у вас могут быть причины, чтоб оно запускалось только при определённых условиях. +В большинстве случаев, создавая веб‑API, вы хотите, чтобы он **работал постоянно**, без перерывов, чтобы клиенты всегда могли к нему обратиться. Разве что у вас есть особые причины запускать его только при определённых условиях, но обычно вы хотите, чтобы он был постоянно запущен и **доступен**. -### Удалённый сервер +### На удалённом сервере { #in-a-remote-server } -Когда вы настраиваете удалённый сервер (облачный сервер, виртуальную машину и т.п.), самое простое, что можно сделать, запустить Uvicorn (или его аналог) вручную, как вы делаете при локальной разработке. +Когда вы настраиваете удалённый сервер (облачный сервер, виртуальную машину и т.п.), самый простой вариант — вручную использовать `fastapi run` (он использует Uvicorn) или что‑то похожее, как вы делаете при локальной разработке. -Это рабочий способ и он полезен **во время разработки**. +Это будет работать и полезно **во время разработки**. -Но если вы потеряете соединение с сервером, то не сможете отслеживать - работает ли всё ещё **запущенный Вами процесс**. +Но если соединение с сервером прервётся, **запущенный процесс**, скорее всего, завершится. -И если сервер перезагрузится (например, после обновления или каких-то действий облачного провайдера), вы скорее всего **этого не заметите**, чтобы снова запустить процесс вручную. Вследствие этого Ваш API останется мёртвым. 😱 +А если сервер перезагрузится (например, после обновлений или миграций у облачного провайдера), вы, вероятно, **даже не заметите этого**. Из‑за этого вы не узнаете, что нужно вручную перезапустить процесс — и ваш API просто будет «мёртв». 😱 -### Автоматический запуск программ +### Автоматический запуск при старте { #run-automatically-on-startup } -Вероятно вы захотите, чтоб Ваша серверная программа (такая, как Uvicorn) стартовала автоматически при включении сервера, без **человеческого вмешательства** и всегда могла управлять Вашим API (так как Uvicorn запускает приложение FastAPI). +Как правило, вы захотите, чтобы серверная программа (например, Uvicorn) запускалась автоматически при старте сервера и без **участия человека**, чтобы всегда был процесс, запущенный с вашим API (например, Uvicorn, запускающий ваше приложение FastAPI). -### Отдельная программа +### Отдельная программа { #separate-program } -Для этого у обычно используют отдельную программу, которая следит за тем, чтобы Ваши приложения запускались при включении сервера. Такой подход гарантирует, что другие компоненты или приложения также будут запущены, например, база данных +Чтобы этого добиться, обычно используют **отдельную программу**, которая гарантирует запуск вашего приложения при старте. Во многих случаях она также запускает и другие компоненты/приложения, например базу данных. -### Примеры инструментов, управляющих запуском программ +### Примеры инструментов для запуска при старте { #example-tools-to-run-at-startup } -Вот несколько примеров, которые могут справиться с такой задачей: +Примеры инструментов, которые могут с этим справиться: * Docker * Kubernetes * Docker Compose -* Docker в режиме Swarm +* Docker в режиме Swarm (Swarm Mode) * Systemd * Supervisor -* Использование услуг облачного провайдера +* Обработка внутри облачного провайдера как часть его услуг * Прочие... -Я покажу Вам некоторые примеры их использования в следующих главах. +Более конкретные примеры будут в следующих главах. -## Перезапуск +## Перезапуски { #restarts } -Вы, вероятно, также захотите, чтоб ваше приложение **перезапускалось**, если в нём произошёл сбой. +Подобно тому как вы обеспечиваете запуск приложения при старте, вы, вероятно, захотите обеспечить его **перезапуск** после сбоев. -### Мы ошибаемся +### Мы ошибаемся { #we-make-mistakes } -Все люди совершают **ошибки**. Программное обеспечение почти *всегда* содержит **баги** спрятавшиеся в разных местах. 🐛 +Мы, люди, постоянно совершаем **ошибки**. В программном обеспечении почти всегда есть **баги**, скрытые в разных местах. 🐛 -И мы, будучи разработчиками, продолжаем улучшать код, когда обнаруживаем в нём баги или добавляем новый функционал (возможно, добавляя при этом баги 😅). +И мы, как разработчики, продолжаем улучшать код — находим баги и добавляем новые возможности (иногда добавляя новые баги 😅). -### Небольшие ошибки обрабатываются автоматически +### Небольшие ошибки обрабатываются автоматически { #small-errors-automatically-handled } -Когда вы создаёте свои API на основе FastAPI и допускаете в коде ошибку, то FastAPI обычно остановит её распространение внутри одного запроса, при обработке которого она возникла. 🛡 +Создавая веб‑API с FastAPI, если в нашем коде возникает ошибка, FastAPI обычно «локализует» её в пределах одного запроса, который эту ошибку вызвал. 🛡 -Клиент получит ошибку **500 Internal Server Error** в ответ на свой запрос, но приложение не сломается и будет продолжать работать с последующими запросами. +Клиент получит **500 Internal Server Error** для этого запроса, но приложение продолжит работать для последующих запросов, а не «упадёт» целиком. -### Большие ошибки - Падение приложений +### Большие ошибки — падения { #bigger-errors-crashes } -Тем не менее, может случиться так, что ошибка вызовет **сбой всего приложения** или даже сбой в Uvicorn, а то и в самом Python. 💥 +Тем не менее возможны случаи, когда код **роняет всё приложение**, приводя к сбою Uvicorn и Python. 💥 -Но мы всё ещё хотим, чтобы приложение **продолжало работать** несмотря на эту единственную ошибку, обрабатывая, как минимум, запросы к *операциям пути* не имеющим ошибок. +И вы, скорее всего, не захотите, чтобы приложение оставалось «мёртвым» из‑за ошибки в одном месте — вы захотите, чтобы оно **продолжало работать** хотя бы для *операций пути*, которые не сломаны. -### Перезапуск после падения +### Перезапуск после падения { #restart-after-crash } -Для случаев, когда ошибки приводят к сбою в запущенном **процессе**, Вам понадобится добавить компонент, который **перезапустит** процесс хотя бы пару раз... +В случаях действительно серьёзных ошибок, которые роняют работающий **процесс**, вам понадобится внешний компонент, отвечающий за **перезапуск** процесса, как минимум пару раз... -/// tip | Заметка +/// tip | Совет -... Если приложение падает сразу же после запуска, вероятно бесполезно его бесконечно перезапускать. Но полагаю, вы заметите такое поведение во время разработки или, по крайней мере, сразу после развёртывания. +...Хотя если приложение **падает сразу же**, вероятно, нет смысла перезапускать его бесконечно. Но такие случаи вы, скорее всего, заметите во время разработки или как минимум сразу после развёртывания. -Так что давайте сосредоточимся на конкретных случаях, когда приложение может полностью выйти из строя, но всё ещё есть смысл его запустить заново. +Давайте сосредоточимся на основных сценариях, когда в каких‑то конкретных ситуациях **в будущем** приложение может падать целиком, и при этом имеет смысл его перезапускать. /// -Возможно вы захотите, чтоб был некий **внешний компонент**, ответственный за перезапуск вашего приложения даже если уже не работает Uvicorn или Python. То есть ничего из того, что написано в вашем коде внутри приложения, не может быть выполнено в принципе. +Скорее всего, вы захотите, чтобы перезапуском вашего приложения занимался **внешний компонент**, потому что к тому моменту Uvicorn и Python уже упали, и внутри того же кода вашего приложения сделать уже ничего нельзя. -### Примеры инструментов для автоматического перезапуска +### Примеры инструментов для автоматического перезапуска { #example-tools-to-restart-automatically } -В большинстве случаев инструменты **запускающие программы при старте сервера** умеют **перезапускать** эти программы. +В большинстве случаев тот же инструмент, который **запускает программу при старте**, умеет обрабатывать и автоматические **перезапуски**. -В качестве примера можно взять те же: +Например, это может быть: * Docker * Kubernetes * Docker Compose -* Docker в режиме Swarm +* Docker в режиме Swarm (Swarm Mode) * Systemd * Supervisor -* Использование услуг облачного провайдера +* Обработка внутри облачного провайдера как часть его услуг * Прочие... -## Запуск нескольких экземпляров приложения (Репликация) - Процессы и память +## Репликация — процессы и память { #replication-processes-and-memory } -Приложение FastAPI, управляемое серверной программой (такой как Uvicorn), запускается как **один процесс** и может обслуживать множество клиентов одновременно. +В приложении FastAPI, используя серверную программу (например, команду `fastapi`, которая запускает Uvicorn), запуск в **одном процессе** уже позволяет обслуживать нескольких клиентов одновременно. -Но часто Вам может понадобиться несколько одновременно работающих одинаковых процессов. +Но во многих случаях вы захотите одновременно запустить несколько процессов‑воркеров. -### Множество процессов - Воркеры (Workers) +### Несколько процессов — Воркеры { #multiple-processes-workers } -Если количество Ваших клиентов больше, чем может обслужить один процесс (допустим, что виртуальная машина не слишком мощная), но при этом Вам доступно **несколько ядер процессора**, то вы можете запустить **несколько процессов** одного и того же приложения параллельно и распределить запросы между этими процессами. +Если клиентов больше, чем способен обслужить один процесс (например, если виртуальная машина не слишком мощная), и на сервере есть **несколько ядер CPU**, вы можете запустить **несколько процессов** одного и того же приложения параллельно и распределять запросы между ними. -**Несколько запущенных процессов** одной и той же API-программы часто называют **воркерами**. +Когда вы запускаете **несколько процессов** одной и той же программы API, их обычно называют **воркерами**. -### Процессы и порты́ +### Процессы‑воркеры и порты { #worker-processes-and-ports } -Помните ли Вы, как на странице [Об HTTPS](https.md){.internal-link target=_blank} мы обсуждали, что на сервере только один процесс может слушать одну комбинацию IP-адреса и порта? +Помните из раздела [Об HTTPS](https.md){.internal-link target=_blank}, что на сервере только один процесс может слушать конкретную комбинацию порта и IP‑адреса? -С тех пор ничего не изменилось. +Это по‑прежнему так. -Соответственно, чтобы иметь возможность работать с **несколькими процессами** одновременно, должен быть **один процесс, прослушивающий порт** и затем каким-либо образом передающий данные каждому рабочему процессу. +Поэтому, чтобы одновременно работало **несколько процессов**, должен быть **один процесс, слушающий порт**, который затем каким‑то образом передаёт коммуникацию каждому воркер‑процессу. -### У каждого процесса своя память +### Память на процесс { #memory-per-process } -Работающая программа загружает в память данные, необходимые для её работы, например, переменные содержащие модели машинного обучения или большие файлы. Каждая переменная **потребляет некоторое количество оперативной памяти (RAM)** сервера. +Когда программа загружает что‑то в память (например, модель машинного обучения в переменную или содержимое большого файла в переменную), всё это **потребляет часть памяти (RAM)** сервера. -Обычно процессы **не делятся памятью друг с другом**. Сие означает, что каждый работающий процесс имеет свои данные, переменные и свой кусок памяти. И если для выполнения вашего кода процессу нужно много памяти, то **каждый такой же процесс** запущенный дополнительно, потребует такого же количества памяти. +И разные процессы обычно **не делят память**. Это значит, что у каждого процесса свои переменные и своя память. Если ваш код потребляет много памяти, то **каждый процесс** будет потреблять сопоставимый объём памяти. -### Память сервера +### Память сервера { #server-memory } -Допустим, что Ваш код загружает модель машинного обучения **размером 1 ГБ**. Когда вы запустите своё API как один процесс, он займёт в оперативной памяти не менее 1 ГБ. А если вы запустите **4 таких же процесса** (4 воркера), то каждый из них займёт 1 ГБ оперативной памяти. В результате вашему API потребуется **4 ГБ оперативной памяти (RAM)**. +Например, если ваш код загружает модель Машинного обучения размером **1 ГБ**, то при запуске одного процесса с вашим API он будет использовать как минимум 1 ГБ RAM. А если вы запустите **4 процесса** (4 воркера), каждый процесс будет использовать 1 ГБ RAM. Всего ваш API будет потреблять **4 ГБ RAM**. -И если Ваш удалённый сервер или виртуальная машина располагает только 3 ГБ памяти, то попытка загрузить в неё 4 ГБ данных вызовет проблемы. 🚨 +И если у вашего удалённого сервера или виртуальной машины только 3 ГБ RAM, попытка загрузить более 4 ГБ вызовет проблемы. 🚨 -### Множество процессов - Пример +### Несколько процессов — пример { #multiple-processes-an-example } -В этом примере **менеджер процессов** запустит и будет управлять двумя **воркерами**. +В этом примере есть **процесс‑менеджер**, который запускает и контролирует два **процесса‑воркера**. -Менеджер процессов будет слушать определённый **сокет** (IP:порт) и передавать данные работающим процессам. +Процесс‑менеджер, вероятно, будет тем, кто слушает **порт** на IP. И он будет передавать всю коммуникацию воркер‑процессам. -Каждый из этих процессов будет запускать ваше приложение для обработки полученного **запроса** и возвращения вычисленного **ответа** и они будут использовать оперативную память. +Эти воркеры будут запускать ваше приложение, выполнять основные вычисления для получения **запроса** и возврата **ответа**, и загружать всё, что вы кладёте в переменные, в RAM. -Безусловно, на этом же сервере будут работать и **другие процессы**, которые не относятся к вашему приложению. +Конечно, на той же машине помимо вашего приложения, скорее всего, будут работать и **другие процессы**. -Интересная деталь заключается в том, что процент **использования центрального процессора (CPU)** каждым процессом может сильно меняться с течением времени, но объём занимаемой **оперативной памяти (RAM)** остаётся относительно **стабильным**. +Интересная деталь: процент **использования CPU** каждым процессом со временем может сильно **меняться**, но **память (RAM)** обычно остаётся более‑менее **стабильной**. -Если у вас есть API, который каждый раз выполняет сопоставимый объем вычислений, и у вас много клиентов, то **загрузка процессора**, вероятно, *также будет стабильной* (вместо того, чтобы постоянно быстро увеличиваться и уменьшаться). +Если у вас API, который каждый раз выполняет сопоставимый объём вычислений, и у вас много клиентов, то **загрузка процессора**, вероятно, *тоже будет стабильной* (вместо того, чтобы быстро и постоянно «скакать»). -### Примеры стратегий и инструментов для запуска нескольких экземпляров приложения +### Примеры инструментов и стратегий репликации { #examples-of-replication-tools-and-strategies } -Существует несколько подходов для достижения целей репликации и я расскажу Вам больше о конкретных стратегиях в следующих главах, например, когда речь пойдет о Docker и контейнерах. +Есть несколько подходов для достижения этого, и я расскажу больше о конкретных стратегиях в следующих главах, например, говоря о Docker и контейнерах. -Основное ограничение при этом - только **один** компонент может работать с определённым **портом публичного IP**. И должен быть способ **передачи** данных между этим компонентом и копиями **процессов/воркеров**. +Главное ограничение: должен быть **один** компонент, который обрабатывает **порт** на **публичном IP**. И у него должен быть способ **передавать** коммуникацию реплицированным **процессам/воркерам**. -Вот некоторые возможные комбинации и стратегии: +Некоторые возможные комбинации и стратегии: -* **Gunicorn** управляющий **воркерами Uvicorn** - * Gunicorn будет выступать как **менеджер процессов**, прослушивая **IP:port**. Необходимое количество запущенных экземпляров приложения будет осуществляться посредством запуска **множества работающих процессов Uvicorn**. -* **Uvicorn** управляющий **воркерами Uvicorn** - * Один процесс Uvicorn будет выступать как **менеджер процессов**, прослушивая **IP:port**. Он будет запускать **множество работающих процессов Uvicorn**. -* **Kubernetes** и аналогичные **контейнерные системы** - * Какой-то компонент в **Kubernetes** будет слушать **IP:port**. Необходимое количество запущенных экземпляров приложения будет осуществляться посредством запуска **нескольких контейнеров**, в каждом из которых работает **один процесс Uvicorn**. -* **Облачные сервисы**, которые позаботятся обо всём за Вас - * Возможно, что облачный сервис умеет **управлять запуском дополнительных экземпляров приложения**. Вероятно, он потребует, чтоб вы указали - какой **процесс** или **образ** следует клонировать. Скорее всего, вы укажете **один процесс Uvicorn** и облачный сервис будет запускать его копии при необходимости. +* **Uvicorn** с `--workers` + * Один **процесс‑менеджер** Uvicorn будет слушать **IP** и **порт** и запускать **несколько процессов‑воркеров Uvicorn**. +* **Kubernetes** и другие распределённые **контейнерные системы** + * Некий компонент на уровне **Kubernetes** будет слушать **IP** и **порт**. Репликация достигается с помощью **нескольких контейнеров**, в каждом из которых работает **один процесс Uvicorn**. +* **Облачные сервисы**, которые берут это на себя + * Облачный сервис, скорее всего, **возьмёт репликацию на себя**. Он, возможно, позволит указать **процесс для запуска** или **образ контейнера**. В любом случае это, скорее всего, будет **один процесс Uvicorn**, а сервис займётся его репликацией. -/// tip | Заметка +/// tip | Совет -Если вы не знаете, что такое **контейнеры**, Docker или Kubernetes, не переживайте. +Не беспокойтесь, если некоторые пункты про **контейнеры**, Docker или Kubernetes пока кажутся неочевидными. -Я поведаю Вам о контейнерах, образах, Docker, Kubernetes и т.п. в главе: [FastAPI внутри контейнеров - Docker](docker.md){.internal-link target=_blank}. +Я расскажу больше про образы контейнеров, Docker, Kubernetes и т.п. в следующей главе: [FastAPI внутри контейнеров — Docker](docker.md){.internal-link target=_blank}. /// -## Шаги, предшествующие запуску +## Предварительные шаги перед запуском { #previous-steps-before-starting } -Часто бывает, что Вам необходимо произвести какие-то подготовительные шаги **перед запуском** своего приложения. +Во многих случаях вы захотите выполнить некоторые шаги **перед запуском** приложения. Например, запустить **миграции базы данных**. -Но в большинстве случаев такие действия достаточно произвести **однократно**. +Но чаще всего эти шаги нужно выполнять только **один раз**. -Поэтому Вам нужен будет **один процесс**, выполняющий эти **подготовительные шаги** до запуска приложения. +Поэтому вы захотите иметь **один процесс**, который выполнит эти **предварительные шаги**, прежде чем запускать приложение. -Также Вам нужно будет убедиться, что этот процесс выполнил подготовительные шаги *даже* если впоследствии вы запустите **несколько процессов** (несколько воркеров) самого приложения. Если бы эти шаги выполнялись в каждом **клонированном процессе**, они бы **дублировали** работу, пытаясь выполнить её **параллельно**. И если бы эта работа была бы чем-то деликатным, вроде миграции базы данных, то это может вызвать конфликты между ними. +И вам нужно будет убедиться, что это делает один процесс **даже** если потом вы запускаете **несколько процессов** (несколько воркеров) самого приложения. Если эти шаги выполнят **несколько процессов**, они **дублируют** работу, запустив её **параллельно**, и, если речь о чём‑то деликатном (например, миграции БД), это может вызвать конфликты. -Безусловно, возможны случаи, когда нет проблем при выполнении предварительной подготовки параллельно или несколько раз. Тогда Вам повезло, работать с ними намного проще. +Конечно, бывают случаи, когда нет проблем, если предварительные шаги выполняются несколько раз — тогда всё проще. -/// tip | Заметка +/// tip | Совет -Имейте в виду, что в некоторых случаях запуск вашего приложения **может не требовать каких-либо предварительных шагов вовсе**. +Также учтите, что в зависимости от вашей схемы развёртывания в некоторых случаях **предварительные шаги могут вовсе не требоваться**. -Что ж, тогда Вам не нужно беспокоиться об этом. 🤷 +Тогда об этом можно не беспокоиться. 🤷 /// -### Примеры стратегий запуска предварительных шагов +### Примеры стратегий для предварительных шагов { #examples-of-previous-steps-strategies } -Существует **сильная зависимость** от того, как вы **развёртываете свою систему**, запускаете программы, обрабатываете перезапуски и т.д. +Это будет **сильно зависеть** от того, как вы **развёртываете систему**, как запускаете программы, обрабатываете перезапуски и т.д. -Вот некоторые возможные идеи: +Некоторые возможные идеи: -* При использовании Kubernetes нужно предусмотреть "инициализирующий контейнер", запускаемый до контейнера с приложением. -* Bash-скрипт, выполняющий предварительные шаги, а затем запускающий приложение. - * При этом Вам всё ещё нужно найти способ - как запускать/перезапускать *такой* bash-скрипт, обнаруживать ошибки и т.п. +* «Init Container» в Kubernetes, который запускается перед контейнером с приложением +* Bash‑скрипт, который выполняет предварительные шаги, а затем запускает приложение + * При этом всё равно нужен способ запускать/перезапускать *этот* bash‑скрипт, обнаруживать ошибки и т.п. -/// tip | Заметка +/// tip | Совет -Я приведу Вам больше конкретных примеров работы с контейнерами в главе: [FastAPI внутри контейнеров - Docker](docker.md){.internal-link target=_blank}. +Я приведу более конкретные примеры с контейнерами в следующей главе: [FastAPI внутри контейнеров — Docker](docker.md){.internal-link target=_blank}. /// -## Утилизация ресурсов +## Использование ресурсов { #resource-utilization } -Ваш сервер располагает ресурсами, которые Ваши программы могут потреблять или **утилизировать**, а именно - время работы центрального процессора и объём оперативной памяти. +Ваш сервер(а) — это **ресурс**, который ваши программы могут потреблять или **использовать**: время вычислений на CPU и доступную оперативную память (RAM). -Как много системных ресурсов вы предполагаете потребить/утилизировать? Если не задумываться, то можно ответить - "немного", но на самом деле Вы, вероятно, захотите использовать **максимально возможное количество**. +Какую долю системных ресурсов вы хотите потреблять/использовать? Можно подумать «немного», но на практике вы, скорее всего, захотите потреблять **максимум без падений**. -Если вы платите за содержание трёх серверов, но используете лишь малую часть системных ресурсов каждого из них, то вы **выбрасываете деньги на ветер**, а также **впустую тратите электроэнергию** и т.п. +Если вы платите за 3 сервера, но используете лишь малую часть их RAM и CPU, вы, вероятно, **тратите деньги впустую** 💸 и **электроэнергию серверов** 🌎 и т.п. -В таком случае было бы лучше обойтись двумя серверами, но более полно утилизировать их ресурсы (центральный процессор, оперативную память, жёсткий диск, сети передачи данных и т.д). +В таком случае лучше иметь 2 сервера и использовать более высокий процент их ресурсов (CPU, память, диск, сетевую полосу и т.д.). -С другой стороны, если вы располагаете только двумя серверами и используете **на 100% их процессоры и память**, но какой-либо процесс запросит дополнительную память, то операционная система сервера будет использовать жёсткий диск для расширения оперативной памяти (а диск работает в тысячи раз медленнее), а то вовсе **упадёт**. Или если какому-то процессу понадобится произвести вычисления, то ему придётся подождать, пока процессор освободится. +С другой стороны, если у вас 2 сервера и вы используете **100% их CPU и RAM**, в какой‑то момент один процесс попросит больше памяти, и сервер начнёт использовать диск как «память» (что в тысячи раз медленнее) или даже **упадёт**. Или процессу понадобятся вычисления, но ему придётся ждать освобождения CPU. -В такой ситуации лучше подключить **ещё один сервер** и перераспределить процессы между серверами, чтоб всем **хватало памяти и процессорного времени**. +В таком случае лучше добавить **ещё один сервер** и запустить часть процессов на нём, чтобы у всех было **достаточно RAM и времени CPU**. -Также есть вероятность, что по какой-то причине возник **всплеск** запросов к вашему API. Возможно, это был вирус, боты или другие сервисы начали пользоваться им. И для таких происшествий вы можете захотеть иметь дополнительные ресурсы. +Также возможен **всплеск** использования вашего API: он мог «взорваться» по популярности, или какие‑то сервисы/боты начали его активно использовать. На такие случаи стоит иметь запас ресурсов. -При настройке логики развёртываний, вы можете указать **целевое значение** утилизации ресурсов, допустим, **от 50% до 90%**. Обычно эти метрики и используют. +Можно задать **целевое значение**, например **между 50% и 90%** использования ресурсов. Скорее всего, именно эти вещи вы будете измерять и на их основе настраивать развёртывание. -Вы можете использовать простые инструменты, такие как `htop`, для отслеживания загрузки центрального процессора и оперативной памяти сервера, в том числе каждым процессом. Или более сложные системы мониторинга нескольких серверов. +Можно использовать простые инструменты вроде `htop`, чтобы смотреть загрузку CPU и RAM на сервере или по процессам. Или более сложные распределённые системы мониторинга. -## Резюме +## Резюме { #recap } -Вы прочитали некоторые из основных концепций, которые необходимо иметь в виду при принятии решения о развертывании приложений: +Здесь вы прочитали о некоторых основных концепциях, которые, вероятно, стоит учитывать при выборе способа развёртывания приложения: -* Использование более безопасного протокола HTTPS -* Настройки запуска приложения -* Перезагрузка приложения -* Запуск нескольких экземпляров приложения -* Управление памятью -* Использование перечисленных функций перед запуском приложения. +* Безопасность — HTTPS +* Запуск при старте +* Перезапуски +* Репликация (количество запущенных процессов) +* Память +* Предварительные шаги перед запуском -Осознание этих идей и того, как их применять, должно дать Вам интуитивное понимание, необходимое для принятия решений при настройке развертываний. 🤓 +Понимание этих идей и того, как их применять, даст вам интуицию, необходимую для принятия решений при настройке и доработке ваших развёртываний. 🤓 -В следующих разделах я приведу более конкретные примеры возможных стратегий, которым вы можете следовать. 🚀 +В следующих разделах я приведу более конкретные примеры возможных стратегий. 🚀 diff --git a/docs/ru/docs/deployment/docker.md b/docs/ru/docs/deployment/docker.md index c72f67172b..3937b01654 100644 --- a/docs/ru/docs/deployment/docker.md +++ b/docs/ru/docs/deployment/docker.md @@ -1,17 +1,17 @@ -# FastAPI и Docker-контейнеры +# FastAPI в контейнерах — Docker { #fastapi-in-containers-docker } -При развёртывании приложений FastAPI, часто начинают с создания **образа контейнера на основе Linux**. Обычно для этого используют **Docker**. Затем можно развернуть такой контейнер на сервере одним из нескольких способов. +При развёртывании приложений FastAPI распространённый подход — собирать **образ контейнера на Linux**. Обычно это делают с помощью **Docker**. Затем такой образ контейнера можно развернуть несколькими способами. -Использование контейнеров на основе Linux имеет ряд преимуществ, включая **безопасность**, **воспроизводимость**, **простоту** и прочие. +Использование Linux-контейнеров даёт ряд преимуществ: **безопасность**, **воспроизводимость**, **простоту** и другие. /// tip | Подсказка -Торопитесь или уже знакомы с этой технологией? Перепрыгните на раздел [Создать Docker-образ для FastAPI 👇](#docker-fastapi) +Нет времени и вы уже знакомы с этим? Перейдите к [`Dockerfile` ниже 👇](#build-a-docker-image-for-fastapi). ///
-Развернуть Dockerfile 👀 +Предпросмотр Dockerfile 👀 ```Dockerfile FROM python:3.9 @@ -24,130 +24,125 @@ RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt COPY ./app /code/app -CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] +CMD ["fastapi", "run", "app/main.py", "--port", "80"] -# Если используете прокси-сервер, такой как Nginx или Traefik, добавьте --proxy-headers -# CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80", "--proxy-headers"] +# Если запускаете за прокси, например Nginx или Traefik, добавьте --proxy-headers +# CMD ["fastapi", "run", "app/main.py", "--port", "80", "--proxy-headers"] ```
-## Что такое "контейнер" +## Что такое контейнер { #what-is-a-container } -Контейнеризация - это **легковесный** способ упаковать приложение, включая все его зависимости и необходимые файлы, чтобы изолировать его от других контейнеров (других приложений и компонентов) работающих на этой же системе. +Контейнеры (в основном Linux-контейнеры) — это очень **легковесный** способ упаковать приложения вместе со всеми их зависимостями и необходимыми файлами, изолировав их от других контейнеров (других приложений или компонентов) в той же системе. -Контейнеры, основанные на Linux, запускаются используя ядро Linux хоста (машины, виртуальной машины, облачного сервера и т.п.). Это значит, что они очень легковесные (по сравнению с полноценными виртуальными машинами, полностью эмулирующими работу операционной системы). +Linux-контейнеры запускаются, используя то же ядро Linux хоста (машины, виртуальной машины, облачного сервера и т.п.). Это означает, что они очень легковесные (по сравнению с полноценными виртуальными машинами, эмулирующими целую операционную систему). -Благодаря этому, контейнеры потребляют **малое количество ресурсов**, сравнимое с процессом запущенным напрямую (виртуальная машина потребует гораздо больше ресурсов). +Таким образом, контейнеры потребляют **малое количество ресурсов**, сопоставимое с запуском процессов напрямую (виртуальная машина потребовала бы намного больше ресурсов). -Контейнеры также имеют собственные запущенные **изолированные** процессы (но часто только один процесс), файловую систему и сеть, что упрощает развёртывание, разработку, управление доступом и т.п. +У контейнеров также есть собственные **изолированные** выполняемые процессы (обычно всего один процесс), файловая система и сеть, что упрощает развёртывание, безопасность, разработку и т.д. -## Что такое "образ контейнера" +## Что такое образ контейнера { #what-is-a-container-image } -Для запуска **контейнера** нужен **образ контейнера**. +**Контейнер** запускается из **образа контейнера**. -Образ контейнера - это **замороженная** версия всех файлов, переменных окружения, программ и команд по умолчанию, необходимых для работы приложения. **Замороженный** - означает, что **образ** не запущен и не выполняется, это всего лишь упакованные вместе файлы и метаданные. +Образ контейнера — это **статическая** версия всех файлов, переменных окружения и команды/программы по умолчанию, которые должны присутствовать в контейнере. Здесь **статическая** означает, что **образ** не запущен, он не выполняется — это только упакованные файлы и метаданные. -В отличие от **образа контейнера**, хранящего неизменное содержимое, под термином **контейнер** подразумевают запущенный образ, то есть объёкт, который **исполняется**. +В противоположность «**образу контейнера**» (хранящему статическое содержимое), «**контейнер**» обычно означает запущенный экземпляр, то, что **выполняется**. -Когда **контейнер** запущен (на основании **образа**), он может создавать и изменять файлы, переменные окружения и т.д. Эти изменения будут существовать только внутри контейнера, но не будут сохраняться в образе контейнера (не будут сохранены на диск). +Когда **контейнер** запущен (на основе **образа контейнера**), он может создавать или изменять файлы, переменные окружения и т.д.. Эти изменения существуют только внутри контейнера и не сохраняются в исходном образе контейнера (не записываются на диск). -Образ контейнера можно сравнить с файлом, содержащем **программу**, например, как файл `main.py`. +Образ контейнера можно сравнить с **файлами программы**, например `python` и каким-то файлом `main.py`. -И **контейнер** (в отличие от **образа**) - это на самом деле выполняемый экземпляр образа, примерно как **процесс**. По факту, контейнер запущен только когда запущены его процессы (чаще, всего один процесс) и остановлен, когда запущенных процессов нет. +А сам **контейнер** (в отличие от **образа контейнера**) — это фактически запущенный экземпляр образа, сопоставимый с **процессом**. По сути, контейнер работает только тогда, когда в нём есть **запущенный процесс** (и обычно это один процесс). Контейнер останавливается, когда в нём не остаётся запущенных процессов. -## Образы контейнеров +## Образы контейнеров { #container-images } -Docker является одним из основных инструментов для создания **образов** и **контейнеров** и управления ими. +Docker — один из основных инструментов для создания и управления **образами контейнеров** и **контейнерами**. -Существует общедоступный Docker Hub с подготовленными **официальными образами** многих инструментов, окружений, баз данных и приложений. +Существует публичный Docker Hub с готовыми **официальными образами** для многих инструментов, окружений, баз данных и приложений. -К примеру, есть официальный образ Python. +Например, есть официальный образ Python. -Также там представлены и другие полезные образы, такие как базы данных: +А также множество образов для разных вещей, например баз данных: * PostgreSQL * MySQL * MongoDB -* Redis +* Redis, и т.д. -и т.п. +Используя готовые образы, очень легко **комбинировать** разные инструменты и использовать их. Например, чтобы попробовать новую базу данных. В большинстве случаев можно воспользоваться **официальными образами** и просто настроить их через переменные окружения. -Использование подготовленных образов значительно упрощает **комбинирование** и использование разных инструментов. Например, вы можете попытаться использовать новую базу данных. В большинстве случаев можно использовать **официальный образ** и всего лишь указать переменные окружения. +Таким образом, во многих случаях вы можете изучить контейнеры и Docker и переиспользовать эти знания с множеством различных инструментов и компонентов. -Таким образом, вы можете изучить, что такое контейнеризация и Docker, и использовать полученные знания с разными инструментами и компонентами. +Например, вы можете запустить **несколько контейнеров**: с базой данных, Python-приложением, веб-сервером с фронтендом на React и связать их через внутреннюю сеть. -Так, вы можете запустить одновременно **множество контейнеров** с базой данных, Python-приложением, веб-сервером, React-приложением и соединить их вместе через внутреннюю сеть. +Все системы управления контейнерами (такие как Docker или Kubernetes) имеют интегрированные возможности для такого сетевого взаимодействия. -Все системы управления контейнерами (такие, как Docker или Kubernetes) имеют встроенные возможности для организации такого сетевого взаимодействия. +## Контейнеры и процессы { #containers-and-processes } -## Контейнеры и процессы +**Образ контейнера** обычно включает в свои метаданные программу или команду по умолчанию, которую следует запускать при старте **контейнера**, а также параметры, передаваемые этой программе. Это очень похоже на запуск команды в терминале. -Обычно **образ контейнера** содержит метаданные предустановленной программы или команду, которую следует выполнить при запуске **контейнера**. Также он может содержать параметры, передаваемые предустановленной программе. Похоже на то, как если бы вы запускали такую программу через терминал. +Когда **контейнер** стартует, он выполняет указанную команду/программу (хотя вы можете переопределить это и запустить другую команду/программу). -Когда **контейнер** запущен, он будет выполнять прописанные в нём команды и программы. Но вы можете изменить его так, чтоб он выполнял другие команды и программы. +Контейнер работает до тех пор, пока работает его **главный процесс** (команда или программа). -Контейнер будет работать до тех пор, пока выполняется его **главный процесс** (команда или программа). +Обычно в контейнере есть **один процесс**, но главный процесс может запускать подпроцессы, и тогда в том же контейнере будет **несколько процессов**. -В контейнере обычно выполняется **только один процесс**, но от его имени можно запустить другие процессы, тогда в этом же в контейнере будет выполняться **множество процессов**. +Нельзя иметь работающий контейнер без **хотя бы одного запущенного процесса**. Если главный процесс останавливается, контейнер останавливается. -Контейнер не считается запущенным, если в нём **не выполняется хотя бы один процесс**. Если главный процесс остановлен, значит и контейнер остановлен. +## Создать Docker-образ для FastAPI { #build-a-docker-image-for-fastapi } -## Создать Docker-образ для FastAPI +Итак, давайте что-нибудь соберём! 🚀 -Что ж, давайте ужё создадим что-нибудь! 🚀 +Я покажу, как собрать **Docker-образ** для FastAPI **с нуля** на основе **официального образа Python**. -Я покажу Вам, как собирать **Docker-образ** для FastAPI **с нуля**, основываясь на **официальном образе Python**. +Именно так стоит делать в **большинстве случаев**, например: -Такой подход сгодится для **большинства случаев**, например: +* При использовании **Kubernetes** или похожих инструментов +* При запуске на **Raspberry Pi** +* При использовании облачного сервиса, который запускает для вас образ контейнера и т.п. -* Использование с **Kubernetes** или аналогичным инструментом -* Запуск в **Raspberry Pi** -* Использование в облачных сервисах, запускающих образы контейнеров для вас и т.п. +### Зависимости пакетов { #package-requirements } -### Установить зависимости +Обычно **зависимости** вашего приложения описаны в каком-то файле. -Обычно вашему приложению необходимы **дополнительные библиотеки**, список которых находится в отдельном файле. +Конкретный формат зависит в основном от инструмента, которым вы **устанавливаете** эти зависимости. -На название и содержание такого файла влияет выбранный Вами инструмент **установки** этих библиотек (зависимостей). +Чаще всего используется файл `requirements.txt` с именами пакетов и их версиями по одному на строку. -Чаще всего это простой файл `requirements.txt` с построчным перечислением библиотек и их версий. +Разумеется, вы будете придерживаться тех же идей, что описаны здесь: [О версиях FastAPI](versions.md){.internal-link target=_blank}, чтобы задать диапазоны версий. -При этом Вы, для выбора версий, будете использовать те же идеи, что упомянуты на странице [О версиях FastAPI](versions.md){.internal-link target=_blank}. - -Ваш файл `requirements.txt` может выглядеть как-то так: +Например, ваш `requirements.txt` может выглядеть так: ``` -fastapi>=0.68.0,<0.69.0 -pydantic>=1.8.0,<2.0.0 -uvicorn>=0.15.0,<0.16.0 +fastapi[standard]>=0.113.0,<0.114.0 +pydantic>=2.7.0,<3.0.0 ``` -Устанавливать зависимости проще всего с помощью `pip`: +И обычно вы установите эти зависимости командой `pip`, например:
```console $ pip install -r requirements.txt ---> 100% -Successfully installed fastapi pydantic uvicorn +Successfully installed fastapi pydantic ```
/// info | Информация -Существуют и другие инструменты управления зависимостями. - -В этом же разделе, но позже, я покажу вам пример использования Poetry. 👇 +Существуют и другие форматы и инструменты для описания и установки зависимостей. /// -### Создать приложение **FastAPI** +### Создать код **FastAPI** { #create-the-fastapi-code } * Создайте директорию `app` и перейдите в неё. * Создайте пустой файл `__init__.py`. -* Создайте файл `main.py` и заполните его: +* Создайте файл `main.py` со следующим содержимым: ```Python from typing import Union @@ -167,77 +162,109 @@ def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` -### Dockerfile +### Dockerfile { #dockerfile } -В этой же директории создайте файл `Dockerfile` и заполните его: +Теперь в той же директории проекта создайте файл `Dockerfile`: ```{ .dockerfile .annotate } -# (1) +# (1)! FROM python:3.9 -# (2) +# (2)! WORKDIR /code -# (3) +# (3)! COPY ./requirements.txt /code/requirements.txt -# (4) +# (4)! RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt -# (5) +# (5)! COPY ./app /code/app -# (6) -CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] +# (6)! +CMD ["fastapi", "run", "app/main.py", "--port", "80"] ``` -1. Начните с официального образа Python, который будет основой для образа приложения. +1. Начинаем с официального базового образа Python. -2. Укажите, что в дальнейшем команды запускаемые в контейнере, будут выполняться в директории `/code`. +2. Устанавливаем текущую рабочую директорию в `/code`. - Инструкция создаст эту директорию внутри контейнера и мы поместим в неё файл `requirements.txt` и директорию `app`. + Здесь мы разместим файл `requirements.txt` и директорию `app`. -3. Скопируете файл с зависимостями из текущей директории в `/code`. +3. Копируем файл с зависимостями в директорию `/code`. - Сначала копируйте **только** файл с зависимостями. + Сначала копируйте **только** файл с зависимостями, не остальной код. - Этот файл **изменяется довольно редко**, Docker ищет изменения при постройке образа и если не находит, то использует **кэш**, в котором хранятся предыдущие версии сборки образа. + Так как этот файл **меняется нечасто**, Docker определит это и использует **кэш** на этом шаге, что позволит использовать кэш и на следующем шаге. -4. Установите библиотеки перечисленные в файле с зависимостями. +4. Устанавливаем зависимости из файла с требованиями. - Опция `--no-cache-dir` указывает `pip` не сохранять загружаемые библиотеки на локальной машине для использования их в случае повторной загрузки. В контейнере, в случае пересборки этого шага, они всё равно будут удалены. + Опция `--no-cache-dir` указывает `pip` не сохранять загруженные пакеты локально, т.к. это нужно только если `pip` будет запускаться снова для установки тех же пакетов, а при работе с контейнерами это обычно не требуется. /// note | Заметка - Опция `--no-cache-dir` нужна только для `pip`, она никак не влияет на Docker или контейнеры. + `--no-cache-dir` относится только к `pip` и не имеет отношения к Docker или контейнерам. /// - Опция `--upgrade` указывает `pip` обновить библиотеки, емли они уже установлены. + Опция `--upgrade` указывает `pip` обновлять пакеты, если они уже установлены. - Как и в предыдущем шаге с копированием файла, этот шаг также будет использовать **кэш Docker** в случае отсутствия изменений. + Поскольку предыдущий шаг с копированием файла может быть обработан **кэшем Docker**, этот шаг также **использует кэш Docker**, когда это возможно. - Использование кэша, особенно на этом шаге, позволит вам **сэкономить** кучу времени при повторной сборке образа, так как зависимости будут сохранены в кеше, а не **загружаться и устанавливаться каждый раз**. + Использование кэша на этом шаге **сэкономит** вам много **времени** при повторных сборках образа во время разработки, вместо того чтобы **загружать и устанавливать** все зависимости **каждый раз**. -5. Скопируйте директорию `./app` внутрь директории `/code` (в контейнере). +5. Копируем директорию `./app` внутрь директории `/code`. - Так как в этой директории расположен код, который **часто изменяется**, то использование **кэша** на этом шаге будет наименее эффективно, а значит лучше поместить этот шаг **ближе к концу** `Dockerfile`, дабы не терять выгоду от оптимизации предыдущих шагов. + Так как здесь весь код, который **меняется чаще всего**, кэш Docker **вряд ли** будет использоваться для этого шагa или **последующих шагов**. -6. Укажите **команду**, запускающую сервер `uvicorn`. + Поэтому важно разместить этот шаг **ближе к концу** `Dockerfile`, чтобы оптимизировать время сборки образа контейнера. - `CMD` принимает список строк, разделённых запятыми, но при выполнении объединит их через пробел, собрав из них одну команду, которую вы могли бы написать в терминале. +6. Указываем **команду** для запуска `fastapi run`, под капотом используется Uvicorn. - Эта команда будет выполнена в **текущей рабочей директории**, а именно в директории `/code`, которая указана в команде `WORKDIR /code`. + `CMD` принимает список строк, каждая из которых — это то, что вы бы ввели в командной строке, разделяя пробелами. - Так как команда выполняется внутри директории `/code`, в которую мы поместили папку `./app` с приложением, то **Uvicorn** сможет найти и **импортировать** объект `app` из файла `app.main`. + Эта команда будет выполнена из **текущей рабочей директории**, той самой `/code`, которую вы задали выше `WORKDIR /code`. /// tip | Подсказка -Если ткнёте на кружок с плюсом, то увидите пояснения. 👆 +Посмотрите, что делает каждая строка, кликнув по номеру рядом со строкой. 👆 + +/// + +/// warning | Предупреждение + +Всегда используйте **exec-форму** инструкции `CMD`, как описано ниже. /// -На данном этапе структура проекта должны выглядеть так: +#### Используйте `CMD` — exec-форма { #use-cmd-exec-form } + +Инструкцию Docker `CMD` можно писать в двух формах: + +✅ **Exec**-форма: + +```Dockerfile +# ✅ Делайте так +CMD ["fastapi", "run", "app/main.py", "--port", "80"] +``` + +⛔️ **Shell**-форма: + +```Dockerfile +# ⛔️ Не делайте так +CMD fastapi run app/main.py --port 80 +``` + +Обязательно используйте **exec**-форму, чтобы FastAPI мог корректно завершаться и чтобы срабатывали [события lifespan](../advanced/events.md){.internal-link target=_blank}. + +Подробнее об этом читайте в документации Docker о shell- и exec-формах. + +Это особенно заметно при использовании `docker compose`. См. раздел FAQ Docker Compose с техническими подробностями: Почему мои сервисы пересоздаются или останавливаются 10 секунд?. + +#### Структура директорий { #directory-structure } + +Теперь у вас должна быть такая структура: ``` . @@ -248,53 +275,52 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] └── requirements.txt ``` -#### Использование прокси-сервера +#### За прокси-сервером TLS терминации { #behind-a-tls-termination-proxy } -Если вы запускаете контейнер за прокси-сервером завершения TLS (балансирующего нагрузку), таким как Nginx или Traefik, добавьте опцию `--proxy-headers`, которая укажет Uvicorn, что он работает позади прокси-сервера и может доверять заголовкам отправляемым им. +Если вы запускаете контейнер за прокси-сервером завершения TLS (балансировщиком нагрузки), таким как Nginx или Traefik, добавьте опцию `--proxy-headers`. Это сообщит Uvicorn (через FastAPI CLI), что приложение работает за HTTPS и можно доверять соответствующим заголовкам. ```Dockerfile -CMD ["uvicorn", "app.main:app", "--proxy-headers", "--host", "0.0.0.0", "--port", "80"] +CMD ["fastapi", "run", "app/main.py", "--proxy-headers", "--port", "80"] ``` -#### Кэш Docker'а +#### Кэш Docker { #docker-cache } -В нашем `Dockerfile` использована полезная хитрость, когда сначала копируется **только файл с зависимостями**, а не вся папка с кодом приложения. +В этом `Dockerfile` есть важная хитрость: мы сначала копируем **только файл с зависимостями**, а не весь код. Вот зачем. ```Dockerfile COPY ./requirements.txt /code/requirements.txt ``` -Docker и подобные ему инструменты **создают** образы контейнеров **пошагово**, добавляя **один слой над другим**, начиная с первой строки `Dockerfile` и добавляя файлы, создаваемые при выполнении каждой инструкции из `Dockerfile`. +Docker и подобные инструменты **строят** образы контейнеров **инкрементально**, добавляя **слой за слоем**, начиная с первой строки `Dockerfile` и добавляя любые файлы, создаваемые каждой инструкцией `Dockerfile`. -При создании образа используется **внутренний кэш** и если в файлах нет изменений с момента последней сборки образа, то будет **переиспользован** ранее созданный слой образа, а не повторное копирование файлов и создание слоя с нуля. -Заметьте, что так как слой следующего шага зависит от слоя предыдущего, то изменения внесённые в промежуточный слой, также повлияют на последующие. +Docker и подобные инструменты также используют **внутренний кэш** при сборке образа: если файл не изменился с момента предыдущей сборки, будет **переиспользован слой**, созданный в прошлый раз, вместо повторного копирования файла и создания нового слоя с нуля. -Избегание копирования файлов не обязательно улучшит ситуацию, но использование кэша на одном шаге, позволит **использовать кэш и на следующих шагах**. Например, можно использовать кэш при установке зависимостей: +Само по себе избегание копирования всех файлов не всегда даёт много, но благодаря использованию кэша на этом шаге Docker сможет **использовать кэш и на следующем шаге**. Например, на шаге установки зависимостей: ```Dockerfile RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt ``` -Файл со списком зависимостей **изменяется довольно редко**. Так что выполнив команду копирования только этого файла, Docker сможет **использовать кэш** на этом шаге. +Файл с зависимостями **меняется нечасто**. Поэтому, копируя только его, Docker сможет **использовать кэш** для этого шага. -А затем **использовать кэш и на следующем шаге**, загружающем и устанавливающем зависимости. И вот тут-то мы и **сэкономим много времени**. ✨ ...а не будем томиться в тягостном ожидании. 😪😆 +А затем Docker сможет **использовать кэш и на следующем шаге**, где скачиваются и устанавливаются зависимости. Здесь мы как раз **экономим много времени**. ✨ ...и не скучаем в ожидании. 😪😆 -Для загрузки и установки необходимых библиотек **может понадобиться несколько минут**, но использование **кэша** занимает несколько **секунд** максимум. +Скачивание и установка зависимостей **может занять минуты**, но использование **кэша** — **секунды**. -И так как во время разработки вы будете часто пересобирать контейнер для проверки работоспособности внесённых изменений, то сэкономленные минуты сложатся в часы, а то и дни. +Поскольку во время разработки вы будете пересобирать образ снова и снова, чтобы проверить изменения в коде, суммарно это сэкономит немало времени. -Так как папка с кодом приложения **изменяется чаще всего**, то мы расположили её в конце `Dockerfile`, ведь после внесённых в код изменений кэш не будет использован на этом и следующих шагах. +Затем, ближе к концу `Dockerfile`, мы копируем весь код. Так как он **меняется чаще всего**, мы ставим этот шаг в конец, потому что почти всегда всё, что после него, уже не сможет использовать кэш. ```Dockerfile COPY ./app /code/app ``` -### Создать Docker-образ +### Собрать Docker-образ { #build-the-docker-image } -Теперь, когда все файлы на своих местах, давайте создадим образ контейнера. +Теперь, когда все файлы на месте, соберём образ контейнера. -* Перейдите в директорию проекта (в ту, где расположены `Dockerfile` и папка `app` с приложением). -* Создай образ приложения FastAPI: +* Перейдите в директорию проекта (где ваш `Dockerfile` и директория `app`). +* Соберите образ FastAPI:
@@ -308,15 +334,15 @@ $ docker build -t myimage . /// tip | Подсказка -Обратите внимание, что в конце написана точка - `.`, это то же самое что и `./`, тем самым мы указываем Docker директорию, из которой нужно выполнять сборку образа контейнера. +Обратите внимание на точку `.` в конце — это то же самое, что `./`. Так мы указываем Docker, из какой директории собирать образ контейнера. -В данном случае это та же самая директория (`.`). +В данном случае это текущая директория (`.`). /// -### Запуск Docker-контейнера +### Запустить Docker-контейнер { #start-the-docker-container } -* Запустите контейнер, основанный на вашем образе: +* Запустите контейнер на основе вашего образа:
@@ -326,35 +352,35 @@ $ docker run -d --name mycontainer -p 80:80 myimage
-## Проверка +## Проверка { #check-it } -Вы можете проверить, что Ваш Docker-контейнер работает перейдя по ссылке: http://192.168.99.100/items/5?q=somequery или http://127.0.0.1/items/5?q=somequery (или похожей, которую использует Ваш Docker-хост). +Проверьте работу по адресу вашего Docker-хоста, например: http://192.168.99.100/items/5?q=somequery или http://127.0.0.1/items/5?q=somequery (или аналогичный URL вашего Docker-хоста). -Там вы увидите: +Вы увидите что-то вроде: ```JSON {"item_id": 5, "q": "somequery"} ``` -## Интерактивная документация API +## Интерактивная документация API { #interactive-api-docs } -Теперь перейдите по ссылке http://192.168.99.100/docs или http://127.0.0.1/docs (или похожей, которую использует Ваш Docker-хост). +Теперь зайдите на http://192.168.99.100/docs или http://127.0.0.1/docs (или аналогичный URL вашего Docker-хоста). -Здесь вы увидите автоматическую интерактивную документацию API (предоставляемую Swagger UI): +Вы увидите автоматическую интерактивную документацию API (на базе Swagger UI): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) -## Альтернативная документация API +## Альтернативная документация API { #alternative-api-docs } -Также вы можете перейти по ссылке http://192.168.99.100/redoc or http://127.0.0.1/redoc (или похожей, которую использует Ваш Docker-хост). +Также можно открыть http://192.168.99.100/redoc или http://127.0.0.1/redoc (или аналогичный URL вашего Docker-хоста). -Здесь вы увидите альтернативную автоматическую документацию API (предоставляемую ReDoc): +Вы увидите альтернативную автоматическую документацию (на базе ReDoc): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) -## Создание Docker-образа на основе однофайлового приложения FastAPI +## Собрать Docker-образ для однофайлового FastAPI { #build-a-docker-image-with-a-single-file-fastapi } -Если ваше приложение FastAPI помещено в один файл, например, `main.py` и структура Ваших файлов похожа на эту: +Если ваше приложение FastAPI — один файл, например `main.py` без директории `./app`, структура файлов может быть такой: ``` . @@ -363,7 +389,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage └── requirements.txt ``` -Вам нужно изменить в `Dockerfile` соответствующие пути копирования файлов: +Тогда в `Dockerfile` нужно изменить пути копирования: ```{ .dockerfile .annotate hl_lines="10 13" } FROM python:3.9 @@ -374,360 +400,221 @@ COPY ./requirements.txt /code/requirements.txt RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt -# (1) +# (1)! COPY ./main.py /code/ -# (2) -CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] +# (2)! +CMD ["fastapi", "run", "main.py", "--port", "80"] ``` -1. Скопируйте непосредственно файл `main.py` в директорию `/code` (не указывайте `./app`). +1. Копируем файл `main.py` напрямую в `/code` (без директории `./app`). -2. При запуске Uvicorn укажите ему, что объект `app` нужно импортировать из файла `main` (вместо импортирования из `app.main`). +2. Используем `fastapi run` для запуска приложения из одного файла `main.py`. -Настройте Uvicorn на использование `main` вместо `app.main` для импорта объекта `app`. +Когда вы передаёте файл в `fastapi run`, он автоматически определит, что это одиночный файл, а не часть пакета, и поймёт, как его импортировать и запустить ваше FastAPI-приложение. 😎 -## Концепции развёртывания +## Концепции развертывания { #deployment-concepts } -Давайте вспомним о [Концепциях развёртывания](concepts.md){.internal-link target=_blank} и применим их к контейнерам. +Ещё раз рассмотрим [концепции развертывания](concepts.md){.internal-link target=_blank} применительно к контейнерам. -Контейнеры - это, в основном, инструмент упрощающий **сборку и развёртывание** приложения и они не обязывают к применению какой-то определённой **концепции развёртывания**, а значит мы можем выбирать нужную стратегию. +Контейнеры главным образом упрощают **сборку и развёртывание** приложения, но не навязывают конкретный подход к этим **концепциям развертывания**, и существует несколько стратегий. -**Хорошая новость** в том, что независимо от выбранной стратегии, мы всё равно можем покрыть все концепции развёртывания. 🎉 +**Хорошая новость** в том, что при любой стратегии есть способ охватить все концепции развертывания. 🎉 -Рассмотрим эти **концепции развёртывания** применительно к контейнерам: +Рассмотрим эти **концепции развертывания** в терминах контейнеров: -* Использование более безопасного протокола HTTPS -* Настройки запуска приложения -* Перезагрузка приложения -* Запуск нескольких экземпляров приложения -* Управление памятью -* Использование перечисленных функций перед запуском приложения +* HTTPS +* Запуск при старте +* Перезапуски +* Репликация (количество запущенных процессов) +* Память +* Предварительные шаги перед запуском -## Использование более безопасного протокола HTTPS +## HTTPS { #https } -Если мы определимся, что **образ контейнера** будет содержать только приложение FastAPI, то работу с HTTPS можно организовать **снаружи** контейнера при помощи другого инструмента. +Если мы рассматриваем только **образ контейнера** для приложения FastAPI (и далее запущенный **контейнер**), то HTTPS обычно обрабатывается **внешним** инструментом. -Это может быть другой контейнер, в котором есть, например, Traefik, работающий с **HTTPS** и **самостоятельно** обновляющий **сертификаты**. +Это может быть другой контейнер, например с Traefik, который берёт на себя **HTTPS** и **автоматическое** получение **сертификатов**. /// tip | Подсказка -Traefik совместим с Docker, Kubernetes и им подобными инструментами. Он очень прост в установке и настройке использования HTTPS для Ваших контейнеров. +У Traefik есть интеграции с Docker, Kubernetes и другими, поэтому очень легко настроить и сконфигурировать HTTPS для ваших контейнеров. /// -В качестве альтернативы, работу с HTTPS можно доверить облачному провайдеру, если он предоставляет такую услугу. +В качестве альтернативы HTTPS может быть реализован как сервис облачного провайдера (при этом приложение всё равно работает в контейнере). -## Настройки запуска и перезагрузки приложения +## Запуск при старте и перезапуски { #running-on-startup-and-restarts } -Обычно **запуском контейнера с приложением** занимается какой-то отдельный инструмент. +Обычно есть другой инструмент, отвечающий за **запуск и работу** вашего контейнера. -Это может быть сам **Docker**, **Docker Compose**, **Kubernetes**, **облачный провайдер** и т.п. +Это может быть сам **Docker**, **Docker Compose**, **Kubernetes**, **облачный сервис** и т.п. -В большинстве случаев это простейшие настройки запуска и перезагрузки приложения (при падении). Например, команде запуска Docker-контейнера можно добавить опцию `--restart`. +В большинстве (или во всех) случаев есть простая опция, чтобы включить запуск контейнера при старте системы и перезапуски при сбоях. Например, в Docker это опция командной строки `--restart`. -Управление запуском и перезагрузкой приложений без использования контейнеров - весьма затруднительно. Но при **работе с контейнерами** - это всего лишь функционал доступный по умолчанию. ✨ +Без контейнеров обеспечить запуск при старте и перезапуски может быть сложно. Но при **работе с контейнерами** в большинстве случаев этот функционал доступен по умолчанию. ✨ -## Запуск нескольких экземпляров приложения - Указание количества процессов +## Репликация — количество процессов { #replication-number-of-processes } -Если у вас есть кластер машин под управлением **Kubernetes**, Docker Swarm Mode, Nomad или аналогичной сложной системой оркестрации контейнеров, скорее всего, вместо использования менеджера процессов (типа Gunicorn и его воркеры) в каждом контейнере, вы захотите **управлять количеством запущенных экземпляров приложения** на **уровне кластера**. +Если у вас есть кластер машин с **Kubernetes**, Docker Swarm Mode, Nomad или другой похожей системой для управления распределёнными контейнерами на нескольких машинах, скорее всего вы будете **управлять репликацией** на **уровне кластера**, а не использовать **менеджер процессов** (например, Uvicorn с воркерами) в каждом контейнере. -В любую из этих систем управления контейнерами обычно встроен способ управления **количеством запущенных контейнеров** для распределения **нагрузки** от входящих запросов на **уровне кластера**. +Одна из таких систем управления распределёнными контейнерами, как Kubernetes, обычно имеет встроенный способ управлять **репликацией контейнеров**, поддерживая **балансировку нагрузки** для входящих запросов — всё это на **уровне кластера**. -В такой ситуации Вы, вероятно, захотите создать **образ Docker**, как [описано выше](#dockerfile), с установленными зависимостями и запускающий **один процесс Uvicorn** вместо того, чтобы запускать Gunicorn управляющий несколькими воркерами Uvicorn. +В таких случаях вы, скорее всего, захотите собрать **Docker-образ с нуля**, как [описано выше](#dockerfile), установить зависимости и запускать **один процесс Uvicorn** вместо множества воркеров Uvicorn. -### Балансировщик нагрузки +### Балансировщик нагрузки { #load-balancer } -Обычно при использовании контейнеров один компонент **прослушивает главный порт**. Это может быть контейнер содержащий **прокси-сервер завершения работы TLS** для работы с **HTTPS** или что-то подобное. +При использовании контейнеров обычно есть компонент, **слушающий главный порт**. Это может быть другой контейнер — **прокси завершения TLS** для обработки **HTTPS** или похожий инструмент. -Поскольку этот компонент **принимает запросы** и равномерно **распределяет** их между компонентами, его также называют **балансировщиком нагрузки**. +Поскольку этот компонент принимает **нагрузку** запросов и распределяет её между воркерами **сбалансированно**, его часто называют **балансировщиком нагрузки**. /// tip | Подсказка -**Прокси-сервер завершения работы TLS** одновременно может быть **балансировщиком нагрузки**. +Тот же компонент **прокси завершения TLS**, который обрабатывает HTTPS, скорее всего также будет **балансировщиком нагрузки**. /// -Система оркестрации, которую вы используете для запуска и управления контейнерами, имеет встроенный инструмент **сетевого взаимодействия** (например, для передачи HTTP-запросов) между контейнерами с Вашими приложениями и **балансировщиком нагрузки** (который также может быть **прокси-сервером**). +При работе с контейнерами система, которую вы используете для запуска и управления ими, уже имеет внутренние средства для передачи **сетевого взаимодействия** (например, HTTP-запросов) от **балансировщика нагрузки** (который также может быть **прокси завершения TLS**) к контейнеру(-ам) с вашим приложением. -### Один балансировщик - Множество контейнеров +### Один балансировщик — несколько контейнеров-воркеров { #one-load-balancer-multiple-worker-containers } -При работе с **Kubernetes** или аналогичными системами оркестрации использование их внутренней сети позволяет иметь один **балансировщик нагрузки**, который прослушивает **главный** порт и передаёт запросы **множеству запущенных контейнеров** с Вашими приложениями. +При работе с **Kubernetes** или похожими системами управления распределёнными контейнерами их внутренние механизмы сети позволяют одному **балансировщику нагрузки**, слушающему главный **порт**, передавать запросы в **несколько контейнеров**, где запущено ваше приложение. -В каждом из контейнеров обычно работает **только один процесс** (например, процесс Uvicorn управляющий Вашим приложением FastAPI). Контейнеры могут быть **идентичными**, запущенными на основе одного и того же образа, но у каждого будут свои отдельные процесс, память и т.п. Таким образом мы получаем преимущества **распараллеливания** работы по **разным ядрам** процессора или даже **разным машинам**. +Каждый такой контейнер с вашим приложением обычно имеет **только один процесс** (например, процесс Uvicorn с вашим приложением FastAPI). Все они — **одинаковые контейнеры**, запускающие одно и то же, но у каждого свой процесс, память и т.п. Так вы используете **параллелизм** по **разным ядрам** CPU или даже **разным машинам**. -Система управления контейнерами с **балансировщиком нагрузки** будет **распределять запросы** к контейнерам с приложениями **по очереди**. То есть каждый запрос будет обработан одним из множества **одинаковых контейнеров** с одним и тем же приложением. +Система распределённых контейнеров с **балансировщиком нагрузки** будет **распределять запросы** между контейнерами с вашим приложением **по очереди**. То есть каждый запрос может обрабатываться одним из нескольких **реплицированных контейнеров**. -**Балансировщик нагрузки** может обрабатывать запросы к *разным* приложениям, расположенным в вашем кластере (например, если у них разные домены или префиксы пути) и передавать запросы нужному контейнеру с требуемым приложением. +Обычно такой **балансировщик нагрузки** может также обрабатывать запросы к *другим* приложениям в вашем кластере (например, к другому домену или под другим префиксом пути URL) и направлять их к нужным контейнерам этого *другого* приложения. -### Один процесс на контейнер +### Один процесс на контейнер { #one-process-per-container } -В этом варианте **в одном контейнере будет запущен только один процесс (Uvicorn)**, а управление изменением количества запущенных копий приложения происходит на уровне кластера. +В таком сценарии, скорее всего, вы захотите иметь **один (Uvicorn) процесс на контейнер**, так как репликация уже управляется на уровне кластера. -Здесь **не нужен** менеджер процессов типа Gunicorn, управляющий процессами Uvicorn, или же Uvicorn, управляющий другими процессами Uvicorn. Достаточно **только одного процесса Uvicorn** на контейнер (но запуск нескольких процессов не запрещён). +Поэтому в контейнере **не нужно** поднимать несколько воркеров, например через опцию командной строки `--workers`. Нужен **один процесс Uvicorn** на контейнер (но, возможно, несколько контейнеров). -Использование менеджера процессов (Gunicorn или Uvicorn) внутри контейнера только добавляет **излишнее усложнение**, так как управление следует осуществлять системой оркестрации. +Наличие отдельного менеджера процессов внутри контейнера (как при нескольких воркерах) только добавит **лишнюю сложность**, которую, вероятно, уже берёт на себя ваша кластерная система. -### Множество процессов внутри контейнера для особых случаев +### Контейнеры с несколькими процессами и особые случаи { #containers-with-multiple-processes-and-special-cases } -Безусловно, бывают **особые случаи**, когда может понадобиться внутри контейнера запускать **менеджер процессов Gunicorn**, управляющий несколькими **процессами Uvicorn**. +Конечно, есть **особые случаи**, когда может понадобиться **контейнер** с несколькими **воркерами Uvicorn** внутри. -Для таких случаев вы можете использовать **официальный Docker-образ** (прим. пер: - *здесь и далее на этой странице, если вы встретите сочетание "официальный Docker-образ" без уточнений, то автор имеет в виду именно предоставляемый им образ*), где в качестве менеджера процессов используется **Gunicorn**, запускающий несколько **процессов Uvicorn** и некоторые настройки по умолчанию, автоматически устанавливающие количество запущенных процессов в зависимости от количества ядер вашего процессора. Я расскажу вам об этом подробнее тут: [Официальный Docker-образ со встроенными Gunicorn и Uvicorn](#docker-gunicorn-uvicorn). +В таких случаях вы можете использовать опцию командной строки `--workers`, чтобы указать нужное количество воркеров: -Некоторые примеры подобных случаев: +```{ .dockerfile .annotate } +FROM python:3.9 -#### Простое приложение +WORKDIR /code -Вы можете использовать менеджер процессов внутри контейнера, если ваше приложение **настолько простое**, что у вас нет необходимости (по крайней мере, пока нет) в тщательных настройках количества процессов и вам достаточно имеющихся настроек по умолчанию (если используется официальный Docker-образ) для запуска приложения **только на одном сервере**, а не в кластере. +COPY ./requirements.txt /code/requirements.txt -#### Docker Compose +RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt -С помощью **Docker Compose** можно разворачивать несколько контейнеров на **одном сервере** (не кластере), но при это у вас не будет простого способа управления количеством запущенных контейнеров с одновременным сохранением общей сети и **балансировки нагрузки**. +COPY ./app /code/app -В этом случае можно использовать **менеджер процессов**, управляющий **несколькими процессами**, внутри **одного контейнера**. +# (1)! +CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] +``` -#### Prometheus и прочие причины +1. Здесь мы используем опцию `--workers`, чтобы установить число воркеров равным 4. -У вас могут быть и **другие причины**, когда использование **множества процессов** внутри **одного контейнера** будет проще, нежели запуск **нескольких контейнеров** с **единственным процессом** в каждом из них. +Примеры, когда это может быть уместно: -Например (в зависимости от конфигурации), у вас могут быть инструменты подобные экспортёру Prometheus, которые должны иметь доступ к **каждому запросу** приходящему в контейнер. +#### Простое приложение { #a-simple-app } -Если у вас будет **несколько контейнеров**, то Prometheus, по умолчанию, **при сборе метрик** получит их **только с одного контейнера**, который обрабатывает конкретный запрос, вместо **сбора метрик** со всех работающих контейнеров. +Вам может понадобиться менеджер процессов в контейнере, если приложение **достаточно простое**, чтобы запускаться на **одном сервере**, а не в кластере. -В таком случае может быть проще иметь **один контейнер** со **множеством процессов**, с нужным инструментом (таким как экспортёр Prometheus) в этом же контейнере и собирающем метрики со всех внутренних процессов этого контейнера. +#### Docker Compose { #docker-compose } + +Вы можете развёртывать на **одном сервере** (не кластере) с **Docker Compose**, и у вас не будет простого способа управлять репликацией контейнеров (в Docker Compose), сохраняя общую сеть и **балансировку нагрузки**. + +Тогда вы можете захотеть **один контейнер** с **менеджером процессов**, который запускает **несколько воркеров** внутри. --- -Самое главное - **ни одно** из перечисленных правил не является **высеченным на камне** и вы не обязаны слепо их повторять. вы можете использовать эти идеи при **рассмотрении вашего конкретного случая** и самостоятельно решать, какая из концепции подходит лучше: +Главное — **ни одно** из этих правил не является **строго обязательным**. Используйте эти идеи, чтобы **оценить свой конкретный случай** и решить, какой подход лучше для вашей системы, учитывая: -* Использование более безопасного протокола HTTPS -* Настройки запуска приложения -* Перезагрузка приложения -* Запуск нескольких экземпляров приложения -* Управление памятью -* Использование перечисленных функций перед запуском приложения +* Безопасность — HTTPS +* Запуск при старте +* Перезапуски +* Репликацию (количество запущенных процессов) +* Память +* Предварительные шаги перед запуском -## Управление памятью +## Память { #memory } -При **запуске одного процесса на контейнер** вы получаете относительно понятный, стабильный и ограниченный объём памяти, потребляемый одним контейнером. +Если вы запускаете **один процесс на контейнер**, у каждого контейнера будет более-менее чётко определённый, стабильный и ограниченный объём потребляемой памяти (контейнеров может быть несколько при репликации). -Вы можете установить аналогичные ограничения по памяти при конфигурировании своей системы управления контейнерами (например, **Kubernetes**). Таким образом система сможет **изменять количество контейнеров** на **доступных ей машинах** приводя в соответствие количество памяти нужной контейнерам с количеством памяти доступной в кластере (наборе доступных машин). +Затем вы можете задать такие же лимиты и требования по памяти в конфигурации вашей системы управления контейнерами (например, в **Kubernetes**). Так система сможет **реплицировать контейнеры** на **доступных машинах**, учитывая объём необходимой памяти и доступной памяти в машинах кластера. -Если у вас **простенькое** приложение, вероятно у вас не будет **необходимости** устанавливать жёсткие ограничения на выделяемую ему память. Но если приложение **использует много памяти** (например, оно использует модели **машинного обучения**), вам следует проверить, как много памяти ему требуется и отрегулировать **количество контейнеров** запущенных на **каждой машине** (может быть даже добавить машин в кластер). +Если приложение **простое**, это, вероятно, **не будет проблемой**, и жёсткие лимиты памяти можно не указывать. Но если вы **используете много памяти** (например, с моделями **Машинного обучения**), проверьте, сколько памяти потребляется, и отрегулируйте **число контейнеров** на **каждой машине** (и, возможно, добавьте машины в кластер). -Если вы запускаете **несколько процессов в контейнере**, то должны быть уверены, что эти процессы не **займут памяти больше**, чем доступно для контейнера. +Если вы запускаете **несколько процессов в контейнере**, нужно убедиться, что их суммарное потребление **не превысит доступную память**. -## Подготовительные шаги при запуске контейнеров +## Предварительные шаги перед запуском и контейнеры { #previous-steps-before-starting-and-containers } -Есть два основных подхода, которые вы можете использовать при запуске контейнеров (Docker, Kubernetes и т.п.). +Если вы используете контейнеры (например, Docker, Kubernetes), есть два основных подхода. -### Множество контейнеров +### Несколько контейнеров { #multiple-containers } -Когда вы запускаете **множество контейнеров**, в каждом из которых работает **только один процесс** (например, в кластере **Kubernetes**), может возникнуть необходимость иметь **отдельный контейнер**, который осуществит **предварительные шаги перед запуском** остальных контейнеров (например, применяет миграции к базе данных). +Если у вас **несколько контейнеров**, и, вероятно, каждый запускает **один процесс** (например, в кластере **Kubernetes**), то вы, скорее всего, захотите иметь **отдельный контейнер**, выполняющий **предварительные шаги** в одном контейнере и одном процессе **до** запуска реплицированных контейнеров-воркеров. /// info | Информация -При использовании Kubernetes, это может быть Инициализирующий контейнер. +Если вы используете Kubernetes, это, вероятно, будет Init Container. /// -При отсутствии такой необходимости (допустим, не нужно применять миграции к базе данных, а только проверить, что она готова принимать соединения), вы можете проводить такую проверку в каждом контейнере перед запуском его основного процесса и запускать все контейнеры **одновременно**. - -### Только один контейнер - -Если у вас несложное приложение для работы которого достаточно **одного контейнера**, но в котором работает **несколько процессов** (или один процесс), то прохождение предварительных шагов можно осуществить в этом же контейнере до запуска основного процесса. Официальный Docker-образ поддерживает такие действия. +Если в вашем случае нет проблемы с тем, чтобы выполнять эти предварительные шаги **многократно и параллельно** (например, вы не запускаете миграции БД, а только проверяете готовность БД), вы можете просто выполнить их в каждом контейнере прямо перед стартом основного процесса. -## Официальный Docker-образ с Gunicorn и Uvicorn +### Один контейнер { #single-container } -Я подготовил для вас Docker-образ, в который включён Gunicorn управляющий процессами (воркерами) Uvicorn, в соответствии с концепциями рассмотренными в предыдущей главе: [Рабочие процессы сервера (воркеры) - Gunicorn совместно с Uvicorn](server-workers.md){.internal-link target=_blank}. +Если у вас простая схема с **одним контейнером**, который затем запускает несколько **воркеров** (или один процесс), можно выполнить подготовительные шаги в этом же контейнере непосредственно перед запуском процесса с приложением. -Этот образ может быть полезен для ситуаций описанных тут: [Множество процессов внутри контейнера для особых случаев](#_11). - -* tiangolo/uvicorn-gunicorn-fastapi. - -/// warning | Предупреждение +### Базовый Docker-образ { #base-docker-image } -Скорее всего у вас **нет необходимости** в использовании этого образа или подобного ему и лучше создать свой образ с нуля как описано тут: [Создать Docker-образ для FastAPI](#docker-fastapi). +Ранее существовал официальный Docker-образ FastAPI: tiangolo/uvicorn-gunicorn-fastapi. Сейчас он помечен как устаревший. ⛔️ -/// +Скорее всего, вам **не стоит** использовать этот базовый образ (или какой-либо аналогичный). -В этом образе есть **автоматический** механизм подстройки для запуска **необходимого количества процессов** в соответствии с доступным количеством ядер процессора. +Если вы используете **Kubernetes** (или другое) и уже настраиваете **репликацию** на уровне кластера через несколько **контейнеров**, в этих случаях лучше **собрать образ с нуля**, как описано выше: [Создать Docker-образ для FastAPI](#build-a-docker-image-for-fastapi). -В нём установлены **разумные значения по умолчанию**, но можно изменять и обновлять конфигурацию с помощью **переменных окружения** или конфигурационных файлов. +А если вам нужны несколько воркеров, просто используйте опцию командной строки `--workers`. -Он также поддерживает прохождение **Подготовительных шагов при запуске контейнеров** при помощи скрипта. +/// note | Технические подробности -/// tip | Подсказка +Этот Docker-образ был создан в то время, когда Uvicorn не умел управлять и перезапускать «упавших» воркеров, и приходилось использовать Gunicorn вместе с Uvicorn, что добавляло заметную сложность, лишь бы Gunicorn управлял и перезапускал воркеров Uvicorn. -Для просмотра всех возможных настроек перейдите на страницу этого Docker-образа: tiangolo/uvicorn-gunicorn-fastapi. +Но теперь, когда Uvicorn (и команда `fastapi`) поддерживают `--workers`, нет причин использовать базовый Docker-образ вместо сборки своего (кода получается примерно столько же 😅). /// -### Количество процессов в официальном Docker-образе - -**Количество процессов** в этом образе **вычисляется автоматически** и зависит от доступного количества **ядер** центрального процессора. - -Это означает, что он будет пытаться **выжать** из процессора как можно больше **производительности**. - -Но вы можете изменять и обновлять конфигурацию с помощью **переменных окружения** и т.п. - -Поскольку количество процессов зависит от процессора, на котором работает контейнер, **объём потребляемой памяти** также будет зависеть от этого. - -А значит, если вашему приложению требуется много оперативной памяти (например, оно использует модели машинного обучения) и Ваш сервер имеет центральный процессор с большим количеством ядер, но **не слишком большим объёмом оперативной памяти**, то может дойти до того, что контейнер попытается занять памяти больше, чем доступно, из-за чего будет падение производительности (или сервер вовсе упадёт). 🚨 - - -### Написание `Dockerfile` - -Итак, теперь мы можем написать `Dockerfile` основанный на этом официальном Docker-образе: - -```Dockerfile -FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9 - -COPY ./requirements.txt /app/requirements.txt - -RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt - -COPY ./app /app -``` - -### Большие приложения - -Если вы успели ознакомиться с разделом [Приложения содержащие много файлов](../tutorial/bigger-applications.md){.internal-link target=_blank}, состоящие из множества файлов, Ваш Dockerfile может выглядеть так: - -```Dockerfile hl_lines="7" -FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9 - -COPY ./requirements.txt /app/requirements.txt +## Развёртывание образа контейнера { #deploy-the-container-image } -RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt - -COPY ./app /app/app -``` - -### Как им пользоваться - -Если вы используете **Kubernetes** (или что-то вроде того), скорее всего вам **не нужно** использовать официальный Docker-образ (или другой похожий) в качестве основы, так как управление **количеством запущенных контейнеров** должно быть настроено на уровне кластера. В таком случае лучше **создать образ с нуля**, как описано в разделе Создать [Docker-образ для FastAPI](#docker-fastapi). - -Официальный образ может быть полезен в отдельных случаях, описанных выше в разделе [Множество процессов внутри контейнера для особых случаев](#_11). Например, если ваше приложение **достаточно простое**, не требует запуска в кластере и способно уместиться в один контейнер, то его настройки по умолчанию будут работать довольно хорошо. Или же вы развертываете его с помощью **Docker Compose**, работаете на одном сервере и т. д - -## Развёртывание образа контейнера - -После создания образа контейнера существует несколько способов его развёртывания. +После того как у вас есть образ контейнера (Docker), его можно развёртывать несколькими способами. Например: -* С использованием **Docker Compose** при развёртывании на одном сервере -* С использованием **Kubernetes** в кластере -* С использованием режима Docker Swarm в кластере -* С использованием других инструментов, таких как Nomad -* С использованием облачного сервиса, который будет управлять разворачиванием вашего контейнера - -## Docker-образ и Poetry - -Если вы пользуетесь Poetry для управления зависимостями вашего проекта, то можете использовать многоэтапную сборку образа: - -```{ .dockerfile .annotate } -# (1) -FROM python:3.9 as requirements-stage - -# (2) -WORKDIR /tmp - -# (3) -RUN pip install poetry - -# (4) -COPY ./pyproject.toml ./poetry.lock* /tmp/ - -# (5) -RUN poetry export -f requirements.txt --output requirements.txt --without-hashes - -# (6) -FROM python:3.9 - -# (7) -WORKDIR /code - -# (8) -COPY --from=requirements-stage /tmp/requirements.txt /code/requirements.txt - -# (9) -RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt - -# (10) -COPY ./app /code/app - -# (11) -CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] -``` - -1. Это первый этап, которому мы дадим имя `requirements-stage`. - -2. Установите директорию `/tmp` в качестве рабочей директории. +* С **Docker Compose** на одном сервере +* В кластере **Kubernetes** +* В кластере Docker Swarm Mode +* С другим инструментом, например Nomad +* С облачным сервисом, который принимает ваш образ контейнера и разворачивает его - В ней будет создан файл `requirements.txt` - -3. На этом шаге установите Poetry. - -4. Скопируйте файлы `pyproject.toml` и `poetry.lock` в директорию `/tmp`. - - Поскольку название файла написано как `./poetry.lock*` (с `*` в конце), то ничего не сломается, если такой файл не будет найден. - -5. Создайте файл `requirements.txt`. - -6. Это второй (и последний) этап сборки, который и создаст окончательный образ контейнера. - -7. Установите директорию `/code` в качестве рабочей. - -8. Скопируйте файл `requirements.txt` в директорию `/code`. - - Этот файл находится в образе, созданном на предыдущем этапе, которому мы дали имя requirements-stage, потому при копировании нужно написать `--from-requirements-stage`. - -9. Установите зависимости, указанные в файле `requirements.txt`. - -10. Скопируйте папку `app` в папку `/code`. - -11. Запустите `uvicorn`, указав ему использовать объект `app`, расположенный в `app.main`. - -/// tip | Подсказка - -Если ткнёте на кружок с плюсом, то увидите объяснения, что происходит в этой строке. - -/// - -**Этапы сборки Docker-образа** являются частью `Dockerfile` и работают как **временные образы контейнеров**. Они нужны только для создания файлов, используемых в дальнейших этапах. - -Первый этап был нужен только для **установки Poetry** и **создания файла `requirements.txt`**, в которым прописаны зависимости вашего проекта, взятые из файла `pyproject.toml`. - -На **следующем этапе** `pip` будет использовать файл `requirements.txt`. - -В итоговом образе будет содержаться **только последний этап сборки**, предыдущие этапы будут отброшены. - -При использовании Poetry, имеет смысл использовать **многоэтапную сборку Docker-образа**, потому что на самом деле вам не нужен Poetry и его зависимости в окончательном образе контейнера, вам **нужен только** сгенерированный файл `requirements.txt` для установки зависимостей вашего проекта. - -А на последнем этапе, придерживаясь описанных ранее правил, создаётся итоговый образ - -### Использование прокси-сервера завершения TLS и Poetry - -И снова повторюсь, если используете прокси-сервер (балансировщик нагрузки), такой как Nginx или Traefik, добавьте в команду запуска опцию `--proxy-headers`: - -```Dockerfile -CMD ["uvicorn", "app.main:app", "--proxy-headers", "--host", "0.0.0.0", "--port", "80"] -``` +## Docker-образ с `uv` { #docker-image-with-uv } -## Резюме +Если вы используете uv для установки и управления проектом, следуйте их руководству по Docker для uv. -При помощи систем контейнеризации (таких, как **Docker** и **Kubernetes**), становится довольно просто обрабатывать все **концепции развертывания**: +## Резюме { #recap } -* Использование более безопасного протокола HTTPS -* Настройки запуска приложения -* Перезагрузка приложения -* Запуск нескольких экземпляров приложения -* Управление памятью -* Использование перечисленных функций перед запуском приложения +Используя системы контейнеризации (например, **Docker** и **Kubernetes**), довольно просто закрыть все **концепции развертывания**: -В большинстве случаев Вам, вероятно, не нужно использовать какой-либо базовый образ, **лучше создать образ контейнера с нуля** на основе официального Docker-образа Python. +* HTTPS +* Запуск при старте +* Перезапуски +* Репликация (количество запущенных процессов) +* Память +* Предварительные шаги перед запуском -Позаботившись о **порядке написания** инструкций в `Dockerfile`, вы сможете использовать **кэш Docker'а**, **минимизировав время сборки**, максимально повысив свою производительность (и не заскучать). 😎 +В большинстве случаев вы, вероятно, не захотите использовать какой-либо базовый образ, а вместо этого **соберёте образ контейнера с нуля** на основе официального Docker-образа Python. -В некоторых особых случаях вы можете использовать официальный образ Docker для FastAPI. 🤓 +Заботясь о **порядке** инструкций в `Dockerfile`и используя **кэш Docker**, вы можете **минимизировать время сборки**, чтобы повысить продуктивность (и не скучать). 😎 diff --git a/docs/ru/docs/deployment/https.md b/docs/ru/docs/deployment/https.md index d8877a9a12..05a03255e8 100644 --- a/docs/ru/docs/deployment/https.md +++ b/docs/ru/docs/deployment/https.md @@ -1,207 +1,231 @@ -# Об HTTPS +# Об HTTPS { #about-https } -Обычно представляется, что HTTPS это некая опция, которая либо "включена", либо нет. +Легко предположить, что HTTPS — это что-то, что просто «включено» или нет. -Но всё несколько сложнее. +Но на самом деле всё гораздо сложнее. -/// tip | Заметка +/// tip | Совет -Если вы торопитесь или вам не интересно, можете перейти на следующую страницу этого пошагового руководства по размещению приложений на серверах с использованием различных технологий. +Если вы торопитесь или вам это не важно, переходите к следующим разделам с пошаговыми инструкциями по настройке всего разными способами. /// -Чтобы **изучить основы HTTPS** для клиента, перейдите по ссылке https://howhttps.works/. - -Здесь же представлены некоторые концепции, которые **разработчик** должен иметь в виду при размышлениях об HTTPS: - -* Протокол HTTPS предполагает, что **серверу** нужно **располагать "сертификатами"** сгенерированными **третьей стороной**. - * На самом деле эти сертификаты **приобретены** у третьей стороны, а не "сгенерированы". -* У сертификатов есть **срок годности**. - * Срок годности **истекает**. - * По истечении срока годности их нужно **обновить**, то есть **снова получить** у третьей стороны. -* Шифрование соединения происходит **на уровне протокола TCP**. - * Протокол TCP находится на один уровень **ниже протокола HTTP**. - * Поэтому **проверка сертификатов и шифрование** происходит **до HTTP**. -* **TCP не знает о "доменах"**, но знает об IP-адресах. - * Информация о **запрашиваемом домене** извлекается из запроса **на уровне HTTP**. -* **Сертификаты HTTPS** "сертифицируют" **конкретный домен**, но проверка сертификатов и шифрование данных происходит на уровне протокола TCP, то есть **до того**, как станет известен домен-получатель данных. -* **По умолчанию** это означает, что у вас может быть **только один сертификат HTTPS на один IP-адрес**. - * Не важно, насколько большой у вас сервер и насколько маленькие приложения на нём могут быть. - * Однако, у этой проблемы есть **решение**. -* Существует **расширение** протокола **TLS** (который работает на уровне TCP, то есть до HTTP) называемое **SNI**. - * Расширение SNI позволяет одному серверу (с **одним IP-адресом**) иметь **несколько сертификатов HTTPS** и обслуживать **множество HTTPS-доменов/приложений**. - * Чтобы эта конструкция работала, **один** её компонент (программа) запущенный на сервере и слушающий **публичный IP-адрес**, должен иметь **все сертификаты HTTPS** для этого сервера. -* **После** установления защищённого соединения, протоколом передачи данных **остаётся HTTP**. - * Но данные теперь **зашифрованы**, несмотря на то, что они передаются по **протоколу HTTP**. - -Обычной практикой является иметь **одну программу/HTTP-сервер** запущенную на сервере (машине, хосте и т.д.) и **ответственную за всю работу с HTTPS**: - -* получение **зашифрованных HTTPS-запросов** -* отправка **расшифрованных HTTP запросов** в соответствующее HTTP-приложение, работающее на том же сервере (в нашем случае, это приложение **FastAPI**) -* получение **HTTP-ответа** от приложения -* **шифрование ответа** используя подходящий **сертификат HTTPS** -* отправка зашифрованного **HTTPS-ответа клиенту**. -Такой сервер часто называют **Прокси-сервер завершения работы TLS** или просто "прокси-сервер". - -Вот некоторые варианты, которые вы можете использовать в качестве такого прокси-сервера: - -* Traefik (может обновлять сертификаты) -* Caddy (может обновлять сертификаты) +Чтобы **изучить основы HTTPS** с точки зрения пользователя, загляните на https://howhttps.works/. + +Теперь, со стороны **разработчика**, вот несколько вещей, которые стоит держать в голове, размышляя об HTTPS: + +* Для HTTPS **серверу** нужно **иметь «сертификаты»**, сгенерированные **третьей стороной**. + * Эти сертификаты на самом деле **приобретаются** у третьей стороны, а не «генерируются». +* У сертификатов есть **срок действия**. + * Они **истекают**. + * После этого их нужно **обновлять**, то есть **получать заново** у третьей стороны. +* Шифрование соединения происходит на **уровне TCP**. + * Это на один уровень **ниже HTTP**. + * Поэтому **сертификаты и шифрование** обрабатываются **до HTTP**. +* **TCP не знает о «доменах»**. Только об IP-адресах. + * Информация о **конкретном домене** передаётся в **данных HTTP**. +* **HTTPS-сертификаты** «сертифицируют» **определённый домен**, но протокол и шифрование происходят на уровне TCP, **до того как** становится известен домен, с которым идёт работа. +* **По умолчанию** это означает, что вы можете иметь **лишь один HTTPS-сертификат на один IP-адрес**. + * Неважно, насколько мощный у вас сервер или насколько маленькие приложения на нём работают. + * Однако у этого есть **решение**. +* Есть **расширение** протокола **TLS** (того самого, что занимается шифрованием на уровне TCP, до HTTP) под названием **SNI**. + * Это расширение SNI позволяет одному серверу (с **одним IP-адресом**) иметь **несколько HTTPS-сертификатов** и обслуживать **несколько HTTPS-доменов/приложений**. + * Чтобы это работало, **один** компонент (программа), запущенный на сервере и слушающий **публичный IP-адрес**, должен иметь **все HTTPS-сертификаты** на этом сервере. +* **После** установления защищённого соединения, протокол обмена данными — **всё ещё HTTP**. + * Содержимое **зашифровано**, несмотря на то, что оно отправляется по **протоколу HTTP**. + +Обычно на сервере (машине, хосте и т.п.) запускают **одну программу/HTTP‑сервер**, которая **управляет всей частью, связанной с HTTPS**: принимает **зашифрованные HTTPS-запросы**, отправляет **расшифрованные HTTP-запросы** в само HTTP‑приложение, работающее на том же сервере (в нашем случае это приложение **FastAPI**), получает **HTTP-ответ** от приложения, **шифрует его** с использованием подходящего **HTTPS‑сертификата** и отправляет клиенту по **HTTPS**. Такой сервер часто называют **прокси‑сервером TLS-терминации**. + +Некоторые варианты, которые вы можете использовать как прокси‑сервер TLS-терминации: + +* Traefik (умеет обновлять сертификаты) +* Caddy (умеет обновлять сертификаты) * Nginx * HAProxy -## Let's Encrypt (центр сертификации) +## Let's Encrypt { #lets-encrypt } -До появления Let's Encrypt **сертификаты HTTPS** приходилось покупать у третьих сторон. +До появления Let's Encrypt эти **HTTPS-сертификаты** продавались доверенными третьими сторонами. -Процесс получения такого сертификата был трудоёмким, требовал предоставления подтверждающих документов и сертификаты стоили дорого. +Процесс получения таких сертификатов был неудобным, требовал бумажной волокиты, а сами сертификаты были довольно дорогими. -Но затем консорциумом Linux Foundation был создан проект **Let's Encrypt**. +Затем появился **Let's Encrypt**. -Он автоматически предоставляет **бесплатные сертификаты HTTPS**. Эти сертификаты используют все стандартные криптографические способы шифрования. Они имеют небольшой срок годности (около 3 месяцев), благодаря чему они даже **более безопасны**. +Это проект Linux Foundation. Он предоставляет **HTTPS‑сертификаты бесплатно**, в автоматическом режиме. Эти сертификаты используют стандартные криптографические механизмы и имеют короткий срок действия (около 3 месяцев), поэтому **безопасность фактически выше** благодаря уменьшенному сроку жизни. -При запросе на получение сертификата, он автоматически генерируется и домен проверяется на безопасность. Это позволяет обновлять сертификаты автоматически. +Домены безопасно проверяются, а сертификаты выдаются автоматически. Это также позволяет автоматизировать процесс их продления. -Суть идеи в автоматическом получении и обновлении этих сертификатов, чтобы все могли пользоваться **безопасным HTTPS. Бесплатно. В любое время.** +Идея — автоматизировать получение и продление сертификатов, чтобы у вас был **безопасный HTTPS, бесплатно и навсегда**. -## HTTPS для разработчиков +## HTTPS для разработчиков { #https-for-developers } -Ниже, шаг за шагом, с заострением внимания на идеях, важных для разработчика, описано, как может выглядеть HTTPS API. +Ниже приведён пример того, как может выглядеть HTTPS‑API, шаг за шагом, с акцентом на идеях, важных для разработчиков. -### Имя домена +### Имя домена { #domain-name } -Чаще всего, всё начинается с **приобретения имени домена**. Затем нужно настроить DNS-сервер (вероятно у того же провайдера, который выдал вам домен). +Чаще всего всё начинается с **приобретения** **имени домена**. Затем вы настраиваете его на DNS‑сервере (возможно, у того же облачного провайдера). -Далее, возможно, вы получаете "облачный" сервер (виртуальную машину) или что-то типа этого, у которого есть постоянный **публичный IP-адрес**. +Скорее всего, вы получите облачный сервер (виртуальную машину) или что-то подобное, и у него будет постоянный **публичный IP-адрес**. -На DNS-сервере (серверах) вам следует настроить соответствующую ресурсную запись ("`запись A`"), указав, что **Ваш домен** связан с публичным **IP-адресом вашего сервера**. +На DNS‑сервере(ах) вы настроите запись («`A record`» - запись типа A), указывающую, что **ваш домен** должен указывать на публичный **IP‑адрес вашего сервера**. -Обычно эту запись достаточно указать один раз, при первоначальной настройке всего сервера. +Обычно это делается один раз — при первоначальной настройке всего. -/// tip | Заметка +/// tip | Совет -Уровни протоколов, работающих с именами доменов, намного ниже HTTPS, но об этом следует упомянуть здесь, так как всё зависит от доменов и IP-адресов. +Часть про доменное имя относится к этапам задолго до HTTPS, но так как всё зависит от домена и IP‑адреса, здесь стоит это упомянуть. /// -### DNS +### DNS { #dns } -Теперь давайте сфокусируемся на работе с HTTPS. +Теперь сфокусируемся на собственно частях, связанных с HTTPS. -Всё начинается с того, что браузер спрашивает у **DNS-серверов**, какой **IP-адрес связан с доменом**, для примера возьмём домен `someapp.example.com`. +Сначала браузер спросит у **DNS‑серверов**, какой **IP соответствует домену**, в нашем примере `someapp.example.com`. -DNS-сервера присылают браузеру определённый **IP-адрес**, тот самый публичный IP-адрес вашего сервера, который вы указали в ресурсной "записи А" при настройке. +DNS‑серверы ответят браузеру, какой **конкретный IP‑адрес** использовать. Это будет публичный IP‑адрес вашего сервера, который вы указали в настройках DNS. -### Рукопожатие TLS +### Начало TLS-рукопожатия { #tls-handshake-start } -В дальнейшем браузер будет взаимодействовать с этим IP-адресом через **port 443** (общепринятый номер порта для HTTPS). +Далее браузер будет общаться с этим IP‑адресом на **порту 443** (порт HTTPS). -Первым шагом будет установление соединения между клиентом (браузером) и сервером и выбор криптографического ключа (для шифрования). +Первая часть взаимодействия — установить соединение между клиентом и сервером и договориться о криптографических ключах и т.п. -Эта часть клиент-серверного взаимодействия устанавливает TLS-соединение и называется **TLS-рукопожатием**. +Это взаимодействие клиента и сервера для установления TLS‑соединения называется **TLS‑рукопожатием**. -### TLS с расширением SNI +### TLS с расширением SNI { #tls-with-sni-extension } -На сервере **только один процесс** может прослушивать определённый **порт** определённого **IP-адреса**. На сервере могут быть и другие процессы, слушающие другие порты этого же IP-адреса, но никакой процесс не может быть привязан к уже занятой комбинации IP-адрес:порт. Эта комбинация называется "сокет". +На сервере **только один процесс** может слушать конкретный **порт** на конкретном **IP‑адресе**. Могут быть другие процессы, слушающие другие порты на том же IP‑адресе, но не более одного процесса на каждую комбинацию IP‑адреса и порта. -По умолчанию TLS (HTTPS) использует порт `443`. Потому этот же порт будем использовать и мы. +По умолчанию TLS (HTTPS) использует порт `443`. Значит, он нам и нужен. -И раз уж только один процесс может слушать этот порт, то это будет процесс **прокси-сервера завершения работы TLS**. +Так как только один процесс может слушать этот порт, делать это будет **прокси‑сервер TLS-терминации**. -Прокси-сервер завершения работы TLS будет иметь доступ к одному или нескольким **TLS-сертификатам** (сертификаты HTTPS). +У прокси‑сервера TLS-терминации будет доступ к одному или нескольким **TLS‑сертификатам** (HTTPS‑сертификатам). -Используя **расширение SNI** упомянутое выше, прокси-сервер из имеющихся сертификатов TLS (HTTPS) выберет тот, который соответствует имени домена, указанному в запросе от клиента. +Используя **расширение SNI**, упомянутое выше, прокси‑сервер TLS-терминации определит, какой из доступных TLS (HTTPS)‑сертификатов нужно использовать для этого соединения, выбрав тот, который соответствует домену, ожидаемому клиентом. -То есть будет выбран сертификат для домена `someapp.example.com`. +В нашем случае это будет сертификат для `someapp.example.com`. -Клиент уже **доверяет** тому, кто выдал этот TLS-сертификат (в нашем случае - Let's Encrypt, но мы ещё обсудим это), потому может **проверить**, действителен ли полученный от сервера сертификат. +Клиент уже **доверяет** организации, выдавшей этот TLS‑сертификат (в нашем случае — Let's Encrypt, но об этом позже), поэтому может **проверить**, что сертификат действителен. -Затем, используя этот сертификат, клиент и прокси-сервер **выбирают способ шифрования** данных для устанавливаемого **TCP-соединения**. На этом операция **TLS-рукопожатия** завершена. +Затем, используя сертификат, клиент и прокси‑сервер TLS-терминации **договариваются о способе шифрования** остальной **TCP‑коммуникации**. На этом **TLS‑рукопожатие** завершено. -В дальнейшем клиент и сервер будут взаимодействовать по **зашифрованному TCP-соединению**, как предлагается в протоколе TLS. И на основе этого TCP-соедениния будет создано **HTTP-соединение**. +После этого у клиента и сервера есть **зашифрованное TCP‑соединение** — это и предоставляет TLS. И они могут использовать это соединение, чтобы начать собственно **HTTP‑обмен**. -Таким образом, **HTTPS** это тот же **HTTP**, но внутри **безопасного TLS-соединения** вместо чистого (незашифрованного) TCP-соединения. +Собственно, **HTTPS** — это обычный **HTTP** внутри **защищённого TLS‑соединения**, вместо чистого (незашифрованного) TCP‑соединения. -/// tip | Заметка +/// tip | Совет -Обратите внимание, что шифрование происходит на **уровне TCP**, а не на более высоком уровне HTTP. +Обратите внимание, что шифрование обмена происходит на **уровне TCP**, а не на уровне HTTP. /// -### HTTPS-запрос +### HTTPS‑запрос { #https-request } -Теперь, когда между клиентом и сервером (в нашем случае, браузером и прокси-сервером) создано **зашифрованное TCP-соединение**, они могут начать **обмен данными по протоколу HTTP**. +Теперь, когда у клиента и сервера (конкретно у браузера и прокси‑сервера TLS-терминации) есть **зашифрованное TCP‑соединение**, они могут начать **HTTP‑обмен**. -Так клиент отправляет **HTTPS-запрос**. То есть обычный HTTP-запрос, но через зашифрованное TLS-содинение. +Клиент отправляет **HTTPS‑запрос**. Это обычный HTTP‑запрос через зашифрованное TLS‑соединение. -### Расшифровка запроса +### Расшифровка запроса { #decrypt-the-request } -Прокси-сервер, используя согласованный с клиентом ключ, расшифрует полученный **зашифрованный запрос** и передаст **обычный (незашифрованный) HTTP-запрос** процессу, запускающему приложение (например, процессу Uvicorn запускающему приложение FastAPI). +Прокси‑сервер TLS-терминации использует согласованное шифрование, чтобы **расшифровать запрос**, и передаёт **обычный (расшифрованный) HTTP‑запрос** процессу, запускающему приложение (например, процессу с Uvicorn, который запускает приложение FastAPI). -### HTTP-ответ +### HTTP‑ответ { #http-response } -Приложение обработает запрос и вернёт **обычный (незашифрованный) HTTP-ответ** прокси-серверу. +Приложение обработает запрос и отправит **обычный (незашифрованный) HTTP‑ответ** прокси‑серверу TLS-терминации. -### HTTPS-ответ +### HTTPS‑ответ { #https-response } -Пркоси-сервер **зашифрует ответ** используя ранее согласованный с клиентом способ шифрования (которые содержатся в сертификате для домена `someapp.example.com`) и отправит его браузеру. +Затем прокси‑сервер TLS-терминации **зашифрует ответ** с использованием ранее согласованного способа шифрования (который начали использовать для сертификата для `someapp.example.com`) и отправит его обратно в браузер. -Наконец, браузер проверит ответ, в том числе, что тот зашифрован с нужным ключом, **расшифрует его** и обработает. +Далее браузер проверит, что ответ корректен и зашифрован правильным криптографическим ключом и т.п., затем **расшифрует ответ** и обработает его. -Клиент (браузер) знает, что ответ пришёл от правильного сервера, так как использует методы шифрования, согласованные ими раннее через **HTTPS-сертификат**. +Клиент (браузер) узнает, что ответ пришёл от правильного сервера, потому что используется способ шифрования, о котором они договорились ранее с помощью **HTTPS‑сертификата**. -### Множество приложений +### Несколько приложений { #multiple-applications } -На одном и том же сервере (или серверах) можно разместить **множество приложений**, например, другие программы с API или базы данных. +На одном и том же сервере (или серверах) могут работать **несколько приложений**, например другие программы с API или база данных. -Напомню, что только один процесс (например, прокси-сервер) может прослушивать определённый порт определённого IP-адреса. -Но другие процессы и приложения тоже могут работать на этом же сервере (серверах), если они не пытаются использовать уже занятую **комбинацию IP-адреса и порта** (сокет). +Только один процесс может обрабатывать конкретную комбинацию IP и порта (в нашем примере — прокси‑сервер TLS-терминации), но остальные приложения/процессы тоже могут работать на сервере(ах), пока они не пытаются использовать ту же **комбинацию публичного IP и порта**. -Таким образом, сервер завершения TLS может обрабатывать HTTPS-запросы и использовать сертификаты для **множества доменов** или приложений и передавать запросы правильным адресатам (другим приложениям). +Таким образом, прокси‑сервер TLS-терминации может обрабатывать HTTPS и сертификаты для **нескольких доменов** (для нескольких приложений), а затем передавать запросы нужному приложению в каждом случае. -### Обновление сертификата +### Продление сертификата { #certificate-renewal } -В недалёком будущем любой сертификат станет **просроченным** (примерно через три месяца после получения). +Со временем каждый сертификат **истечёт** (примерно через 3 месяца после получения). -Когда это произойдёт, можно запустить другую программу, которая подключится к Let's Encrypt и обновит сертификат(ы). Существуют прокси-серверы, которые могут сделать это действие самостоятельно. +Затем будет другая программа (иногда это отдельная программа, иногда — тот же прокси‑сервер TLS-терминации), которая свяжется с Let's Encrypt и продлит сертификат(ы). -**TLS-сертификаты** не привязаны к IP-адресу, но **связаны с именем домена**. +**TLS‑сертификаты** **связаны с именем домена**, а не с IP‑адресом. -Так что при обновлении сертификатов программа должна **подтвердить** центру сертификации (Let's Encrypt), что обновление запросил **"владелец", который контролирует этот домен**. +Поэтому, чтобы продлить сертификаты, программа продления должна **доказать** удостоверяющему центру (Let's Encrypt), что она действительно **«владеет» и контролирует этот домен**. -Есть несколько путей осуществления этого. Самые популярные из них: +Для этого, учитывая разные потребности приложений, есть несколько способов. Популярные из них: -* **Изменение записей DNS**. - * Для такого варианта Ваша программа обновления должна уметь работать с API DNS-провайдера, обслуживающего Ваши DNS-записи. Не у всех провайдеров есть такой API, так что этот способ не всегда применим. -* **Запуск в качестве программы-сервера** (как минимум, на время обновления сертификатов) на публичном IP-адресе домена. - * Как уже не раз упоминалось, только один процесс может прослушивать определённый порт определённого IP-адреса. - * Это одна из причин использования прокси-сервера ещё и в качестве программы обновления сертификатов. - * В случае, если обновлением сертификатов занимается другая программа, вам понадобится остановить прокси-сервер, запустить программу обновления сертификатов на сокете, предназначенном для прокси-сервера, настроить прокси-сервер на работу с новыми сертификатами и перезапустить его. Эта схема далека от идеальной, так как Ваши приложения будут недоступны на время отключения прокси-сервера. +* **Изменить некоторые DNS‑записи**. + * Для этого программа продления должна поддерживать API DNS‑провайдера, поэтому, в зависимости от используемого провайдера DNS, этот вариант может быть доступен или нет. +* **Запуститься как сервер** (как минимум на время получения сертификатов) на публичном IP‑адресе, связанном с доменом. + * Как сказано выше, только один процесс может слушать конкретный IP и порт. + * Это одна из причин, почему очень удобно, когда тот же прокси‑сервер TLS-терминации также занимается процессом продления сертификатов. + * В противном случае вам, возможно, придётся временно остановить прокси‑сервер TLS-терминации, запустить программу продления для получения сертификатов, затем настроить их в прокси‑сервере TLS-терминации и перезапустить его. Это не идеально, так как ваше приложение(я) будут недоступны, пока прокси‑сервер TLS-терминации остановлен. -Весь этот процесс обновления, одновременный с обслуживанием запросов, является одной из основных причин, по которой желательно иметь **отдельную систему для работы с HTTPS** в виде прокси-сервера завершения TLS, а не просто использовать сертификаты TLS непосредственно с сервером приложений (например, Uvicorn). +Весь этот процесс продления, совмещённый с обслуживанием приложения, — одна из главных причин иметь **отдельную систему для работы с HTTPS** в виде прокси‑сервера TLS-терминации, вместо использования TLS‑сертификатов напрямую в сервере приложения (например, Uvicorn). -## Резюме +## Пересылаемые HTTP-заголовки прокси { #proxy-forwarded-headers } -Наличие **HTTPS** очень важно и довольно **критично** в большинстве случаев. Однако, Вам, как разработчику, не нужно тратить много сил на это, достаточно **понимать эти концепции** и принципы их работы. +Когда вы используете прокси для обработки HTTPS, ваш **сервер приложения** (например, Uvicorn через FastAPI CLI) ничего не знает о процессе HTTPS, он общается обычным HTTP с **прокси‑сервером TLS-терминации**. -Но узнав базовые основы **HTTPS** вы можете легко совмещать разные инструменты, которые помогут вам в дальнейшей разработке. +Обычно этот **прокси** на лету добавляет некоторые HTTP‑заголовки перед тем, как переслать запрос на **сервер приложения**, чтобы тот знал, что запрос был **проксирован**. -В следующих главах я покажу вам несколько примеров, как настраивать **HTTPS** для приложений **FastAPI**. 🔒 +/// note | Технические детали + +Заголовки прокси: + +* X-Forwarded-For +* X-Forwarded-Proto +* X-Forwarded-Host + +/// + +Тем не менее, так как **сервер приложения** не знает, что он находится за доверенным **прокси**, по умолчанию он не будет доверять этим заголовкам. + +Но вы можете настроить **сервер приложения**, чтобы он доверял *пересылаемым* заголовкам, отправленным **прокси**. Если вы используете FastAPI CLI, вы можете использовать *опцию CLI* `--forwarded-allow-ips`, чтобы указать, с каких IP‑адресов следует доверять этим *пересылаемым* заголовкам. + +Например, если **сервер приложения** получает запросы только от доверенного **прокси**, вы можете установить `--forwarded-allow-ips="*"`, чтобы доверять всем входящим IP, так как он всё равно будет получать запросы только с IP‑адреса, используемого **прокси**. + +Таким образом, приложение сможет знать свой публичный URL, использует ли оно HTTPS, какой домен и т.п. + +Это будет полезно, например, для корректной обработки редиректов. + +/// tip | Совет + +Подробнее об этом вы можете узнать в документации: [За прокси — Включить пересылаемые заголовки прокси](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank} + +/// + +## Резюме { #recap } + +Наличие **HTTPS** очень важно и во многих случаях довольно **критично**. Большая часть усилий, которые вам, как разработчику, нужно приложить вокруг HTTPS, — это просто **понимание этих концепций** и того, как они работают. + +Зная базовую информацию о **HTTPS для разработчиков**, вы сможете легко комбинировать и настраивать разные инструменты, чтобы управлять всем этим простым способом. + +В некоторых из следующих глав я покажу вам несколько конкретных примеров настройки **HTTPS** для приложений **FastAPI**. 🔒 diff --git a/docs/ru/docs/deployment/index.md b/docs/ru/docs/deployment/index.md index e88ddc3e2c..c85fa0d529 100644 --- a/docs/ru/docs/deployment/index.md +++ b/docs/ru/docs/deployment/index.md @@ -1,16 +1,16 @@ -# Развёртывание +# Развёртывание { #deployment } Развернуть приложение **FastAPI** довольно просто. -## Да что такое это ваше - "развёртывание"?! +## Что означает развёртывание { #what-does-deployment-mean } Термин **развёртывание** (приложения) означает выполнение необходимых шагов, чтобы сделать приложение **доступным для пользователей**. -Обычно **веб-приложения** размещают на удалённом компьютере с серверной программой, которая обеспечивает хорошую производительность, стабильность и т. д., Чтобы ваши пользователи могли эффективно, беспрерывно и беспроблемно обращаться к приложению. +Для **веб-API** это обычно означает размещение его на **удалённой машине** с **серверной программой**, обеспечивающей хорошую производительность, стабильность и т.д., чтобы ваши **пользователи** могли **получать доступ** к приложению эффективно и без перебоев или проблем. -Это отличается от **разработки**, когда вы постоянно меняете код, делаете в нём намеренные ошибки и исправляете их, останавливаете и перезапускаете сервер разработки и т. д. +Это отличается от этапов **разработки**, когда вы постоянно меняете код, ломаете его и исправляете, останавливаете и перезапускаете сервер разработки и т.д. -## Стратегии развёртывания +## Стратегии развёртывания { #deployment-strategies } В зависимости от вашего конкретного случая, есть несколько способов сделать это. diff --git a/docs/ru/docs/deployment/manually.md b/docs/ru/docs/deployment/manually.md index 9b1d32be80..37fed5780e 100644 --- a/docs/ru/docs/deployment/manually.md +++ b/docs/ru/docs/deployment/manually.md @@ -1,163 +1,157 @@ -# Запуск сервера вручную - Uvicorn +# Запуск сервера вручную { #run-a-server-manually } -Для запуска приложения **FastAPI** на удалённой серверной машине вам необходим программный сервер, поддерживающий протокол ASGI, такой как **Uvicorn**. +## Используйте команду `fastapi run` { #use-the-fastapi-run-command } -Существует три наиболее распространённые альтернативы: +Коротко: используйте `fastapi run`, чтобы запустить ваше приложение FastAPI: -* Uvicorn: высокопроизводительный ASGI сервер. -* Hypercorn: ASGI сервер, помимо прочего поддерживающий HTTP/2 и Trio. -* Daphne: ASGI сервер, созданный для Django Channels. - -## Сервер как машина и сервер как программа - -В этих терминах есть некоторые различия и вам следует запомнить их. 💡 - -Слово "**сервер**" чаще всего используется в двух контекстах: +
-- удалённый или расположенный в "облаке" компьютер (физическая или виртуальная машина). -- программа, запущенная на таком компьютере (например, Uvicorn). +```console +$ fastapi run main.py -Просто запомните, если вам встретился термин "сервер", то обычно он подразумевает что-то из этих двух смыслов. + FastAPI Starting production server 🚀 -Когда имеют в виду именно удалённый компьютер, часто говорят просто **сервер**, но ещё его называют **машина**, **ВМ** (виртуальная машина), **нода**. Все эти термины обозначают одно и то же - удалённый компьютер, обычно под управлением Linux, на котором вы запускаете программы. + Searching for package file structure from directories + with __init__.py files + Importing from /home/user/code/awesomeapp -## Установка программного сервера + module 🐍 main.py -Вы можете установить сервер, совместимый с протоколом ASGI, так: + code Importing the FastAPI app object from the module with + the following code: -//// tab | Uvicorn + from main import app -* Uvicorn, очень быстрый ASGI сервер, основанный на библиотеках uvloop и httptools. + app Using import string: main:app -
+ server Server started at http://0.0.0.0:8000 + server Documentation at http://0.0.0.0:8000/docs -```console -$ pip install "uvicorn[standard]" + Logs: ----> 100% + INFO Started server process [2306215] + INFO Waiting for application startup. + INFO Application startup complete. + INFO Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C + to quit) ```
-/// tip | Подсказка - -С опцией `standard`, Uvicorn будет устанавливаться и использоваться с некоторыми дополнительными рекомендованными зависимостями. - -В них входит `uvloop`, высокопроизводительная замена `asyncio`, которая значительно ускоряет работу асинхронных программ. - -/// - -//// +В большинстве случаев этого достаточно. 😎 -//// tab | Hypercorn +Этой командой, например, можно запускать приложение **FastAPI** в контейнере, на сервере и т.д. -* Hypercorn, ASGI сервер, поддерживающий протокол HTTP/2. +## ASGI‑серверы { #asgi-servers } -
+Давайте немного углубимся в детали. -```console -$ pip install hypercorn +FastAPI использует стандарт для построения Python‑веб‑фреймворков и серверов под названием ASGI. FastAPI — ASGI-веб‑фреймворк. ----> 100% -``` +Главное, что вам нужно, чтобы запустить приложение **FastAPI** (или любое другое ASGI‑приложение) на удалённой серверной машине, — это программа ASGI‑сервера, такая как **Uvicorn**; именно он используется по умолчанию в команде `fastapi`. -
+Есть несколько альтернатив, например: -...или какой-либо другой ASGI сервер. +* Uvicorn: высокопроизводительный ASGI‑сервер. +* Hypercorn: ASGI‑сервер, среди прочего совместимый с HTTP/2 и Trio. +* Daphne: ASGI‑сервер, созданный для Django Channels. +* Granian: HTTP‑сервер на Rust для Python‑приложений. +* NGINX Unit: NGINX Unit — лёгкая и многофункциональная среда выполнения веб‑приложений. -//// +## Сервер как машина и сервер как программа { #server-machine-and-server-program } -## Запуск серверной программы +Есть небольшой нюанс в терминологии, о котором стоит помнить. 💡 -Затем запустите ваше приложение так же, как было указано в руководстве ранее, но без опции `--reload`: +Слово «сервер» обычно используют и для обозначения удалённого/облачного компьютера (физической или виртуальной машины), и для программы, работающей на этой машине (например, Uvicorn). -//// tab | Uvicorn +Имейте в виду, что слово «сервер» в целом может означать любое из этих двух. -
+Когда речь идёт об удалённой машине, её зачастую называют **сервер**, а также **машина**, **VM** (виртуальная машина), **нода**. Всё это — варианты названия удалённой машины, обычно под управлением Linux, на которой вы запускаете программы. -```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +## Установка серверной программы { #install-the-server-program } -INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) -``` +При установке FastAPI он поставляется с продакшн‑сервером Uvicorn, и вы можете запустить его командой `fastapi run`. -
+Но вы также можете установить ASGI‑сервер вручную. -//// +Создайте [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активируйте его и затем установите серверное приложение. -//// tab | Hypercorn +Например, чтобы установить Uvicorn:
```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% ```
-//// +Аналогично устанавливаются и другие ASGI‑серверы. -/// warning | Предупреждение +/// tip | Совет -Не забудьте удалить опцию `--reload`, если ранее пользовались ею. +С добавлением `standard` Uvicorn установит и будет использовать ряд рекомендованных дополнительных зависимостей. -Включение опции `--reload` требует дополнительных ресурсов, влияет на стабильность работы приложения и может повлечь прочие неприятности. +В их числе `uvloop` — высокопроизводительная замена `asyncio`, дающая серьёзный прирост производительности при параллельной работе. -Она сильно помогает во время **разработки**, но **не следует** использовать её при **реальной работе** приложения. +Если вы устанавливаете FastAPI, например так: `pip install "fastapi[standard]"`, вы уже получаете и `uvicorn[standard]`. /// -## Hypercorn с Trio - -Starlette и **FastAPI** основаны на AnyIO, которая делает их совместимыми как с asyncio - стандартной библиотекой Python, так и с Trio. - +## Запуск серверной программы { #run-the-server-program } -Тем не менее Uvicorn совместим только с asyncio и обычно используется совместно с `uvloop`, высокопроизводительной заменой `asyncio`. - -Но если вы хотите использовать **Trio** напрямую, то можете воспользоваться **Hypercorn**, так как они совместимы. ✨ - -### Установка Hypercorn с Trio - -Для начала, вам нужно установить Hypercorn с поддержкой Trio: +Если вы установили ASGI‑сервер вручную, обычно нужно передать строку импорта в специальном формате, чтобы он смог импортировать ваше приложение FastAPI:
```console -$ pip install "hypercorn[trio]" ----> 100% +$ uvicorn main:app --host 0.0.0.0 --port 80 + +INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ```
-### Запуск с Trio +/// note | Примечание -Далее запустите Hypercorn с опцией `--worker-class` и аргументом `trio`: +Команда `uvicorn main:app` означает: -
+* `main`: файл `main.py` (Python‑«модуль»). +* `app`: объект, созданный в `main.py` строкой `app = FastAPI()`. -```console -$ hypercorn main:app --worker-class trio +Эквивалентно: + +```Python +from main import app ``` -
+/// -Hypercorn, в свою очередь, запустит ваше приложение использующее Trio. +У каждого альтернативного ASGI‑сервера будет похожая команда; подробнее см. в их документации. -Таким образом, вы сможете использовать Trio в своём приложении. Но лучше использовать AnyIO, для сохранения совместимости и с Trio, и с asyncio. 🎉 +/// warning | Предупреждение + +Uvicorn и другие серверы поддерживают опцию `--reload`, полезную в период разработки. + +Опция `--reload` потребляет значительно больше ресурсов, менее стабильна и т.п. + +Она сильно помогает во время **разработки**, но в **продакшн** её использовать **не следует**. + +/// -## Концепции развёртывания +## Концепции развёртывания { #deployment-concepts } -В вышеприведённых примерах серверные программы (например Uvicorn) запускали только **один процесс**, принимающий входящие запросы с любого IP (на это указывал аргумент `0.0.0.0`) на определённый порт (в примерах мы указывали порт `80`). +В этих примерах серверная программа (например, Uvicorn) запускает **один процесс**, слушающий все IP‑адреса (`0.0.0.0`) на заранее заданном порту (например, `80`). -Это основная идея. Но возможно, вы озаботитесь добавлением дополнительных возможностей, таких как: +Это базовая идея. Но, вероятно, вам понадобится позаботиться и о некоторых дополнительных вещах, например: -* Использование более безопасного протокола HTTPS -* Настройки запуска приложения -* Перезагрузка приложения -* Запуск нескольких экземпляров приложения -* Управление памятью -* Использование перечисленных функций перед запуском приложения. +* Безопасность — HTTPS +* Запуск при старте системы +* Перезапуски +* Репликация (количество запущенных процессов) +* Память +* Предварительные шаги перед запуском -Я расскажу вам больше о каждой из этих концепций в следующих главах, с конкретными примерами стратегий работы с ними. 🚀 +В следующих главах я расскажу подробнее про каждую из этих концепций, о том, как о них думать, и приведу конкретные примеры со стратегиями, как с ними работать. 🚀 diff --git a/docs/ru/docs/deployment/versions.md b/docs/ru/docs/deployment/versions.md index e8db30ce89..58d5aa110d 100644 --- a/docs/ru/docs/deployment/versions.md +++ b/docs/ru/docs/deployment/versions.md @@ -1,42 +1,42 @@ -# О версиях FastAPI +# О версиях FastAPI { #about-fastapi-versions } -**FastAPI** уже используется в продакшене во многих приложениях и системах. Покрытие тестами поддерживается на уровне 100%. Однако его разработка все еще продолжается. +**FastAPI** уже используется в продакшене во многих приложениях и системах. Покрытие тестами поддерживается на уровне 100%. Но его разработка всё ещё движется быстрыми темпами. Часто добавляются новые функции, регулярно исправляются баги, код продолжает постоянно совершенствоваться. -По указанным причинам текущие версии до сих пор `0.x.x`. Это говорит о том, что каждая версия может содержать обратно несовместимые изменения, следуя соглашению о Семантическом Версионировании. +По указанным причинам текущие версии до сих пор `0.x.x`. Это говорит о том, что каждая версия может содержать обратно несовместимые изменения, следуя Семантическому версионированию. -Уже сейчас вы можете создавать приложения в продакшене, используя **FastAPI** (и скорее всего так и делаете), главное убедиться в том, что вы используете версию, которая корректно работает с вашим кодом. +Уже сейчас вы можете создавать приложения в продакшене, используя **FastAPI** (и скорее всего так и делаете), главное убедиться в том, что вы используете версию, которая корректно работает с вашим кодом. -## Закрепите вашу версию `fastapi` +## Закрепите вашу версию `fastapi` { #pin-your-fastapi-version } Первым делом вам следует "закрепить" конкретную последнюю используемую версию **FastAPI**, которая корректно работает с вашим приложением. -Например, в своём приложении вы используете версию `0.45.0`. +Например, в своём приложении вы используете версию `0.112.0`. Если вы используете файл `requirements.txt`, вы можете указать версию следующим способом: ```txt -fastapi==0.45.0 +fastapi[standard]==0.112.0 ``` -это означает, что вы будете использовать именно версию `0.45.0`. +это означает, что вы будете использовать именно версию `0.112.0`. Или вы можете закрепить версию следующим способом: ```txt -fastapi>=0.45.0,<0.46.0 +fastapi[standard]>=0.112.0,<0.113.0 ``` -это значит, что вы используете версии `0.45.0` или выше, но меньше чем `0.46.0`. Например, версия `0.45.2` все еще будет подходить. +это значит, что вы используете версии `0.112.0` или выше, но меньше чем `0.113.0`. Например, версия `0.112.2` всё ещё будет подходить. -Если вы используете любой другой инструмент для управления зависимостями, например Poetry, Pipenv или др., у них у всех имеется способ определения специфической версии для ваших пакетов. +Если вы используете любой другой инструмент для управления установками/зависимостями, например `uv`, Poetry, Pipenv или др., у них у всех имеется способ определения специфической версии для ваших пакетов. -## Доступные версии +## Доступные версии { #available-versions } -Вы можете посмотреть доступные версии (например, проверить последнюю на данный момент) в [примечаниях к выпуску](../release-notes.md){.internal-link target=_blank}. +Вы можете посмотреть доступные версии (например, проверить последнюю на данный момент) в [Примечаниях к выпуску](../release-notes.md){.internal-link target=_blank}. -## О версиях +## О версиях { #about-versions } Следуя соглашению о Семантическом Версионировании, любые версии ниже `1.0.0` потенциально могут добавить обратно несовместимые изменения. @@ -44,7 +44,7 @@ FastAPI следует соглашению в том, что любые изм /// tip | Подсказка -"ПАТЧ" - это последнее число. Например, в `0.2.3`, ПАТЧ-версия - это `3`. +"ПАТЧ" — это последнее число. Например, в `0.2.3`, ПАТЧ-версия — это `3`. /// @@ -58,11 +58,11 @@ fastapi>=0.45.0,<0.46.0 /// tip | Подсказка -"МИНОРНАЯ" версия - это число в середине. Например, в `0.2.3` МИНОРНАЯ версия - это `2`. +"МИНОРНАЯ" версия — это число в середине. Например, в `0.2.3` МИНОРНАЯ версия — это `2`. /// -## Обновление версий FastAPI +## Обновление версий FastAPI { #upgrading-the-fastapi-versions } Вам следует добавить тесты для вашего приложения. @@ -70,9 +70,9 @@ fastapi>=0.45.0,<0.46.0 После создания тестов вы можете обновить свою версию **FastAPI** до более новой. После этого следует убедиться, что ваш код работает корректно, запустив тесты. -Если все работает корректно, или после внесения необходимых изменений все ваши тесты проходят, только тогда вы можете закрепить вашу новую версию `fastapi`. +Если всё работает корректно, или после внесения необходимых изменений все ваши тесты проходят, только тогда вы можете закрепить вашу новую версию `fastapi`. -## О Starlette +## О Starlette { #about-starlette } Не следует закреплять версию `starlette`. @@ -80,14 +80,14 @@ fastapi>=0.45.0,<0.46.0 Так что решение об используемой версии Starlette, вы можете оставить **FastAPI**. -## О Pydantic +## О Pydantic { #about-pydantic } Pydantic включает свои собственные тесты для **FastAPI**, так что новые версии Pydantic (выше `1.0.0`) всегда совместимы с FastAPI. -Вы можете закрепить любую версию Pydantic, которая вам подходит, выше `1.0.0` и ниже `2.0.0`. +Вы можете закрепить любую версию Pydantic, которая вам подходит, выше `1.0.0`. Например: ```txt -pydantic>=1.2.0,<2.0.0 +pydantic>=2.7.0,<3.0.0 ``` diff --git a/docs/ru/docs/environment-variables.md b/docs/ru/docs/environment-variables.md index a6c7b0c77a..6291b79d26 100644 --- a/docs/ru/docs/environment-variables.md +++ b/docs/ru/docs/environment-variables.md @@ -1,6 +1,6 @@ -# Переменные окружения +# Переменные окружения { #environment-variables } -/// tip +/// tip | Совет Если вы уже знаете, что такое «переменные окружения» и как их использовать, можете пропустить это. @@ -10,7 +10,7 @@ Переменные окружения могут быть полезны для работы с **настройками** приложений, как часть **установки** Python и т.д. -## Создание и использование переменных окружения +## Создание и использование переменных окружения { #create-and-use-env-vars } Можно **создавать** и использовать переменные окружения в **оболочке (терминале)**, не прибегая к помощи Python: @@ -50,7 +50,7 @@ Hello Wade Wilson //// -## Чтение переменных окружения в python +## Чтение переменных окружения в python { #read-env-vars-in-python } Так же существует возможность создания переменных окружения **вне** Python, в терминале (или любым другим способом), а затем **чтения их в Python**. @@ -63,11 +63,12 @@ name = os.getenv("MY_NAME", "World") print(f"Hello {name} from Python") ``` -/// tip +/// tip | Совет -Второй аргумент `os.getenv()` - это возвращаемое по умолчанию значение. +Второй аргумент `os.getenv()` - это возвращаемое по умолчанию значение. Если значение не указано, то по умолчанию оно равно `None`. В данном случае мы указываем `«World»` в качестве значения по умолчанию. + /// Затем можно запустить эту программу на Python: @@ -150,13 +151,13 @@ Hello World from Python
-/// tip +/// tip | Совет Подробнее об этом можно прочитать на сайте The Twelve-Factor App: Config. /// -## Типизация и Валидация +## Типизация и Валидация { #types-and-validation } Эти переменные окружения могут работать только с **текстовыми строками**, поскольку они являются внешними по отношению к Python и должны быть совместимы с другими программами и остальной системой (и даже с различными операционными системами, такими как Linux, Windows, macOS). @@ -164,7 +165,7 @@ Hello World from Python Подробнее об использовании переменных окружения для работы с **настройками приложения** вы узнаете в [Расширенное руководство пользователя - Настройки и переменные среды](./advanced/settings.md){.internal-link target=_blank}. -## Переменная окружения `PATH` +## Переменная окружения `PATH` { #path-environment-variable } Существует **специальная** переменная окружения **`PATH`**, которая используется операционными системами (Linux, macOS, Windows) для поиска программ для запуска. @@ -208,7 +209,7 @@ C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System3 Если она ее находит, то **использует ее**. В противном случае она продолжает искать в **других каталогах**. -### Установка Python и обновление `PATH` +### Установка Python и обновление `PATH` { #installing-python-and-updating-the-path } При установке Python вас могут спросить, нужно ли обновить переменную окружения `PATH`. @@ -286,7 +287,7 @@ $ C:\opt\custompython\bin\python Эта информация будет полезна при изучении [Виртуальных окружений](virtual-environments.md){.internal-link target=_blank}. -## Вывод +## Вывод { #conclusion } Благодаря этому вы должны иметь базовое представление о том, что такое **переменные окружения** и как использовать их в Python. diff --git a/docs/ru/docs/fastapi-cli.md b/docs/ru/docs/fastapi-cli.md index c0be4a5df3..156e3d2007 100644 --- a/docs/ru/docs/fastapi-cli.md +++ b/docs/ru/docs/fastapi-cli.md @@ -1,4 +1,4 @@ -# FastAPI CLI +# FastAPI CLI { #fastapi-cli } **FastAPI CLI** это программа командной строки, которую вы можете использовать для запуска вашего FastAPI приложения, для управления FastAPI-проектом, а также для многих других вещей. @@ -50,26 +50,26 @@ $ fastapi dev Uvicorn, высокопроизводительный, готовый к работе в production сервер ASGI. 😎 +Внутри **FastAPI CLI** используется Uvicorn, высокопроизводительный, готовый к работе в продакшне ASGI-сервер. 😎 -## `fastapi dev` +## `fastapi dev` { #fastapi-dev } Вызов `fastapi dev` запускает режим разработки. -По умолчанию включена автоматическая перезагрузка (**auto-reload**), благодаря этому при изменении кода происходит перезагрузка сервера приложения. Эта установка требует значительных ресурсов и делает систему менее стабильной. Используйте её только при разработке. Приложение слушает входящие подключения на IP `127.0.0.1`. Это IP адрес вашей машины, предназначенный для внутренних коммуникаций (`localhost`). +По умолчанию включена авто-перезагрузка (**auto-reload**), благодаря этому при изменении кода происходит перезагрузка сервера приложения. Эта установка требует значительных ресурсов и делает систему менее стабильной. Используйте её только при разработке. Приложение слушает входящие подключения на IP `127.0.0.1`. Это IP адрес вашей машины, предназначенный для внутренних коммуникаций (`localhost`). -## `fastapi run` +## `fastapi run` { #fastapi-run } -Вызов `fastapi run` по умолчанию запускает FastAPI в режиме production. +Вызов `fastapi run` по умолчанию запускает FastAPI в режиме продакшн. -По умолчанию функция перезагрузки **auto-reload** отключена. Приложение слушает входящие подключения на IP `0.0.0.0`, т.е. на всех доступных адресах компьютера. Таким образом, приложение будет находиться в публичном доступе для любого, кто может подсоединиться к вашей машине. Продуктовые приложения запускаются именно так, например, с помощью контейнеров. +По умолчанию авто-перезагрузка (**auto-reload**) отключена. Приложение слушает входящие подключения на IP `0.0.0.0`, т.е. на всех доступных адресах компьютера. Таким образом, приложение будет находиться в публичном доступе для любого, кто может подсоединиться к вашей машине. Продуктовые приложения запускаются именно так, например, с помощью контейнеров. В большинстве случаев вы будете (и должны) использовать прокси-сервер ("termination proxy"), который будет поддерживать HTTPS поверх вашего приложения. Всё будет зависеть от того, как вы развертываете приложение: за вас это либо сделает ваш провайдер, либо вам придется сделать настройки самостоятельно. /// tip | Подсказка -Вы можете больше узнать об этом в документации по развертыванию приложений [deployment documentation](deployment/index.md){.internal-link target=_blank}. +Вы можете больше узнать об этом в [документации по развертыванию](deployment/index.md){.internal-link target=_blank}. /// diff --git a/docs/ru/docs/features.md b/docs/ru/docs/features.md index 77d6b936a8..91ffe331b1 100644 --- a/docs/ru/docs/features.md +++ b/docs/ru/docs/features.md @@ -1,23 +1,21 @@ -# Основные свойства +# Возможности { #features } -## Основные свойства FastAPI +## Возможности FastAPI { #fastapi-features } **FastAPI** предлагает вам следующее: -### Использование открытых стандартов +### Основано на открытых стандартах { #based-on-open-standards } -* OpenAPI для создания API, включая объявления операций пути, параметров, тела запроса, безопасности и т.д. - - -* Автоматическое документирование моделей данных в соответствии с JSON Schema (так как спецификация OpenAPI сама основана на JSON Schema). -* Разработан, придерживаясь этих стандартов, после тщательного их изучения. Эти стандарты изначально включены во фреймфорк, а не являются дополнительной надстройкой. +* OpenAPI для создания API, включая объявления операций пути, параметров, тел запросов, безопасности и т. д. +* Автоматическая документация моделей данных с помощью JSON Schema (так как сама спецификация OpenAPI основана на JSON Schema). +* Разработан вокруг этих стандартов, после тщательного их изучения. Это не дополнительная надстройка поверх. * Это также позволяет использовать автоматическую **генерацию клиентского кода** на многих языках. -### Автоматически генерируемая документация +### Автоматическая документация { #automatic-docs } -Интерактивная документация для API и исследования пользовательских веб-интерфейсов. Поскольку этот фреймворк основан на OpenAPI, существует несколько вариантов документирования, 2 из которых включены по умолчанию. +Интерактивная документация для API и исследовательские веб-интерфейсы. Поскольку фреймворк основан на OpenAPI, существует несколько вариантов документирования, 2 из них включены по умолчанию. -* Swagger UI, с интерактивным взаимодействием, вызывает и тестирует ваш API прямо из браузера. +* Swagger UI, с интерактивным исследованием, вызовом и тестированием вашего API прямо из браузера. ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) @@ -25,22 +23,21 @@ ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### Только современный Python +### Только современный Python { #just-modern-python } -Все эти возможности основаны на стандартных **аннотациях типов Python 3.8** (благодаря Pydantic). Не нужно изучать новый синтаксис. Только лишь стандартный современный Python. +Все основано на стандартных **аннотациях типов Python** (благодаря Pydantic). Не нужно изучать новый синтаксис. Только стандартный современный Python. -Если вам нужно освежить знания, как использовать аннотации типов в Python (даже если вы не используете FastAPI), выделите 2 минуты и просмотрите краткое руководство: [Введение в аннотации типов Python¶ -](python-types.md){.internal-link target=_blank}. +Если вам нужно освежить знания о типах в Python (даже если вы не используете FastAPI), выделите 2 минуты и просмотрите краткое руководство: [Типы Python](python-types.md){.internal-link target=_blank}. -Вы пишете на стандартном Python с аннотациями типов: +Вы пишете стандартный Python с типами: ```Python from datetime import date from pydantic import BaseModel -# Объявляем параметр user_id с типом `str` -# и получаем поддержку редактора внутри функции +# Объявляем параметр как `str` +# и получаем поддержку редактора кода внутри функции def main(user_id: str): return user_id @@ -70,17 +67,17 @@ my_second_user: User = User(**second_user_data) `**second_user_data` означает: -Передать ключи и значения словаря `second_user_data`, в качестве аргументов типа "ключ-значение", это эквивалентно: `User(id=4, name="Mary", joined="2018-11-30")` . +Передать ключи и значения словаря `second_user_data` в качестве аргументов "ключ-значение", эквивалентно: `User(id=4, name="Mary", joined="2018-11-30")` /// -### Поддержка редакторов (IDE) +### Поддержка редакторов (IDE) { #editor-support } Весь фреймворк был продуман так, чтобы быть простым и интуитивно понятным в использовании, все решения были проверены на множестве редакторов еще до начала разработки, чтобы обеспечить наилучшие условия при написании кода. -В опросе Python-разработчиков было выяснено, что наиболее часто используемой функцией редакторов, является "автодополнение". +В опросах Python‑разработчиков видно, что одной из самых часто используемых функций является «автозавершение». -Вся структура **FastAPI** основана на удовлетворении этой возможности. Автодополнение работает везде. +Вся структура **FastAPI** основана на удовлетворении этой возможности. Автозавершение работает везде. Вам редко нужно будет возвращаться к документации. @@ -94,23 +91,23 @@ my_second_user: User = User(**second_user_data) ![editor support](https://fastapi.tiangolo.com/img/pycharm-completion.png) -Вы будете получать автодополнение кода даже там, где вы считали это невозможным раньше. -Как пример, ключ `price` внутри тела JSON (который может быть вложенным), приходящего в запросе. +Вы будете получать автозавершение кода даже там, где вы считали это невозможным раньше. Как пример, ключ `price` внутри тела JSON (который может быть вложенным), приходящего в запросе. + +Больше никаких неправильных имён ключей, метания по документации или прокручивания кода вверх и вниз в попытках узнать — использовали вы ранее `username` или `user_name`. -Больше никаких неправильных имён ключей, метания по документации или прокручивания кода вверх и вниз, в попытках узнать - использовали вы ранее `username` или `user_name`. +### Краткость { #short } -### Краткость -FastAPI имеет продуманные значения **по умолчанию** для всего, с произвольными настройками везде. Все параметры могут быть тонко подстроены так, чтобы делать то, что вам нужно и определять необходимый вам API. +FastAPI имеет продуманные значения **по умолчанию** для всего, с опциональными настройками везде. Все параметры могут быть тонко подстроены так, чтобы делать то, что вам нужно, и определять необходимый вам API. -Но, по умолчанию, всё это **"и так работает"**. +Но по умолчанию всё **«просто работает»**. -### Проверка значений +### Проверка значений { #validation } -* Проверка значений для большинства (или всех?) **типов данных** Python, включая: +* Проверка значений для большинства (или всех?) **типов данных** Python, включая: * Объекты JSON (`dict`). - * Массивы JSON (`list`) с установленными типами элементов. + * Массив JSON (`list`) с определёнными типами элементов. * Строковые (`str`) поля с ограничением минимальной и максимальной длины. - * Числа (`int`, `float`) с минимальными и максимальными значениями и т.п. + * Числа (`int`, `float`) с минимальными и максимальными значениями и т. п. * Проверка для более экзотических типов, таких как: * URL. @@ -118,11 +115,11 @@ FastAPI имеет продуманные значения **по умолчан * UUID. * ...и другие. -Все проверки обрабатываются хорошо зарекомендовавшим себя и надежным **Pydantic**. +Все проверки обрабатываются хорошо зарекомендовавшим себя и надёжным **Pydantic**. -### Безопасность и аутентификация +### Безопасность и аутентификация { #security-and-authentication } -Встроеные функции безопасности и аутентификации. Без каких-либо компромиссов с базами данных или моделями данных. +Встроенные функции безопасности и аутентификации. Без каких‑либо компромиссов с базами данных или моделями данных. Все схемы безопасности, определённые в OpenAPI, включая: @@ -137,68 +134,68 @@ FastAPI имеет продуманные значения **по умолчан Все инструменты и компоненты спроектированы для многократного использования и легко интегрируются с вашими системами, хранилищами данных, реляционными и NoSQL базами данных и т. д. -### Внедрение зависимостей +### Внедрение зависимостей { #dependency-injection } FastAPI включает в себя чрезвычайно простую в использовании, но чрезвычайно мощную систему Внедрения зависимостей. -* Даже зависимости могут иметь зависимости, создавая иерархию или **"графы" зависимостей**. +* Даже зависимости могут иметь зависимости, создавая иерархию или **«граф» зависимостей**. * Всё **автоматически обрабатывается** фреймворком. * Все зависимости могут запрашивать данные из запросов и **дополнять операции пути** ограничениями и автоматической документацией. -* **Автоматическая проверка** даже для параметров *операций пути*, определенных в зависимостях. -* Поддержка сложных систем аутентификации пользователей, **соединений с базами данных** и т.д. -* **Никаких компромиссов** с базами данных, интерфейсами и т.д. Но легкая интеграция со всеми ними. +* **Автоматическая проверка** даже для параметров *операций пути*, определённых в зависимостях. +* Поддержка сложных систем аутентификации пользователей, **соединений с базами данных** и т. д. +* **Никаких компромиссов** с базами данных, интерфейсами и т. д. Но при этом — лёгкая интеграция со всеми ними. -### Нет ограничений на "Плагины" +### Нет ограничений на "Плагины" { #unlimited-plug-ins } -Или, другими словами, нет сложностей с ними, импортируйте и используйте нужный вам код. +Или, другими словами, нет необходимости в них — просто импортируйте и используйте нужный вам код. -Любая интеграция разработана настолько простой в использовании (с зависимостями), что вы можете создать "плагин" для своего приложения в пару строк кода, используя ту же структуру и синтаксис, что и для ваших *операций пути*. +Любая интеграция разработана настолько простой в использовании (с зависимостями), что вы можете создать «плагин» для своего приложения в пару строк кода, используя ту же структуру и синтаксис, что и для ваших *операций пути*. -### Проверен +### Проверен { #tested } -* 100% покрытие тестами. -* 100% аннотирование типов в кодовой базе. -* Используется в реально работающих приложениях. +* 100% покрытие тестами. +* 100% аннотирование типов в кодовой базе. +* Используется в продакшн‑приложениях. -## Основные свойства Starlette +## Возможности Starlette { #starlette-features } -**FastAPI** основан на Starlette и полностью совместим с ним. Так что, любой дополнительный код Starlette, который у вас есть, будет также работать. +**FastAPI** основан на Starlette и полностью совместим с ним. Так что любой дополнительный код Starlette, который у вас есть, также будет работать. -На самом деле, `FastAPI` - это класс, унаследованный от `Starlette`. Таким образом, если вы уже знаете или используете Starlette, большая часть функционала будет работать так же. +На самом деле, `FastAPI` — это подкласс `Starlette`. Таким образом, если вы уже знаете или используете Starlette, большая часть функционала будет работать так же. -С **FastAPI** вы получаете все возможности **Starlette** (так как FastAPI это всего лишь Starlette на стероидах): +С **FastAPI** вы получаете все возможности **Starlette** (так как FastAPI — это всего лишь Starlette на стероидах): -* Серьёзно впечатляющая производительность. Это один из самых быстрых фреймворков на Python, наравне с приложениями использующими **NodeJS** или **Go**. +* Серьёзно впечатляющая производительность. Это один из самых быстрых фреймворков на Python, наравне с **NodeJS** и **Go**. * Поддержка **WebSocket**. -* Фоновые задачи для процессов. +* Фоновые задачи в том же процессе. * События запуска и выключения. -* Тестовый клиент построен на библиотеке HTTPX. +* Тестовый клиент построен на HTTPX. * **CORS**, GZip, статические файлы, потоковые ответы. * Поддержка **сессий и cookie**. * 100% покрытие тестами. * 100% аннотирование типов в кодовой базе. -## Особенности и возможности Pydantic +## Возможности Pydantic { #pydantic-features } -**FastAPI** основан на Pydantic и полностью совместим с ним. Так что, любой дополнительный код Pydantic, который у вас есть, будет также работать. +**FastAPI** полностью совместим с (и основан на) Pydantic. Поэтому любой дополнительный код Pydantic, который у вас есть, также будет работать. -Включая внешние библиотеки, также основанные на Pydantic, такие как: ORM'ы, ODM'ы для баз данных. +Включая внешние библиотеки, также основанные на Pydantic, такие как ORM’ы, ODM’ы для баз данных. Это также означает, что во многих случаях вы можете передавать тот же объект, который получили из запроса, **непосредственно в базу данных**, так как всё проверяется автоматически. И наоборот, во многих случаях вы можете просто передать объект, полученный из базы данных, **непосредственно клиенту**. -С **FastAPI** вы получаете все возможности **Pydantic** (так как, FastAPI основан на Pydantic, для обработки данных): - -* **Никакой нервотрёпки** : - * Не нужно изучать новых схем в микроязыках. - * Если вы знаете аннотации типов в Python, вы знаете, как использовать Pydantic. -* Прекрасно сочетается с вашими **IDE/linter/мозгом**: - * Потому что структуры данных pydantic - это всего лишь экземпляры классов, определённых вами. Автодополнение, проверка кода, mypy и ваша интуиция - всё будет работать с вашими проверенными данными. -* Проверка **сложных структур**: - * Использование иерархических моделей Pydantic; `List`, `Dict` и т.п. из модуля `typing` (входит в стандартную библиотеку Python). - * Валидаторы позволяют четко и легко определять, проверять и документировать сложные схемы данных в виде JSON Schema. - * У вас могут быть глубоко **вложенные объекты JSON** и все они будут проверены и аннотированы. +С **FastAPI** вы получаете все возможности **Pydantic** (так как FastAPI основан на Pydantic для обработки данных): + +* **Никакой нервотрёпки**: + * Не нужно изучать новые схемы в микроязыках. + * Если вы знаете типы в Python, вы знаете, как использовать Pydantic. +* Прекрасно сочетается с вашим **IDE/linter/мозгом**: + * Потому что структуры данных pydantic — это всего лишь экземпляры классов, определённых вами; автозавершение, проверка кода, mypy и ваша интуиция — всё будет работать с вашими валидированными данными. +* Валидация **сложных структур**: + * Использование иерархических моделей Pydantic; `List`, `Dict` и т. п. из модуля `typing` (входит в стандартную библиотеку Python). + * Валидаторы позволяют чётко и легко определять, проверять и документировать сложные схемы данных в виде JSON Schema. + * У вас могут быть глубоко **вложенные объекты JSON**, и все они будут проверены и аннотированы. * **Расширяемость**: - * Pydantic позволяет определять пользовательские типы данных или расширять проверку методами модели, с помощью проверочных декораторов. + * Pydantic позволяет определять пользовательские типы данных или расширять проверку методами модели с помощью декораторов валидаторов. * 100% покрытие тестами. diff --git a/docs/ru/docs/help-fastapi.md b/docs/ru/docs/help-fastapi.md index 2f73c3c101..6bfabb96cb 100644 --- a/docs/ru/docs/help-fastapi.md +++ b/docs/ru/docs/help-fastapi.md @@ -1,261 +1,255 @@ -# Помочь FastAPI - Получить помощь +# Помочь FastAPI - Получить помощь { #help-fastapi-get-help } Нравится ли Вам **FastAPI**? -Хотели бы Вы помочь FastAPI, его пользователям и автору? +Хотели бы Вы помочь FastAPI, другим пользователям и автору? -Может быть у Вас возникли трудности с **FastAPI** и Вам нужна помощь? +Или Вы хотите получить помощь по **FastAPI**? -Есть несколько очень простых способов оказания помощи (иногда достаточно всего лишь одного или двух кликов). +Есть несколько очень простых способов помочь (иногда достаточно всего лишь одного-двух кликов). И также есть несколько способов получить помощь. -## Подписаться на новостную рассылку +## Подписаться на новостную рассылку { #subscribe-to-the-newsletter } Вы можете подписаться на редкую [новостную рассылку **FastAPI и его друзья**](newsletter.md){.internal-link target=_blank} и быть в курсе о: * Новостях о FastAPI и его друзьях 🚀 * Руководствах 📝 * Возможностях ✨ -* Исправлениях 🚨 +* Ломающих изменениях 🚨 * Подсказках и хитростях ✅ -## Подписаться на FastAPI в X (Twitter) +## Подписаться на FastAPI в X (Twitter) { #follow-fastapi-on-x-twitter } Подписаться на @fastapi в **X (Twitter)** для получения наисвежайших новостей о **FastAPI**. 🐦 -## Добавить **FastAPI** звезду на GitHub +## Добавить **FastAPI** звезду на GitHub { #star-fastapi-in-github } -Вы можете добавить FastAPI "звезду" на GitHub (кликнуть на кнопку звезды в верхнем правом углу экрана): https://github.com/fastapi/fastapi. ⭐️ +Вы можете добавить FastAPI "звезду" на GitHub (кликнув на кнопку звезды в правом верхнем углу): https://github.com/fastapi/fastapi. ⭐️ -Чем больше звёзд, тем легче другим пользователям найти нас и увидеть, что проект уже стал полезным для многих. +Чем больше звёзд, тем легче другим пользователям найти проект и увидеть, что он уже оказался полезным для многих. -## Отслеживать свежие выпуски в репозитории на GitHub +## Отслеживать свежие выпуски в репозитории на GitHub { #watch-the-github-repository-for-releases } -Вы можете "отслеживать" FastAPI на GitHub (кликните по кнопке "watch" наверху справа): https://github.com/fastapi/fastapi. 👀 +Вы можете "отслеживать" FastAPI на GitHub (кликнув по кнопке "watch" наверху справа): https://github.com/fastapi/fastapi. 👀 -Там же Вы можете указать в настройках - "Releases only". +Там же Вы можете выбрать "Releases only". С такой настройкой Вы будете получать уведомления на вашу электронную почту каждый раз, когда появится новый релиз (новая версия) **FastAPI** с исправлениями ошибок и новыми возможностями. -## Связаться с автором +## Связаться с автором { #connect-with-the-author } -Можно связаться со мной (Себястьян Рамирез / `tiangolo`), автором FastAPI. +Можно связаться со мной (Sebastián Ramírez / `tiangolo`), автором. Вы можете: * Подписаться на меня на **GitHub**. * Посмотреть другие мои проекты с открытым кодом, которые могут быть полезны Вам. - * Подписавшись на меня Вы сможете получать уведомления, что я создал новый проект с открытым кодом,. + * Подписаться, чтобы видеть, когда я создаю новый проект с открытым кодом. * Подписаться на меня в **X (Twitter)** или в Mastodon. - * Поделиться со мной, как Вы используете FastAPI (я обожаю читать про это). - * Получать уведомления, когда я делаю объявления и представляю новые инструменты. + * Поделиться со мной, как Вы используете FastAPI (я обожаю это читать). + * Узнавать, когда я делаю объявления или выпускаю новые инструменты. * Вы также можете подписаться на @fastapi в X (Twitter) (это отдельный аккаунт). -* Подписаться на меня в **Linkedin**. - * Получать уведомления, когда я делаю объявления и представляю новые инструменты (правда чаще всего я использую X (Twitter) 🤷‍♂). -* Читать, что я пишу (или подписаться на меня) в **Dev.to** или в **Medium**. - * Читать другие идеи, статьи и читать об инструментах созданных мной. - * Подпишитесь на меня, чтобы прочитать, когда я опубликую что-нибудь новое. +* Подписаться на меня в **LinkedIn**. + * Узнавать, когда я делаю объявления или выпускаю новые инструменты (хотя чаще я использую X (Twitter) 🤷‍♂). +* Читать, что я пишу (или подписаться на меня) на **Dev.to** или **Medium**. + * Читать другие идеи, статьи и о созданных мной инструментах. + * Подписаться, чтобы читать, когда я публикую что-то новое. -## Оставить сообщение в X (Twitter) о **FastAPI** +## Оставить сообщение в X (Twitter) о **FastAPI** { #tweet-about-fastapi } -Оставьте сообщение в X (Twitter) о **FastAPI** и позвольте мне и другим узнать - почему он Вам нравится. 🎉 +Оставьте сообщение в X (Twitter) о **FastAPI** и позвольте мне и другим узнать, почему он Вам нравится. 🎉 -Я люблю узнавать о том, как **FastAPI** используется, что Вам понравилось в нём, в каких проектах/компаниях Вы используете его и т.п. +Я люблю узнавать о том, как **FastAPI** используется, что Вам понравилось в нём, в каких проектах/компаниях Вы его используете и т.д. -## Оставить голос за FastAPI +## Оставить голос за FastAPI { #vote-for-fastapi } * Голосуйте за **FastAPI** в Slant. -* Голосуйте за **FastAPI** в AlternativeTo. -* Расскажите, как Вы используете **FastAPI** на StackShare. +* Голосуйте за **FastAPI** в AlternativeTo. +* Расскажите, что Вы используете **FastAPI** на StackShare. -## Помочь другим с их проблемами на GitHub +## Помочь другим с вопросами на GitHub { #help-others-with-questions-in-github } -Вы можете посмотреть, какие проблемы испытывают другие люди и попытаться помочь им. Чаще всего это вопросы, на которые, весьма вероятно, Вы уже знаете ответ. 🤓 +Вы можете попробовать помочь другим с их вопросами в: -Если Вы будете много помогать людям с решением их проблем, Вы можете стать официальным [Экспертом FastAPI](fastapi-people.md#_3){.internal-link target=_blank}. 🎉 +* GitHub Discussions +* GitHub Issues -Только помните, самое важное при этом - доброта. Столкнувшись с проблемой, люди расстраиваются и часто задают вопросы не лучшим образом, но постарайтесь быть максимально доброжелательным. 🤗 +Во многих случаях Вы уже можете знать ответы на эти вопросы. 🤓 -Идея сообщества **FastAPI** в том, чтобы быть добродушным и гостеприимными. Не допускайте издевательств или неуважительного поведения по отношению к другим. Мы должны заботиться друг о друге. +Если Вы много помогаете людям с их вопросами, Вы станете официальным [Экспертом FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}. 🎉 + +Только помните, самое важное — постарайтесь быть добрыми. Люди приходят со своими разочарованиями и часто задают вопросы не лучшим образом, но постарайтесь, насколько можете, быть доброжелательными. 🤗 + +Идея сообщества **FastAPI** — быть доброжелательным и гостеприимным. В то же время не допускайте травлю или неуважительное поведение по отношению к другим. Мы должны заботиться друг о друге. --- -Как помочь другим с их проблемами: +Как помочь другим с вопросами (в обсуждениях или Issues): -### Понять вопрос +### Понять вопрос { #understand-the-question } -* Удостоверьтесь, что поняли **цель** и обстоятельства случая вопрошающего. +* Убедитесь, что поняли **цель** и кейс использования задающего вопрос. -* Затем проверьте, что вопрос (в подавляющем большинстве - это вопросы) Вам **ясен**. +* Затем проверьте, что вопрос (в подавляющем большинстве это вопросы) сформулирован **ясно**. -* Во многих случаях вопрос касается решения, которое пользователь придумал сам, но может быть и решение **получше**. Если Вы поймёте проблему и обстоятельства случая, то сможете предложить **альтернативное решение**. +* Во многих случаях спрашивают о воображаемом решении пользователя, но может быть решение **получше**. Если Вы лучше поймёте проблему и кейс, сможете предложить **альтернативное решение**. -* Ежели вопрос Вам непонятен, запросите больше **деталей**. +* Если вопрос непонятен, запросите больше **деталей**. -### Воспроизвести проблему +### Воспроизвести проблему { #reproduce-the-problem } -В большинстве случаев есть что-то связанное с **исходным кодом** вопрошающего. +В большинстве случаев и вопросов есть что-то связанное с **исходным кодом** автора. -И во многих случаях будет предоставлен только фрагмент этого кода, которого недостаточно для **воспроизведения проблемы**. +Во многих случаях предоставляют только фрагмент кода, но этого недостаточно, чтобы **воспроизвести проблему**. -* Попросите предоставить минимальный воспроизводимый пример, который можно **скопировать** и запустить локально дабы увидеть такую же ошибку, или поведение, или лучше понять обстоятельства случая. +* Попросите предоставить минимальный воспроизводимый пример, который Вы сможете **скопировать-вставить** и запустить локально, чтобы увидеть ту же ошибку или поведение, или лучше понять их кейс. -* Если на Вас нахлынуло великодушие, то можете попытаться **создать похожий пример** самостоятельно, основываясь только на описании проблемы. Но имейте в виду, что это может занять много времени и, возможно, стоит сначала позадавать вопросы для прояснения проблемы. +* Если чувствуете себя особенно великодушными, можете попытаться **создать такой пример** сами, основываясь только на описании проблемы. Просто помните, что это может занять много времени, и, возможно, сначала лучше попросить уточнить проблему. -### Предложить решение +### Предложить решение { #suggest-solutions } -* После того как Вы поняли вопрос, Вы можете дать **ответ**. +* После того как Вы поняли вопрос, Вы можете дать возможный **ответ**. -* Следует понять **основную проблему и обстоятельства случая**, потому что может быть решение лучше, чем то, которое пытались реализовать. +* Во многих случаях лучше понять **исходную проблему или кейс**, потому что может существовать способ решить её лучше, чем то, что пытаются сделать. -### Попросить закрыть проблему +### Попросить закрыть { #ask-to-close } -Если Вам ответили, высоки шансы, что Вам удалось решить проблему, поздравляю, **Вы - герой**! 🦸 +Если Вам ответили, велика вероятность, что Вы решили их проблему, поздравляю, **Вы — герой**! 🦸 -* В таком случае, если вопрос решён, попросите **закрыть проблему**. +* Теперь, если проблема решена, можно попросить их: + * В GitHub Discussions: пометить комментарий как **answer** (ответ). + * В GitHub Issues: **закрыть** Issue. -## Отслеживать репозиторий на GitHub +## Отслеживать репозиторий на GitHub { #watch-the-github-repository } -Вы можете "отслеживать" FastAPI на GitHub (кликните по кнопке "watch" наверху справа): https://github.com/fastapi/fastapi. 👀 +Вы можете "отслеживать" FastAPI на GitHub (кликнув по кнопке "watch" наверху справа): https://github.com/fastapi/fastapi. 👀 -Если Вы выберете "Watching" вместо "Releases only", то будете получать уведомления когда кто-либо попросит о помощи с решением его проблемы. +Если Вы выберете "Watching" вместо "Releases only", то будете получать уведомления, когда кто-либо создаёт новый вопрос или Issue. Вы также можете указать, что хотите получать уведомления только о новых Issues, или обсуждениях, или пулл-реквестах и т.д. -Тогда Вы можете попробовать решить эту проблему. +Тогда Вы можете попробовать помочь им с решением этих вопросов. -## Запросить помощь с решением проблемы +## Задать вопросы { #ask-questions } -Вы можете создать новый запрос с просьбой о помощи в репозитории на GitHub, например: +Вы можете создать новый вопрос в репозитории GitHub, например: -* Задать **вопрос** или попросить помощи в решении **проблемы**. -* Предложить новое **улучшение**. +* Задать **вопрос** или спросить о **проблеме**. +* Предложить новую **возможность**. -**Заметка**: Если Вы создаёте подобные запросы, то я попрошу Вас также оказывать аналогичную помощь другим. 😉 +**Заметка**: если Вы это сделаете, то я попрошу Вас также помогать другим. 😉 -## Проверять пул-реквесты +## Проверять пулл-реквесты { #review-pull-requests } -Вы можете помочь мне проверять пул-реквесты других участников. +Вы можете помочь мне проверять пулл-реквесты других участников. -И повторюсь, постарайтесь быть доброжелательным. 🤗 +И, снова, постарайтесь быть доброжелательными. 🤗 --- -О том, что нужно иметь в виду при проверке пул-реквестов: +О том, что нужно иметь в виду и как проверять пулл-реквест: -### Понять проблему +### Понять проблему { #understand-the-problem } -* Во-первых, убедитесь, что **поняли проблему**, которую пул-реквест пытается решить. Для этого может потребоваться продолжительное обсуждение. +* Во-первых, убедитесь, что **поняли проблему**, которую пулл-реквест пытается решить. Возможно, это обсуждалось более подробно в GitHub Discussion или Issue. -* Также есть вероятность, что пул-реквест не актуален, так как проблему можно решить **другим путём**. В таком случае Вы можете указать на этот факт. +* Также есть вероятность, что пулл-реквест не нужен, так как проблему можно решить **другим путём**. Тогда Вы можете предложить или спросить об этом. -### Не переживайте о стиле +### Не переживайте о стиле { #dont-worry-about-style } -* Не стоит слишком беспокоиться о таких вещах, как стиль сообщений в коммитах или количество коммитов. При слиянии пул-реквеста с основной веткой, я буду сжимать и настраивать всё вручную. +* Не стоит слишком беспокоиться о таких вещах, как стиль сообщений в коммитах — при слиянии я выполню squash и настрою коммит вручную. -* Также не беспокойтесь о правилах стиля, для проверки сего есть автоматизированные инструменты. +* Также не беспокойтесь о правилах стиля, это уже проверяют автоматизированные инструменты. -И если всё же потребуется какой-то другой стиль, я попрошу Вас об этом напрямую или добавлю сам коммиты с необходимыми изменениями. +Если будет нужна какая-то другая стилистика или единообразие, я попрошу об этом напрямую или добавлю поверх свои коммиты с нужными изменениями. -### Проверить код +### Проверить код { #check-the-code } -* Проверьте и прочитайте код, посмотрите, какой он имеет смысл, **запустите его локально** и посмотрите, действительно ли он решает поставленную задачу. +* Проверьте и прочитайте код, посмотрите, логичен ли он, **запустите его локально** и проверьте, действительно ли он решает проблему. -* Затем, используя **комментарий**, сообщите, что Вы сделали проверку, тогда я буду знать, что Вы действительно проверили код. +* Затем оставьте **комментарий**, что Вы это сделали, так я пойму, что Вы действительно проверили код. /// info | Информация -К сожалению, я не могу так просто доверять пул-реквестам, у которых уже есть несколько одобрений. +К сожалению, я не могу просто доверять PR-ам только потому, что у них есть несколько одобрений. -Бывали случаи, что пул-реквесты имели 3, 5 или больше одобрений, вероятно из-за привлекательного описания, но когда я проверял эти пул-реквесты, они оказывались сломаны, содержали ошибки или вовсе не решали проблему, которую, как они утверждали, должны были решить. 😅 +Несколько раз было так, что у PR-ов было 3, 5 или больше одобрений, вероятно из-за привлекательного описания, но когда я их проверял, они оказывались сломанными, содержали баги или вовсе не решали заявленную проблему. 😅 -Потому это действительно важно - проверять и запускать код, и комментарием уведомлять меня, что Вы проделали эти действия. 🤓 +Поэтому очень важно действительно прочитать и запустить код и сообщить мне об этом в комментарии. 🤓 /// -* Если Вы считаете, что пул-реквест можно упростить, то можете попросить об этом, но не нужно быть слишком придирчивым, может быть много субъективных точек зрения (и у меня тоже будет своя 🙈), поэтому будет лучше, если Вы сосредоточитесь на фундаментальных вещах. +* Если PR можно упростить, Вы можете попросить об этом, но не нужно быть слишком придирчивым — может быть много субъективных мнений (и у меня тоже 🙈), поэтому лучше сосредоточиться на фундаментальных вещах. -### Тестировать +### Тестировать { #tests } -* Помогите мне проверить, что у пул-реквеста есть **тесты**. +* Помогите мне проверить, что у PR есть **тесты**. -* Проверьте, что тесты **падали** до пул-реквеста. 🚨 +* Проверьте, что тесты **падают** до PR. 🚨 -* Затем проверьте, что тесты **не валятся** после пул-реквеста. ✅ +* Затем проверьте, что тесты **проходят** после PR. ✅ -* Многие пул-реквесты не имеют тестов, Вы можете **напомнить** о необходимости добавления тестов или даже **предложить** какие-либо свои тесты. Это одна из тех вещей, которые отнимают много времени и Вы можете помочь с этим. +* Многие PR не имеют тестов — Вы можете **напомнить** добавить тесты или даже **предложить** некоторые тесты сами. Это одна из самых трудозатратных частей, и здесь Вы можете очень помочь. -* Затем добавьте комментарий, что Вы испробовали в ходе проверки. Таким образом я буду знать, как Вы произвели проверку. 🤓 +* Затем добавьте комментарий, что Вы попробовали, чтобы я знал, что Вы это проверили. 🤓 -## Создать пул-реквест +## Создать пулл-реквест { #create-a-pull-request } -Вы можете [сделать вклад](contributing.md){.internal-link target=_blank} в код фреймворка используя пул-реквесты, например: +Вы можете [сделать вклад](contributing.md){.internal-link target=_blank} в исходный код пулл-реквестами, например: -* Исправить опечатку, которую Вы нашли в документации. -* Поделиться статьёй, видео или подкастом о FastAPI, которые Вы создали или нашли изменив этот файл. - * Убедитесь, что Вы добавили свою ссылку в начало соответствующего раздела. -* Помочь с [переводом документации](contributing.md#_8){.internal-link target=_blank} на Ваш язык. - * Вы также можете проверять переводы сделанные другими. +* Исправить опечатку, найденную в документации. +* Поделиться статьёй, видео или подкастом о FastAPI, которые Вы создали или нашли, изменив этот файл. + * Убедитесь, что добавили свою ссылку в начало соответствующего раздела. +* Помочь с [переводом документации](contributing.md#translations){.internal-link target=_blank} на Ваш язык. + * Вы также можете проверять переводы, сделанные другими. * Предложить новые разделы документации. -* Исправить существующуе проблемы/баги. +* Исправить существующую проблему/баг. * Убедитесь, что добавили тесты. * Добавить новую возможность. * Убедитесь, что добавили тесты. - * Убедитесь, что добавили документацию, если она необходима. + * Убедитесь, что добавили документацию, если это уместно. -## Помочь поддерживать FastAPI +## Помочь поддерживать FastAPI { #help-maintain-fastapi } Помогите мне поддерживать **FastAPI**! 🤓 -Предстоит ещё много работы и, по большей части, **ВЫ** можете её сделать. +Предстоит ещё много работы, и, по большей части, **ВЫ** можете её сделать. Основные задачи, которые Вы можете выполнить прямо сейчас: -* [Помочь другим с их проблемами на GitHub](#github_1){.internal-link target=_blank} (смотрите вышестоящую секцию). -* [Проверить пул-реквесты](#-){.internal-link target=_blank} (смотрите вышестоящую секцию). +* [Помочь другим с вопросами на GitHub](#help-others-with-questions-in-github){.internal-link target=_blank} (смотрите секцию выше). +* [Проверять пулл-реквесты](#review-pull-requests){.internal-link target=_blank} (смотрите секцию выше). -Эти две задачи **отнимают больше всего времени**. Это основная работа по поддержке FastAPI. +Именно эти две задачи **забирают больше всего времени**. Это основная работа по поддержке FastAPI. -Если Вы можете помочь мне с этим, **Вы помогаете поддерживать FastAPI** и следить за тем, чтобы он продолжал **развиваться быстрее и лучше**. 🚀 +Если Вы можете помочь мне с этим, **Вы помогаете поддерживать FastAPI** и делаете так, чтобы он продолжал **развиваться быстрее и лучше**. 🚀 -## Подключиться к чату +## Подключиться к чату { #join-the-chat } -Подключайтесь к 👥 чату в Discord 👥 и общайтесь с другими участниками сообщества FastAPI. +Подключайтесь к 👥 серверу чата в Discord 👥 и общайтесь с другими участниками сообщества FastAPI. /// tip | Подсказка -Вопросы по проблемам с фреймворком лучше задавать в GitHub issues, так больше шансов, что Вы получите помощь от [Экспертов FastAPI](fastapi-people.md#_3){.internal-link target=_blank}. +По вопросам — задавайте их в GitHub Discussions, так гораздо выше шанс, что Вы получите помощь от [Экспертов FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}. -Используйте этот чат только для бесед на отвлечённые темы. +Используйте чат только для прочих общих бесед. /// -### Не использовать чаты для вопросов - -Имейте в виду, что чаты позволяют больше "свободного общения", потому там легко задавать вопросы, которые слишком общие и на которые труднее ответить, так что Вы можете не получить нужные Вам ответы. - -В разделе "проблемы" на GitHub, есть шаблон, который поможет Вам написать вопрос правильно, чтобы Вам было легче получить хороший ответ или даже решить проблему самостоятельно, прежде чем Вы зададите вопрос. В GitHub я могу быть уверен, что всегда отвечаю на всё, даже если это займет какое-то время. И я не могу сделать то же самое в чатах. 😅 - -Кроме того, общение в чатах не так легкодоступно для поиска, как в GitHub, потому вопросы и ответы могут потеряться среди другого общения. И только проблемы решаемые на GitHub учитываются в получении лычки [Эксперт FastAPI](fastapi-people.md#_3){.internal-link target=_blank}, так что весьма вероятно, что Вы получите больше внимания на GitHub. - -С другой стороны, в чатах тысячи пользователей, а значит есть большие шансы в любое время найти там кого-то, с кем можно поговорить. 😄 - -## Спонсировать автора - -Вы также можете оказать мне финансовую поддержку посредством спонсорства через GitHub. +### Не используйте чат для вопросов { #dont-use-the-chat-for-questions } -Там можно просто купить мне кофе ☕️ в знак благодарности. 😄 +Имейте в виду, что в чатах, благодаря "свободному общению", легко задать вопросы, которые слишком общие и на которые сложнее ответить, поэтому Вы можете не получить ответы. -А ещё Вы можете стать Серебряным или Золотым спонсором для FastAPI. 🏅🎉 +На GitHub шаблон поможет Вам правильно сформулировать вопрос, чтобы Вам было легче получить хороший ответ или даже решить проблему самостоятельно ещё до того, как спросите. И на GitHub я могу следить за тем, чтобы всегда отвечать на всё, даже если это занимает время. А с чатами я не могу сделать этого лично. 😅 -## Спонсировать инструменты, на которых зиждется мощь FastAPI +Кроме того, переписка в чатах хуже ищется, чем на GitHub, поэтому вопросы и ответы могут теряться среди остальных сообщений. И только те, что на GitHub, учитываются для получения лычки [Эксперт FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}, так что вероятнее всего Вы получите больше внимания именно на GitHub. -Как Вы могли заметить в документации, FastAPI опирается на плечи титанов: Starlette и Pydantic. +С другой стороны, в чатах тысячи пользователей, так что почти всегда есть шанс найти там кого-то для разговора. 😄 -Им тоже можно оказать спонсорскую поддержку: +## Спонсировать автора { #sponsor-the-author } -* Samuel Colvin (Pydantic) -* Encode (Starlette, Uvicorn) +Если Ваш **продукт/компания** зависят от **FastAPI** или связаны с ним и Вы хотите донести до пользователей информацию о себе, Вы можете спонсировать автора (меня) через GitHub Sponsors. В зависимости от уровня поддержки Вы можете получить дополнительные бонусы, например, бейдж в документации. 🎁 --- -Благодарствую! 🚀 +Спасибо! 🚀 diff --git a/docs/ru/docs/history-design-future.md b/docs/ru/docs/history-design-future.md index 96604e3a4e..d679af3e37 100644 --- a/docs/ru/docs/history-design-future.md +++ b/docs/ru/docs/history-design-future.md @@ -1,4 +1,4 @@ -# История создания и дальнейшее развитие +# История, проектирование и будущее { #history-design-and-future } Однажды, один из пользователей **FastAPI** задал вопрос: @@ -6,7 +6,7 @@ Что ж, вот небольшая часть истории проекта. -## Альтернативы +## Альтернативы { #alternatives } В течение нескольких лет я, возглавляя различные команды разработчиков, создавал довольно сложные API для машинного обучения, распределённых систем, асинхронных задач, баз данных NoSQL и т.д. @@ -24,45 +24,47 @@ Я всячески избегал создания нового фреймворка в течение нескольких лет. Сначала я пытался собрать все нужные возможности, которые ныне есть в **FastAPI**, используя множество различных фреймворков, плагинов и инструментов. -Но в какой-то момент не осталось другого выбора, кроме как создать что-то, что предоставляло бы все эти возможности сразу. Взять самые лучшие идеи из предыдущих инструментов и, используя введённые в Python подсказки типов (которых не было до версии 3.6), объединить их. +Но в какой-то момент не осталось другого выбора, кроме как создать что-то, что предоставляло бы все эти возможности сразу. Взять самые лучшие идеи из предыдущих инструментов и, используя введённые в Python аннотации типов (которых не было до версии 3.6), объединить их. -## Исследования +## Исследования { #investigation } Благодаря опыту использования существующих альтернатив, мы с коллегами изучили их основные идеи и скомбинировали собранные знания наилучшим образом. -Например, стало ясно, что необходимо брать за основу стандартные подсказки типов Python, а самым лучшим подходом является использование уже существующих стандартов. +Например, стало ясно, что необходимо брать за основу стандартные аннотации типов Python. + +Также наилучшим подходом является использование уже существующих стандартов. Итак, прежде чем приступить к написанию **FastAPI**, я потратил несколько месяцев на изучение OpenAPI, JSON Schema, OAuth2, и т.п. для понимания их взаимосвязей, совпадений и различий. -## Дизайн +## Проектирование { #design } Затем я потратил некоторое время на придумывание "API" разработчика, который я хотел иметь как пользователь (как разработчик, использующий FastAPI). -Я проверил несколько идей на самых популярных редакторах кода среди Python-разработчиков: PyCharm, VS Code, Jedi. +Я проверил несколько идей на самых популярных редакторах кода: PyCharm, VS Code, редакторы на базе Jedi. -Данные по редакторам я взял из опроса Python-разработчиков, который охватываает около 80% пользователей. +Данные по редакторам я взял из опроса Python-разработчиков, который охватывает около 80% пользователей. Это означает, что **FastAPI** был специально проверен на редакторах, используемых 80% Python-разработчиками. И поскольку большинство других редакторов, как правило, работают аналогичным образом, все его преимущества должны работать практически для всех редакторов. -Таким образом, я смог найти наилучшие способы сократить дублирование кода, обеспечить повсеместное автодополнение, проверку типов и ошибок и т.д. +Таким образом, я смог найти наилучшие способы сократить дублирование кода, обеспечить повсеместное автозавершение, проверку типов и ошибок и т.д. И все это, чтобы все пользователи могли получать наилучший опыт разработки. -## Зависимости +## Зависимости { #requirements } Протестировав несколько вариантов, я решил, что в качестве основы буду использовать **Pydantic** и его преимущества. -По моим предложениям был изменён код этого фреймворка, чтобы сделать его полностью совместимым с JSON Schema, поддержать различные способы определения ограничений и улучшить помощь редакторов (проверки типов, автозаполнение). +По моим предложениям был изменён код этого фреймворка, чтобы сделать его полностью совместимым с JSON Schema, поддержать различные способы определения ограничений и улучшить поддержку в редакторах кода (проверки типов, автозавершение) на основе тестов в нескольких редакторах. В то же время, я принимал участие в разработке **Starlette**, ещё один из основных компонентов FastAPI. -## Разработка +## Разработка { #development } К тому времени, когда я начал создавать **FastAPI**, большинство необходимых деталей уже существовало, дизайн был определён, зависимости и прочие инструменты были готовы, а знания о стандартах и спецификациях были четкими и свежими. -## Будущее +## Будущее { #future } Сейчас уже ясно, что **FastAPI** со своими идеями стал полезен многим людям. diff --git a/docs/ru/docs/index.md b/docs/ru/docs/index.md index 692c03ecba..1fcc9ea9d8 100644 --- a/docs/ru/docs/index.md +++ b/docs/ru/docs/index.md @@ -1,4 +1,4 @@ -# FastAPI +# FastAPI { #fastapi }