Monogenes

Appearance

FastAPI — основы ​

FastAPI — это мощный инструмент для создания современных и высокопроизводительных API. Он сочетает в себе простоту использования, скорость разработки и гибкость. Благодаря поддержке аннотаций типов и автоматической документации разработчики могут значительно ускорить процесс создания API, минимизируя количество ошибок.

FastAPI подходит как для небольших проектов, так и для крупных систем, требующих высокой производительности.

Что такое FastAPI? ​

FastAPI — это асинхронный веб-фреймворк, созданный на базе Starlette (веб-фреймворка) и Pydantic (библиотеки для валидации данных). Он предлагает множество удобных инструментов для разработки API, таких как автоматическая документация, встроенная валидация данных и высокая производительность благодаря использованию асинхронных вызовов.

Основные преимущества FastAPI ​

  1. Высокая производительность
    FastAPI работает на основе асинхронного веб-сервера ASGI, что делает его одним из самых быстрых Python-фреймворков.

  2. Аннотации типов
    Использование типов в Python (например, str, int, List) позволяет FastAPI автоматически проверять значения запросов и генерировать документацию.

  3. Автоматическая документация
    FastAPI автоматически создаёт документацию API с помощью Swagger UI и ReDoc. Это упрощает тестирование и работу с API.

  4. Простота использования
    Несмотря на свою мощь, FastAPI остаётся интуитивно понятным и легко изучаемым.

  5. Асинхронность
    Поддержка асинхронных функций позволяет обрабатывать множество запросов одновременно, улучшая производительность.

Установка FastAPI в виртуальное окружение: ​

Устанавливать пакет лучше используя виртуальное окружение это позволяет:

  • создать изоляцию зависимостей проекта от глобальных пакетов.
  • предотвращение конфликтов версий.
  • позволяет легко управлять разными версиями FastAPI для разных проектов.

Из минусов только требует дополнительных шагов для создания и активации окружения.

  1. Создать виртуальное окружение:

    shell
    py -3.13 -m venv .venv

  2. Активировать виртуальное окружение:

    shell
    source .venv/bin/activate (Linux/macOS)
.venv\Scripts\activate (Windows)

  3. Установить FastAPI:

    shell
    pip install fastapi[all]

    pip install fastapi[all]: устанавливает FastAPI и все рекомендуемые зависимости, включая:

    • uvicorn: ASGI-сервер для запуска приложения.
    • pydantic: для валидации данных.
    • httpx: для выполнения HTTP-запросов.
    • starlette: основа FastAPI.
    • и другие полезные пакеты.

Пример простого приложения ​

Создадим простое веб-приложение с использованием FastAPI. В корневой папке проекта, создать файл main.py:

python
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def get_main_page() -> str:
    return "The main page of the local FastAPI!"

@app.get("/new_page/")
def get_new_page() -> str:
    return "The new page of the local FastAPI!"

app = FastAPI(): Создает экземпляр приложения FastAPI. app теперь является объектом, который будет обрабатывать входящие HTTP-запросы.

