Browse Source
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Sebastián Ramírez <[email protected]>pull/5347/head
Vladislav Kramorenko
3 years ago
committed by
GitHub
GitHub
2 changed files with 204 additions and 0 deletions
@ -0,0 +1,203 @@ |
|||||
|
# Основные свойства |
||||
|
|
||||
|
## Основные свойства FastAPI |
||||
|
|
||||
|
**FastAPI** предлагает вам следующее: |
||||
|
|
||||
|
### Использование открытых стандартов |
||||
|
|
||||
|
* <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). |
||||
|
* Разработан, придерживаясь этих стандартов, после тщательного их изучения. Эти стандарты изначально включены во фреймфорк, а не являются дополнительной надстройкой. |
||||
|
* Это также позволяет использовать автоматическую **генерацию клиентского кода** на многих языках. |
||||
|
|
||||
|
### Автоматически генерируемая документация |
||||
|
|
||||
|
Интерактивная документация для 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 |
||||
|
|
||||
|
Все эти возможности основаны на стандартных **аннотациях типов Python 3.6** (благодаря Pydantic). Не нужно изучать новый синтаксис. Только лишь стандартный современный Python. |
||||
|
|
||||
|
Если вам нужно освежить знания, как использовать аннотации типов в Python (даже если вы не используете FastAPI), выделите 2 минуты и просмотрите краткое руководство: [Введение в аннотации типов Python¶ |
||||
|
](python-types.md){.internal-link target=_blank}. |
||||
|
|
||||
|
Вы пишете на стандартном Python с аннотациями типов: |
||||
|
|
||||
|
```Python |
||||
|
from datetime import date |
||||
|
|
||||
|
from pydantic import BaseModel |
||||
|
|
||||
|
# Объявляем параметр user_id с типом `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) |
||||
|
``` |
||||
|
|
||||
|
!!! Информация |
||||
|
`**second_user_data` означает: |
||||
|
|
||||
|
Передать ключи и значения словаря `second_user_data`, в качестве аргументов типа "ключ-значение", это эквивалентно: `User(id=4, name="Mary", joined="2018-11-30")` . |
||||
|
|
||||
|
### Поддержка редакторов (IDE) |
||||
|
|
||||
|
Весь фреймворк был продуман так, чтобы быть простым и интуитивно понятным в использовании, все решения были проверены на множестве редакторов еще до начала разработки, чтобы обеспечить наилучшие условия при написании кода. |
||||
|
|
||||
|
В опросе 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`. |
||||
|
|
||||
|
### Краткость |
||||
|
FastAPI имеет продуманные значения **по умолчанию** для всего, с произвольными настройками везде. Все параметры могут быть тонко подстроены так, чтобы делать то, что вам нужно и определять необходимый вам API. |
||||
|
|
||||
|
Но, по умолчанию, всё это **"и так работает"**. |
||||
|
|
||||
|
### Проверка значений |
||||
|
|
||||
|
* Проверка значений для большинства (или всех?) **типов данных** Python, включая: |
||||
|
* Объекты JSON (`dict`). |
||||
|
* Массивы JSON (`list`) с установленными типами элементов. |
||||
|
* Строковые (`str`) поля с ограничением минимальной и максимальной длины. |
||||
|
* Числа (`int`, `float`) с минимальными и максимальными значениями и т.п. |
||||
|
|
||||
|
* Проверка для более экзотических типов, таких как: |
||||
|
* URL. |
||||
|
* Email. |
||||
|
* UUID. |
||||
|
* ...и другие. |
||||
|
|
||||
|
Все проверки обрабатываются хорошо зарекомендовавшим себя и надежным **Pydantic**. |
||||
|
|
||||
|
### Безопасность и аутентификация |
||||
|
|
||||
|
Встроеные функции безопасности и аутентификации. Без каких-либо компромиссов с базами данных или моделями данных. |
||||
|
|
||||
|
Все схемы безопасности, определённые в OpenAPI, включая: |
||||
|
|
||||
|
* HTTP Basic. |
||||
|
* **OAuth2** (также с **токенами JWT**). Ознакомьтесь с руководством [OAuth2 с JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. |
||||
|
* Ключи API в: |
||||
|
* Заголовках. |
||||
|
* Параметрах запросов. |
||||
|
* Cookies и т.п. |
||||
|
|
||||
|
Вдобавок все функции безопасности от Starlette (включая **сессионные cookies**). |
||||
|
|
||||
|
Все инструменты и компоненты спроектированы для многократного использования и легко интегрируются с вашими системами, хранилищами данных, реляционными и NoSQL базами данных и т. д. |
||||
|
|
||||
|
### Внедрение зависимостей |
||||
|
|
||||
|
FastAPI включает в себя чрезвычайно простую в использовании, но чрезвычайно мощную систему <abbr title='известную как: "components", "resources", "services", "providers"'><strong>Внедрения зависимостей</strong></abbr>. |
||||
|
|
||||
|
* Даже зависимости могут иметь зависимости, создавая иерархию или **"графы" зависимостей**. |
||||
|
* Всё **автоматически обрабатывается** фреймворком. |
||||
|
* Все зависимости могут запрашивать данные из запросов и **дополнять операции пути** ограничениями и автоматической документацией. |
||||
|
* **Автоматическая проверка** даже для параметров *операций пути*, определенных в зависимостях. |
||||
|
* Поддержка сложных систем аутентификации пользователей, **соединений с базами данных** и т.д. |
||||
|
* **Никаких компромиссов** с базами данных, интерфейсами и т.д. Но легкая интеграция со всеми ними. |
||||
|
|
||||
|
### Нет ограничений на "Плагины" |
||||
|
|
||||
|
Или, другими словами, нет сложностей с ними, импортируйте и используйте нужный вам код. |
||||
|
|
||||
|
Любая интеграция разработана настолько простой в использовании (с зависимостями), что вы можете создать "плагин" для своего приложения в пару строк кода, используя ту же структуру и синтаксис, что и для ваших *операций пути*. |
||||
|
|
||||
|
### Проверен |
||||
|
|
||||
|
* 100% <abbr title="Количество автоматически проверямого кода">покрытие тестами</abbr>. |
||||
|
* 100% <abbr title="Аннотации типов Python, благодаря которым ваш редактор и другие инструменты могут обеспечить вам лучшую поддержку">аннотирование типов</abbr> в кодовой базе. |
||||
|
* Используется в реально работающих приложениях. |
||||
|
|
||||
|
## Основные свойства Starlette |
||||
|
|
||||
|
**FastAPI** основан на <a href="https://www.starlette.io/" 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</a>, наравне с приложениями использующими **NodeJS** или **Go**. |
||||
|
* Поддержка **WebSocket**. |
||||
|
* Фоновые задачи для процессов. |
||||
|
* События запуска и выключения. |
||||
|
* Тестовый клиент построен на библиотеке `requests`. |
||||
|
* **CORS**, GZip, статические файлы, потоковые ответы. |
||||
|
* Поддержка **сессий и cookie**. |
||||
|
* 100% покрытие тестами. |
||||
|
* 100% аннотирование типов в кодовой базе. |
||||
|
|
||||
|
## Особенности и возможности Pydantic |
||||
|
|
||||
|
**FastAPI** основан на <a href="https://pydantic-docs.helpmanual.io" 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="Интегрированное окружение для разработки, похожее на текстовый редактор">IDE</abbr>/<abbr title="программа проверяющая ошибки в коде">linter</abbr>/мозгом**: |
||||
|
* Потому что структуры данных pydantic - это всего лишь экземпляры классов, определённых вами. Автодополнение, проверка кода, mypy и ваша интуиция - всё будет работать с вашими проверенными данными. |
||||
|
* **Быстродействие**: |
||||
|
* В <a href="https://pydantic-docs.helpmanual.io/benchmarks/" class="external-link" target="_blank">тестовых замерах</a> Pydantic быстрее, чем все другие проверенные библиотеки. |
||||
|
* Проверка **сложных структур**: |
||||
|
* Использование иерархических моделей Pydantic; `List`, `Dict` и т.п. из модуля `typing` (входит в стандартную библиотеку Python). |
||||
|
* Валидаторы позволяют четко и легко определять, проверять и документировать сложные схемы данных в виде JSON Schema. |
||||
|
* У вас могут быть глубоко **вложенные объекты JSON** и все они будут проверены и аннотированы. |
||||
|
* **Расширяемость**: |
||||
|
* Pydantic позволяет определять пользовательские типы данных или расширять проверку методами модели, с помощью проверочных декораторов. |
||||
|
* 100% покрытие тестами. |
||||
Loading…
Reference in new issue