Adaptery dostawców

Adapter dostawca - izolowana warstwa integracyjna (warstwa antykorupcyjna, ACL), która przekłada kontrakt zewnętrznego dostawcy (dostawca gier, brama płatnicza, KYC/AML, ocena ryzyka, powiadomienia itp.) na wewnętrzny język domeny i odwrotnie. Chroni domenę przed niestabilnymi interfejsami API, anomaliami sieciowymi, ewolucjami schematów i polityką bezpieczeństwa.

1. Oddzielenie od produkcji: Nie „surowy” ładunek zewnętrzny uderza w rdzeń.

2. Niezawodność: zarządzanie awariami (timeouts, retries, DLQ, wyłącznik).

3. Spójność: idempotencja, kolejność kluczy, komunikaty transakcyjne.

4. Działanie: mierniki, śledzenie, limity, izolacja transferowa i rezydencja.

1) Obszar odpowiedzialności adaptera

Zamówienia: opis systemów zewnętrznych/punktów końcowych; mapowanie → polecenia/zdarzenia wewnętrzne.
Transport: REST/gRPC/WebSocket/SQS/Kafka/SFTP; basen podłączeniowy, ciśnienie wsteczne.
Bezpieczeństwo: mTLS, OAuth2, HMAC, klucze/certyfikaty na lokatora/region, rotacja tajemnic.
Niezawodność: timeouts, retras with jitter, wyłącznik, deduplication.
Idempotencja: 'Idempotence-Key '/' request _ id', przechowywanie odpowiedzi/statusów.
Obserwowalność: mierniki SLO, kłody strukturalne, śledzenie.
Wersioning: wsparcie dla wielu wersji schematów/punktów końcowych.
Operacje: ficheflags, kanarki, piaskownice, certyfikat.

2) W stosownych przypadkach (przykładowe konteksty)

Gra/RGS: rozpocząć/zamknąć rundę, zakłady/wygrane, żetony sesyjne, statusy dostawcy.
Płatności/PSP: wpłaty/wypłaty, statusy haków internetowych, obciążenie zwrotne, 3-D Secure.
KYC/AML: weryfikacja, kontrole sankcji/POP, monitorowanie transakcji.
Ryzyko/oszustwo: punktacja, wyzwalacze, blokowanie zaleceń.
Komunikaty: e-mail/SMS/push, limity wysyłki, szablony.

Każdy typ ma własną maszynę stanu zdarzeń i SLA - adapter jest zobowiązany do jego normalizacji.

3) Kontrakt i odwzorowanie (wewnętrzne, zewnętrzne)

• Wprowadzamy opublikowany język wewnątrz adaptera i nigdy nie przeciągamy pól dostawcy.
• Wszystkie wiadomości przenoszą 'lokator _ id',' region ',' provider _ id', 'operation _ id',' version _ ts'.
• Obsługujemy kilka wersji programów zewnętrznych za pośrednictwem maperów.

yaml mapping:
provider: "AcmeRGS"
version: "v3"
inbound:
SpinResultV3 -> Round. Resulted
BonusWinV3  -> Bonus. Wagered outbound:
StartRound  -> POST /v3/sessions/{id}/start
Stake    -> POST /v3/spins compat:
accepts: ["v2","v3"]
emits:  ["v3"]

4) Idempotencja i porządek

Request de-dup: "Idempotency-Key: <operation_id>' in requests; historia '(op_id → stan końcowy/odpowiedź)' z TTL.
Webhook de-dup: tablica „skrzynka odbiorcza (dostawca, event_id)” jako PK.
Kolejność według klucza: serializuj wywołania i przetwarzanie przez 'aggregate _ id' (na przykład' round _ id' lub 'psp _ tx _ id').
Skrzynka odbiorcza/wdychanie: komunikaty transakcyjne na obu krawędziach rurociągu.

5) Niezawodność: czasy, rekolekcje, wyłącznik

