공급자 어댑터
공급자 어댑터-외부 공급 업체 계약 (게임 공급 업체, 결제 게이트웨이, KYC/AML, 위험 채점, 알림 등) 을 내부 도메인 언어로 변환하는 격리 된 통합 계층 (ACL). 불안정한 API, 네트워크 이상, 스키마 진화 및 보안 정책으로부터 도메인을 보호합니다.
주요 목표:1. 디커플링: "원시" 외부 페이로드가 핵심에 도달하지 않습니다.
2. 신뢰성: 고장 관리 (타임 아웃, 재 시도, DLQ, 회로 차단기).
3. 일관성: demempotency, 주요 순서, 거래 메시징.
4. 운영: 지표, 추적, 제한, 전송 격리 및 거주.
1) 어댑터 책임 영역
계약: 외부 체계/종점에 대한 설명; → 내부 명령/이벤트 매핑.
전송: REST/gRPC/WebSocket/SQS/Kafka/SFT; 연결 풀, 역압.
보안: mSL, OAuth2, HMAC, 테넌트/지역 당 키/인증서, 비밀 회전.
신뢰성: 타임 아웃, 지터를 사용한 배상, 회로 차단기, 중복 제거.
이념성: 'Idempotency-Key '/' 요청 _ id', 응답/상태 저장.
관찰 가능성: SLO 지표, 구조 로그, 추적.
버전 지원: 여러 버전의 체계/엔드 포인트 지원.
운영: ficheflags, 카나리아 릴리스, 샌드 박스, 인증.
2) 해당되는 경우 (예: 상황)
게임/RGS: 시작/종료 라운드, 베팅/승, 세션 토큰, 제공자 상태.
결제/PSP: 예금/인출, 웹 후크 상태, 채권 회수, 3D 보안.
KYC/AML: 검증, 제재/POP 점검, 거래 모니터링.
위험/사기: 득점, 트리거, 권장 사항 차단.
Comms: 전자 메일/SMS/푸시, 메일 제한, 템플릿.
각 유형에는 자체 이벤트 상태 머신과 SLA가 있습니다. 어댑터는이를 정규화해야합니다.
3) 계약 및 매핑 (외부)
원칙:- 우리는 어댑터 내부에 게시 된 언어를 입력하고 공급자의 필드를 드래그하지 않습니다.
- 모든 메시지에는 '테넌트 _ id', '지역', '제공자 _ id', 'operation _ id', '버전 _ ts' 가 있습니다.
- 매퍼를 통해 여러 버전의 외부 구성표를 지원합니다.
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) 이념과 질서
요청 해제: 요청시 'Idempotency-Key: <operation _ id>'; TTL의 스토리 '(op _ id → 최종 상태/응답)'.
Webhook ddup: 테이블 '받은 편지함 (제공자, 이벤트 _ id)' 을 PK로 표시합니다.
키 별 순서: '집계 _ id' (예: 'round _ id' 또는 'psp _ tx _ id') 로 호출 및 처리를 직렬화합니다.
전송/인복싱: 파이프 라인의 양쪽 가장자리에있는 거래 메시징.
5) 신뢰성: 타임 아웃, 휴식, 회로 차단기
타임 아웃: 연결/읽기를 위해 별도의 짧은 클라이언트 측 (p95 지향).
배상: 재시도 가능 (5xx/타임 아웃/429), 지수 백오프 + 전체 지터, 시도 제한 및 총 마감일.
회로 차단기: 오류/대기 시간이 증가하면 열립니다. 우아한 저하 (예: 보조 RGS 기능을 비활성화하고 "결과 대기" 를 설정).
DLQ: 풍부한 메타 정보, 안전한 재 드레이브가있는 "유독 한" 메시지.
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: 106) 요율 제한, 할당량, 경쟁력
공급자 제한 사항 관찰 (RPS, 버스트, 동시성).
"잡음" 클라이언트가 예산을 삭감하지 않도록 테넌트 당 WFQ/DRR (공정성) 을 구현하십시오.
'재생 후 '/' X-RateLimit-' 헤더를 존중하십시오.
내부 대기열 + 제품의 역압.
7) 안전 및 준수
전송: mTLS, TLS 1. 2 +, 현재 암호 제품군, 가능한 경우 인증서 고정.
인증: OAuth2 클라이언트 자격 증명/MSL, HMAC (서명 된 바디 해시 + 타임 스탬프), API 키.
PII 최소화: 필요한 필드 만; 로그 및 DLQ의 마스킹/편집.
비밀: KMS/HashiCorp Vault, 자동 회전, 임차인/지역당 격리.
준수: PSP 용 PCI DSS, PAN 대신 토큰 스토리지, GDPR/로컬 데이터 법률.
8) 다중 테넌트 및 다중 지역
테넌트/지역당 키/엔드 포인트 구성.
데이터 레지던트: 전화는 "홈" 지역에서 이루어집니다. 교차 지역-집계 만.
격리: 자체 연결 풀 및 임차인 당 한계.
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) 관찰 가능성: 지표, 로그, 추적
메트릭:- 클래스 별 성공/오류 (2xx/4xx/5xx/타임 아웃/429).
- 방법별로 p50/p95/p99 대기 시간.
- 속도 제한 작동, 개방/폐쇄 차단기, DLQ- 속도, 재 구동 성공.
- 구조 로그: '테넌트 _ id', 'provesser _ id', 'operation _ id', 'endpoint', 'state', 'sid', 'backoff _ ms'.
- 추적: 단일 'trace _ id', 스팬 "직렬화 → 전송 → 수신 → 맵 → 게시", 태그 'skima _ version', 'region'.
10) Versioning 및 phicheflags
외부 계약의 v1/v2를 병렬로 지원합니다. 마이그레이션 - 카나리아/세입자.
새로운 공급자 기능은 깃발 뒤에 있습니다. 출시없이 전환.
진화 계약: 체계의 추가 우선 엄격한 검증 (JSON Schema/Proto).
11) 플레이 북 (런북)
1. Squall 429/limes: 글로벌 스로틀 링 켜기, 'Reduction-After' 존중, 세입자 간의 창문 재분배.
2. 타임 아웃 성장: 동시성 감소, 타임 아웃 신중하게 증가, 오픈 브레이커, 기능 저하 가능
3. 스키마 불일치: 재구동 동결, 호환 가능한 매퍼 활성화, 백필/재처리.
4. 웹 후크 플랩: 풀/조정 모드로 전환하고받은 편지함을 적용하십시오.
5. 공급자의 사고: 샌드 박스/백업 DC로 전환 (있는 경우) "지연된" 작업을 활성화하십시오.
12) 테스트
계약 테스트: 고정 공급자 수정에 대한 생산자/소비자.
혼돈 테스트: 지연, 낙하, 고장, 복제, 부분 응답, 단절.
성능: 버스트 스파이크에 대한 스트레스; 측정 p95/p99, 차단기 동작.
이념성: 동일한 'operation _ id' 를 반복하면 추가 효과가 발생하지 않습니다.
샌드 박스 E2E: 행복한 경로/chargeback/논쟁/취소/recalc 스크립트.
13) 배포 패턴
별도의 서비스 어댑터: + 격리, 독립 릴리스; -추가 네트워크.
사이드카/플러그인: + 통화 지역; -버전을 관리하기가 더 어렵습니다.
라이브러리: + 포함하기 쉬운; -높은 커플 링 및 잡종 버전.
추천: 명확한 API와 릴리스주기를 갖춘 서비스 어댑터.
14) 어댑터 API 예 (의사)
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"
}- 'provider _ event _ id' → '받은 편지함' (PK on '(provesser, 이벤트 _ id)') → 도메인 이벤트 'PaymentAuthorized' 가 포함 된 웹 후크.
15) 전형적인 오류
"원시" 외부 회로를 도메인 → 엄격한 연결 및 고가의 마이그레이션으로 가져옵니다.
demotency 및 받은 편지함/아웃 박스 → 중복 효과 및 팬텀 상태 부족.
지터/제한이없는 배신자 → 폭풍 및 요율 제한 금지.
공정성이없는 유일한 글로벌 풀 → 한 명의 임차인이 모두를 "넣습니다".
PII 개정/→ 식별자가없는 로그는 사건 및 준수 위험을 조사 할 수 없습니다.
카나리아/플래그가 없습니다 → 릴리스는 모든 사람을 한 번에 깨뜨립니다.
'재생 후' 및 공급자 유지 보수 일정을 무시합니다.
16) 사전 판매 점검표
- 외부 스키마 매핑 → 내부 언어; 버전 및 이전 버전 호환성.
- 요청/웹 후크의 신원 ('operation _ id', '받은 편지함').
- 타임 아웃, 풀 지터, 회로 차단기, DLQ 및 안전한 재구동 기능이있는 리트레이.
- 요율 제한은 임차인 당 공정성입니다. '재생 후' 에 대한 존중.
- mSL/OAuth/HMAC, 비밀 회전, PII 최소화, 액세스 감사.
- 지역 격리 및 데이터 레지던트; 세입자/지역당 구성 요소.
- p95/p99 메트릭, 클래스 오류, 차단기/429/DLQ 비율; 추적.
- 샌드 박스 및 계약 테스트; 카나리아 롤아웃 및 phicheflags.
- 사건 플레이 북 및 통화 중 교육.
- 문서: SLA, 한계, 스키마, 진화 과정.
결론
공급자 어댑터는 도메인과 외부 세계 사이의 방패 및 변환기입니다. 등기성, 오류 제어 및 관찰 성을 갖춘 강력한 ACL은 통합을 예측할 수있게하고 공급자의 변경 비용을 줄이며 "체인 오류로부터 보호합니다. "독립적이고 관리 가능한 구성 요소로서의 디자인 어댑터와" 외부 세계 "는 내부 아키텍처를 깨뜨리지 않습니다.