直接兼容性

什麼是直接兼容性

直接兼容性（前向兼容性）是系統能夠正確處理比最初設計的新客戶端或數據的能力。簡而言之：當新客戶端到達時，舊服務器不會崩潰；老消費者在遇到新信息時不會倒下。

從向後兼容（當新系統支持舊客戶時），前進的方向有所不同：我們設計協議和客戶以「生存」未來的擴展，而無需對整個生態系統進行全面升級。

基本原則

1.Tolerant reader & tolerant writer

讀者忽略未知字段/標題，並允許具有正確後退的新的enum值。
Writer不會發送服務器未明確聲明為受支持的任何內容（capabilities）。

2.Capability negotiation

在handshake階段顯式交換功能（fichi/版本/媒體類型）。客戶端會根據服務器響應調整其行為。

3.默認降解

新功能被認為是可選的：如果服務器/用戶不支持它們，則腳本仍將以有用的最小值（MGC）結尾。

4.穩定核心（MGC）

最低保修合同不變；創新作為擴展而存在。

5.錯誤合同作為協議的一部分

可預測的代碼/原因（「不支持」，「媒體類型未知」）允許客戶端自動回滾到受支持的模式。

6.沒有驚喜的版本

主要生產線是分開的；次要擴展不需要服務器/用戶更新。

這在哪裏尤為重要

具有長壽命集成的公共API（合作夥伴，移動應用程序中的SDK）。
具有多個獨立用戶的活動平臺。
移動客戶端更新速度比後端慢。
Edge/IoT，其中一些設備隊很少通過。

樣式的實現模式

REST/HTTP

Negotiation:

帶參數的「接受」/介質（'application/vnd。example.order+json;v=1;profile=risk`).

「Prefer： include=……」用於可選單元。
標題"X-Capabilities： risk_score,item_details_v2'。

客戶行為：

僅當服務器確認了能力時（通過OPTIONS/DESC/LID-ENPOINT），才以基本格式發送請求，擴展。
「415/406/501」會自動回滾到支持的格式/方法。
服務器響應：未知參數-忽略；多余的字段-允許；錯誤格式（「type/code/detail/trace_id」）是穩定的。

gRPC / Protobuf

穩定服務：新方法/領域-加法；舊服務器靜靜地忽略未知的查詢字段。
功能發現：「GetCapabilities（）」方法返回幻影/極限列表。除非服務器已聲明,否則客戶端不會調用「v2方法」。
流媒體：記錄最少信息集的順序；新的「框架」標記舊客戶端忽略的擴展/類型。

GraphQL

前向友好：服務器上會出現新的字段/類型-舊客戶端根本不要求它們。
禁止猜測：客戶必須保留電路（內窺鏡/密碼根），並且不得發送未知的指令/變量。
降級：如果服務器不了解自定義指令/功能-客戶端將構建沒有它的請求。

Event-driven (Kafka/NATS/Pulsar, Avro/JSON/Proto)

註冊表中方案的FORWARD兼容性：舊用戶可以讀取新方案記錄的消息。
帶有默認值的加法字段：新生產商不會打破舊用戶。
Core vs Enriched：內核保持不變，新信息發布在「.enriched」或作為可選字段。

設計實踐

1.最低要求合同（MGC）

該操作必須具有「狹窄的頸部」，所有服務器將支持多年。

2.Ficha-Flag在合同級別

將fici描述為命名功能：「risk_score」，「pricing_v2」，「strong_idempotency」。客戶端明確打開它們。

3.「不支持」的顯式錯誤代碼"

HTTP: `501 Not Implemented`, `415 Unsupported Media Type`, детальные `problem+json`.

gRPC: `UNIMPLEMENTED`/`FAILED_PRECONDITION`.

事件：帶有「reason=unsupported_feature」的DLQ中的路由。

4.不依賴順序/完整列表

客戶端必須為新的enum值，缺少新字段以及「附加」屬性做好準備。

5.穩定的ID和格式

不要改變行內的ID/分期付款密鑰格式-這打破了讀者一側的前進。

