Расширения Flask: что реально нужно на живом проекте

Проблема: расширения ставятся раньше, чем появляется задача

Типичный Flask-проект начинается с pip install flask, а через час в requirements.txt уже десять расширений. Flask-Login, Flask-WTF, Flask-Mail, Flask-Caching, Flask-CORS, Flask-Migrate, Flask-RESTful — каждое по отдельности выглядит разумно. Вместе они тянут транзитивные зависимости, конфликтуют по версиям, а половина из них в проекте не используется или используется на десять процентов.

Ниже — разбор на примере сервиса, который встречается чаще всего: JSON API с авторизацией, базой на PostgreSQL и парой фоновых задач. Flask 3.x, Python 3.11+.

Что делает расширение Flask и почему это не обычная библиотека

Расширение Flask — это пакет, который интегрируется через паттерн init_app: получает доступ к конфигурации приложения, регистрирует свои обработчики, подключается к жизненному циклу запроса. Обычная Python-библиотека (requests, httpx, pydantic) не знает ничего о Flask и не нуждается в init_app.

Отсюда правило: если задачу решает обычная библиотека — расширение не нужно. Flask-Requests не существует не потому, что никто не написал, а потому что requests и так работает. Но для работы с базой через контекст приложения, управления миграциями и сессиями «чистый» SQLAlchemy требует обвязки — и тут расширение оправдано.

Сноска: init_app — метод, через который расширение привязывается к экземпляру Flask-приложения. Позволяет создавать расширение отдельно от приложения и подключать позже, что критично для паттерна application factory.

Ядро: четыре расширения, которые закрывают 80% задач API-сервиса

Flask-SQLAlchemy + Flask-Migrate

SQLAlchemy — стандарт ORM в Python-экосистеме. Flask-SQLAlchemy оборачивает создание движка, управление сессиями и привязку к контексту приложения. Без него вам придётся вручную открывать и закрывать сессии в teardown_appcontext, следить за пулом соединений и писать свой init_app. Это возможно, но вы повторите то, что расширение уже делает.

Flask-Migrate добавляет CLI-команды для Alembic — инструмента миграций. Без него Alembic работает, но конфигурация миграций живёт отдельно от Flask-конфига, и при нескольких базах или окружениях настройка становится хрупкой.

# models.py — Flask-SQLAlchemy 3.x, Flask 3.x
from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

class User(db.Model):
    __tablename__ = "users"
    id = db.Column(db.Integer, primary_key=True)
    email = db.Column(db.String(256), unique=True, nullable=False)
    password_hash = db.Column(db.String(256), nullable=False)
    created_at = db.Column(db.DateTime, server_default=db.func.now())

# Инициализация миграций (Flask-Migrate 4.x)
# В терминале, из корня проекта:
# flask db init       — создаёт папку migrations
# flask db migrate -m "create users"  — генерирует скрипт миграции
# flask db upgrade    — применяет миграцию к базе

Проверка: после flask db upgrade таблица users должна появиться в базе. Если вы видите ошибку Target database is not up to date, значит в папке миграций есть неприменённые скрипты — выполните flask db upgrade ещё раз или проверьте таблицу alembic_version.

Flask-CORS

Если фронтенд живёт на другом домене, браузер заблокирует запросы без CORS-заголовков. Flask-CORS добавляет их в ответы. Без расширения вы напишете декоратор after_request на десять строк. Работает — но при разных правилах для разных эндпоинтов (одни открыты для всех, другие только для конкретного домена) ручная логика разрастается и ломается при рефакторинге.

# app.py
from flask_cors import CORS

# Разрешаем запросы только с домена фронтенда
CORS(app, origins=["https://frontend.example.com"])

Цена вопроса: если ваш API не вызывается из браузера (мобильное приложение, серверный клиент) — CORS не нужен вовсе. Ставить его «на всякий случай» с origins="*" — дыра в безопасности без реальной пользы.

Flask-Login или PyJWT

Здесь возникает развилка. Flask-Login управляет сессиями через cookie — подходит для серверного рендеринга. Для JSON API с токенами он избыточен: вам не нужны login_user, logout_user и remember me. В API-сервисе проще взять PyJWT (обычная библиотека, не расширение) и написать декоратор проверки токена самостоятельно.

