Интеграция FastAPI в существующий проект: пошаговая инструкция за 60 минут

FastAPI, современный веб-фреймворк на Python, завоевал популярность благодаря своей скорости, простоте и автоматической генерации документации. Часто возникает задача встроить его в уже работающий проект, будь то монолитное приложение на Django/Flask или сервис, которому требуется быстрый и удобный API-слой. Эта инструкция покажет, как выполнить такую интеграцию за один час, не нарушив работу существующего кода.

Шаг 1: Подготовка окружения (5 минут). Убедитесь, что в вашем проекте используется Python 3.7+. Создайте и активируйте виртуальное окружение, если это ещё не сделано. Установите FastAPI и стандартный ASGI-сервер для разработки Uvicorn одной командой: pip install fastapi uvicorn[standard]. Если ваш проект использует систему управления зависимостями (poetry, pipenv), добавьте пакеты туда. Проверьте, нет ли конфликтов версий с существующими зависимостями, особенно если проект использует старые версии библиотек для работы с данными, например, Pydantic.

Шаг 2: Создание первого эндпоинта (15 минут). Не трогая существующий код приложения, создайте в корне проекта или в отдельном каталоге (например, api) новый файл main.py. Это будет точка входа для FastAPI. Импортируйте FastAPI и создайте экземпляр приложения: from fastapi import FastAPI app = FastAPI(title="Project API", version="1.0.0"). Теперь создайте простейший GET-эндпоинт для проверки работоспособности. Используйте декоратор: @app.get("/health") def health_check(): return {"status": "ok"}. Важный момент — если ваш основной проект уже запускается на каком-то порту (например, 8000), для FastAPI нужно назначить другой порт.

Шаг 3: Запуск и проверка (5 минут). Запустите ваше FastAPI-приложение из командной строки в отдельном терминале: uvicorn api.main:app --reload --port 8001. Ключ --reload позволит автоматически перезагружать сервер при изменениях кода. Откройте браузер и перейдите по адресу http://localhost:8001/health. Вы должны увидеть JSON-ответ {"status": "ok"}. Затем перейдите на http://localhost:8001/docs. Вы автоматически попадёте на интерактивную документацию Swagger UI, сгенерированную FastAPI. Это подтвердит, что основа работает.

Шаг 4: Интеграция логики существующего проекта (25 минут). Теперь ключевой этап — заставить FastAPI использовать функции, классы и данные из вашего основного приложения. Предположим, у вас есть модуль core.services с функцией get_user_data(user_id). Вам нужно сделать её доступной через API. Импортируйте эту функцию в ваш main.py. Создайте эндпоинт, который будет её вызывать. Используйте возможности FastAPI для валидации пути: @app.get("/users/{user_id}") def read_user(user_id: int): data = get_user_data(user_id) return data. FastAPI автоматически преобразует user_id из строки URL в целое число и вернёт 422 ошибку, если передано не число.

Если ваше основное приложение использует базу данных, убедитесь, что механизмы подключения (пулы соединений, настройки сессий) корректно работают в контексте асинхронного ASGI-сервера. FastAPI отлично работает как с синхронными, так и с асинхронными функциями. Для синхронных, блокирующих операций (тяжёлые вычисления, запросы к БД) рекомендуется использовать фоновые задачи или вынести их в отдельные потоки, чтобы не блокировать цикл событий.

Шаг 5: Добавление middleware и CORS (10 минут). Для бесшовной интеграции часто требуется, чтобы фронтенд, работающий на другом домене или порту, мог обращаться к вашему новому API. Для этого нужно настроить CORS (Cross-Origin Resource Sharing). В FastAPI это делается в несколько строк: from fastapi.middleware.cors import CORSMiddleware app.add_middleware(CORSMiddleware, allow_origins=["http://localhost:3000"], allow_methods=["*"], allow_headers=["*"]). Укажите адрес вашего фронтенд-приложения в allow_origins.

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

По итогам этого часа вы получите работающий API-слой поверх вашего приложения. Он будет иметь автоматическую документацию, валидацию запросов и возможность независимого масштабирования. Дальнейшие шаги — это добавление большего количества эндпоинтов, внедрение полноценной аутентификации (например, с помощью OAuth2 и JWT, что в FastAPI делается очень просто), подключение фоновых задач с помощью Celery или встроенного BackgroundTasks и, наконец, контейнеризация приложения с помощью Docker для последующего развёртывания. Главное преимущество такого подхода — постепенность. Вы можете развивать API независимо от основного монолита, а в будущем и вовсе вынести из него отдельные микросервисы.