AI Web Backend

Надежное, масштабируемое бэкенд-приложение, построенное на принципах Clean Architecture с использованием внедрения зависимостей, SOLID и современных практик Python.

Содержание

• Обзор архитектуры
• Структура проекта
• Паттерны проектирования
• Используемые технологии
• Установка и настройка
• Рабочий процесс разработки
• Тестирование
• Развертывание

Обзор архитектуры

Проект реализует Clean Architecture с четырьмя основными слоями:

1. Domain Layer (внутренний) - Содержит бизнес-сущности, бизнес-правила и интерфейсы
2. Application Layer - Реализует сценарии использования с помощью доменных сущностей
3. Infrastructure Layer - Реализует интерфейсы, определенные в доменном слое
4. Presentation Layer - Обрабатывает HTTP запросы/ответы и сериализацию

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

./
├── alembic.ini
├── docker-compose.yml
├── Dockerfile
├── Makefile
├── requirements.txt
├── simple_architecture_design.png
└── src/
    ├── application/         # Сервисы приложения, реализующие сценарии использования
    │   ├── analytics_service.py
    │   ├── request_service.py
    │   └── user_service.py
    ├── bootstrap/           # Компоненты начальной загрузки и точка входа
    │   ├── configs.py       # Конфигурация приложения
    │   ├── di_container.py  # Контейнер внедрения зависимостей
    │   ├── log.py          # Конфигурация логирования
    │   └── main.py         # Главная точка входа
    ├── domain/             # Бизнес-сущности и правила
    │   ├── entities/       # Доменные модели
    │   ├── exceptions/     # Доменные исключения
    │   └── interfaces/     # Порты для приложения
    ├── infra/              # Реализации инфраструктуры
    │   ├── db/            # Реализации баз данных
    │   │   ├── cache/     # Redis кэш
    │   │   ├── mongo_db/  # Реализация MongoDB
    │   │   └── postgres/  # Реализация PostgreSQL
    │   ├── llm_provider/  # Реализация LLM провайдера
    │   ├── prometheus/    # Мониторинг с Prometheus
    │   └── security/      # Реализации безопасности
    └── presentation/      # API эндпоинты и схемы
        ├── api/           # API маршруты
        └── schemas/       # Схемы запросов/ответов
└── tests/                # Директория тестов
    ├── shared.py
    ├── test_analytics.py
    ├── test_request.py
    └── test_user.py

Паттерны проектирования

1. Внедрение зависимостей

Используется для:

• Разделения компонентов
• Упрощения тестирования через mock-объекты
• Централизации конфигурации
• Обеспечения принципов Clean Architecture

Реализация: DIContainer в bootstrap/di_container.py управляет всеми зависимостями и их жизненным циклом.

2. Паттерн Repository

Абстрагирует логику доступа к данным:

• Предоставляет интерфейс коллекции для доменных объектов
• Отделяет домен от механизмов хранения данных
• Упрощает тестирование через мокирование

Реализация: Репозитории в infra/db/postgres/repositories/ реализуют соответствующие доменные интерфейсы.

3. Паттерн Unit of Work

Управляет границами транзакций:

• Координирует множественные операции репозитория в одной транзакции
• Обеспечивает атомарность
• Упрощает управление транзакциями в сервисах приложения

Реализация: SQLAlchemyUnitOfWork в infra/db/postgres/uow.py

4. Паттерн Factory

Используется для создания сложных объектов:

• Централизует логику создания
• Инкапсулирует сложность инициализации
• Упрощает клиентский код

Реализация: Используется в DI контейнере для создания сервисов и репозиториев.

Используемые технологии

База данных

• PostgreSQL: Основная реляционная база данных для структурированных данных
  • Выбрана за ACID-совместимость, надежность и богатый набор функций
• MongoDB: Для аналитических данных и полуструктурированной информации
  • Подходит для большого объема аналитических данных без жесткой схемы
• Redis: Для кэширования
  • Улучшает производительность, снижая нагрузку на базу данных

API Framework

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

Аутентификация

• JWT: Stateless аутентификация
  • Масштабируемый подход к аутентификации для распределенных систем
  • Минимальное управление состоянием на бэкенде

Внедрение зависимостей

• dependency-injector: Python DI контейнер
  • Обеспечивает слабую связность компонентов
  • Упрощает тестирование с mock-объектами

Мониторинг

• Prometheus: Для сбора метрик и мониторинга
  • Промышленный стандарт для наблюдаемости
  • Богатая экосистема инструментов и интеграций

LLM провайдер

• Ollama: Для AI/LLM возможностей
  • Предоставляет гибкий доступ к языковым моделям
  • Легко заменяется другими провайдерами

Установка и настройка

Шаги установки

1. Клонирование репозитория:

   git clone <repository-url>
   cd ai_web

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

   python -m venv venv
   source venv/bin/activate  # На Windows: venv\Scripts\activate

3. Установка зависимостей:

   pip install -r requirements.txt

4. Запуск с Docker Compose:

   docker-compose up -d

Рабочий процесс разработки

Организация кода

• Следование структуре проекта
• Разделение слоев и соблюдение правила зависимостей
• Использование интерфейсов для определения границ между слоями

Добавление новых функций

1. Определение сущностей и интерфейсов в доменном слое
2. Реализация сценариев использования в слое приложения
3. Создание реализаций инфраструктуры
4. Добавление API эндпоинтов в презентационный слой

Миграции базы данных

Используйте Alembic для миграций схемы PostgreSQL:

make migrate

Тестирование

Unitстирование

• Тестирование доменных сущностей и сервисов приложения в изоляции
• Использование mock-объектов для внешних зависимостей

 PYTHONPATH=src pytest -p no:warnings

Тестирование

• Тестирование репозиториев с реальными базами данных

Развертывание

Docker развертывание

Приложение контейнеризировано и может быть развернуто с помощью Docker Compose:

docker-compose up -d

make run