Асинхронный сервис процессинга платежей

Микросервис на FastAPI, SQLAlchemy 2 async, PostgreSQL, RabbitMQ (FastStream), Dishka, Alembic. Архитектура близка к NotificationService: слои controllers → domain (use cases, DTO, интерфейсы репозиториев) → gateways (ORM, репозитории, UoW), плюс services для интеграций (webhook, эмуляция шлюза, outbox relay).

Возможности

• POST /api/v1/payments — создание платежа (заголовки X-API-Key, Idempotency-Key), ответ 202 с payment_id, status, created_at.
• GET /api/v1/payments/{payment_id} — детали платежа.
• Outbox — запись события в таблицу outbox в одной транзакции с платежом; фоновый relay в процессе API публикует в очередь payments.new.
• Consumer — один обработчик: эмуляция шлюза (2–5 с, ~90% успех), обновление статуса, webhook с 3 попытками и экспоненциальной задержкой 1 с / 2 с / 4 с.
• Повтор обработки сообщения — до 3 попыток с backoff 1 с / 2 с между публикациями повторного сообщения; после этого сообщение уходит в DLQ payments.new.dlq.
• GET /health — без API-ключа (удобно для Docker healthcheck).

Переменные окружения

См. .env.example. Обязательные:

• DATABASE_URL — postgresql+asyncpg://...
• RABBITMQ_URL — amqp://guest:guest@rabbitmq:5672/
• API_KEY — значение заголовка X-API-Key

Локальный запуск (uv)

cd async_serv_processing_payment
cp .env.example .env
# поднимите Postgres и RabbitMQ или используйте docker-compose ниже

uv sync
uv run alembic upgrade head
uv run uvicorn src.main:app --reload --port 8000

Во втором терминале:

uv run python -m src.consumer_main

Docker Compose

docker compose up --build

Сервисы: postgres, rabbitmq, migrate, api (порт 8000), consumer.

Порты на хосте (чтобы реже конфликтовать с уже запущенными сервисами): Postgres 5433→5432, RabbitMQ 5673→5672, UI 15673→15672. Внутри compose сеть сервисы доступны как postgres:5432 и rabbitmq:5672.

Консоль RabbitMQ: http://localhost:15673 (guest/guest).

Примеры запросов

Создание платежа:

curl -sS -X POST "http://localhost:8000/api/v1/payments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev-secret-api-key" \
  -H "Idempotency-Key: demo-1" \
  -d '{
    "amount": "10.50",
    "currency": "RUB",
    "description": "Тестовый платёж",
    "metadata": {"order_id": "123"},
    "webhook_url": "https://webhook.site/your-unique-url"
  }'

Повтор того же запроса с тем же Idempotency-Key вернёт тот же платёж (идемпотентность).

Получение платежа:

curl -sS "http://localhost:8000/api/v1/payments/<payment_id>" \
  -H "X-API-Key: dev-secret-api-key"

Очереди RabbitMQ

Имя	Назначение
payments.new	Новые платежи из outbox
payments.new.dlq	Сообщения после исчерпания попыток обработки

Миграции

uv run alembic revision --autogenerate -m "message"
uv run alembic upgrade head

Тесты

uv run pytest