Примеры приведенные ниже, подсказывают как можно организовать структуру проекта FastAPI.
Так же предложен вариант использования паттернов Dependency Injection и Unit of Work. Принцип заключается в том, чтобы разделить логику и код на слои.
Что позволит иметь:
- более поддерживаемую и понятную структуру проекта
- масштабирование и переиспользование кода
- возможность тестирования отдельных частей проекта
Контроллеры мы можем называть по разному: routers, endpoints, controllers.
Контроллеры отвечают за запрос\ответ. Можно сказать что они должны быть "тупые", не иметь бизнес-логики.
Они вызывают нужные зависимости: авторизация, проверка прав и т.д. Передают данные в сервис. Обрабатывают
HttpExceptions.
Нужно использовать зависимости (Depends) так как они кешируются.
Зависимости можно использовать повторно несколько раз — FastAPI по
умолчанию кэширует результат зависимости в пределах области запроса, т.е. если у нас есть зависимость,
которая вызывает сервис, мы не будем посещать БД каждый раз, когда вызываем эту
зависимость — только первый вызов функции.
Зная это, мы можем легко разделить зависимости на несколько более мелких функций, которые работают в меньшем домене и легче повторно использовать в других маршрутах.
Сервис отвечает за бизнес логику и взаимодействуют с репозиторием.
Если в пределах одной сессии (в нашем случае SqlAlchemy) нужно взаимодействовать с несколькими репозиториями, то следует использовать Unit of Work.
Репозиторий — это коллекция, которая содержит сущности, может фильтровать и возвращать результат обратно, в зависимости от требований нашего приложения. Где и как он хранит эти объекты, является ДЕТАЛЬЮ РЕАЛИЗАЦИИ.
В нашем случае репозиторий может взаимодействовать с базой данных, например Postgres, Redis, MongoDB.
Если сказать просто, UoW это класс, который объединяет репозитории.
П 7CE4 ттерн Unit of Work помогает упростить работу с различными репозиториями и дает уверенность, что все репозитории будут использовать один и тот же DbContext.
Так же использование паттерна Репозиторий и UoW позволяет создать правильную структуру для развертывания приложения и внедрения DI, которые как минимум помогают в тестировании проекта.
Приложение (app) - отдельная часть логики проекта. Содержит свои контроллеры, сервисы, репозитории, зависимости, модели, exceptions и т.д.
Структура проекта, где файлы разбиты по приложениям проекта.
├── migrations/
├── src
│ ├── config/
│ │ ├── database
│ │ │ ├── db_config.py
│ │ │ └── db_helper.py
│ │ └── project_config.py
│ ├── support # app
│ │ ├── support_controller.py
│ │ ├── support_schema.py
│ │ ├── dependencies.py
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ ├── support_repository.py
│ │ ├── support_service.py
│ └── user # app
│ ├── routes.py
│ └── main.py
├── tests/
│ ├── users
│ └── support
├── pyproject.toml или requirements.txt
├── .env
├── .gitignore
├── logging.ini
└── alembic.ini
- migrations - директория alembic для миграций
- migrations/versions - файлы миграций
- migrations/base.py - файл с импортированными модулями моделей для работы автогенерации миграций
- migrations/env.py - скрипт alembic для работы миграций
- src/config - директория для общих настроек
- src/config/database/db_config.py - настройки базы данных
- src/config/database/db_helper.py - получение сессии базы данных
- src/config/project_config.py - настройки для проекта
- src - верхний уровень приложения, содержит общие маршруты, main.py и все приложения
- src/main.py - корень проекта, который запускает приложение FastAPI
- src/routes.py - общие routers для всех приложений проекта
- src/interfaces - директория для классов интерфейсов
- src/exceptions (errors) - классы exceptions
- src/models - классы моделей SqlAlchemy
- src/models/base_model - базовый класс SqlAlchemy
- src/schemas - общие классы Pydantic
- src/schemas/base_schema - класс базовой модели Pydantic, с настройкой для интеграция с ORM (Ранее известный как "ORM Mode"/from_orm)
- src/repositories - классы репозиториев
- src/repositories/base_repository - класс базового repository
- src/repositories/sqlalchemy_repository - класс базового repository для SqlAlchemy
- src/repositories/uow - реализация Unit of Work для использования нескольких репозиториев в одной сессии SqlAlchemy
- src/services - базовые классы сервисов
- src/services/generic_service - класс generic для сервисов
- src/services/base_service - базовый класс сервиса (CRUD) для взаимодействия с repository
- tests - тесты проекта
- .env - переменные окружения
- .env.example - пример (шаблон) для файла .env
- pyproject.toml - файл зависимостей для poetry
- poetry.lock - обеспечить согласованность между текущими установленными зависимостями и теми, которые вы указали в файле pyproject.toml
- requirements.txt - файл зависимостей для pip
- prefix_repository.py - работа с БД (Postgres, Redis, MongoDB и т.д.)
- prefix_service.py - специфичная для модуля бизнес-логика
- prefix_schema.py - pydantic модели
- routers.py - общие routers для всех контроллеров (endpoints, api) модуля
- dependencies.py - зависимости для приложения
- exceptions.py - специфические для модуля исключения
- constants.py - константы
- Поддерживаем плоскую структуру
- Избегаем длинных названий файлов и используем _ (user_service.py)
- Приложение называем в единственном числе (session, user)
- Сущности более одной собираются в папки (services, schemas)
- Поддерживаем цепочку Controller - Service - Repository
- Sharеd сущности выносим вне контекстов (entities, repositories)