Timeouts: krótki klient-side (zorientowany na p95), oddzielny do podłączenia/odczytu.
Przekładki: tylko do pobrania (5xx/timeout/429), wykładnicze backoff + full jitter, limit próby i całkowity termin.
Wyłącznik: otwórz, gdy błąd/opóźnienie wzrosną; wdzięczna degradacja (na przykład wyłączyć wtórne funkcje RGS, ustawić „czekać na wynik”).
DLQ: „trujące” wiadomości z bogatymi meta-informacjami, bezpieczne redrave.

yaml reliability:
timeout_ms:
connect: 1000 read:  1500 retry:
max_attempts: 6 initial_backoff_ms: 200 max_backoff_ms: 8000 jitter: full retry_on: [TIMEOUT, 5xx, 429]
circuit_breaker:
failure_rate_threshold: 20%   # за окно slow_call_threshold_ms: 1500 half_open_max_calls: 10

6) Limity stawek, kwoty, konkurencyjność

Przestrzegać ograniczeń dostawcy (RPS, wybuch, jednoczesność).
Wdrożenie per-najemcy WFQ/DRR (uczciwość), aby „hałaśliwy” klient nie zjadł budżetu.
Szanuj nagłówki 'Retry-After '/' X-ΔLimit-'.
Wewnętrzne kolejki + podciśnienie na produkcie.

7) Bezpieczeństwo i zgodność

Transport: mTLS, TLS 1. 2 +, aktualne apartamenty szyfrujące, jeśli to możliwe.
Uwierzytelnianie: OAuth2 poświadczenia klienta/MTLS, HMAC (podpisane hashes ciała + znacznik czasu), klucze API.
Minimalizacja PII: tylko wymagane pola; maskowanie/edycja w dziennikach i DLQ.
Sekrety: KMS/HashiCorp Vault, automatyczna rotacja, izolacja na najemcę/region.
Zgodność: PCI DSS dla PSP, token do przechowywania zamiast PAN, RODO/lokalnych przepisów dotyczących danych.

8) Wielopoziomowy i wielobranżowy

Konfiguracja klawiszy/punktów końcowych na lokatora/region.
Pobyt danych: połączenia są wykonywane z regionu „domowego”; cross-region - tylko kruszywa.
Izolacja: własne puli połączeń i limity na najemcę.

yaml tenants:
T1:
region: eu-central provider_keys:
acme_rgs: { client_id: "...", cert_ref: "vault://..." }
psp_foo: { hmac_key_ref: "kms://..." }
endpoints:
acme_rgs: "https://eu. api. acme-rgs. com"
psp_foo: "https://eu. api. psp-foo. com"
T2:
region: sa-east
...

9) Obserwowalność: metryki, kłody, śledzenie

• Sukcesy/błędy według klasy (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latency metodą.
• Uruchomienie limitu szybkości, wyłącznik otwarcia/zamknięcia, szybkość DLQ, sukces przekierowania.
• Logi strukturalne: 'lokator _ id',' provider _ id', 'operation _ id',' endpoint ',' status ',' attempt ',' backoff _ ms '.
• Śledzenie: single 'trace _ id', spans' serialize → wyślij → receive → map → publish, 'tags' schema _ version', 'region'.

10) Wersioning i phicheflags

Wsparcie v1/v2 kontraktu zewnętrznego równolegle; migracja - kanaryjska/przez najemców.
Każda nowa funkcja dostawcy jest za flagą; przełączanie bez zwolnienia.
Umowa Evolution: pierwszy dodatek, rygorystyczna walidacja programów (JSON Schema/Proto).

11) Playbooks (książki startowe)

1. Squall 429/limits: włącz globalne przepuszczanie, szanuj 'Retry-After', redystrybuuj okna między lokatorami.
2. Wzrost czasu: zmniejszenie jednoczesności, staranne zwiększenie czasu, otwarty wyłącznik, umożliwienie degradacji funkcji.
3. Niedopasowanie schematu: zamrozić redrive, włączyć kompatybilny maper, zasypać/przerobić.
4. Klapa Webhook: przełącz na tryb pull/reconcile, zastosuj dedup skrzynki odbiorczej.
5. Incydent u dostawcy: przełączyć na piaskownicę/kopię zapasową DC (jeśli istnieje), aktywować operacje „odroczone”.

