mirror of https://github.com/tiangolo/fastapi.git
202 lines
16 KiB
Markdown
202 lines
16 KiB
Markdown
# Возможности { #features }
|
||
|
||
## Возможности FastAPI { #fastapi-features }
|
||
|
||
**FastAPI** предлагает вам следующее:
|
||
|
||
### Основано на открытых стандартах { #based-on-open-standards }
|
||
|
||
* <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank"><strong>OpenAPI</strong></a> для создания API, включая объявления <abbr title="также известные как HTTP-методы, например: POST, GET, PUT, DELETE">операций</abbr> <abbr title="также известен как: эндпоинты, маршруты)">пути</abbr>, параметров, тел запросов, безопасности и т. д.
|
||
* Автоматическая документация моделей данных с помощью <a href="https://json-schema.org/" class="external-link" target="_blank"><strong>JSON Schema</strong></a> (так как сама спецификация OpenAPI основана на JSON Schema).
|
||
* Разработан вокруг этих стандартов, после тщательного их изучения. Это не дополнительная надстройка поверх.
|
||
* Это также позволяет использовать автоматическую **генерацию клиентского кода** на многих языках.
|
||
|
||
### Автоматическая документация { #automatic-docs }
|
||
|
||
Интерактивная документация для API и исследовательские веб-интерфейсы. Поскольку фреймворк основан на OpenAPI, существует несколько вариантов документирования, 2 из них включены по умолчанию.
|
||
|
||
* <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank"><strong>Swagger UI</strong></a>, с интерактивным исследованием, вызовом и тестированием вашего API прямо из браузера.
|
||
|
||
|
||
|
||
* Альтернативная документация API в <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank"><strong>ReDoc</strong></a>.
|
||
|
||
|
||
|
||
### Только современный Python { #just-modern-python }
|
||
|
||
Все основано на стандартных **аннотациях типов Python** (благодаря Pydantic). Не нужно изучать новый синтаксис. Только стандартный современный Python.
|
||
|
||
Если вам нужно освежить знания о типах в Python (даже если вы не используете FastAPI), выделите 2 минуты и просмотрите краткое руководство: [Типы Python](python-types.md){.internal-link target=_blank}.
|
||
|
||
Вы пишете стандартный Python с типами:
|
||
|
||
```Python
|
||
from datetime import date
|
||
|
||
from pydantic import BaseModel
|
||
|
||
# Объявляем параметр как `str`
|
||
# и получаем поддержку редактора кода внутри функции
|
||
def main(user_id: str):
|
||
return user_id
|
||
|
||
|
||
# Модель Pydantic
|
||
class User(BaseModel):
|
||
id: int
|
||
name: str
|
||
joined: date
|
||
```
|
||
|
||
Это можно использовать так:
|
||
|
||
```Python
|
||
my_user: User = User(id=3, name="John Doe", joined="2018-07-19")
|
||
|
||
second_user_data = {
|
||
"id": 4,
|
||
"name": "Mary",
|
||
"joined": "2018-11-30",
|
||
}
|
||
|
||
my_second_user: User = User(**second_user_data)
|
||
```
|
||
|
||
/// info | Информация
|
||
|
||
`**second_user_data` означает:
|
||
|
||
Передать ключи и значения словаря `second_user_data` в качестве аргументов "ключ-значение", эквивалентно: `User(id=4, name="Mary", joined="2018-11-30")`
|
||
|
||
///
|
||
|
||
### Поддержка редакторов (IDE) { #editor-support }
|
||
|
||
Весь фреймворк был продуман так, чтобы быть простым и интуитивно понятным в использовании, все решения были проверены на множестве редакторов еще до начала разработки, чтобы обеспечить наилучшие условия при написании кода.
|
||
|
||
В опросах Python‑разработчиков видно, <a href="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features" class="external-link" target="_blank">что одной из самых часто используемых функций является «автозавершение»</a>.
|
||
|
||
Вся структура **FastAPI** основана на удовлетворении этой возможности. Автозавершение работает везде.
|
||
|
||
Вам редко нужно будет возвращаться к документации.
|
||
|
||
Вот как ваш редактор может вам помочь:
|
||
|
||
* в <a href="https://code.visualstudio.com/" class="external-link" target="_blank">Visual Studio Code</a>:
|
||
|
||
|
||
|
||
* в <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>:
|
||
|
||
|
||
|
||
Вы будете получать автозавершение кода даже там, где вы считали это невозможным раньше. Как пример, ключ `price` внутри тела JSON (который может быть вложенным), приходящего в запросе.
|
||
|
||
Больше никаких неправильных имён ключей, метания по документации или прокручивания кода вверх и вниз в попытках узнать — использовали вы ранее `username` или `user_name`.
|
||
|
||
### Краткость { #short }
|
||
|
||
FastAPI имеет продуманные значения **по умолчанию** для всего, с опциональными настройками везде. Все параметры могут быть тонко подстроены так, чтобы делать то, что вам нужно, и определять необходимый вам API.
|
||
|
||
Но по умолчанию всё **«просто работает»**.
|
||
|
||
### Проверка значений { #validation }
|
||
|
||
* Проверка значений для большинства (или всех?) **типов данных** Python, включая:
|
||
* Объекты JSON (`dict`).
|
||
* Массив JSON (`list`) с определёнными типами элементов.
|
||
* Строковые (`str`) поля с ограничением минимальной и максимальной длины.
|
||
* Числа (`int`, `float`) с минимальными и максимальными значениями и т. п.
|
||
|
||
* Проверка для более экзотических типов, таких как:
|
||
* URL.
|
||
* Email.
|
||
* UUID.
|
||
* ...и другие.
|
||
|
||
Все проверки обрабатываются хорошо зарекомендовавшим себя и надёжным **Pydantic**.
|
||
|
||
### Безопасность и аутентификация { #security-and-authentication }
|
||
|
||
Встроенные функции безопасности и аутентификации. Без каких‑либо компромиссов с базами данных или моделями данных.
|
||
|
||
Все схемы безопасности, определённые в OpenAPI, включая:
|
||
|
||
* HTTP Basic.
|
||
* **OAuth2** (также с **токенами JWT**). Ознакомьтесь с руководством [OAuth2 с JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}.
|
||
* Ключи API в:
|
||
* Заголовках.
|
||
* Параметрах запросов.
|
||
* Cookies и т.п.
|
||
|
||
Вдобавок все функции безопасности от Starlette (включая **сессионные cookies**).
|
||
|
||
Все инструменты и компоненты спроектированы для многократного использования и легко интегрируются с вашими системами, хранилищами данных, реляционными и NoSQL базами данных и т. д.
|
||
|
||
### Внедрение зависимостей { #dependency-injection }
|
||
|
||
FastAPI включает в себя чрезвычайно простую в использовании, но чрезвычайно мощную систему <abbr title='известную как: "components", "resources", "services", "providers"'><strong>Внедрения зависимостей</strong></abbr>.
|
||
|
||
* Даже зависимости могут иметь зависимости, создавая иерархию или **«граф» зависимостей**.
|
||
* Всё **автоматически обрабатывается** фреймворком.
|
||
* Все зависимости могут запрашивать данные из запросов и **дополнять операции пути** ограничениями и автоматической документацией.
|
||
* **Автоматическая проверка** даже для параметров *операций пути*, определённых в зависимостях.
|
||
* Поддержка сложных систем аутентификации пользователей, **соединений с базами данных** и т. д.
|
||
* **Никаких компромиссов** с базами данных, интерфейсами и т. д. Но при этом — лёгкая интеграция со всеми ними.
|
||
|
||
### Нет ограничений на "Плагины" { #unlimited-plug-ins }
|
||
|
||
Или, другими словами, нет необходимости в них — просто импортируйте и используйте нужный вам код.
|
||
|
||
Любая интеграция разработана настолько простой в использовании (с зависимостями), что вы можете создать «плагин» для своего приложения в пару строк кода, используя ту же структуру и синтаксис, что и для ваших *операций пути*.
|
||
|
||
### Проверен { #tested }
|
||
|
||
* 100% <abbr title="Количество автоматически проверяемого кода">покрытие тестами</abbr>.
|
||
* 100% <abbr title="Аннотации типов Python, благодаря которым ваш редактор и внешние инструменты могут обеспечить вам лучшую поддержку">аннотирование типов</abbr> в кодовой базе.
|
||
* Используется в продакшн‑приложениях.
|
||
|
||
## Возможности Starlette { #starlette-features }
|
||
|
||
**FastAPI** основан на <a href="https://www.starlette.dev/" class="external-link" target="_blank"><strong>Starlette</strong></a> и полностью совместим с ним. Так что любой дополнительный код Starlette, который у вас есть, также будет работать.
|
||
|
||
На самом деле, `FastAPI` — это подкласс `Starlette`. Таким образом, если вы уже знаете или используете Starlette, большая часть функционала будет работать так же.
|
||
|
||
С **FastAPI** вы получаете все возможности **Starlette** (так как FastAPI — это всего лишь Starlette на стероидах):
|
||
|
||
* Серьёзно впечатляющая производительность. Это <a href="https://github.com/encode/starlette#performance" class="external-link" target="_blank">один из самых быстрых фреймворков на Python, наравне с **NodeJS** и **Go**</a>.
|
||
* Поддержка **WebSocket**.
|
||
* Фоновые задачи в том же процессе.
|
||
* События запуска и выключения.
|
||
* Тестовый клиент построен на HTTPX.
|
||
* **CORS**, GZip, статические файлы, потоковые ответы.
|
||
* Поддержка **сессий и cookie**.
|
||
* 100% покрытие тестами.
|
||
* 100% аннотирование типов в кодовой базе.
|
||
|
||
## Возможности Pydantic { #pydantic-features }
|
||
|
||
**FastAPI** полностью совместим с (и основан на) <a href="https://docs.pydantic.dev/" class="external-link" target="_blank"><strong>Pydantic</strong></a>. Поэтому любой дополнительный код Pydantic, который у вас есть, также будет работать.
|
||
|
||
Включая внешние библиотеки, также основанные на Pydantic, такие как <abbr title="Object-Relational Mapper">ORM</abbr>’ы, <abbr title="Object-Document Mapper">ODM</abbr>’ы для баз данных.
|
||
|
||
Это также означает, что во многих случаях вы можете передавать тот же объект, который получили из запроса, **непосредственно в базу данных**, так как всё проверяется автоматически.
|
||
|
||
И наоборот, во многих случаях вы можете просто передать объект, полученный из базы данных, **непосредственно клиенту**.
|
||
|
||
С **FastAPI** вы получаете все возможности **Pydantic** (так как FastAPI основан на Pydantic для обработки данных):
|
||
|
||
* **Никакой нервотрёпки**:
|
||
* Не нужно изучать новые схемы в микроязыках.
|
||
* Если вы знаете типы в Python, вы знаете, как использовать Pydantic.
|
||
* Прекрасно сочетается с вашим **<abbr title="Integrated Development Environment - Интегрированная среда разработки: попросту «редактора кода»">IDE</abbr>/<abbr title="Программа, проверяющая ошибки в коде">linter</abbr>/мозгом**:
|
||
* Потому что структуры данных pydantic — это всего лишь экземпляры классов, определённых вами; автозавершение, проверка кода, mypy и ваша интуиция — всё будет работать с вашими валидированными данными.
|
||
* Валидация **сложных структур**:
|
||
* Использование иерархических моделей Pydantic; `List`, `Dict` и т. п. из модуля `typing` (входит в стандартную библиотеку Python).
|
||
* Валидаторы позволяют чётко и легко определять, проверять и документировать сложные схемы данных в виде JSON Schema.
|
||
* У вас могут быть глубоко **вложенные объекты JSON**, и все они будут проверены и аннотированы.
|
||
* **Расширяемость**:
|
||
* Pydantic позволяет определять пользовательские типы данных или расширять проверку методами модели с помощью декораторов валидаторов.
|
||
* 100% покрытие тестами.
|