FastAPI Template

Оглавление

• Разворачивание проекта
  • Зависимости
  • Окружение
  • Запуск в локальном окружении
  • Запуск в тестовом окружении
  • Запуск в прод окружении
  • После запуска
  • Возможные ошибки
• Стэк
  • Основные инструменты
  • Другие библиотеки / интеграции
• Запуск тестов
  • Внутри Docker-контейнера (рекомендуется)
  • Вне Docker-контейнера
• Запуск flake8
  • Внутри Docker-контейнера (рекомендуется)
  • Вне Docker-контейнера
• Запуск mypy
  • Внутри Docker-контейнера (рекомендуется)
  • Вне Docker-контейнера
• Разработка
  • Форматирование кода
  • Git хуки

Разворачивание проекта

Зависимости

• docker
• docker compose
• python 3.8+ (опционально, для локального запуска pytest/flake8/mypy)
• poetry (опционально, для локального запуска pytest/flake8/mypy)

Окружение

Перед запуском контейнеров, необходимо убедиться, что директории docker присутствует файл .env, в котором заполнены все необходимые переменные окружения.
Названия этих переменных можно посмотреть в .env.example

Подробное описание переменных окружения

REGISTRY

Ссылка на container registry. Необходимо заполнить, если используется compose файл с указанными image для кастомных сборок (например, docker-compose.main.yml)

ENVIRONMENT

Окружение (development, production, testing, etc). Может быть использовано для различных нужд в рамках проекта

PROJECT_NAME

Название проекта

SECRET_KEY

Секретный ключ для FastAPI

DEBUG

Режим отладки
0 - выключен
1 - включен
Если включен, то:

• 500 ошибки сервера не будут обработаны обработчиком исключений
• В логах будут отображаться запросы в БД, генерируемые в рамках запроса

PROD

Режим прод окружения
0 - выключен
1 - включен
Если выключен, то:

• Будет доступна документация swagger-ui/redoc
• Работа с платежными системами будет работать в боевом режиме
• Чувствительные данные будут исключены из логов

MEDIA_PATH

Путь к директории, в которой хранятся медиа-файлы

MEDIA_URL

Префикс в ссылке для медиа-файлов

STATIC_PATH

Путь к директории, в которой хранятся статические файлы

STATIC_URL

Префикс в ссылке для статических-файлов

LOG_PATH

Путь к директории, в которой хранятся лог-файлы

IN_GUNICORN

Флаг, который определяет, запускается ли проект через gunicorn

Database

При первом запуске DB_NAME, DB_USER, DB_PASSWORD могут быть любыми
При дальнейших запусках DB_NAME, DB_USER, DB_PASSWORD должны быть такими же, как при первом запуске
DB_HOST должен соответствовать названию сервиса БД из compose конфигурации
DB_PORT должен соответствовать порту БД из compose конфигурации

Nginx

NGINX_OUTER_PORT - порт, через который можно обращаться к контейнеру nginx
NGINX_INNER_PORT - порт, на который будут переадресовываться все запросы внутри контейнера nginx

ASGI

ASGI_PORT - порт, по которому можно обращаться к asgi сервису

RabbitMQ

RABBITMQ_HOST должен соответствовать названию сервиса RabbitMQ из compose конфигурации
RABBITMQ_PORT - любой доступный на хосте порт
При первом запуске RABBITMQ_USER, RABBITMQ_PASSWORD могут быть любыми
При дальнейших запусках RABBITMQ_USER, RABBITMQ_PASSWORD должны быть такими же, как при первом запуске

Celery

CELERY_BROKER_URL - ссылка для доступа к брокеру сообщений
CELERY_RESULT_BACKEND - бэкенд для хранения результатов выполнения задач

Redis

REDIS_HOST должен соответствовать названию сервиса Redis из compose конфигурации
REDIS_PORT - любой доступный на хосте порт
REDIS_PASSWORD - пароль от пользователя default

Logging

LOGGING_SENSITIVE_FIELDS - чувствительные поля, которые нужно игнорировать при записи лога. Должны быть разделены через запятую, без пробелов
LOGGING_LOGGERS - названия логеров. Должны быть разделены через запятую, без пробелов
LOGGING_MAX_BYTES - максимальное кол-во байт на один лог файл
LOGGING_BACKUP_COUNT - максимальное кол-во бэкап файлов для логов

Docker Compose Specific

