28.09.2025 12:47
enamored_poc 0 416 Источник

1. Введение в FastAPI

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

Ключевые технические преимущества FastAPI обусловлены его архитектурой и используемыми компонентами:

  • Производительность: FastAPI является одним из самых быстрых фреймворков для Python, достигая производительности, сравнимой с NodeJS и Go. Это возможно благодаря тому, что он построен поверх ASGI-фреймворка Starlette для асинхронной обработки запросов и использует ASGI-сервер Uvicorn.

  • Скорость разработки: Использование аннотаций типов Python для объявления параметров запросов, заголовков и тел запросов позволяет значительно сократить объем шаблонного кода. Это приводит к ускорению цикла разработки и повышению читаемости кодовой базы.

  • Надежность и валидация данных: В основе FastAPI лежит библиотека Pydantic, которая обеспечивает строгую валидацию типов данных "из коробки". Любые несоответствия в поступающих данных автоматически обрабатываются, и клиенту возвращается информативный JSON-ответ с описанием ошибки.

  • Автоматическая генерация документации: Фреймворк автоматически генерирует схему API в соответствии со стандартом OpenAPI. На основе этой схемы создаются два интерфейса интерактивной документации: Swagger UI и ReDoc. Это позволяет команде разработки и конечным потребителям API иметь всегда актуальную документацию, сгенерированную непосредственно из исходного кода.

Цель данной статьи — предоставить пошаговое руководство по началу работы с FastAPI. В этой первой части мы выполним настройку рабочего окружения, создадим и запустим минимально рабочее приложение, а также детально разберем структуру его кода и базовые концепции фреймворка.

2. Настройка рабочего окружения

Корректная настройка рабочего окружения является фундаментальным шагом для обеспечения изоляции зависимостей и воспроизводимости проекта. Мы будем использовать встроенный в Python модуль venv для создания легковесного виртуального окружения.

Принцип изоляции зависимостей: Виртуальное окружение создает изолированную среду с собственным интерпретатором Python и набором установленных пакетов. Это позволяет избежать конфликтов версий между зависимостями разных проектов и гарантирует, что проект будет использовать именно те версии библиотек, которые были определены на этапе разработки.

Следуйте приведенным ниже шагам для настройки окружения:

1. Создание директории проекта

Создайте директорию для вашего проекта и перейдите в нее.

mkdir fastapi_project
cd fastapi_project

2. Инициализация виртуального окружения

Выполните команду для создания виртуального окружения в поддиректории с именем venv:

python -m venv venv

Эта команда создаст папку venv, содержащую копию интерпретатора Python и структуру директорий для установки пакетов.

3. Активация виртуального окружения

Перед установкой зависимостей необходимо активировать окружение. Команда активации отличается для разных операционных систем:

  • Для Windows (Command Prompt или PowerShell):

    .\venv\Scripts\activate

  • Для macOS и Linux (bash/zsh):

    source venv/bin/activate

После активации в начале командной строки появится префикс (venv), указывающий на то, что вы работаете внутри виртуального окружения.

4. Установка основных зависимостей

Теперь установим FastAPI и ASGI-сервер Uvicorn с помощью менеджера пакетов pip.

pip install fastapi uvicorn

  • fastapi: Ядро фреймворка, предоставляющее все необходимые классы и функции для создания API, включая декораторы путей, обработку зависимостей и интеграцию с Pydantic.

  • uvicorn: Высокопроизводительный ASGI-сервер (Asynchronous Server Gateway Interface). FastAPI, будучи асинхронным фреймворком, требует ASGI-совместимого сервера для запуска и обработки входящих запросов. Uvicorn является стандартным выбором для этой цели.

3. Реализация первого приложения

После успешной настройки рабочего окружения мы можем приступить к написанию и запуску минимального рабочего приложения на FastAPI.

Структура проекта

На данном этапе наш проект будет состоять из одного файла. В корневой директории проекта (fastapi_project) создайте файл с именем main.py. Этот файл будет точкой входа в наше приложение.

