Andrey
d2d7c83575
Обновлены пути к библиотекам в Dockerfile для соответствия новой версии Python. Исправлены все тесты, теперь все проходят
89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
---
|
||
description: "Архитектурные паттерны и структура проекта Telegram бота на aiogram"
|
||
alwaysApply: true
|
||
---
|
||
|
||
# Архитектура проекта
|
||
|
||
Этот проект - Telegram бот на **aiogram 3.10.0** с четкой архитектурой и разделением ответственности.
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
helper_bot/
|
||
├── handlers/ # Обработчики событий (admin, callback, group, private, voice)
|
||
│ ├── services.py # Бизнес-логика для каждого модуля
|
||
│ ├── exceptions.py # Кастомные исключения модуля
|
||
│ └── dependencies.py # Dependency injection для модуля
|
||
├── middlewares/ # Middleware для cross-cutting concerns
|
||
├── utils/ # Утилиты и вспомогательные функции
|
||
├── keyboards/ # Клавиатуры для бота
|
||
└── filters/ # Кастомные фильтры
|
||
|
||
database/
|
||
├── repositories/ # Репозитории для работы с БД (Repository pattern)
|
||
├── models.py # Модели данных
|
||
├── base.py # Базовый класс DatabaseConnection
|
||
└── async_db.py # AsyncBotDB - основной интерфейс к БД
|
||
```
|
||
|
||
## Архитектурные паттерны
|
||
|
||
### 1. Repository Pattern
|
||
- Все операции с БД выполняются через репозитории в `database/repositories/`
|
||
- Каждая сущность имеет свой репозиторий (UserRepository, PostRepository, etc.)
|
||
- Репозитории наследуются от `DatabaseConnection` из `database/base.py`
|
||
- Используется `RepositoryFactory` для создания репозиториев
|
||
|
||
### 2. Service Layer Pattern
|
||
- Бизнес-логика вынесена в сервисы (`handlers/*/services.py`)
|
||
- Handlers только обрабатывают события и вызывают сервисы
|
||
- Сервисы работают с репозиториями через `AsyncBotDB`
|
||
|
||
### 3. Dependency Injection
|
||
- Используется `BaseDependencyFactory` для управления зависимостями
|
||
- Глобальный экземпляр доступен через `get_global_instance()`
|
||
- Зависимости внедряются через `DependenciesMiddleware`
|
||
- Для каждого модуля handlers может быть свой `dependencies.py` с фабриками
|
||
|
||
### 4. Middleware Pattern
|
||
- Middleware регистрируются в `main.py` на уровне dispatcher
|
||
- Порядок регистрации важен: DependenciesMiddleware → MetricsMiddleware → BlacklistMiddleware → RateLimitMiddleware
|
||
- Middleware обрабатывают cross-cutting concerns (логирование, метрики, rate limiting)
|
||
|
||
## Принципы
|
||
|
||
1. **Разделение ответственности**: Handlers → Services → Repositories
|
||
2. **Асинхронность**: Все операции с БД и API асинхронные
|
||
3. **Типизация**: Используются type hints везде, где возможно
|
||
4. **Логирование**: Всегда через `logs.custom_logger.logger`
|
||
5. **Метрики**: Декораторы `@track_time`, `@track_errors`, `@db_query_time` для мониторинга
|
||
|
||
## Версия Python
|
||
|
||
Проект использует **Python 3.11.9** во всех окружениях:
|
||
- Локальная разработка: Python 3.11.9 (указана в `.python-version`)
|
||
- Docker (production): Python 3.11.9-alpine (указана в `Dockerfile`)
|
||
- Минимальная версия: Python 3.11 (указана в `pyproject.toml`)
|
||
|
||
**Важно:**
|
||
- При написании кода можно использовать фичи Python 3.11
|
||
- Доступны улучшенные type hints, match/case (Python 3.10+)
|
||
- Используйте type hints везде, где возможно
|
||
- `@dataclass` доступен (Python 3.7+)
|
||
|
||
**Структура проекта:**
|
||
- Docker файлы находятся в двух местах:
|
||
- `/prod/Dockerfile` - для инфраструктуры (Python 3.11.9-alpine)
|
||
- `/prod/bots/telegram-helper-bot/Dockerfile` - для бота (Python 3.11.9-alpine)
|
||
- При обновлении версии Python нужно обновить оба Dockerfile
|
||
|
||
**Для локальной разработки:**
|
||
Рекомендуется использовать `pyenv` для установки Python 3.11.9:
|
||
```bash
|
||
pyenv install 3.11.9
|
||
pyenv local 3.11.9
|
||
```
|
||
|
||
Подробнее см. `docs/PYTHON_VERSION_MANAGEMENT.md`
|