KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

fastapi_base

★ 141 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Базовый шаблон проекта для 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 и т.д.

### Пример проекта
Структура проекта, где файлы разбиты по приложениям проекта. 
- [Пример](./examples/app_support_2)

### Пример структуры проекта
```
├── 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](https://python-poetry.org/docs/)
- 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)

fastapi_base

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README