Stripe pamięta twoje żądanie, gdy odpowiedź znika

Co obejmuje ten film

• Idempotentność dotyczy zamierzonego efektu powtórzenia operacji. Stripe API v1 dodaje udokumentowaną umowę odtwarzania zapisanej odpowiedzi.
• Ponowienie tej samej logicznej akcji używa tego samego klucza i parametrów. Zachowaj klucz operacji we wszystkich oddzielnych wywołaniach SDK lub restartach aplikacji; genuinely nowa akcja potrzebuje własnego klucza.
• Po rozpoczęciu wykonywania punktu końcowego, Stripe API v1 zapisuje status i treść pierwszego żądania, w tym błędy 500, i zwraca tę zapisaną odpowiedź przy ponowieniach.
• Zmienione parametry z tym samym kluczem powodują niezgodność. Błędy walidacji i konflikty współbieżnego wykonywania nie zapisują idempotentnego wyniku dla tej próby i mogą zostać ponowione.
• Stripe przechowuje klucze API v1 przez co najmniej 24 godziny i może je później usunąć. Ogranicz nierozwiązane ponowienia sieciowe do pierwszych 24 godzin, a następnie zatrzymaj się i uzgodnij wynik przed powtórzeniem operacji.
• Buforowany błąd 500 może być wielokrotnie odtwarzany po odzyskaniu łączności. Pierwotna operacja mogła mieć skutki uboczne; użyj odpowiedniego obiektu, żądania w panelu kontrolnym i webhooków, aby ustalić jej wynik.
• API v2 używa innej semantyki odtwarzania. Klucz nie gwarantuje uniwersalnej dostawy dokładnie raz dla wiadomości e-mail, inwentarza i każdej lokalnej operacji bazy danych.

Przetłumaczona transkrypcja

Przetłumaczono z oryginalnej narracji angielskiej. Dostępne audio i napisy są kontrolowane przez YouTube.

Czy limit czasu anulował Twoją płatność?

0:00 Myślisz, że limit czasu oznacza, że Twoja płatność się nie powiodła. Serwer może zakończyć operację, podczas gdy odpowiedź znika, pozostawiając Twoją płatność z pewnością niczego nie wyświetlającą. Dlaczego ponowienie może naliczyć opłatę ponownie? Jak Stripe zapamiętuje próbę? Kiedy należy przestać ponawiać? I pamiętaj o jednym paskudnym szczególe. Zapamiętany błąd może przetrwać problem z siecią.

0:17 Wróćmy do tego. To jest The Daily Diff, pod maską.

Co identyfikuje klucz idempotentności?

0:21 Idempotentność oznacza, że powtórzenie operacji ma ten sam zamierzony efekt, co wykonanie jej raz. Klucz idempotentności etykietuje jedną logiczną akcję. Stripe's API w wersji pierwszej rozpoznaje tę etykietę przy ponowieniach i odtwarza zapisaną odpowiedź. Wyobraź sobie kupowanie kawy. Stripe kończy Twoje żądanie płatności, a odpowiedź ginie w drodze powrotnej do domu. Klient widzi kręcące się kółko. Ich bank może mieć bardziej ekscytującą interpretację. Niezabezpieczone żądanie utworzenia może powtórzyć skutek uboczny.

Jak ten sam klucz sprawia, że ponowienie jest bezpieczne?

0:45 Dołącz unikalny klucz przed pierwszą próbą i zachowaj go do ponowień. Jeśli Twoja aplikacja zostanie ponownie uruchomiona, zachowaj ten klucz wraz z operacją w swoich zapisach. Dla API Stripe w wersji pierwszej, po rozpoczęciu wykonywania punktu końcowego, zapisywany jest status i treść pierwszego żądania. Wyślij ponownie ten sam klucz i parametry, a Stripe zwróci zapisaną odpowiedź. Kawa pozostaje na miejscu, podczas gdy paragon podróżuje ponownie.

Co dokładnie zapisuje Stripe?

1:07 Oto rzeczywiste sformułowanie Stripe. Ponowienia z tym samym kluczem zwracają zapisaną odpowiedź, w tym błędy pięćsetne. Dokumentacja wykonuje więcej pracy niż Twój optymistycznie nazwany pomocnik ponowień. Klient stuka ponownie. Twoja aplikacja decyduje, czy to wznawia oczekujący zakup, czy rozpoczyna inny jeden. Z genuinely nową kawą wiąże się nowy klucz. Świeży klucz dla każdego ponowienia sieciowego niweczy ochronę.

1:27 Różne parametry z tym samym kluczem wywołują niezgodność.

Co się dzieje, gdy żądanie się zmienia?

1:30 Jeśli parametry nie przejdą walidacji, lub inne żądanie z tym kluczem jest nadal wykonywane, Stripe nie zapisuje idempotentnego wyniku dla tej próby. Te żądania mogą zostać ponowione. Żądanie wyścigowe otrzymuje konflikt. To są zasady wersji pierwszej. Wersja druga zachowuje się inaczej. Nagłówek nie może obiecać dostarczenia dokładnie raz w całym systemie. Poczta e-mail, inwentarz i Twoja baza danych potrzebują obsługi błędów.

1:52 Klucz chroni operację w ramach jej udokumentowanego zakresu. Stripe przechowuje klucze wersji pierwszej przez co najmniej dwadzieścia cztery godziny i może je usunąć

Jak długo zapamiętany wynik jest bezpieczny do ponowienia?

1:59 po tym czasie. Przycięty klucz może wykonać nowe żądanie. Zachowaj nierozwiązane ponowienia w ciągu pierwszego dnia. Poza tym, zatrzymaj się i uzgodnij pierwotny wynik. Użyj wykładniczego wycofywania i jittera, aby dać serwerowi przestrzeń do oddychania. W przeciwnym razie ponowienia tworzą kolejkę przed płonącą kawiarnią. Biblioteki Stripe obsługują ponowienia, ale sprawdź domyślne ustawienia swojej biblioteki. Ten uporczywy błąd to haczyk.

Dlaczego zapamiętany błąd może ciągle powracać?

2:20 Buforowana odpowiedź pięćsetna jest odtwarzana po odzyskaniu łączności. Pierwotna operacja mogła wywołać skutki uboczne. Rozwiąż jej wynik, używając obiektów, Panelu kontrolnego i webhooków. Nowy klucz może powtórzyć akcję. Jeśli wolisz to przeczytać niż usłyszeć, diff trafia na Twoją skrzynkę odbiorczą każdego ranka, za darmo na daily diff dot dev, link poniżej.

Czy wysłałbym przycisk ponowienia z tą umową?

2:39 Werdykt, pod maską. Wysyłaj to. Wysyłałbym stabilne klucze z ograniczonymi ponowieniami i uzgadnianiem, aby klienci dostawali kawę bez finansowania Twojej edukacji w zakresie systemów rozproszonych. I to jest dzisiejszy diff. Jestem Niko z Axrisi. Łącz odpowiedzialnie.

Źródła

1. Idempotent requestsStripe Docs
2. Designing robust and predictable APIs with idempotencyStripe Engineering — Brandur Leach
3. Advanced error handlingStripe Docs
4. HTTP Semantics — RFC 9110 §9.2.2 Idempotent MethodsIETF / RFC Editor