生態系統API

（部分： 生態系統和網絡）

1）目標和原則

• 快速，可預測的集成（時間到集成↓）。
• 可靠性和可擴展性（SLO, QoS, backpressure）。
• 監管安全和合規性（最低限度，審計）。
• 無故障進化（版本，兼容性，ficheflagi）。

原理：contract-first,數據最小化,相容性,實驗默認,兩速發布（核心與實驗）。

2） API分類法

1.REST/HTTP-同步CRUD/命令操作，idempotency-key，pagination/cursors。
2.gRPC/QUIC-低潛伏期、流、二進制協議。
3.事件（Pub/Sub）是域事件（「deposit」，「payout.」，「bridge.」，「risk.」）。
4.Webhooks-帶有簽名和轉發的反向通知。
5.GraphQL（受限制）是實例化店面頂部的聚合讀數。
6.Admin/Meta-目錄、版本、狀態、鍵、配額。

訪問級別：公共（有限的方法/閱讀），合作夥伴（漏洞和配額），內部（私人輪廓）。

3）合同和計劃

OpenAPI/AsyncAPI/Protobuf IDL是唯一的真相來源。
數據合同-兼容性測試，電路linter，禁止沒有MAJOR的「打破」字段。
目錄：資產/網絡，PSP/方法，區域/轄區，SDK版本，功能標誌。

最小REST合同（OpenAPI片段）

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

事件（AsyncAPI）

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

4）轉化與兼容性

SemVer: `MAJOR.MINOR.PATCH`.MINOR/PATCH-向後兼容；MAJOR是並行版本（「/v1」，「/v2」）+適配器。
Deprecation policy： 90天≥窗口、「兩條線路」支持、自動合同通知。
Feature Flags：按區域/合作夥伴啟用/禁用字段/方法。
能力缺失：在握手時聲明支持的配置文件。

5）相等性，順序和光標

Idempotency-Key for Commands （create/cancel）, TTL密鑰≥ 72小時。
Exactly-once語義通過outbox/inbox和偶數匹配器。
遊標分區：「next_cursor」，對插入/刪除的抵抗力。
排序和過濾器-穩定，明確記錄。

6）安全與信任

mTLS（service↔service），塞特釘和鑰匙旋轉。
OAuth2/OIDC（客戶端，JWT和簡短的TTL），PoP/DPoP綁定到通道。
Webhook簽名（NMAS/密鑰版本/時間），重復保護。
RBAC/ABAC和PoLP：漏洞，org_id/tenant_id，設施/操作限制。
DLP/PII最小化：標簽/logs中禁止PII，標記標識符。
Rate-limits和WAF：per org/route/region，abuse保護。

密鑰策略示例（YAML）

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7）配額、QoS和backpressure

QoS類：P0（付款/橋梁/決賽），P1（雜貨），P2（散裝/存檔）。
配額/限額：RPS，concur-requests，bytes/sec，事件/派對。
管理控制：提前拒絕「昂貴」請求,重量查詢後衛。
Backpressure：令牌/學分,隊列與DLQ,轉發與抖動。

配額政策

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8）可觀察性： SLI/SLO，度量，跟蹤

• p95/99 latency по маршрутам, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.
• Contract Compliance％（電路/簽名）。
• Webhook retry/dropped%.

SLO（地標）： P0 p95 ≤ 400毫秒，可用性≥ 99。95%;Webhook delivery p95 ≤ 2 с;Events freshness p95 ≤ 60 с.

度量標準： 潛伏直方圖,錯誤代碼,響應大小,RPS, per-tenant.

Traces：直通式「trace_id」 （edge→gateway→service→DB→event/webhook）。
Logs：結構化的，沒有PII的「request_id」相關性。

9）沒有市中心的發行模式

Blue-Green/Canary帶有SLO門和outlier噴射。
Schema-first演變：僅添加字段,適配器用於舊客戶端。
Zero-downtime DB遷移：在線DDL,雙向轉換器。
更改控制：時間表、審核和兼容性註冊表。

10）目錄和登記冊

API/版本註冊表

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

事件目錄

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

鑰匙/漏洞

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11）測試和合同合規性

合同測試：客戶生成、方案驗證、negative-_cases。
重復事件測試：對重復/重新排序的抵抗力。
Chaos/Lat測試：流失/抖動註射，緩慢排氣。
安全測試：webhook簽名，鍵輪換，重復攻擊。
性能配置文件：SLA尖峰，「熱門」路線，DA/依賴橋。

12）接口示例

Webhooks（簽名和轉發）

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

GraphQL（聚合讀取、僅讀）

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC（事件流）

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13）流程和角色

Owner API-合同/版本/SLO/配額。
安全-密鑰/簽名/審計/DLP。
SRE/Ops-dashbords，alerts，capacity。

Partner Success-onbording, limits, ficheflagi.

合規性-管轄權，制裁，報告。

14）Dashbords

Core API： latency/error/RPS通過路由和觸角。
Webhooks： delivery p95, retries, drops,簽名。

Events: freshness, lag, consumer health, DLQ.

安全：到期密鑰、簽名、拒絕請求。
Governance： Active versions/depreceit,合同兼容性。

15）事件劇本

A. p95潛伏期P0的生長

1.包括優先級P0和P2-throttle；2）擴展網關；

2.將部分讀取切換到緩存；4）熱點路線分析。

B.交付網絡手冊的下降

1.檢查簽名/小時移位，2）增加retrai/taymout，

2.啟用batchi, 4）暫時切換到子彈尾端。

C.開發合同

1.啟用「嚴格模式」（切斷不正確的消息）,

2.通知制作人，3）發布適配器，4）後面貼紙，更新linters。

D.鑰匙/硫磺損害

1.Revoke/rotate, 2）重新編譯webhooks, 3）審核,4）通知合作夥伴。

E.重復/重復爆炸

1.檢查Idempotency-Key/TTL，2）放大dedup，3）限制「嘈雜」源。

16）實施支票

1.描述合同（OpenAPI/AsyncAPI/IDL），包括林特和CI。
2.自定義auth （OAuth2/OIDC, mTLS）、webhook簽名、密鑰旋轉。
3.引入配額/QoS/限額，重質保衛和後壓。
4.提高可觀察性：SLI/SLO，軌道，dashbords，alertes。
5.組織發布：canary/blue-green, schema-first遷移。
6.運行版本/事件/密鑰目錄和刪除過程。
7.進行chaos/perf/安全測試，發布花花公子。
8.定期審核數據最小化和法規遵從性。

17）詞匯表

合同第一-通過代碼的正式合同來設計API。
Idempotency-Key是使操作重復安全的關鍵。
AsyncAPI是事件接口的規範。
QoS是服務質量/優先級類別。
DLQ是問題消息的「死隊列」。
錯誤預算燒傷-相對於SLO的「燃燒」錯誤預算率。

底線：生態系統API不是一組殘局，而是可管理的合同，安全，配額和可觀察性系統。遵循此框架，生態系統可以快速集成，可預測的SLO和安全的演變，而無需從網絡層和身份驗證到事件流和報告。