{"id":16229328,"url":"https://github.com/djwoms/fastapi_base","last_synced_at":"2025-10-05T04:36:28.411Z","repository":{"id":195859186,"uuid":"693826199","full_name":"DJWOMS/fastapi_base","owner":"DJWOMS","description":"Базовый шаблон проекта для FastAPI","archived":false,"fork":false,"pushed_at":"2023-11-02T09:45:19.000Z","size":404,"stargazers_count":109,"open_issues_count":0,"forks_count":14,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-03T03:13:06.567Z","etag":null,"topics":["fastapi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DJWOMS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-19T19:42:15.000Z","updated_at":"2025-04-01T17:45:24.000Z","dependencies_parsed_at":"2024-10-27T20:36:22.832Z","dependency_job_id":"0e38d641-71d9-4dad-b709-9665ddef6f79","html_url":"https://github.com/DJWOMS/fastapi_base","commit_stats":null,"previous_names":["djwoms/fastapi_base"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DJWOMS/fastapi_base","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJWOMS%2Ffastapi_base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJWOMS%2Ffastapi_base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJWOMS%2Ffastapi_base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJWOMS%2Ffastapi_base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DJWOMS","download_url":"https://codeload.github.com/DJWOMS/fastapi_base/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJWOMS%2Ffastapi_base/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271599790,"owners_count":24787801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi"],"created_at":"2024-10-10T12:58:03.775Z","updated_at":"2025-10-05T04:36:23.372Z","avatar_url":"https://github.com/DJWOMS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Базовый шаблон проекта для FastAPI\n\n## Общее описание\n\n\u003cimg src=\"/examples/uow.jpg\"/\u003e\n\nПримеры приведенные ниже, подсказывают как можно организовать структуру проекта FastAPI.\n\nТак же предложен вариант использования паттернов Dependency Injection и Unit of Work.\nПринцип заключается в том, чтобы разделить логику и код на слои. \n\nЧто позволит иметь:\n- более поддерживаемую и понятную структуру проекта\n- масштабирование и переиспользование кода\n- возможность тестирования отдельных частей проекта\n\n## О слоях\n\n### Контроллеры \nКонтроллеры мы можем называть по разному: `routers`, `endpoints`, `controllers`.\n\nКонтроллеры отвечают за запрос\\ответ. Можно сказать что они должны быть \"тупые\", не иметь бизнес-логики.\nОни вызывают нужные зависимости: авторизация, проверка прав и т.д. Передают данные в сервис. Обрабатывают \n`HttpExceptions`.\n\nНужно использовать зависимости (`Depends`) так как они кешируются.\nЗависимости можно использовать повторно несколько раз — FastAPI по \nумолчанию кэширует результат зависимости в пределах области запроса, т.е. если у нас есть зависимость, \nкоторая вызывает сервис, мы не будем посещать БД каждый раз, когда вызываем эту \nзависимость — только первый вызов функции.\n\nЗная это, мы можем легко разделить зависимости на несколько более мелких функций, которые работают в \nменьшем домене и легче повторно использовать в других маршрутах.\n\n### Сервисы\nСервис отвечает за бизнес логику и взаимодействуют с репозиторием.\n\nЕсли в пределах одной сессии (в нашем случае SqlAlchemy) нужно взаимодействовать с несколькими репозиториями, то\nследует использовать Unit of Work.\n\n### Репозитории\nРепозиторий — это коллекция, которая содержит сущности, может фильтровать и возвращать\nрезультат обратно, в зависимости от требований нашего приложения. Где и как он хранит эти объекты, \nявляется ДЕТАЛЬЮ РЕАЛИЗАЦИИ.\n\nВ нашем случае репозиторий может взаимодействовать с базой данных, например Postgres, Redis, MongoDB.\n\n### Unit of Work\nЕсли сказать просто, UoW это класс, который объединяет репозитории.\n\nПаттерн Unit of Work помогает упростить работу с различными репозиториями и дает уверенность, что все \nрепозитории будут использовать один и тот же DbContext.\n\nТак же использование паттерна Репозиторий и UoW позволяет создать правильную структуру для развертывания \nприложения и внедрения DI, которые как минимум помогают в тестировании проекта.\n\n\n## Структура\nПриложение (app) - отдельная часть логики проекта. Содержит свои контроллеры, сервисы, репозитории,\nзависимости, модели, exceptions и т.д.\n\n### Пример проекта\nСтруктура проекта, где файлы разбиты по приложениям проекта. \n- [Пример](./examples/app_support_2)\n\n### Пример структуры проекта\n```\n├── migrations/\n├── src\n│   ├── config/\n│   │   ├── database\n│   │   │   ├── db_config.py\n│   │   │   └── db_helper.py\n│   │   └── project_config.py\n│   ├── support # app\n│   │   ├── support_controller.py\n│   │   ├── support_schema.py\n│   │   ├── dependencies.py\n│   │   ├── constants.py\n│   │   ├── exceptions.py\n│   │   ├── support_repository.py\n│   │   ├── support_service.py\n│   └── user # app\n│   ├── routes.py\n│   └── main.py\n├── tests/\n│   ├── users\n│   └── support\n├── pyproject.toml или requirements.txt\n├── .env\n├── .gitignore\n├── logging.ini\n└── alembic.ini\n```\n\n### Директории и файлы\n\n- migrations - директория alembic для миграций\n- migrations/versions - файлы миграций\n- migrations/base.py - файл с импортированными модулями моделей для работы автогенерации миграций\n- migrations/env.py - скрипт alembic для работы миграций\n- src/config - директория для общих настроек\n- src/config/database/db_config.py - настройки базы данных\n- src/config/database/db_helper.py - получение сессии базы данных\n- src/config/project_config.py - настройки для проекта\n- src - верхний уровень приложения, содержит общие маршруты, main.py и все приложения\n- src/main.py - корень проекта, который запускает приложение FastAPI\n- src/routes.py - общие routers для всех приложений проекта\n- src/interfaces - директория для классов интерфейсов\n- src/exceptions (errors) - классы exceptions\n- src/models - классы моделей SqlAlchemy\n- src/models/base_model - базовый класс SqlAlchemy\n- src/schemas - общие классы Pydantic\n- src/schemas/base_schema - класс базовой модели Pydantic, с настройкой для интеграция с ORM (Ранее известный \nкак \"ORM Mode\"/from_orm)\n- src/repositories - классы репозиториев\n- src/repositories/base_repository - класс базового repository\n- src/repositories/sqlalchemy_repository - класс базового repository для SqlAlchemy\n- src/repositories/uow - реализация Unit of Work для использования нескольких репозиториев в одной \nсессии SqlAlchemy\n- src/services - базовые классы сервисов\n- src/services/generic_service - класс generic для сервисов\n- src/services/base_service - базовый класс сервиса (CRUD) для взаимодействия с repository\n- tests - тесты проекта\n- .env - переменные окружения\n- .env.example - пример (шаблон) для файла .env\n- pyproject.toml - файл зависимостей для [poetry](https://python-poetry.org/docs/)\n- poetry.lock - обеспечить согласованность между текущими установленными зависимостями и \nтеми, которые вы указали в файле pyproject.toml\n- requirements.txt - файл зависимостей для pip\n\n### Файлы приложения\n\n- prefix_repository.py - работа с БД (Postgres, Redis, MongoDB и т.д.)\n- prefix_service.py - специфичная для модуля бизнес-логика\n- prefix_schema.py - pydantic модели\n- routers.py - общие routers для всех контроллеров (endpoints, api) модуля\n- dependencies.py - зависимости для приложения\n- exceptions.py - специфические для модуля исключения\n- constants.py - константы\n\n## Соглашения\n\n- Поддерживаем плоскую структуру\n- Избегаем длинных названий файлов и используем _ (user_service.py)\n- Приложение называем в единственном числе (session, user)\n- Сущности более одной собираются в папки (services, schemas)\n- Поддерживаем цепочку Controller - Service - Repository\n- Sharеd сущности выносим вне контекстов (entities, repositories)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjwoms%2Ffastapi_base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjwoms%2Ffastapi_base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjwoms%2Ffastapi_base/lists"}