RESTART_POLICY - политика рестарта контейнеров
NGINX_VERSION - версия Nginx
POSTGRES_VERSION - версия PostgreSQL
REDIS_VERSION - версия Redis
RABBITMQ_VERSION - версия Rabbitmq
ASGI_TARGET - образ для сборки asgi сервиса
CELERY_TARGET - образ для сборки celery worker сервиса
BEAT_TARGET - образ для сборки celery beat сервиса
*_CPUS - лимит ядер на контейнер
*_MEM_LIMIT - лимит памяти на контейнер
*_MEM_RESERVATION - запас памяти на контейнер

Запуск в локальном окружении

docker-compose -f docker/docker-compose.yml -f docker/docker-compose.local.yml up

или

make localup

После запуска проект будет доступен по адресу http://localhost:.../

Запуск в тестовом окружении

docker-compose up

или

make up

Запуск в прод окружении

docker-compose -f docker/docker-compose.yml -f docker/docker-compose.main.yml up

или

make mainup

После запуска

Проект станет доступен по порту ${NGINX_OUTER_PORT}
В локальном окружении достаточно перейти по адресу http://localhost:${NGINX_OUTER_PORT}/
В другом окружении необходимо настроить домен, при обращении к которому веб-сервер (Nginx/Apache) будет проксировать все запросы на порт ${NGINX_OUTER_PORT}

Возможные ошибки

Если на хосте установлена docker compose версии >2, то может возникнуть ошибка синтаксиса команды. В таком случае в командах выше нужно заменить

docker-compose

на

docker compose

Стэк

Основные инструменты

• Используемый язык программирования — Python ...
• Используемый фреймворк — FastAPI ...
• Используемая СУБД — PostgreSQL ...
• Используемая для кэширования NoSQL БД — Redis ...
• Используемый брокер сообщений — RabbitMQ ...
• Используемая асинхронная очередь задач — Celery ...

Другие библиотеки / интеграции

• uvicorn (...) — HTTP-сервер для FastAPI
• psycopg (...) — библиотека для работы с PostgreSQL в Python
• redis (...) — библиотека для работы с Redis в Python
• Celery (...) — библиотека для асинхронных очередей задач
• amqp (...) — библиотека для работы с amqp-протоколом
• JSON-log-formatter (...) — библиотека для форматирования логов в JSON-формате
• dependency-injector (...) — библиотека для внедрения зависимостей (DI)
• pytest (...) — библиотека для тестирования
• pytest-cov (...) — библиотека для оценки покрытия кода тестами через pytest
• pytest-mock (...) — библиотека для мока зависимостей через pytest
• pytest-timeout (...) — библиотека для ограничения времени выполнения тестов через pytest
• concurrent-log-handler (...) — библиотека для последовательной записи логов в файлы при запуске веб приложения через несколько воркеров (как в uvicorn)
• mypy (...) — статический анализатор типов
• flake8 (...) — инструмент линтинга для Python
• black (...) — библиотека для форматирования кода на языке Python
• isort (...) - библиотека для сортировки импортов

Запуск тестов

Внутри Docker-контейнера (рекомендуется)

1. Зайти в контейнер asgi через команду

   docker exec -it ${PROJECT_NAME}-asgi bash

2. Начать выполнение тестов через команду

   pytest

или

make test

Вне Docker-контейнера

При таком запуске тесты, в которых тестируется работа с БД, выполнятся с ошибкой
При ошибке выполнения команды запустите тесты внутри Docker-контейнера

1. Перейти в директорию с конфигурационным файлом

2. Начать выполнение тестов через команду

   poetry run pytest

Запуск Flake8

Внутри Docker-контейнера (рекомендуется)

1. Зайти в контейнер asgi через команду

   docker exec -it ${PROJECT_NAME}-asgi bash

2. Начать выполнение flake8 через команду

   flake8 .

или

make flake8

Вне Docker-контейнера

1. Перейти в директорию с конфигурационным файлом

2. Начать выполнение flake8 через команду

   poetry run flake8 .

Запуск mypy

Внутри Docker-контейнера (рекомендуется)

1. Зайти в контейнер asgi через команду

   docker exec -it ${PROJECT_NAME}-asgi bash

2. Начать выполнение mypy через команду

   mypy .

или

make mypy

Вне Docker-контейнера

При возникновении ошибок запуск возможен только внутри Docker-контейнера

1. Перейти в директорию с конфигурационным файлом

2. Начать выполнение mypy через команду

   poetry run mypy .

