Język: Polski · English

Produkcyjne demo wzorca Idempotency Key: bezpiecznie wątkowo, bez blokowania wątków, bez wywołań zewnętrznego API wewnątrz transakcji bazodanowej, na wątkach wirtualnych (Project Loom). Cały stos startuje jedną komendą docker compose up.

Więcej teorii: TEORIA.md.

Klient wysyła żądanie „zaksięguj płatność 199,99 PLN". Sieć się zawiesza - klient nie dostaje odpowiedzi. Co robi? Ponawia to samo żądanie.

Bez zabezpieczenia serwer potraktuje drugie żądanie jako nową operację - druga płatność, podwójne obciążenie.

Klient generuje unikalny identyfikator operacji (Idempotency Key) i wysyła go w nagłówku przy każdym żądaniu:

POST /api/v1/payments
Idempotency-Key: 7f3a9c2e-4b1d-4e8a-9f6c-1a2b3c4d5e6f
Content-Type: application/json

{"amount": 199.99, "currency": "PLN", "recipient": "ACME"}

Serwer zapamiętuje: „ten klucz = ten wynik". Kolejne żądanie z tym samym kluczem i tą samą treścią dostaje ten sam wynik, bez ponownego wykonania operacji.

Ważne: klucz generuje klient (np. UUID), nie serwer. Dzięki temu klient może bezpiecznie ponowić request po timeoucie, używając tego samego klucza.

• Wiele instancji serwisu - każda ma własną pamięć; synchronizacja musi być w bazie danych.
• Wyścig równoległy - dwa żądania z tym samym kluczem mogą trafić w ten sam moment; tylko jedno może „wygrać".
• Trwałość - po restarcie serwisu replay nadal musi działać.

W tym projekcie synchronizacją zajmuje się PRIMARY KEY na kolumnie idempotency_key - baza gwarantuje, że tylko jeden INSERT się powiedzie.

Nigdy nie wołaj zewnętrznego API (operator płatności) wewnątrz transakcji bazodanowej.

Wolne HTTP (setki ms-sekundy) trzyma otwarte połączenie do bazy, wyczerpuje pulę HikariCP i blokuje inne żądania. Dlatego aplikacja dzieli pracę na 3 fazy o rozdzielonych transakcjach (opisane poniżej).

Projekt składa się z dwóch niezależnych aplikacji Spring Boot (osobne pom.xml, osobne Dockerfile) orkiestrowanych przez Docker Compose:

idempotency-key-pattern/
├── payment-service/        # główny serwis (port 8080)
│   ├── src/main/java/com/app/
│   ├── src/main/resources/   schema.sql, data.sql, application.yaml
│   ├── pom.xml
│   └── Dockerfile
├── payment-gateway/        # atrapa operatora płatności (port 8081)
│   ├── src/main/java/com/app/
│   ├── pom.xml
│   └── Dockerfile
├── docker-compose.yml      # MySQL + oba serwisy
├── README.md
├── README.en.md
└── TEORIA.md

Klient
  │  POST + Idempotency-Key
  ▼
PaymentController                    ← presentation/
  │  ProcessPaymentCommand
  ▼
ProcessPaymentUseCaseImpl            ← infrastructure/usecase/  ← SEDNO (3 fazy)
  │
  ├── IdempotencyTransactionBoundary ← infrastructure/tx/
  │     └── IdempotencyPaymentService ← application/service/
  │
  └── PaymentGatewayPort             ← application/port/output/
        └── PaymentGatewayAdapter    ← infrastructure/gateway/  (RestClient → :8081)

com.app
├── domain/                         # rdzeń - model i repozytoria
│   ├── model/                      Payment, IdempotencyLookup
│   ├── repository/                 PaymentRepository, IdempotencyRecordRepository
│   └── exception/                  wyjątki domenowe (409 / 422 / 502)
│
├── application/                    # logika biznesowa
│   ├── service/                    IdempotencyPaymentService
│   └── port/
│       ├── input/                  ProcessPaymentUseCase, Command, Result
│       └── output/                 PaymentGatewayPort
│
├── infrastructure/                 # świat zewnętrzny
│   ├── usecase/                    ProcessPaymentUseCaseImpl (3 fazy)
│   ├── tx/                         IdempotencyTransactionBoundary
│   ├── configuration/              BeanConfiguration, GatewayProperties
│   ├── gateway/                    adapter + DTO, RestClient do operatora
│   └── persistence/                entity, repository, adapter, mapper
│
└── presentation/                   REST API
    ├── controller/                 PaymentController
    ├── dto/                        request/response DTO
    └── exception/                  GlobalExceptionHandler

Drugi serwis - payment-gateway (port 8081) - to atrapa wolnego operatora (~800 ms), sama też idempotentna (pamięta wynik per Idempotency-Key w pamięci). Dzięki temu system jest idempotentny end-to-end.

Implementacja w ProcessPaymentUseCaseImpl:

Dlaczego tak:

1. Brak API w transakcji. Wolne wywołanie operatora (faza 2) nigdy nie trzyma otwartej transakcji ani połączenia do bazy.
2. Bezpieczeństwo wątkowe = baza. Synchronizację daje klucz główny na idempotency_key. Tylko jedno żądanie wygra INSERT; przegrani dostają błąd unikalności i są klasyfikowani. Działa też przy wielu instancjach.
3. Nie blokujemy. Równoległe żądanie z tym samym kluczem dostaje natychmiast 409.
4. Bezpieczne ponawianie. Gdy operator zawiedzie, zwalniamy rezerwację, więc klient może ponowić z tym samym kluczem.

Wymagania: Docker + Docker Compose (do pełnego stosu). Do lokalnego buildu bez Dockera: JDK 25, Maven 3.9+.

docker compose up -d --build

Zatrzymanie i usunięcie wolumenu z danymi:

docker compose down -v

payment-service czeka na mysql z condition: service_healthy. Jeśli przy starcie pojawi się błąd połączenia z bazą (Connection refused), poczekaj chwilę i uruchom ponownie:

docker compose restart payment-service

W data.sql jest gotowy rekord seed-key-demo:

curl -i -X POST http://localhost:8080/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seed-key-demo" \
  -d '{"amount": 49.99, "currency": "PLN", "recipient": "Sklep Demo"}'

Oczekiwany wynik: 201, Idempotent-Replayed: true, ten sam paymentId przy każdym wywołaniu.

Endpoint: POST http://localhost:8080/api/v1/payments

Nagłówki:

• Content-Type: application/json
• Idempotency-Key: <unikalny klucz - generuje klient>

Body:

{
  "amount": 199.99,
  "currency": "PLN",
  "recipient": "ACME Corp"
}

Używaj nowego klucza na każdą nową płatność. W produkcji zamiast test-001 stosuj UUID (crypto.randomUUID()).