6.「機器可讀」文檔"

主機描述符：OpenAPI/AsyncAPI/Proto descriptors/GraphQL SDL。客戶可以驗證相片支持。

前向兼容性測試

FORWARD/FULL模式下的Schema-diff：新方案驗證舊消費者/服務器。
客戶端合同測試：新客戶機對舊服務器執行開機/關機。
Golden requests：在「舊」服務器上運行一組「新」請求；預計會退化而不會出現重大錯誤。
Chaos/latency：檢查定時器/轉發器-新客戶端必須正確地體驗舊服務器最壞的SLA。
金絲雀：一些新客戶使用以前的服務器版本-收集錯誤/降級遙測。

可觀察性和操作指標

不支持快照及其自動回滾的查詢/消息的百分比。
按客戶端版本分配（User-Agent/元數據/claims）。
錯誤「UNIMPLEMENTED/501/415」以及帶有「unsupported_feature」的DLQ中的路由。
降解時間：MGC對「擴展」響應的p95/p99。

方案註冊表中的兼容模式

FORWARD：新條目與舊讀者兼容（需要默認、可選）。
FULL: и FORWARD, и BACKWARD;方便公共合同。
建議：對於事件-制片人的BACKWARD和消費者的FORWARD（通過tolerant reader），對於外部API-FULL。

示例

REST （capabilities+降解）

1.客戶端執行「GET/meta/capabilities」 →「{」risk_score"：false，「price_v2"：true}」。
2.在「POST/orders」上發送基字段；「risk_score」不提示,因為服務器無法訪問它。
3.如果不小心發送了「Prefer： include=risk_score」，則服務器將在沒有「risk_score」（或「Preference-Applied： none」）字段的情況下響應200-客戶端不會掉落。

gRPC (discovery)

「GetCapabilities（）」返回方法/幻想列表。如果不調用「CaptureV2」，則客戶端不會調用「CaptureV2」-而是使用「Capture」並將輸入本地轉換為受支持的視圖。

事件（註冊表中的FORWARD）

制作人添加了「risk_score」字段（帶有默認功能的不可讀性）。老主人忽略了他。它的邏輯只使用穩定的內核字段。

反模式

硬客戶端：通過惠特利斯特字段過濾響應，落在陌生的屬性上。
隱式fichi：客戶端開始發送新參數,而無需檢查大寫字母。
更改線路內的ID/密鑰格式 →舊服務器/用戶停止理解新的請求/消息。
關於完整的enum列表（switch undefault）的加密假設。
編譯為流控制：將錯誤字符串替換為合同代碼。

實施支票

由MGC定義；新功能被標記為可選功能。
描述並實現了能力要求（端口/元數據/手寫）。
客戶忽略不熟悉的字段並正確處理新的enum （fallback）。
錯誤合同可預見「不支持」（HTTP/gRPC/Event）。
已將電路註冊表配置為FORWARD/FULL以匹配工件。
自動測試：schema-diff （FORWARD）,客戶端針對舊服務器的合同測試,金絲雀。
度量標準：客戶版本,幻燈片故障,降解比例,p95 MGC。
Documents/SDK發布幻燈片列表和退化示例。

FAQ

在實踐中，前進與後退有什麼不同？
Backward：新服務器不會破壞舊客戶端。前進：舊服務器不會中斷新客戶端（或舊用戶端-來自新消息）。理想情況下，你能完全實現。

你是否總是需要輸入大寫字母?

如果您期望在沒有同步發布的情況下進行積極的演變-是的。這比保持數十條主要生產線便宜。

如何與安全？
新的fici必須需要單獨的scopes/claims。如果服務器不支持它們，則客戶端不應降低安全性，而應放棄fichi。

可以根據服務器版本「猜測」支持嗎?

不希望。最好明確查詢（capabilities）或查看介質/方案。

底線

直接互操作性是談判能力和安全退化的紀律。穩定的內核、能力限制、可加性擴展和可預測的錯誤使新客戶和數據能夠與舊服務器和消費者相處,而無需大量發布和夜間遷移。