Sebastián Ramírez
4 days ago
committed by
GitHub
GitHub
36 changed files with 4070 additions and 0 deletions
@ -0,0 +1,247 @@ |
|||
# Дополнительные ответы в OpenAPI |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
Это достаточно сложная тема. |
|||
|
|||
Если вы только начинаете работать с **FastAPI**, вам это может не понадобиться. |
|||
|
|||
/// |
|||
|
|||
Вы можете объявлять дополнительные ответы с дополнительными статус-кодами, типами содержимого, описаниями и т.д. |
|||
|
|||
Эти дополнительные ответы будут включены в схему OpenAPI, так что они также появятся в документации API. |
|||
|
|||
Но для этих дополнительных ответов вы должны убедиться, что возвращаете `Response`, например, `JSONResponse` напрямую, с вашим статус-кодом и содержимым. |
|||
|
|||
## Дополнительный ответ с `model` |
|||
|
|||
Вы можете передать своим декораторам *операций пути* параметр `responses`. |
|||
|
|||
Он принимает `dict`: ключами являются статус-коды для каждого ответа (например, `200`), а значениями являются другие `dict` с информацией для каждого из них. |
|||
|
|||
Каждый из этих `dict` ответа может содержать ключ `model`, содержащий Pydantic-модель, как и `response_model`. |
|||
|
|||
**FastAPI** возьмет эту модель, сгенерирует ее JSON Schema и включит в нужное место в OpenAPI. |
|||
|
|||
Например, чтобы объявить другой ответ с кодом состояния `404` и Pydantic-моделью `Message`, вы можете написать: |
|||
|
|||
{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *} |
|||
|
|||
/// note | Заметка |
|||
|
|||
Имейте в виду, что вы должны вернуть `JSONResponse` напрямую. |
|||
|
|||
/// |
|||
|
|||
/// info | Информация |
|||
|
|||
Ключ `model` не является частью OpenAPI. |
|||
|
|||
**FastAPI** возьмет Pydantic-модель оттуда, сгенерирует JSON Schema и поместит в нужное место. |
|||
|
|||
Правильное место: |
|||
|
|||
* В ключе `content`, который имеет значение другой JSON объект (`dict`), содержащий: |
|||
* Ключ с типом содержимого, например `application/json`, который в качестве значения содержит другой JSON объект, содержащий: |
|||
* Ключ `schema`, который имеет в качестве значения JSON Schema из модели, вот куда нужно поместить. |
|||
* **FastAPI** добавляет сюда ссылку на глобальные JSON Schemas в другом месте вашего OpenAPI вместо того, чтобы включать его напрямую. Таким образом, другие приложения и клиенты могут использовать эти JSON Schemas напрямую, предоставлять лучшие инструменты генерации кода и другие функции. |
|||
|
|||
/// |
|||
|
|||
Сгенерированные ответы в OpenAPI для этой *операции пути* будут: |
|||
|
|||
```JSON hl_lines="3-12" |
|||
{ |
|||
"responses": { |
|||
"404": { |
|||
"description": "Дополнительный ответ", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/Message" |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"200": { |
|||
"description": "Успешный ответ", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/Item" |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"422": { |
|||
"description": "Ошибка валидации", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Схемы ссылаются на другое место внутри схемы OpenAPI: |
|||
|
|||
```JSON hl_lines="4-16" |
|||
{ |
|||
"components": { |
|||
"schemas": { |
|||
"Message": { |
|||
"title": "Сообщение", |
|||
"required": [ |
|||
"сообщение" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"сообщение": { |
|||
"title": "Сообщение", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"Item": { |
|||
"title": "Предмет", |
|||
"required": [ |
|||
"идентификатор", |
|||
"значение" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"идентификатор": { |
|||
"title": "Идентификатор", |
|||
"type": "string" |
|||
}, |
|||
"значение": { |
|||
"title": "Значение", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"ValidationError": { |
|||
"title": "Ошибка валидации", |
|||
"required": [ |
|||
"местоположение", |
|||
"сообщение", |
|||
"тип" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"местоположение": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"type": "string" |
|||
} |
|||
}, |
|||
"сообщение": { |
|||
"title": "Сообщение", |
|||
"type": "string" |
|||
}, |
|||
"тип": { |
|||
"title": "Тип ошибки", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"HTTPValidationError": { |
|||
"title": "Ошибка валидации HTTP", |
|||
"type": "object", |
|||
"properties": { |
|||
"детали": { |
|||
"title": "Детали", |
|||
"type": "array", |
|||
"items": { |
|||
"$ref": "#/components/schemas/ValidationError" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Дополнительные типы содержимого для основного ответа |
|||
|
|||
Вы можете использовать этот же параметр `responses`, чтобы добавить разные типы содержимого для одного и того же основного ответа. |
|||
|
|||
Например, вы можете добавить дополнительный медиа-тип `image/png`, объявив, что ваши *операции пути* могут возвращать JSON объект (с медиа-типом `application/json`) или изображение PNG: |
|||
|
|||
{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *} |
|||
|
|||
/// note | Заметка |
|||
|
|||
Обратите внимание, что вы должны возвращать изображение, используя `FileResponse` напрямую. |
|||
|
|||
/// |
|||
|
|||
/// info | Информация |
|||
|
|||
Если вы явно не указываете другой тип содержимого в вашем параметре `responses`, FastAPI предположит, что ответ имеет тот же тип содержимого, что и основной класс ответа (по умолчанию `application/json`). |
|||
|
|||
Но если вы задали пользовательский класс ответа с `None` в качестве типа содержимого, FastAPI будет использовать `application/json` для любого дополнительного ответа, у которого есть ассоциированная модель. |
|||
|
|||
/// |
|||
|
|||
## Комбинирование информации |
|||
|
|||
Вы также можете комбинировать информацию о ответах из разных мест, включая параметры `response_model`, `status_code` и `responses`. |
|||
|
|||
Вы можете объявить `response_model`, используя стандартный статус-код `200` (или пользовательский, если необходимо), а затем объявить дополнительную информацию для этого же ответа в `responses`, напрямую в схеме OpenAPI. |
|||
|
|||
**FastAPI** сохранит дополнительную информацию из `responses` и объединит ее с JSON Schema из вашей модели. |
|||
|
|||
Например, вы можете объявить ответ с кодом состояния `404`, который использует Pydantic-модель и имеет пользовательское `description`. |
|||
|
|||
И ответ с кодом состояния `200`, который использует ваш `response_model`, но включает пользовательский `example`: |
|||
|
|||
{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *} |
|||
|
|||
Все это будет объединено и включено в ваш OpenAPI, и показано в документации API: |
|||
|
|||
<img src="/img/tutorial/additional-responses/image01.png"> |
|||
|
|||
## Комбинирование предопределенных и пользовательских ответов |
|||
|
|||
Возможно, вы захотите иметь некоторые предопределенные ответы, которые применяются ко многим *операциям пути*, но хотите объединить их с пользовательскими ответами, необходимыми для каждой *операции пути*. |
|||
|
|||
Для таких случаев вы можете использовать технику Python "распаковка" `dict` с помощью `**dict_to_unpack`: |
|||
|
|||
```Python |
|||
old_dict = { |
|||
"old key": "old value", |
|||
"second old key": "second old value", |
|||
} |
|||
new_dict = {**old_dict, "new key": "new value"} |
|||
``` |
|||
|
|||
Здесь, `new_dict` будет содержать все пары `ключ-значение` из `old_dict` плюс новую пару `ключ-значение`: |
|||
|
|||
```Python |
|||
{ |
|||
"old key": "old value", |
|||
"second old key": "second old value", |
|||
"new key": "new value", |
|||
} |
|||
``` |
|||
|
|||
Вы можете использовать эту технику для повторного использования некоторых предопределенных ответов в ваших *операциях пути* и объединить их с дополнительными пользовательскими. |
|||
|
|||
Например: |
|||
|
|||
{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *} |
|||
|
|||
## Больше информации об ответах OpenAPI |
|||
|
|||
Чтобы узнать, что именно можно включить в ответы, вы можете посмотреть эти разделы в спецификации OpenAPI: |
|||
|
|||
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object" class="external-link" target="_blank">OpenAPI Responses Object</a>, включает в себя `Response Object`. |
|||
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object" class="external-link" target="_blank">OpenAPI Response Object</a>, вы можете включить что угодно из этого напрямую в каждый ответ внутри вашего параметра `responses`. Включая `description`, `headers`, `content` (внутри этого вы указываете разные типы медиа и JSON Schemas), и `links`. |
|||
@ -0,0 +1,65 @@ |
|||
# Продвинутые зависимости |
|||
|
|||
## Параметризуемые зависимости |
|||
|
|||
Все зависимости, которые мы видели, являются фиксированной функцией или классом. |
|||
|
|||
Но могут быть случаи, когда вы захотите иметь возможность задавать параметры для зависимости, не объявляя множество разных функций или классов. |
|||
|
|||
Представим, что мы хотим иметь зависимость, которая проверяет, содержит ли параметр запроса `q` некоторое фиксированное содержимое. |
|||
|
|||
Но нам нужно иметь возможность параметризовать это фиксированное содержимое. |
|||
|
|||
## "Вызываемый" экземпляр |
|||
|
|||
В Python есть способ сделать экземпляр класса "вызываемым". |
|||
|
|||
Не сам класс (он уже может быть вызываемым), а экземпляр этого класса. |
|||
|
|||
Для этого мы объявляем метод `__call__`: |
|||
|
|||
{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *} |
|||
|
|||
В этом случае **FastAPI** будет использовать этот `__call__` для проверки дополнительных параметров и под-зависимостей, и он будет вызываться для передачи значения в параметр вашей *функции-обработчика пути* позже. |
|||
|
|||
## Параметризация экземпляра |
|||
|
|||
Теперь мы можем использовать `__init__`, чтобы объявить параметры экземпляра, которые мы можем использовать для "параметризации" зависимости: |
|||
|
|||
{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[9] *} |
|||
|
|||
В данном случае **FastAPI** никогда не будет касаться или заботиться об `__init__`, мы будем использовать его напрямую в нашем коде. |
|||
|
|||
## Создание экземпляра |
|||
|
|||
Мы можем создать экземпляр этого класса с помощью: |
|||
|
|||
{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[18] *} |
|||
|
|||
Таким образом, мы можем "параметризовать" нашу зависимость, в которой теперь есть `"bar"`, как атрибут `checker.fixed_content`. |
|||
|
|||
## Использование экземпляра в качестве зависимости |
|||
|
|||
Затем мы могли бы использовать этот `checker` в `Depends(checker)`, вместо `Depends(FixedContentQueryChecker)`, потому что зависимость — это экземпляр `checker`, а не сам класс. |
|||
|
|||
И при разрешении зависимости, **FastAPI** вызовет этот `checker` так: |
|||
|
|||
```Python |
|||
checker(q="somequery") |
|||
``` |
|||
|
|||
...и передаст то, что это возвращает, как значение зависимости в нашей *функции-обработчике пути* как параметр `fixed_content_included`: |
|||
|
|||
{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[22] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Все это может показаться надуманным. И пока не совсем ясно, насколько это полезно. |
|||
|
|||
Эти примеры намеренно просты, но показывают, как все работает. |
|||
|
|||
В главах о безопасности есть утилиты-функции, которые реализованы таким же образом. |
|||
|
|||
Если вы все это поняли, вы уже знаете, как работают эти утилиты для безопасности изнутри. |
|||
|
|||
/// |
|||
@ -0,0 +1,361 @@ |
|||
# За прокси-сервером |
|||
|
|||
В некоторых ситуациях вам может понадобиться использовать **прокси**-сервер, такой как Traefik или Nginx, с конфигурацией, добавляющей дополнительный префикс к path, который ваше приложение не видит. |
|||
|
|||
В таких случаях вы можете использовать `root_path` для настройки вашего приложения. |
|||
|
|||
`root_path` — это механизм, предоставляемый спецификацией ASGI (на основе которой построен FastAPI через Starlette). |
|||
|
|||
`root_path` используется для обработки этих конкретных случаев. |
|||
|
|||
Он также используется внутренне при монтировании подприложений. |
|||
|
|||
## Прокси с вырезанным префиксом path |
|||
|
|||
Использование прокси с вырезанным префиксом path означает, что вы можете объявить путь как `/app` в своем коде. Но затем вы добавляете слой сверху (прокси), который помещает ваше приложение **FastAPI** под путь, такой как `/api/v1`. |
|||
|
|||
В этом случае оригинальный путь `/app` будет фактически работать как `/api/v1/app`. |
|||
|
|||
Несмотря на то, что весь ваш код написан с учетом использования только `/app`. |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial001.py hl[6] *} |
|||
|
|||
И прокси будет **"вырезать"** **префикс пути** на лету перед передачей запроса серверу приложения (вероятно, Uvicorn через CLI FastAPI), оставляя ваше приложение уверенным, что оно работает на `/app`, чтобы вам не пришлось обновлять весь код для включения префикса `/api/v1`. |
|||
|
|||
До этого момента все будет работать как обычно. |
|||
|
|||
Но затем, когда вы откроете встроенный интерфейс документации (фронтенд), он будет ожидать получить OpenAPI-схему на `/openapi.json`, вместо `/api/v1/openapi.json`. |
|||
|
|||
Поэтому фронтенд (который работает в браузере) попытается достичь `/openapi.json` и не сможет получить OpenAPI-схему. |
|||
|
|||
Поскольку у нас есть прокси с префиксом пути `/api/v1` для нашего приложения, фронтенд должен получить OpenAPI-схему на `/api/v1/openapi.json`. |
|||
|
|||
```mermaid |
|||
graph LR |
|||
|
|||
browser("Браузер") |
|||
proxy["Прокси на http://0.0.0.0:9999/api/v1/app"] |
|||
server["Сервер на http://127.0.0.1:8000/app"] |
|||
|
|||
browser --> proxy |
|||
proxy --> server |
|||
``` |
|||
|
|||
/// совет | Совет |
|||
|
|||
IP `0.0.0.0` обычно используется, чтобы указать, что программа слушает все доступные IP-адреса на этой машине/сервере. |
|||
|
|||
/// |
|||
|
|||
Интерфейс документации также будет нуждаться в OpenAPI-схеме для декларации, что этот API `server` расположен на `/api/v1` (за прокси). Например: |
|||
|
|||
```JSON hl_lines="4-8" |
|||
{ |
|||
"openapi": "3.1.0", |
|||
// Другие данные здесь |
|||
"servers": [ |
|||
{ |
|||
"url": "/api/v1" |
|||
} |
|||
], |
|||
"paths": { |
|||
// Другие данные здесь |
|||
} |
|||
} |
|||
``` |
|||
|
|||
В этом примере "Прокси" может быть чем-то вроде **Traefik**. А сервером может быть что-то вроде CLI FastAPI с **Uvicorn**, который запускает ваше приложение FastAPI. |
|||
|
|||
### Указание `root_path` |
|||
|
|||
Чтобы достичь этого, вы можете использовать командную строку с опцией `--root-path`, например: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi run main.py --root-path /api/v1 |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn запущен на http://127.0.0.1:8000 (Нажмите CTRL+C для остановки) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Если вы используете Hypercorn, у него также есть опция `--root-path`. |
|||
|
|||
/// note | Технические подробности |
|||
|
|||
Спецификация ASGI определяет `root_path` для этого случая использования. |
|||
|
|||
И опция командной строки `--root-path` предоставляет этот `root_path`. |
|||
|
|||
/// |
|||
|
|||
### Проверка текущего `root_path` |
|||
|
|||
Вы можете получить текущий `root_path`, используемый вашим приложением для каждого запроса, он является частью словаря `scope` (это часть спецификации ASGI). |
|||
|
|||
Здесь мы включаем его в сообщение просто для демонстрации. |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial001.py hl[8] *} |
|||
|
|||
Затем, если вы запустите Uvicorn с: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi run main.py --root-path /api/v1 |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn запущен на http://127.0.0.1:8000 (Нажмите CTRL+C для остановки) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Ответ будет что-то вроде: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
### Установка `root_path` в приложении FastAPI |
|||
|
|||
Альтернативно, если у вас нет возможности предоставить опцию командной строки, такую как `--root-path` или аналогичную, вы можете установить параметр `root_path` при создании вашего приложения FastAPI: |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial002.py hl[3] *} |
|||
|
|||
Передача `root_path` в `FastAPI` будет эквивалентна передаче опции командной строки `--root-path` для Uvicorn или Hypercorn. |
|||
|
|||
### О `root_path` |
|||
|
|||
Учтите, что сервер (Uvicorn) не будет использовать `root_path` ни для чего, кроме передачи его приложению. |
|||
|
|||
Но если вы зайдете через браузер по адресу <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000/app</a>, вы увидите обычный ответ: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
Итак, он не будет ожидать доступа по адресу `http://127.0.0.1:8000/api/v1/app`. |
|||
|
|||
Uvicorn будет ожидать, что прокси получит доступ к Uvicorn по адресу `http://127.0.0.1:8000/app`, а затем это будет уже ответственность прокси — добавить дополнительный префикс `/api/v1`. |
|||
|
|||
## О прокси с вырезанным префиксом path |
|||
|
|||
Имейте в виду, что прокси с вырезанным префиксом path — это всего лишь один из способов его настройки. |
|||
|
|||
Вероятно, во многих случаях по умолчанию будет то, что у прокси нет вырезанного префикса path. |
|||
|
|||
В случае, подобном этому (без вырезанного префикса path), прокси будет слушать что-то вроде `https://myawesomeapp.com`, и тогда, если браузер перейдет на `https://myawesomeapp.com/api/v1/app`, а ваш сервер (например, Uvicorn) слушает на `http://127.0.0.1:8000`, прокси (без вырезанного префикса path) получит доступ к Uvicorn на том же пути: `http://127.0.0.1:8000/api/v1/app`. |
|||
|
|||
## Тестирование локально с Traefik |
|||
|
|||
Вы можете легко провести эксперимент локально с вырезанным префиксом path, используя <a href="https://docs.traefik.io/" class="external-link" target="_blank">Traefik</a>. |
|||
|
|||
<a href="https://github.com/containous/traefik/releases" class="external-link" target="_blank">Скачайте Traefik</a>, это один исполняемый файл, вы можете извлечь сжатый файл и запустить его прямо из терминала. |
|||
|
|||
Затем создайте файл `traefik.toml` с: |
|||
|
|||
```TOML hl_lines="3" |
|||
[entryPoints] |
|||
[entryPoints.http] |
|||
address = ":9999" |
|||
|
|||
[providers] |
|||
[providers.file] |
|||
filename = "routes.toml" |
|||
``` |
|||
|
|||
Это указывает Traefik слушать на порту 9999 и использовать другой файл `routes.toml`. |
|||
|
|||
/// совет |
|||
|
|||
Мы используем порт 9999 вместо стандартного порта HTTP 80, чтобы вам не пришлось запускать это с привилегиями администратора (`sudo`). |
|||
|
|||
/// |
|||
|
|||
Теперь создайте другой файл `routes.toml`: |
|||
|
|||
```TOML hl_lines="5 12 20" |
|||
[http] |
|||
[http.middlewares] |
|||
|
|||
[http.middlewares.api-stripprefix.stripPrefix] |
|||
prefixes = ["/api/v1"] |
|||
|
|||
[http.routers] |
|||
|
|||
[http.routers.app-http] |
|||
entryPoints = ["http"] |
|||
service = "app" |
|||
rule = "PathPrefix(`/api/v1`)" |
|||
middlewares = ["api-stripprefix"] |
|||
|
|||
[http.services] |
|||
|
|||
[http.services.app] |
|||
[http.services.app.loadBalancer] |
|||
[[http.services.app.loadBalancer.servers]] |
|||
url = "http://127.0.0.1:8000" |
|||
``` |
|||
|
|||
Этот файл настраивает Traefik для использования префикса path `/api/v1`. |
|||
|
|||
А затем Traefik перенаправит свои запросы на ваш Uvicorn, запущенный на `http://127.0.0.1:8000`. |
|||
|
|||
Теперь запустите Traefik: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ ./traefik --configFile=traefik.toml |
|||
|
|||
INFO[0000] Конфигурация загружена из файла: /home/user/awesomeapi/traefik.toml |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
И теперь запустите ваше приложение, используя опцию `--root-path`: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi run main.py --root-path /api/v1 |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn запущен на http://127.0.0.1:8000 (Нажмите CTRL+C для остановки) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
### Проверьте ответы |
|||
|
|||
Теперь, если вы перейдете по URL с портом для Uvicorn: <a href="http://127.0.0.1:8000/app" class="external-link" target="_blank">http://127.0.0.1:8000/app</a>, вы увидите нормальный ответ: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
/// совет | Совет |
|||
|
|||
Обратите внимание, что, хотя вы получаете доступ к нему по адресу `http://127.0.0.1:8000/app`, он отображает `root_path` как `/api/v1`, взятый из опции `--root-path`. |
|||
|
|||
/// |
|||
|
|||
А теперь откройте URL с портом для Traefik, включая префикс path: <a href="http://127.0.0.1:9999/api/v1/app" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/app</a>. |
|||
|
|||
Мы получаем такой же ответ: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
но на этот раз по URL с префиксом path, предоставленным прокси: `/api/v1`. |
|||
|
|||
Конечно, идея здесь в том, что все должны получить доступ к приложению через прокси, так что версия с префиксом path `/api/v1` — это "правильная" версия. |
|||
|
|||
И версия без префикса path (`http://127.0.0.1:8000/app`), предоставляемая напрямую Uvicorn, будет исключительно для _прокси_ (Traefik), чтобы получить к ней доступ. |
|||
|
|||
Это демонстрирует, как прокси (Traefik) использует префикс path и как сервер (Uvicorn) использует `root_path` из опции `--root-path`. |
|||
|
|||
### Проверьте интерфейс документации |
|||
|
|||
Но вот где начинается веселье. ✨ |
|||
|
|||
"Официальный" способ доступа к приложению будет через прокси с префиксом path, который мы определили. Поэтому, как и ожидалось, если вы попытаетесь использовать интерфейс документации, обслуживаемый Uvicorn напрямую, без префикса path в URL, он не будет работать, потому что предполагается, что доступ будет осуществляться через прокси. |
|||
|
|||
Вы можете проверить это по адресу <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>: |
|||
|
|||
<img src="/img/tutorial/behind-a-proxy/image01.png"> |
|||
|
|||
Но если мы получим доступ к интерфейсу документации по "официальному" URL, используя прокси с портом `9999`, по адресу `/api/v1/docs`, он работает правильно! 🎉 |
|||
|
|||
Вы можете проверить это по адресу <a href="http://127.0.0.1:9999/api/v1/docs" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/docs</a>: |
|||
|
|||
<img src="/img/tutorial/behind-a-proxy/image02.png"> |
|||
|
|||
Как и хотели. ✔️ |
|||
|
|||
Это потому, что FastAPI использует этот `root_path` для создания `server` по умолчанию в OpenAPI с URL, предоставленным `root_path`. |
|||
|
|||
## Дополнительные серверы |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
Это более сложный случай использования. Вы можете пропустить его, если хотите. |
|||
|
|||
/// |
|||
|
|||
По умолчанию **FastAPI** создаст `server` в схеме OpenAPI с URL для `root_path`. |
|||
|
|||
Но вы также можете предоставить другие альтернативные `servers`, например, если вы хотите, чтобы *этот же* интерфейс документации взаимодействовал как со средой тестирования, так и со средой продакшн. |
|||
|
|||
Если вы передаете пользовательский список `servers` и существует `root_path` (потому что ваш API находится за прокси), **FastAPI** вставит "server" с этим `root_path` в начало списка. |
|||
|
|||
Например: |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *} |
|||
|
|||
Создаст схему OpenAPI, как: |
|||
|
|||
```JSON hl_lines="5-7" |
|||
{ |
|||
"openapi": "3.1.0", |
|||
// Другие данные здесь |
|||
"servers": [ |
|||
{ |
|||
"url": "/api/v1" |
|||
}, |
|||
{ |
|||
"url": "https://stag.example.com", |
|||
"description": "Тестовая среда" |
|||
}, |
|||
{ |
|||
"url": "https://prod.example.com", |
|||
"description": "Продакшн среда" |
|||
} |
|||
], |
|||
"paths": { |
|||
// Другие данные здесь |
|||
} |
|||
} |
|||
``` |
|||
|
|||
/// совет | Совет |
|||
|
|||
Обратите внимание на автоматически сгенерированный сервер с `url` значением `/api/v1`, взятым из `root_path`. |
|||
|
|||
/// |
|||
|
|||
В интерфейсе документации по адресу <a href="http://127.0.0.1:9999/api/v1/docs" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/docs</a> это будет выглядеть так: |
|||
|
|||
<img src="/img/tutorial/behind-a-proxy/image03.png"> |
|||
|
|||
/// совет | Совет |
|||
|
|||
Интерфейс документации будет взаимодействовать с сервером, который вы выберете. |
|||
|
|||
/// |
|||
|
|||
### Отключение автоматического сервера от `root_path` |
|||
|
|||
Если вы не хотите, чтобы **FastAPI** включал автоматический сервер, используя `root_path`, вы можете использовать параметр `root_path_in_servers=False`: |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *} |
|||
|
|||
и тогда он не будет включен в схему OpenAPI. |
|||
|
|||
## Монтирование подприложения |
|||
|
|||
Если вам нужно смонтировать подприложение (как описано в [Подприложения - Монтирование](sub-applications.md){.internal-link target=_blank}), используя также прокси с `root_path`, вы можете сделать это обычным образом, как и ожидалось. |
|||
|
|||
FastAPI будет использовать `root_path` умно, поэтому все будет работать, как и задумано. ✨ |
|||
@ -0,0 +1,313 @@ |
|||
# Пользовательский ответ - HTML, поток, файл и другие |
|||
|
|||
По умолчанию **FastAPI** будет возвращать ответы, используя `JSONResponse`. |
|||
|
|||
Вы можете переопределить это, возвращая `Response` напрямую, как показано в разделе [Возврат Response напрямую](response-directly.md){.internal-link target=_blank}. |
|||
|
|||
Но если вы возвращаете `Response` напрямую (или любой подкласс, такой как `JSONResponse`), данные не будут автоматически конвертироваться (даже если вы объявите `response_model`), и документация не будет автоматически генерироваться (например, включая конкретный "тип содержимого", в HTTP-заголовке `Content-Type` как часть генерируемого OpenAPI). |
|||
|
|||
Но вы также можете объявить `Response`, который хотите использовать (например, любой подкласс `Response`), в *декораторе операции пути*, используя параметр `response_class`. |
|||
|
|||
Содержимое, которое вы возвращаете из вашей *функции-обработчика пути*, будет помещено внутрь этого `Response`. |
|||
|
|||
И если этот `Response` имеет JSON тип содержимого (`application/json`), как в случае с `JSONResponse` и `UJSONResponse`, данные, которые вы возвращаете, будут автоматически конвертироваться (и фильтроваться) с помощью любого Pydantic `response_model`, который вы объявили в *декораторе операции пути*. |
|||
|
|||
/// note | Замечание |
|||
|
|||
Если вы используете класс ответа без типа содержимого, FastAPI ожидает, что ваш ответ не будет содержать контент, поэтому он не задокументирует формат ответа в автоматически генерируемой документации OpenAPI. |
|||
|
|||
/// |
|||
|
|||
## Использование `ORJSONResponse` |
|||
|
|||
Например, если вы заботитесь о производительности, вы можете установить и использовать <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a> и установить ответ `ORJSONResponse`. |
|||
|
|||
Импортируйте класс (подкласс) `Response`, который вы хотите использовать, и объявите его в *декораторе операции пути*. |
|||
|
|||
Для больших ответов возврат `Response` напрямую значительно быстрее, чем возврат словаря. |
|||
|
|||
Это происходит потому, что по умолчанию FastAPI будет проверять каждый элемент внутри и убеждаться, что он сериализуем как JSON, используя тот же [Совместимый с JSON кодировщик](../tutorial/encoder.md){.internal-link target=_blank}, о котором рассказано в руководстве. Это позволяет вам возвращать **произвольные объекты**, например, модели базы данных. |
|||
|
|||
Но если вы уверены, что содержимое, которое вы возвращаете, **сериализуемо с JSON**, вы можете передать его напрямую в класс ответа и избежать дополнительной нагрузки, которую FastAPI имел бы, передавая возвращаемый контент через `jsonable_encoder` перед передачей его в класс ответа. |
|||
|
|||
{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *} |
|||
|
|||
/// info | Информация |
|||
|
|||
Параметр `response_class` также будет использоваться для определения "типа содержимого" ответа. |
|||
|
|||
В данном случае HTTP-заголовок `Content-Type` будет установлен в `application/json`. |
|||
|
|||
И он будет задокументирован как таковой в OpenAPI. |
|||
|
|||
/// |
|||
|
|||
/// tip | Совет |
|||
|
|||
`ORJSONResponse` доступен только в FastAPI, не в Starlette. |
|||
|
|||
/// |
|||
|
|||
## HTML-ответ |
|||
|
|||
Чтобы вернуть ответ с HTML напрямую из **FastAPI**, используйте `HTMLResponse`. |
|||
|
|||
* Импортируйте `HTMLResponse`. |
|||
* Передайте `HTMLResponse` в качестве параметра `response_class` вашего *декоратора операции пути*. |
|||
|
|||
{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *} |
|||
|
|||
/// info | Информация |
|||
|
|||
Параметр `response_class` также будет использоваться для определения "типа содержимого" ответа. |
|||
|
|||
В этом случае HTTP-заголовок `Content-Type` будет установлен в `text/html`. |
|||
|
|||
И он будет задокументирован как таковой в OpenAPI. |
|||
|
|||
/// |
|||
|
|||
### Возврат `Response` |
|||
|
|||
Как показано в разделе [Возврат Response напрямую](response-directly.md){.internal-link target=_blank}, вы также можете переопределить ответ напрямую в вашей *операции пути*, возвращая его. |
|||
|
|||
Тот же пример, что и выше, возвращающий `HTMLResponse`, может выглядеть так: |
|||
|
|||
{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *} |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
`Response`, возвращенный напрямую вашей *функцией-обработчиком пути*, не будет задокументирован в OpenAPI (например, `Content-Type` не будет задокументирован) и не будет виден в автоматически генерируемой интерактивной документации. |
|||
|
|||
/// |
|||
|
|||
/// info | Информация |
|||
|
|||
Конечно, фактический заголовок `Content-Type`, статус-код и др., будут из объекта `Response`, который вы вернули. |
|||
|
|||
/// |
|||
|
|||
### Документирование в OpenAPI и переопределение `Response` |
|||
|
|||
Если вы хотите переопределить ответ из функции, но при этом документация должна содержать "тип содержимого" в OpenAPI, вы можете использовать параметр `response_class` И вернуть объект `Response`. |
|||
|
|||
Тогда `response_class` будет использоваться только для документирования OpenAPI *операции пути*, но ваш `Response` будет использоваться как есть. |
|||
|
|||
#### Возврат `HTMLResponse` напрямую |
|||
|
|||
Например, это может быть что-то вроде: |
|||
|
|||
{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *} |
|||
|
|||
В этом примере функция `generate_html_response()` уже генерирует и возвращает `Response` вместо возврата HTML в виде `str`. |
|||
|
|||
Возвращая результат вызова `generate_html_response()`, вы уже возвращаете `Response`, который переопределит поведение **FastAPI** по умолчанию. |
|||
|
|||
Но так как вы также передали `HTMLResponse` в `response_class`, **FastAPI** будет знать, как задокументировать это в OpenAPI и интерактивной документации как HTML с `text/html`: |
|||
|
|||
<img src="/img/tutorial/custom-response/image01.png"> |
|||
|
|||
## Доступные ответы |
|||
|
|||
Вот некоторые из доступных ответов. |
|||
|
|||
Имейте в виду, что вы можете использовать `Response` для возврата чего-либо еще или даже создать собственный подкласс. |
|||
|
|||
/// note | Технические детали |
|||
|
|||
Вы также можете использовать `from starlette.responses import HTMLResponse`. |
|||
|
|||
**FastAPI** предоставляет те же `starlette.responses`, что и `fastapi.responses`, просто для вашего удобства, как разработчика. Но большинство доступных ответов поступают напрямую из Starlette. |
|||
|
|||
/// |
|||
|
|||
### `Response` |
|||
|
|||
Основной класс `Response`, все остальные ответы наследуются от него. |
|||
|
|||
Вы можете вернуть его напрямую. |
|||
|
|||
Он принимает следующие параметры: |
|||
|
|||
* `content` - `str` или `bytes`. |
|||
* `status_code` - `int` HTTP статус-код. |
|||
* `headers` - `dict` строк. |
|||
* `media_type` - `str`, который задает тип содержимого, например `"text/html"`. |
|||
|
|||
FastAPI (фактически Starlette) автоматически добавит заголовок Content-Length. Он также включит заголовок Content-Type, основанный на `media_type` и добавит кодировку для текстовых типов. |
|||
|
|||
{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} |
|||
|
|||
### `HTMLResponse` |
|||
|
|||
Принимает текст или байты и возвращает HTML-ответ, как вы прочли выше. |
|||
|
|||
### `PlainTextResponse` |
|||
|
|||
Принимает текст или байты и возвращает ответ с простым текстом. |
|||
|
|||
{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *} |
|||
|
|||
### `JSONResponse` |
|||
|
|||
Принимает данные и возвращает ответ, кодированный как `application/json`. |
|||
|
|||
Это ответ по умолчанию, используемый в **FastAPI**, как вы прочли выше. |
|||
|
|||
### `ORJSONResponse` |
|||
|
|||
Быстрая альтернатива JSON-ответа, использующая <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a>, как вы прочли выше. |
|||
|
|||
/// info | Информация |
|||
|
|||
Для этого требуется установка `orjson`, например с помощью `pip install orjson`. |
|||
|
|||
/// |
|||
|
|||
### `UJSONResponse` |
|||
|
|||
Альтернативный JSON-ответ, использующий <a href="https://github.com/ultrajson/ultrajson" class="external-link" target="_blank">`ujson`</a>. |
|||
|
|||
/// info | Информация |
|||
|
|||
Для этого требуется установка `ujson`, например с помощью `pip install ujson`. |
|||
|
|||
/// |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
`ujson` менее осторожна, чем встроенная реализация Python, в том, как она обрабатывает некоторые крайние случаи. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Возможно, `ORJSONResponse` может быть более быстрой альтернативой. |
|||
|
|||
/// |
|||
|
|||
### `RedirectResponse` |
|||
|
|||
Возвращает HTTP-перенаправление. Использует статус-код 307 (Временное перенаправление) по умолчанию. |
|||
|
|||
Вы можете вернуть `RedirectResponse` напрямую: |
|||
|
|||
{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *} |
|||
|
|||
--- |
|||
|
|||
Или вы можете использовать его в параметре `response_class`: |
|||
|
|||
|
|||
{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *} |
|||
|
|||
Если вы сделаете это, то можете вернуть URL непосредственно из вашей *функции-обработчика пути*. |
|||
|
|||
В этом случае, используемый `status_code` будет тем, что по умолчанию для `RedirectResponse`, а именно `307`. |
|||
|
|||
--- |
|||
|
|||
Вы также можете использовать параметр `status_code` в сочетании с параметром `response_class`: |
|||
|
|||
{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *} |
|||
|
|||
### `StreamingResponse` |
|||
|
|||
Принимает асинхронный генератор или обычный генератор/итератор и отправляет тело ответа в потоке. |
|||
|
|||
{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *} |
|||
|
|||
#### Использование `StreamingResponse` с объектами, похожими на файлы |
|||
|
|||
Если у вас есть объект, похожий на файл (например, объект, возвращаемый `open()`), вы можете создать функцию-генератор для итерации по этому объекту. |
|||
|
|||
Таким образом, вам не нужно предварительно загружать все в память, и вы можете передать эту функцию-генератор в `StreamingResponse` и вернуть ее. |
|||
|
|||
Это включает множество библиотек для взаимодействия с облачным хранилищем, обработки видео и других. |
|||
|
|||
{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *} |
|||
|
|||
1. Это функция-генератор. Это "функция-генератор", потому что она содержит оператор `yield`. |
|||
2. Используя блок `with`, мы обеспечиваем закрытие объекта, похожего на файл, после завершения выполнения функции-генератора. То есть после того, как отправка ответа завершена. |
|||
3. Этот `yield from` указывает функции итерироваться по объекту `file_like`. Затем для каждой части, которую итерация проходит, возвращать эту часть из функции-генератора (`iterfile`). |
|||
|
|||
Таким образом, это функция-генератор, которая передает работу по "генерации" чему-то еще во внутренности. |
|||
|
|||
Делая так, мы можем поместить это в блок `with` и таким образом обеспечить закрытие объекта, похожего на файл, после завершения. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Обратите внимание, что здесь, так как мы используем стандартный `open()`, который не поддерживает `async` и `await`, мы объявляем операцию пути с использованием обычного `def`. |
|||
|
|||
/// |
|||
|
|||
### `FileResponse` |
|||
|
|||
Асинхронно отправляет файл в поток как ответ. |
|||
|
|||
Принимает другой набор аргументов для создания экземпляра, чем другие типы ответов: |
|||
|
|||
* `path` - Путь к файлу, который необходимо отправить в поток. |
|||
* `headers` - Любые пользовательские заголовки, которые необходимо включить, в виде словаря. |
|||
* `media_type` - Строка, задающая тип содержимого. Если не установлено, для определения типа содержимого будет использоваться имя файла или путь. |
|||
* `filename` - Если установлено, это будет включено в заголовок `Content-Disposition` ответа. |
|||
|
|||
Ответы на файлы будут включать соответствующие заголовки `Content-Length`, `Last-Modified` и `ETag`. |
|||
|
|||
{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *} |
|||
|
|||
Вы также можете использовать параметр `response_class`: |
|||
|
|||
{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *} |
|||
|
|||
В этом случае, вы можете вернуть путь к файлу напрямую из вашей *функции-обработчика пути*. |
|||
|
|||
## Класс пользовательского ответа |
|||
|
|||
Вы можете создать свой собственный класс пользовательского ответа, наследуя от `Response` и используя его. |
|||
|
|||
Например, предположим, вы хотите использовать <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a>, но с некоторыми пользовательскими настройками, не используемыми в включенном классе `ORJSONResponse`. |
|||
|
|||
Допустим, вы хотите, чтобы он возвращал JSON с отступами и форматированием, поэтому вы хотите использовать опцию orjson `orjson.OPT_INDENT_2`. |
|||
|
|||
Вы могли бы создать `CustomORJSONResponse`. Главное, что вам нужно сделать, это создать метод `Response.render(content)`, который возвращает содержимое как `bytes`: |
|||
|
|||
{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *} |
|||
|
|||
Теперь вместо возвращения: |
|||
|
|||
```json |
|||
{"message": "Hello World"} |
|||
``` |
|||
|
|||
...этот ответ вернет: |
|||
|
|||
```json |
|||
{ |
|||
"message": "Hello World" |
|||
} |
|||
``` |
|||
|
|||
Конечно, вы, вероятно, найдете гораздо лучшие способы использовать это, чем форматирование JSON. 😉 |
|||
|
|||
## Класс ответа по умолчанию |
|||
|
|||
При создании экземпляра класса **FastAPI** или `APIRouter` вы можете указать, какой класс ответа использовать по умолчанию. |
|||
|
|||
Параметр, который это определяет, называется `default_response_class`. |
|||
|
|||
В приведенном ниже примере **FastAPI** будет использовать `ORJSONResponse` по умолчанию во всех *операциях пути* вместо `JSONResponse`. |
|||
|
|||
{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Вы все еще можете переопределять `response_class` в *операциях пути*, как и раньше. |
|||
|
|||
/// |
|||
|
|||
## Дополнительная документация |
|||
|
|||
Вы также можете объявить тип содержимого и многие другие детали в OpenAPI, используя `responses`: [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. |
|||
@ -0,0 +1,95 @@ |
|||
# Использование Dataclasses |
|||
|
|||
FastAPI построен на основе **Pydantic**, и я уже показывал вам, как использовать модели Pydantic для объявления HTTP-запросов и HTTP-ответов. |
|||
|
|||
Но FastAPI также поддерживает использование <a href="https://docs.python.org/3/library/dataclasses.html" class="external-link" target="_blank">`dataclasses`</a> таким же образом: |
|||
|
|||
{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *} |
|||
|
|||
Это по-прежнему поддерживается благодаря **Pydantic**, так как в нем есть <a href="https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel" class="external-link" target="_blank">внутренняя поддержка `dataclasses`</a>. |
|||
|
|||
Итак, даже с приведенным выше кодом, который явно не использует Pydantic, FastAPI использует Pydantic для преобразования стандартных dataclasses в собственный вариант dataclasses от Pydantic. |
|||
|
|||
И, конечно же, он поддерживает то же самое: |
|||
|
|||
* валидация данных |
|||
* сериализация данных |
|||
* документация данных и т.д. |
|||
|
|||
Это работает так же, как и с моделями Pydantic. И это фактически достигается таким же образом, под капотом, с использованием Pydantic. |
|||
|
|||
/// info | Информация |
|||
|
|||
Имейте в виду, что dataclasses не могут выполнять все то, что могут делать модели Pydantic. |
|||
|
|||
Поэтому, возможно, вам все равно придется использовать модели Pydantic. |
|||
|
|||
Но если у вас есть много dataclasses, это отличный трюк, чтобы использовать их для создания веб-API с помощью FastAPI. 🤓 |
|||
|
|||
/// |
|||
|
|||
## Dataclasses в `response_model` |
|||
|
|||
Вы также можете использовать `dataclasses` в параметре `response_model`: |
|||
|
|||
{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *} |
|||
|
|||
Dataclass будет автоматически преобразован в Pydantic dataclass. |
|||
|
|||
Таким образом, его схема будет отображаться в интерфейсе документации API: |
|||
|
|||
<img src="/img/tutorial/dataclasses/image01.png"> |
|||
|
|||
## Dataclasses в Вложенных Структурах Данных |
|||
|
|||
Вы также можете комбинировать `dataclasses` с другими аннотациями типов для создания вложенных структур данных. |
|||
|
|||
В некоторых случаях, возможно, вам все равно придется использовать версию `dataclasses` от Pydantic. Например, если у вас возникли ошибки с автоматической генерацией документации API. |
|||
|
|||
В этом случае вы можете просто заменить стандартные `dataclasses` на `pydantic.dataclasses`, что является заменой "на лету": |
|||
|
|||
{* ../../docs_src/dataclasses/tutorial003.py hl[1,5,8:11,14:17,23:25,28] *} |
|||
|
|||
1. Мы по-прежнему импортируем `field` из стандартных `dataclasses`. |
|||
|
|||
2. `pydantic.dataclasses` является заменой "на лету" для `dataclasses`. |
|||
|
|||
3. Dataclass `Author` включает список dataclasses `Item`. |
|||
|
|||
4. Dataclass `Author` используется как параметр `response_model`. |
|||
|
|||
5. Вы можете использовать другие стандартные аннотации типов с dataclasses как HTTP-тело запроса. |
|||
|
|||
В этом случае это список dataclasses `Item`. |
|||
|
|||
6. Здесь мы возвращаем словарь, содержащий `items`, который является списком dataclasses. |
|||
|
|||
FastAPI по-прежнему способен <abbr title="конвертирование данных в формат, который может быть передан">сериализовать</abbr> данные в JSON. |
|||
|
|||
7. Здесь `response_model` использует аннотацию типа список dataclasses `Author`. |
|||
|
|||
Снова вы можете комбинировать `dataclasses` с стандартными аннотациями типов. |
|||
|
|||
8. Обратите внимание, что эта *функция-обработчик пути* использует обычный `def` вместо `async def`. |
|||
|
|||
Как всегда, в FastAPI вы можете сочетать `def` и `async def` в зависимости от необходимости. |
|||
|
|||
Если вы забыли, когда использовать какой, посмотрите раздел _"Нет времени?"_ в документации о [`async` и `await`](../async.md#in-a-hurry){.internal-link target=_blank}. |
|||
|
|||
9. Эта *функция-обработчик пути* не возвращает dataclasses (хотя могла бы), а список словарей с внутренними данными. |
|||
|
|||
FastAPI будет использовать параметр `response_model` (который включает dataclasses), чтобы преобразовать ответ. |
|||
|
|||
Вы можете комбинировать `dataclasses` с другими аннотациями типов в различных комбинациях, чтобы формировать сложные структуры данных. |
|||
|
|||
Посмотрите советы по аннотации в коде выше, чтобы узнать больше деталей. |
|||
|
|||
## Узнать больше |
|||
|
|||
Вы также можете комбинировать `dataclasses` с другими моделями Pydantic, наследовать их, включать их в свои собственные модели и т.д. |
|||
|
|||
Чтобы узнать больше, ознакомьтесь с <a href="https://docs.pydantic.dev/latest/concepts/dataclasses/" class="external-link" target="_blank">документацией Pydantic о dataclasses</a>. |
|||
|
|||
## Версия |
|||
|
|||
Это доступно начиная с версии FastAPI `0.67.0`. 🔖 |
|||
@ -0,0 +1,165 @@ |
|||
# События жизненного цикла |
|||
|
|||
Вы можете определить логику (код), которая должна быть выполнена перед запуском приложения. Это значит, что данный код будет выполнен **единожды**, **перед** тем, как приложение **начнет принимать HTTP-запросы**. |
|||
|
|||
Аналогично, вы можете определить логику (код), которая должна быть выполнена при остановке приложения. В этом случае код будет выполнен **единожды**, **после** обработки, возможно, **множества HTTP-запросов**. |
|||
|
|||
Поскольку этот код выполняется до того, как приложение **начинает** принимать запросы, и непосредственно после того, как оно **заканчивает** обработку запросов, он охватывает весь **lifespan** приложения (слово "lifespan" сейчас станет важным 😉). |
|||
|
|||
Это может быть очень полезно для настройки **ресурсов**, которые вам нужно использовать для всего приложения, и которые **разделяются** между запросами, и/или которые требуют **освобождения** после завершения работы. Например, пул подключений к базе данных или загрузка общей модели машинного обучения. |
|||
|
|||
## Пример использования |
|||
|
|||
Давайте начнем с примера **использования**, а затем посмотрим, как его решить. |
|||
|
|||
Предположим, у вас есть несколько **моделей машинного обучения**, которые вы хотите использовать для обработки запросов. 🤖 |
|||
|
|||
Те же самые модели разделяются между всеми запросами, то есть это не одна модель на запрос или одна на пользователя или что-то подобное. |
|||
|
|||
Представим, что загрузка модели может **занять значительное время**, потому что необходимо прочитать много **данных с диска**. Поэтому вы не хотите делать это для каждого запроса. |
|||
|
|||
Вы можете загрузить ее на верхнем уровне модуля/файла, но это также означало бы, что модель **загрузится**, даже если вы просто запускаете простой автоматизированный тест, и такой тест был бы **медленный**, так как пришлось бы ждать, пока модель загрузится, прежде чем можно было бы выполнить независимую часть кода. |
|||
|
|||
Это то, что мы решаем: давайте загрузим модель до того, как запросы начнут обрабатываться, но только непосредственно перед тем, как приложение начнет принимать запросы, а не в процессе загрузки кода. |
|||
|
|||
## Lifespan |
|||
|
|||
Вы можете определить эту логику *запуска* и *выключения* с помощью параметра `lifespan` в приложении `FastAPI` и "менеджера контекста" (я покажу вам, что это такое, через мгновение). |
|||
|
|||
Давайте начнем с примера и затем разберем его подробно. |
|||
|
|||
Создаем асинхронную функцию `lifespan()` с `yield` следующим образом: |
|||
|
|||
{* ../../docs_src/events/tutorial003.py hl[16,19] *} |
|||
|
|||
Здесь мы симулируем дорогостоящую операцию *запуска*, загружая модель, помещая (фальшивую) функцию модели в словарь с моделями машинного обучения перед `yield`. Этот код будет выполнен **до** того, как приложение **начнет принимать запросы**, в процессе *запуска*. |
|||
|
|||
И затем, сразу после `yield`, мы выгружаем модель. Этот код будет выполнен **после** того, как приложение **завершит обработку запросов**, непосредственно перед *выключением*. Это может, например, освободить такие ресурсы, как память или GPU. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Выключение происходит, когда вы **останавливаете** приложение. |
|||
|
|||
Возможно, вам нужно запустить новую версию, или вы просто устали от его работы. 🤷 |
|||
|
|||
/// |
|||
|
|||
### Функция Lifespan |
|||
|
|||
Первое, что следует заметить, это то, что мы определяем асинхронную функцию с `yield`. Это очень похоже на зависимости с `yield`. |
|||
|
|||
{* ../../docs_src/events/tutorial003.py hl[14:19] *} |
|||
|
|||
Первая часть функции, до `yield`, будет выполнена **до** того, как приложение начнет свою работу. |
|||
|
|||
А часть после `yield` будет выполнена **после** завершения работы приложения. |
|||
|
|||
### Асинхронный менеджер контекста |
|||
|
|||
Если вы посмотрите, функция декорирована с помощью `@asynccontextmanager`. |
|||
|
|||
Это преобразует функцию в нечто, называемое "**асинхронным менеджером контекста**". |
|||
|
|||
{* ../../docs_src/events/tutorial003.py hl[1,13] *} |
|||
|
|||
**Менеджер контекста** в Python - это нечто, что вы можете использовать в операторе `with`, например, `open()` может быть использован как менеджер контекста: |
|||
|
|||
```Python |
|||
with open("file.txt") as file: |
|||
file.read() |
|||
``` |
|||
|
|||
В последних версиях Python также существует **асинхронный менеджер контекста**. Вы бы использовали его с `async with`: |
|||
|
|||
```Python |
|||
async with lifespan(app): |
|||
await do_stuff() |
|||
``` |
|||
|
|||
Когда вы создаете менеджер контекста или асинхронный менеджер контекста, как выше, его работа заключается в том, что, до входа в блок `with`, он выполняет код перед `yield`, и после выхода из блока `with`, он выполняет код после `yield`. |
|||
|
|||
В нашем примере кода выше мы не используем его напрямую, но передаем его FastAPI для использования. |
|||
|
|||
Параметр `lifespan` приложения `FastAPI` принимает **асинхронный менеджер контекста**, так что мы можем передать ему наш новый асинхронный менеджер контекста `lifespan`. |
|||
|
|||
{* ../../docs_src/events/tutorial003.py hl[22] *} |
|||
|
|||
## Альтернативные события (устаревшие) |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
Рекомендуемый способ обработки *запуска* и *выключения* — это использование параметра `lifespan` приложения `FastAPI`, как описано выше. Если вы предоставите параметр `lifespan`, обработчики событий `startup` и `shutdown` больше не будут вызываться. Вы можете использовать либо `lifespan`, либо события, но не оба. |
|||
|
|||
Эту часть можно, вероятно, пропустить. |
|||
|
|||
/// |
|||
|
|||
Существует альтернативный способ определения логики, которая будет выполнена во время *запуска* и во время *выключения*. |
|||
|
|||
Вы можете определить обработчики событий (функции), которые необходимо выполнить до запуска приложения или при его остановке. |
|||
|
|||
Эти функции могут быть объявлены как `async def`, так и обычный `def`. |
|||
|
|||
### Событие `startup` |
|||
|
|||
Чтобы добавить функцию, которую следует запустить перед запуском приложения, объявите ее с событием `"startup"`: |
|||
|
|||
{* ../../docs_src/events/tutorial001.py hl[8] *} |
|||
|
|||
В этом случае функция-обработчик события `startup` инициализирует "базу данных" элементов (просто `dict`) с некоторыми значениями. |
|||
|
|||
Вы можете добавить более одной функции-обработчика события. |
|||
|
|||
И ваше приложение не начнет принимать запросы до тех пор, пока все обработчики событий `startup` не будут выполнены. |
|||
|
|||
### Событие `shutdown` |
|||
|
|||
Чтобы добавить функцию, которую следует запустить при остановке приложения, объявите ее с событием `"shutdown"`: |
|||
|
|||
{* ../../docs_src/events/tutorial002.py hl[6] *} |
|||
|
|||
Здесь функция-обработчик события `shutdown` запишет строку текста `"Application shutdown"` в файл `log.txt`. |
|||
|
|||
/// info | Информация |
|||
|
|||
В функции `open()`, `mode="a"` означает "добавить", так что строка будет добавлена после того, что уже есть в этом файле, без перезаписи предыдущего содержимого. |
|||
|
|||
/// |
|||
|
|||
/// tip | Совет |
|||
|
|||
Обратите внимание, что в данном случае мы используем стандартную функцию Python `open()`, которая взаимодействует с файлом. |
|||
|
|||
Таким образом, это включает в себя ввод/вывод (I/O), который требует "ожидания" для записи данных на диск. |
|||
|
|||
Но `open()` не использует `async` и `await`. |
|||
|
|||
Поэтому мы объявляем функцию-обработчик события как стандартный `def` вместо `async def`. |
|||
|
|||
/// |
|||
|
|||
### `startup` и `shutdown` вместе |
|||
|
|||
Существует большая вероятность, что логика ваших *запуска* и *выключения* связана; возможно, вы хотите что-то запустить, а затем завершить, получить ресурс, а затем освободить его и т. д. |
|||
|
|||
Делать это в раздельных функциях, которые не используют совместно логику или переменные, сложнее, так как придется сохранять значения в глобальных переменных или использовать подобные уловки. |
|||
|
|||
Из-за этого теперь рекомендуется вместо этого использовать `lifespan`, как объяснено выше. |
|||
|
|||
## Технические детали |
|||
|
|||
Просто техническая деталь для любознательных гиков. 🤓 |
|||
|
|||
В основе, в технической спецификации ASGI, это часть <a href="https://asgi.readthedocs.io/en/latest/specs/lifespan.html" class="external-link" target="_blank">Протокола Lifespan</a>, и он определяет события, называемые `startup` и `shutdown`. |
|||
|
|||
/// info | Информация |
|||
|
|||
Вы можете прочитать больше об обработчиках `lifespan` в Starlette в <a href="https://www.starlette.io/lifespan/" class="external-link" target="_blank">документации "Lifespan" Starlette</a>. |
|||
|
|||
Включая информацию о том, как обрабатывать состояние lifespan, которое может быть использовано в других частях вашего кода. |
|||
|
|||
/// |
|||
|
|||
## Подприложения |
|||
|
|||
🚨 Помните, что эти события жизненного цикла (запуска и завершения) будут выполнены только для основного приложения, а не для [подприложений - монтировок](sub-applications.md){.internal-link target=_blank}. |
|||
@ -0,0 +1,261 @@ |
|||
# Генерация клиентов |
|||
|
|||
Так как **FastAPI** основан на спецификации OpenAPI, вы автоматически получаете совместимость со многими инструментами, включая автоматическую документацию API (предоставляемую Swagger UI). |
|||
|
|||
Один конкретный плюс, который не всегда очевиден, заключается в том, что вы можете **сгенерировать клиентов** (иногда их называют <abbr title="Software Development Kits">**SDKs**</abbr> ) для вашего API для многих разных **языков программирования**. |
|||
|
|||
## Генераторы клиентов OpenAPI |
|||
|
|||
Существует множество инструментов для генерации клиентов из **OpenAPI**. |
|||
|
|||
Один из популярных инструментов — это <a href="https://openapi-generator.tech/" class="external-link" target="_blank">OpenAPI Generator</a>. |
|||
|
|||
Если вы создаете **фронтенд**, очень интересной альтернативой является <a href="https://github.com/hey-api/openapi-ts" class="external-link" target="_blank">openapi-ts</a>. |
|||
|
|||
## Генераторы клиентов и SDK - спонсоры |
|||
|
|||
Существуют также некоторые **поддерживаемые компаниями** генераторы клиентов и SDK, основанные на OpenAPI (FastAPI), в некоторых случаях они могут предложить вам **дополнительные функции** поверх высококачественных сгенерированных SDK/клиентов. |
|||
|
|||
Некоторые из них также ✨ [**спонсируют FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, что обеспечивает продолжительное и здоровое **развитие** FastAPI и его **экосистемы**. |
|||
|
|||
Это также демонстрирует их истинную приверженность FastAPI и его **сообществу** (вам), ведь они не только хотят предоставить вам **качественное обслуживание**, но и стремятся обеспечить вам **качественный и здоровый фреймворк**, FastAPI. 🙇 |
|||
|
|||
Например, вам может быть интересно попробовать: |
|||
|
|||
* <a href="https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship" class="external-link" target="_blank">Speakeasy</a> |
|||
* <a href="https://www.stainlessapi.com/?utm_source=fastapi&utm_medium=referral" class="external-link" target="_blank">Stainless</a> |
|||
* <a href="https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi" class="external-link" target="_blank">liblab</a> |
|||
|
|||
Также существует несколько других компаний, предлагающих аналогичные услуги, которые вы можете найти в интернете. 🤓 |
|||
|
|||
## Генерация TypeScript-клиента для фронтенда |
|||
|
|||
Давайте начнем с простой FastAPI-программы: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *} |
|||
|
|||
Обратите внимание, что *операции пути* определяют модели, которые они используют для полезной нагрузки запроса и ответа, используя модели `Item` и `ResponseMessage`. |
|||
|
|||
### Документация API |
|||
|
|||
Если вы перейдете к документации API, вы увидите, что в ней содержатся **схемы** для данных, которые должны быть отправлены в запросах и получены в ответах: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image01.png"> |
|||
|
|||
Вы видите эти схемы, потому что они были объявлены с моделями в приложении. |
|||
|
|||
Эта информация доступна в **схеме OpenAPI** приложения и затем отображается в документации API (с помощью Swagger UI). |
|||
|
|||
И эта же информация из моделей, включенных в OpenAPI, может быть использована для **генерации кода клиента**. |
|||
|
|||
### Генерация TypeScript-клиента |
|||
|
|||
Теперь, когда у нас есть приложение с моделями, мы можем сгенерировать код клиента для фронтенда. |
|||
|
|||
#### Установка `openapi-ts` |
|||
|
|||
Вы можете установить `openapi-ts` в код своего фронтенда с помощью: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ npm install @hey-api/openapi-ts --save-dev |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
#### Генерация кода клиента |
|||
|
|||
Чтобы сгенерировать код клиента, вы можете использовать командное приложение `openapi-ts`, которое теперь будет установлено. |
|||
|
|||
Поскольку оно установлено в локальном проекте, вы, вероятно, не сможете вызвать эту команду напрямую, но вы можете поместить её в свой файл `package.json`. |
|||
|
|||
Он может выглядеть следующим образом: |
|||
|
|||
```JSON hl_lines="7" |
|||
{ |
|||
"name": "frontend-app", |
|||
"version": "1.0.0", |
|||
"description": "", |
|||
"main": "index.js", |
|||
"scripts": { |
|||
"generate-client": "openapi-ts --input http://localhost:8000/openapi.json --output ./src/client --client axios" |
|||
}, |
|||
"author": "", |
|||
"license": "", |
|||
"devDependencies": { |
|||
"@hey-api/openapi-ts": "^0.27.38", |
|||
"typescript": "^4.6.2" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
После добавления этого скрипта NPM `generate-client` вы можете запустить его с помощью: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ npm run generate-client |
|||
|
|||
frontend-app@1.0.0 generate-client /home/user/code/frontend-app |
|||
> openapi-ts --input http://localhost:8000/openapi.json --output ./src/client --client axios |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Эта команда сгенерирует код в `./src/client` и будет использовать `axios` (фронтенд HTTP-библиотеку) для внутренних нужд. |
|||
|
|||
### Попробуйте код клиента |
|||
|
|||
Теперь вы можете импортировать и использовать код клиента, он может выглядеть следующим образом, обратите внимание, что вы получаете автозавершение для методов: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image02.png"> |
|||
|
|||
Вы также получите автозавершение для отправляемой полезной нагрузки: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image03.png"> |
|||
|
|||
/// tip | Совет |
|||
|
|||
Обратите внимание на автозавершение для `name` и `price`, которые были определены в приложении FastAPI, в модели `Item`. |
|||
|
|||
/// |
|||
|
|||
Вы получите ошибки на лету для данных, которые вы отправляете: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image04.png"> |
|||
|
|||
Объект-ответ также будет иметь автозавершение: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image05.png"> |
|||
|
|||
## FastAPI-приложение с тегами |
|||
|
|||
Во многих случаях ваше FastAPI-приложение будет больше, и вы, скорее всего, будете использовать теги для разделения разных групп *операций пути*. |
|||
|
|||
Например, у вас может быть раздел для **товаров** и другой раздел для **пользователей**, и они могут быть разделены с помощью тегов: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *} |
|||
|
|||
### Генерация TypeScript-клиента с тегами |
|||
|
|||
Если вы генерируете клиента для FastAPI-приложения с использованем тегов, то обычно клиентский код также будет разделен по тегам. |
|||
|
|||
Таким образом, вы сможете правильно упорядочить и сгруппировать клиентский код: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image06.png"> |
|||
|
|||
В данном случае у вас есть: |
|||
|
|||
* `ItemsService` |
|||
* `UsersService` |
|||
|
|||
### Имена методов клиента |
|||
|
|||
Сейчас сгенерированные имена методов, такие как `createItemItemsPost`, не выглядят очень чистыми: |
|||
|
|||
```TypeScript |
|||
ItemsService.createItemItemsPost({name: "Plumbus", price: 5}) |
|||
``` |
|||
|
|||
...это потому, что генератор клиента использует внутренний **идентификатор операции** OpenAPI для каждой *операции пути*. |
|||
|
|||
OpenAPI требует, чтобы каждый идентификатор операции был уникальным среди всех *операций пути*, поэтому FastAPI использует **название функции**, **путь** и **метод/операцию HTTP** для генерации этого идентификатора операции, поскольку таким образом он может обеспечить уникальность идентификаторов операций. |
|||
|
|||
Но я покажу вам, как улучшить это. 🤓 |
|||
|
|||
## Пользовательские идентификаторы операций и лучшие имена методов |
|||
|
|||
Вы можете **изменить** способ **генерации** этих идентификаторов операций, чтобы упростить их и получить **более простые названия методов** в клиентах. |
|||
|
|||
В этом случае вы должны обеспечить уникальность каждого идентификатора операции другим способом. |
|||
|
|||
Например, вы можете убедиться, что каждая *операция пути* имеет тег, а затем генерировать идентификатор операции на основе **тега** и **названия операции пути** (названия функции). |
|||
|
|||
### Пользовательская функция генерации уникального идентификатора |
|||
|
|||
FastAPI использует **уникальный ID** для каждой *операции пути*, он используется для **идентификатора операции**, а также для имен любых необходимых пользовательских моделей для запросов или ответов. |
|||
|
|||
Вы можете настроить эту функцию. Она принимает `APIRoute` и возвращает строку. |
|||
|
|||
Например, здесь используется первый тег (обычно у вас будет только один тег) и название *операции пути* (название функции). |
|||
|
|||
Вы можете передать эту пользовательскую функцию **FastAPI** в параметре `generate_unique_id_function`: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *} |
|||
|
|||
### Генерация TypeScript-клиента с пользовательскими идентификаторами операций |
|||
|
|||
Теперь, если вы снова сгенерируете клиент, вы увидите, что у него улучшенные названия методов: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image07.png"> |
|||
|
|||
Как видите, названия методов теперь содержат тег, а затем имя функции, теперь они не включают информацию из URL-пути и HTTP-операции. |
|||
|
|||
### Предобработка спецификации OpenAPI для генератора клиентов |
|||
|
|||
Сгенерированный код все равно содержит некоторую **дублирующую информацию**. |
|||
|
|||
Мы уже знаем, что этот метод связан с **товарами (items)**, потому что это слово появилось в `ItemsService` (взято из тега), но у нас все равно есть имя тега в имени метода. 😕 |
|||
|
|||
Вероятно, мы все равно захотим сохранить это для OpenAPI в целом, так как это обеспечит **уникальность** идентификаторов операций. |
|||
|
|||
Но для сгенерированного клиента мы можем **изменить** идентификаторы операций OpenAPI прямо перед генерацией клиентов, только чтобы сделать эти названия методов более приятными и **чистыми**. |
|||
|
|||
Мы можем загрузить OpenAPI JSON в файл `openapi.json`, а затем **удалить** этот префикс тега с помощью такого скрипта: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial004.py *} |
|||
|
|||
//// tab | Node.js |
|||
|
|||
```Javascript |
|||
{!> ../../docs_src/generate_clients/tutorial004.js!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
Таким образом, идентификаторы операций будут переименованы из `items-get_items` в просто `get_items`, так генератор клиентов сможет генерировать более простые имена методов. |
|||
|
|||
### Генерация TypeScript-клиента с предобработанным OpenAPI |
|||
|
|||
Теперь, так как конечный результат находится в файле `openapi.json`, вы измените файл `package.json`, чтобы использовать этот локальный файл, например: |
|||
|
|||
```JSON hl_lines="7" |
|||
{ |
|||
"name": "frontend-app", |
|||
"version": "1.0.0", |
|||
"description": "", |
|||
"main": "index.js", |
|||
"scripts": { |
|||
"generate-client": "openapi-ts --input ./openapi.json --output ./src/client --client axios" |
|||
}, |
|||
"author": "", |
|||
"license": "", |
|||
"devDependencies": { |
|||
"@hey-api/openapi-ts": "^0.27.38", |
|||
"typescript": "^4.6.2" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
После генерации нового клиента у вас теперь будут **чистые названия методов**, с всеми **подсказками автозавершения**, **ошибками на лету** и т.д.: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image08.png"> |
|||
|
|||
## Преимущества |
|||
|
|||
При использовании автоматически сгенерированных клиентов вы получите **автозавершение** для: |
|||
|
|||
* Методов. |
|||
* Полезной нагрузки запроса в теле, параметрах запроса и т.д. |
|||
* Полезной нагрузки ответа. |
|||
|
|||
Вы также получите **ошибки на лету** для всего. |
|||
|
|||
И всякий раз, когда вы обновляете код на серверной стороне и **регенерируете** фронтенд, он будет содержать любые новые *операции пути* как методы, старые будут удалены, а любые другие изменения будут отражены в сгенерированном коде. 🤓 |
|||
|
|||
Это также означает, что если что-то изменится, это будет **отражено** в клиентском коде автоматически. И если вы **соберёте** клиент, у него возникнет ошибка, если у вас возникнет **несоответствие** в используемых данных. |
|||
|
|||
Таким образом, вы **обнаружите множество ошибок** на раннем этапе цикла разработки, вместо того чтобы ждать, пока ошибки проявятся у ваших конечных пользователей в продакшне, и потом пытаться выяснить, в чем проблема. ✨ |
|||
@ -0,0 +1,96 @@ |
|||
# Продвинутое использование Middleware |
|||
|
|||
В основном руководстве вы узнали, как добавить [пользовательский Middleware](../tutorial/middleware.md){.internal-link target=_blank} в ваше приложение. |
|||
|
|||
А также вы узнали, как обрабатывать [CORS с использованием `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}. |
|||
|
|||
В этом разделе мы увидим, как использовать другие middleware. |
|||
|
|||
## Добавление ASGI middleware |
|||
|
|||
Так как **FastAPI** основан на Starlette и реализует спецификацию <abbr title="Asynchronous Server Gateway Interface">ASGI</abbr>, вы можете использовать любой ASGI middleware. |
|||
|
|||
Для работы middleware не обязательно должны быть созданы специально для FastAPI или Starlette, достаточно того, чтобы они следовали спецификации ASGI. |
|||
|
|||
В общем случае, ASGI middleware представляют собой классы, которые ожидают получение ASGI приложения в качестве первого аргумента. |
|||
|
|||
Таким образом, в документации для сторонних ASGI middleware, скорее всего, будет указано сделать следующее: |
|||
|
|||
```Python |
|||
from unicorn import UnicornMiddleware |
|||
|
|||
app = SomeASGIApp() |
|||
|
|||
new_app = UnicornMiddleware(app, some_config="rainbow") |
|||
``` |
|||
|
|||
Но FastAPI (на самом деле Starlette) предоставляет более простой способ сделать это, обеспечивая правильную обработку ошибок сервера и работу пользовательских обработчиков ошибок. |
|||
|
|||
Для этого используйте `app.add_middleware()` (как в примере для CORS). |
|||
|
|||
```Python |
|||
from fastapi import FastAPI |
|||
from unicorn import UnicornMiddleware |
|||
|
|||
app = FastAPI() |
|||
|
|||
app.add_middleware(UnicornMiddleware, some_config="rainbow") |
|||
``` |
|||
|
|||
`app.add_middleware()` принимает класс middleware в качестве первого аргумента и любые дополнительные аргументы, которые должны быть переданы в middleware. |
|||
|
|||
## Интегрированные middleware |
|||
|
|||
**FastAPI** включает несколько middleware для общих случаев использования, далее мы рассмотрим, как их использовать. |
|||
|
|||
/// note | Технические детали |
|||
|
|||
В следующих примерах вы также можете использовать `from starlette.middleware.something import SomethingMiddleware`. |
|||
|
|||
**FastAPI** предоставляет несколько middleware в `fastapi.middleware` исключительно для удобства разработчика. Но большинство доступных middleware поступает непосредственно из Starlette. |
|||
|
|||
/// |
|||
|
|||
## `HTTPSRedirectMiddleware` |
|||
|
|||
Обеспечивает, чтобы все входящие запросы были перенаправлены на `https` или `wss`. |
|||
|
|||
Любой входящий запрос на `http` или `ws` будет перенаправлен на защищенную схему. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *} |
|||
|
|||
## `TrustedHostMiddleware` |
|||
|
|||
Обеспечивает наличие корректно заданного HTTP-заголовка `Host` во всех входящих запросах для защиты от атак на основе HTTP-заголовка Host. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *} |
|||
|
|||
Поддерживаются следующие аргументы: |
|||
|
|||
* `allowed_hosts` - список доменных имен, которые разрешены в качестве имен хостов. Разрешены шаблоны доменов, такие как `*.example.com`, для соответствия поддоменам. Для разрешения всех имен хостов можно использовать `allowed_hosts=["*"]` или вовсе не добавлять middleware. |
|||
|
|||
Если входящий запрос не валидируется, отправляется ответ с кодом `400`. |
|||
|
|||
## `GZipMiddleware` |
|||
|
|||
Обрабатывает GZip-ответы для любого запроса, который включает `"gzip"` в HTTP-заголовке `Accept-Encoding`. |
|||
|
|||
Middleware будет обрабатывать как стандартные, так и потоковые HTTP-ответы. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *} |
|||
|
|||
Поддерживаются следующие аргументы: |
|||
|
|||
* `minimum_size` - не выполнять GZip сжатие для HTTP-ответов, которые меньше этого минимального размера в байтах. По умолчанию `500`. |
|||
* `compresslevel` - используется во время GZip сжатия. Это число в диапазоне от 1 до 9. По умолчанию `9`. Меньшее значение приводит к более быстрому сжатию, но большему размеру файлов, в то время как большее значение приводит к более медленному сжатию, но меньшему размеру файлов. |
|||
|
|||
## Другие middleware |
|||
|
|||
Существует много других ASGI middleware. |
|||
|
|||
Например: |
|||
|
|||
* <a href="https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py" class="external-link" target="_blank">`ProxyHeadersMiddleware` от Uvicorn</a> |
|||
* <a href="https://github.com/florimondmanca/msgpack-asgi" class="external-link" target="_blank">MessagePack</a> |
|||
|
|||
Чтобы увидеть другие доступные middleware, ознакомьтесь с <a href="https://www.starlette.io/middleware/" class="external-link" target="_blank">документацией Starlette по Middleware</a> и <a href="https://github.com/florimondmanca/awesome-asgi" class="external-link" target="_blank">списком ASGI Awesome List</a>. |
|||
@ -0,0 +1,186 @@ |
|||
# OpenAPI Callbacks |
|||
|
|||
Вы можете создать API с *операцией пути*, которая может инициировать запрос к *внешнему API*, созданному кем-то другим (вероятно, тем же разработчиком, который будет *использовать* ваше API). |
|||
|
|||
Процесс, который происходит, когда ваше API-приложение вызывает *внешний API*, называется "callback". Потому что ПО, написанное внешним разработчиком, отправляет запрос вашему API, а затем ваше API *отвечает*, отправляя запрос к *внешнему API* (который, возможно, был создан тем же разработчиком). |
|||
|
|||
В этом случае, вы могли бы захотеть задокументировать, как этот внешний API *должен* выглядеть. Какие *операции пути* он должен содержать, какое тело ожидать, какой ответ должен возвращать и т.д. |
|||
|
|||
## Приложение с callback'ами |
|||
|
|||
Рассмотрим это на примере. |
|||
|
|||
Представьте, что вы разрабатываете приложение, позволяющее создавать счета. |
|||
|
|||
Эти счета будут иметь `id`, `title` (опционально), `customer` и `total`. |
|||
|
|||
Пользователь вашего API (внешний разработчик) создаст счет в вашем API с помощью POST-запроса. |
|||
|
|||
Затем ваше API будет (давайте представим): |
|||
|
|||
* Отправлять счет какому-то клиенту внешнего разработчика. |
|||
* Собирать деньги. |
|||
* Отправлять уведомление обратно пользователю API (внешнему разработчику). |
|||
* Это будет сделано с помощью отправки POST-запроса (от *вашего API*) в некоторый *внешний API*, предоставленный этим внешним разработчиком (это и есть "callback"). |
|||
|
|||
## Обычное приложение **FastAPI** |
|||
|
|||
Сначала посмотрим, как обычное приложение API выглядело бы до добавления callback'а. |
|||
|
|||
Оно будет иметь *операцию пути*, которая будет принимать `Invoice` в теле запроса и параметр запроса `callback_url`, который будет содержать URL для callback'а. |
|||
|
|||
Эта часть довольно обычная, и, вероятно, большая часть кода уже знакома вам: |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *} |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
Параметр запроса `callback_url` использует тип Url из Pydantic <a href="https://docs.pydantic.dev/latest/api/networks/" class="external-link" target="_blank">Url</a>. |
|||
|
|||
/// |
|||
|
|||
Единственное новое здесь — это `callbacks=invoices_callback_router.routes` как аргумент к *декоратору операции пути*. Дальше мы увидим, что это значит. |
|||
|
|||
## Документирование callback'а |
|||
|
|||
Фактический код callback'а будет сильно зависеть от вашего API-приложения. |
|||
|
|||
И, вероятно, значительно изменится от одного приложения к другому. |
|||
|
|||
Это может быть всего одна или две строчки кода, такие как: |
|||
|
|||
```Python |
|||
callback_url = "https://example.com/api/v1/invoices/events/" |
|||
httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) |
|||
``` |
|||
|
|||
Но, возможно, наиболее важная часть callback'а — это убедиться, что пользователь вашего API (внешний разработчик) корректно реализует *внешний API*, согласно данным, которые *ваше API* собирается отправить в теле запроса callback'а и т.д. |
|||
|
|||
Итак, следующее, что мы сделаем, это добавим код для документации, как этот *внешний API* должен выглядеть для получения callback'а от *вашего API*. |
|||
|
|||
Эта документация отобразится в интерфейсе Swagger по адресу `/docs` в вашем API и позволит внешним разработчикам узнать, как создать *внешний API*. |
|||
|
|||
Этот пример не реализует сам callback (это может быть всего одна строка кода), только часть документации. |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
Фактический callback — это просто HTTP-запрос. |
|||
|
|||
При реализации callback'а самостоятельно, вы можете использовать что-то вроде <a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPX</a> или <a href="https://requests.readthedocs.io/" class="external-link" target="_blank">Requests</a>. |
|||
|
|||
/// |
|||
|
|||
## Написание кода документации для callback'а |
|||
|
|||
Этот код не будет выполнен в вашем приложении, нам нужно его только чтобы *документировать*, как *внешний API* должен выглядеть. |
|||
|
|||
Но вы уже знаете, как легко создавать автоматическую документацию для API с **FastAPI**. |
|||
|
|||
Поэтому мы используем эти же знания, чтобы задокументировать, как *внешний API* должен выглядеть... создавая *операцию(ии) пути*, которые внешний API должен реализовать (те, которые ваше API вызовет). |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
Когда пишете код для документации callback'а, может быть полезно представить, что вы — этот *внешний разработчик*. И что вы в данный момент реализуете *внешний API*, а не *ваше API*. |
|||
|
|||
Временное принятие этой точки зрения (внешнего разработчика) поможет вам скорее определить, куда помещать параметры, Pydantic-модель для тела запроса, для ответа и т.д. для этого *внешнего API*. |
|||
|
|||
/// |
|||
|
|||
### Создание callback `APIRouter` |
|||
|
|||
Сначала создайте новый `APIRouter`, который будет содержать один или несколько callback'ов. |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *} |
|||
|
|||
### Создание callback *операции пути* |
|||
|
|||
Чтобы создать callback *операцию пути*, используйте тот же `APIRouter`, который вы создали выше. |
|||
|
|||
Она должна выглядеть как обычная операция пути FastAPI: |
|||
|
|||
* Она, вероятно, должна иметь объявление тела запроса, которое она должна принять, например `body: InvoiceEvent`. |
|||
* И она может также иметь объявление ответа, который она должна вернуть, например `response_model=InvoiceEventReceived`. |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *} |
|||
|
|||
Есть 2 основных отличия от обычной *операции пути*: |
|||
|
|||
* Реальный код не нужен, так как ваше приложение никогда не вызовет этот код. Он используется только для документирования *внешнего API*. Поэтому функция может просто содержать `pass`. |
|||
* В *пути* может содержаться <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">выражение OpenAPI 3</a> (подробнее ниже), где можно использовать переменные с параметрами и частями оригинального запроса, отправленного к *вашему API*. |
|||
|
|||
### Выражение пути callback'а |
|||
|
|||
Путь callback'а может содержать <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">выражение OpenAPI 3</a>, которое может включать части оригинального запроса, отправленного к *вашему API*. |
|||
|
|||
В этом случае это `str`: |
|||
|
|||
```Python |
|||
"{$callback_url}/invoices/{$request.body.id}" |
|||
``` |
|||
|
|||
Таким образом, если пользователь вашего API (внешний разработчик) отправляет запрос к *вашему API* по адресу: |
|||
|
|||
``` |
|||
https://yourapi.com/invoices/?callback_url=https://www.external.org/events |
|||
``` |
|||
|
|||
с JSON-телом: |
|||
|
|||
```JSON |
|||
{ |
|||
"id": "2expen51ve", |
|||
"customer": "Mr. Richie Rich", |
|||
"total": "9999" |
|||
} |
|||
``` |
|||
|
|||
тогда *ваше API* обработает счет, и чуть позже отправит callback-запрос на `callback_url` (во *внешний API*): |
|||
|
|||
``` |
|||
https://www.external.org/events/invoices/2expen51ve |
|||
``` |
|||
|
|||
с JSON-телом, содержащим что-то вроде: |
|||
|
|||
```JSON |
|||
{ |
|||
"description": "Payment celebration", |
|||
"paid": true |
|||
} |
|||
``` |
|||
|
|||
и ожидает ответа от этого *внешнего API* с JSON-телом вроде: |
|||
|
|||
```JSON |
|||
{ |
|||
"ok": true |
|||
} |
|||
``` |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
Обратите внимание, как callback URL включает URL, полученный как параметр запроса в `callback_url` (`https://www.external.org/events`), и также `id` счета из тела JSON (`2expen51ve`). |
|||
|
|||
/// |
|||
|
|||
### Добавление router для callback'ов |
|||
|
|||
На данном этапе у вас есть *операция(ии) пути для callback'а*, необходимые (те, которые *внешний разработчик* должен реализовать во *внешнем API*) в callback router, который вы создали выше. |
|||
|
|||
Теперь используйте параметр `callbacks` в *декораторе операции пути вашего API*, чтобы передать атрибут `.routes` (который на самом деле является просто `list`'ом маршрутов/*операций пути*) из этого callback router: |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *} |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
Обратите внимание, что вы не передаете сам router (`invoices_callback_router`) в `callback=`, а передаете атрибут `.routes`, как в `invoices_callback_router.routes`. |
|||
|
|||
/// |
|||
|
|||
### Проверка документации |
|||
|
|||
Теперь вы можете запустить ваше приложение и перейти на <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
Вы увидите вашу документацию, включая раздел "Callbacks" для вашей *операции пути*, который показывает, как должен выглядеть *внешний API*: |
|||
|
|||
<img src="/img/tutorial/openapi-callbacks/image01.png"> |
|||
@ -0,0 +1,55 @@ |
|||
# OpenAPI Webhooks |
|||
|
|||
Существуют случаи, когда вы хотите сообщить пользователям вашего API, что ваше приложение может отправлять запросы их приложениям с данными, обычно для уведомления о каком-то событии. |
|||
|
|||
Это означает, что вместо обычного процесса, когда ваши пользователи отправляют запросы вашему API, это ваш API (или ваше приложение) может отправлять запросы их системе (их API, их приложению). |
|||
|
|||
Это обычно называется **webhook**. |
|||
|
|||
## Шаги вебхуков |
|||
|
|||
Процесс обычно состоит в том, что **вы определяете** в вашем коде сообщение, которое вы собираетесь отправить, **тело запроса**. |
|||
|
|||
Вы также каким-либо образом определяете, в какие **моменты** ваше приложение будет отправлять эти запросы или события. |
|||
|
|||
И **ваши пользователи** каким-либо образом (например, в веб-панели управления) определяют **URL**, куда ваше приложение должно отправлять эти запросы. |
|||
|
|||
Вся **логика** регистрации URL-адресов для вебхуков и кода для фактической отправки этих запросов зависит от вас. Вы пишете это в **собственном коде** так, как хотите. |
|||
|
|||
## Документирование вебхуков с помощью **FastAPI** и OpenAPI |
|||
|
|||
С помощью **FastAPI** и OpenAPI вы можете определить названия этих вебхуков, типы HTTP операций, которые ваше приложение может отправлять (например, `POST`, `PUT` и т.д.), и **тела запросов**, которые ваше приложение будет отправлять. |
|||
|
|||
Это может значительно упростить вашим пользователям **внедрение их API** для получения ваших **вебхуков**, они даже могут автоматически сгенерировать часть своего API кода. |
|||
|
|||
/// info | Информация |
|||
|
|||
Вебхуки доступны в OpenAPI 3.1.0 и выше, поддерживаемые FastAPI `0.99.0` и выше. |
|||
|
|||
/// |
|||
|
|||
## Приложение с вебхуками |
|||
|
|||
Когда вы создаете приложение **FastAPI**, есть атрибут `webhooks`, который вы можете использовать для определения *вебхуков* так же, как вы бы определяли *операции пути*, например с помощью `@app.webhooks.post()`. |
|||
|
|||
{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *} |
|||
|
|||
Вебхуки, которые вы определяете, попадут в **схему OpenAPI** и в **автоматическую документацию UI**. |
|||
|
|||
/// info | Информация |
|||
|
|||
Объект `app.webhooks` на самом деле является `APIRouter`, того же типа, который вы бы использовали при структурировании своего приложения с множеством файлов. |
|||
|
|||
/// |
|||
|
|||
Обратите внимание, что с вебхуками вы на самом деле не объявляете *путь* (например, `/items/`), текст, который вы передаете, является просто **идентификатором** вебхука (название события), например в `@app.webhooks.post("new-subscription")`, имя вебхука — `new-subscription`. |
|||
|
|||
Это потому, что ожидается, что **ваши пользователи** определят фактический **путь URL**, куда они хотят получать запрос webhook, каким-то другим образом (например, в веб-панели управления). |
|||
|
|||
### Проверьте документацию |
|||
|
|||
Теперь вы можете запустить ваше приложение и перейти по адресу <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
Вы увидите, что ваша документация содержит обычные *операции пути* и теперь также некоторые **вебхуки**: |
|||
|
|||
<img src="/img/tutorial/openapi-webhooks/image01.png"> |
|||
@ -0,0 +1,204 @@ |
|||
# Продвинутая конфигурация операций пути |
|||
|
|||
## OpenAPI operationId |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
Если вы не "эксперт" в OpenAPI, то, скорее всего, вам это не понадобится. |
|||
|
|||
/// |
|||
|
|||
Вы можете задать `operationId` для OpenAPI, который будет использоваться в вашей *операции пути* с помощью параметра `operation_id`. |
|||
|
|||
Следует удостовериться, что он уникален для каждой операции. |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *} |
|||
|
|||
### Использование имени функции *операции пути* в качестве operationId |
|||
|
|||
Если вы хотите использовать имена ваших функций API в качестве `operationId`, вы можете перебрать их все и переопределить `operation_id` каждой *операции пути*, используя `APIRoute.name`. |
|||
|
|||
Необходимо сделать это после добавления всех ваших *операций пути*. |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2, 12:21, 24] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Если вы вручную вызываете `app.openapi()`, обновите `operationId` до этого. |
|||
|
|||
/// |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
Если вы это делаете, необходимо удостовериться, что каждая из ваших *функций операций пути* имеет уникальное имя. |
|||
|
|||
Даже если они находятся в разных модулях (файлах Python). |
|||
|
|||
/// |
|||
|
|||
## Исключение из OpenAPI |
|||
|
|||
Чтобы исключить *операцию пути* из генерируемой схемы OpenAPI (и таким образом, из систем автоматической документации), используйте параметр `include_in_schema` и установите его значение как `False`: |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *} |
|||
|
|||
## Расширенное описание из строки документации |
|||
|
|||
Вы можете ограничить количество строк, используемых из строки документации функции *операции пути* для OpenAPI. |
|||
|
|||
Добавление `\f` (экранированный символ "перевод страницы") приведет к тому, что **FastAPI** обрежет вывод, используемый для OpenAPI, на этом месте. |
|||
|
|||
Этот символ не покажется в документации, но другие инструменты (такие как Sphinx) смогут использовать остальную часть. |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *} |
|||
|
|||
## Дополнительные ответы |
|||
|
|||
Вы, вероятно, уже знаете, как объявить `response_model` и `status_code` для *операции пути*. |
|||
|
|||
Это определяет метаданные об основном ответе *операции пути*. |
|||
|
|||
Вы также можете объявить дополнительные ответы с их моделями, статус-кодами и т.д. |
|||
|
|||
В документации есть целая глава об этом, которую вы можете прочитать в разделе [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. |
|||
|
|||
## Дополнения OpenAPI |
|||
|
|||
Когда вы объявляете *операцию пути* в вашем приложении, **FastAPI** автоматически генерирует соответствующие метаданные об этой *операции пути*, чтобы включить их в схему OpenAPI. |
|||
|
|||
/// note | Технические детали |
|||
|
|||
В спецификации OpenAPI это называется <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object" class="external-link" target="_blank">Объект операции</a>. |
|||
|
|||
/// |
|||
|
|||
Это содержит всю информацию о *операции пути* и используется для генерации автоматической документации. |
|||
|
|||
Это включает в себя `tags`, `parameters`, `requestBody`, `responses` и т.д. |
|||
|
|||
Эта схема OpenAPI для данной *операции пути* обычно генерируется автоматически **FastAPI**, но ее можно и расширить. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Это точка низкоуровневого расширения. |
|||
|
|||
Если вам нужно только объявить дополнительные ответы, более удобный способ сделать это — через [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. |
|||
|
|||
/// |
|||
|
|||
Вы можете расширить схему OpenAPI для *операции пути* с помощью параметра `openapi_extra`. |
|||
|
|||
### Расширения OpenAPI |
|||
|
|||
Этот `openapi_extra` может быть полезен, например, чтобы объявить [Расширения OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions): |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *} |
|||
|
|||
Если вы откроете автоматическую документацию API, ваше расширение появится внизу конкретной *операции пути*. |
|||
|
|||
<img src="/img/tutorial/path-operation-advanced-configuration/image01.png"> |
|||
|
|||
И если вы увидите результат OpenAPI (по адресу `/openapi.json` в вашем API), вы увидите ваше расширение также как часть конкретной *операции пути*: |
|||
|
|||
```JSON hl_lines="22" |
|||
{ |
|||
"openapi": "3.1.0", |
|||
"info": { |
|||
"title": "FastAPI", |
|||
"version": "0.1.0" |
|||
}, |
|||
"paths": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {} |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"x-aperture-labs-portal": "blue" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Пользовательская схема OpenAPI *операции пути* |
|||
|
|||
Словарь в `openapi_extra` будет глубоко объединен с автоматически сгенерированной схемой OpenAPI для *операции пути*. |
|||
|
|||
Так вы можете добавить дополнительные данные в автоматически сгенерированную схему. |
|||
|
|||
Например, вы можете решить сами считывать и валидировать запрос без использования автоматических функций FastAPI с Pydantic, но вы все равно можете захотеть определить запрос в схеме OpenAPI. |
|||
|
|||
Вы можете сделать это с помощью `openapi_extra`: |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[19:36, 39:40] *} |
|||
|
|||
В этом примере мы не объявили никакой Pydantic-модели. На самом деле тело запроса даже не <abbr title="преобразовано из какого-либо простого формата, как байты, в Python-объекты">проанализировано</abbr> как JSON, оно считывается напрямую как `bytes`, и функция `magic_data_reader()` будет отвечать за его парсинг. |
|||
|
|||
Тем не менее, мы можем объявить ожидаемую схему для тела запроса. |
|||
|
|||
### Пользовательский тип содержимого OpenAPI |
|||
|
|||
Используя этот же трюк, вы можете использовать Pydantic-модель для определения JSON-схемы, которая затем будет включена в пользовательский раздел схемы OpenAPI для *операции пути*. |
|||
|
|||
И вы можете сделать это даже если тип данных в запросе не JSON. |
|||
|
|||
Например, в этом приложении мы не используем интегрированные функции FastAPI для извлечения JSON-схемы из Pydantic-моделей и автоматической валидации для JSON. В самом деле, мы объявляем тип содержимого запроса как YAML, а не JSON: |
|||
|
|||
//// tab | Pydantic v2 |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22, 24] *} |
|||
|
|||
//// |
|||
|
|||
//// tab | Pydantic v1 |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[17:22, 24] *} |
|||
|
|||
//// |
|||
|
|||
/// info | Информация |
|||
|
|||
В версии Pydantic 1 метод для получения JSON-схемы для модели назывался `Item.schema()`, в версии Pydantic 2 метод называется `Item.model_json_schema()`. |
|||
|
|||
/// |
|||
|
|||
Тем не менее, хотя мы не используем стандартную интегрированную функциональность, мы все же используем модель Pydantic, чтобы вручную сгенерировать JSON-схему для данных, которые мы хотим получить в YAML. |
|||
|
|||
Затем мы используем запрос напрямую и извлекаем тело как `bytes`. Это означает, что FastAPI даже не будет пытаться парсить содержимое запроса как JSON. |
|||
|
|||
И затем в нашем коде мы парсим это YAML-содержимое напрямую, и затем снова используем ту же модель Pydantic для валидации содержимого YAML: |
|||
|
|||
//// tab | Pydantic v2 |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *} |
|||
|
|||
//// |
|||
|
|||
//// tab | Pydantic v1 |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[26:33] *} |
|||
|
|||
//// |
|||
|
|||
/// info | Информация |
|||
|
|||
В версии Pydantic 1 метод для парсинга и валидации объекта назывался `Item.parse_obj()`, в версии Pydantic 2 метод называется `Item.model_validate()`. |
|||
|
|||
/// |
|||
|
|||
/// tip | Совет |
|||
|
|||
Здесь мы повторно используем ту же модель Pydantic. |
|||
|
|||
Но таким же образом можно было бы валидировать ее каким-то другим способом. |
|||
|
|||
/// |
|||
@ -0,0 +1,41 @@ |
|||
# HTTP-заголовки ответа |
|||
|
|||
## Использование параметра `Response` |
|||
|
|||
Вы можете объявить параметр типа `Response` в вашей *функции-обработчике пути* (так же, как вы делаете для cookie). |
|||
|
|||
Затем вы можете установить HTTP-заголовки в этом *временном* объекте ответа. |
|||
|
|||
{* ../../docs_src/response_headers/tutorial002.py hl[1, 7:8] *} |
|||
|
|||
После этого вы можете вернуть любой объект, который вам нужен, как обычно (например, `dict`, модель базы данных и т.д.). |
|||
|
|||
Если вы объявили `response_model`, он все равно будет использован для фильтрации и преобразования объекта, который вы вернули. |
|||
|
|||
**FastAPI** использует этот *временный* ответ для извлечения HTTP-заголовков (также cookie и статус-код ответа) и помещает их в окончательный ответ, который содержит значение, которое вы вернули и которое фильтруется любым `response_model`. |
|||
|
|||
Вы также можете объявить параметр `Response` в зависимостях и установить HTTP-заголовки (и cookie) в них. |
|||
|
|||
## Непосредственный возврат `Response` |
|||
|
|||
Вы также можете добавить HTTP-заголовки при непосредственном возврате объекта типа `Response`. |
|||
|
|||
Создайте ответ, как описано в разделе [Непосредственный возврат ответа](response-directly.md){.internal-link target=_blank}, и передайте HTTP-заголовки в качестве дополнительного параметра: |
|||
|
|||
{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *} |
|||
|
|||
/// note | Технические детали |
|||
|
|||
Вы также могли бы использовать `from starlette.responses import Response` или `from starlette.responses import JSONResponse`. |
|||
|
|||
**FastAPI** предоставляет те же `starlette.responses`, что и `fastapi.responses`, для удобства разработчика. Но большинство доступных ответов поступает непосредственно из Starlette. |
|||
|
|||
И так как `Response` может часто использоваться для установки HTTP-заголовков и cookie, **FastAPI** также предоставляет его в `fastapi.Response`. |
|||
|
|||
/// |
|||
|
|||
## Пользовательские заголовки |
|||
|
|||
Имейте в виду, что можно добавлять проприетарные пользовательские HTTP-заголовки <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">с использованием префикса 'X-'</a>. |
|||
|
|||
Но если у вас есть пользовательские заголовки, которые вы хотите, чтобы клиент в браузере мог видеть, вам нужно добавить их в ваши CORS-настройки (прочтите больше в разделе [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), используя параметр `expose_headers`, документированный в <a href="https://www.starlette.io/middleware/#corsmiddleware" class="external-link" target="_blank">документации Starlette по CORS</a>. |
|||
@ -0,0 +1,107 @@ |
|||
# HTTP Basic Auth |
|||
|
|||
Для самых простых случаев можно использовать HTTP Basic Auth. |
|||
|
|||
В HTTP Basic Auth приложение ожидает HTTP-заголовок, содержащий имя пользователя и пароль. |
|||
|
|||
Если он не получит их, то вернет ошибку HTTP 401 "Unauthorized" (неавторизовано). |
|||
|
|||
Также будет возвращен HTTP-заголовок `WWW-Authenticate` со значением `Basic` и опциональным параметром `realm`. |
|||
|
|||
Это говорит браузеру показать встроенную панель для ввода имени пользователя и пароля. |
|||
|
|||
Затем, когда вы вводите эти имя пользователя и пароль, браузер отправляет их в заголовке автоматически. |
|||
|
|||
## Простая HTTP Basic Auth |
|||
|
|||
* Импортируйте `HTTPBasic` и `HTTPBasicCredentials`. |
|||
* Создайте "`security` scheme" используя `HTTPBasic`. |
|||
* Используйте эту `security` зависимость в вашей *операции пути*. |
|||
* Она возвращает объект типа `HTTPBasicCredentials`: |
|||
* Содержит отправленные `username` и `password`. |
|||
|
|||
{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *} |
|||
|
|||
Когда вы попытаетесь открыть URL в первый раз (или нажмете кнопку "Execute" в документации) браузер спросит вас имя пользователя и пароль: |
|||
|
|||
<img src="/img/tutorial/security/image12.png"> |
|||
|
|||
## Проверка имени пользователя |
|||
|
|||
Вот более полный пример. |
|||
|
|||
Используйте зависимость, чтобы проверить, правильные ли имя пользователя и пароль. |
|||
|
|||
Для этого используйте стандартный модуль Python <a href="https://docs.python.org/3/library/secrets.html" class="external-link" target="_blank">`secrets`</a> для проверки имени пользователя и пароля. |
|||
|
|||
`secrets.compare_digest()` требует `bytes` или `str`, содержащий только ASCII-символы (те, что на английском), это значит, что он не будет работать с символами, такими как `á`, например в `Sebastián`. |
|||
|
|||
Чтобы с этим справиться, мы сначала конвертируем `username` и `password` в `bytes`, кодируя их в UTF-8. |
|||
|
|||
Затем мы можем использовать `secrets.compare_digest()` для гарантии, что `credentials.username` равен `"stanleyjobson"`, а `credentials.password` равен `"swordfish"`. |
|||
|
|||
{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *} |
|||
|
|||
Это будет аналогично: |
|||
|
|||
```Python |
|||
if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"): |
|||
# Return some error |
|||
... |
|||
``` |
|||
|
|||
Но, используя `secrets.compare_digest()`, это будет защищено от атак под названием "тайминговые атаки". |
|||
|
|||
### Тайминговые атаки |
|||
|
|||
Что такое "тайминговая атака"? |
|||
|
|||
Представим, что некоторая группа злоумышленников пытается угадать имя пользователя и пароль. |
|||
|
|||
Они отправляют запрос с именем пользователя `johndoe` и паролем `love123`. |
|||
|
|||
Тогда Python-код в вашем приложении будет эквивалентен чему-то вроде: |
|||
|
|||
```Python |
|||
if "johndoe" == "stanleyjobson" and "love123" == "swordfish": |
|||
... |
|||
``` |
|||
|
|||
Но в тот момент, когда Python сравнивает первую `j` в `johndoe` с первой `s` в `stanleyjobson`, он вернет `False`, так как уже знает, что эти две строки не одинаковы, считая, что "нет смысла тратить больше вычислительных ресурсов на сравнение остальных букв". И ваше приложение скажет "Неправильное имя пользователя или пароль". |
|||
|
|||
Но затем злоумышленники попробуют с именем пользователя `stanleyjobsox` и паролем `love123`. |
|||
|
|||
И ваш код приложения делает что-то вроде: |
|||
|
|||
```Python |
|||
if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish": |
|||
... |
|||
``` |
|||
|
|||
Python должен будет сравнить весь `stanleyjobso` в `stanleyjobsox` и `stanleyjobson`, чтобы понять, что строки не одинаковы. Так что это займет дополнительные микросекунды, чтобы ответить "Неправильное имя пользователя или пароль". |
|||
|
|||
#### Время ответа помогает злоумышленникам |
|||
|
|||
В этот момент, заметив, что серверу понадобилось немного больше времени, чтобы отправить ответ "Неправильное имя пользователя или пароль", злоумышленники узнают, что они что-то угадали, некоторые начальные буквы были правильными. |
|||
|
|||
И тогда они могут попробовать снова, зная, что это, вероятно, что-то более похожее на `stanleyjobsox`, чем на `johndoe`. |
|||
|
|||
#### "Профессиональная" атака |
|||
|
|||
Конечно, злоумышленники не будут делать все это вручную, они напишут программу, чтобы делать это, возможно, с тысячами или миллионами тестов в секунду. И они будут получать лишь одну правильную букву за раз. |
|||
|
|||
Но, делая так, за несколько минут или часов злоумышленники могли бы угадать правильное имя пользователя и пароль, с "помощью" нашего приложения, просто используя время, затраченное на ответ. |
|||
|
|||
#### Исправьте это с помощью `secrets.compare_digest()` |
|||
|
|||
Но в нашем коде мы фактически используем `secrets.compare_digest()`. |
|||
|
|||
Вкратце, это займет одинаковое время, чтобы сравнить `stanleyjobsox` с `stanleyjobson`, как и `johndoe` с `stanleyjobson`. И то же самое для пароля. |
|||
|
|||
Таким образом, используя `secrets.compare_digest()` в коде вашего приложения, оно будет защищено от этого целого спектра атак на безопасность. |
|||
|
|||
### Возврат ошибки |
|||
|
|||
После обнаружения, что учетные данные неверны, верните `HTTPException` с кодом состояния 401 (тот же, что возвращается, когда учетные данные не предоставлены) и добавьте заголовок `WWW-Authenticate`, чтобы браузер снова отобразил приглашение для входа: |
|||
|
|||
{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *} |
|||
@ -0,0 +1,19 @@ |
|||
# Расширенная безопасность |
|||
|
|||
## Дополнительные функции |
|||
|
|||
Существуют дополнительные функции для обеспечения безопасности, кроме тех, которые рассмотрены в [Руководстве пользователя: Безопасность](../../tutorial/security/index.md){.internal-link target=_blank}. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Следующие разделы **не обязательно "продвинутые"**. |
|||
|
|||
И возможно, что для вашего случая решения находятся в одном из них. |
|||
|
|||
/// |
|||
|
|||
## Сначала прочтите Руководство |
|||
|
|||
Следующие разделы предполагают, что вы уже прочитали основное [Руководство пользователя: Безопасность](../../tutorial/security/index.md){.internal-link target=_blank}. |
|||
|
|||
Все они основаны на тех же концепциях, но позволяют использовать некоторые дополнительные функции. |
|||
@ -0,0 +1,274 @@ |
|||
# OAuth2 scope |
|||
|
|||
Вы можете использовать OAuth2 scope напрямую с **FastAPI**, они интегрированы для работы без проблем. |
|||
|
|||
Это позволит вам иметь более тонкую систему разрешений, следуя стандарту OAuth2, интегрированную в ваше OpenAPI приложение (и документы API). |
|||
|
|||
OAuth2 с scope — это механизм, используемый многими крупными провайдерами аутентификации, такими как Facebook, Google, GitHub, Microsoft, Twitter и т.д. Они используют его для предоставления определенных разрешений пользователям и приложениям. |
|||
|
|||
Каждый раз, когда вы "входите с помощью" Facebook, Google, GitHub, Microsoft, Twitter, это приложение использует OAuth2 с scope. |
|||
|
|||
В этом разделе вы увидите, как управлять аутентификацией и авторизацией с использованием того же OAuth2 с scope в вашем приложении **FastAPI**. |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
Это более или менее сложный раздел. Если вы только начинаете, вы можете пропустить его. |
|||
|
|||
Вы не обязательно нуждаетесь в OAuth2 scope, и можете обрабатывать аутентификацию и авторизацию, как вам угодно. |
|||
|
|||
Но OAuth2 с scope может быть прекрасно интегрирован в ваш API (с OpenAPI) и в ваши документы API. |
|||
|
|||
Тем не менее, вы все равно должны применять эти scope, или любые другие требования к безопасности/авторизации, так как вам нужно, в вашем коде. |
|||
|
|||
В многих случаях, OAuth2 с scope может быть избыточными. |
|||
|
|||
Но если вы знаете, что они вам нужны, или вы заинтересовались, продолжайте чтение. |
|||
|
|||
/// |
|||
|
|||
## OAuth2 scope и OpenAPI |
|||
|
|||
Спецификация OAuth2 определяет "scope" как список строк, разделенных пробелами. |
|||
|
|||
Содержимое каждой из этих строк может иметь любой формат, но не должно содержать пробелов. |
|||
|
|||
Эти scope представляют собой "разрешения". |
|||
|
|||
В OpenAPI (например, в документах API) вы можете определить "схемы безопасности". |
|||
|
|||
Когда одна из этих схем безопасности использует OAuth2, вы также можете объявлять и использовать scope. |
|||
|
|||
Каждый "scope" — это просто строка (без пробелов). |
|||
|
|||
Обычно они используются для объявления определенных разрешений безопасности, например: |
|||
|
|||
* `users:read` или `users:write` — это распространенные примеры. |
|||
* `instagram_basic` используется Facebook/Instagram. |
|||
* `https://www.googleapis.com/auth/drive` используется Google. |
|||
|
|||
/// info | Информация |
|||
|
|||
В OAuth2 "scope" — это просто строка, указывающая на конкретные требуемые разрешения. |
|||
|
|||
Не имеет значения, есть ли в нем другие символы, такие как `:`, или если это URL. |
|||
|
|||
Эти детали специфичны для реализации. |
|||
|
|||
Для OAuth2 они просто строки. |
|||
|
|||
/// |
|||
|
|||
## Общее представление |
|||
|
|||
Сначала давайте быстро посмотрим на части, которые изменяются по сравнению с примерами в основном **Учебнике - Руководстве пользователя** для [OAuth2 с Паролем (и хешированием), Bearer с JWT токенами](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Теперь используя OAuth2 scope: |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:125,129:135,140,156] *} |
|||
|
|||
Теперь давайте рассмотрим эти изменения шаг за шагом. |
|||
|
|||
## Схема безопасности OAuth2 |
|||
|
|||
Первое изменение состоит в том, что мы теперь объявляем схему безопасности OAuth2 с двумя доступными scope, `me` и `items`. |
|||
|
|||
Параметр `scopes` принимает `dict`, где каждый scope указывается в качестве ключа, а описание — в качестве значения: |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *} |
|||
|
|||
Поскольку мы теперь объявляем эти scope, они будут отображаться в документации API, когда вы входите/авторизируетесь. |
|||
|
|||
И вы сможете выбрать, к каким scope вы хотите дать доступ: `me` и `items`. |
|||
|
|||
Это тот же механизм, который используется, когда вы предоставляете разрешения при входе в Facebook, Google, GitHub и т.д: |
|||
|
|||
<img src="/img/tutorial/security/image11.png"> |
|||
|
|||
## JWT токен с scope |
|||
|
|||
Теперь модифицируйте токен *операции пути*, чтобы вернуть запрашиваемые scope. |
|||
|
|||
Мы по-прежнему используем тот же `OAuth2PasswordRequestForm`. Он включает свойство `scopes` с `list` из `str`, в котором содержатся все scope, полученные в запросе. |
|||
|
|||
И мы возвращаем scope как часть JWT токена. |
|||
|
|||
/// danger | Опасность |
|||
|
|||
Для упрощения, здесь мы просто добавляем полученные scope непосредственно в токен. |
|||
|
|||
Но в вашем приложении, с целью безопасности, вы должны удостовериться, что добавляете только те scope, которые пользователь действительно может иметь, или те, которые вы заранее определили. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *} |
|||
|
|||
## Объявление scope в *операциях пути* и зависимостях |
|||
|
|||
Теперь мы объявляем, что *операция пути* для `/users/me/items/` требует scope `items`. |
|||
|
|||
Для этого мы импортируем и используем `Security` из `fastapi`. |
|||
|
|||
Вы можете использовать `Security` для объявления зависимостей (так же как `Depends`), но `Security` также принимает параметр `scopes` со списком scope (строк). |
|||
|
|||
В данном случае, мы передаем функцию зависимости `get_current_active_user` в `Security` (так же как мы бы делали это с `Depends`). |
|||
|
|||
Но мы также передаем `list` с scope, в этом случае только с одним scope: `items` (хотя их может быть больше). |
|||
|
|||
И функция зависимости `get_current_active_user` также может объявлять подзависимости, не только с `Depends`, но и с `Security`. Объявляя свою подзависимость (`get_current_user`), а также требования к scope. |
|||
|
|||
В этом случае требуется scope `me` (могут требоваться и другие scope). |
|||
|
|||
/// note | Примечание |
|||
|
|||
Вам не обязательно нужно добавлять разные scope в разные места. |
|||
|
|||
Мы делаем это здесь, чтобы продемонстрировать, как **FastAPI** обрабатывает scope, объявленные на разных уровнях. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *} |
|||
|
|||
/// info | Технические детали |
|||
|
|||
`Security` на самом деле является подклассом `Depends`, и у него есть всего один дополнительный параметр, который мы рассмотрим позже. |
|||
|
|||
Но используя `Security` вместо `Depends`, **FastAPI** будет знать, что он может объявить scope безопасности, использовать их внутри и документировать API с помощью OpenAPI. |
|||
|
|||
Но когда вы импортируете `Query`, `Path`, `Depends`, `Security` и другие из `fastapi`, это на самом деле функции, которые возвращают специальные классы. |
|||
|
|||
/// |
|||
|
|||
## Используйте `SecurityScopes` |
|||
|
|||
Теперь обновите зависимость `get_current_user`. |
|||
|
|||
Это та зависимость, которая используется выше. |
|||
|
|||
Вот где мы используем ту же схему OAuth2, которую создали ранее, объявляя ее как зависимость: `oauth2_scheme`. |
|||
|
|||
Поскольку эта функция зависимости не имеет собственных требований к scope, мы можем использовать `Depends` с `oauth2_scheme`, нам не нужно использовать `Security`, когда нам не нужно указывать scope безопасности. |
|||
|
|||
Также мы объявляем специальный параметр типа `SecurityScopes`, импортированный из `fastapi.security`. |
|||
|
|||
Этот класс `SecurityScopes` похож на `Request` (`Request` использовался для получения объекта запроса напрямую). |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *} |
|||
|
|||
## Используйте `scopes` |
|||
|
|||
Параметр `security_scopes` будет типа `SecurityScopes`. |
|||
|
|||
У него есть свойство `scopes` со списком, содержащим все scope, требуемые как сама зависимость, так и все зависимости, которые используют это как подзависимость. Это значит, все "зависимые"... это может звучать запутанно, но это объясняется снова позже. |
|||
|
|||
Объект `security_scopes` (класса `SecurityScopes`) также предоставляет атрибут `scope_str` с одной строкой, содержащей эти scope, разделенные пробелами (мы собираемся использовать его). |
|||
|
|||
Мы создаем `HTTPException`, который мы можем использовать (`raise`) позже в нескольких повторяющихся моментах. |
|||
|
|||
В этом исключении мы включаем требуемые scope (если они есть) в виде строки, разделенной пробелами (используя `scope_str`). Мы помещаем эту строку, содержащую scope, в HTTP-заголовке `WWW-Authenticate` (это часть спецификации). |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *} |
|||
|
|||
## Проверьте `username` и форму данных |
|||
|
|||
Мы проверяем, что получили `username`, и извлекаем scope. |
|||
|
|||
Затем мы валидируем эти данные с помощью Pydantic-модели (обрабатывая исключение `ValidationError`), и если мы получаем ошибку при чтении JWT токена или валидации данных с Pydantic, мы вызываем `HTTPException`, который создали ранее. |
|||
|
|||
Для этого мы обновляем Pydantic-модель `TokenData` с новым свойством `scopes`. |
|||
|
|||
Валидируя данные с помощью Pydantic, мы можем убедиться, что у нас, например, точно есть `list` из `str` с scope и `str` с `username`. |
|||
|
|||
Вместо, например, `dict`, или чего-то еще, так как это может сломать приложение в какой-то момент позже, создавая угрозу безопасности. |
|||
|
|||
Мы также проверяем, что у нас есть пользователь с этим именем пользователя, и если нет, вызываем то же самое исключение, созданное ранее. |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:128] *} |
|||
|
|||
## Проверьте `scopes` |
|||
|
|||
Теперь мы проверяем, все ли требуемые scope, этой зависимостью и всеми зависимыми (включая *операции пути*), включены в предоставленные токеном scope, в противном случае вызываем `HTTPException`. |
|||
|
|||
Для этого мы используем `security_scopes.scopes`, который содержит `list` со всеми этими scope как `str`. |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[129:135] *} |
|||
|
|||
## Дерево зависимостей и scope |
|||
|
|||
Давайте еще раз рассмотрим это дерево зависимостей и scope. |
|||
|
|||
Поскольку зависимость `get_current_active_user` имеет подзависимость на `get_current_user`, scope `"me"`, объявленный в `get_current_active_user`, будет включен в список требуемых scope в `security_scopes.scopes`, переданном в `get_current_user`. |
|||
|
|||
Сама *операция пути* также объявляет scope, `"items"`, так что он также будет в списке `security_scopes.scopes`, передаваемом в `get_current_user`. |
|||
|
|||
Вот как выглядит иерархия зависимостей и scope: |
|||
|
|||
* У *операции пути* `read_own_items`: |
|||
* Требуемые scope `["items"]` с зависимостью: |
|||
* `get_current_active_user`: |
|||
* Функция зависимости `get_current_active_user` имеет: |
|||
* Требуемые scope `["me"]` с зависимостью: |
|||
* `get_current_user`: |
|||
* У функции зависимости `get_current_user`: |
|||
* Нет требуемых scope. |
|||
* Зависимость, использующая `oauth2_scheme`. |
|||
* Параметр `security_scopes` типа `SecurityScopes`: |
|||
* У этого параметра `security_scopes` есть свойство `scopes` со `list`, содержащим все scope, объявленные выше, так что: |
|||
* `security_scopes.scopes` будет содержать `["me", "items"]` для *операции пути* `read_own_items`. |
|||
* `security_scopes.scopes` будет содержать `["me"]` для *операции пути* `read_users_me`, потому что он объявлен в зависимости `get_current_active_user`. |
|||
* `security_scopes.scopes` будет содержать `[]` (ничего) для *операции пути* `read_system_status`, потому что там не объявлено никакое `Security` с `scopes`, и его зависимость `get_current_user` также не объявляет никакие `scopes`. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Самое важное и "магическое" здесь то, что `get_current_user` будет иметь разный список `scopes` для проверки для каждой *операции пути*. |
|||
|
|||
Все зависит от `scopes`, объявленных в каждой *операции пути* и каждой зависимости в дереве зависимостей для данной конкретной *операции пути*. |
|||
|
|||
/// |
|||
|
|||
## Подробности о `SecurityScopes` |
|||
|
|||
Вы можете использовать `SecurityScopes` в любой точке и в нескольких местах, он не должен быть на уровне "корневой" зависимости. |
|||
|
|||
Он будет всегда иметь scope безопасности, объявленные в текущих зависимостях `Security` и всех зависимых для **конкретно этой** *операции пути* и **конкретно этого** дерева зависимостей. |
|||
|
|||
Поскольку `SecurityScopes` будут иметь все scope, заявленные зависимыми, вы можете использовать его для проверки того, что токен имеет требуемые scope в центральной функции зависимости, а затем объявлять разные требования к scope в разных *операциях пути*. |
|||
|
|||
Они будут проверяться независимо для каждой *операции пути*. |
|||
|
|||
## Проверьте это |
|||
|
|||
Если вы откроете документацию API, вы можете аутентифицироваться и указать, какие scope вы хотите авторизовать. |
|||
|
|||
<img src="/img/tutorial/security/image11.png"> |
|||
|
|||
Если вы не выберете ни один scope, вы будете "аутентифицированы", но при попытке доступа к `/users/me/` или `/users/me/items/` вы получите ошибку, сообщающую, что у вас недостаточно разрешений. Вы все равно сможете получить доступ к `/status/`. |
|||
|
|||
И если вы выберете scope `me`, но не scope `items`, вы сможете получить доступ к `/users/me/`, но не к `/users/me/items/`. |
|||
|
|||
Это именно то, что произойдет с сторонним приложением, которое пытается получить доступ к одной из этих *операций пути* с токеном, предоставленным пользователем, в зависимости от того, сколько разрешений пользователь дал приложению. |
|||
|
|||
## О сторонних интеграциях |
|||
|
|||
В этом примере мы используем OAuth2 "парольный" поток. |
|||
|
|||
Это уместно, когда мы входим в наше собственное приложение, вероятно, с нашим собственным фронтендом. |
|||
|
|||
Потому что мы можем доверять ему получение `username` и `password`, так как мы его контролируем. |
|||
|
|||
Но если вы строите приложение OAuth2, к которому будут подключаться другие (т.е. если вы создаете провайдер аутентификации, эквивалентный Facebook, Google, GitHub и т.д.), вы должны использовать один из других потоков. |
|||
|
|||
Наиболее распространенным является поток implicit. |
|||
|
|||
Наиболее безопасным является поток с кодом, но его сложнее реализовать, так как он требует больше шагов. Поскольку он более сложен, многие провайдеры в конечном итоге предлагают поток implicit. |
|||
|
|||
/// note | Примечание |
|||
|
|||
Часто каждый провайдер аутентификации называет свои потоки по-разному, чтобы сделать это частью своего бренда. |
|||
|
|||
Но в конечном итоге они реализуют тот же стандарт OAuth2. |
|||
|
|||
/// |
|||
|
|||
**FastAPI** включает утилиты для всех этих потоков аутентификации OAuth2 в `fastapi.security.oauth2`. |
|||
|
|||
## `Security` в `dependencies` декоратора |
|||
|
|||
Таким же образом, как вы можете определять `list` из `Depends` в параметре `dependencies` декоратора (как объяснено в [Dependencies в декораторах операций пути](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), вы также можете использовать `Security` с `scopes` там. |
|||
@ -0,0 +1,346 @@ |
|||
# Настройки и переменные окружения |
|||
|
|||
Во многих случаях вашим приложениям могут понадобиться внешние настройки или конфигурации, например, секретные ключи, учетные данные базы данных, учетные данные для почтовых сервисов и т.д. |
|||
|
|||
Большинство этих настроек являются изменяемыми (могут изменяться), как, например, URL-ы баз данных. Многие из них могут быть чувствительными, как, например, секреты. |
|||
|
|||
По этой причине их обычно предоставляют в виде переменных окружения, которые считываются приложением. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Чтобы понять, что такое переменные окружения, можете прочитать [Переменные окружения](../environment-variables.md){.internal-link target=_blank}. |
|||
|
|||
/// |
|||
|
|||
## Типы и валидация |
|||
|
|||
Эти переменные окружения могут обрабатывать только текстовые строки, так как они являются внешними для Python и должны быть совместимы с другими программами и остальной системой (и даже с разными операционными системами, такими как Linux, Windows, macOS). |
|||
|
|||
Это означает, что любое значение, считанное в Python из переменной окружения, будет типа `str`, и любое преобразование в другой тип или валидация должны осуществляться в коде. |
|||
|
|||
## Pydantic `Settings` |
|||
|
|||
К счастью, Pydantic предоставляет отличную утилиту для работы с этими настройками, поступающими из переменных окружения, используя <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/" class="external-link" target="_blank">Pydantic: Управление настройками</a>. |
|||
|
|||
### Установка `pydantic-settings` |
|||
|
|||
Сначала убедитесь, что вы создали ваше [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его и затем установили пакет `pydantic-settings`: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install pydantic-settings |
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Этот пакет также включен, если вы устанавливаете все зависимости с: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "fastapi[all]" |
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
/// info | Информация |
|||
|
|||
В Pydantic v1 он поставлялся с основным пакетом. Теперь он распространяется как отдельный пакет, чтобы вы могли выбрать, устанавливать его или нет, если вам не нужна эта функциональность. |
|||
|
|||
/// |
|||
|
|||
### Создание объекта `Settings` |
|||
|
|||
Импортируйте `BaseSettings` из Pydantic и создайте подкласс, как это делается с Pydantic-моделью. |
|||
|
|||
Так же, как и с Pydantic-моделями, вы объявляете атрибуты класса с аннотациями типов и, возможно, значениями по умолчанию. |
|||
|
|||
Вы можете использовать все те же функции валидации и инструменты, которые используете в Pydantic-моделях, например, разные типы данных и дополнительные валидации с `Field()`. |
|||
|
|||
//// tab | Pydantic v2 |
|||
|
|||
{* ../../docs_src/settings/tutorial001.py hl[2,5:8,11] *} |
|||
|
|||
//// |
|||
|
|||
//// tab | Pydantic v1 |
|||
|
|||
/// info | Информация |
|||
|
|||
В Pydantic v1 вы импортировали бы `BaseSettings` непосредственно из `pydantic` вместо `pydantic_settings`. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/settings/tutorial001_pv1.py hl[2,5:8,11] *} |
|||
|
|||
//// |
|||
|
|||
/// tip | Совет |
|||
|
|||
Если вам нужно что-то быстрое для копирования и вставки, не используйте этот пример, используйте последний ниже. |
|||
|
|||
/// |
|||
|
|||
Когда вы создаете экземпляр этого класса `Settings` (в данном случае, в объекте `settings`), Pydantic будет считывать переменные окружения без учета регистра, так что переменная в верхнем регистре `APP_NAME` все еще будет считана для атрибута `app_name`. |
|||
|
|||
Затем он выполнит преобразование и валидацию данных. Таким образом, когда вы используете этот объект `settings`, у вас будут данные тех типов, которые вы объявили (например, `items_per_user` будет типа `int`). |
|||
|
|||
### Использование `settings` |
|||
|
|||
Затем вы можете использовать новый объект `settings` в вашем приложении: |
|||
|
|||
{* ../../docs_src/settings/tutorial001.py hl[18:20] *} |
|||
|
|||
### Запуск сервера |
|||
|
|||
Далее вы можете запустить сервер, передавая конфигурации как переменные окружения, например, вы можете установить `ADMIN_EMAIL` и `APP_NAME` следующим образом: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
/// tip | Совет |
|||
|
|||
Чтобы установить несколько переменных окружения для одной команды, просто разделите их пробелами и укажите перед командой. |
|||
|
|||
/// |
|||
|
|||
Тогда настройка `admin_email` будет установлена в `"deadpool@example.com"`. |
|||
|
|||
Настройка `app_name` будет иметь значение `"ChimichangApp"`. |
|||
|
|||
А `items_per_user` сохранит свое значение по умолчанию — `50`. |
|||
|
|||
## Настройки в другом модуле |
|||
|
|||
Вы можете поместить эти настройки в другой файл-модуль, как вы видели в [Более крупные приложения - Несколько файлов](../tutorial/bigger-applications.md){.internal-link target=_blank}. |
|||
|
|||
Например, у вас может быть файл `config.py` с: |
|||
|
|||
{* ../../docs_src/settings/app01/config.py *} |
|||
|
|||
И затем использовать его в файле `main.py`: |
|||
|
|||
{* ../../docs_src/settings/app01/main.py hl[3,11:13] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Вам также нужен будет файл `__init__.py`, как вы видели в [Более крупные приложения - Несколько файлов](../tutorial/bigger-applications.md){.internal-link target=_blank}. |
|||
|
|||
/// |
|||
|
|||
## Настройки в зависимости |
|||
|
|||
В некоторых случаях может быть полезно предоставлять настройки из зависимости, вместо использования глобального объекта `settings`, который используется везде. |
|||
|
|||
Это может быть особенно полезно во время тестирования, так как очень легко переопределить зависимость вашими собственными настройками. |
|||
|
|||
### Файл конфигурации |
|||
|
|||
Исходя из предыдущего примера, ваш файл `config.py` может выглядеть так: |
|||
|
|||
{* ../../docs_src/settings/app02/config.py hl[10] *} |
|||
|
|||
Обратите внимание, что теперь мы не создаем экземпляр по умолчанию `settings = Settings()`. |
|||
|
|||
### Основной файл приложения |
|||
|
|||
Теперь мы создаем зависимость, которая возвращает новый `config.Settings()`. |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/main.py hl[6,12:13] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Мы обсудим `@lru_cache` чуть позже. |
|||
|
|||
На данный момент можно считать, что `get_settings()` — это обычная функция. |
|||
|
|||
/// |
|||
|
|||
А затем мы можем потребовать его в *функции-обработчике пути* как зависимость и использовать ее в любом месте, где это необходимо. |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/main.py hl[17,19:21] *} |
|||
|
|||
### Настройки и тестирование |
|||
|
|||
Затем вам будет очень легко предоставить другой объект настроек во время тестирования, создав переопределение зависимости для `get_settings`: |
|||
|
|||
{* ../../docs_src/settings/app02/test_main.py hl[9:10,13,21] *} |
|||
|
|||
В переопределении зависимости мы устанавливаем новое значение для `admin_email`, создавая новый объект `Settings`, а затем возвращаем этот новый объект. |
|||
|
|||
Затем мы можем протестировать, что он используется. |
|||
|
|||
## Чтение файла `.env` |
|||
|
|||
Если у вас есть множество настроек, которые могут часто меняться, возможно, в разных окружениях, может быть полезно поместить их в файл и затем считывать их из него, как если бы они были переменными окружения. |
|||
|
|||
Эта практика достаточно распространена, чтобы у нее было название, эти переменные окружения обычно помещаются в файл `.env`, и этот файл называется "dotenv". |
|||
|
|||
/// tip | Совет |
|||
|
|||
Файл, начинающийся с точки (`.`), является скрытым файлом в системах, похожих на Unix, таких как Linux и macOS. |
|||
|
|||
Но файл dotenv не обязательно должен иметь именно такое имя. |
|||
|
|||
/// |
|||
|
|||
Pydantic поддерживает считывание из таких файлов с использованием внешней библиотеки. Вы можете узнать больше на <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support" class="external-link" target="_blank">Pydantic Settings: Поддержка Dotenv (.env)</a>. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Для этого необходимо выполнить `pip install python-dotenv`. |
|||
|
|||
/// |
|||
|
|||
### Файл `.env` |
|||
|
|||
Вы могли бы иметь файл `.env` с: |
|||
|
|||
```bash |
|||
ADMIN_EMAIL="deadpool@example.com" |
|||
APP_NAME="ChimichangApp" |
|||
``` |
|||
|
|||
### Чтение настроек из `.env` |
|||
|
|||
А затем обновить ваш `config.py` следующим образом: |
|||
|
|||
//// tab | Pydantic v2 |
|||
|
|||
{* ../../docs_src/settings/app03_an/config.py hl[9] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Атрибут `model_config` используется только для настройки Pydantic. Вы можете прочитать больше на <a href="https://docs.pydantic.dev/latest/concepts/config/" class="external-link" target="_blank">Pydantic: Концепции: Конфигурация</a>. |
|||
|
|||
/// |
|||
|
|||
//// |
|||
|
|||
//// tab | Pydantic v1 |
|||
|
|||
{* ../../docs_src/settings/app03_an/config_pv1.py hl[9:10] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Класс `Config` используется только для настройки Pydantic. Вы можете прочитать больше на <a href="https://docs.pydantic.dev/1.10/usage/model_config/" class="external-link" target="_blank">Конфигурация Pydantic модели</a>. |
|||
|
|||
/// |
|||
|
|||
//// |
|||
|
|||
/// info | Информация |
|||
|
|||
В версии Pydantic 1 конфигурация осуществлялась во внутреннем классе `Config`, в версии Pydantic 2 это делается в атрибуте `model_config`. Этот атрибут принимает `dict`, и чтобы получить автозавершение и встроенные ошибки, вы можете импортировать и использовать `SettingsConfigDict` для определения этого `dict`. |
|||
|
|||
/// |
|||
|
|||
Здесь мы определяем конфигурацию `env_file` внутри вашего класса Pydantic `Settings` и устанавливаем значение для имени файла с файлом dotenv, который мы хотим использовать. |
|||
|
|||
### Создание `Settings` только один раз с `lru_cache` |
|||
|
|||
Чтение файла с диска обычно является дорогой (медленной) операцией, поэтому, вероятно, вы захотите делать это только один раз, а затем использовать тот же объект настроек, вместо того чтобы считывать его для каждого запроса. |
|||
|
|||
Но каждый раз, когда мы выполняем: |
|||
|
|||
```Python |
|||
Settings() |
|||
``` |
|||
|
|||
новый объект `Settings` будет создан, и при создании он снова считает файл `.env`. |
|||
|
|||
Если бы функция зависимости выглядела так: |
|||
|
|||
```Python |
|||
def get_settings(): |
|||
return Settings() |
|||
``` |
|||
|
|||
мы бы создавали этот объект для каждого запроса, и мы бы считывали файл `.env` для каждого запроса. ⚠️ |
|||
|
|||
Но так как мы используем декоратор `@lru_cache` сверху, объект `Settings` будет создан только один раз, при первом вызове. ✔️ |
|||
|
|||
{* ../../docs_src/settings/app03_an_py39/main.py hl[1,11] *} |
|||
|
|||
Затем для всех последующих вызовов `get_settings()` в зависимостях для следующих запросов, вместо выполнения внутреннего кода функции `get_settings()` и создания нового объекта `Settings`, будет возвращен тот же объект, который был возвращен при первом вызове, снова и снова. |
|||
|
|||
#### Технические детали `lru_cache` |
|||
|
|||
`@lru_cache` модифицирует функцию, которую он декорирует, чтобы возвращать то же самое значение, которое было возвращено в первый раз, вместо того чтобы вычислять его снова, выполняя код функции каждый раз. |
|||
|
|||
Таким образом, функция ниже будет выполнена один раз для каждой комбинации аргументов. А затем возвращаемые значения для каждой из этих комбинаций аргументов будут использоваться снова и снова, когда функция вызывается с точно такой же комбинацией аргументов. |
|||
|
|||
Например, если у вас есть функция: |
|||
|
|||
```Python |
|||
@lru_cache |
|||
def say_hi(name: str, salutation: str = "Ms."): |
|||
return f"Hello {salutation} {name}" |
|||
``` |
|||
|
|||
ваша программа может выполняться так: |
|||
|
|||
```mermaid |
|||
sequenceDiagram |
|||
|
|||
participant code as Код |
|||
participant function as say_hi() |
|||
participant execute as Выполнить код функции |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> execute: выполнить код функции |
|||
execute ->> code: вернуть результат |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> code: вернуть сохраненный результат |
|||
end |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Rick") |
|||
function ->> execute: выполнить код функции |
|||
execute ->> code: вернуть результат |
|||
end |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Rick", salutation="Mr.") |
|||
function ->> execute: выполнить код функции |
|||
execute ->> code: вернуть результат |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Rick") |
|||
function ->> code: вернуть сохраненный результат |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> code: вернуть сохраненный результат |
|||
end |
|||
``` |
|||
|
|||
В случае нашей зависимости `get_settings()`, функция даже не принимает никаких аргументов, поэтому всегда возвращает одно и то же значение. |
|||
|
|||
Таким образом, она ведет себя почти как глобальная переменная. Но поскольку используется функция зависимости, мы можем легко переопределить ее для тестирования. |
|||
|
|||
`@lru_cache` является частью `functools`, который является частью стандартной библиотеки Python, вы можете прочитать больше об этом в <a href="https://docs.python.org/3/library/functools.html#functools.lru_cache" class="external-link" target="_blank">документации Python по `@lru_cache`</a>. |
|||
|
|||
## Резюме |
|||
|
|||
Вы можете использовать Pydantic Settings для управления настройками или конфигурациями вашего приложения, используя все возможности Pydantic-моделей. |
|||
|
|||
* Используя зависимость, вы можете упростить тестирование. |
|||
* Вы можете использовать `.env` файлы с ним. |
|||
* Использование `@lru_cache` позволяет избежать повторного чтения файла dotenv для каждого запроса, при этом позволяя его переопределять во время тестирования. |
|||
@ -0,0 +1,67 @@ |
|||
# Подприложения - Mounts |
|||
|
|||
Если вам нужно иметь два независимых FastAPI приложения, каждое с собственным, независимым OpenAPI и собственными интерфейсами документации, вы можете создать основное приложение и "смонтировать" одно (или более) подприложение(я). |
|||
|
|||
## Монтирование **FastAPI** приложения |
|||
|
|||
"Монтирование" означает добавление полностью "независимого" приложения в определенный path, которое затем будет обрабатывать все под этим path, с _операциями пути_, объявленными в этом подприложении. |
|||
|
|||
### Высокоуровневое приложение |
|||
|
|||
Сначала создайте основное, высшего уровня, **FastAPI** приложение и его *операции пути*: |
|||
|
|||
{* ../../docs_src/sub_applications/tutorial001.py hl[3, 6:8] *} |
|||
|
|||
### Подприложение |
|||
|
|||
Затем создайте ваше подприложение и его *операции пути*. |
|||
|
|||
Это подприложение является стандартным FastAPI приложением, но именно оно будет "смонтировано": |
|||
|
|||
{* ../../docs_src/sub_applications/tutorial001.py hl[11, 14:16] *} |
|||
|
|||
### Монтирование подприложения |
|||
|
|||
В вашем высшего уровня приложении, `app`, смонтируйте подприложение, `subapi`. |
|||
|
|||
В этом случае оно будет смонтировано на path `/subapi`: |
|||
|
|||
{* ../../docs_src/sub_applications/tutorial001.py hl[11, 19] *} |
|||
|
|||
### Проверьте автоматическую документацию API |
|||
|
|||
Теперь запустите команду `fastapi` с вашим файлом: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi dev main.py |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
И откройте документацию по адресу <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
Вы увидите автоматическую документацию API для основного приложения, включающую лишь его собственные _операции пути_: |
|||
|
|||
<img src="/img/tutorial/sub-applications/image01.png"> |
|||
|
|||
Затем откройте документацию для подприложения по адресу <a href="http://127.0.0.1:8000/subapi/docs" class="external-link" target="_blank">http://127.0.0.1:8000/subapi/docs</a>. |
|||
|
|||
Вы увидите автоматическую документацию API для подприложения, включающую только его собственные _операции пути_, все с правильным префиксом под-path `/subapi`: |
|||
|
|||
<img src="/img/tutorial/sub-applications/image02.png"> |
|||
|
|||
Если вы попробуете взаимодействовать с любым из двух пользовательских интерфейсов, они будут работать правильно, потому что браузер сможет обратиться к каждому конкретному приложению или подприложению. |
|||
|
|||
### Технические детали: `root_path` |
|||
|
|||
Когда вы монтируете подприложение, как описано выше, FastAPI позаботится о передаче пути монтирования для подприложения, используя механизм из спецификации ASGI, называемый `root_path`. |
|||
|
|||
Таким образом, подприложение будет знать, что необходимо использовать этот префикс пути для UI документации. |
|||
|
|||
И подприложение также может иметь свои собственные смонтированные подприложения, и всё будет работать корректно, потому что FastAPI обрабатывает все эти `root_path`s автоматически. |
|||
|
|||
Вы узнаете больше о `root_path` и том, как его использовать явно в разделе про [Работу за прокси-сервером](behind-a-proxy.md){.internal-link target=_blank}. |
|||
@ -0,0 +1,126 @@ |
|||
# Шаблоны |
|||
|
|||
Вы можете использовать любой шаблонизатор, который захотите, с **FastAPI**. |
|||
|
|||
Популярным выбором является Jinja2, который также используется Flask и другими инструментами. |
|||
|
|||
Существуют утилиты для его простой настройки, которые вы можете использовать непосредственно в своем приложении **FastAPI** (предоставлено Starlette). |
|||
|
|||
## Установка зависимостей |
|||
|
|||
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его и установили `jinja2`: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install jinja2 |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
## Использование `Jinja2Templates` |
|||
|
|||
* Импортируйте `Jinja2Templates`. |
|||
* Создайте объект `templates`, который вы сможете повторно использовать позднее. |
|||
* Объявите параметр `Request` в *операции пути*, которая будет возвращать шаблон. |
|||
* Используйте созданные вами `templates` для рендеринга и возврата `TemplateResponse`, передайте имя шаблона, объект запроса и словарь "context" с парами "ключ-значение", которые будут использоваться внутри шаблона Jinja2. |
|||
|
|||
{* ../../docs_src/templates/tutorial001.py hl[4,11,15:18] *} |
|||
|
|||
/// note | Примечание |
|||
|
|||
До FastAPI 0.108.0, Starlette 0.29.0, параметр `name` был первым. |
|||
|
|||
Также, до этого, в предыдущих версиях объект `request` передавался как часть пар ключ-значение в контексте для Jinja2. |
|||
|
|||
/// |
|||
|
|||
/// tip | Совет |
|||
|
|||
Объявляя `response_class=HTMLResponse`, интерфейс документации сможет определить, что ответ будет в формате HTML. |
|||
|
|||
/// |
|||
|
|||
/// note | Технические детали |
|||
|
|||
Вы также можете использовать `from starlette.templating import Jinja2Templates`. |
|||
|
|||
**FastAPI** предоставляет тот же `starlette.templating` как `fastapi.templating` просто для вашего удобства, разработчик. Но большинство доступных ответов поступают непосредственно от Starlette. То же самое касается `Request` и `StaticFiles`. |
|||
|
|||
/// |
|||
|
|||
## Написание шаблонов |
|||
|
|||
Затем вы можете написать шаблон в `templates/item.html`, например: |
|||
|
|||
```jinja hl_lines="7" |
|||
{!../../docs_src/templates/templates/item.html!} |
|||
``` |
|||
|
|||
### Значения контекста шаблона |
|||
|
|||
В HTML, который содержит: |
|||
|
|||
{% raw %} |
|||
|
|||
```jinja |
|||
Item ID: {{ id }} |
|||
``` |
|||
|
|||
{% endraw %} |
|||
|
|||
...будет показан `id`, взятый из "context" `dict`, который вы передали: |
|||
|
|||
```Python |
|||
{"id": id} |
|||
``` |
|||
|
|||
Например, с `id`, равным `42`, это будет рендериться как: |
|||
|
|||
```html |
|||
Item ID: 42 |
|||
``` |
|||
|
|||
### Аргументы `url_for` в шаблоне |
|||
|
|||
Вы также можете использовать `url_for()` внутри шаблона; он принимает в качестве аргументов те же аргументы, которые использовались бы в вашей *функции-обработчике пути*. |
|||
|
|||
Таким образом, раздел с: |
|||
|
|||
{% raw %} |
|||
|
|||
```jinja |
|||
<a href="{{ url_for('read_item', id=id) }}"> |
|||
``` |
|||
|
|||
{% endraw %} |
|||
|
|||
...сгенерирует ссылку на тот же URL, который был бы обработан *функцией-обработчиком пути* `read_item(id=id)`. |
|||
|
|||
Например, с `id`, равным `42`, это будет рендериться как: |
|||
|
|||
```html |
|||
<a href="/items/42"> |
|||
``` |
|||
|
|||
## Шаблоны и статические файлы |
|||
|
|||
Вы также можете использовать `url_for()` внутри шаблона и использовать его, например, с `StaticFiles`, которые вы смонтировали с `name="static"`. |
|||
|
|||
```jinja hl_lines="4" |
|||
{!../../docs_src/templates/templates/item.html!} |
|||
``` |
|||
|
|||
В этом примере это будет ссылка на CSS-файл по пути `static/styles.css` с: |
|||
|
|||
```CSS hl_lines="4" |
|||
{!../../docs_src/templates/static/styles.css!} |
|||
``` |
|||
|
|||
И поскольку вы используете `StaticFiles`, этот CSS-файл будет автоматически обслуживаться вашим приложением **FastAPI** по URL `/static/styles.css`. |
|||
|
|||
## Дополнительные сведения |
|||
|
|||
Для получения дополнительной информации, включая тестирование шаблонов, смотрите <a href="https://www.starlette.io/templates/" class="external-link" target="_blank">документацию Starlette по шаблонам</a>. |
|||
@ -0,0 +1,53 @@ |
|||
# Тестирование зависимостей с использованием переопределений |
|||
|
|||
## Переопределение зависимостей в процессе тестирования |
|||
|
|||
Существуют сценарии, когда вам может понадобиться переопределить зависимость во время тестирования. |
|||
|
|||
Вы не хотите, чтобы оригинальная зависимость выполнялась (также как и любые её подзависимости). |
|||
|
|||
Вместо этого, вы хотите предоставить другую зависимость, которая будет использоваться только во время тестов (возможно, только для некоторых конкретных тестов), и будет предоставлять значение, которое можно использовать там, где использовалось значение оригинальной зависимости. |
|||
|
|||
### Примеры использования: внешний сервис |
|||
|
|||
Примером может служить ситуация, когда у вас есть внешний провайдер аутентификации, которого вам необходимо вызывать. |
|||
|
|||
Вы отправляете ему токен, и он возвращает аутентифицированного пользователя. |
|||
|
|||
Этот провайдер может брать плату за каждый запрос, и вызов его может занять больше времени, чем если бы вы использовали фиксированного пользователя-мока для тестов. |
|||
|
|||
Вероятно, вы захотите протестировать внешнего провайдера один раз, но не обязательно вызывать его для каждого теста, который вы запускаете. |
|||
|
|||
В этом случае вы можете переопределить зависимость, которая вызывает этого провайдера, и использовать пользовательскую зависимость, которая возвращает мока-пользователя, только для ваших тестов. |
|||
|
|||
### Использование атрибута `app.dependency_overrides` |
|||
|
|||
В таких случаях ваше приложение **FastAPI** имеет атрибут `app.dependency_overrides`, который является простым `dict`. |
|||
|
|||
Чтобы переопределить зависимость для тестирования, вы указываете оригинальную зависимость (функцию) в качестве ключа, и ваше переопределение зависимости (другую функцию) в качестве значения. |
|||
|
|||
Затем **FastAPI** будет вызывать это переопределение вместо оригинальной зависимости. |
|||
|
|||
{* ../../docs_src/dependency_testing/tutorial001_an_py310.py hl[26:27,30] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Вы можете установить переопределение зависимости для зависимости, используемой в любом месте вашего приложения **FastAPI**. |
|||
|
|||
Оригинальная зависимость может использоваться в *функции-обработчике пути*, *декораторе операции пути* (если вы не используете возвращаемое значение), вызове `.include_router()`, и т. д. |
|||
|
|||
FastAPI все равно сможет ее переопределить. |
|||
|
|||
/// |
|||
|
|||
Затем вы можете сбросить ваши переопределения (удалить их), установив `app.dependency_overrides` в пустой `dict`: |
|||
|
|||
```Python |
|||
app.dependency_overrides = {} |
|||
``` |
|||
|
|||
/// tip | Совет |
|||
|
|||
Если вы хотите переопределить зависимость только в некоторых тестах, вы можете установить переопределение в начале теста (внутри тестовой функции) и сбросить его в конце (в конце тестовой функции). |
|||
|
|||
/// |
|||
@ -0,0 +1,5 @@ |
|||
# Тестирование событий: startup - shutdown |
|||
|
|||
Когда вам нужно, чтобы ваши обработчики событий (`startup` и `shutdown`) запускались в ваших тестах, вы можете использовать `TestClient` с оператором `with`: |
|||
|
|||
{* ../../docs_src/app_testing/tutorial003.py hl[9:12,20:24] *} |
|||
@ -0,0 +1,13 @@ |
|||
# Тестирование WebSockets |
|||
|
|||
Вы можете использовать тот же `TestClient` для тестирования WebSockets. |
|||
|
|||
Для этого вы используете `TestClient` в операторе `with`, подключаясь к WebSocket: |
|||
|
|||
{* ../../docs_src/app_testing/tutorial002.py hl[27:31] *} |
|||
|
|||
/// note | Заметка |
|||
|
|||
Для получения дополнительных сведений обратитесь к документации Starlette для <a href="https://www.starlette.io/testclient/#testing-websocket-sessions" class="external-link" target="_blank">тестирования WebSockets</a>. |
|||
|
|||
/// |
|||
@ -0,0 +1,56 @@ |
|||
# Прямое использование объекта Request |
|||
|
|||
До сих пор вы объявляли части HTTP-запроса, которые вам нужны, с указанием их типов. |
|||
|
|||
Получение данных из: |
|||
|
|||
* path как параметров. |
|||
* HTTP-заголовков. |
|||
* cookies. |
|||
* и т.д. |
|||
|
|||
И благодаря этому, **FastAPI** валидирует эти данные, выполняет их преобразование и автоматически генерирует документацию для вашего API. |
|||
|
|||
Но есть ситуации, когда может понадобиться доступ к объекту `Request` напрямую. |
|||
|
|||
## Подробности об объекте `Request` |
|||
|
|||
Так как **FastAPI** на самом деле построен на **Starlette**, с уровнем дополнительных инструментов сверху, вы можете использовать объект <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request`</a> из Starlette напрямую, когда это необходимо. |
|||
|
|||
Это также означает, что если вы получаете данные из объекта `Request` напрямую (например, читаете тело запроса), они не будут валидироваться, преобразовываться или документироваться (с использованием OpenAPI для автоматического пользовательского интерфейса API) в FastAPI. |
|||
|
|||
Хотя любой другой параметр, объявленный обычно (например, тело запроса с Pydantic моделью), все равно будет валидироваться, преобразовываться, аннотироваться и т.д. |
|||
|
|||
Но есть определенные случаи, когда полезно получить объект `Request`. |
|||
|
|||
## Использование объекта `Request` напрямую |
|||
|
|||
Представьте, что вы хотите получить IP-адрес/хост клиента внутри вашей *функции-обработчика пути*. |
|||
|
|||
Для этого вам нужно будет получить доступ к запросу напрямую. |
|||
|
|||
{* ../../docs_src/using_request_directly/tutorial001.py hl[1,7:8] *} |
|||
|
|||
Объявляя параметр *функции-обработчика пути* с типом `Request`, **FastAPI** поймет, что необходимо передать объект `Request` в этот параметр. |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
Обратите внимание, что в этом случае мы объявляем path параметр вместе с параметром запроса. |
|||
|
|||
Таким образом, path параметр будет извлечен, провалидирован, преобразован в указанный тип и аннотирован с помощью OpenAPI. |
|||
|
|||
Точно так же вы можете объявить любой другой параметр как обычно, и дополнительно получить также объект `Request`. |
|||
|
|||
/// |
|||
|
|||
## Документация по `Request` |
|||
|
|||
Вы можете прочитать больше деталей о <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">объекте `Request` на официальном сайте документации Starlette</a>. |
|||
|
|||
/// note | Технические Подробности |
|||
|
|||
Вы также можете использовать `from starlette.requests import Request`. |
|||
|
|||
**FastAPI** предоставляет это напрямую просто для удобства для вас, разработчика. Но эта функция приходит прямо из Starlette. |
|||
|
|||
/// |
|||
@ -0,0 +1,35 @@ |
|||
# Включение WSGI - Flask, Django и другие |
|||
|
|||
Вы можете монтировать WSGI-приложения, как вы видели в разделе [Дополнительные приложения - Монтирования](sub-applications.md){.internal-link target=_blank}, [За прокси](behind-a-proxy.md){.internal-link target=_blank}. |
|||
|
|||
Для этого вы можете использовать `WSGIMiddleware`, чтобы обернуть ваше WSGI-приложение, например, Flask, Django и т.д. |
|||
|
|||
## Использование `WSGIMiddleware` |
|||
|
|||
Вам нужно импортировать `WSGIMiddleware`. |
|||
|
|||
Затем обернуть WSGI (например, Flask) приложение с помощью middleware (промежуточного слоя). |
|||
|
|||
И затем смонтировать это под path. |
|||
|
|||
{* ../../docs_src/wsgi/tutorial001.py hl[2:3,3] *} |
|||
|
|||
## Проверьте это |
|||
|
|||
Теперь каждый HTTP-запрос по path `/v1/` будет обработан приложением Flask. |
|||
|
|||
А остальные запросы будут обработаны **FastAPI**. |
|||
|
|||
Если вы запустите его и перейдете по ссылке <a href="http://localhost:8000/v1/" class="external-link" target="_blank">http://localhost:8000/v1/</a>, вы увидите ответ от Flask: |
|||
|
|||
```txt |
|||
Hello, World from Flask! |
|||
``` |
|||
|
|||
И если вы перейдете по ссылке <a href="http://localhost:8000/v2" class="external-link" target="_blank">http://localhost:8000/v2</a>, вы увидите ответ от FastAPI: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World" |
|||
} |
|||
``` |
|||
@ -0,0 +1,17 @@ |
|||
# Развёртывание FastAPI на облачных провайдерах |
|||
|
|||
Вы можете использовать практически **любого облачного провайдера** для развертывания вашего приложения FastAPI. |
|||
|
|||
В большинстве случаев у основных облачных провайдеров есть руководства по развертыванию FastAPI с их помощью. |
|||
|
|||
## Облачные провайдеры - спонсоры |
|||
|
|||
Некоторые облачные провайдеры ✨ [**спонсируют FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, это обеспечивает продолжительное и здоровое **развитие** FastAPI и его **экосистемы**. |
|||
|
|||
Это демонстрирует их настоящую приверженность FastAPI и его **сообществу** (вам), так как они не только хотят предоставить вам **хороший сервис**, но и хотят убедиться, что у вас есть **хороший и здоровый фреймворк**, FastAPI. 🙇 |
|||
|
|||
Возможно, вам захочется попробовать их услуги и следовать их руководствам: |
|||
|
|||
* <a href="https://docs.platform.sh/languages/python.html?utm_source=fastapi-signup&utm_medium=banner&utm_campaign=FastAPI-signup-June-2023" class="external-link" target="_blank">Platform.sh</a> |
|||
* <a href="https://docs.porter.run/language-specific-guides/fastapi" class="external-link" target="_blank">Porter</a> |
|||
* <a href="https://docs.render.com/deploy-fastapi?utm_source=deploydoc&utm_medium=referral&utm_campaign=fastapi" class="external-link" target="_blank">Render</a> |
|||
@ -0,0 +1,137 @@ |
|||
# Воркеры сервера - Uvicorn с воркерами |
|||
|
|||
Давайте снова рассмотрим концепции деплоя: |
|||
|
|||
* Безопасность - HTTPS |
|||
* Запуск при старте |
|||
* Перезапуски |
|||
* **Репликация (количество рабочих процессов)** |
|||
* Память |
|||
* Подготовительные шаги перед запуском |
|||
|
|||
До этого момента, с помощью всех туториалов в документации, вы, вероятно, запускали **серверную программу**, например, используя команду `fastapi`, которая запускает Uvicorn, выполняя **единственный процесс**. |
|||
|
|||
При деплое приложений вы, вероятно, захотите иметь некоторую **репликацию процессов**, чтобы воспользоваться преимуществами **многих ядер** и иметь возможность обрабатывать больше запросов. |
|||
|
|||
Как вы видели в предыдущей главе о [Концепции деплоя](concepts.md){.internal-link target=_blank}, существует множество стратегий, которые вы можете использовать. |
|||
|
|||
Здесь я покажу вам, как использовать **Uvicorn** с **воркер-процессами**, используя команду `fastapi` или непосредственно команду `uvicorn`. |
|||
|
|||
/// info | Информация |
|||
|
|||
Если вы используете контейнеры, например, с Docker или Kubernetes, я расскажу вам больше об этом в следующей главе: [FastAPI в контейнерах - Docker](docker.md){.internal-link target=_blank}. |
|||
|
|||
В частности, работая с **Kubernetes**, вы, вероятно, **не** захотите использовать воркеры, а вместо этого запускать **один процесс Uvicorn в контейнере**, но об этом я расскажу позже в той главе. |
|||
|
|||
/// |
|||
|
|||
## Несколько воркеров |
|||
|
|||
Вы можете запустить несколько воркеров, используя опцию командной строки `--workers`: |
|||
|
|||
//// tab | `fastapi` |
|||
|
|||
Если вы используете команду `fastapi`: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ <font color="#4E9A06">fastapi</font> run --workers 4 <u style="text-decoration-style:solid">main.py</u> |
|||
|
|||
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Запуск продакшн-сервера 🚀 |
|||
|
|||
Поиск структуры файлов пакета в директориях с |
|||
<font color="#3465A4">__init__.py</font> |
|||
Импорт из <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font> |
|||
|
|||
<span style="background-color:#007166"><font color="#D3D7CF"> module </font></span> 🐍 main.py |
|||
|
|||
<span style="background-color:#007166"><font color="#D3D7CF"> code </font></span> Импортирование объекта приложения FastAPI из модуля со следующим кодом: |
|||
|
|||
<u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u> |
|||
|
|||
<span style="background-color:#007166"><font color="#D3D7CF"> app </font></span> Использование строки импорта: <font color="#3465A4">main:app</font> |
|||
|
|||
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Сервер стартовал на <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000</u></font> |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Документация по адресу <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000/docs</u></font> |
|||
|
|||
Логи: |
|||
|
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Uvicorn работает на <font color="#729FCF"><u style="text-decoration-style:solid">http://0.0.0.0:8000</u></font> <b>(</b>Нажмите CTRL+C для выхода<b>)</b> |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Стартовал родительский процесс <b>[</b><font color="#34E2E2"><b>27365</b></font><b>]</b> |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Стартовал серверный процесс <b>[</b><font color="#34E2E2"><b>27368</b></font><b>]</b> |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Стартовал серверный процесс <b>[</b><font color="#34E2E2"><b>27369</b></font><b>]</b> |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Стартовал серверный процесс <b>[</b><font color="#34E2E2"><b>27370</b></font><b>]</b> |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Стартовал серверный процесс <b>[</b><font color="#34E2E2"><b>27367</b></font><b>]</b> |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Ожидание запуска приложения. |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Ожидание запуска приложения. |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Ожидание запуска приложения. |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Ожидание запуска приложения. |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Запуск приложения завершён. |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Запуск приложения завершён. |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Запуск приложения завершён. |
|||
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Запуск приложения завершён. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// |
|||
|
|||
//// tab | `uvicorn` |
|||
|
|||
Если вы предпочитаете использовать команду `uvicorn` напрямую: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 |
|||
<font color="#A6E22E">INFO</font>: Uvicorn работает на <b>http://0.0.0.0:8080</b> (Нажмите CTRL+C для выхода) |
|||
<font color="#A6E22E">INFO</font>: Стартовал родительский процесс [<font color="#A1EFE4"><b>27365</b></font>] |
|||
<font color="#A6E22E">INFO</font>: Стартовал серверный процесс [<font color="#A1EFE4">27368</font>] |
|||
<font color="#A6E22E">INFO</font>: Ожидание запуска приложения. |
|||
<font color="#A6E22E">INFO</font>: Запуск приложения завершён. |
|||
<font color="#A6E22E">INFO</font>: Стартовал серверный процесс [<font color="#A1EFE4">27369</font>] |
|||
<font color="#A6E22E">INFO</font>: Ожидание запуска приложения. |
|||
<font color="#A6E22E">INFO</font>: Запуск приложения завершён. |
|||
<font color="#A6E22E">INFO</font>: Стартовал серверный процесс [<font color="#A1EFE4">27370</font>] |
|||
<font color="#A6E22E">INFO</font>: Ожидание запуска приложения. |
|||
<font color="#A6E22E">INFO</font>: Запуск приложения завершён. |
|||
<font color="#A6E22E">INFO</font>: Стартовал серверный процесс [<font color="#A1EFE4">27367</font>] |
|||
<font color="#A6E22E">INFO</font>: Ожидание запуска приложения. |
|||
<font color="#A6E22E">INFO</font>: Запуск приложения завершён. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// |
|||
|
|||
Единственная новая опция здесь - `--workers`, указывающая Uvicorn запустить 4 воркер-процесса. |
|||
|
|||
Вы также можете увидеть, что отображается **PID** каждого процесса: `27365` для родительского процесса (это **менеджер процессов**) и один для каждого воркер-процесса: `27368`, `27369`, `27370` и `27367`. |
|||
|
|||
## Концепции деплоя |
|||
|
|||
Здесь вы увидели, как использовать несколько **воркеров** для **параллелизации** выполнения приложения, использовать преимущества **многих ядер** процессора и иметь возможность обрабатывать **больше запросов**. |
|||
|
|||
Из списка концепций деплоя, приведённого выше, использование воркеров в основном поможет с **репликацией**, и немного - с **перезапусками**, но вам по-прежнему необходимо позаботиться о следующих вещах: |
|||
|
|||
* **Безопасность - HTTPS** |
|||
* **Запуск при старте** |
|||
* ***Перезапуски*** |
|||
* Репликация (количество рабочих процессов) |
|||
* **Память** |
|||
* **Подготовительные шаги перед запуском** |
|||
|
|||
## Контейнеры и Docker |
|||
|
|||
В следующей главе о [FastAPI в контейнерах - Docker](docker.md){.internal-link target=_blank} я объясню некоторые стратегии, которые вы можете использовать для работы с другими **концепциями деплоя**. |
|||
|
|||
Я покажу вам, как **создать собственный образ с нуля** для запуска одного процесса Uvicorn. Это простой процесс и, вероятно, то, что вы захотите сделать при использовании системы управления распределёнными контейнерами, такой как **Kubernetes**. |
|||
|
|||
## Итог |
|||
|
|||
Вы можете использовать несколько воркер-процессов с опцией `--workers` в CLI с командами `fastapi` или `uvicorn`, чтобы воспользоваться преимуществами **многоядерных процессоров**, для выполнения **нескольких процессов параллельно**. |
|||
|
|||
Вы можете использовать эти инструменты и идеи, если настраиваете **собственную систему деплоя**, одновременно заботясь о других концепциях деплоя самостоятельно. |
|||
|
|||
Изучите следующую главу, чтобы узнать о **FastAPI** с контейнерами (например, Docker и Kubernetes). Вы увидите, что эти инструменты также имеют простые способы решения других **концепций деплоя**. ✨ |
|||
@ -0,0 +1,56 @@ |
|||
# Условный OpenAPI |
|||
|
|||
Если потребуется, вы можете использовать настройки и переменные окружения, чтобы условно настраивать OpenAPI в зависимости от окружения, и даже полностью отключать его. |
|||
|
|||
## О безопасности, API и документации |
|||
|
|||
Скрытие пользовательских интерфейсов вашей документации в продакшне *не должно* быть способом защиты вашего API. |
|||
|
|||
Это не добавляет никакой дополнительной безопасности вашему API, *операции пути* по-прежнему будут доступны там, где они есть. |
|||
|
|||
Если в вашем коде есть уязвимость, она всё равно будет существовать. |
|||
|
|||
Скрытие документации лишь затрудняет понимание того, как взаимодействовать с вашим API, и может усложнить его отладку в продакшне. Это может рассматриваться просто как форма <a href="https://en.wikipedia.org/wiki/Security_through_obscurity" class="external-link" target="_blank">безопасности через неясность</a>. |
|||
|
|||
Если вы хотите защитить ваш API, есть несколько более эффективных подходов: |
|||
|
|||
* Убедитесь, что у вас есть хорошо определённые Pydantic-модели для тел запросов и ответов. |
|||
* Настройте необходимые разрешения и роли с использованием зависимостей. |
|||
* Никогда не храните пароли в открытом виде, только хеши паролей. |
|||
* Реализуйте и используйте известные криптографические инструменты, такие как Passlib и JWT токены и т. д. |
|||
* Добавьте более детальный контроль разрешений с помощью OAuth2 областей, где это необходимо. |
|||
* ...и так далее. |
|||
|
|||
Тем не менее, может быть очень специфический случай, когда вам действительно нужно отключить документацию API для какого-то окружения (например, для продакшна) или в зависимости от настроек из переменных окружения. |
|||
|
|||
## Условный OpenAPI из настроек и переменных окружения |
|||
|
|||
Вы можете легко использовать те же настройки Pydantic для конфигурации вашего сгенерированного OpenAPI и интерфейсов документации. |
|||
|
|||
Например: |
|||
|
|||
{* ../../docs_src/conditional_openapi/tutorial001.py hl[6,11] *} |
|||
|
|||
Здесь мы объявляем настройку `openapi_url` с тем же значением по умолчанию `"/openapi.json"`. |
|||
|
|||
Затем мы используем его при создании приложения `FastAPI`. |
|||
|
|||
Затем вы можете отключить OpenAPI (включая документацию UI) путем установки значения переменной окружения `OPENAPI_URL` в пустую строку, так: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ OPENAPI_URL= uvicorn main:app |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Затем, если вы перейдете по URL-адресам `/openapi.json`, `/docs` или `/redoc`, вы получите ошибку `404 Not Found`, например: |
|||
|
|||
```JSON |
|||
{ |
|||
"detail": "Not Found" |
|||
} |
|||
``` |
|||
@ -0,0 +1,70 @@ |
|||
# Настройка Swagger UI |
|||
|
|||
Вы можете настроить некоторые дополнительные <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">параметры Swagger UI</a>. |
|||
|
|||
Чтобы их настроить, передайте аргумент `swagger_ui_parameters` при создании объекта приложения `FastAPI()` или в функцию `get_swagger_ui_html()`. |
|||
|
|||
`swagger_ui_parameters` принимает словарь с конфигурациями, передаваемыми непосредственно в Swagger UI. |
|||
|
|||
FastAPI преобразует конфигурации в **JSON**, чтобы они были совместимы с JavaScript, так как это нужно для Swagger UI. |
|||
|
|||
## Отключение подсветки синтаксиса |
|||
|
|||
Например, вы можете отключить подсветку синтаксиса в Swagger UI. |
|||
|
|||
Без изменения настроек, подсветка синтаксиса включена по умолчанию: |
|||
|
|||
<img src="/img/tutorial/extending-openapi/image02.png"> |
|||
|
|||
Но вы можете отключить её, установив `syntaxHighlight` в `False`: |
|||
|
|||
{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *} |
|||
|
|||
...и тогда Swagger UI больше не будет отображать подсветку синтаксиса: |
|||
|
|||
<img src="/img/tutorial/extending-openapi/image03.png"> |
|||
|
|||
## Изменение темы |
|||
|
|||
Таким же образом вы можете установить тему подсветки синтаксиса с помощью ключа `"syntaxHighlight.theme"` (обратите внимание, что в нем есть точка): |
|||
|
|||
{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *} |
|||
|
|||
Эта конфигурация изменит цветовую тему подсветки синтаксиса: |
|||
|
|||
<img src="/img/tutorial/extending-openapi/image04.png"> |
|||
|
|||
## Изменение параметров Swagger UI по умолчанию |
|||
|
|||
FastAPI включает некоторые параметры конфигурации по умолчанию, подходящие для большинства случаев использования. |
|||
|
|||
Эти конфигурации по умолчанию включают: |
|||
|
|||
{* ../../fastapi/openapi/docs.py ln[8:23] hl[17:23] *} |
|||
|
|||
Вы можете переопределить любой из них, установив другое значение в аргументе `swagger_ui_parameters`. |
|||
|
|||
Например, чтобы отключить `deepLinking`, вы можете передать эти настройки в `swagger_ui_parameters`: |
|||
|
|||
{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *} |
|||
|
|||
## Другие параметры Swagger UI |
|||
|
|||
Чтобы узнать о всех возможных конфигурациях, которые вы можете использовать, прочитайте официальную <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">документацию по параметрам Swagger UI</a>. |
|||
|
|||
## Настройки только для JavaScript |
|||
|
|||
Swagger UI также позволяет использовать другие конфигурации, представляющие собой **только для JavaScript** объекты (например, функции JavaScript). |
|||
|
|||
FastAPI также включает эти настройки `presets`, предназначенные только для JavaScript: |
|||
|
|||
```JavaScript |
|||
presets: [ |
|||
SwaggerUIBundle.presets.apis, |
|||
SwaggerUIBundle.SwaggerUIStandalonePreset |
|||
] |
|||
``` |
|||
|
|||
Это объекты **JavaScript**, а не строки, поэтому вы не можете передавать их напрямую из кода Python. |
|||
|
|||
Если вам нужно использовать такие настройки, предназначенные только для JavaScript, вы можете использовать один из методов выше. Переопределите все *операции пути* Swagger UI и вручную напишите любой нужный JavaScript. |
|||
@ -0,0 +1,185 @@ |
|||
# Статические ресурсы пользовательского интерфейса для документации (самостоятельный хостинг) |
|||
|
|||
Документация API использует **Swagger UI** и **ReDoc**, и для каждой из них нужны определенные JavaScript и CSS файлы. |
|||
|
|||
По умолчанию эти файлы обслуживаются с <abbr title="Content Delivery Network: сервис, обычно состоящий из нескольких серверов, который предоставляет статические файлы, такие как JavaScript и CSS. Обычно используется для обслуживания этих файлов с сервера, находящегося ближе к клиенту, улучшая производительность.">CDN</abbr>. |
|||
|
|||
Но можно настроить их по-своему, задать определенный CDN или обслуживать файлы самостоятельно. |
|||
|
|||
## Пользовательский CDN для JavaScript и CSS |
|||
|
|||
Допустим, вы хотите использовать другой <abbr title="Content Delivery Network">CDN</abbr>, например, `https://unpkg.com/`. |
|||
|
|||
Это может быть полезно, если, например, вы живете в стране, где ограничивают некоторые URL-адреса. |
|||
|
|||
### Отключите автоматическую документацию |
|||
|
|||
Первый шаг — отключить автоматическую документацию, так как по умолчанию она использует стандартный CDN. |
|||
|
|||
Чтобы отключить их, установите для их URL-адресов значение `None` при создании приложения `FastAPI`: |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial001.py hl[8] *} |
|||
|
|||
### Включите пользовательскую документацию |
|||
|
|||
Теперь вы можете создать *операции пути* для пользовательской документации. |
|||
|
|||
Вы можете повторно использовать внутренние функции FastAPI для создания HTML-страниц для документации и передать им необходимые аргументы: |
|||
|
|||
* `openapi_url`: URL-адрес, где HTML-страница документации может получить OpenAPI-схему для вашего API. Вы можете использовать здесь атрибут `app.openapi_url`. |
|||
* `title`: заголовок вашего API. |
|||
* `oauth2_redirect_url`: здесь вы можете использовать `app.swagger_ui_oauth2_redirect_url`, чтобы воспользоваться значением по умолчанию. |
|||
* `swagger_js_url`: URL-адрес, по которому HTML для ваших документов Swagger UI может получить **JavaScript** файл. Это пользовательский URL-адрес CDN. |
|||
* `swagger_css_url`: URL-адрес, по которому HTML для ваших документов Swagger UI может получить **CSS** файл. Это пользовательский URL-адрес CDN. |
|||
|
|||
И аналогично для ReDoc... |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial001.py hl[2:6,11:19,22:24,27:33] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
*Операция пути* для `swagger_ui_redirect` — это вспомогательная функция, когда вы используете OAuth2. |
|||
|
|||
Если вы интегрируете свой API с провайдером OAuth2, вы сможете пройти аутентификацию и вернуться к документации API с полученными учетными данными. И взаимодействовать с ней, используя настоящую аутентификацию OAuth2. |
|||
|
|||
Swagger UI справится с этим закулисно для вас, но ему нужен этот вспомогательный "редирект". |
|||
|
|||
/// |
|||
|
|||
### Создайте *операцию пути* для тестирования |
|||
|
|||
Теперь, чтобы убедиться, что всё работает, создайте *операцию пути*: |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial001.py hl[36:38] *} |
|||
|
|||
### Проверьте это |
|||
|
|||
Теперь вы должны иметь возможность перейти к вашей документации по адресу <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a> и перезагрузить страницу. Она будет загружать эти ресурсы с нового CDN. |
|||
|
|||
## Самостоятельный хостинг JavaScript и CSS для документации |
|||
|
|||
Самостоятельный хостинг JavaScript и CSS может быть полезен, если, например, вам нужно, чтобы ваше приложение продолжало работать даже в офлайн-режиме, без открытого доступа к Интернету, или в локальной сети. |
|||
|
|||
Здесь вы увидите, как можно обслуживать эти файлы самостоятельно, в том же приложении FastAPI, и настроить документацию для их использования. |
|||
|
|||
### Структура файлов проекта |
|||
|
|||
Допустим, структура файлов вашего проекта выглядит так: |
|||
|
|||
``` |
|||
. |
|||
├── app |
|||
│ ├── __init__.py |
|||
│ ├── main.py |
|||
``` |
|||
|
|||
Теперь создайте каталог для хранения этих статических файлов. |
|||
|
|||
Теперь ваша новая структура файлов может выглядеть так: |
|||
|
|||
``` |
|||
. |
|||
├── app |
|||
│ ├── __init__.py |
|||
│ ├── main.py |
|||
└── static/ |
|||
``` |
|||
|
|||
### Загрузите файлы |
|||
|
|||
Загрузите необходимые статические файлы для документации и разместите их в каталоге `static/`. |
|||
|
|||
Вы можете щелкнуть правой кнопкой мыши по каждой ссылке и выбрать опцию, аналогичную `Сохранить ссылку как...`. |
|||
|
|||
**Swagger UI** использует файлы: |
|||
|
|||
* <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js" class="external-link" target="_blank">`swagger-ui-bundle.js`</a> |
|||
* <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css" class="external-link" target="_blank">`swagger-ui.css`</a> |
|||
|
|||
А **ReDoc** использует файл: |
|||
|
|||
* <a href="https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js" class="external-link" target="_blank">`redoc.standalone.js`</a> |
|||
|
|||
После этого ваша структура файлов может выглядеть следующим образом: |
|||
|
|||
``` |
|||
. |
|||
├── app |
|||
│ ├── __init__.py |
|||
│ ├── main.py |
|||
└── static |
|||
├── redoc.standalone.js |
|||
├── swagger-ui-bundle.js |
|||
└── swagger-ui.css |
|||
``` |
|||
|
|||
### Обслуживание статических файлов |
|||
|
|||
* Импортируйте `StaticFiles`. |
|||
* "Монтируйте" экземпляр `StaticFiles()` на конкретном пути. |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial002.py hl[7,11] *} |
|||
|
|||
### Тестирование статических файлов |
|||
|
|||
Запустите ваше приложение и перейдите на <a href="http://127.0.0.1:8000/static/redoc.standalone.js" class="external-link" target="_blank">http://127.0.0.1:8000/static/redoc.standalone.js</a>. |
|||
|
|||
Вы должны увидеть очень длинный JavaScript файл для **ReDoc**. |
|||
|
|||
Он может начинаться с чего-то вроде: |
|||
|
|||
```JavaScript |
|||
/*! Для информации о лицензии смотрите redoc.standalone.js.LICENSE.txt */ |
|||
!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")): |
|||
... |
|||
``` |
|||
|
|||
Это подтверждает, что вы можете обслуживать статические файлы из вашего приложения, и что вы разместили статические файлы для документации в правильном месте. |
|||
|
|||
Теперь мы можем настроить приложение для использования этих статических файлов для документации. |
|||
|
|||
### Отключите автоматическую документацию для статических файлов |
|||
|
|||
Также как при использовании пользовательского CDN, первый шаг — отключить автоматическую документацию, так как по умолчанию они используют CDN. |
|||
|
|||
Чтобы отключить их, установите для их URL-адресов значение `None` при создании приложения `FastAPI`: |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial002.py hl[9] *} |
|||
|
|||
### Включите пользовательскую документацию для статических файлов |
|||
|
|||
И аналогично предыдущим шагам с пользовательским CDN, теперь вы можете создать *операции пути* для пользовательской документации. |
|||
|
|||
Опять же, вы можете повторно использовать внутренние функции FastAPI для создания HTML-страниц для документации и передать им необходимые аргументы: |
|||
|
|||
* `openapi_url`: URL-адрес, где HTML-страница документации может получить OpenAPI-схему для вашего API. Вы можете использовать здесь атрибут `app.openapi_url`. |
|||
* `title`: заголовок вашего API. |
|||
* `oauth2_redirect_url`: здесь вы можете использовать `app.swagger_ui_oauth2_redirect_url`, чтобы воспользоваться значением по умолчанию. |
|||
* `swagger_js_url`: URL-адрес, по которому HTML для ваших документов Swagger UI может получить **JavaScript** файл. **Это тот файл, который теперь обслуживает ваше приложение**. |
|||
* `swagger_css_url`: URL-адрес, по которому HTML для ваших документов Swagger UI может получить **CSS** файл. **Это тот файл, который теперь обслуживает ваше приложение**. |
|||
|
|||
И аналогично для ReDoc... |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial002.py hl[2:6,14:22,25:27,30:36] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
*Операция пути* для `swagger_ui_redirect` — это вспомогательная функция, когда вы используете OAuth2. |
|||
|
|||
Если вы интегрируете свой API с провайдером OAuth2, вы сможете пройти аутентификацию и вернуться к документации API с полученными учетными данными. И взаимодействовать с ней, используя настоящую аутентификацию OAuth2. |
|||
|
|||
Swagger UI справится с этим закулисно для вас, но ему нужен этот вспомогательный "редирект". |
|||
|
|||
/// |
|||
|
|||
### Создайте *операцию пути* для тестирования статических файлов |
|||
|
|||
Теперь, чтобы убедиться, что всё работает, создайте *операцию пути*: |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *} |
|||
|
|||
### Проверьте пользовательский интерфейс статических файлов |
|||
|
|||
Теперь вы должны иметь возможность отключить WiFi, перейти к вашей документации по адресу <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a> и перезагрузить страницу. |
|||
|
|||
И даже без Интернета вы сможете увидеть документацию для вашего API и взаимодействовать с ней. |
|||
@ -0,0 +1,109 @@ |
|||
# Пользовательские классы Request и APIRoute |
|||
|
|||
В некоторых случаях вам может понадобиться переопределить логику, используемую в классах `Request` и `APIRoute`. |
|||
|
|||
В частности, это может быть хорошей альтернативой логике в middleware (Промежуточный слой). |
|||
|
|||
Например, если вы хотите прочитать или изменить тело запроса до того, как оно будет обработано вашим приложением. |
|||
|
|||
/// danger |
|||
|
|||
Это "продвинутая" функция. |
|||
|
|||
Если вы только начинаете работать с **FastAPI**, вы можете пропустить этот раздел. |
|||
|
|||
/// |
|||
|
|||
## Сценарии использования |
|||
|
|||
Некоторые сценарии использования включают: |
|||
|
|||
* Конвертация тел запросов, не являющихся JSON, в JSON (например, <a href="https://msgpack.org/index.html" class="external-link" target="_blank">`msgpack`</a>). |
|||
* Разжатие тел запросов, сжатых методом gzip. |
|||
* Автоматическое логирование всех тел запросов. |
|||
|
|||
## Обработка пользовательских кодировок тела запроса |
|||
|
|||
Давайте посмотрим, как использовать пользовательский подкласс `Request` для разжатия gzip-запросов. |
|||
|
|||
И подкласс `APIRoute`, чтобы использовать этот пользовательский класс запроса. |
|||
|
|||
### Создание пользовательского класса `GzipRequest` |
|||
|
|||
/// tip | Совет |
|||
|
|||
Это учебный пример, чтобы показать как это работает. Если вам нужна поддержка gzip, вы можете использовать предоставленный [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}. |
|||
|
|||
/// |
|||
|
|||
Сначала мы создадим класс `GzipRequest`, который переопределит метод `Request.body()`, чтобы разжать тело запроса, если присутствует соответствующий заголовок. |
|||
|
|||
Если в заголовке нет `gzip`, он не будет пытаться разжать тело запроса. |
|||
|
|||
Таким образом, один и тот же класс маршрута может обрабатывать как gzip-сжатые, так и несжатые запросы. |
|||
|
|||
{* ../../docs_src/custom_request_and_route/tutorial001.py hl[8:15] *} |
|||
|
|||
### Создание пользовательского класса `GzipRoute` |
|||
|
|||
Затем мы создаем пользовательский подкласс `fastapi.routing.APIRoute`, который будет использовать `GzipRequest`. |
|||
|
|||
На этот раз он переопределит метод `APIRoute.get_route_handler()`. |
|||
|
|||
Этот метод возвращает функцию. И эта функция принимает запрос и возвращает ответ. |
|||
|
|||
Здесь мы используем его для создания `GzipRequest` из исходного запроса. |
|||
|
|||
{* ../../docs_src/custom_request_and_route/tutorial001.py hl[18:26] *} |
|||
|
|||
/// note | Технические детали |
|||
|
|||
`Request` имеет атрибут `request.scope`, который является просто Python-словарем, содержащим метаданные, относящиеся к запросу. |
|||
|
|||
`Request` также имеет `request.receive`, это функция для "получения" тела запроса. |
|||
|
|||
Словарь `scope` и функция `receive` являются частью спецификации ASGI. |
|||
|
|||
И именно эти две вещи, `scope` и `receive`, нужны для создания нового экземпляра `Request`. |
|||
|
|||
Чтобы узнать больше о `Request`, ознакомьтесь с <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">документацией Starlette о запросах</a>. |
|||
|
|||
/// |
|||
|
|||
Единственное, что функция, возвращаемая `GzipRequest.get_route_handler`, делает иначе, это преобразует `Request` в `GzipRequest`. |
|||
|
|||
Таким образом, наш `GzipRequest` позаботится о разжатии данных (если это необходимо) перед передачей их нашим *операциям пути*. |
|||
|
|||
После этого вся логика обработки такая же. |
|||
|
|||
Но благодаря изменениям в `GzipRequest.body`, тело запроса будет автоматически разжиматься, когда **FastAPI** нужно будет его загрузить. |
|||
|
|||
## Доступ к телу запроса в обработчике исключений |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
Чтобы решить эту же проблему, вероятно, гораздо проще использовать `body` в пользовательском обработчике для `RequestValidationError` ([Обработка ошибок](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}). |
|||
|
|||
Но этот пример по-прежнему актуален и показывает, как взаимодействовать с внутренними компонентами. |
|||
|
|||
/// |
|||
|
|||
Мы также можем использовать этот же подход, чтобы получить доступ к телу запроса в обработчике исключений. |
|||
|
|||
Все, что нам нужно сделать, — это обработать запрос внутри блока `try`/`except`: |
|||
|
|||
{* ../../docs_src/custom_request_and_route/tutorial002.py hl[13,15] *} |
|||
|
|||
Если возникает исключение, экземпляр `Request` все равно будет доступен, поэтому мы можем прочитать и использовать тело запроса при обработке ошибки: |
|||
|
|||
{* ../../docs_src/custom_request_and_route/tutorial002.py hl[16:18] *} |
|||
|
|||
## Пользовательский класс `APIRoute` в роутере |
|||
|
|||
Вы также можете установить параметр `route_class` для `APIRouter`: |
|||
|
|||
{* ../../docs_src/custom_request_and_route/tutorial003.py hl[26] *} |
|||
|
|||
В этом примере *операции путей* под `router` будут использовать пользовательский класс `TimedRoute`, и в ответе будет добавлен дополнительный HTTP-заголовок `X-Response-Time` с временем, затраченным на генерацию ответа: |
|||
|
|||
{* ../../docs_src/custom_request_and_route/tutorial003.py hl[13:20] *} |
|||
@ -0,0 +1,80 @@ |
|||
# Расширение OpenAPI |
|||
|
|||
Бывают случаи, когда вам может понадобиться изменить сгенерированную схему OpenAPI. |
|||
|
|||
В этом разделе вы узнаете, как это сделать. |
|||
|
|||
## Обычный процесс |
|||
|
|||
Обычный (по умолчанию) процесс выглядит следующим образом. |
|||
|
|||
Приложение `FastAPI` (экземпляр) имеет метод `.openapi()`, который ожидается вернуть схему OpenAPI. |
|||
|
|||
В рамках создания объекта приложения для `/openapi.json` (или для того, что вы указали в `openapi_url`) регистрируется *операция пути*. |
|||
|
|||
Она просто возвращает JSON ответ с результатом метода `.openapi()` приложения. |
|||
|
|||
По умолчанию метод `.openapi()` проверяет свойство `.openapi_schema`, чтобы увидеть, есть ли в нем содержимое, и возвращает их. |
|||
|
|||
Если его нет, он генерирует его с использованием вспомогательной функции в `fastapi.openapi.utils.get_openapi`. |
|||
|
|||
И эта функция `get_openapi()` принимает в качестве параметров: |
|||
|
|||
* `title`: Заголовок OpenAPI, отображаемый в документации. |
|||
* `version`: Версия вашего API, например `2.5.0`. |
|||
* `openapi_version`: Версия спецификации OpenAPI, используемой. По умолчанию последняя: `3.1.0`. |
|||
* `summary`: Краткое резюме API. |
|||
* `description`: Описание вашего API, оно может включать markdown и будет показано в документации. |
|||
* `routes`: Список маршрутов, это каждая из зарегистрированных *операций пути*. Они берутся из `app.routes`. |
|||
|
|||
/// info | Информация |
|||
|
|||
Параметр `summary` доступен в OpenAPI 3.1.0 и выше, поддерживается FastAPI 0.99.0 и выше. |
|||
|
|||
/// |
|||
|
|||
## Переопределение значений по умолчанию |
|||
|
|||
Используя информацию выше, вы можете использовать ту же вспомогательную функцию для генерации схемы OpenAPI и переопределения каждой части, которая вам нужна. |
|||
|
|||
Например, давайте добавим <a href="https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo" class="external-link" target="_blank">OpenAPI расширение ReDoc для включения настраиваемого логотипа</a>. |
|||
|
|||
### Обычный **FastAPI** |
|||
|
|||
Сначала напишите все ваше приложение на **FastAPI** как обычно: |
|||
|
|||
{* ../../docs_src/extending_openapi/tutorial001.py hl[1,4,7:9] *} |
|||
|
|||
### Генерация схемы OpenAPI |
|||
|
|||
Затем используйте ту же вспомогательную функцию для генерации схемы OpenAPI внутри функции `custom_openapi()`: |
|||
|
|||
{* ../../docs_src/extending_openapi/tutorial001.py hl[2,15:21] *} |
|||
|
|||
### Изменение схемы OpenAPI |
|||
|
|||
Теперь вы можете добавить расширение ReDoc, добавив настраиваемый `x-logo` в "объект" `info` в схеме OpenAPI: |
|||
|
|||
{* ../../docs_src/extending_openapi/tutorial001.py hl[22:24] *} |
|||
|
|||
### Кэширование схемы OpenAPI |
|||
|
|||
Вы можете использовать свойство `.openapi_schema` как "кэш", чтобы сохранить вашу сгенерированную схему. |
|||
|
|||
Таким образом, ваше приложение не будет генерировать схему каждый раз, когда пользователь открывает вашу документацию API. |
|||
|
|||
Она будет сгенерирована только один раз, и затем та же самая кэшированная схема будет использована для следующих запросов. |
|||
|
|||
{* ../../docs_src/extending_openapi/tutorial001.py hl[13:14,25:26] *} |
|||
|
|||
### Переопределение метода |
|||
|
|||
Теперь вы можете заменить метод `.openapi()` на вашу новую функцию. |
|||
|
|||
{* ../../docs_src/extending_openapi/tutorial001.py hl[29] *} |
|||
|
|||
### Проверьте это |
|||
|
|||
Как только вы перейдете по адресу <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>, вы увидите, что вы используете ваш настраиваемый логотип (в этом примере используется логотип **FastAPI**): |
|||
|
|||
<img src="/img/tutorial/extending-openapi/image01.png"> |
|||
@ -0,0 +1,39 @@ |
|||
# Общие сведения - How To - Рецепты |
|||
|
|||
Вот несколько путеводителей на другие части документации для общих или часто задаваемых вопросов. |
|||
|
|||
## Фильтрация данных - Безопасность |
|||
|
|||
Чтобы убедиться, что вы не возвращаете больше данных, чем следует, прочитайте документацию по [Учебнику - Модель ответа - Возвращаемый тип](../tutorial/response-model.md){.internal-link target=_blank}. |
|||
|
|||
## Теги документации - OpenAPI |
|||
|
|||
Чтобы добавить теги к вашим *операциям пути* и сгруппировать их в интерфейсе документации, прочитайте документацию по [Учебнику - Конфигурации операций пути - Теги](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}. |
|||
|
|||
## Краткое описание и описание документации - OpenAPI |
|||
|
|||
Чтобы добавить краткое описание и описание к вашим *операциям пути* и отобразить их в интерфейсе документации, прочитайте документацию по [Учебнику - Конфигурации операций пути - Краткое описание и описание](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}. |
|||
|
|||
## Описание ответа в документации - OpenAPI |
|||
|
|||
Чтобы определить описание ответа, отображаемого в интерфейсе документации, прочитайте документацию по [Учебнику - Конфигурации операций пути - Описание ответа](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}. |
|||
|
|||
## Устаревание *операции пути* в документации - OpenAPI |
|||
|
|||
Чтобы пометить *операцию пути* как устаревшую и отобразить это в интерфейсе документации, прочитайте документацию по [Учебнику - Конфигурации операций пути - Устаревание](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}. |
|||
|
|||
## Преобразование любых данных в совместимые с JSON |
|||
|
|||
Чтобы преобразовать любые данные в совместимые с JSON, прочитайте документацию по [Учебнику - Совместимый кодировщик JSON](../tutorial/encoder.md){.internal-link target=_blank}. |
|||
|
|||
## Метаданные OpenAPI - Документация |
|||
|
|||
Чтобы добавить метаданные в вашу схему OpenAPI, включая лицензию, версию, контактную информацию и т.д., прочитайте документацию по [Учебнику - Метаданные и URL-адреса документации](../tutorial/metadata.md){.internal-link target=_blank}. |
|||
|
|||
## Пользовательский URL OpenAPI |
|||
|
|||
Чтобы кастомизировать (или удалить) URL OpenAPI, прочитайте документацию по [Учебнику - Метаданные и URL-адреса документации](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}. |
|||
|
|||
## URL-адреса документации OpenAPI |
|||
|
|||
Чтобы обновить URL-адреса, используемые для автоматически сгенерированных интерфейсов документации, прочитайте документацию по [Учебнику - Метаданные и URL-адреса документации](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}. |
|||
@ -0,0 +1,60 @@ |
|||
# GraphQL |
|||
|
|||
Так как **FastAPI** основан на стандарте **ASGI**, очень легко интегрировать любую библиотеку **GraphQL**, также совместимую с ASGI. |
|||
|
|||
Вы можете комбинировать обычные *операции пути* FastAPI с GraphQL в одном и том же приложении. |
|||
|
|||
/// tip | Совет |
|||
|
|||
**GraphQL** решает некоторые очень специфические случаи использования. |
|||
|
|||
У него есть **преимущества** и **недостатки** по сравнению с обычными **веб API**. |
|||
|
|||
Убедитесь, что вы оценили, компенсируют ли **выгоды** для вашего случая использования **недостатки**. 🤓 |
|||
|
|||
/// |
|||
|
|||
## Библиотеки GraphQL |
|||
|
|||
Вот некоторые из библиотек **GraphQL**, которые поддерживают **ASGI**. Вы можете использовать их с **FastAPI**: |
|||
|
|||
* <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a> 🍓 |
|||
* С <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">документацией для FastAPI</a> |
|||
* <a href="https://ariadnegraphql.org/" class="external-link" target="_blank">Ariadne</a> |
|||
* С <a href="https://ariadnegraphql.org/docs/fastapi-integration" class="external-link" target="_blank">документацией для FastAPI</a> |
|||
* <a href="https://tartiflette.io/" class="external-link" target="_blank">Tartiflette</a> |
|||
* С <a href="https://tartiflette.github.io/tartiflette-asgi/" class="external-link" target="_blank">Tartiflette ASGI</a> для обеспечения интеграции с ASGI |
|||
* <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a> |
|||
* С <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a> |
|||
|
|||
## GraphQL с использованием Strawberry |
|||
|
|||
Если вам нужно или вы хотите работать с **GraphQL**, библиотека <a href="https://strawberry.rocks/" class="external-link" target="_blank">**Strawberry**</a> является **рекомендуемой**, так как ее дизайн наиболее близок к дизайну **FastAPI**, и всё основано на **аннотациях типов**. |
|||
|
|||
В зависимости от вашего случая использования, вы можете предпочесть другую библиотеку, но если бы вы спросили меня, я бы, вероятно, предложил попробовать **Strawberry**. |
|||
|
|||
Вот небольшой пример того, как можно интегрировать Strawberry с FastAPI: |
|||
|
|||
{* ../../docs_src/graphql/tutorial001.py hl[3,22,25] *} |
|||
|
|||
Вы можете узнать больше о Strawberry в <a href="https://strawberry.rocks/" class="external-link" target="_blank">документации Strawberry</a>. |
|||
|
|||
А также документацию о <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">Strawberry с FastAPI</a>. |
|||
|
|||
## Устаревший `GraphQLApp` от Starlette |
|||
|
|||
В предыдущих версиях Starlette включалась класс `GraphQLApp` для интеграции с <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a>. |
|||
|
|||
Он был исключен из Starlette, но если у вас есть код, который использует его, вы можете легко **мигрировать** на <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a>, который покрывает тот же случай использования и имеет **почти идентичный интерфейс**. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Если вам нужен GraphQL, я всё же рекомендую обратить внимание на <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a>, так как он основан на аннотациях типов, а не на кастомных классах и типах. |
|||
|
|||
/// |
|||
|
|||
## Узнать больше |
|||
|
|||
Вы можете узнать больше о **GraphQL** в <a href="https://graphql.org/" class="external-link" target="_blank">официальной документации GraphQL</a>. |
|||
|
|||
Также вы можете прочитать больше о каждой из описанных выше библиотек по предоставленным ссылкам. |
|||
@ -0,0 +1,13 @@ |
|||
# Как сделать - Рецепты |
|||
|
|||
Здесь вы найдете различные рецепты или руководства "как сделать" для **различных тем**. |
|||
|
|||
Большинство этих идей будут более или менее **независимыми**, и в большинстве случаев вам следует изучать их только в том случае, если они напрямую применимы к **вашему проекту**. |
|||
|
|||
Если что-то кажется интересным и полезным для вашего проекта, смело изучайте это, в противном случае вы можете просто пропустить их. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Если вы хотите **изучить FastAPI** структурированным образом (рекомендуется), прочитайте [Учебник - Руководство пользователя](../tutorial/index.md){.internal-link target=_blank} главу за главой. |
|||
|
|||
/// |
|||
@ -0,0 +1,104 @@ |
|||
# Отдельные схемы OpenAPI для ввода и вывода или нет |
|||
|
|||
При использовании **Pydantic v2** сгенерированный OpenAPI более точный и **правильный**, чем раньше. 😎 |
|||
|
|||
Фактически, в некоторых случаях, будет даже **две схемы JSON** в OpenAPI для одной и той же модели Pydantic: для ввода и вывода, в зависимости от наличия **значений по умолчанию**. |
|||
|
|||
Давайте посмотрим, как это работает и как изменить это, если необходимо. |
|||
|
|||
## Модели Pydantic для ввода и вывода |
|||
|
|||
Предположим, у вас есть модель Pydantic со значениями по умолчанию, как эта: |
|||
|
|||
{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *} |
|||
|
|||
### Модель для ввода |
|||
|
|||
Если использовать эту модель для ввода, как здесь: |
|||
|
|||
{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *} |
|||
|
|||
...то поле `description` **не будет обязательным**. Потому что у него есть значение по умолчанию `None`. |
|||
|
|||
### Модель ввода в документации |
|||
|
|||
Вы можете убедиться в этом, посмотрев документацию: поле `description` не помечено как обязательное **красной звездочкой**: |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image01.png"> |
|||
</div> |
|||
|
|||
### Модель для вывода |
|||
|
|||
Но если использовать ту же модель для вывода, как здесь: |
|||
|
|||
{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py hl[19] *} |
|||
|
|||
...тогда, поскольку `description` имеет значение по умолчанию, если вы **ничего не вернете** для этого поля, оно по-прежнему будет иметь это **значение по умолчанию**. |
|||
|
|||
### Модель для данных ответа |
|||
|
|||
Если вы взаимодействуете с документацией и проверяете ответ, даже если в коде ничего не добавлялось в одно из полей `description`, JSON-ответ содержит значение по умолчанию (`null`): |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image02.png"> |
|||
</div> |
|||
|
|||
Это означает, что у него **всегда будет значение**, просто иногда это значение может быть `None` (или `null` в JSON). |
|||
|
|||
Это значит, что клиенты, использующие ваш API, не должны проверять, существует ли значение, они могут **предполагать, что поле всегда будет**, но в некоторых случаях оно будет иметь значение по умолчанию `None`. |
|||
|
|||
Способ описать это в OpenAPI — отметить это поле как **обязательное**, потому что оно всегда будет присутствовать. |
|||
|
|||
Из-за этого, схема JSON для модели может отличаться в зависимости от того, используется она для **ввода или вывода**: |
|||
|
|||
* для **ввода** `description` **не будет обязательным** |
|||
* для **вывода** оно будет **обязательным** (и возможно `None`, или в терминах JSON, `null`) |
|||
|
|||
### Модель для вывода в документации |
|||
|
|||
Вы также можете проверить модель вывода в документации, **оба** поля `name` и `description` отмечены как **обязательные** с **красной звездочкой**: |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image03.png"> |
|||
</div> |
|||
|
|||
### Модель для ввода и вывода в документации |
|||
|
|||
И если вы проверите все доступные схемы (JSON схемы) в OpenAPI, вы увидите, что их две: `Item-Input` и `Item-Output`. |
|||
|
|||
Для `Item-Input` `description` **не обязателен**, у него нет красной звездочки. |
|||
|
|||
Но для `Item-Output` `description` **обязателен**, у него есть красная звездочка. |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image04.png"> |
|||
</div> |
|||
|
|||
С этой функцией из **Pydantic v2**, ваша документация API более **точная**, и если у вас есть автоматически сгенерированные клиенты и SDK, они будут более точными тоже, с более лучшим **опытом разработчика** и консистентностью. 🎉 |
|||
|
|||
## Не разделять схемы |
|||
|
|||
Теперь, есть случаи, когда вы можете захотеть иметь **одну и ту же схему для ввода и вывода**. |
|||
|
|||
Возможно, основным случаем использования будет, если у вас уже есть какой-то автоматически сгенерированный клиентский код/SDK, и вы не хотите обновлять весь автоматически сгенерированный клиентский код/SDK еще. Вы, вероятно, захотите сделать это в какой-то момент, но, возможно, не прямо сейчас. |
|||
|
|||
В этом случае вы можете отключить эту функцию в **FastAPI** с параметром `separate_input_output_schemas=False`. |
|||
|
|||
/// info | Информация |
|||
|
|||
Поддержка `separate_input_output_schemas` была добавлена в FastAPI в версии `0.102.0`. 🤓 |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/separate_openapi_schemas/tutorial002_py310.py hl[10] *} |
|||
|
|||
### Одинаковая схема для вводных и выводных моделей в документации |
|||
|
|||
И теперь будет одна единственная схема для ввода и вывода для модели, только `Item`, и `description` будет **необязательным**: |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image05.png"> |
|||
</div> |
|||
|
|||
Это такое же поведение, как в Pydantic v1. 🤓 |
|||
@ -0,0 +1,7 @@ |
|||
# Тестирование базы данных |
|||
|
|||
Вы можете изучить базы данных, SQL и SQLModel в <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">документации SQLModel</a>. 🤓 |
|||
|
|||
Есть мини <a href="https://sqlmodel.tiangolo.com/tutorial/fastapi/" class="external-link" target="_blank">учебное пособие по использованию SQLModel с FastAPI</a>. ✨ |
|||
|
|||
Этот учебник включает в себя раздел о <a href="https://sqlmodel.tiangolo.com/tutorial/fastapi/tests/" class="external-link" target="_blank">тестировании SQL баз данных</a>. 😎 |
|||
@ -0,0 +1,3 @@ |
|||
# Ресурсы |
|||
|
|||
Дополнительные ресурсы, внешние ссылки, статьи и другое. ✈️ |
|||
Loading…
Reference in new issue