提供商適配器

提供商適配器是一個隔離的集成層（反腐敗層，ACL），可將提供商的外部合同（遊戲提供商，支付網關，KYC/AML，風險評分，符號化等）轉換為內部域語言並返回。它保護域免受不穩定API，網絡異常，電路演變和安全策略的影響。

1.Decupling：沒有「原始」外部付費進入內核。

2.可靠性：管理故障（timeouts、retries、DLQ、circuit breaker）。

3.一致性：等效性，按鍵順序，事務性加速。

4.操作：度量標準，示蹤劑，限制，陰極絕緣和居住。

1）適配器責任區

合同：外部計劃/結束說明；mapping →內部命令/事件。
運輸：REST/gRPC/WebSocket/SQS/Kafka/SFTP；連接池,backpressure。
安全：mTLS，OAuth2，HMAC，按電話/區域的密鑰/證書，秘密輪換。
可靠性：Taymauts,回程夾具,電路斷路器,重復數據消除。
相似性：「Idempotency-Key」/「request_id」，答案/狀態的存儲。
可觀察性：SLO度量，結構邏輯，跟蹤。
轉化：支持多個版本的電路/殘局。
運營：ficheflagi，金絲雀發行，沙箱，認證。

2）應用地點（上下文示例）

遊戲/RGS：開始/結束回合，投註/獲勝，會話令牌，提供商狀態。
Payments/PSP：存款/收取，webhooks狀態，充電器，3-D安全。
KYC/AML：驗證，制裁/RER驗證，交易監控。
Risk/Fraud：得分，觸發器，鎖定建議。
Comms： e-mail/SMS/push,郵寄限制,模板。

每種類型都有自己的活動狀態機和SLA-適配器必須使其正常化。

3）合同和mapping（內部↔外部）

• 在適配器內鍵入Published Language,從不向外拖動ISP字段。
• 所有消息均帶有「tenant_id」，「region」，「provider_id」，「operation_id」和「version_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）相似性和順序

請求de-dup：'Idempotency-Key：<查詢中的operation_id>'；TTL的「（op_id →最終狀態/回應）」。
Webhook de-dup：表格'inbox （provider, event_id）'作為PK。
按鍵順序：通過「aggregate_id」（例如「round_id」或「psp_tx_id」）對調用和處理進行序列化。
Outbox/Inboxing：在傳送帶的兩邊進行事務性加速。

5）可靠性： taymouts, retrais, circuit breaker

Taymauts：短客戶端側面（p95方向）,分別用於connect/read。
Retrai：僅在retryable（5xx/timeout/429），指數backoff+full jitter，嘗試限制和總截止日期。
Circuit Breaker：當錯誤/潛伏期增加時打開；graceful degradation（例如，禁用次要RGS fici，放置「等待結果」）。
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: 10

6）價格限制，配額，競爭力

遵守提供商的限制（RPS, burst, concurency）。
實施per tenant WFQ/DRR （fairness）,以便「嘈雜」的客戶不會吃掉預算。
尊重"Retry-After"/"X-RateLimit-頭條新聞。
Prodewser上的內部隊列+backpressure。

7）安全性和合規性

運輸：mTLS，TLS 1。2+，最新的cipher套房，盡可能獲得證書。
身份驗證：OAuth2 client-credentials/MTLS，HMAC（簽名的身體哈希+timestamp），API密鑰。
PII最小化：只有必要的字段；log和DLQ中的偽裝/編輯。
保密：KMS/HashiCorp Vault，自動旋轉，per tenant/region隔離。
合規性：用於PSP的PCI DSS，代幣存儲而不是PAN，GDPR/本地數據法。

8）多特南特和多區域

每個特南特/地區的密鑰/尾端配置。
數據駐留：呼叫來自「家庭」地區；跨區域-僅聚合。
隔離：本機連接池和per tenant限制。

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/timeout/429）。
• p50/p95/p99方法延遲。
• 觸發率極限，breaker打開/關閉，DLQ-rate，redrive-success。
• 結構邏輯是：「tenant_id」，「provider_id」，「operation_id」，「endpoint」，「status」，「attempt」，「backoff_ms」。
• Tracing：單個「trace_id」，演唱「serialize → send → receive → map → publish」，標簽「schema_version」，「region」。

10）Version和ficheflagi

平行維護v1/v2外部合同；遷徙是金絲雀/tenant。
提供商的任何新幻燈片都在旗幟後面；不發布切換。
進化條約：增益第一，嚴格驗證方案（JSON Schema/Proto）。

11）花花公子（runbooks）

1.429沖擊/極限：打開全局trottling，尊重「Retry-After」，在tenant之間重新分配窗口。
2.Taymauts的增長：減少混亂，小心翼翼地增加taymauts，打開斷路器，包括菲奇退化。
3.Schema mismatch：冷凍紅土,啟用兼容的mapper,執行backfill/重新處理。
4.Flap webhuks：轉到拉動/重新啟動模式,應用inbox dedup。
5.提供商發生的事件：切換到沙箱/備份DC（如果有），激活「延遲」操作。

12）測試

合同測試：生產者/消費者對固定供應商的偽造。
混沌測試：延遲，下沈，訂單外出，復制，部分響應，連接中斷。
表演：爆料壓力；p95/p99測量，breaker行為。
相同性：重復相同的「operation_id」不會產生其他效果。
E2E在沙箱中：快樂路徑/chargeback/爭議/取消/修復腳本。

13）實現選項（部署模式）

獨立服務適配器：+隔離,獨立發行版；−。
Sidecar/插件：+呼叫本地性；−更難控制版本。
庫：+只是嵌入；−高配對和雜種版本。

建議：具有清晰API及其發布周期的服務適配器。

14） Adapter 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"
}

• Webhook帶有「provider_event_id」 → 「inbox」（PK在「（provider,event_id）」上）→ mapping → 「PaymentAuthorized」域事件。

15）典型錯誤

將「原始」外部電路拖入域→緊密的連通性和昂貴的遷移。
缺乏同位素和inbox/outbox →效果和幻影狀態。
沒有jitter/限值的 retrai →暴風雨和禁令的限值。
唯一沒有公平的全球池→一個特南特「放下」所有人。
沒有PII 修訂版/ID的日誌→無法調查事件和合規風險。
沒有金絲雀/旗幟→釋放會立即打破所有人。
忽略提供商的「Retry-After」和服務時間表。

16）售前支票清單

• 模仿外部方案→內部語言；版本和向後兼容性。
• 查詢/webhook的可取性（「operation_id」，「inbox」）。
• Taymauts，帶有全套夾具的背包，巡回賽斷路器，DLQ和安全重做。

[] Rate limits и fairness per tenant;尊重「Retry-After」。

• mTLS/OAuth/HMAC，秘密輪換，PII最小化，訪問審核。
• 區域隔離和數據駐留；configi per tenant/region。
• p95/p99度量標準，類別錯誤，breaker/429/DLQ-rate；跟蹤。
• 沙盒和合同測試；金絲雀rollout和ficheflagi。
• 事件花花公子和電話培訓。
• 文檔：SLA，限制，模式，進化過程。

結論

提供商適配器是您域與外部世界之間的盾牌和翻譯器。具有等效性，錯誤控制和可觀察性的強大ACL使集成可預測，降低了提供商的更改成本，並防止了「鏈路故障」。將適配器設計為獨立、可管理的組件-您的「外部環境」將停止破壞內部體系結構。