Минимальный код приложения

Откройте файл main.py и добавьте в него следующий код. Этот код определяет одно "действие пути" (path operation) для корневого URL.

# main.py

from fastapi import FastAPI

# 1. Инстанцирование класса FastAPI
# Этот объект является основной точкой взаимодействия для создания всего API.
app = FastAPI()

# 2. Определение "действия пути" (path operation) с помощью декоратора
# @app.get("/") сообщает FastAPI, что функция ниже отвечает на GET-запросы к URL "/"
@app.get("/")
def read_root():
    """
    Этот эндпоинт возвращает стартовое сообщение.
    """
    # 3. Возврат данных
    # Фреймворк автоматически сериализует словарь в JSON-ответ.
    return {"message": "Application is running"}

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

Для запуска приложения используется ASGI-сервер Uvicorn. Убедитесь, что вы находитесь в корневой директории проекта (fastapi_project) и ваше виртуальное окружение (venv) активировано. Выполните в терминале следующую команду:

uvicorn main:app --reload

После выполнения команды вы увидите в терминале вывод, подобный следующему:

INFO:     Will watch for changes in directory: '...'
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using statreload
INFO:     Started server process [12347]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Разбор команды запуска

Рассмотрим детально компоненты команды uvicorn main:app --reload:

  • main: Указывает на имя Python-файла, который Uvicorn должен импортировать (модуль main.py).

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

  • --reload: Это флаг, предназначенный для разработки. Он активирует режим автоматической перезагрузки: Uvicorn будет отслеживать изменения в файлах проекта и автоматически перезапускать сервер при их обнаружении. Это избавляет от необходимости вручную останавливать и запускать сервер после каждого изменения в коде.

Теперь ваше первое приложение на FastAPI запущено и доступно по адресу http://127.0.0.1:8000. Вы можете открыть этот URL в браузере или использовать любой HTTP-клиент (например, curl), чтобы отправить GET-запрос и получить JSON-ответ: {"message":"Application is running"}.

4. Анализ базовой структуры кода

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

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Application is running"}

from fastapi import FastAPI

Эта строка импортирует класс FastAPI из библиотеки fastapi. Данный класс является основной точкой входа и предоставляет всю функциональность, необходимую для построения API.

app = FastAPI()

Здесь мы создаем экземпляр класса FastAPI. Объект app, согласно общепринятому соглашению, является центральным элементом приложения. Именно через этот объект происходит регистрация всех API-маршрутов (эндпоинтов), middleware, обработчиков событий и других конфигураций.

@app.get("/")

Это "декоратор операции пути" (path operation decorator). Декораторы в Python — это функции, которые изменяют или расширяют поведение других функций. В данном контексте декоратор @app.get("/") связывает HTTP-метод и URL-путь с функцией-обработчиком, которая определена непосредственно под ним.

  • app: Указывает на наш экземпляр приложения.

  • .get: Определяет, что данная операция будет обрабатывать HTTP GET запросы. FastAPI предоставляет аналогичные декораторы для всех стандартных HTTP-методов: .post(), .put(), .delete(), .patch() и других.

  • ("/"): Строковый аргумент, который задает путь (path) URL. В данном случае это корневой путь (/).

Таким образом, конструкция @app.get("/") сообщает FastAPI: "Когда на сервер поступает HTTP GET запрос на корневой URL, выполни код функции, которая следует за этим декоратором".

def read_root():

Это "функция операции пути" (path operation function). Она представляет собой стандартную функцию Python, содержащую логику, которая должна быть выполнена при получении запроса.

FastAPI спроектирован для работы с асинхронным кодом и способен корректно обрабатывать как синхронные функции (объявленные через def), так и асинхронные (объявленные через async def). В случае синхронной функции FastAPI выполнит ее в отдельном пуле потоков, чтобы не блокировать основной цикл событий (event loop), что является ключевым для поддержания высокой производительности.

