API驗證和合同互操作性

TL;DR

兼容性是紀律，不是運氣。保持明確的版本策略（SemVer），更改數學（「破裂」，沒有），合同測試，電路寄存器和Sunset過程。對於金錢和合規性-嚴格的帶有vN的REST/gRPC，對於UI聚合-帶有「@deprecated」的進化GraphQL。總是：金絲雀流量，向後兼容性≥一個發布周期，遷移海達，場使用遙測。

1）基本概念和目標

Backwards compatible （BC）：較舊的客戶端適合新服務器。
Forwards compatible （FC）：新客戶機適合舊服務器（受限制）。
電線兼容性：「電線」上的格式不會斷裂（對於gRPC/Protobuf尤其重要）。
SemVer: `MAJOR.MINOR.PATCH'-打破合同→晉升MAJOR。

目標：盡量減少破壞性變化，並提供可預測的遷移窗口。

2）更改矩陣： 什麼是可能的，什麼是不可能的

3）不同的API樣式的策略

3.1 REST

URI（「/v1/……」）或域中的版本（「api-v1.」）。頭版僅適用於內部情況。
添加,不要刪除：新字段-ok,舊字段-在圖中標記為「deprecated」並至少保留一個周期。

狀態/錯誤： 不要更改代碼和結構。code/error.message/error.details`.

相似性不變：不要將安全的「POST」與「Idempotency-Key」轉換為「行為上不同」的挑戰。

3.2 gRPC / Protobuf

字段編號是神聖的：不要過度使用刪除的數字，標記為「保留」。
僅添加新的選項/修復字段；「嚴格強制」-通過驗證，不是「要求」。

測試包： 'payments。v1`, `payments.v2`.

服務互操作性：新的RPC →新方法；我們不會改變老人的行為。

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3.3 GraphQL

沒有v2的演變：添加字段/類型；刪除-通過'@deprecated （reason）'並發布窗口。
Persisted Queries：對於公共客戶,使用白色查詢列表-更容易控制兼容性。
Field-level authZ和遙測：在刪除之前,要知道實際使用哪些字段。

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3.4 Webhooks

路徑上的版本（'/webhooks/v1/payments'）和固定的事件信封（'event_id'，'type'，'ts'，'data'）。
簽名/NMAS保持不變；新算法-作為帶有標誌的選項。
擴展-僅通過新的「data.」和「headers」字段-而不刪除舊字段。

4）網關API和版本路由

基於規則的路由：在前綴「/v1」上,在標題「X-Aapi-Version」上,在域上。
影子/金絲雀：在新版本的「陰影」中反映部分生產流量,比較答案。
Rate/Quotas每版本：在遷移過程中保護舊客戶。

• "日落：-版本關閉日期
• 「Deprecation： true」-版本過時
• `Link: ;rel=「deprecation」'-在changelog/遷移海德

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5）計劃註冊和合同

OpenAPI / JSON Schema для REST;Protobuf descriptors для gRPC;SDL registry для GraphQL.

CI檢查：公關時，linters+「斷斷續續檢查」。
消費者驅動合同（CDC）：消費者測試（Pact/對應）-防止不可見斷裂。
Changelog：機器可讀性（例如'CHANGELOG。註冊表中的md'+發行說明）。

6）領域的演變： 實用規則

ID/密鑰：沒有新的字段「_v2」和過渡期,請勿更改格式（UUID↔int）。
時間/貨幣：保持UTC ISO-8601/epoch和amount_minor+貨幣；不要改變規模（一美分/美分）。
Enum：添加值-ok；不要改變舊的意思。對於REST-給出字符串值而不是ints。
分離：基於cursor的更穩定；不要改變光標的語義。

7）剝奪和「日落」-procedura

1.公告（T-90/60）：changelog，發送給合作夥伴，標題「Deprecation/Sunset」。
2.重復期：V1和V2並行運行；V1在響應/邏輯中提供了警告。
3.使用遙測：還有誰叫V1？點觸點。
4.V1冷凍：只有bagfixs/無幻影。
5.關閉（Sunset）： 410 Gone或帶有遷移說明的塊頁。

8）無痛發布： 布局策略

Blue/Green或Weighted routing： 1-5-25-50-100%的流量。
兼容性窗口：最少1-2次要版本,更常見的是外部API 6-12個月。
Feature Flags：在不更改版本的情況下啟用新的邏輯字段/分支。
閱讀/寫入拆分：首先添加對讀取新字段的支持,然後開始編寫。

9）兼容性測試（實踐包）

對舊版本的響應進行金測試。
雙重電路測試：禁止在CI中打破。
在V2（影子）的舞臺上重播生產軌道。
Back/Forward腳本：舊服務器上的新客戶端,反之亦然（如果允許FC）。
Webhook合同測試：驗證簽名，格式，時間。

10）驗證過程的度量和SLO

上次MINOR的客戶百分比（目標≥ Sunset之前的80％）。
版本兼容性/不可用錯誤（目標-0）。
舊版的呼叫比例（降至Sunset）。
客戶端遷移時間（中位數/p95）。
版本之間的Latency/regression delta（不比基本版本差）。

11）工件示例

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

graphql type Query { payout(id: ID!): Payout }

12）轉化相鄰通道

SDK/CLI：SemVer+依賴API版本，README中規定了兼容性。
事件/流（WS/Kafka）：envelope版本。version`;新屬性-可選；兩種版本之間的工作方式相同。
報告/CSV：文件/帽名版本；在右側添加列；不要改變順序/類型。

13）政府和角色

合同所有者（域所有者）、API Steward（規則和林特）、Release Manager（日落/通信）。
用於中斷更改的RFC過程：業務案例,遷移計劃,工件,日期。
單個API目錄：其中可見架構、版本、Sunset日歷、聯系人。

14）反模式

「安靜」斷裂：我們更改狀態/錯誤/字段類型,沒有版本。
重新使用protobuf號碼-破壞後繼和舊客戶端。
GraphQL無需遙測字段使用-刪除「摸索」。
全局v2是大型遊戲而不是點演化。
公共API查詢參數中的版本是一個非突出且易受攻擊的方案。
沒有移民蓋德和例子-合作夥伴拖累，時間表中斷。

15）查看新版本發布列表

• 更新了電路（OpenAPI/Protobuf/SDL），通過了linter和breaking-checks。
• 添加集成和合同測試（CDC）。
• 準備好SDK/示例代碼/遷移海德和 Changelog。
• 包含「Deprecation/Sunset」（舊版本）+「How to migrate」頁面。
• 金絲雀/影子計劃，Alerts和dashbords比較指標。
• 向後兼容性保持一致的時間。
• 回滾計劃（rollback）和風險矩陣是一致的。

總結

穩定API是一個過程，而不是「一勞永逸」。遵守規則：SemVer+僅添加進化+電路寄存器+合同測試+日落程序。共享樣式（REST/gRPC/GraphQL）及其策略,將版本路由到Gateway API,推出金絲雀,測量效果。因此，您將避免出現「驚喜」，加快合作夥伴集成，並保持現金和合規關鍵域的可預測性。