12) Badanie

Testy umowne: producent/konsument w stosunku do stałych poprawek dostawcy.
Testy chaosu: opóźnienia, krople, nieporządek, duplikaty, częściowa odpowiedź, odłączenie.
Wydajność: stres na kolce pęknięcia; pomiar p95/p99, zachowanie wyłącznika.
Idempotencja: powtarzanie tego samego 'operation _ id' nie powoduje dodatkowych efektów.
E2E piaskownicy: happy-path/chargeback/controversy/cancellation/recalc scripts.

13) Schematy wdrażania

Oddzielny adapter serwisowy: + izolacja, niezależne wersje; − dodatkowa sieć.
Sidecar/plugin: + lokalizacja połączeń; − trudniejsze do zarządzania wersjami.
Biblioteka: + łatwe do wbudowania; − wysokie sprzęgi i wersje motley.

Zalecenie: adapter serwisowy z wyraźnym interfejsem API i cyklem jego wydawania.

14) Przykład API adaptera (Pseudo)

http
POST /adapters/psp/authorize
Headers:
X-Tenant: T1
Idempotency-Key: op-uuid
Body:
{ "amount":"10. 00","currency":"EUR","method":"card","card_token":"tok_..." }

→ 202 Accepted
{
"operation_id":"op-uuid",
"status":"PENDING",
"as_of":"2025-10-31T12:00:00Z"
}

• Webhook z 'provider _ event _ id' →' skrzynka odbiorcza '(PK on' (provider,event_id) ') → mapowanie → zdarzenie domenowe' ΔAuthorized '.

15) Typowe błędy

Wciąganie „surowego” obwodu zewnętrznego do domeny → ciasna łączność i drogie migracje.
Brak idempotencji i skrzynki odbiorczej/outbox → duplikaty efektów i stanów fantomowych.
Retrai bez jitter/limitów → burza i zakaz limitu stawki.
Jedyny globalny basen bez sprawiedliwości → jeden najemca „stawia” wszystkich.
Kłody bez PII wersja/→ identyfikatory nie mogą być badane incydenty i ryzyko zgodności.
Nie ma kanarów/flag → wydanie łamie wszystkich naraz.
Ignorowanie 'Retry-After' i harmonogramów konserwacji dostawcy.

16) Lista kontrolna przedsprzedaży

• Odwzorowanie schematów zewnętrznych → język wewnętrzny; wersje i kompatybilność wsteczna.
• Identyfikacja żądań/haków internetowych ('operation _ id',' inbox ').
• Timeouts, retras z full-jitter, wyłącznik, DLQ i bezpieczny redrive.
• Wartości graniczne uprzywilejowania na najemcę; szacunek dla „Retry-After”.
• mTLS/OAuth/HMAC, tajna rotacja, minimalizacja PII, audyt dostępu.
• Izolacja regionalna i rezydencja danych; konfiguracje na najemcę/region.
• metryki p95/p99, błąd klasy, breaker/429/DLQ-rate; śledzenie.
• Piaskownice i testy kontraktowe; canary rollout i phicheflags.
• Playbooks incydentów i szkolenia dyżurne.
• Dokumentacja: SLA, limity, schematy, procesy ewolucji.

Wnioski

Adaptery dostawców to tarcza i tłumacz między domeną a światem zewnętrznym. Silny ACL z idempotencją, kontrolą błędów i obserwowalnością sprawia, że integracje są przewidywalne, zmniejsza koszty zmian u dostawcy i chroni przed "awariami łańcucha. "Adaptery projektowe jako niezależne, zarządzalne komponenty - a Twój "świat zewnętrzny" przestanie łamać wewnętrzną architekturę.