Разработка

Форматирование кода

При разработке рекомендуется использовать black, чтобы поддерживать чистоту кода и избегать лишних изменений при работе с гитом.
Пример конфигурационного файла для Visual Studio Code .vscode/settings.json:

{
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": true
    }
}

Git хуки

При разработке рекомендуется использовать pre-commit, чтобы перед формированием МР код был уже подготовленным и поверхностно проверенным (например, через flake8)

Для использования должны быть установлены dev-зависимости

Pre-commit хуки

Установка

poetry run pre-commit install

Удаление

poetry run pre-commit uninstall

После установки, при каждом коммите будут отрабатывать хуки из конфигурационного файла, предназначенные для коммитов (stages: [commit])

Pre-push хуки

Установка

poetry run pre-commit install --hook-type pre-push

Удаление

poetry run pre-commit uninstall -t pre-push

После установки, при каждом пуше будут отрабатывать хуки из конфигурационного файла, предназначенные для пушей (stages: [push])

Git хуки

При разработке рекомендуется использовать pre-commit, чтобы перед формированием МР код был уже подготовленным и поверхностно проверенным (например, через flake8)

Для использования должны быть установлены dev-зависимости

Pre-commit хуки

Установка

poetry run pre-commit install

Удаление

poetry run pre-commit uninstall

После установки, при каждом коммите будут отрабатывать хуки из конфигурационного файла, предназначенные для коммитов (stages: [commit])

Pre-push хуки

Установка

poetry run pre-commit install --hook-type pre-push

Удаление

poetry run pre-commit uninstall -t pre-push

После установки, при каждом пуше будут отрабатывать хуки из конфигурационного файла, предназначенные для пушей (stages: [push])

Make

Для удобного запуска контейнеров, их сборки, запуска тестов и т.п. в проекте есть Makefile

Для выполнения инструкции, на примере запуска тестов, нужно выполнить команду

make test

Git Flow

Основные правила работы с ветками на проекте:

• develop — ветка разработки.
  • Собирается и разворачивается на dev-сервере;
• feature/{feature-slug} — feature-ветка.
  • Создается только из ветки develop;
  • По готовности создается MR в ветку develop.
• bugfix/{bug-slug} — bugfix-ветка.
  • Создается только из ветки develop;
  • По готовности создается MR в ветку develop.
• release/{major}.{minor} — release-ветка.
  • Создается только из ветки develop;
  • Считается как release-candidate;
  • Собирается и разворачивается на stage-сервере (пока не утверждено, как вариант);
  • Прямо в ветке могут быть пофикшены баги, без MR;
  • Все пофикшенные в ветке баги должны быть смержены в develop, желательно сразу по готовности бага, чтобы не упустить фикс;
  • По готовности создается MR в ветку main.
  • Правила изменения версии релиза:
    • minor версия увеличивается при изменениях, не нарушающих обратную совместимость. Т.е. при этих изменениях пользователи API продолжат работу без необходимости вносить изменения;
    • major версия увеличивается при изменениях, нарушающих обратную совместимость.
      • В идеале, major версия должна совпадать с последней версией API, т.к. новая версия API внедряется по такому же принципу - при появлении изменений, нарушающих обратную совместимость.
• hotfix/{bug-slug} — hotfix-ветка.
  • Создается только из ветки main;
  • По готовности создается MR в ветку main.
• main — прод ветка.
  • Собирается и разворачивается на prod-сервере;
  • После слияния MR в эту ветку создается tag и release по этой ветке (т.е. по последнему коммиту этой ветки).

CI/CD

Dev-сервер

TBD

Prod-сервер

TBD

Release ветки

TBD

Выпуск релиза

TBD

CHANGELOG.md

Заметки о релизах ведутся начиная с версии 1.0.0

По готовности релиза в release/* ветке или при хотфиксе в hotfix/* ветке, нужно обновить файл CHANGELOG.md.

Заметки о новом релизе добавляются в начало файла, т.е. до предыдущего релиза. Шаблон заметки о релизе

## 1.1.0 (2024-01-01)

Security:

  -   

Features:

  - 

Bugfixes:

  - 

При необходимости, можно вести заметки о будущем релизе прямо в ветке develop. В таком случае, вместо даты релиза нужно писать unreleased, который потом следует заменить на фактическую дату релиза

## 1.2.0 (unreleased)

Security:

  -   

Features:

  - 

Bugfixes:

  -