return {"message": "Application is running"}

Функция-обработчик возвращает Python-словарь. Одной из ключевых возможностей FastAPI является автоматическая сериализация данных. Фреймворк обнаружит, что возвращаемое значение является словарем, и автоматически преобразует его в JSON-формат. Кроме того, FastAPI установит соответствующий заголовок ответа Content-Type в application/json.

По умолчанию, для успешных ответов будет использован HTTP-статус 200 OK. FastAPI способен сериализовать большинство стандартных типов Python, а также модели данных Pydantic, что является основой для валидации и документирования.

5. Интерактивная документация API

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

Механизм генерации документации

FastAPI использует информацию, уже имеющуюся в вашем коде, для построения полной и точной схемы API. Источниками данных для генерации служат:

  • Декораторы операций пути (@app.get, @app.post и т.д.), которые определяют эндпоинты и HTTP-методы.

  • Параметры функций и их аннотации типов, которые описывают path, query, header и cookie параметры.

  • Модели Pydantic, которые определяют структуру тел запросов и ответов.

На основе этих данных FastAPI генерирует схему API, полностью соответствующую стандарту OpenAPI (ранее известный как Swagger). OpenAPI — это общепринятый стандарт для спецификации RESTful API, который позволяет как человеку, так и машине понимать возможности сервиса без доступа к его исходному коду.

Доступ к интерфейсам документации

После запуска приложения (uvicorn main:app --reload) FastAPI автоматически предоставляет два веб-интерфейса для доступа к сгенерированной документации.

  1. Swagger UI

    • URL: http://127.0.0.1:8000/docs

    Swagger UI предоставляет полнофункциональный, интерактивный интерфейс, который позволяет не только просматривать все доступные эндпоин��ы, их параметры, тела запросов и возможные ответы, но и выполнять тестовые запросы напрямую из браузера. Для нашего текущего приложения вы увидите эндпоинт GET /, сможете развернуть его описание и нажать кнопку "Try it out", а затем "Execute", чтобы отправить реальный запрос на ваш запущенный сервер и увидеть ответ.

  2. ReDoc

    • URL: http://127.0.0.1:8000/redoc

    ReDoc предоставляет альтернативное, более статичное и чистое представление документации. Этот интерфейс ориентирован в первую очередь на удобочитаемость и часто используется для генерации документации для конечных пользователей API. В отличие от Swagger UI, он не имеет встроенной функциональности для отправки запросов, но представляет всю информацию о схеме API в структурированном и удобном для навигации виде.

Ценность для процесса разработки

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

6. Заключение и анонс следующей части

Резюме проделанной работы

В рамках данной статьи был рассмотрен начальный этап работы с фреймворком FastAPI. Мы успешно выполнили следующие ключевые задачи:

  1. Настроили изолированное рабочее окружение с помощью модуля venv, что является стандартной практикой для Python-разработки.

  2. Установили необходимые зависимости — сам фреймворк fastapi и ASGI-сервер uvicorn.

  3. Создали и запустили минимально рабочее приложение, разобрав команду запуска и ее параметры, включая флаг --reload для автоматической перезагрузки в режиме разработки.

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

  5. Ознакомились с системой автоматической генерации интерактивной документации, доступной по эндпоинтам /docs (Swagger UI) и /redoc (ReDoc).

На данном этапе у вас есть работающее API с одним эндпоинтом и полное понимание его структуры и принципов работы. Это прочная основа для дальнейшего изучения более сложных возможностей фреймворка.

Анонс следующей части

Текущее приложение имеет статичный характер и не взаимодействует с внешними данными. В следующей части нашего руководства мы перейдем к реализации динамического поведения API.

7. Практическое задание

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

Ссылка на репозиторий: Ссылка на домашнее задание.

P.S. Больше подобных разборов, полезные фрагменты кода и анонсы моих новых статей вы найдете в моем Telegram-канале. Заходите, чтобы оставаться на связи!

→ Мой Python-канал

Комментарии (0)