Idempotentność i ponowienia przez proxy: jak ponowienie żądania nie tworzy duplikatu zamówienia
Spis treści
- Wprowadzenie: jeden przycisk, dwa zamówienia i tunel, w którym giną odpowiedzi
- Podstawy: czym jest idempotentność i dlaczego powtórzenie żądania w ogóle jest niebezpieczne
- Głębokie zanurzenie: kontrakt serwerowy i anatomia bezpiecznego ponowienia
- Metoda 1: generowanie i przekazywanie klucza idempotentności po stronie klienta
- Metoda 2: serwerowa implementacja magazynu kluczy
- Metoda 3: protokół ponowień przez proxy, który nie łamie idempotentności
- Metoda 4: gdy serwer nie obsługuje kluczy idempotentności
- Typowe błędy: jak zespoły same tworzą duplikaty
- Narzędzia i zasoby do implementacji
- Przypadki i wyniki
- Faq: trudne pytania o idempotentność i ponowienia
- Zakończenie: kontrakt zamiast nadziei
Wprowadzenie: jeden przycisk, dwa zamówienia i tunel, w którym giną odpowiedzi
Wyobraź sobie integrację, która działa od lat. Twój serwis wysyła zamówienia do zewnętrznego systemu, ruch idzie przez pulę mobilnych proxy, żeby rozłożyć żądania po regionach i nie wbijać się w limity jednego adresu. Wszystko stabilnie. I nagle księgowość przynosi raport: w ciągu miesiąca u partnera pojawiło się czterdzieści siedem bliźniaczych zamówień. Te same produkty, te same kwoty, różnica w czasie utworzenia trzy-cztery sekundy. Nikt niczego nie zmieniał. Co się stało?
Stało się coś zupełnie zwyczajnego: połączenie przez proxy zerwało się w drodze powrotnej. Serwer otrzymał żądanie, utworzył zamówienie, wysłał odpowiedź, ale odpowiedź nie dotarła do klienta. Klient uczciwie uznał, że żądanie się nie udało, i je powtórzył. Drugie żądanie też się wykonało. Tak rodzi się duplikat i żadna polityka ponowień sama w sobie przed nim nie chroni.
Ważne, żeby od razu przeprowadzić granicę. O tym, jak poprawnie powtarzać żądania po błędzie 429, ile czekać między próbami i jak budować opóźnienie wykładnicze, pisaliśmy osobno: to temat polityki ponowień. Dziś rozmowa jest inna. Mówimy o kontrakcie między klientem a serwerem, który czyni ponowienie bezpiecznym albo niebezpiecznym niezależnie od tego, jak dokładnie je wykonujesz. Ten kontrakt nazywa się idempotentnością, a jego głównym narzędziem jest klucz idempotentności.
Dlaczego temat jest szczególnie ostry właśnie przy pracy przez proxy? Bo proxy dokłada do łańcucha jeszcze jeden odcinek, na którym odpowiedź może zginąć. Mobilne proxy dodatkowo zmieniają zewnętrzne IP przy rotacji, a serwer całkiem może zobaczyć drugie żądanie z innego adresu. Jeśli twoja ochrona przed duplikatami opiera się na sesji, IP albo oknie czasowym, rozsypuje się. Jeśli opiera się na kluczu idempotentności, jest jej wszystko jedno, skąd przyszło ponowienie.
Z tego przewodnika dowiesz się, jak zbudowana jest idempotentność na poziomie protokołu i logiki biznesowej, jak generować i przechowywać klucze, jak zaprojektować serwerowy magazyn, który wytrzymuje współbieżne ponowienia, co zrobić, gdy zewnętrzne API nie obsługuje kluczy, i na jakich błędach potykają się nawet doświadczone zespoły. Przeanalizujemy przypadki z liczbami, zbierzemy checklisty i odpowiemy na niewygodne pytania. Materiał jest skierowany do twórców integracji, architektów i tech leadów, którzy pracują z zamówieniami, płatnościami i wszelkimi operacjami, gdzie „dwa razy” znaczy „źle”.
Podstawy: czym jest idempotentność i dlaczego powtórzenie żądania w ogóle jest niebezpieczne
Definicja prostymi słowami
Operacja jest idempotentna, jeśli jej wielokrotne wykonanie daje ten sam rezultat co jednokrotne. Naciśnięcie przycisku wezwania windy dziesięć razy jest idempotentne: winda przyjedzie raz. Dołożenie do koszyka kolejnej sztuki produktu nie jest idempotentne: każde naciśnięcie zmienia stan. Przelanie pieniędzy na pewno nie jest idempotentne, chyba że system został specjalnie zaprojektowany tak, żeby powtórzenie przelewu z tym samym identyfikatorem nic nie robiło.
W HTTP są metody, które zgodnie ze specyfikacją uchodzą za idempotentne: GET, PUT, DELETE, HEAD. Jest metoda POST, której domyślnie nie uznaje się za idempotentną. Właśnie POST najczęściej służy do tworzenia zamówień, płatności, wysyłania wiadomości. Czyli najbardziej ryzykowna operacja żyje w najbardziej nieidempotentnej metodzie. Zbieg okoliczności? Raczej historyczna prawidłowość, z którą trzeba pracować.
Trzy możliwe wyniki każdego żądania
Kiedy klient wysyła żądanie i nie dostaje odpowiedzi, znajduje się w stanie niepewności. Możliwe są dokładnie trzy scenariusze:
- Żądanie nie dotarło do serwera. Powtarzanie jest bezpieczne: nic się nie stało.
- Żądanie dotarło, serwer wykonał operację, odpowiedź zginęła. Powtarzanie jest niebezpieczne: operacja wykona się drugi raz.
- Żądanie dotarło, serwer zaczął wykonywanie i jeszcze nie skończył. Powtarzanie jest podwójnie niebezpieczne: dwie operacje będą wykonywać się równolegle.
Kluczowy kłopot polega na tym, że klient nie potrafi odróżnić tych scenariuszy. Timeout wygląda identycznie we wszystkich trzech przypadkach. Zerwane połączenie też. Stąd fundamentalna zasada systemów rozproszonych: niezawodne dostarczanie jest możliwe tylko jako „co najmniej raz” (at-least-once). Gwarancji „dokładnie raz” (exactly-once) na poziomie transportu uzyskać nie można; można ją jedynie emulować na poziomie aplikacji, czyniąc ponowienia nieszkodliwymi. Idempotentność jest właśnie tym sposobem emulacji.
Jak proxy wydłuża łańcuch niepewności
Bez proxy między klientem a serwerem jest jeden odcinek sieci. Z proxy są dwa: klient — proxy oraz proxy — serwer. Odpowiedź może zginąć na którymkolwiek z nich. Co więcej, jeśli zginęła na pierwszym odcinku, to proxy już dostało odpowiedź, serwer już zakończył operację, a klient nigdy się o tym nie dowie.
Mobilne proxy dodają swoją specyfikę. Mają rotację IP według harmonogramu albo na żądanie, przełączanie między stacjami bazowymi, naturalne wahania jakości łącza radiowego. Każde z tych zdarzeń potrafi zerwać połączenie TCP w dowolnym momencie. Co więcej, najczęściej zerwanie następuje nie podczas przesyłania treści żądania (jest małe i wylatuje szybko), ale podczas oczekiwania na odpowiedź, gdy połączenie po prostu pozostaje otwarte. Właśnie w tym momencie serwer przetwarza twoje zamówienie. Właśnie w tym momencie zerwanie daje największą szansę na duplikat.
Czym jest klucz idempotentności
Klucz idempotentności (Idempotency-Key) to unikalny identyfikator operacji biznesowej, który klient generuje raz i przekazuje z każdą próbą wykonania tej operacji. Serwer zapamiętuje klucz i wynik. Przy ponownym żądaniu z tym samym kluczem serwer nie wykonuje operacji od nowa, ale zwraca zapisany wynik. Klient może powtarzać do woli: zamówienie zostanie utworzone raz.
Zwróć uwagę na sformułowanie: klucz identyfikuje operację, a nie żądanie HTTP. Ta różnica stanie się kluczowa dalej, gdy będziemy omawiać błędy implementacji.
Głębokie zanurzenie: kontrakt serwerowy i anatomia bezpiecznego ponowienia
Kontrakt jako umowa o zachowaniu
Idempotentność to nie nagłówek i nie biblioteka. To umowa, w której serwer obiecuje klientowi konkretne zachowanie przy ponowieniach, a klient obiecuje przestrzegać zasad tworzenia kluczy. Dobry kontrakt odpowiada na następujące pytania:
- Która encja jest jednostką idempotentności: zamówienie, płatność, pozycja zamówienia, batch?
- Jak klient przekazuje klucz: nagłówek, pole w treści, część URL-a?
- Co się dzieje, jeśli klucz się powtórzył, a treść żądania jest inna?
- Co się dzieje, jeśli pierwsze żądanie jeszcze się wykonuje, a przyszło drugie z tym samym kluczem?
- Jak długo serwer pamięta klucz?
- Co wróci przy ponowieniu: dokładnie ta sama odpowiedź co do bajtu czy aktualny stan encji?
- Jak ponowienie odróżnia się od nowego żądania w logach i metrykach?
Jeśli choć na jedno z tych pytań nie ma odpowiedzi w dokumentacji API, kontrakt jest niepełny, a w nieokreślonych sytuacjach zachowanie będzie zależeć od implementacji, wersji i fazy księżyca.
Trzy stany klucza
Na serwerze każdy klucz ma cykl życia złożony z trzech stanów. Zrozumienie tego cyklu wyjaśnia dziewięćdziesiąt procent problemów z duplikatami.
- Brak. Klucz widziany po raz pierwszy. Serwer musi atomowo go zarezerwować i rozpocząć przetwarzanie.
- W toku (in-progress). Pierwsze żądanie jest przetwarzane. Drugie żądanie z tym samym kluczem nie powinno uruchamiać drugiego przetwarzania. Warianty: zwrócić 409 Conflict ze wskazówką, żeby poczekać, zablokować się do zakończenia pierwszego i zwrócić jego wynik, zwrócić 202 Accepted z linkiem do statusu.
- Zakończony. Wynik zapisany. Ponowienie zwraca zapisany wynik bez efektów ubocznych.
Najczęstszy błąd architektoniczny to pominięcie stanu środkowego. Programista sprawdza „czy klucz jest w bazie”, nie znajduje, zaczyna przetwarzanie, a równoległe ponowienie w tym samym momencie robi dokładnie to samo. Dwa wątki, dwa sprawdzenia, dwa zamówienia. Sprawdzenie i rezerwacja muszą być jedną atomową operacją: wstawienie z unikalnym indeksem, warunkowy zapis w Redis, transakcja z blokadą.
Fingerprint żądania
Klucz identyfikuje operację, ale operację z jaką treścią? Jeśli klient przez błąd wysłał klucz K z kwotą 1000 złotych, a potem powtórzył z tym samym kluczem i kwotą 10000, co powinien zrobić serwer? Po cichu zwrócić wynik pierwszej operacji — niebezpiecznie: klient będzie myślał, że zapłacił 10000. Wykonać drugą — złamać idempotentność.
Prawidłowa odpowiedź: serwer przechowuje odcisk (fingerprint) żądania — hash znormalizowanej treści i istotnych nagłówków. Przy ponowieniu z tym samym kluczem, ale innym odciskiem zwracany jest błąd 422 Unprocessable Content albo 400 z jawnym kodem w rodzaju idempotency_key_reused_with_different_payload. To chroni przed błędami logicznymi klienta i przed fałszowaniem ponowień.
Przechowywanie odpowiedzi: migawka czy aktualny stan
Istnieją dwa podejścia do tego, co zwracać przy ponowieniu. Migawka — serwer zapisuje status, nagłówki i treść oryginalnej odpowiedzi i zwraca je bez zmian. Jest to ściśle idempotentne i przewidywalne. Aktualny stan — serwer po kluczu znajduje utworzoną encję i zwraca jej bieżące przedstawienie. Jest to wygodniejsze, jeśli między próbami zamówienie zdążyło przejść w inny status, ale mniej przewidywalne.
W systemach płatniczych dominuje migawka: klient powinien otrzymać dokładnie tę odpowiedź, która była przy pierwszej próbie. W systemach zarządzania zamówieniami często stosuje się hybrydę: migawka dla kodów błędów, aktualny stan dla sukcesu. Ważne, żeby wybór był zapisany w kontrakcie.
Co zmienia proxy na poziomie kontraktu
Technicznie proxy nie uczestniczy w kontrakcie idempotentności: jest przezroczyste dla nagłówków i treści. Ale zmienia prawdopodobieństwa. Przy połączeniu bezpośrednim zgubienie odpowiedzi przy udanym wykonaniu to rzadkość, ułamek promila. Przez łańcuch z mobilnym proxy i rotacją to zdarzenie staje się regularne. Obserwowaliśmy integracje, w których przy pięciominutowej rotacji IP około 0,3–0,8% żądań kończyło się zerwaniem połączenia na etapie oczekiwania na odpowiedź. Przy dziesięciu tysiącach zamówień na dobę to trzydzieści–osiemdziesiąt potencjalnych duplikatów dziennie. Bez klucza idempotentności każdy z nich zamienia się w rzeczywisty duplikat.
Jest i drugi niuans. Wiele serwerów włącza do logiki antyfraudowej sprawdzenie „ponowne żądanie z innego IP”. Przy rotacji mobilnego proxy ponowienie prawie zawsze przyjdzie z nowego adresu. Jeśli serwer interpretuje to jako podejrzaną aktywność i odrzuca ponowienie bez sięgnięcia do magazynu kluczy, klient nie dostanie zapisanego wyniku i pozostanie w niepewności. Dobry kontrakt sprawdza klucz przed jakimikolwiek heurystykami powiązanymi z siecią.
Metoda 1: generowanie i przekazywanie klucza idempotentności po stronie klienta
Gdzie rodzi się klucz
Główna zasada: klucz generuje się raz na operację biznesową, przed pierwszą próbą wysyłki, i zapisuje razem z zamiarem wykonania operacji. Jeśli klucz powstaje wewnątrz klienta HTTP przy każdym wywołaniu, ponowienie dostanie nowy klucz i cała ochrona się wyzeruje. To tak częsty błąd, że wyniesiemy go osobno do sekcji o antywzorcach, ale powtórzmy tu: klucz żyje na poziomie serwisu zamówień, a nie na poziomie transportu.
Praktyczna kolejność wygląda tak:
- Użytkownik albo proces wewnętrzny inicjuje utworzenie zamówienia.
- Serwis tworzy lokalny rekord „zamiar zamówienia” ze statusem pending i generuje klucz.
- Klucz i payload zapisują się w lokalnej bazie w jednej transakcji.
- Dopiero po zatwierdzeniu transakcji uruchamiana jest wysyłka do zewnętrznego API przez proxy.
- Wszystkie ponowienia czytają klucz z lokalnego rekordu, a nie generują nowego.
- Po otrzymaniu odpowiedzi lokalny rekord jest aktualizowany wynikiem i zewnętrznym identyfikatorem zamówienia.
Taka kolejność gwarantuje, że nawet restart twojego serwisu w środku ponowień nie doprowadzi do zmiany klucza: leży on w bazie.
Format klucza
Klucz musi być globalnie unikalny i nieprzewidywalny dla osób trzecich. Sprawdzone warianty:
- UUID wersji 4 — klasyka, 122 bity losowości, pasuje wszędzie.
- UUID wersji 7 albo ULID — zawierają znacznik czasu w starszych bitach, co czyni je wygodnymi do sortowania i indeksowania w bazie serwera. W 2026 roku to już standardowy wybór dla nowych systemów.
- Klucz deterministyczny z naturalnego identyfikatora — na przykład hash z identyfikatora koszyka, identyfikatora użytkownika i wersji koszyka. Przydatny, gdy klient sam może zgubić stan i wygenerować klucz ponownie z tych samych danych.
Czego unikać: liczb sekwencyjnych (łatwo odgadnąć cudzy klucz i dostać cudzą odpowiedź), krótkich ciągów, kluczy zależnych tylko od czasu o niskiej precyzji.
Sposób przekazywania
Standard de facto to nagłówek Idempotency-Key. Szkic specyfikacji IETF utrwala właśnie tę nazwę, a większość nowoczesnych API się jej trzyma. Przykład wywołania przez proxy:
curl -x http://user:pass@proxy.example:8080 -H "Idempotency-Key: 018f3a2c-7b1e-7c3d-9a4e-1f2b3c4d5e6f" -H "Content-Type: application/json" -d '{"cart_id":"c-9921","amount":149000}' https://api.partner.example/v1/orders
Niektóre API przyjmują klucz w treści żądania (pole client_reference_id, external_id, request_id). To też działający wariant, ale z jednym niuansem: jeśli serwer używa pola treści jako klucza, musi ono uczestniczyć w unikalnym indeksie, inaczej to tylko etykieta, a nie ochrona.
Zakres działania klucza
Klucz musi być unikalny w obrębie jednego konta klienta i jednego endpointu. Dobry serwer składa wewnętrzny klucz przechowywania jako kombinację identyfikatora konta, metody, ścieżki i przekazanego klucza. To chroni przed kolizjami między różnymi klientami i przed przypadkowym ponownym użyciem klucza do innej operacji.
Checklista po stronie klienta
- Klucz jest generowany przed pierwszą próbą i przechowywany w bazie razem z zamiarem.
- Wszystkie ponowienia używają tego samego klucza.
- Treść żądania przy ponowieniu co do bajtu zgadza się z pierwszą próbą.
- Klient umie obsłużyć 409 (operacja w toku) jako sygnał, żeby poczekać i powtórzyć, a nie jako błąd.
- Klient umie obsłużyć 422 z kodem niezgodności odcisku jako błąd logiczny wymagający interwencji.
- Klient loguje klucz we wszystkich wpisach związanych z operacją, żeby duplikaty dało się zbadać.
- Klient nie resetuje klucza przy zmianie proxy, rotacji IP ani przełączeniu na zapasową pulę.
Metoda 2: serwerowa implementacja magazynu kluczy
Jeśli jesteś właścicielem serwera, do którego przez proxy zwracają się twoi klienci lub partnerzy, ta sekcja jest o tobie. Jeśli jesteś tylko klientem, pomoże ci ocenić jakość cudzej implementacji po dokumentacji i zachowaniu.
Schemat przechowywania
Minimalna tabela albo struktura na klucze zawiera następujące pola:
- scope_key — klucz złożony: konto, metoda, ścieżka, przekazany Idempotency-Key. Unikalny indeks.
- fingerprint — hash znormalizowanej treści żądania.
- state — jedna z wartości: in_progress, completed, failed.
- response_status, response_headers, response_body — migawka odpowiedzi, wypełniana przy zakończeniu.
- resource_id — identyfikator utworzonej encji, jeśli dotyczy.
- locked_at, completed_at, expires_at — znaczniki czasu do obsługi zawieszonych operacji i czyszczenia.
Atomowa rezerwacja
Serce implementacji to operacja, która jednym działaniem albo tworzy rekord w stanie in_progress, albo komunikuje, że rekord już istnieje. W bazie relacyjnej to wstawienie z obsługą konfliktu po unikalnym indeksie. W Redisie — polecenie SET z flagami NX i EX, które zapisuje wartość tylko przy braku klucza i od razu ustawia czas życia. Żadnego „najpierw SELECT, potem INSERT”: między nimi wśliźnie się równoległe ponowienie.
Pseudokod na poziomie logiki:
- Oblicz scope_key i fingerprint.
- Spróbuj wstawić rekord ze state = in_progress. Jeśli wstawienie się udało, przejdź do wykonania operacji.
- Jeśli konflikt: odczytaj istniejący rekord.
- Jeśli fingerprint się nie zgadza — zwróć 422 z kodem niezgodności.
- Jeśli state = in_progress — zwróć 409 z nagłówkiem Retry-After albo czekaj na zakończenie (w rozsądnym timeoucie).
- Jeśli state = completed — zwróć zapisaną migawkę odpowiedzi z nagłówkiem oznaczającym ponowienie, na przykład
Idempotent-Replayed: true.
Wykonanie i utrwalenie wyniku
Tu kryje się druga pułapka. Operacja się wykonała, zamówienie utworzone, ale proces padł przed zapisem wyniku do magazynu kluczy. Rekord zostaje w stanie in_progress na zawsze. Ponowienie dostaje 409, potem jeszcze 409, i tak w nieskończoność.
Istnieją trzy podejścia do rozwiązania:
- Jedna transakcja. Utworzenie zamówienia i aktualizacja rekordu klucza wykonują się w jednej transakcji bazy danych. Najbardziej niezawodny wariant, jeśli zamówienie i klucze żyją w jednej bazie.
- Klucz jako część encji. Klucz idempotentności jest przechowywany wprost w tabeli zamówień z unikalnym indeksem. Wtedy samo zamówienie jest rekordem klucza; osobna tabela nie jest potrzebna. Prosto i niezawodnie w przypadkach z jedną encją na operację.
- Odzyskiwanie zawieszonych. Proces w tle znajduje rekordy in_progress starsze niż próg (na przykład 60 sekund), sprawdza, czy operacja faktycznie została wykonana (po resource_id albo wyszukaniu encji), i albo dokańcza utrwalenie, albo przełącza rekord w failed, pozwalając na ponowienie.
Obsługa błędów pierwszej próby
Co zapisać, jeśli pierwsza próba zakończyła się błędem? To zależy od typu błędu. Błędy walidacji (400, 422) są deterministyczne: ponowienie z tą samą treścią da ten sam wynik, można je cache'ować. Błędy infrastruktury (500, 503, timeout bazy) nie są deterministyczne: jeśli je zcache'ujesz, klient nigdy nie będzie mógł pomyślnie wykonać operacji. Prawidłowe zachowanie: przy błędzie infrastruktury zwolnić klucz (usunąć rekord albo przełączyć w failed z możliwością ponownego przejęcia), żeby następne ponowienie spróbowało jeszcze raz.
Czas życia klucza
Kluczy nie można trzymać wiecznie: tabela się rozrośnie. Ale zbyt krótki okres też jest niebezpieczny: jeśli klient powtarza pół godziny po awarii sieci, klucz musi być żywy. Praktyka dużych operatorów płatności zbiega się na 24 godzinach jako minimum. Dla zamówień w e-commerce rozsądne są 24–72 godziny. Dla operacji, które klient może powtarzać po długich awariach (na przykład synchronizacja katalogów raz na dobę), okres musi przewyższać interwał synchronizacji co najmniej dwukrotnie.
Obserwowalność
Każde ponowienie powinno zostawiać ślad. Metryki, które warto zbierać: liczba ponowień z trafieniem w completed (nieszkodliwe ponowienia), liczba 409 (współbieżne ponowienia), liczba 422 (niezgodność odcisku — prawie zawsze błąd klienta), wiek najstarszego rekordu in_progress (wskaźnik zawieszonych operacji). Stosunek ponowień do unikalnych operacji to bezpośrednia miara jakości sieci między klientem a serwerem. Jeśli gwałtownie rośnie, gdzieś pogorszyła się jakość kanału proxy albo zmieniła się rotacja.
Checklista po stronie serwera
- Rezerwacja klucza jest atomowa.
- Jest osobny stan in_progress i jasna odpowiedź na współbieżne ponowienie.
- Przechowywany jest odcisk treści, niezgodność odrzucana jawnym błędem.
- Utrwalenie wyniku jest transakcyjne albo istnieje mechanizm odzyskiwania zawieszonych rekordów.
- Błędy infrastruktury nie są cache'owane, deterministyczne — są.
- TTL nie mniejszy niż 24 godziny i udokumentowany.
- Ponowienie jest oznaczane nagłówkiem i widoczne w metrykach.
- Sprawdzenie klucza następuje wcześniej niż sieciowe heurystyki antyfraudowe.
Metoda 3: protokół ponowień przez proxy, który nie łamie idempotentności
Polityka ponowień to temat sąsiedniego artykułu, ale jest wąska warstwa, w której polityka ponowień i idempotentność się przecinają: które dokładnie sygnały z łańcucha proxy oznaczają, że ponowienie jest potrzebne, i jak ponowienie nie powinno niszczyć kontraktu. Przeanalizujmy ją.
Odróżniaj awarię proxy od awarii upstreamu
Pracując przez proxy, klient dostaje błędy trzech pochodzeń i na każde trzeba reagować inaczej:
- Błędy połączenia z proxy. Nie udało się połączyć z proxy, proxy zwróciło 407 (wymagane uwierzytelnienie), proxy zamknęło połączenie przed wysłaniem żądania. Żądanie na pewno nie dotarło do serwera. Ponowienie jest bezpieczne nawet bez klucza, ale z kluczem — i tak lepiej.
- Błędy proxy przy odwołaniu do upstreamu. Proxy zwróciło 502 Bad Gateway albo 504 Gateway Timeout. Tu niepewność jest największa: 502 zwykle oznacza, że upstream nie odpowiedział poprawnie, ale mógł wykonać operację; 504 oznacza, że proxy zmęczyło się czekaniem, a serwer być może wciąż przetwarza. Ponowienie tylko z kluczem.
- Odpowiedzi upstreamu, które przeszły przez proxy. 500, 503, 429 od docelowego serwera. Ich semantykę określa kontrakt docelowego API. Ponowienie z kluczem zgodnie z zasadami polityki ponowień.
Osobnej uwagi wymaga zerwanie połączenia podczas czytania odpowiedzi. Nagłówki już przyszły, treść się urwała. To najbardziej podstępny przypadek: status 201 Created być może zobaczyłeś, ale identyfikatora zamówienia z treści nie dostałeś. Ponowienie z kluczem zwróci pełną migawkę odpowiedzi. Bez klucza dostaniesz drugie zamówienie i przy tym nadal nie poznasz identyfikatora pierwszego.
Rotacja IP jako zdarzenie, a nie tło
Jeśli twoja pula mobilnych proxy rotuje adresy według harmonogramu, synchronizuj wysyłkę krytycznych operacji z oknami stabilności. Prosty trik: dowiadywać się od API serwisu proxy, ile czasu zostało do następnej rotacji, i nie zaczynać tworzenia zamówienia, jeśli do rotacji zostało mniej niż twój timeout oczekiwania na odpowiedź. To nie zastępuje idempotentności, ale zmniejsza liczbę ponowień, a więc obciążenie magazynu kluczy i antyfraudu partnera.
Jeśli rotacja odbywa się na żądanie, nie wywołuj zmiany IP między próbami jednej operacji bez potrzeby. Niektóre zespoły robią tak „żeby obejść zablokowanie”, ale serwer, widząc ten sam klucz z nowego adresu, może włączyć dodatkowe sprawdzenie. Klucz uratuje przed duplikatem, ale ponowienie może się spowolnić.
Timeouty: dwie granice zamiast jednej
Przy połączeniu bezpośrednim zwykle ustawia się jeden timeout na odpowiedź. Przez proxy potrzebne są co najmniej dwa: timeout nawiązania połączenia z proxy (krótki, kilka sekund) i timeout oczekiwania na odpowiedź od upstreamu (dłuższy, z uwzględnieniem czasu przetwarzania zamówienia). Jeśli połączysz je w jeden, krótki timeout będzie ciągle się włączał przy wolnym przetwarzaniu, rodząc zbędne ponowienia, a długi — każe ci czekać na niedostępne proxy zbędne sekundy.
Ważne: timeout oczekiwania na odpowiedź nie może być krótszy niż faktyczny czas tworzenia zamówienia na serwerze. Inaczej będziesz systematycznie zrywać połączenie dokładnie w momencie przetwarzania, i każda operacja zamieni się w parę „zerwana próba plus ponowienie”. Klucz uchroni przed duplikatami, ale serwer będzie zużywał zasoby na przetwarzanie na próżno.
Ponowienie przez inne proxy
Rozsądna strategia: pierwsza ponowna próba idzie przez to samo proxy (być może połączenie tylko mrugnęło), druga — przez inne proxy z puli (być może problem jest w konkretnym kanale). Klucz się przy tym nie zmienia. Treść się nie zmienia. Zmienia się tylko trasa. Tak oddzielasz problemy sieciowe od problemów samego żądania i dostajesz informację diagnostyczną: jeśli przez drugie proxy przeszło od razu, sprawa była w kanale.
Krok po kroku: protokół bezpiecznego ponowienia
- Odczytaj klucz i treść z lokalnego rekordu zamiaru.
- Wyślij żądanie przez bieżące proxy z dwoma timeoutami.
- Przy sukcesie: zapisz wynik, zakończ.
- Przy 409 od serwera: poczekaj wskazany czas albo rozsądny interwał, powtórz z tym samym kluczem.
- Przy 422 z kodem niezgodności odcisku: zatrzymaj się, podnieś incydent, nie powtarzaj automatycznie.
- Przy błędzie połączenia z proxy: zmień proxy, powtórz natychmiast.
- Przy 502, 504, zerwaniu albo timeoucie: zastosuj politykę opóźnienia, powtórz z tym samym kluczem; od drugiego ponowienia — przez inne proxy.
- Po wyczerpaniu prób: zostaw rekord w stanie unknown, przekaż do kolejki uzgadniania (patrz Metoda 4).
Punkt ósmy jest krytyczny. Stan „nie wiem, czy zamówienie zostało utworzone” jest stanem legalnym i nie wolno go po cichu spłaszczać ani do „utworzone”, ani do „nieutworzone”.
Metoda 4: gdy serwer nie obsługuje kluczy idempotentności
Idealny świat kończy się na pierwszym API partnerskim, w którego dokumentacji słowo „idempotentność” nie występuje. Co zrobić, jeśli jesteś klientem, a serwer po prostu tworzy zamówienie na każdy POST? Jest kilka technik, od prostych do architektonicznych.
Naturalny klucz w polach żądania
Wiele API, nie mając formalnego Idempotency-Key, przyjmuje pole w rodzaju external_order_id, client_reference, merchant_order_number i obiecuje unikalność po nim w obrębie konta. To jest idempotentność pod inną nazwą. Sprawdź dokumentację i, co ważniejsze, sprawdź zachowanie: wyślij dwa żądania z tym samym zewnętrznym identyfikatorem w środowisku testowym i zobacz, czy wróci błąd duplikatu, czy utworzy się druga encja. Obietnice w dokumentacji i rzeczywiste zachowanie rozchodzą się częściej, niż by się chciało.
Czytanie przed ponowieniem
Jeśli serwer daje możliwość wyszukiwania encji po twoim zewnętrznym identyfikatorze albo po parametrach (na przykład lista zamówień z filtrem po czasie i kwocie), to przed każdym ponowieniem rób żądanie sprawdzające: czy nie pojawiło się już zamówienie z moimi cechami? Nie daje to ścisłej gwarancji (między sprawdzeniem a ponowieniem może prześlizgnąć się okno), ale zmniejsza prawdopodobieństwo duplikatu o rząd wielkości. Schemat:
- Pierwsza próba zakończyła się nieokreślenie.
- Poczekaj interwał wystarczający na zakończenie przetwarzania na serwerze.
- Wykonaj GET z filtrem po zewnętrznym identyfikatorze albo unikalnej kombinacji pól.
- Jeśli zamówienie znalezione — zapisz jego identyfikator, ponowienie nie jest potrzebne.
- Jeśli nie znalezione — powtórz POST.
Żeby wyszukiwanie działało, wkładaj do zamówienia znacznik, po którym można je znaleźć: komentarz, pole własne, unikalny numer pozycji. Nawet jeśli serwer zignoruje go jako klucz, zwróci go w odpowiedzi i będziesz mógł porównywać.
Rozdzielenie operacji na rezerwację i potwierdzenie
Niektóre API obsługują model dwufazowy: najpierw tworzony jest szkic albo hold (operacja, którą można bezpiecznie powtórzyć albo anulować), potem potwierdzenie po identyfikatorze szkicu. Potwierdzenie po identyfikatorze jest z natury idempotentne: dwa razy potwierdzić tego samego szkicu nie można. Jeśli taki model jest dostępny, jest lepszy od jednostopniowego tworzenia nawet przy kluczach, bo zmniejsza okno niepewności najbardziej ryzykownego kroku.
Wzorzec Outbox po twojej stronie
Nawet jeśli serwer niczego nie gwarantuje, ty możesz zagwarantować, że z twojej strony każda operacja wyjdzie dokładnie z jednym zamiarem. Transakcyjny Outbox to tabela operacji wychodzących, do której zapis trafia w jednej transakcji ze zmianą biznesową (na przykład z przejściem koszyka w status „w trakcie składania”). Osobny proces-wysyłacz pobiera rekordy z Outboxa i wykonuje żądania przez proxy. Każdy rekord ma unikalny identyfikator, którego używasz jako klucza albo jako external_id. Nawet jeśli wysyłacz padnie w środku pracy, rekord zostanie w Outboxie, a ponowienie pójdzie z tym samym identyfikatorem.
Uzgadnianie jako ostatnia linia obrony
Reconciliation, czyli uzgadnianie, to regularny proces, który porównuje listę twoich operacji z listą encji po stronie partnera i znajduje rozbieżności: zamówienia, które są u partnera, ale nie są powiązane u ciebie; operacje w stanie unknown; duplikaty po pokrywających się cechach. Uzgadnianie nie zapobiega duplikatowi, ale znajduje go w minutach, a nie w miesiąc po raporcie księgowości. Dla operacji przez niestabilne kanały to obowiązkowy komponent, a nie opcja.
Praktyka: uruchamiać uzgadnianie co 10–15 minut dla operacji starszych niż twój maksymalny timeout ponowień, automatycznie wiązać znalezione encje z rekordami w unknown, a wykryte duplikaty przekazywać do kolejki anulowania z ręcznym potwierdzeniem, jeśli kwota przekracza próg.
Saga i kompensacje
Jeśli zamówienie jest częścią łańcucha działań (rezerwacja magazynu, płatność, dostawa), duplikat w jednym ogniwie łamie cały łańcuch. Wzorzec sagi zakłada, że każdy krok ma działanie kompensujące: anulowanie zamówienia, zwrot płatności, zdjęcie rezerwacji. Kompensacja też musi być idempotentna, inaczej będziesz walczyć z duplikatami anulowań. Projektując integrację, od razu wypisuj pary „działanie — kompensacja” i dla obu sprawdzaj, że ponowienie jest bezpieczne.
Typowe błędy: jak zespoły same tworzą duplikaty
Błąd 1. Klucz generowany wewnątrz klienta HTTP
Najczęstszy. Otoczka nad biblioteką HTTP dodaje nagłówek Idempotency-Key z nowym UUID przy każdym wywołaniu. Mechanizm ponowień wewnątrz tej samej biblioteki wywołuje wysyłkę od nowa — i dostaje nowy klucz. Z zewnątrz wszystko wygląda poprawnie: nagłówek jest. W rzeczywistości ochrony nie ma. Sprawdzaj po logach serwera albo proxy, że przy ponowieniach klucz się zgadza.
Błąd 2. Klucz zmienia się razem z treścią przy „poprawianiu” żądania
Klient dostał 400 z powodu nieprawidłowego pola, poprawił pole i powtórzył z tym samym kluczem. Serwer ze sprawdzeniem odcisku zwróci 422. Serwer bez sprawdzenia zwróci zcache'owany błąd 400 i klient będzie bił głową w ścianę. Poprawione żądanie to nowa operacja, potrzebuje nowego klucza.
Błąd 3. Sprawdzenie klucza przez SELECT, potem INSERT
Omówione wyżej, ale powtórzmy: między odczytem a zapisem zdąży prześlizgnąć się równoległe ponowienie. Szczególnie często objawia się to właśnie przy pracy przez proxy, bo clientowe timeouty rodzą ponowienia w odstępach kilku sekund, a przetwarzanie zamówienia zajmuje tyle samo. Tylko atomowa rezerwacja.
Błąd 4. Idempotentność po IP albo sesji
Serwer „zapamiętuje”, że z tego IP tylko co było takie samo żądanie, i odrzuca ponowienie. Przy rotacji mobilnego proxy ponowienie przychodzi z innego adresu i ochrona nie zadziała. Odwrotny wariant też jest zły: legalne różne zamówienia z jednego adresu proxy (przecież masz wielu klientów za jednym IP) są odrzucane jako duplikaty. Klucz musi być jawny i przekazany przez klienta.
Błąd 5. Zbyt krótki TTL
Klucze żyją pięć minut, „żeby nie zaśmiecać Redisa”. Awaria sieci trwa dwadzieścia minut. Kolejka ponowień dochodzi do operacji po pół godzinie. Klucz zapomniany, zamówienie tworzy się drugi raz. TTL musi pokrywać najdłuższy realistyczny scenariusz odłożonego ponowienia.
Błąd 6. Cache'owanie błędów infrastruktury
Pierwsza próba padła z 500 z powodu chwilowej niedostępności bazy. Serwer zapisał 500 jako wynik pod kluczem. Wszystkie kolejne ponowienia dostają 500 z cache'a, choć baza dawno wstała. Klient jest zmuszony zmienić klucz, tracąc powiązanie z pierwotną operacją. Cache'ować można tylko wyniki deterministyczne.
Błąd 7. Spłaszczanie stanu unknown
Po wyczerpaniu prób klient oznacza operację jako failed i pozwala użytkownikowi złożyć zamówienie na nowo. Ale serwer pierwszą operację wykonał. Użytkownik dostaje dwa zamówienia i podwójne obciążenie. Stan unknown musi istnieć jawnie i być rozwiązywany przez uzgadnianie, a nie przez optymistyczne założenie.
Błąd 8. Ponawianie operacji nieidempotentnych „bo tak prościej”
Uniwersalna warstwa ponowień powtarza wszystkie żądania tak samo, w tym POST bez kluczy. Działa do pierwszego sztormu sieciowego, po którym w ciągu godziny pojawiają się setki duplikatów. Warstwa ponowień musi wiedzieć, które żądania wolno powtarzać, i odmawiać ponawiania nieidempotentnych bez jawnego klucza.
Błąd 9. Jeden klucz na batch
Klient wysyła tablicę stu zamówień z jednym kluczem. Serwer przetworzył sześćdziesiąt i padł. Ponowienie z tym samym kluczem dostaje 409 albo częściową migawkę. Jak zrozumieć, które czterdzieści trzeba utworzyć? Dla batchy potrzebny jest albo klucz na każdą pozycję, albo serwerowa gwarancja atomowości całego batcha, albo odpowiedź ze statusem po elementach. Bez tego batche przez niestabilny kanał to źródło chaosu.
Błąd 10. Brak klucza w logach
Duplikat się zdarzył i próbujesz zrozumieć, czy to było ponowienie z tym samym kluczem (błąd serwera), czy dwie różne operacje (błąd klienta). W logach nie ma klucza. Dochodzenie zamienia się w zgadywanie. Klucz musi być w każdym wierszu logu po obu stronach i w dzienniku proxy, jeśli serwis proxy obsługuje logowanie nagłówków.
Narzędzia i zasoby do implementacji
Po stronie klienta
- Biblioteki identyfikatorów. Generatory UUIDv7 i ULID są dla wszystkich głównych języków. Wybieraj te, które gwarantują monotoniczność w obrębie milisekundy, jeśli klucze trafiają do indeksów bazy serwera.
- Klienci HTTP z rozdzielnymi timeoutami. Upewnij się, że twój klient pozwala ustawić osobno timeout połączenia z proxy i timeout czytania odpowiedzi. Większość nowoczesnych klientów to potrafi, ale domyślnie często stoi jeden wspólny timeout.
- Kolejki z gwarancją dostarczenia. Do implementacji Outboxa nada się każdy system brokerowy z potwierdzeniem przetworzenia. Ważne, żeby identyfikator wiadomości był stabilny między ponownymi dostarczeniami — wygodnie użyć go jako podstawy klucza.
- API zarządzania proxy. Dobre serwisy mobilnych proxy mają interfejs programistyczny pozwalający poznać stan kanału, czas do rotacji, zmienić IP na żądanie. Integracja z tym API daje możliwość nie zaczynania krytycznych operacji przed rotacją i świadomej zmiany trasy między próbami.
Po stronie serwera
- Baza relacyjna z unikalnymi indeksami. Najbardziej niezawodny wariant magazynu kluczy, jeśli wolumeny pozwalają. Wstawienie z obsługą konfliktu to atomowa operacja od razu z pudełka.
- Redis albo odpowiednik. Dla systemów wysokoobciążonych: SET z flagami NX i EX do rezerwacji, osobny klucz na migawkę odpowiedzi. Pamiętaj o ryzyku utraty danych przy awarii węzła i konfiguruj trwałość.
- Middleware do idempotentności. Dla popularnych frameworków webowych istnieją gotowe warstwy pośrednie realizujące podstawowy kontrakt: rezerwacja, odcisk, migawka. Sprawdzaj, jak zachowują się przy współbieżnych ponowieniach i przy padzie między wykonaniem a utrwaleniem — właśnie tam dobre implementacje rozchodzą się z formalnymi.
- Bramy API. Niektóre bramy potrafią deduplikować po nagłówku na wejściu. To zdejmuje obciążenie z aplikacji, ale brama zwykle nie wie o wyniku biznesowym i może cache'ować błędy infrastruktury. Używaj jako pierwszego filtra, nie jako jedynej ochrony.
Testowanie
- Wstrzykiwanie awarii sieciowych. Narzędzia proxy do testów, które potrafią zerwać połączenie po wysłaniu żądania, ale przed odpowiedzią, opóźnić odpowiedź ponad timeout, zwrócić 502 i 504. Bez takich testów nie zobaczysz zachowania systemu w jedynym istotnym scenariuszu.
- Testy współbieżne. Jednoczesna wysyłka N żądań z jednym kluczem. Oczekiwany wynik: dokładnie jedna utworzona encja, N-1 odpowiedzi 409 albo migawek. Każdy inny wynik to defekt.
- Test na restart w środku operacji. Zabić proces po utworzeniu zamówienia, ale przed utrwaleniem klucza. Sprawdzić, że mechanizm odzyskiwania zawieszonych rekordów zadziałał.
- Test na rotację. Pierwsza próba przez jedno IP, ponowienie przez inne. Sprawdzić, że serwer zwrócił migawkę, a nie odrzucił ponowienie heurystyką.
Standardy i dokumenty
Szkic specyfikacji IETF dotyczący nagłówka Idempotency-Key to punkt wyjścia do formułowania kontraktu: zdefiniowano tam nazwę nagłówka, semantykę konfliktów i zalecane kody odpowiedzi. Publiczna dokumentacja dużych operatorów płatności to dobry wzorzec opisywania kontraktu dla zewnętrznych integratorów: TTL, zachowanie przy niezgodności treści, obsługa współbieżnych żądań. Sekcja o metodach idempotentnych w specyfikacji semantyki HTTP wyjaśnia, dlaczego PUT i DELETE można powtarzać, a POST nie, i warto ją przeczytać przed projektowaniem endpointów.
Przypadki i wyniki
Przypadek 1. Agregator zamówień i 47 duplikatów miesięcznie
Firma-agregator przekazywała zamówienia do systemu partnera logistycznego przez pulę mobilnych proxy z rotacją co pięć minut. Wolumen — około 12 tysięcy zamówień na dobę. Kluczy idempotentności nie było: partnerskie API ich nie dokumentowało. Duplikaty wykrywano raz w miesiącu po uzgodnieniu finansowym, każdy kosztował średnio 900 złotych na anulowanie, zwrot i pracę ręczną.
Diagnostyka po logach proxy pokazała: 0,4% żądań kończyło się zerwaniem połączenia po wysłaniu treści, a przed otrzymaniem odpowiedzi, głównie w minutach rotacji. Ponowienie szło po trzech sekundach, a w 30% przypadków pierwsza próba była już wykonana. Rachunek zgadzał się z obserwowanymi duplikatami.
Rozwiązanie w trzech krokach. Po pierwsze, okazało się, że API partnera przyjmuje pole external_id i odrzuca duplikaty po nim, choć w dokumentacji wspomniano o tym jednym zdaniem. Pole zaczęto wypełniać stabilnym identyfikatorem z lokalnego Outboxa. Po drugie, okna rotacji zsynchronizowano z wysyłką: na 15 sekund przed rotacją nowe zamówienia nie były wysyłane. Po trzecie, dodano uzgadnianie co 10 minut. Wynik za kwartał: zero duplikatów, liczba ponowień spadła o 70% dzięki synchronizacji z rotacją, średni czas składania zamówienia wzrósł o 1,2 sekundy z powodu oczekiwania na okna — akceptowalna cena.
Przypadek 2. Serwis płatniczy i współbieżne ponowienia
Serwis fintech zaimplementował idempotentność po swojej stronie: nagłówek był przyjmowany, klucz zapisywany w bazie, przy ponowieniu zwracana była migawka. Duplikaty mimo to się pojawiały, rzadko, ale regularnie: około jednego na 40 tysięcy operacji. Dochodzenie pokazało, że sprawdzenie klucza odbywało się przez odczyt, a potem przez zapis, i klienci z agresywnymi timeoutami (dwa ponowienia w ciągu sekundy przez różne proxy) trafiali w okno między nimi.
Zamieniono to na wstawienie z unikalnym indeksem i dodano stan in_progress z odpowiedzią 409 i nagłówkiem Retry-After na jedną sekundę. Dodano metrykę współbieżnych ponowień. Pokazała ona coś nieoczekiwanego: 2% wszystkich operacji dostaje co najmniej jedno 409, czyli klienci powtarzają znacznie agresywniej, niż zakładano. Serwis zaktualizował dokumentację z zaleceniami dotyczącymi timeoutów, i po dwóch miesiącach udział 409 spadł do 0,3%. Duplikatów — zero przez pół roku.
Przypadek 3. Integracja z marketplace a batche
Sprzedawca ładował stany i ceny na marketplace batchami po 500 pozycji przez proxy. Idempotentność batcha była na poziomie całego żądania. Przy zerwaniu połączenia ponowienie albo było odrzucane (batch w toku), albo zwracało migawkę częściowego wyniku, z której nie było jasne, które pozycje się zaktualizowały. Sprzedawca wnioskował „nie zaktualizowano” i ładował od nowa, co tworzyło wyścigi między starym a nowym batchem.
Rozwiązanie: przejść na batche z identyfikatorami operacji per element i pytać o status per element po nieokreślonym zakończeniu. Rozmiar batcha zmniejszono do 100 pozycji, żeby czas przetwarzania nie przekraczał timeoutu. Liczba „zawieszonych” aktualizacji spadła z dziesiątek dziennie do zera, a rozbieżności stanów, wcześniej regularnie prowadzące do anulowań zamówień kupujących, zniknęły.
Przypadek 4. Agent automatyczny i ponowienia łańcuchowe
Trend 2026 roku: coraz więcej integracji wykonują autonomiczne agenci oparci na dużych modelach językowych, którzy wywołują API według instrukcji. Zespół wdrożył takiego agenta do składania zamówień u dostawców. Agent przy nieokreślonej odpowiedzi „rozmyślał” i decydował powtórzyć operację, generując nowe żądanie. Kluczy nie było, bo agent formował wywołanie za każdym razem od nowa. W pierwszym tygodniu — 11 duplikatów zakupów.
Poprawka: agentowi zabroniono formować żądania tworzenia bezpośrednio. Tworzy rekord zamiaru w Outboxie przez narzędzie wewnętrzne, a wysyłkę wykonuje deterministyczny serwis z kluczami i uzgadnianiem. Agent dostaje tylko końcowy status. Duplikaty zniknęły, a przy okazji pojawiło się pełne śledzenie, kto i dlaczego zainicjował każdy zakup. Wniosek ogólny: systemy autonomiczne z możliwością ponowień to nowe i potężne źródło duplikatów, i bariera idempotentności jest dla nich obowiązkowa.
FAQ: trudne pytania o idempotentność i ponowienia
Czy klucz idempotentności jest potrzebny dla PUT i DELETE, skoro są idempotentne ze specyfikacji?
Formalnie nie: ponowienie PUT z tą samą treścią da ten sam stan. Ale są niuanse. Jeśli PUT zwraca 201 przy tworzeniu i 200 przy aktualizacji, ponowienie zwróci inny status i klient może zinterpretować go inaczej. DELETE przy ponowieniu zwróci 404 zamiast 204, co często jest obsługiwane jako błąd. Klucz z migawką odpowiedzi czyni zachowanie przewidywalnym. Poza tym, jeśli PUT wywołuje efekty uboczne (wysłanie powiadomienia, zapis do audytu), wykonają się ponownie. Idempotentność metody nie równa się idempotentności wszystkich efektów ubocznych.
Co zrobić, jeśli serwer zwrócił 409 in_progress, a pierwsza próba faktycznie umarła?
To odpowiedzialność serwera: musi mieć mechanizm odzyskiwania zawieszonych rekordów z progiem czasowym. Klientowi warto czekać na 409 nie w nieskończoność, a ograniczoną liczbę razy (na przykład do dwóch minut), potem przełączać operację w unknown i przekazywać do uzgadniania. Jeśli serwer systematycznie trzyma in_progress dłużej niż rozsądnie, to defekt implementacji, o którym trzeba powiadomić właściciela API.
Jak postąpić z kluczem, jeśli żądanie idzie przez kilka proxy w łańcuchu?
Nic specjalnie: klucz przekazywany jest w nagłówku i przechodzi przezroczysto przez dowolny łańcuch. Jedyne, co warto sprawdzić, to czy jakiś pośredni węzeł nie usuwa niestandardowych nagłówków. Niektóre korporacyjne bramy filtrują nagłówki po białej liście. Prosty test: wysłać żądanie przez cały łańcuch na własny endpoint debugowy i upewnić się, że nagłówek dotarł.
Czy można użyć hasha treści żądania jako klucza i nic nie przechowywać po stronie klienta?
Można, ale z zastrzeżeniami. Dwa różne zamówienia o identycznej treści (ten sam produkt, ta sama kwota, ten sam kupujący) dostaną jeden klucz i drugie zostanie odrzucone jako ponowienie. Żeby tego uniknąć, do treści dodaje się unikalny komponent — identyfikator koszyka albo lokalny numer porządkowy. Wtedy hash z treści staje się deterministycznym kluczem operacji. Takie podejście jest wygodne dla klientów bez niezawodnego lokalnego magazynu, ale wymaga ścisłej normalizacji treści: zmiana kolejności pól w JSON zmieni hash.
Jak długo czekać przed ponowieniem, żeby serwer zdążył dokończyć pierwszą próbę?
To pytanie o politykę ponowień, ale z punktu widzenia kontraktu ważne jest jedno: jeśli serwer obsługuje in_progress z 409, nie trzeba czekać „na oko” — serwer sam powie, że operacja jeszcze się wykonuje. Jeśli serwer takiego stanu nie ma, interwał przed ponowieniem musi przekraczać 99. percentyl czasu przetwarzania operacji na serwerze. Można go poznać z dokumentacji, z metryk udanych żądań albo empirycznie na stanowisku testowym.
Czy warto czynić idempotentnymi operacje odczytu?
GET jest idempotentny z definicji, klucz nie jest mu potrzebny. Jest jednak wyjątek: „odczyt z efektem ubocznym”, na przykład GET, który oznacza powiadomienie jako przeczytane albo pobiera limit. To architektoniczny zapaszek; takie operacje lepiej przerobić na POST z kluczem niż doczepiać idempotentność do GET-a.
Co zrobić z kluczami przy migracji albo zmianie wersji API?
Włączaj wersję endpointu do zakresu działania klucza na serwerze. Wtedy klucz użyty w v1 nie zderzy się z tym samym kluczem w v2. Dla klienta zasada jest prosta: migracja to nowe operacje z nowymi kluczami, stare klucze nie są przenoszone. Jeśli operacja była w unknown w momencie migracji, najpierw rozwiąż ją uzgadnianiem, potem migruj.
Jak wytłumaczyć biznesowi, po co wydawać sprint na idempotentność, jeśli duplikaty „prawie się nie zdarzają”?
Policz koszt jednego duplikatu: anulowanie, zwrot, wsparcie, reputacja, czasem kary od partnera. Pomnóż przez obserwowaną częstotliwość. Potem pokaż, że częstotliwość rośnie nieliniowo przy awariach sieci: w spokojny dzień zero duplikatów, w dniu awarii u operatora — setki w ciągu godziny. Idempotentność to ubezpieczenie ze znaną składką i nieznaną, ale potencjalnie ogromną wypłatą. Dodatkowo daje efekt uboczny: możliwość agresywnego powtarzania żądań bez strachu, co przyspiesza odzyskiwanie po awariach.
Czy idempotentność zwiększa obciążenie serwera?
Nieznacznie: jeden dodatkowy zapis i jeden odczyt na operację. Za to zmniejsza obciążenie w scenariuszach awaryjnych, bo ponowienie zwraca migawkę w milisekundach zamiast pełnego przetwarzania zamówienia. Przy sztormie ponowień serwer z idempotentnością znosi obciążenie lepiej niż bez niej — jest to kontrintuicyjne, ale potwierdzone praktyką.
Zakończenie: kontrakt zamiast nadziei
Zbierzmy najważniejsze. Każda sieć dostarcza żądania według zasady „co najmniej raz”. Proxy — szczególnie mobilne, z rotacją i kanałem radiowym — czynią ponowienia nie rzadkością, a normą. Polityka ponowień odpowiada na pytanie „kiedy i jak powtarzać”. Idempotentność odpowiada na pytanie „dlaczego ponowienie niczego nie zepsuje”. Bez drugiej odpowiedzi pierwsza jest niebezpieczna.
Bezpieczne ponowienie opiera się na trzech filarach. Klucz operacji, zrodzony przed pierwszą próbą i żyjący w twojej bazie, a nie w kliencie HTTP. Kontrakt serwerowy z atomową rezerwacją, stanem in_progress, odciskiem treści, migawką odpowiedzi i rozsądnym TTL. Uzgadnianie jako ostatnia linia obrony dla operacji, które utknęły w niepewności. Jeśli serwer nie daje kontraktu, rolę klucza przejmuje naturalny identyfikator, a rolę magazynu — twój Outbox.
Co zrobić dalej, jeszcze dziś:
- Znajdź w swoich integracjach wszystkie operacje POST, które powtarzają się automatycznie. Dla każdej odpowiedz: czy jest klucz, gdzie się generuje, czy zgadza się przy ponowieniach.
- Przeczytaj dokumentację partnerskich API pod kątem pól external_id i nagłówka Idempotency-Key. Sprawdź zachowanie w środowisku testowym dwoma identycznymi żądaniami.
- Dodaj stan unknown do modelu operacji i proces uzgadniania dla niego.
- Jeśli jesteś właścicielem serwera, przejedź trzy testy: współbieżne ponowienia, pad między wykonaniem a utrwaleniem, ponowienie z innego IP.
- Wyprowadź na dashboard stosunek ponowień do unikalnych operacji. To twój wskaźnik zdrowia kanału przez proxy.
Idempotentność to rzadki przypadek, gdy dyscyplina inżynierska bezpośrednio przekłada się na spokój biznesu. Raz zaprojektowany kontrakt przez lata chroni przed duplikatami, sztormami ponowień i nocnymi telefonami z księgowości. I, szczerze mówiąc, jest szczególna przyjemność w patrzeniu na wykres tysięcy ponowień przez niestabilny kanał i widzeniu w kolumnie duplikatów pewnego zera.