@app.get("/"): Это декоратор. Декораторы в Python - это способ обернуть функцию и добавить ей дополнительную функциональность. В данном случае, @app.get("/") регистрирует функцию get_main_page для обработки HTTP GET запросов, направленных на корневой путь /. "/" – Это путь (path) или маршрут (route). Он указывает, по какому URL адресу должна быть доступна эта функция. В данном случае, это корневой путь, то есть, когда пользователь заходит на локальный сайт (например, http://localhost:8000 или http://127.0.0.1:8000), он вызывает эту функцию.

@app.get("/new_page/"): Регистрирует функцию для обработки GET запросов к /new_page/. В данном случае, когда пользователь заходит на локальный сайт (например, http://localhost:8000/new_page/), он вызывает эту функцию.

Результат полученный в браузере:

img_1.png

Запуск приложения ​

Для запуска приложения в консоли/терминале используется сервер Uvicorn:

bash
uvicorn main:app --reload
  • main — относительный путь к файлу (без .py), начиная с корневой папки проекта.
  • app — объект приложения FastAPI.
  • --reload — автоматическая перезагрузка при изменении кода (удобно для разработки).

После запуска приложение будет доступно по адресу: http://127.0.0.1:8000.

Результат вывода главной страницы полученный в браузере по адресу http://127.0.0.1:8000:

img.png

Результат вывода другой страницы полученный в браузере по адресу http://127.0.0.1:8000/new_page/:

img_1.png

Если задать неверный адрес, не существующий андрес (в возможно в результате ошибки), приложение отобразит следующее содержимое:

img_2.png

Отображение в терминале ​

FastApi содержит модуль логирования для отображения изменений и работы приложения. Отображение в терминале при запуске FastAPI с Uvicorn и опцией --reload показывает следующее:

1. Запуск Uvicorn и настройка отслеживания изменений: ​

  • (.venv) PS C:\fast_api_base> uvicorn main:app --reload:

    • Эта команда запускает Uvicorn, ASGI-сервер, который будет обслуживать ваше FastAPI-приложение.
    • main:app указывает, что Uvicorn должен искать экземпляр FastAPI приложения (app) в файле main.py.
    • --reload активирует автоматическую перезагрузку сервера при обнаружении изменений в коде.

  • INFO: Will watch for changes in these directories: ['C:\\fast_api_base']: Uvicorn сообщает, какие каталоги он будет отслеживать на предмет изменений файлов. В данном случае, это текущий рабочий каталог.

  • INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit): Uvicorn сообщает, на каком адресе и порту запущен сервер. 127.0.0.1 (localhost) означает, что сервер доступен только с вашего компьютера. 8000 - это порт по умолчанию, но его можно изменить. Также сообщается, что остановить сервер можно нажать сочетание клавиш CTRL+C.

  • INFO: Started reloader process [20644] using WatchFiles: Запускается процесс автоматической перезагрузки (reloader), который использует библиотеку WatchFiles для отслеживания изменений файлов. Номер в квадратных скобках – это ID процесса.

  • INFO: Started server process [20736]: Запускается основной процесс Uvicorn-сервера. Номер в квадратных скобках – это ID процесса.

  • INFO: Waiting for application startup.: Uvicorn ожидает завершения процедуры запуска приложения. Если в вашем FastAPI-приложении есть код, который должен быть выполнен при запуске (например, подключение к базе данных), Uvicorn будет ждать его завершения.

  • INFO: Application startup complete.: Uvicorn сообщает об успешном завершении запуска приложения.

2. Обработка HTTP-запросов: ​

Обращение к главной странице:

  • INFO: 127.0.0.1:3423 - "GET / HTTP/1.1" 200 OK: Сервер получил GET-запрос по адресу /. 200 OK означает, что запрос был успешно обработан и сервер вернул успешный ответ. Это говорит о том, что после перезагрузки вы добавили обработчик для корневого пути.

Обращение к новой странице, со слешем / в конце:

  • INFO: 127.0.0.1:3466 - "GET /new_page/ HTTP/1.1" 200 OK: Сервер получил GET-запрос по адресу /new_page/. 200 OK означает, что запрос был успешно обработан и сервер вернул успешный ответ.

Обращение к новой странице, без слеша / в конце:

  • INFO: 127.0.0.1:3466 - "GET /new_page HTTP/1.1" 307 Temporary Redirect: Сервер получил GET-запрос по адресу /new_page. 307 Temporary Redirect означает, что сервер временно перенаправляет запрос на другой адрес. FastAPI автоматически добавляет слеш в конце пути, если он отсутствует, и перенаправляет на путь со слешем.
  • INFO: 127.0.0.1получает GET-запрос по адресу /new_page/` (уже со слешем) и успешно его обрабатывает.

Обращение к не существующему адресу страницы:

  • INFO: 127.0.0.1:3520 - "GET /no_page/ HTTP/1.1" 404 Not Found: Сервер получил GET-запрос по адресу /no_page/. 404 Not Found означает, что по этому адресу не найдено никакого обработчика в вашем FastAPI-приложении.:3466 - "GET /new_page/ HTTP/1.1" 200 OK`: После перенаправления, сервер

3. Перезагрузка сервера (из-за изменения кода): ​

FastAPI поддерживает автоматическую перезагрузку сервера при изменении кода, что делает разработку более удобной и быстрой. Эта функция называется hot reload и включается по умолчанию при запуске приложения в режиме разработки. Т.е. при изменении или написании нового кода не нужно останавливать сервер и запускать сервер заново.

Сообщения выводимые в терминале при изменении в коде:

  • WARNING: WatchFiles detected changes in 'main.py'. Reloading...: WatchFiles, используемый Uvicorn, обнаружил изменения в файле main.py (где находится ваше FastAPI приложение). Это запускает процесс перезагрузки сервера.
  • INFO: Shutting down: Uvicorn начинает процесс остановки текущего экземпляра сервера.
  • INFO: Waiting for application shutdown.: Uvicorn ожидает завершения процедуры остановки приложения. Если в вашем FastAPI-приложении есть код, который должен быть выполнен при остановке (например, закрытие соединения с базой данных), Uvicorn будет ждать его завершения.
  • INFO: Application shutdown complete.: Uvicorn сообщает об успешном завершении остановки приложения.
  • INFO: Finished server process [20736]: Завершен процесс Uvicorn-сервера со старым ID.
  • INFO: Started server process [18328]: Запускается новый процесс Uvicorn-сервера (с новым ID).
  • INFO: Waiting for application startup.: Uvicorn ожидает завершения процедуры запуска приложения.
  • INFO: Application startup complete.: Uvicorn сообщает об успешном завершении запуска приложения.

Ключевые моменты: ​

  • INFO: Информационные сообщения.
  • WARNING: Предупреждения.
  • 127.0.0.1: Локальный адрес вашего компьютера.
  • 8000: Порт, на котором работает сервер.
  • GET: HTTP-метод (в данном случае, получение данных).
  • /: Корневой путь (root path).
  • 404 Not Found: HTTP-статус код, означающий, что запрошенный ресурс не найден.
  • 200 OK: HTTP-статус код, означающий, что запрос был успешно обработан.
  • 307 Temporary Redirect: HTTP-статус код, означающий временное перенаправление.
  • --reload: Флаг, который включает автоматическую перезагрузку сервера при изменении кода.

Понимание этих сообщений помогает отлаживать ваше FastAPI-приложение и следить за работой.

Автоматическая документация ​

FastAPI автоматически генерирует документацию API. После запуска приложения вы можете открыть:

  1. Swagger UI — доступен по адресу http://127.0.0.1:8000/docs. Это интерактивный интерфейс для тестирования API.
  2. ReDoc — доступен по адресу http://127.0.0.1:8000/redoc. Это статическая документация API.

Проверка работы ​

  1. Откройте браузер на http://127.0.0.1:8000/.

    Вы увидите следующий текст:

    Добро пожаловать в локальный FastAPI!

  2. Откройте браузер на http://127.0.0.1:8000/items/5?q=somequery.

Вы увидите следующий JSON ответ:

json
{"item_id": 5, "q": "somequery"}

Вы уже создали API, который:

Получает HTTP-запросы по путям / и /items/{item_id}.

И первый и второй путь используют GET операции (также известные как HTTP методы).

  • путь /items/{item_id} имеет параметр пути item_id, который должен быть int.
  • путь /items/{item_id} имеет необязательный str параметр запроса q.

Работа с параметрами запросов ​

Параметры пути указываются в фигурных скобках {}. Например:

python
@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

В данном случае user_id будет автоматически преобразован в int, а если тип не совпадает, FastAPI вернёт ошибку.