# auth.py — декоратор проверки JWT (PyJWT 2.x)
import functools
import jwt
from flask import request, jsonify, current_app

def token_required(view_func):
    @functools.wraps(view_func)
    def wrapper(*args, **kwargs):
        token = request.headers.get("Authorization", "").removeprefix("Bearer ")
        if not token:
            return jsonify({"error": "Токен не передан"}), 401
        try:
            payload = jwt.decode(
                token,
                current_app.config["SECRET_KEY"],
                algorithms=["HS256"],
            )
        except jwt.ExpiredSignatureError:
            return jsonify({"error": "Токен истёк"}), 401
        except jwt.InvalidTokenError:
            return jsonify({"error": "Невалидный токен"}), 401
        return view_func(payload, *args, **kwargs)
    return wrapper

30 строк — и у вас полная контролируемая авторизация без расширения. Flask-Login тут лишний.

Что ставят, но не нужно

Каждое расширение — это чужой код, который живёт по чужому графику релизов. Flask-RESTful не поддерживается, Flask-Script не нужен с Flask 1.0, Flask-WTF бесполезен в чистом API. Ставьте расширение, когда готовы платить зависимостью за конкретную экономию кода, а не за абстрактное удобство.

Конфликты и подводные камни

Версии SQLAlchemy

Flask-SQLAlchemy 3.x требует SQLAlchemy 2.x. Если в проекте есть расширение, написанное под SQLAlchemy 1.4 (а таких много — старые драйверы, расширения для геоданных), вы получите ошибки импорта при обновлении. Проверяйте совместимость до pip install, а не после.

Двойная инициализация

Ошибка, которая стреляет не сразу: вызов init_app дважды для одного расширения на одном приложении. Flask-SQLAlchemy переживёт, Flask-Migrate может создать дублирующиеся CLI-команды. Следите, чтобы фабрика приложения вызывалась один раз.

Порядок инициализации

Flask-Migrate зависит от Flask-SQLAlchemy. Если вы вызовете migrate.init_app(app, db) до db.init_app(app), получите ошибку. Порядок прост: сначала db, потом всё, что от него зависит.

Минимальная фабрика приложения

# app.py — Flask 3.x, Flask-SQLAlchemy 3.x, Flask-Migrate 4.x
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_cors import CORS

db = SQLAlchemy()
migrate = Migrate()

def create_app():
    app = Flask(__name__)
    app.config.from_prefixed_env()  # читает FLASK_* из окружения

    db.init_app(app)
    migrate.init_app(app, db)
    CORS(app, origins=app.config.get("CORS_ORIGINS", "*").split(","))

    # Импорт и регистрация блюпринтов
    from .routes import api_bp
    app.register_blueprint(api_bp, url_prefix="/api")

    return app

Четыре импорта, три init_app — и проект готов к росту. Всё остальное подключается, когда для этого появляется реальная причина.

Чек-лист: ставить расширение или нет

1. Задача требует интеграции с жизненным циклом Flask (контекст, конфиг, CLI)? Если нет — обычная библиотека лучше.
2. Расширение активно поддерживается? Проверьте дату последнего коммита и совместимость с Flask 3.x.
3. Вы используете хотя бы 30% его функциональности? Если берёте Flask-Caching ради одного декоратора — напишите его сами.
4. Расширение не дублирует то, что уже есть во Flask? Встроенные MethodView, flask.cli, jsonify закрывают многое.
5. Транзитивные зависимости не конфликтуют с тем, что уже в проекте? Проверьте через pip install --dry-run (pip 23.1+).

Что дальше

После базовой сборки первый практический шаг — настроить структурированное логирование (стандартный logging + python-json-logger, без расширений Flask) и health-check эндпоинт, который проверяет соединение с базой. Это то, что спросят на первом же код-ревью, и то, без чего проект не готов к деплою. Тему фоновых задач (Celery, arq, dramatiq) и их интеграции с Flask-контекстом стоит разбирать отдельно — связка нетривиальная и заслуживает собственного разбора.