Objaśnienie · Inżynieria

Czym jest klucz idempotencji: i dlaczego potrzebuje go Państwa aplikacja

4 listopada 2026 · Software by Design

Każda aplikacja działająca offline prędzej czy później odpowiada na to samo pytanie: co się dzieje, gdy użytkownik stuka „wyślij” dwa razy, albo gdy sieć umiera w połowie żądania i klient ponawia? odpowiedź to niewielki mechanizm zwany kluczem idempotencji, oto jak działa i jak wygląda w naszym własnym kodzie.

Problem w jednym zdaniu

Sieci są zawodne, więc klient musi ponawiać. Retry oznacza, że ta sama logiczna akcja dociera więcej niż raz. Bez zabezpieczenia „więcej niż raz” staje się dwoma wpisami czasu, dwiema fakturami, dwiema rezerwacjami.

Zwróćmy uwagę, czym problem nie jest: nie jest „użytkownik kliknął dwa razy”. Użytkownicy klikają podwójnie, ale typowy przypadek jest znacznie mniej widoczny, aplikacja mobilna na budowie traci zasięg, kolejkuje odbicie wejścia, serwer je stosuje, odpowiedź ginie w drodze i aplikacja (całkowicie słusznie) wysyła ją ponownie. Duplikat to system działający zgodnie z założeniem.

Mechanizm

Klucz idempotencji to unikalny identyfikator, który klient generuje na logiczną akcję, nie na żądanie HTTP. Klient dołącza ten sam klucz do oryginalnego żądania i każdego retry tej akcji. Serwer pamięta klucze, które widział. Gdy klucz dociera drugi raz, serwer zwraca pierwszy wynik zamiast wykonać mutację dwukrotnie.

Trzy właściwości sprawiają, że to działa:

  • Klucz należy do klienta. Gdyby wydawał go serwer, retry sprzed jego otrzymania nie dałby się zidentyfikować. Klucz jest wybijany na urządzeniu, w naszych aplikacjach mobilnych to UUID tworzony w chwili, gdy użytkownik odbija, a nie gdy odpalane jest wywołanie sieciowe.
  • Wpis to rezerwacja, nie wynik. Serwer najpierw zapisuje rezerwację („ten klucz jest już mój, wynik w toku”), a dopiero potem mutuje. Konkurujący retry trafia na rezerwację i czeka na oryginalny wynik albo go odtwarza, nigdy nie wślizgnie pod nią drugiej mutacji.
  • Rezerwacja wiąże payload. Razem z kluczem zapisujemy hasz akcji i jej znormalizowanych wejść. Ten sam klucz, inny payload → konflikt 409, nie ciche nadpisanie. Retry powinno zawsze znaczyć wyłącznie „to samo jeszcze raz”.

Gdzie pojawia się w naszych aplikacjach

Mobilna kolejka odbić ArbeitszeitCheck niesie clientRequestIdcodeclient_event_id przez każde odtworzenie. TourCheck wiąże ten sam kontrakt z code przy potwierdzeniach punktów kontrolnych, gdzie odtworzenie porównuje całą rezerwację, notatkę, zdjęcie, znacznik czasu, z zapisanym wierszem. Wygaśnięcie ma takie samo znaczenie jak deduplikacja: nasze wiersze rezerwacji żyją siedem dni, wystarczająco długo, by pokryć długi weekend bez zasięgu, na tyle krótko, by tabela pozostała kolejką, a nie logiem.

Wersja skrócona dla Państwa aplikacji

Jeśli Państwa API mutuje stan, a klient może ponawiać, a każdy klient może, potrzebują Państwo dokładnie trzech rzeczy: klucza generowanego po stronie klienta na akcję, wiersza rezerwacji przy pierwszym zapisie i hasza payloadu, by „ten sam klucz” znaczył też „ta sama intencja”. To cały wzorzec. Wszystko inne, okna odtwarzania, zadania porządkowe, kody statusu konfliktu, to hydraulika wokół tych trzech zobowiązań.