FastAPI Service Template

Минимальный, аккуратно собранный шаблон backend-сервиса на FastAPI: HTTP API, env-настройки, health-checks, миграции, тесты, Docker и Kubernetes.

Быстрый старт · Команды · Конфигурация · API · Структура

Что внутри

Компонент	Назначение
FastAPI + Granian	ASGI-приложение и локальный запуск сервиса
Pydantic Settings	Конфигурация из env и .env
SQLAlchemy + Alembic	База данных, metadata и миграции
Pytest + coverage	Тесты приложения и отчёт покрытия
Docker	Сборка и локальный запуск контейнера
Kubernetes	Базовые манифесты для деплоя и jobs

Быстрый старт

uv sync
uv run python -m app

Сервис будет доступен на http://localhost:8000.

curl http://localhost:8000/health
curl http://localhost:8000/healthz

{"status": "ok"}
{"message": "pong"}

Команды

make test                         # pytest + coverage по app/
make linter                       # ruff check --fix . + ruff format .
make build                        # lock, clean, test, linter
make migrate-create msg="change"  # создать Alembic migration
make migrate-apply                # применить миграции
make service                      # собрать и запустить Docker container

Конфигурация

Настройки читаются из переменных окружения и .env.

SERVICE_NAME=fastapi-service
VERSION=0.1.0
ENVIRONMENT=development
LOG_LEVEL=info
HOST=0.0.0.0
PORT=8000
RELOAD=false
CORS_ORIGINS=["*"]
RUN_MIGRATIONS_ON_STARTUP=false
DATABASE_URL=postgresql+psycopg://user:pass@localhost:5432/service_db

RUN_MIGRATIONS_ON_STARTUP=true запускает alembic upgrade head при старте приложения. Для production обычно лучше выносить миграции в отдельный job.

API

Метод	Путь	Ответ
GET	/health	{"status": "ok"}
GET	/healthz	{"message": "pong"}
GET	/docs	Swagger UI
GET	/openapi.json	OpenAPI schema

Структура

app/
  __main__.py       local Granian entrypoint
  asgi.py           ASGI target: app.asgi:app
  application.py    FastAPI app factory, CORS, lifespan
  settings.py       env config via pydantic-settings
  db.py             SQLAlchemy DeclarativeBase
  migrations.py     Alembic upgrade helper
  routers/          API routers
docs/               project documentation
migrations/         Alembic environment and revisions
tests/              pytest suite
k8s/                Kubernetes manifests
scripts/            service helper scripts

Разработка

Новые endpoints добавляйте в app/routers/. Бизнес-логику держите отдельно от router-функций, а новые SQLAlchemy-модели импортируйте в app/models.py, чтобы Alembic видел metadata при --autogenerate.

Перед PR:

make test
make linter

Документация

Полная документация проекта: docs/project.md.