API兼容性和更新

1）互操作性基本原則

Additive-first：添加新字段而不破壞舊字段（新可選字段/端點,新的enum值）。
穩定的合同：「規範中承諾的東西既有效又有效」；行為記錄在案。
Backward> Forward：向後兼容性優先級；通過tolerant閱讀器允許前進。
文檔是主要的：唯一的真相來源是註冊表中的架構版本（OpenAPI/AsyncAPI/Proto）。
顯而易見的演變：破裂-僅通過新的主要版本和遷移指南。

2）變更分類法

2.1兼容（MINOR/PATCH）

添加可選的字段/頭部、新的尾部、帶有默認值的查詢參數。
增加限制（「page_size」，TTL），在不更改代碼/語義的情況下澄清錯誤。
如果客戶端忽略了「陌生人」（tolerant-reader）,則添加enum值。

2.2模棱兩可（Behavioral）

更改違約，排序順序，精細的時間表，配額-可以「打破」業務邏輯。需要RFC+公告和金絲雀。

2.3折斷（MAJOR）

重命名/刪除字段，更改類型/格式，替換錯誤代碼，反向合同/身份驗證方案不兼容。

3）考試政策

策略：「path versioning」（「/v1」，「/v2」）。
小調/補丁：「添加，不要打破」。
過時的標題（dop.）：「X-API-Version-Date」，用於溫和的漸進式更改。
媒體類型（opz。）: `Accept: application/vnd.acme.v1+json'用於細顆粒。

4）去除和日落

4.1通訊頭條

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4.2輸出順序

1.在門戶/通訊/SDK發布註釋中宣布。
2.警告窗口≥ 90-180天。
3.Dashboard adoption中的狀態。
4.在日落之後-410 Gone或「read-only」模式，如果同意的話。

5）遷移和共享版本

過渡時期的雙寫作/雙讀取和報告對賬。
適配器（臨時）：舊付費的網關轉換→新方案；適配器的壽命受到限制。
SDK幫助：支持兩個版本的版本,帶有解密警告（每個過程1次）。
Fich-flags： 在鍵/tenant列表中包含新的語義。

6）背面和前方兼容性

6.1 Backward（舊客戶端↔新服務器）

不要更改類型/強制格式。
新字段-僅可選。
錯誤-以前的「error_code」、新代碼添加、不替換。

6.2 Forward（新客戶端↔舊服務器）

通過「OPTIONS」/「/versions」檢查能力（機會）。
格雷斯行為：客戶必須容忍缺席的犯規。

7）合同和自動檢查

註冊：保留方案的版本；公關部門→報告「破解/不破解」。
Linter：名稱/類型,等效性,分期,穩定代碼。
CDC（消費者驅動合同）：供應商的CI（Pact和類似物）中的集成商測試。
蓋特：公關在沒有「專業大滿貫」/RFC的情況下被鎖定。

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8）金絲雀發行和回程

金絲雀：10% → 25% → 50% → 100%的流量；SLO惡化時的自動回滾（5xx/latency/429）。
Beta密鑰：通過allowlist訪問新版本。
釋放凍結：在燃燒錯誤預算時。
接受分析：新版本的流量/客戶比例,遷移時間。

9）詳細兼容性： 錯誤，分離，相容性

9.1個錯誤

不要更改現有腳本中的HTTP狀態。
'error_code'-穩定；僅添加新代碼。
「application/problem+json」是單一格式。

9.2分離

如果支持舊的「offset/limit」，則切換到cursor/keyset=MINOR。
記錄「（updated_at,id）」排序和光標穩定性。

9.3 Idempotency

對於寫作-沖突中的"Idempotency-Key"+"409 IDEMP_REPLAY'。
遷移不應改變冪等語義。

10）網關轉型（適當時）

Map v1→v2字段，規範錯誤，轉換日期/貨幣格式。
Guardrails：轉換透明且可邏輯；不要隱藏斷裂，而是用作限時橋梁。

11）通訊和門戶

Changelog с датами (`added/changed/deprecated/removed/fixed`).

版本卡：狀態（beta/GA/deprecated），日落日期，指向海德的鏈接。

通知的Webhooks： 'deprecation。notice`, `version.released`, `plan.change`.

SDK發布註釋+門戶網站上的橫幅。

12）成功指標

Adoption rate v2（按請求/客戶端）。
Backward-compat incidents（「折紙」）。
發行前/發行後的Error mix（4xx/5xx/429份額）。
時間到中位數。
支持負載（tikets/ned）。
Cost-to-Serve（每個呼叫的基礎架構成本）。

13）模板和示例

13.1版本和刪除標題

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13.2版本策略（YAML片段）

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13.3 OpenAPI：兼容字段添加

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14）發行支票清單（MINOR/MAJOR）

MINOR

• DIFF：非突破，linter綠色
• 文檔/SDK更新（示例/編解碼器）
• 金絲雀+在SLO上自動回滾
• Comm Plan，門戶網站頁面
• Dashbords adoption和錯誤

MAJOR

• RFC/ADR、日落日期和窗口≥90 -180天
• v1↔v2橋（gateway）和遷移指南
• 雙重寫作/閱讀和對賬
• 具有兩個API+警告的SDK
• 具有關鍵集成商的飛行員

15）實施計劃（3次叠代）

1.基礎（2周）：

CI中的Registry電路，lint和auto-diff；互操作性政策；標題「Deprecation/Sunset」。

2.托管版本（3-4周）：

金絲雀，幻燈片，SLO-Alerta；版本門戶；支持2個分支的SDK版本。

3.自動化和規模（連續）：

CI中的消費者疾病預防控制中心測試，日落趨勢預測，自動符號化和提醒。

16）迷你常見問題

可以在沒有專業的情況下更改字段類型嗎?

沒有。甚至「stroka→chislo」都是斷裂。輸入新字段,舊字段為deprecate。

Enum： 可以添加值嗎?

是的，如果客戶是tolerant讀者。否則-首先是警報和beta。

多少保留舊版本?

到目前為止，adoption是新的≥95％，並且經過了消除窗口。在政策中記錄最後期限。

底線

API兼容性是一門學科：additive方法，正式方案和difs，金絲雀版本，清晰的解密和管理的遷移。穩固變更策略，自動化驗證和通信，測量適應-您的更新將停止破壞客戶，並且演變速度將增長而不會失去可靠性。