🏗️ Капстоун A — Community Pulse API (Flask)

📁 Серия: Капстоун A 🔧 Стек: Flask 3 · SQLAlchemy 2 · Flask-Migrate · Pydantic v2 📊 Этапов: 7 шагов

#flask #sqlalchemy #pydantic #rest-api #капстоун

⚡ Кратко: что строим

Community Pulse API — production-grade REST API для сбора мнений сообщества: вопросы, ответы и агрегированная статистика. Проект продолжает код из уроков 09–11 и доводит его до уровня реального приложения.

Стек: Flask 3.x · SQLAlchemy 2.x (Mapped/mapped_column) · Flask-Migrate · Pydantic v2
Результат: работающий API с миграциями, валидацией, blueprints, статистикой, обработкой ошибок и конфигом для prod
Закрывает: callout-verify из уроков 09 (FLASK_ENV, Mapped в Flask-SQLAlchemy) и 11 (фильтрация request.args/ilike)

Время прохождения: ~4–5 часов (7 этапов по 30–45 минут каждый).

📖 О проекте

Community Pulse API — REST API для сбора мнений сообщества. Пользователи задают вопросы и голосуют «за» или «против». API возвращает вопросы, принимает голоса и считает агрегированную статистику. Это типичная задача для опросных платформ, инструментов обратной связи и продуктовых метрик.

Серия берёт за основу код, написанный в уроках 09–11 (базовый Flask + SQLAlchemy + Pydantic), и поднимает его до уровня реального проекта: добавляет Flask-Migrate, современный API SQLAlchemy 2.x (Mapped/mapped_column), строгую валидацию через Pydantic v2, централизованную обработку ошибок, логирование и конфиг для продакшна.

Что закрывает этот капстоун

В ходе основного курса ряд тем был помечен callout-verify — сложные места, требующие практики в реальном проекте. Данная серия закрывает:

Урок 09 — Flask Project — правильный config-класс (убираем устаревший FLASK_ENV), современный синтаксис Mapped[T] / mapped_column() вместо старого db.Column()
Урок 11 — Flask Project 2 — правильная фильтрация через request.args и ilike(), надёжная обработка 404/422 через error handlers

Технологический стек

Flask 3.x Веб-фреймворк, application factory, blueprints

SQLAlchemy 2.x ORM, Mapped/mapped_column, современные запросы

Flask-SQLAlchemy Интеграция SQLAlchemy с Flask app context

Flask-Migrate Управление миграциями через Alembic

Pydantic v2 Валидация входных данных, сериализация ответов

SQLite / PostgreSQL SQLite для dev, PostgreSQL для prod

📋 Этапы серии

Каждый этап продолжает проект предыдущего. Проходить строго по порядку.

Структура и настройка

Создаём venv, устанавливаем зависимости, описываем структуру директорий, пишем application factory и config-классы без устаревшего FLASK_ENV.

⏱️ ~30 мин 📄 config.py · app/__init__.py · run.py

База данных и миграции

Подключаем Flask-SQLAlchemy и Flask-Migrate, инициализируем расширения, запускаем flask db init / migrate / upgrade, создаём первую миграцию.

⏱️ ~30 мин 📄 app/__init__.py · migrations/

Модели и связи

Описываем модели Question и Response с современным синтаксисом SQLAlchemy 2.x: Mapped[T], mapped_column(), relationship().

⏱️ ~35 мин 📄 app/models/question.py · app/models/response.py · app/models/__init__.py

Pydantic-схемы

Пишем схемы Pydantic v2 для валидации входа и сериализации выхода. model_config = ConfigDict(from_attributes=True) для чтения ORM-объектов.

⏱️ ~30 мин 📄 app/schemas/question.py · app/schemas/response.py · app/schemas/__init__.py

Blueprints и CRUD

Создаём blueprints для вопросов и ответов, реализуем все CRUD-эндпоинты, регистрируем blueprints в factory. Фильтрация через request.args и ilike().

⏱️ ~45 мин 📄 app/api/questions.py · app/api/responses.py · app/api/__init__.py

Статистика и обработка ошибок

Добавляем эндпоинт агрегированной статистики через func.count(), регистрируем централизованные error handlers для 404/422/500, правильные статус-коды.

⏱️ ~40 мин 📄 app/api/stats.py · app/errors.py

Логирование, prod-конфиг и финальная проверка

Настраиваем логирование через Python logging, production-конфиг (переменные окружения), прогоняем API через Postman, проходим финальный чеклист проекта.

⏱️ ~40 мин 📄 config.py · app/__init__.py · .env.example

📚 Что понадобится

Необходимые знания и инструменты:

Урок 05 — SQLAlchemy: модели и поля — ORM, модели, типы
Урок 06 — SQLAlchemy: связи — ForeignKey, relationship
Урок 01 — Flask: основы — routes, request, jsonify
Урок 09 — Flask: проект — application factory, blueprints
Урок 11 — Flask: проект 2 — полный CRUD, Pydantic в Flask
Python 3.10+, установленный pip и venv
Git (базовые команды: init, add, commit)
Postman или curl для тестирования API

🚀 Как работать с серией

Проходите этапы строго по порядку — каждый продолжает код предыдущего.
Перед каждым этапом: прочитайте секцию «Цель» и «Затрагиваемые файлы».
Над каждым блоком кода указан путь к файлу — не гадайте, куда писать.
После каждого этапа: выполните шаги из раздела «Проверка».
Если что-то пошло не так — секция «Проверка» содержит диагностику.

Важно: Не пропускайте этапы и не меняйте порядок. Структура файлов, которую создаёте на шаге 1, используется на шагах 2, 3 и далее.

Связь с уроками 09–11: Этот капстоун не переписывает уроки — он их расширяет. Код из уроков 09–11 переосмыслен: добавлен Flask-Migrate (которого раньше не было), модели переведены на современный синтаксис Mapped, обработка ошибок сделана централизованной.