合同API測試

1）為什麼要進行合同測試

該合同記錄了客戶的期望和提供商的承諾：路線/方法，標題，身體模式，狀態，錯誤語義和約束。目的是在集成之前捕獲不兼容的更改，並安全發布版本，而無需重E2E。

2）方法

消費驅動合同（CDC）：客戶形成期望（Pact和類似物）；提供商定期對其進行驗證。
規格：作為單一真理來源的合同（OpenAPI/Protobuf/GraphQL SDL）；測試驗證實現與規範。
事件：消息模式（Avro/JSON Schema/Protobuf）+經紀人/註冊表中的互操作性規則。

3） HTTP/REST： 規格流

1.合同：OpenAPI 3。x（模式、示例、代碼）。
2.Lint和統計分析：樣式，必填字段，統一代碼。
3.實現驗證：測試生成器與OpenAPI （schemathesis/Dredd方法）+手動底片。
4.Snapshots：捕捉示例響應,ETag語義,同位性標題。

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4）CDC（Pact方法）

1.消費者編寫測試，形成pact文件（期望）。

2.發布到經紀人（工件）。

3.CI的Provider提升服務（或合同櫃臺），驗證pact 's。

4.經紀人計算can-i-deploy兼容性矩陣。

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5） gRPC/Protobuf合同

合同是「.proto」，其中包含數據包/服務的版本。
兼容性：不要重新使用標簽,只添加新的選項,不刪除使用的字段；預留號碼。
測試：生成服務器/客戶機穩定,租用自動生成的案例+底片（未知領域,尺寸限制）。

6）事件合同（Kafka/NATS/……）

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.

兼容性策略：「BACKWARD」（通常足夠）或「FULL」。
Prodewser測試：驗證針對方案的信息；消費者測試：接受新舊版本。
不變性：等速鍵、順序/可重復性、重復數據消除語義。

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7）兼容性和版本

Backward-copatible（建議的最低限度）：添加可選字段,不要打破現有字段。
前瞻性：消費者忽略未知領域。
滿：兩者。

轉化： 「path （/v1）」、「Accept： application/vnd」。brand.v2+json`, `proto package v2`.

Deprecation策略：輸出窗口（例如90天）,警告標題/事件。

8）負面和錯誤也是合同

標準化代碼：400/401/403/404/409/422/429/5xx，必填字段「code」，「message」，「trace_id」。
尺寸/限額是合同的一部分(413/414/431）。
等效性：重復行為（409 vs 201 same id）。
標題：429/503的「Retry-After」，「Idempotency-Key」，「Content-Language」等。

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9）數據管理合同

示例/試衣間響應（examples）是活的，在CI中得到驗證。
CDC的fixturs是最小的，確定性的。
數據生成-基於數字/日期的屬性；但不要破壞狙擊手的穩定性。

10）CI/CD中的管道（參考）

1.Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).

2.出版物：作為文物的合同（經紀人/登記處）。
3.驗證：提供商運行CDC數據包/規範測試。
4.can-i-deploy門：沒有綠色矩陣,不允許發布。
5.Diff：驗證更改是否兼容（semantic diff）。
6.報告：JUnit/HTML，違規行為/定義列表。

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11）工具（按任務類）

Lint/驗證器：openapi-linters，protobuf-lint，avro-tools。
CDC：pact家族/經紀人，Spring Cloud Contract，Hoverfly（HTTP記錄/反射）。
規格先行者：schemathesis/Dredd樣方法，Postman test+JSON Schema。
Diff： semantic-diff OpenAPI/Proto/Avro（顯示斷開更改）。
容器：Testcontainers提升供應商/合同櫃臺。

12）反模式

「Spetz-dock」與代碼分開→同步。將合同存儲在服務附近。
第三方服務的洗滌代替合同→升級時的脆弱性。
隨機響應/生成而不涉及長笛→模式。
更改字段的類型/強制性而不修改版本。
無通知/撤消的靜音擴展。
沒有負面合同和錯誤代碼。

13） iGaming/財務細節

將貨幣字段正式化：「amount」-具有比例的貶值,貨幣是ISO-4217和不變量。
支付/webhook合同：HMAC/mTLS，反重播（「X-Timestamp」窗口），等效性，「Retry-After」。
區域/特南特：強制性標題「X-Tenant/X-Region」，消息本地化。
事件：不變日誌（審核）,重復數據消除密鑰,交付保證（at least once+idemented hendler）。

14）測試的「骨架」示例

14.1 Schemathesis風格（偽造的）

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14.2 Postman作為規範運行者

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14.3 Provider驗證CDC（偽）

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15）準備就緒支票清單

• 存儲庫中的合同，CI驗證和發布文物。
• CDC用於關鍵集成；broker/matrix 「can-i-deploy」正在運行。
• 兼容性策略（HTTP/gRPC/Events）已得到記錄；自動semantic-diff。
• 負面合同：錯誤，尺寸限制，相等性，「Retry-After」。
• 測試數據是確定性的；支持示例快照。

［……］核查和執行：時間、通知、標題。

• 對於事件-計劃註冊和兼容模式；生產者/消費者測試這兩個版本。
• 工件：JUnit/HTML，報告diff/verify，兼容性矩陣。
• 事件過程：快速回滾合同/遠距標誌,通知集成商。

16) TL;DR

將期望值捕獲到合同中並自動運行：用於客戶期望的CDC、用於實現的規範測試、用於事件的模式註冊表。保持嚴格的兼容性政策和負面合同（錯誤、限制、等效性）。如果沒有綠色can-i-deploy矩陣和半空格，則無需進行突破性更改即可發布。