語義轉換

語義版本（SemVer）是關於版本號如何反映更改性質的約定。格式： MAJOR。MINOR.PATCH[-PRERELEASE][+BUILD].

• MAJOR-不兼容的更改（斷開）。
• MINOR-反向可移動的fici/擴展。
• PATCH-可逆的錯誤/安全修復。

目標：API、事件、數據模式、SDK和configs的可預測演變,沒有突然的消費者故障。

1）編號公約

X.Y.Z[-alpha.1    -rc.1][+build.sha]

預發布（「-alpha」，「-beta」，「-rc」）是不穩定的組件；不保證兼容性。
Build metadata（「+sha」）-不影響比較順序,有利於跟蹤。
最多1。0.0任何更改都可以視為突破（但最好從一開始就遵守規則）。

2）如何計算突破/小調/補丁

PATCH (Z):

錯誤和安全假貨沒有合同變更。
不影響合同的醫生。
優化而不更改響應/事件/模式。

MINOR (Y):

添加新的可選字段/方法/末端。
如果消費者容忍不熟悉的含義，則擴展含義。
新的DB索引，帶有默認值的nullable列，新事件以及舊事件。

MAJOR (X):

刪除/重命名字段、更改類型、強制性。
更改語義/狀態/錯誤代碼。
更改序列化格式、密鑰模式、傳輸協議。
拓撲的壓縮/合並，事件意義的轉移，分期方案的更改。
需要「雙相」切換而無需向後兼容的DB遷移。

3）通過人工制品進行轉化

3.1 REST

選項：「URI/v1/……」，標題（「接受：application/vnd」。acme.game+json;version=1'），參數。
建議：URI中用於公共API的版本；對於內部-通過標題c negotation。
MINOR：添加可選字段、新過濾器/資源；不要改變現有的答案。
PATCH：虛構,說明完善,穩定排序。

3.2 gRPC

更改簽名/類型→ MAJOR（新包/服務： 'acme。wallet.v2`).

新字段-帶有選項標簽；服務器必須忽略未知數。
我們不會刪除字段：「depricate+保留編號」,僅在以下MAJOR中刪除。

3.3 GraphQL

MINOR：新字段/類型/查詢；刪除-通過'@deprecated'+遷移窗口,完全刪除-MAJOR。
更改nullable→non-nullable-MAJOR。

3.4事件和拓撲（Kafka/SQS）

Schema Registry中的方案：additive的演變（添加帶有默認字段）。

新的不兼容版本→新的主題/主題版本（'bet。settled.v2`).

在MAJOR中，分期密鑰不變。

3.5 DB計劃

1.添加列（nullable/c默認）→

2.填滿後退→

3.翻譯閱讀→

4.刪除舊的（僅限於MAJOR）。

類型/RK/唯一性更改為 MAJOR，在ficheflag和雙重記錄下。

3.6 SDK/CLI

公共方法/簽名是相同的規則。
對於自動生成（OpenAPI/Proto），是批處理名稱和工件的版本。

4）剝奪政策和生命周期

在每個斷裂更改之前都先進行剝離（通常外部為90-180天，內部為30-60天）。
通訊：changelog，電子郵件/webhooks合作夥伴，開發者門戶網站上的橫幅。
雙運行模式：同時保持「v1」和「v2」，監視「v1」的流量份額。

Sunset headers (REST): `Sunset: 2026-03-31`, `Link: ;rel="deprecation"`.

5) Version negotiation

客戶端發送所需的版本+最大支持版本（例如「接受版本：1.2」）。
如果能夠升級,服務器將響應「Content-Version： 2」。
在雙向協議（WebSocket，gRPC）中，是「支持_版本」的Hello框架交換。

6）與提供程序適配器（ACL）的集成)

外部提供商正在改變模式-在適配器內,我們保留v1/v2映射器,並在內部事件中發布MINOR,同時保留我們的域合同。
如果外部更改進入內部-這是我們域事件的MAJOR和新的主題。

7）Changelog和Commites標簽

• `feat:...` → MINOR
• 「fix：……」/「chore」，「docs」，「perf」（無合同）→ PATCH
• 'feat!：'/'fix!：' /'refactor!：'或'BREAKING CHANGE： 'in → MAJOR

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8）自動發行版

CI：電路驗證器（OpenAPI/Protobuf/Avro/JSON-Shema），破解誹謗的細節。
SemVer-bot： Conventional Commits分析→計算bump （major/minor/patch）,設置標簽,生成changelog。
CD：分離的deploy和release（ficheflagi/configi激活新版本）。
控制：在成功的canary和一致的SLO之前,我們不會在PRO上發布「最新」。

9）配置和策略的語義

Configs（YAML/JSON）也有方案版本：「schema_version： 3」。
MINOR-新的可選字段/規則；MAJOR-結構/義務變更。
在驗證器中支持v2/v3；不兼容報告的configs遷移者。

10）兼容性測試

消費者驅動合同測試（Pact）：每次集成。
Schema-evolution測試：在新電路上運行舊的付費,反之亦然。
重播：在陰影中播放「v1」到「v2」的原始流量。
基於物業的：對陌生字段/enum的抵抗力。

11）按版本分列的可觀察性

對度量/邏輯進行標記：「api_version」、「schema_version」、「event_version」。
遷移碼：按版本劃分的流量份額,「v1/v2」的錯誤/潛伏期。
Alerta：如果「v1」沒有按計劃下降；「v2」發行後的4xx/5xx增長。

12）無停機遷移模式

Expand → Migrate → Contract (БД).

雙寫作+在切換閱讀之前比較差異。
Shadow compare用於排名/規則。
按特南特/地區分列的金絲雀；用於快速回滾的特征標誌。
Read-compat/Write-compat窗口：新版本讀取舊數據,但以新格式寫入。

13）反模式

「每個字段中的版本」代替資源/事件的轉換。
在MINOR下隱藏斷開更改（例如默認更改）。
刪除沒有窗口和消耗度量的缺失。
「Forever v1」：沒有計劃消除舊版本的→ techdolg和漏洞。
業務版本和容器映像版本的混合。

14）考試政策支票清單

• 記錄了版本格式和真相來源（Registry/Portal）。
• 批準了人工制品突破標準清單（REST/gRPC/GraphQL/events/DB）。
• 剝奪過程：時機，通訊，日落/橫幅，雙跑。
• 自動分頻電路檢查器和公約委員會。
• 使用版本和Alerta的達什板。
• 遷移花花公子（expand/migrate/contract，dual-write，shadow）。
• Configi和SDK有自己的版本和寄存器。
• 為客戶提供「如何選擇版本」的文檔,為團隊提供「如何升級」的文檔。

15）測試示例（iGaming案例）

「BetSettled v1」 → 「v2」事件：添加了「void_reason」（選項）和「tax」。amount` (optional) — MINOR.重新命名為「payout'→'win_amount」-MAJOR，新的主題。
REST'/wallets/transfer'：添加過濾器'?tenant_id='-MINOR。更改錯誤代碼「409'→'422」-MAJOR。
GraphQL：標記為「播放器」。年齡為'@deprecated'，有利於'Player。ageGroup'-在MINOR中發布，在X期之後在MAJOR中刪除。
DB：添加了「bonus_wager_left」 nullable-MINOR列。做了不空，刪除了「bonus_left」-MAJOR（通過expand/contract）。

二.結論

語義轉換不是關於數字，而是關於信任和可預測性。清晰的規則、自動檢查、受控的剝奪和透明的遙測使得API、事件和電路能夠無痛苦地進行集成,並經常、安全和有意義地發布更改。