提供商适配器

提供商适配器是一个隔离的集成层（反腐败层，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使集成可预测，降低了提供商的更改成本，并防止了"链路故障"。将适配器设计为独立、可管理的组件-您的"外部环境"将停止破坏内部体系结构。