Goods API

🇷🇺 Описание (Russian)

Goods API — учебный / pet-проект backend-сервиса для работы с товарами. Проект демонстрирует типичную архитектуру API-приложения на Python с разделением на домены, конфигурацию, инфраструктуру и деплой.

Цель проекта:

• отработать структуру backend-приложения
• показать работу с БД
• подготовить сервис к контейнеризации и деплою
• приблизиться к real-world backend разработке
• реализовать полноценный мониторинг и логирование

---

🚀 Возможности

• REST API для работы с товарами
• Чёткое разделение слоёв (routers / models / database)
• Конфигурация через YAML
• Docker и docker-compose
• Kubernetes manifests
• Terraform конфигурация
• Poetry для управления зависимостями
• Встроенные метрики Prometheus
• Готовность к интеграции с Grafana и Loki

---

📂 Структура проекта (обновлённая)

.
├── api_deployment.yml
├── api_service.yml
├── app
│   ├── config
│   │   └── conf.py
│   ├── database
│   │   ├── db.py
│   │   └── __init__.py
│   ├── goods
│   │   ├── __init__.py
│   │   ├── models
│   │   │   ├── goods.py
│   │   │   └── __init__.py
│   │   └── routers
│   │       ├── goods.py
│   │       └── __init__.py
│   ├── __init__.py
│   ├── metrics
│   │   ├── goods.py
│   │   ├── http.py
│   │   └── __init__.py
│   └── middleware
│       └── prometheus.py
├── db_config.yml
├── db_secrets_example.yml
├── docker-compose.yml
├── Dockerfile
├── init-db.sh
├── LICENSE
├── main.py
├── main.tf
├── mixed-load.sh
├── monitoring
│   └── prometheus
│       └── prometheus.yml
├── poetry.lock
├── postgres_pvc.yml
├── postgres_service.yml
├── postgres_stateful.yml
├── pyproject.toml
└── README.md

---

✅ План развития проекта (Roadmap)

• Добавлен Prometheus для сбора метрик

  • Метрики HTTP запросов (количество, длительность, статусы)
  • Бизнес-метрики товаров (количество созданных/обновлённых товаров)
  • Эндпоинт /metrics для сбора данных Prometheus
  • Middleware для автоматического сбора HTTP метрик

• Добавить дашборд Grafana для визуализации метрик

  • Создать готовые дашборды для:
    • Мониторинга состояния API (HTTP метрики)
    • Бизнес-метрик товаров
    • Мониторинга здоровья базы данных
  • Настроить алерты на основе метрик
  • Добавить конфигурацию Grafana в docker-compose и Kubernetes

• Реализовать логирование с помощью Loki + Promtail

  • Настроить сбор логов приложения
  • Интегрировать с Grafana для единого интерфейса
  • Создать дашборды для анализа логов
  • Реализовать структурированное логирование (JSON-формат)

• Настроить алертинг

  • Создать правила алертинга в Prometheus
  • Интегрировать с Alertmanager
  • Настроить уведомления (email, Slack, Telegram)

---

🐳 Запуск через Docker (с метриками)

docker-compose up --build

После запуска API будет доступен:

• Основное API: http://localhost:8000
• Документация Swagger: http://localhost:8000/docs
• Метрики Prometheus: http://localhost:8000/metrics
• Дашборд Grafana: http://localhost:3000

---

📊 Метрики Prometheus

Сервис предоставляет следующие метрики:

HTTP метрики

• http_requests_total - общее количество HTTP запросов
• http_request_duration_seconds - длительность HTTP запросов
• http_requests_in_progress - текущие выполняющиеся запросы

Бизнес метрики товаров

• goods_created_total - количество созданных товаров
• goods_updated_total - количество обновлённых товаров
• goods_operations_total - общее количество операций с товарами

---

☸ Kubernetes

В репозитории присутствуют манифесты для деплоя:

• API
• PostgreSQL (StatefulSet + PVC + Service)

Файлы:

• api_deployment.yml
• api_service.yml
• postgres_stateful.yml
• postgres_pvc.yml
• postgres_service.yml

---

🧱 Terraform

Файл main.tf содержит базовую Terraform-конфигурацию и может быть использован для развёртывания инфраструктуры (в зависимости от выбранного провайдера).

---

🔐 Secrets

⚠️ Важно

Файл db_secrets.yml:

• содержит чувствительные данные
• не должен быть закоммичен
• используется только локально или через CI/CD

В репозитории хранится только:

db_secrets_example.yml

---

🛠 Технологии

• Python
• FastAPI (или аналогичный ASGI-фреймворк)
• PostgreSQL
• Prometheus (метрики)
• Docker / Docker Compose
• Kubernetes
• Terraform
• Poetry

---

📌 Статус проекта

Проект находится в активной разработке. Реализовано:

• Базовая структура API
• Работа с базой данных
• Контейнеризация (Docker)
• Конфигурация Kubernetes
• Метрики Prometheus
• Дашборды Grafana
• Логирование Loki+Promtail
• Полное мониторинговое решение

Используется как:

• учебный проект
• playground для backend / DevOps практик
• пример реализации мониторинга в Python приложениях

---