Crypto Casino
Bieg torrent
Pięć krytycznych błędów integracji API przy uruchamianiu
Błąd # 1. Brak idempotencji i „burza” rekolekcji
Objawy: duplikaty zleceń/płatności, rozbieżności w kwotach, sporne zwroty, alerty DLQ rosną.
Korzeń: powtarzająca się dostawa żądań/haków i klap sieciowych jest normalna. Jeśli operacja „create/write off” nie jest idempotent, przekłada się pomnożyć uszkodzenia.
Jak
Idempotence-Key/' operation _ id' do wszystkich niebezpiecznych metod (POST/PATCH).
Niepowtarzalny indeks w bazie danych dla 'operation _ id'. Powtórka - zwróć poprzedni wynik.
Haki przez tabelę skrzynki odbiorczej (dedupe by 'event _ id + signature'). Zdarzenia wychodzące - Outbox.
Retrai: maksymalnie 1-2 razy, wykładnik + jitter, tylko dla bezpiecznych operacji.
Konwencja HTTP (przykład):http
POST/v1/płatności
Idempotency-Key: ik_f35a2
Typ treści: aplikacja/json
{"kwota": 5000, "waluta": "EUR", "źródło": "card_..."}sql
ALTER TABLE PAYMENTS ADD CONSTRAINT uniq_op UNIQUE (operation_id);python dla i w zakresie (2):
try: return call_api (ładunek użytkowy, timeout = 0. 6)
z wyjątkiem Timeout:
sen (0. 05 2i + losowo. jednolity (0, 0. 05))
podnieść w górę StreamNiedostępne- Cała logika „monetary/creating” ma 'operation _ id' i uniq index.
- Przychodzące haki internetowe tylko za pośrednictwem skrzynki odbiorczej z idempotentem.
- Klient SDK automatycznie ustawia Idempotency-Key.
Błąd numer 2. Timeouts/Retrays vs. SLO: przegrzanie zależności
Objawy: p95 nagle unosi się, kolejki rosną, wyłącznik "bangs'.
Korzeń: całkowity SLO odpowiedzi wynosi 400-600 ms, a czasy do zewnętrznych API to 1-2 s, a nawet przekładki × 3. Robisz dłużej niż możesz i burzę uzależnienia z powtórzeń.
Jak
Harmonogram budżetowy: jeżeli SLO wynosi 400 ms, górna granica czasowa: 250-300 ms; Całkowity czas realizacji SLO ≤ żądanie.
Limity/Backpressure: semafory/worker-pool dla połączeń na każdą zależność. Zatłoczony → 429/503 naraz.
Wyłącznik: 'otwórz' z dozownikiem timeouts/5xx, 'half-open'.
Kontrola wstępu: ograniczenie współistnienia (na gwint, na punkt końcowy/PSP).
Przykład (Go):go sem: = make (chan struct {}, 64 )//limit konkurencji do PSP func callPSP (ctx context. Kontekst, req Req) (Res, błąd) {
wybierz {
przypadek sem <- struct {} {}:
defer func () {<-sem} ()
c, anuluj: = kontekst. WithTimeout (ctx, 300time. Milisekunda)
defer anuluj ()
powrót psp. Do (c, req)
domyślnie:
powrót Res {}, ErrBusy//natychmiastowa awaria zamiast niekończącej się kolejki
}
}- Terminy są krótsze niż SLO; retrai ≤ 2; Jest jitter.
- Puli/semafory dla zewnętrznych API; wyłącznik z metrykami.
- Na ruchliwych trasach wracamy 429/Retry-After, a nie utrzymujemy połączenia.
Błąd numer 3. Słabe bezpieczeństwo: Podpisy Webhook, Tajemnice, TLS
Objawy: przejście „innych ludzi” webhooks, sekrety w kodzie/dzienniku, ryzyko MITM.
Korzeń: brak kontroli podpisu/świeżości, sekrety żyją w plikach, starych TLS i słabych nagłówkach.
Jak
Podpis haków internetowych HMAC-SHA256 + 'X-Timestamp' (okno ≤ 5-10 minut), ścisłe porównanie podpisu.
mTLS dla integracji krytycznych lub listy uprawnień IP.
Rotacja tajemnic poprzez Vault/Cloud KMS; minimalne prawa; audyt odejmowania.
TLS 1. 2/1. Tylko 3, HSTS, poprawny CORS (wąska lista źródeł).
Weryfikacja podpisu (Python):python def verify (sig_hdr, ts_hdr, body, secret):
jeśli abs (czas. czas () - int (ts_hdr))> 600: podwyżka wygasła ()
calc = hmac. nowe (tajne, (ts_hdr + „.”. + ciało). kodowanie (), hashlib. sha256). heksdigest ()
jeśli nie hmac. compare_digest (calc, sig_hdr): podnieść BadSig ()- Wszystkie haki są podpisane i zweryfikowane; okno świeżości jest ograniczone.
- Sekrety w KMS/Vault, jest rotacja i audyt.
- TLS/HSTS włączone; punkt CORS; IP/mTLS, w stosownych przypadkach.
Błąd numer 4. Dryf kontraktowy: program „żył swoim życiem”
Objawy: prod spadł „tylko u niektórych klientów”, 500/422 w dziennikach, różne wersje SDK i API argument.
Korzeń: nie ma ścisłego opisu umów, wstecznych niezgodnych zmian, „cichych” pól, różnych znaczeń dla tych samych nazw.
Jak
Umowa pierwsza: OpenAPI/AsyncAPI + serwer/generacja klienta; dla zdarzeń - Avro/Protobuf + Schema Registry.
Wersioning: 'v1 → v2' (URI/nagłówek), plan odchylenia, okres łaski.
Wsteczny kompat: tylko dodatkowe zmiany w drobnych wersjach; nie można usunąć/zmienić nazwy bez v-bump.
Testy kontraktowe: Pact/Buf - dostawca/odbiorca są testowane w CI.
Przykłady:yaml
OpenAPI: jasny rodzaj sumy w małych jednostkach amount_minor:
typ: minimum całkowite: 0 opis: suma w minimalnych jednostkach walutowych (liczba całkowita)- Umowy są przechowywane w git, CI waliduje/przerywa, jeśli są niezgodne.
- Schemat rejestrów zdarzeń, „back/forward” kompatybilność.
- Strona dokująca zmian, daty deprymacji, ławka testowa dla partnerów.
Błąd numer 5. Start „ślepy”: brak metryk/kłód/szlaków i piaskownicy
Objawy: „nic nie jest widoczne”, wsparcie wypełnia, debag - ręce w prod.
Korzeń: obserwowalność nie została uwzględniona, nie ma syntetyki, piaskownica została przetestowana „słowami”.
Jak
Wskaźniki RED/USE: szybkość/błąd/opóźnienie na każdym punkcie końcowym, drogą/metodą.
Korelacja: 'trace _ id' we wszystkich logach i odpowiedziach; Wiązka zaproszeń, webkhuk.
Syntetyka: testy zdrowotne (login/deposit piasek), monitorowanie SLA T + 60 dla webhooks.
Sandbox/stage: całkowicie odizolowane klucze/domeny, fikcyjne PSP, wpisy „nieujęte w raportach”.
Odpowiedź z identyfikatorem śladu:http
HTTP/1. 1 202 Przyjęte
Identyfikator śladu: 7f2b3d8e9c1a4
Lokalizacja :/ v1/ops/req_42/status- Wskaźniki RED/USE, deski rozdzielcze, wpisy (objawy + przyczyny).
- Szlaki końcowe; Dzienniki JSON, bez PII, z 'trace _ id'.
- Syntetyka z kluczowych regionów; piaskownica jest wymagana, różne klucze.
Plan prelaunch (T-7 → T-0)
T-7 dni:- Skanowanie umowy końcowej: czy istnieją niezgodne ze wspólnym rynkiem zmiany; zamrożenie systemów.
- Sekrety/certyfikaty: sprawdź rotację, dostęp, zasady KMS.
- Syntetyka 24 × 7, wpisy są powiązane z dyżurem.
- Załadunek mini-run (wybuch 2-5 minut): p95/baseny/kolejki w zielonej strefie.
- DRY-RUN webhooks (powtórki, 5xx, jitter), sprawdzenie DLQ.
- „Książka telefoniczna” partnerów: kontakty L1/L2, kanał wojenny.
- Ruch kanałowy 5% → 25% → 50% dla bram SLO; gotowy zwrot.
- Kill-switch/feature-flags na ryzykowne funkcje są wliczone.
- Sala wojenna jest aktywna, szablony stanu są przygotowane.
Plan Rollback (jeśli coś poszło nie tak)
1. Zwolnij ruch do poprzedniej stabilnej wersji/trasy.
2. Wyłączyć kontrowersyjne zmiany phicheflag.
3. Ustabilizować kolejki/baseny, zatrzymać odwrót w burzy.
4. Po incydencie: zbierać linię czasu, korzenie, zadania (stałe poprawki/umowy).
Stół do samodzielnego badania początkowego (krótki)
Często pytany „co jeśli”...
... czy dostawca nie obsługuje Idempotency-Key?
Zapisz 'hash (body)' + 'partner _ request _ id' i wprowadź swoją idempotencję.
... haki czasami przychodzą „przed” odpowiedzią?
Sew na 'operation _ id' i tymczasowo zachować status' nieznany → reconcile '; okresowy pojednawca zamknie rozbieżności.
... trzeba wspierać starych klientów i nowych?
W wersji punkty końcowe ('/v1'i '/v2 '), trasa według nagłówka/URI, utrzymują kompatybilność wsteczną przez co najmniej N miesiące.
Wznów streszczenie
Awarie integracji są prawie zawsze o tym samym: brak idempotencji, błędne czasy i rekolekcje, słaby podpis haków webowych, dryfowanie kontraktów i brak widoczności. Naprawić kontrakty z wyprzedzeniem, włączyć obserwowalność, umieścić limity/backprescher, podpisać wszystkie zewnętrzne interakcje i uruchomić syntetyki. Następnie, nawet w przypadku niepowodzeń partnerów, Twoje wydanie pozostanie do zarządzania - bez pieniędzy utraconych w retras, i bez bezsennej nocy dla całego zespołu.