Базовый шаблон проекта для FastAPI

Общее описание

Примеры приведенные ниже, подсказывают как можно организовать структуру проекта FastAPI.

Так же предложен вариант использования паттернов Dependency Injection и Unit of Work. Принцип заключается в том, чтобы разделить логику и код на слои.

Что позволит иметь:

более поддерживаемую и понятную структуру проекта
масштабирование и переиспользование кода
возможность тестирования отдельных частей проекта

О слоях

Контроллеры

Контроллеры мы можем называть по разному: routers, endpoints, controllers.

Контроллеры отвечают за запрос\ответ. Можно сказать что они должны быть "тупые", не иметь бизнес-логики. Они вызывают нужные зависимости: авторизация, проверка прав и т.д. Передают данные в сервис. Обрабатывают HttpExceptions.

Нужно использовать зависимости (Depends) так как они кешируются. Зависимости можно использовать повторно несколько раз — FastAPI по умолчанию кэширует результат зависимости в пределах области запроса, т.е. если у нас есть зависимость, которая вызывает сервис, мы не будем посещать БД каждый раз, когда вызываем эту зависимость — только первый вызов функции.

Зная это, мы можем легко разделить зависимости на несколько более мелких функций, которые работают в меньшем домене и легче повторно использовать в других маршрутах.

Сервисы

Сервис отвечает за бизнес логику и взаимодействуют с репозиторием.

Если в пределах одной сессии (в нашем случае SqlAlchemy) нужно взаимодействовать с несколькими репозиториями, то следует использовать Unit of Work.

Репозитории

Репозиторий — это коллекция, которая содержит сущности, может фильтровать и возвращать результат обратно, в зависимости от требований нашего приложения. Где и как он хранит эти объекты, является ДЕТАЛЬЮ РЕАЛИЗАЦИИ.

В нашем случае репозиторий может взаимодействовать с базой данных, например Postgres, Redis, MongoDB.

Unit of Work

Если сказать просто, UoW это класс, который объединяет репозитории.

Паттерн 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)

maxim-zaitsev/fastapi_base