Sebastián Ramírez
1 week ago
36 changed files with 4071 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 Schema в другом месте вашего OpenAPI вместо того, чтобы включать её напрямую. Таким образом, другие приложения и клиенты могут использовать эти JSON Schema напрямую, предоставлять лучшие инструменты для генерации кода и т.д. |
|||
|
|||
/// |
|||
|
|||
Сгенерированные ответы в OpenAPI для этой *операции пути* будут: |
|||
|
|||
```JSON hl_lines="3-12" |
|||
{ |
|||
"responses": { |
|||
"404": { |
|||
"description": "Additional Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/Message" |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/Item" |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Схемы ссылаются на другое место внутри OpenAPI схемы: |
|||
|
|||
```JSON hl_lines="4-16" |
|||
{ |
|||
"components": { |
|||
"schemas": { |
|||
"Message": { |
|||
"title": "Message", |
|||
"required": [ |
|||
"message" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"message": { |
|||
"title": "Message", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"Item": { |
|||
"title": "Item", |
|||
"required": [ |
|||
"id", |
|||
"value" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"id": { |
|||
"title": "Id", |
|||
"type": "string" |
|||
}, |
|||
"value": { |
|||
"title": "Value", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"ValidationError": { |
|||
"title": "ValidationError", |
|||
"required": [ |
|||
"loc", |
|||
"msg", |
|||
"type" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"loc": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"type": "string" |
|||
} |
|||
}, |
|||
"msg": { |
|||
"title": "Message", |
|||
"type": "string" |
|||
}, |
|||
"type": { |
|||
"title": "Error Type", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"HTTPValidationError": { |
|||
"title": "HTTPValidationError", |
|||
"type": "object", |
|||
"properties": { |
|||
"detail": { |
|||
"title": "Detail", |
|||
"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` определенное фиксированное содержимое. |
|||
|
|||
Но мы хотим иметь возможность параметризовать это фиксированное содержимое. |
|||
|
|||
## Экземпляр "callable" |
|||
|
|||
В Python есть способ сделать экземпляр класса "вызваемым" (callable). |
|||
|
|||
Не сам класс (который уже является вызваемым), а именно экземпляр этого класса. |
|||
|
|||
Для этого мы объявляем метод `__call__`: |
|||
|
|||
{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *} |
|||
|
|||
В этом случае этот `__call__` используется **FastAPI** для проверки дополнительных параметров и подзависимости, и это то, что будет вызвано для передачи значения в параметр в вашей функции *операции пути* позже. |
|||
|
|||
## Параметризация экземпляра |
|||
|
|||
Теперь мы можем использовать `__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, с конфигурацией, которая добавляет дополнительный префикс пути, не видимый вашему приложению. |
|||
|
|||
В таких случаях вы можете использовать `root_path` для настройки вашего приложения. |
|||
|
|||
`root_path` — это механизм, предусмотренный спецификацией ASGI (на которой построен FastAPI через Starlette). |
|||
|
|||
`root_path` используется для обработки этих специфических случаев. |
|||
|
|||
Также он используется внутренне при монтировании подприложений. |
|||
|
|||
## Прокси с обрезанным префиксом пути |
|||
|
|||
Наличие прокси с обрезанным префиксом пути в этом случае означает, что вы можете объявить путь `/app` в вашем коде, но затем добавить слой сверху (прокси), который поместит ваше приложение **FastAPI** под путь вроде `/api/v1`. |
|||
|
|||
В этом случае изначальный путь `/app` на самом деле будет обслуживаться по адресу `/api/v1/app`. |
|||
|
|||
Хотя весь ваш код написан, предполагая, что существует только `/app`. |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial001.py hl[6] *} |
|||
|
|||
И прокси будет **"обрезать"** **префикс пути** на лету перед передачей запроса на сервер приложения (вероятно, через FastAPI CLI через Uvicorn), оставляя ваше приложение уверенным в том, что оно обслуживается по адресу `/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 |
|||
``` |
|||
|
|||
/// tip | Совет |
|||
|
|||
IP `0.0.0.0` обычно используется, чтобы указать, что программа слушает все доступные IP-адреса на этой машине/сервере. |
|||
|
|||
/// |
|||
|
|||
UI документации также будет нужна схема OpenAPI, чтобы указать, что этот API `server` находится по адресу `/api/v1` (за прокси). Например: |
|||
|
|||
```JSON hl_lines="4-8" |
|||
{ |
|||
"openapi": "3.1.0", |
|||
// Другие данные здесь |
|||
"servers": [ |
|||
{ |
|||
"url": "/api/v1" |
|||
} |
|||
], |
|||
"paths": { |
|||
// Другие данные здесь |
|||
} |
|||
} |
|||
``` |
|||
|
|||
В этом примере "Прокси" может быть чем-то вроде **Traefik**. А сервер будет чем-то вроде FastAPI CLI с **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 running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</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 running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Ответ будет таким: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Здравствуй, мир", |
|||
"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": "Здравствуй, мир", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
Таким образом, он не будет ожидать доступа по адресу `http://127.0.0.1:8000/api/v1/app`. |
|||
|
|||
Uvicorn будет ожидать, что прокси будет обращаться к Uvicorn по адресу `http://127.0.0.1:8000/app`, и тогда это будет обязанностью прокси добавить дополнительный префикс `/api/v1` поверх. |
|||
|
|||
## О прокси с обрезанным префиксом пути |
|||
|
|||
Учтите, что использование прокси с обрезанным префиксом пути — это только один из способов его настройки. |
|||
|
|||
Вероятно, в большинстве случаев по умолчанию прокси не будет иметь обрезанного префикса пути. |
|||
|
|||
В таком случае (без обрезанного префикса пути) прокси будет слушать что-то вроде `https://myawesomeapp.com`, и тогда, если браузер зайдет на `https://myawesomeapp.com/api/v1/app`, а ваш сервер (например, Uvicorn) слушает на `http://127.0.0.1:8000`, прокси (без обрезанного префикса пути) будет обращаться к Uvicorn по тому же пути: `http://127.0.0.1:8000/api/v1/app`. |
|||
|
|||
## Тестирование локально с Traefik |
|||
|
|||
Вы можете легко запустить эксперимент локально с обрезанным префиксом пути, используя <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`. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Мы используем порт 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 на использование префикса пути `/api/v1`. |
|||
|
|||
И затем Traefik будет перенаправлять свои запросы на ваш Uvicorn, работающий на `http://127.0.0.1:8000`. |
|||
|
|||
Теперь запустите Traefik: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ ./traefik --configFile=traefik.toml |
|||
|
|||
INFO[0000] Configuration loaded from file: /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 running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</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": "Здравствуй, мир", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
/// tip | Совет |
|||
|
|||
Заметьте, что, хотя вы обращаетесь к нему по адресу `http://127.0.0.1:8000/app`, он показывает `root_path` как `/api/v1`, взятый из параметра `--root-path`. |
|||
|
|||
/// |
|||
|
|||
А теперь откройте URL с портом для Traefik, включая префикс пути: <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": "Здравствуй, мир", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
только на этот раз по адресу URL с префиксом, предоставленным прокси: `/api/v1`. |
|||
|
|||
Конечно, идея в том, чтобы все получали доступ к приложению через прокси, поэтому версия с префиксом пути `/api/v1` является "правильной". |
|||
|
|||
А версия без префикса пути (`http://127.0.0.1:8000/app`), предоставленная напрямую Uvicorn, будет исключительно для доступа _прокси_ (Traefik) к нему. |
|||
|
|||
Это демонстрирует, как прокси (Traefik) использует префикс пути и как сервер (Uvicorn) использует `root_path` из параметра `--root-path`. |
|||
|
|||
### Проверка UI документации |
|||
|
|||
Но вот интересная часть. ✨ |
|||
|
|||
"Официальный" способ доступа к приложению будет через прокси с префиксом пути, который мы определили. Таким образом, как мы и ожидали, если вы попытаетесь использовать UI документации, предоставляемый напрямую Uvicorn, без префикса пути в 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"> |
|||
|
|||
Но если мы получим доступ к UI документации по "официальному" 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`, например, если вы хотите, чтобы *тот же* UI документации взаимодействовал как с окружением для тестирования, так и с производственным окружением. |
|||
|
|||
Если вы передадите кастомный список `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": "Staging environment" |
|||
}, |
|||
{ |
|||
"url": "https://prod.example.com", |
|||
"description": "Production environment" |
|||
} |
|||
], |
|||
"paths": { |
|||
// Другие данные здесь |
|||
} |
|||
} |
|||
``` |
|||
|
|||
/// tip | Совет |
|||
|
|||
Обратите внимание на автоматически сгенерированный сервер с значением `url` `/api/v1`, взятое из `root_path`. |
|||
|
|||
/// |
|||
|
|||
В UI документации по адресу <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"> |
|||
|
|||
/// tip | Совет |
|||
|
|||
UI документации будет взаимодействовать с сервером, который вы выберете. |
|||
|
|||
/// |
|||
|
|||
### Отключить автоматический сервер из `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,312 @@ |
|||
# Пользовательский ответ - HTML, поток, файл и другие |
|||
|
|||
По умолчанию, **FastAPI** будет возвращать ответы, используя `JSONResponse`. |
|||
|
|||
Вы можете переопределить это, возвращая `Response` напрямую, как показано в [Возврат ответа напрямую](response-directly.md){.internal-link target=_blank}. |
|||
|
|||
Но если вы возвращаете `Response` напрямую (или любой подкласс, например, `JSONResponse`), данные не будут автоматически преобразованы (даже если вы объявите `response_model`), и документация не будет автоматически сгенерирована (например, включая конкретный "media type", в 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` также будет использоваться для определения "media type" ответа. |
|||
|
|||
В этом случае, 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` также будет использоваться для определения "media type" ответа. |
|||
|
|||
В этом случае, HTTP заголовок `Content-Type` будет установлен в `text/html`. |
|||
|
|||
И он будет задокументирован как таковой в OpenAPI. |
|||
|
|||
/// |
|||
|
|||
### Возврат `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` |
|||
|
|||
Если вы хотите переопределить ответ внутри функции, но в то же время задокументировать "media type" в 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 для объявления запросов и ответов. |
|||
|
|||
Но 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 будет автоматически преобразован в dataclass Pydantic. |
|||
|
|||
Таким образом, его схема будет отображаться в пользовательском интерфейсе 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` включает в себя список `Item` dataclasses. |
|||
|
|||
4. Dataclass `Author` используется как параметр `response_model`. |
|||
|
|||
5. Вы можете использовать другие стандартные аннотации типов с dataclasses в качестве тела запроса. |
|||
|
|||
В этом случае это список `Item` dataclasses. |
|||
|
|||
6. Здесь мы возвращаем словарь, содержащий `items`, который представляет собой список dataclasses. |
|||
|
|||
FastAPI все еще способен <abbr title="преобразовать данные в формат, который может быть передан">сериализовать</abbr> данные в JSON. |
|||
|
|||
7. Здесь `response_model` использует аннотацию типа списка `Author` dataclasses. |
|||
|
|||
Опять же, вы можете сочетать `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 @@ |
|||
# События жизненного цикла |
|||
|
|||
Вы можете определить логику (код), которая должна выполняться перед тем, как приложение **запустится**. Это означает, что этот код будет выполнен **один раз**, **до** того как приложение **начнет принимать запросы**. |
|||
|
|||
Таким же образом, вы можете определить логику (код), которая должна выполняться при **завершении работы** приложения. В этом случае этот код будет выполнен **один раз**, **после** обработки возможных **многочисленных запросов**. |
|||
|
|||
Так как этот код выполняется до того, как приложение **начнет** принимать запросы, и сразу после того как оно **закончит** их обрабатывать, он покрывает весь **жизненный цикл** приложения (слово "жизненный цикл" будет важно через секунду 😉). |
|||
|
|||
Это может быть очень полезно для настройки **ресурсов**, которые вам нужно использовать для всего приложения, и которые **разделяются** между запросами, и/или которые нужно **очистить** впоследствии. Например, пул соединений с базой данных или загрузка общего алгоритма машинного обучения. |
|||
|
|||
## Пример использования |
|||
|
|||
Начнем с примера **использования**, а затем посмотрим, как это решить. |
|||
|
|||
Представьте, что у вас есть несколько **моделей машинного обучения**, которые вы хотите использовать для обработки запросов. 🤖 |
|||
|
|||
Эти же модели разделяются между запросами, так что это не одна модель на запрос или одна на пользователя или что-то подобное. |
|||
|
|||
Представьте, что загрузка модели может **занимать довольно много времени**, потому что ей нужно прочесть много **данных с диска**. Поэтому вы не хотите делать это для каждого запроса. |
|||
|
|||
Вы могли бы загрузить её на верхнем уровне модуля/файла, но это также означало бы, что модель будет **загружена**, даже если вы просто запускаете простой автоматический тест, и тогда этот тест будет **медленным**, потому что ему придется ждать загрузки модели перед выполнением независимой части кода. |
|||
|
|||
Вот это мы и решим: загрузим модель перед обработкой запросов, но только прямо перед тем, как приложение начнёт принимать запросы, а не во время загрузки кода. |
|||
|
|||
## Жизненный цикл |
|||
|
|||
Вы можете определить логику для *запуска* и *завершения работы* с использованием параметра `lifespan` приложения `FastAPI` и "контекстного менеджера" (я покажу вам, что это такое, через секунду). |
|||
|
|||
Начнем с примера, а затем рассмотрим его подробно. |
|||
|
|||
Мы создаем асинхронную функцию `lifespan()` с использованием `yield`, как показано ниже: |
|||
|
|||
{* ../../docs_src/events/tutorial003.py hl[16,19] *} |
|||
|
|||
Здесь мы симулируем дорогую *операцию старта* загрузки модели, помещая (фейковую) функцию модели в словарь с моделями машинного обучения до `yield`. Этот код будет выполнен **до** того, как приложение **начнет принимать запросы**, в момент *старта*. |
|||
|
|||
А затем, сразу после `yield`, мы выгружаем модель. Этот код будет выполнен **после** того, как приложение **закончит обрабатывать запросы**, прямо перед *завершением работы*. Это может, например, освободить такие ресурсы, как память или GPU. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Завершение работы происходит, когда вы **останавливаете** приложение. |
|||
|
|||
Возможно, вам нужно запустить новую версию или вы просто устали его запускать. 🤷 |
|||
|
|||
/// |
|||
|
|||
### Функция жизненного цикла |
|||
|
|||
Первое, на что стоит обратить внимание, это то, что мы определяем асинхронную функцию с `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">оглашения Жизненного Цикла</a>, и она определяет события `startup` и `shutdown`. |
|||
|
|||
/// info | Информация |
|||
|
|||
Вы можете прочитать больше о обработчиках `lifespan` в Starlette в <a href="https://www.starlette.io/lifespan/" class="external-link" target="_blank">документации Starlette's Lifespan</a>. |
|||
|
|||
В том числе то, как справляться с состоянием жизненного цикла, которое может быть использовано в других областях вашего кода. |
|||
|
|||
/// |
|||
|
|||
## Подпрограммы |
|||
|
|||
🚨 Помните, что эти события жизненного цикла (startup и shutdown) будут выполнены только для основного приложения, а не для [Подпрограмм - Монтирования](sub-applications.md){.internal-link target=_blank}. |
|||
@ -0,0 +1,261 @@ |
|||
# Генерация клиентов |
|||
|
|||
Так как **FastAPI** основан на спецификации OpenAPI, вы получаете автоматическую совместимость со многими инструментами, включая автоматическую документацию API (предоставленную Swagger UI). |
|||
|
|||
Одним из преимуществ, не всегда очевидных, является возможность **генерировать клиентов** (иногда их называют <abbr title="Software Development Kits">**SDK**</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 использует **уникальный идентификатор** для каждой *операции пути*, он используется для **идентификатора операции**, а также для имен необходимых пользовательских моделей, для запросов или ответов. |
|||
|
|||
Вы можете настроить эту функцию. Она принимает `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 прямо перед генерацией клиентов, чтобы сделать имена методов более красивыми и **чистыми**. |
|||
|
|||
Мы могли бы загрузить JSON OpenAPI в файл `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 |
|||
|
|||
В основном учебнике вы прочитали, как добавить [Custom Middleware](../tutorial/middleware.md){.internal-link target=_blank} в ваше приложение. |
|||
|
|||
Также вы узнали, как обрабатывать [CORS с помощью `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}. |
|||
|
|||
В этой секции мы рассмотрим, как использовать другие middlewares. |
|||
|
|||
## Добавление ASGI middlewares |
|||
|
|||
Так как **FastAPI** основан на Starlette и реализует спецификацию <abbr title="Asynchronous Server Gateway Interface">ASGI</abbr>, вы можете использовать любое ASGI middleware. |
|||
|
|||
Middleware не обязательно должен быть создан для FastAPI или Starlette, чтобы работать, до тех пор, пока он следует спецификации ASGI. |
|||
|
|||
В общем, ASGI middlewares - это классы, которые ожидают получить ASGI приложение в качестве первого аргумента. |
|||
|
|||
Таким образом, в документации для сторонних ASGI middlewares вероятно, вас попросят сделать что-то похожее на: |
|||
|
|||
```Python |
|||
from unicorn import UnicornMiddleware |
|||
|
|||
app = SomeASGIApp() |
|||
|
|||
new_app = UnicornMiddleware(app, some_config="rainbow") |
|||
``` |
|||
|
|||
Но FastAPI (на самом деле Starlette) предоставляет более простой способ сделать это, который гарантирует, что внутренние middleware будут правильно обрабатывать ошибки сервера и пользовательские обработчики исключений. |
|||
|
|||
Для этого используйте `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. |
|||
|
|||
## Встроенные middlewares |
|||
|
|||
**FastAPI** включает несколько middlewares для общих случаев использования, дальше мы рассмотрим как их использовать. |
|||
|
|||
/// note | Технические детали |
|||
|
|||
Для следующих примеров вы также могли бы использовать `from starlette.middleware.something import SomethingMiddleware`. |
|||
|
|||
**FastAPI** предоставляет несколько middlewares в `fastapi.middleware` просто для вашего удобства, как разработчика. Но большинство доступных middlewares приходят непосредственно из Starlette. |
|||
|
|||
/// |
|||
|
|||
## `HTTPSRedirectMiddleware` |
|||
|
|||
Обеспечивает, чтобы все входящие запросы были либо `https`, либо `wss`. |
|||
|
|||
Любой входящий запрос на `http` или `ws` будет перенаправлен на защищённую схему. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *} |
|||
|
|||
## `TrustedHostMiddleware` |
|||
|
|||
Обеспечивает, чтобы все входящие запросы имели правильно установленный заголовок `Host`, чтобы защититься от атак посредством подмены заголовка HTTP Host. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *} |
|||
|
|||
Поддерживаются следующие аргументы: |
|||
|
|||
* `allowed_hosts` - Список доменных имён, которые должны быть разрешены в качестве имён хоста. Поддерживаются подстановочные домены, такие как `*.example.com`, для совпадения с поддоменами. Чтобы разрешить любое имя хоста, либо используйте `allowed_hosts=["*"]`, либо пропустите middleware. |
|||
|
|||
Если входящий запрос проходит проверку неправильно, то будет отправлен ответ `400`. |
|||
|
|||
## `GZipMiddleware` |
|||
|
|||
Обрабатывает GZip ответы для любого запроса, который включает `"gzip"` в заголовке `Accept-Encoding`. |
|||
|
|||
Middleware обрабатывает как стандартные, так и потоковые ответы. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *} |
|||
|
|||
Поддерживаются следующие аргументы: |
|||
|
|||
* `minimum_size` - Не использовать GZip для ответов, размер которых меньше этого минимума в байтах. По умолчанию `500`. |
|||
* `compresslevel` - Используется во время GZip сжатия. Это целое число в диапазоне от 1 до 9. Значение по умолчанию `9`. Меньшее значение приводит к более быстрому сжатию, но большим размерам файлов, в то время как большее значение приводит к более медленному сжатию, но меньшим размерам файлов. |
|||
|
|||
## Другие middlewares |
|||
|
|||
Существует много других ASGI middlewares. |
|||
|
|||
Например: |
|||
|
|||
* <a href="https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py" class="external-link" target="_blank">Uvicorn's `ProxyHeadersMiddleware`</a> |
|||
* <a href="https://github.com/florimondmanca/msgpack-asgi" class="external-link" target="_blank">MessagePack</a> |
|||
|
|||
Чтобы увидеть другие доступные middlewares, ознакомьтесь с <a href="https://www.starlette.io/middleware/" class="external-link" target="_blank">документацией по Middlewares от Starlette</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 *должен* выглядеть. Какие *операции пути* он должен иметь, какое тело ожидать, какой ответ должен возвращать и т. д. |
|||
|
|||
## Приложение с обратными вызовами |
|||
|
|||
Давайте посмотрим на всё это на примере. |
|||
|
|||
Представьте, что вы разрабатываете приложение, которое позволяет создавать счета-фактуры. |
|||
|
|||
Эти счета-фактуры будут иметь `id`, `title` (необязательно), `customer` и `total`. |
|||
|
|||
Пользователь вашего API (внешний разработчик) создаст счет-фактуру в вашем API с помощью POST-запроса. |
|||
|
|||
Затем ваше API (давайте представим): |
|||
|
|||
* Отправит счет некоторому клиенту внешнего разработчика. |
|||
* Соберет деньги. |
|||
* Отправит уведомление обратно пользователю API (внешнему разработчику). |
|||
* Это будет сделано путем отправки POST-запроса (из *вашего API*) на какой-то *внешний API*, предоставленный тем внешним разработчиком (это и есть "обратный вызов"). |
|||
|
|||
## Обычное приложение **FastAPI** |
|||
|
|||
Давайте сначала посмотрим, как будет выглядеть обычное API-приложение до добавления обратного вызова. |
|||
|
|||
Оно будет иметь *операцию пути*, которая будет получать тело `Invoice`, и параметр запроса `callback_url`, который будет содержать URL для обратного вызова. |
|||
|
|||
Эта часть довольно обычная, большая часть кода, вероятно, уже знакома вам: |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Параметр запроса `callback_url` использует тип Pydantic <a href="https://docs.pydantic.dev/latest/api/networks/" class="external-link" target="_blank">Url</a>. |
|||
|
|||
/// |
|||
|
|||
Единственное, что ново, это `callbacks=invoices_callback_router.routes` в качестве аргумента для декоратора *операции пути*. Мы посмотрим, что это такое дальше. |
|||
|
|||
## Документирование обратного вызова |
|||
|
|||
Фактический код обратного вызова будет сильно зависеть от вашего собственного API-приложения. |
|||
|
|||
И, вероятно, будет значительно отличаться для разных приложений. |
|||
|
|||
Это может быть всего одна или две строчки кода, например: |
|||
|
|||
```Python |
|||
callback_url = "https://example.com/api/v1/invoices/events/" |
|||
httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) |
|||
``` |
|||
|
|||
Но, возможно, самая важная часть обратного вызова — это убедиться, что пользователь вашего API (внешний разработчик) корректно реализует *внешний API*, в соответствии с данными, которые *ваше API* собирается отправить в теле запроса для обратного вызова и т. д. |
|||
|
|||
Таким образом, что мы собираемся сделать дальше, это добавить код для документирования того, как этот *внешний API* должен выглядеть, чтобы принимать обратный вызов от *вашего API*. |
|||
|
|||
Эта документация будет отображаться в Swagger UI по адресу `/docs` в вашем API и она позволит внешним разработчикам знать, как построить *внешний API*. |
|||
|
|||
Этот пример не реализует сам обратный вызов (это может быть всего одна строка кода), только часть документации. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Фактический обратный вызов — это просто HTTP-запрос. |
|||
|
|||
При самостоятельной реализации обратного вызова вы можете использовать что-то вроде <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>. |
|||
|
|||
/// |
|||
|
|||
## Написание кода документации для обратного вызова |
|||
|
|||
Этот код не будет выполняться в вашем приложении, нам он нужен только для того, чтобы *документировать*, как этот *внешний API* должен выглядеть. |
|||
|
|||
Но вы уже знаете, как легко создать автоматическую документацию для API с использованием **FastAPI**. |
|||
|
|||
Итак, мы собираемся использовать эти знания, чтобы задокументировать, как *внешний API* должен выглядеть... создав *операции пути*, которые внешний API должен реализовать (те, которые ваше API будет вызывать). |
|||
|
|||
/// tip | Совет |
|||
|
|||
При написании кода для документирования обратного вызова может быть полезно представить, что вы — это тот *внешний разработчик*. И что вы в данный момент реализуете *внешний API*, а не *ваше API*. |
|||
|
|||
Временное принятие этой точки зрения (внешнего разработчика) может помочь вам почувствовать, что более очевидно, где разместить параметры, модель Pydantic для тела, для ответа и т. д. для этого *внешнего API*. |
|||
|
|||
/// |
|||
|
|||
### Создание `APIRouter` для обратного вызова |
|||
|
|||
Сначала создайте новый `APIRouter`, который будет содержать один или несколько обратных вызовов. |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *} |
|||
|
|||
### Создание *операции пути* для обратного вызова |
|||
|
|||
Чтобы создать *операцию пути* для обратного вызова, используйте тот же `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*. |
|||
|
|||
### Выражение пути обратного вызова |
|||
|
|||
*Путь* обратного вызова может содержать <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_url` (во *внешний API*): |
|||
|
|||
``` |
|||
https://www.external.org/events/invoices/2expen51ve |
|||
``` |
|||
|
|||
с JSON-телом, содержащим что-то вроде: |
|||
|
|||
```JSON |
|||
{ |
|||
"description": "Payment celebration", |
|||
"paid": true |
|||
} |
|||
``` |
|||
|
|||
и оно будет ожидать ответ от этого *внешнего API* с JSON-телом как: |
|||
|
|||
```JSON |
|||
{ |
|||
"ok": true |
|||
} |
|||
``` |
|||
|
|||
/// tip | Совет |
|||
|
|||
Обратите внимание, как URL для обратного вызова содержит URL, полученный в виде параметра запроса в `callback_url` (`https://www.external.org/events`) и также `id` счета-фактуры из JSON-тела (`2expen51ve`). |
|||
|
|||
/// |
|||
|
|||
### Добавление маршрутизатора для обратных вызовов |
|||
|
|||
На этом этапе у вас есть нужные *операции пути для обратных вызовов* (те, которые *внешний разработчик* должен реализовать во *внешнем API*) в созданном выше маршрутизаторе для обратных вызовов. |
|||
|
|||
Теперь используйте параметр `callbacks` в *декораторе операции пути вашего API*, чтобы передать атрибут `.routes` (на самом деле это просто `list` маршрутов/*операций путей*) из этого маршрутизатора для обратных вызовов: |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *} |
|||
|
|||
/// tip | Совет |
|||
|
|||
Обратите внимание, что вы передаете не сам маршрутизатор (`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 Вебхуки |
|||
|
|||
Существуют случаи, когда вы хотите сообщить вашим **пользователям API**, что ваше приложение может вызвать *их* приложение (отправив запрос) с некоторыми данными, обычно чтобы **уведомить** о каком-то типе **события**. |
|||
|
|||
Это означает, что вместо обычного процесса, когда ваши пользователи отправляют запросы вашему API, это **ваш API** (или ваше приложение), который может **отправлять запросы их системе** (их API, их приложению). |
|||
|
|||
Обычно это называется **вебхук**. |
|||
|
|||
## Шаги вебхуков |
|||
|
|||
Процесс обычно заключается в том, что **вы определяете** в своем коде, какое сообщение вы будете отправлять, **тело запроса**. |
|||
|
|||
Вы также каким-то образом определяете, в какие **моменты** ваше приложение будет отправлять эти запросы или события. |
|||
|
|||
А **ваши пользователи** каким-то образом (например, в веб-интерфейсе где-то) определяют **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** схеме и в автоматическом **документированном интерфейсе**. |
|||
|
|||
/// info | Информация |
|||
|
|||
Объект `app.webhooks` на самом деле просто `APIRouter`, тот же тип, который вы бы использовали при структурировании вашего приложения с несколькими файлами. |
|||
|
|||
/// |
|||
|
|||
Обратите внимание, что с вебхуками вы на самом деле не объявляете *путь* (как `/items/`), текст, который вы передаете, является просто **идентификатором** вебхука (именем события), например, в `@app.webhooks.post("new-subscription")` имя вебхука - `new-subscription`. |
|||
|
|||
Это потому, что предполагается, что **ваши пользователи** будут определять фактический **путь 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/openapi-webhooks/image01.png"> |
|||
@ -0,0 +1,204 @@ |
|||
# Расширенная конфигурация операций пути |
|||
|
|||
## OpenAPI operationId |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
Если вы не "эксперт" в OpenAPI, вам, вероятно, это не нужно. |
|||
|
|||
/// |
|||
|
|||
Вы можете установить OpenAPI `operationId` для использования в вашей *операции пути* с параметром `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] *} |
|||
|
|||
## Расширенное описание из docstring |
|||
|
|||
Вы можете ограничить строки, используемые из docstring функции *операции пути* для OpenAPI. |
|||
|
|||
Добавление `\f` (экранированный символ "form feed") приводит к тому, что **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 Extra |
|||
|
|||
Когда вы объявляете *операцию пути* в своем приложении, **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">Operation Object</a>. |
|||
|
|||
/// |
|||
|
|||
Он содержит всю информацию о *операции пути* и используется для генерации автоматической документации. |
|||
|
|||
Он включает `tags`, `parameters`, `requestBody`, `responses` и т. д. |
|||
|
|||
Эта OpenAPI схема, специфичная для *операции пути*, обычно генерируется автоматически **FastAPI**, но вы также можете расширить ее. |
|||
|
|||
/// tip | Совет |
|||
|
|||
Это низкоуровневая точка расширения. |
|||
|
|||
Если вам нужно только объявить дополнительные ответы, более удобный способ сделать это — с [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. |
|||
|
|||
/// |
|||
|
|||
Вы можете расширить схему OpenAPI для *операции пути* с помощью параметра `openapi_extra`. |
|||
|
|||
### Расширения OpenAPI |
|||
|
|||
Этот `openapi_extra` может быть полезен, например, для объявления [OpenAPI Extensions](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 Schema, которое затем включается в пользовательскую секцию OpenAPI схемы для *операции пути*. |
|||
|
|||
И вы могли бы сделать это, даже если тип данных в запросе не является JSON. |
|||
|
|||
Например, в этом приложении мы не используем интегрированную функциональность FastAPI для извлечения JSON Schema из моделей 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 Schema для модели назывался `Item.schema()`, в версии Pydantic 2 этот метод называется `Item.model_json_schema()`. |
|||
|
|||
/// |
|||
|
|||
Тем не менее, хотя мы и не используем стандартную интегрированную функциональность, мы все равно используем модель Pydantic для ручной генерации JSON Schema для данных, которые мы хотим получить в формате 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 @@ |
|||
# Заголовки ответов |
|||
|
|||
## Используйте параметр `Response` |
|||
|
|||
Вы можете объявить параметр типа `Response` в вашей *функции обработки пути* (как вы можете сделать для cookies). |
|||
|
|||
А затем вы можете установить заголовки в этом *временном* объекте ответа. |
|||
|
|||
{* ../../docs_src/response_headers/tutorial002.py hl[1, 7:8] *} |
|||
|
|||
И затем вы можете вернуть любой объект, который вам нужен, как вы обычно делаете (например, `dict`, модель базы данных и т.д.). |
|||
|
|||
И если вы объявили `response_model`, он все равно будет использован для фильтрации и конвертации объекта, который вы вернули. |
|||
|
|||
**FastAPI** использует этот *временный* ответ для извлечения заголовков (а также cookies и кода состояния) и помещает их в окончательный ответ, содержащий значение, которое вы вернули, отфильтрованное с помощью любого `response_model`. |
|||
|
|||
Вы также можете объявить параметр `Response` в зависимостях и установить заголовки (и cookies) в них. |
|||
|
|||
## Возврат `Response` напрямую |
|||
|
|||
Вы также можете добавить заголовки, когда возвращаете `Response` напрямую. |
|||
|
|||
Создайте ответ, как описано в разделе [Return a Response Directly](response-directly.md){.internal-link target=_blank} и передайте заголовки в качестве дополнительного параметра: |
|||
|
|||
{* ../../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` может часто использоваться для установки заголовков и cookies, **FastAPI** также предоставляет его в `fastapi.Response`. |
|||
|
|||
/// |
|||
|
|||
## Пользовательские заголовки |
|||
|
|||
Имейте в виду, что пользовательские проприетарные заголовки могут быть добавлены <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 Базовая Аутентификация |
|||
|
|||
Для самых простых случаев вы можете использовать HTTP Базовую Аутентификацию. |
|||
|
|||
В HTTP Базовой Аутентификации, приложение ожидает заголовок, содержащий имя пользователя и пароль. |
|||
|
|||
Если оно не получает его, то возвращает ошибку HTTP 401 "Unauthorized". |
|||
|
|||
Также возвращается заголовок `WWW-Authenticate` со значением `Basic` и необязательный параметр `realm`. |
|||
|
|||
Это сообщает браузеру показать встроенное окно запроса имени пользователя и пароля. |
|||
|
|||
Затем, когда вы вводите это имя пользователя и пароль, браузер отправляет их в заголовке автоматически. |
|||
|
|||
## Простая HTTP Базовая Аутентификация |
|||
|
|||
* Импортируйте `HTTPBasic` и `HTTPBasicCredentials`. |
|||
* Создайте "`сущность` схемы безопасности" с использованием `HTTPBasic`. |
|||
* Используйте эту `схему безопасности` с зависимостью в вашем *путевом обработчике*. |
|||
* Это возвращает объект типа `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"): |
|||
# Возвращаем какую-то ошибку |
|||
... |
|||
``` |
|||
|
|||
Но, используя `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 области |
|||
|
|||
Вы можете использовать OAuth2 области непосредственно с **FastAPI**, они интегрированы для бесшовной работы. |
|||
|
|||
Это позволит вам иметь более детализированную систему разрешений, следуя стандарту OAuth2, интегрированному в ваше приложение OpenAPI (и API-документацию). |
|||
|
|||
OAuth2 с областями — это механизм, используемый многими крупными поставщиками аутентификации, такими как Facebook, Google, GitHub, Microsoft, Twitter и др. Они используют его, чтобы предоставить пользователям и приложениям доступ к определённым разрешениям. |
|||
|
|||
Каждый раз, когда вы "входите через" Facebook, Google, GitHub, Microsoft, Twitter, это приложение использует OAuth2 с областями. |
|||
|
|||
В этом разделе вы узнаете, как управлять аутентификацией и авторизацией с помощью тех же OAuth2 областей в вашем приложении на **FastAPI**. |
|||
|
|||
/// warning | Предупреждение |
|||
|
|||
Это более или менее продвинутый раздел. Если вы только начинаете, вы можете его пропустить. |
|||
|
|||
Вам не обязательно нужны OAuth2 области, и вы можете обрабатывать аутентификацию и авторизацию так, как вам удобно. |
|||
|
|||
Но OAuth2 с областями можно красиво интегрировать в ваш API (с OpenAPI) и в вашу API-документацию. |
|||
|
|||
Тем не менее, вы всё равно соблюдаете эти области или любое другое требование безопасности/авторизации, как вам нужно, в вашем коде. |
|||
|
|||
Во многих случаях, OAuth2 с областями может быть излишен. |
|||
|
|||
Но если вы знаете, что он вам нужен, или вы просто любопытны, продолжайте читать. |
|||
|
|||
/// |
|||
|
|||
## OAuth2 области и OpenAPI |
|||
|
|||
Спецификация OAuth2 определяет "области" как список строк, разделённых пробелами. |
|||
|
|||
Содержимое каждой из этих строк может иметь любой формат, но не должно содержать пробелов. |
|||
|
|||
Эти области представляют собой "разрешения". |
|||
|
|||
В OpenAPI (например, в API-документации) вы можете определить "схемы безопасности". |
|||
|
|||
Когда одна из этих схем безопасности использует OAuth2, вы также можете определить и использовать области. |
|||
|
|||
Каждая "область" — это просто строка (без пробелов). |
|||
|
|||
Они обычно используются для определения конкретных разрешений безопасности, например: |
|||
|
|||
* `users:read` или `users:write` — это общие примеры. |
|||
* `instagram_basic` используется Facebook / Instagram. |
|||
* `https://www.googleapis.com/auth/drive` используется Google. |
|||
|
|||
/// info | Информация |
|||
|
|||
В OAuth2 "область" — это просто строка, которая декларирует необходимое специфическое разрешение. |
|||
|
|||
Неважно, есть ли у неё другие символы, такие как `:`, или если это URL. |
|||
|
|||
Эти детали зависят от реализации. |
|||
|
|||
Для OAuth2 они просто строки. |
|||
|
|||
/// |
|||
|
|||
## Глобальный обзор |
|||
|
|||
Во-первых, быстро рассмотрим части, которые изменяются в примерах в основном **Учебнике - Руководстве пользователя** для [OAuth2 с паролем (и хешированием), носитель с JWT токенами](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Теперь используя OAuth2 области: |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:125,129:135,140,156] *} |
|||
|
|||
Теперь давайте рассмотрим эти изменения шаг за шагом. |
|||
|
|||
## Схема безопасности OAuth2 |
|||
|
|||
Первое изменение заключается в том, что теперь мы объявляем схему безопасности OAuth2 с двумя доступными областями, `me` и `items`. |
|||
|
|||
Параметр `scopes` принимает `dict` с каждой областью в качестве ключа и описанием в качестве значения: |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *} |
|||
|
|||
Поскольку мы теперь объявляем эти области, они будут отображаться в API-документации, когда вы войдете/авторизуетесь. |
|||
|
|||
И вы сможете выбрать, к каким областям вы хотите предоставить доступ: `me` и `items`. |
|||
|
|||
Это тот же механизм, который используется при предоставлении разрешений при входе через Facebook, Google, GitHub и т.д.: |
|||
|
|||
<img src="/img/tutorial/security/image11.png"> |
|||
|
|||
## JWT токен с областями |
|||
|
|||
Теперь измените *path operation*, чтобы вернуть запрошенные области. |
|||
|
|||
Мы всё ещё используем тот же `OAuth2PasswordRequestForm`. Он включает собственность `scopes` со `списком` `str`, с каждой областью, полученной в запросе. |
|||
|
|||
И мы возвращаем области как часть JWT токена. |
|||
|
|||
/// danger | Опасность |
|||
|
|||
Для простоты, здесь мы просто добавляем области, полученные напрямую в токен. |
|||
|
|||
Но в вашем приложении, для безопасности, вы должны убедиться, что добавляете только те области, которые пользователь действительно может иметь, или те, которые вы предопределили. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *} |
|||
|
|||
## Объявление областей в *path operations* и зависимостях |
|||
|
|||
Теперь мы объявляем, что *path operation* для `/users/me/items/` требует область `items`. |
|||
|
|||
Для этого мы импортируем и используем `Security` из `fastapi`. |
|||
|
|||
Вы можете использовать `Security` для объявления зависимостей (так же, как `Depends`), но `Security` также получает параметр `scopes` со списком областей (строк). |
|||
|
|||
В этом случае мы передаем функцию зависимости `get_current_active_user` в `Security` (так же, как мы бы делали с `Depends`). |
|||
|
|||
Но мы также передаем `список` областей, в этом случае только одну область: `items` (их могло бы быть больше). |
|||
|
|||
И функция зависимости `get_current_active_user` также может объявлять подзависимости, не только с помощью `Depends`, но и с помощью `Security`. Объявляя свою подзависимую функцию (`get_current_user`), и дополнительные требования к областям. |
|||
|
|||
В этом случае требуется область `me` (могло бы требоваться более одной области). |
|||
|
|||
/// note | Примечание |
|||
|
|||
Вам не обязательно нужно добавлять разные области в разных местах. |
|||
|
|||
Мы делаем это здесь, чтобы продемонстрировать, как **FastAPI** обрабатывает области, объявленные на разных уровнях. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *} |
|||
|
|||
/// info | Технические детали |
|||
|
|||
`Security` на самом деле является подклассом `Depends`, и имеет только один дополнительный параметр, который мы увидим позже. |
|||
|
|||
Но используя `Security` вместо `Depends`, **FastAPI** распознает, что можно объявлять области безопасности, использовать их внутри и документировать API с помощью OpenAPI. |
|||
|
|||
Но когда вы импортируете `Query`, `Path`, `Depends`, `Security` и другие из `fastapi`, это на самом деле функции, которые возвращают специальные классы. |
|||
|
|||
/// |
|||
|
|||
## Использование `SecurityScopes` |
|||
|
|||
Теперь обновите зависимость `get_current_user`. |
|||
|
|||
Эта функция используется приведёнными выше зависимостями. |
|||
|
|||
Здесь мы используем ту же схему OAuth2, которую создали ранее, объявляя её как зависимость: `oauth2_scheme`. |
|||
|
|||
Поскольку эта функция зависимости сама по себе не имеет требований к областям, мы можем использовать `Depends` с `oauth2_scheme`, нам не нужно использовать `Security`, когда нам не нужно указывать области безопасности. |
|||
|
|||
Мы также объявляем специальный параметр типа `SecurityScopes`, импортированный из `fastapi.security`. |
|||
|
|||
Этот класс `SecurityScopes` аналогичен `Request` (в `Request` использовался объект запроса напрямую). |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *} |
|||
|
|||
## Используйте `scopes` |
|||
|
|||
Параметр `security_scopes` будет типа `SecurityScopes`. |
|||
|
|||
Он будет иметь свойство `scopes` со списком всех областей, требуемых самой функцией и всеми зависимостями, использующими её как подзависимость. Это значит, все "зависящие"... это может звучать запутанно, ниже объясняется подробнее. |
|||
|
|||
Объект `security_scopes` (класса `SecurityScopes`) также предоставляет атрибут `scope_str` с одной строкой, содержащей эти области, разделённые пробелами (мы его используем). |
|||
|
|||
Мы создаём `HTTPException`, который можем использовать (`raise`) позже в некоторых точках. |
|||
|
|||
В этом исключении мы включаем требуемые области (если они есть) в виде строки, разделённой пробелами (используя `scope_str`). Мы помещаем эту строку, содержащую области, в заголовок `WWW-Authenticate` (это часть спецификации). |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *} |
|||
|
|||
## Проверка `username` и формы данных |
|||
|
|||
Мы проверяем, что получили `username`, и извлекаем области. |
|||
|
|||
А затем мы валидируем эти данные с помощью модели Pydantic (отлавливая исключение `ValidationError`), и если у нас есть ошибка чтения JWT токена или валидирования данных с помощью Pydantic, мы возбуждаем созданное ранее `HTTPException`. |
|||
|
|||
Для этого мы обновляем модель Pydantic `TokenData`, добавив новое свойство `scopes`. |
|||
|
|||
Валидируя данные с помощью Pydantic, мы можем убедиться, что у нас есть, например, именно `список` `str` с областями и `str` с `username`. |
|||
|
|||
Вместо, например, `dict`, или чего-то ещё, что могло бы в какой-то момент сломать приложение, создавая риск безопасности. |
|||
|
|||
Мы также проверяем, что у нас есть пользователь с этим именем пользователя, и если нет, мы возбуждаем то же исключение, которое создали ранее. |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:128] *} |
|||
|
|||
## Проверка `scopes` |
|||
|
|||
Теперь проверяем, что все области, требуемые этой зависимостью и всеми зависимыми (включая *path operations*), включены в области, предоставленные в полученном токене, в противном случае возбуждаем `HTTPException`. |
|||
|
|||
Для этого используем `security_scopes.scopes`, который содержит `список` со всеми этими областями как `str`. |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[129:135] *} |
|||
|
|||
## Дерево зависимостей и области |
|||
|
|||
Давайте снова рассмотрим это дерево зависимостей и области. |
|||
|
|||
Поскольку зависимость `get_current_active_user` имеет подзависимость `get_current_user`, область `"me"`, объявленная в `get_current_active_user`, будет включена в `список` требуемых областей в `security_scopes.scopes`, переданный `get_current_user`. |
|||
|
|||
*Path operation* также объявляет область, `"items"`, так что это тоже будет в `списке` `security_scopes.scopes`, переданный `get_current_user`. |
|||
|
|||
Вот как выглядит иерархия зависимостей и областей: |
|||
|
|||
* *Path operation* `read_own_items` имеет: |
|||
* Требуемые области `["items"]` с зависимостью: |
|||
* `get_current_active_user`: |
|||
* Функция зависимости `get_current_active_user` имеет: |
|||
* Требуемые области `["me"]` с зависимостью: |
|||
* `get_current_user`: |
|||
* Функция зависимости `get_current_user` имеет: |
|||
* Нет требуемых собственной области. |
|||
* Зависимость, использующую `oauth2_scheme`. |
|||
* Параметр `security_scopes` типа `SecurityScopes`: |
|||
* Этот параметр `security_scopes` имеет свойство `scopes` с `списком`, содержащим все выше указанные области, так что: |
|||
* `security_scopes.scopes` будет содержать `["me", "items"]` для *path operation* `read_own_items`. |
|||
* `security_scopes.scopes` будет содержать `["me"]` для *path operation* `read_users_me`, потому что она объявлена в зависимости `get_current_active_user`. |
|||
* `security_scopes.scopes` будет содержать `[]` (ничего) для *path operation* `read_system_status`, потому что она не объявляет никакой `Security` с `scopes`, а её зависимость `get_current_user` также не объявляет никаких `scopes`. |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
Самое важное и "магическое" здесь то, что `get_current_user` будет иметь различный список `scopes` для проверки для каждого *path operation*. |
|||
|
|||
Всё зависит от `scopes`, объявленных в каждом *path operation* и каждой зависимости в дереве зависимостей для этого конкретного *path operation*. |
|||
|
|||
/// |
|||
|
|||
## Больше деталей об `SecurityScopes` |
|||
|
|||
Вы можете использовать `SecurityScopes` в любой точке, и в нескольких местах, не обязательно на "корневой" зависимости. |
|||
|
|||
Оно всегда будет иметь области безопасности, объявленные в текущих `Security` зависимостях и все зависимые для **этого конкретного** *path operation* и **этого конкретного** дерева зависимостей. |
|||
|
|||
Поскольку `SecurityScopes` будут иметь все области, объявленные зависимыми, вы можете использовать его для проверки, что токен имеет требуемые области в центральной функции зависимости, а затем объявить различные требования к областям в различных *path operations*. |
|||
|
|||
Они будут проверяться независимо для каждого *path operation*. |
|||
|
|||
## Проверьте это |
|||
|
|||
Если откроете API-документацию, вы можете пройти аутентификацию и указать, какие области хотите авторизовать. |
|||
|
|||
<img src="/img/tutorial/security/image11.png"> |
|||
|
|||
Если вы не выберете ни одной области, вы будете "аутентифицированы", но при попытке получить доступ к `/users/me/` или `/users/me/items/` вы получите ошибку, говоря, что у вас недостаточно разрешений. Вы всё ещё сможете получить доступ к `/status/`. |
|||
|
|||
И если вы выберете область `me`, но не `items`, вы сможете получить доступ к `/users/me/`, но не к `/users/me/items/`. |
|||
|
|||
Вот что произойдёт с приложениями третьих сторон, которые пытались бы получить доступ к одной из этих *path operations* с токеном, предоставленным пользователем, в зависимости от того, сколько разрешений пользователь дал приложению. |
|||
|
|||
## О сторонних интеграциях |
|||
|
|||
В этом примере мы используем "парольный" поток OAuth2. |
|||
|
|||
Это уместно, когда мы входим в наше собственное приложение, вероятно, с нашим собственным интерфейсом. |
|||
|
|||
Потому что мы можем доверять ему получение `username` и `password`, так как мы его контролируем. |
|||
|
|||
Но если вы создаёте OAuth2 приложение, к которому будут подключаться другие (то есть, если вы создаёте поставщика аутентификации, эквивалентного Facebook, Google, GitHub и т.д.), вы должны использовать один из других потоков. |
|||
|
|||
Наиболее распространенный — это неявный поток. |
|||
|
|||
Наиболее безопасный — это поток с кодом, но его сложнее реализовать, так как он требует больше шагов. Из-за сложности многие провайдеры в конечном итоге рекомендуют неявный поток. |
|||
|
|||
/// note | Примечание |
|||
|
|||
Часто каждый поставщик аутентификации называет свои потоки по-разному, чтобы сделать это частью их бренда. |
|||
|
|||
Но в конце концов, они реализуют тот же стандарт OAuth2. |
|||
|
|||
/// |
|||
|
|||
**FastAPI** включает утилиты для всех этих потоков аутентификации OAuth2 в `fastapi.security.oauth2`. |
|||
|
|||
## `Security` в бедператора `dependencies` |
|||
|
|||
Так же, как вы можете определить `список` `Depends` в параметре `dependencies` там бедператора (как объясняется в [Зависимости в бедператорaх path operation](../../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> |
|||
|
|||
Он также включен при установке `all`-дополнений с: |
|||
|
|||
<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()` — это обычная функция. |
|||
|
|||
/// |
|||
|
|||
И затем мы можем требовать его из функции обработчика *path operation* в качестве зависимости и использовать его везде, где это необходимо. |
|||
|
|||
{* ../../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) support</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: Concepts: Configuration</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 Model Config</a>. |
|||
|
|||
/// |
|||
|
|||
//// |
|||
|
|||
/// info | Информация |
|||
|
|||
В версии Pydantic 1 настройка осуществлялась во внутреннем классе `Config`, в версии Pydantic 2 это делается в атрибуте `model_config`. Этот атрибут принимает `dict`, и чтобы получить автозаполнение и inline ошибки, вы можете импортировать и использовать `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 Code |
|||
participant function as say_hi() |
|||
participant execute as Execute function |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> execute: execute function code |
|||
execute ->> code: return the result |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> code: return stored result |
|||
end |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Rick") |
|||
function ->> execute: execute function code |
|||
execute ->> code: return the result |
|||
end |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Rick", salutation="Mr.") |
|||
function ->> execute: execute function code |
|||
execute ->> code: return the result |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Rick") |
|||
function ->> code: return stored result |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> code: return stored result |
|||
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 @@ |
|||
# Подприложения - Монтирование |
|||
|
|||
Если вам нужно иметь два независимых приложения FastAPI, каждое со своей независимой OpenAPI и собственным интерфейсом документации, вы можете создать основное приложение и "монтировать" одно (или несколько) подпрограмм. |
|||
|
|||
## Монтирование приложения **FastAPI** |
|||
|
|||
"Монтирование" означает добавление полностью "независимого" приложения в определенный путь, которое будет обрабатывать все запросы, поступающие по этому пути, с _operations path_, объявленными в этом подприложении. |
|||
|
|||
### Приложение верхнего уровня |
|||
|
|||
Сначала создайте главное приложение верхнего уровня **FastAPI** и его *operations path*: |
|||
|
|||
{* ../../docs_src/sub_applications/tutorial001.py hl[3, 6:8] *} |
|||
|
|||
### Подприложение |
|||
|
|||
Затем создайте свое подприложение и его *operations path*. |
|||
|
|||
Это подприложение является просто еще одним стандартным приложением FastAPI, но именно оно будет "смонтировано": |
|||
|
|||
{* ../../docs_src/sub_applications/tutorial001.py hl[11, 14:16] *} |
|||
|
|||
### Монтирование подприложения |
|||
|
|||
В вашем приложении верхнего уровня `app` смонтируйте подприложение `subapi`. |
|||
|
|||
В этом случае оно будет смонтировано по пути `/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 для основного приложения, содержащую только его _operations path_: |
|||
|
|||
<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 для подприложения, содержащую только его _operations path_, все с правильным префиксом подпути `/subapi`: |
|||
|
|||
<img src="/img/tutorial/sub-applications/image02.png"> |
|||
|
|||
Если вы попробуете взаимодействовать с любым из этих двух пользовательских интерфейсов, они будут работать корректно, потому что браузер сможет общаться с каждым определенным приложением или подприложением. |
|||
|
|||
### Технические детали: `root_path` |
|||
|
|||
Когда вы монтируете подприложение, как описано выше, FastAPI позаботится о передаче пути монтирования для подприложения с использованием механизма из спецификации ASGI, называемого `root_path`. |
|||
|
|||
Таким образом, подприложение будет знать об использовании этого префикса пути для интерфейса документации. |
|||
|
|||
И подприложение также может иметь свои собственные смонтированные подприложения и все будет работать корректно, так как FastAPI автоматически обрабатывает все эти `root_path`. |
|||
|
|||
Вы узнаете больше о `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`, передавая имя шаблона, объект запроса и "контекст" — словарь с парами ключ-значение, которые будут использоваться внутри шаблона 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`, взятый из "контекста" `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`) запускались в тестах, вы можете использовать `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 напрямую |
|||
|
|||
До сих пор вы объявляли части запроса, которые вам нужны, с указанием их типов. |
|||
|
|||
Получение данных из: |
|||
|
|||
* Параметров пути. |
|||
* Заголовков. |
|||
* Куки. |
|||
* и т.д. |
|||
|
|||
И при этом **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 | Совет |
|||
|
|||
Обратите внимание, что в этом случае мы объявляем параметр пути рядом с параметром запроса. |
|||
|
|||
Таким образом, параметр пути будет извлечен, проверен, преобразован в указанный тип и аннотирован с 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 - Mounts](sub-applications.md){.internal-link target=_blank}, [Behind a Proxy](behind-a-proxy.md){.internal-link target=_blank}. |
|||
|
|||
Для этого вы можете использовать `WSGIMiddleware` и использовать его для обёртки вашего WSGI-приложения, например, Flask, Django и т. д. |
|||
|
|||
## Использование `WSGIMiddleware` |
|||
|
|||
Вам нужно импортировать `WSGIMiddleware`. |
|||
|
|||
Затем оберните WSGI (например, Flask) приложение с помощью middleware. |
|||
|
|||
И затем смонтируйте его под определённым путём. |
|||
|
|||
{* ../../docs_src/wsgi/tutorial001.py hl[2:3,3] *} |
|||
|
|||
## Проверка |
|||
|
|||
Теперь каждый запрос по пути `/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,139 @@ |
|||
# Серверные Рабочие Процессы - 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**. |
|||
|
|||
## Итоги |
|||
|
|||
Вы можете использовать несколько рабочих процессов с помощью опции CLI `--workers` с командами `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, как эти, вы можете использовать один из методов, упомянутых выше. Переопределите всю *path operation* Swagger UI и вручную напишите любой необходимый JavaScript. |
|||
@ -0,0 +1,185 @@ |
|||
# Пользовательские статические ресурсы Docs UI (самостоятельный хостинг) |
|||
|
|||
API документация использует **Swagger UI** и **ReDoc**, и каждому из них требуются некоторые файлы JavaScript и CSS. |
|||
|
|||
По умолчанию эти файлы предоставляются через <abbr title="Сеть доставки контента: служба, обычно состоящая из нескольких серверов, которая предоставляет статические файлы, такие как JavaScript и CSS. Обычно используется для доставки этих файлов с сервера, наиболее близкого к клиенту, что улучшает производительность.">CDN</abbr>. |
|||
|
|||
Но возможно его настроить: можно установить определенный CDN или разместить файлы самостоятельно. |
|||
|
|||
## Пользовательский CDN для JavaScript и CSS |
|||
|
|||
Предположим, что вы хотите использовать другой <abbr title="Сеть доставки контента">CDN</abbr>, например, хотите использовать `https://unpkg.com/`. |
|||
|
|||
Это может быть полезно, если, например, вы живете в стране, где некоторые URL-адреса ограничены. |
|||
|
|||
### Отключение автоматической документации |
|||
|
|||
Первый шаг — отключить автоматическую документацию, так как по умолчанию они используют стандартный CDN. |
|||
|
|||
Чтобы отключить их, установите их URL в `None` при создании вашего приложения `FastAPI`: |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial001.py hl[8] *} |
|||
|
|||
### Включение пользовательской документации |
|||
|
|||
Теперь вы можете создать *path operations* для пользовательской документации. |
|||
|
|||
Вы можете повторно использовать внутренние функции 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 | Совет |
|||
|
|||
*Path operation* для `swagger_ui_redirect` является помощником, когда вы используете OAuth2. |
|||
|
|||
Если вы интегрируете свой API с провайдером OAuth2, вы сможете авторизоваться и вернуться к документации API с полученными учетными данными. И взаимодействовать с ним, используя реальную аутентификацию через OAuth2. |
|||
|
|||
Swagger UI сделает это для вас за кулисами, но для этого нужен этот помощник "перенаправления". |
|||
|
|||
/// |
|||
|
|||
### Создание *path operation* для его тестирования |
|||
|
|||
Теперь, чтобы проверить, что все работает, создайте *path operation*: |
|||
|
|||
{* ../../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 |
|||
/*! For license information please see 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, теперь вы можете создать *path operations* для пользовательской документации. |
|||
|
|||
Снова можно использовать внутренние функции 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 | Совет |
|||
|
|||
*Path operation* для `swagger_ui_redirect` является помощником, когда вы используете OAuth2. |
|||
|
|||
Если вы интегрируете свой API с провайдером OAuth2, вы сможете авторизоваться и вернуться к документации API с полученными учетными данными. И взаимодействовать с ним, используя реальную аутентификацию через OAuth2. |
|||
|
|||
Swagger UI сделает это для вас за кулисами, но для этого нужен этот помощник "перенаправления". |
|||
|
|||
/// |
|||
|
|||
### Создание *path operation* для тестирования статических файлов |
|||
|
|||
Теперь, чтобы убедиться, что все работает, создайте *path operation*: |
|||
|
|||
{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *} |
|||
|
|||
### Тестирование статических файлов UI |
|||
|
|||
Теперь вы должны иметь возможность отключить Wi-Fi, перейти на свою документацию по адресу <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 @@ |
|||
# Классы кастомных запросов и 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 `dict`, содержащий метаданные, связанные с запросом. |
|||
|
|||
`Request` также имеет `request.receive`, это функция для "получения" тела запроса. |
|||
|
|||
`scope` `dict` и функция `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` и добавят в ответ заголовок `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 @@ |
|||
# Общие - Как сделать - Рецепты |
|||
|
|||
Вот несколько указателей на другие места в документации для общих или частых вопросов. |
|||
|
|||
## Фильтрация данных - Безопасность |
|||
|
|||
Чтобы убедиться, что вы не возвращаете больше данных, чем следует, прочитайте документацию [Учебник - Модель ответа - Возвращаемый тип](../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 немного более точен и **правилен**, чем раньше. 😎 |
|||
|
|||
Фактически, в некоторых случаях, для одной и той же модели Pydantic в OpenAPI даже будет **две схемы JSON** — для ввода и вывода, в зависимости от того, имеют ли они **значения по умолчанию**. |
|||
|
|||
Посмотрим, как это работает, и как изменить это, если вам нужно это сделать. |
|||
|
|||
## 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