API驗證策略
為什麼需要轉學
API的變化速度快於客戶端。轉化允許在沒有積分故障的情況下釋放幻影和編輯錯誤，設置更改的儀式，並使進化可預測。關鍵：默認的加法更改,主要只用於切片,自動兼容性檢查和深思熟慮的日落策略。
基本原則
1.增量第一：新的可選字段/方法/事件-ok；刪除和改變意義是專業。
2.MGC（最低保修合同）穩定；富集-通過capabilities/'?include='。
3.Tolerant reader：客戶會忽略未知字段,並正確地體驗enum擴展。
4.Semantic Versioning: `MAJOR.MINOR.PATCH'用於工件，SDK和事件。
5.Automate： schema-diff、linters和CDC測試阻止斷裂變化。
在何處存儲版本（尋址機制）
REST/HTTP
URI版本：'/v1/orders' →簡單地路由，在網關中方便。減-「掩蓋」表示的演變。
介質/標題：'接受：application/vnd。example.orders.v1+json'-精確的格式控制；更難借用。
Query版本：'?api-version=1'-對A/B很方便,但很容易在腰包/logs中丟失。
建議：主要線路的URI+feature/capability flags和次要擴展的content-Nacacisation。
gRPC / Protobuf
軟件包/服務："package payments。v1;服務PaymentsV1；'是顯式行。
標簽編號不變；已刪除的標簽不能重新使用。
新領域是「選擇性」；突破→新的「.v2」。
GraphQL
URL中沒有顯式專業的方案。通過@deprecated和遷移窗口演變；「真正」的專業是新的終端電路。
控制complexity/depth是合同的一部分。
Event-driven (Kafka/NATS/Pulsar)
事件名稱：'payment。authorized.v1'是類型中的版本。
具有兼容性模式（BACKWARD/FORWARD/FULL）的電路註冊表（Avro/JSON 計劃/Protobuf）。
Major →過渡時期的雙演員「v1」和「v2」。
版本模型和更改策略
Semantic Versioning
MAJOR-破解更改：刪除/重命名字段,更改分期密鑰,不同的狀態含義,收緊驗證。
MINOR-可加性：新的可選字段/端點/事件，tolerant-reader中的新烯素值。
PATCH-不更改合同和語義的修補程序。
Deprecation & Sunset
在HTTP中，標題為「Sunset」，「Deprecation」；在事件中-單獨的'.deprecation.notice`.
標記過時（「Deprecated：true」，「@deprecated」），發布日落日期，替代品和遷移海德。
運行使用遙測以做出刪除決定。
Version Style策略
REST
在/v1 ，/v2上的主要線。
MINOR：方案擴展，'？fields='，'？include='；安全的enum擴展。
ETag/If-Match和等效開機自檢以實現無切片一致性。
錯誤是穩定的格式（「類型」，「代碼」，「trace_id」）。
gRPC
介紹新的服務/方法： 'PaymentsV2.Capture`.
錯誤狀態和最後期限語義是合同的一部分；更改→新方法/服務。
流媒體：商定消息順序，不要換成次要。
GraphQL
自由添加字段和類型；刪除-通過'@deprecated'+遷移窗口；大型重新設計→新方案（'/graphql-v2'）。
內窺鏡和描述是客戶遷移的必經之路。
Events
Core vs enriched：核心穩定，富集生活在附近，分開旋轉。
分期密鑰在主要線路內不變。
主要遷移是「dual-emit」+投影/消費者的遷移。
Negotation和能力標誌
Capabilities：客戶端發送"X-Capabilities：risk_score,price_v2'；服務器以高級視圖響應。
部分響應的Prefer（HTTP）和「hints」。
在套接字/流中-帶有支持擴展列表的手寫消息。
大版本發布無痛苦
1.RFC/ADR：為什麼需要一個主要的風險矩陣。
2.雙跑：並行啟動「v1」和「v2」（雙重事件發布，兩條網關路線，交通鏡像）。
3.遷移適配器：用於重型客戶的代理/轉換器「v1↔v2」。
4.金絲雀：按客戶組/拓撲/標簽在gateway。
5.日落計劃：日期，通訊，展位，測試數據，使用監控。
平臺和基礎設施的作用
Gateway/Service Mesh API： 按版本、標題、路徑進行路由；rate-limit и auth per-version.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Schema Registry＆Catalog：具有誹謗歷史的孢子/方案的真相來源。
Observability： 該版本必須包含在logi/traces/mindics.
版本測試
公關中的Schema-diff：阻斷。
Consumer-Driven Contracts：對提供商進行實際消費者合同審查。
金色樣本：版本的參考響應。
E2E-Canary：比較版本p95/p99，錯誤和時間間隔。
Replay for event：投影在v2上重新定位,沒有差異。
數據和數據庫遷移
對於REST/gRPC：DB遷移是通過expand-and-ontract進行協調的（添加專欄→開始寫作→切換閱讀→舊版）。
對於事件：雙配音和用戶遷移；有時-對新投影重新播放日誌。
不要做「大爆炸」--用回滾擊中步驟。
與安全的關系
逐個版本：v1/v2的單個OIDC-scopes/角色。
秘密/令牌是合同的一部分；他們的變化=主要。
PII/PCI-不必要地擴展付費負載；新字段-特權最小。
反模式
Swagger-wash：更新了規範,服務器沒有（反之亦然）。
重新使用protobuf標簽是一種安靜的數據破壞。
沒有專業的enum意義改變。
全球「/v2」「為了化妝品」：沒有斷裂事實的版本。
忘了日落/使用指標：無法安全地刪除舊版本。
一個用於不同專業的一般拓撲：順序和鍵的混合。
發行前的支票清單
- 更改是加法的，或者準備了單獨的大線。
- Linters和schema-diff綠色（破裂不會脫落）。
- 更新了SDK/示例/文檔以及兼容性腳註。
- 在客戶端中啟用tolerant reader；enum-fallback測試。
- 對於專業-雙跑計劃，適配器，金絲雀，日落日期和通訊。
- Metrics/logs/traces包含一個版本並對其進行細分。
- 有一個攤位和一個金色套件來比較v1↔v2。
- 對於事件-BACKWARD/FULL模式下的電路註冊表,分期密鑰保持不變。
模式示例
REST (URI + negotiation)
路線： '/api/v2/orders/{id}'
Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`
Deprecation: `Sunset: 2026-06-30`, `Link: ;rel="alternate"`
Protobuf/gRPC
proto package payments.v2;
service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}Events
`payment.captured.v2'（內核）和'payment。enriched.v2'（詳細信息）。
制片人的過渡期是「v1」和「v2」。
FAQ
什麼時候確切需要'/v2'？
當不變式/語義發生變化時，刪除字段/方法，更改標識符格式，分期密鑰，SLA/計時器，以使客戶端崩潰。
可以在REST中沒有明確版本生活嗎?
僅適用於小型系統。對於外部積分-更明顯的專業線。
保留過時版本的時間是多少?
取決於生態系統。對於外部合作夥伴，通常需要6-12個月的早期通知和金絲雀。
事件轉換與API有何不同?
事件是唯一的；新語義=新類型「.v2」和dual-emit。分期付款的關鍵是合同的一部分。
結果
轉化策略是一個過程和工具：默認的加法演變，清晰的大線，能力失調，雙奔跑和日落。加上自動兼容性檢查、使用遙測和文檔紀律-而且您的API將快速發展，沒有「夜間遷移」和客戶意外下降。