技術和基礎設施→轉化API

API轉化

1）為什麼需要它

驗證是一種管理的方式，可以在不發生故障的情況下更改服務和客戶之間的合同。在具有大量集成的產品（付款，KYC/AML，遊戲，計費，報告）中，「舊」和「新」客戶同時生活。正確的版本策略：

降低了發布事件的風險，
允許有計劃地引入改進和安全性，
為企業提供了可預測的合作夥伴遷移時間表。

2）更改分類

PATCH（不中斷）：不更改合同的修復程序（添加可選字段、驗證小冊子）。
MINOR（擴展）：反向兼容擴展（新端點,帶默認字段）。
MAJOR（斷開）：更改結構、語義或刪除字段/末尾。

建議使用SemVer'MAJOR。MINOR.PATCH'用於工件（SDK/模式），可以簡化「外部」API編號（v1，v2）。

3） REST轉化模型

1.在URI中：

`GET /v1/payments/{id}`

優點：透明、可緩存、易於路由。缺點：重復文檔，更難巧妙地演變。

2.在標題中（content negotation）：

`Accept: application/vnd.company.payments.v2+json`

優點：靈活性，URL中沒有「垃圾」，介質的方便演變。缺點：更難在瀏覽器中借記，需要紀律嚴明的客戶端。

3.在自定義標題中：

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

優點：就在網關上。缺點：沒有標準，小心緩存。

4.日期版本（基於日期）：

有利於金融科技/報告：可預測的變化「切口」（例如季度）。

5.資源/模型轉換：

相同的端點可以返回不同的視圖：'fields=……'或'profile=lite	full`.這是一個補充，不是忠誠的替代。

建議：外部集成-'URI vN'+Deprecation/Sunset標題；對於內部-如果網關和平臺支持,則可以「接受」或版本標題。

4) GraphQL

偏好-沒有全局版本。通過添加字段/類型和剝離（'@deprecated（reason：「……」）'）進行演變。
破裂的變化僅在帶有遷移蓋德的「大」窗口（經過驗證的計劃名稱）中。
註意「n+1」並確保您不會更改現有字段的測量。

5) gRPC / Protobuf

字段編號不變。遠程字段標記為「保留」。
將字段添加為帶有安全默認值的選項。
使用buf breaking/lint自動驗證兼容性。

轉化包/模塊： 'package payments。v1;` → `payments.v2`.

6）事件API （EDA）

事件圖是相同的合同。將其存儲在Schema Registry（Avro/JSON-Schema/Protobuf）中。

拓撲和版本： 'payments。v1.authorized`, `payments.v2.authorized`.

斷開更改是新事件類型或新拓撲。
進化保證：在LTS時期為領事提供反向匹配。

7）剝奪和EOL政策

實施透明規則：

Deprecation： changelog和BOM （OpenAPI/GraphQL SDL）中的標簽,標題
「Deprecation： true」和可能的「Sunset： Tue, 31 Mar 2026 pm GMT」
通訊：電子郵件/合作夥伴門戶,webhooks通知,發布通知。
截止日期：MINOR-3-6個月的支持，MAJOR-9-18個月（取決於臨界值）。
時間窗口：鎖定在「API驗證策略」中。

8）路由和發布

網關API （Cong/Apigee/Nginx/Envoy）：前綴「/v1/」、標題或介質規則。

路由示例：


if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow：將新版本滾動到1-5%的流量，比較合同錯誤指標和日誌。
Feature Flags：在不改變合同的情況下隱藏行為。
零時段遷移：MAJOR提供雙寫入/讀（雙寫入/讀取）數據模式。

9）合同測試和兼容性控制

buf breaking для protobuf.

OpenAPI Diff（或swagger-diff）-檢查MINOR/PATCH是否不中斷電路。
Spectral Linting是一種必備元數據的樣式（版本，Deprecation）。
Consumer-Driven Contracts （Pact）-確保提供商不會破壞客戶。
CI必須在不提高MAJOR的情況下下降。

10）文檔和SDK

Version spacks： '/docs/api/v1/openapi。json`, `/docs/api/v2/…`.

使用SemVer和changelog按版本（npm/maven/pypi）生成SDK。
在SDK中用註釋/註釋標記舊方法。

11）按版本劃分的觀察力

分開收集指標：

每個版本的RPS/潛在性/錯誤（「api_version」標簽）。
Endpoint使用圖：v1上還有誰？
Alerts：「>10% 4xx due to contract mismatch」,「老客戶>T日後的 X%」。

12）緩存和版本

路徑上的版本提高了CDN的緩存能力。

對於標題/介質版本-仔細使用Vary：

`Vary: Accept, X-API-Version`.
不要改變MINOR中響應的語義來打破kesh鍵。

13）安全性

不要在JWT中加密或縫制版本-版本定義查詢而不是令牌。
不要透露裝配的內部編號。在外部消息中,使用「v1/v2」。
在MAJOR中，修改驗證，限制，PII掩蓋。

14）遷移和汽車助理

發布「遷移指南v1 → v2」：字段對應表，查詢/響應示例，邊緣案例。
為突出顯示舊字段的客戶提供Linter （CLI）。
對於大型合作夥伴-具有兩個版本的sandbox和測試日期。

15）反模式

「永恒的v1」：沒有截止日期和使用指標。
MINOR/PATCH中隱藏的斷開更改。
「查詢字符串中的版本」（'?v=2'）-打破緩存和可讀性。
「一個終點-一百個標誌值」：難以測試/記錄。

16）實施支票

1.為外部和內部客戶選擇了一個模型（URI/Accept/Header）。
2.SemVer for BOM和SDK, CI中的自動斷路檢查。
3.Deprecation/Sunset策略和通信模板。
4.網關路由+金絲雀，按版本行駛。
5.CDC/合同測試關鍵集成（付款，KYC，報告）。
6.文檔/SDK/遷移指南與發布同時發布。
7.具有日期和責任的EOL計劃。

17）示例

17.1 REST （URI+頭條）

查詢：


GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

答案是：

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

剝奪標題（在v1上）：


Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17.2 Content Negotation（介質）


GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17.3 GraphQL（場剝奪）

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17.4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17.5事件模型

Topics：

`wallet.v1.balance.updated`
`wallet.v2.balance.changed"（具有擴展模式的新事件）

方案存儲在Registry中，制作人不會發布具有違反兼容性方案的事件。

18） iGaming/fintech的背景（實踐）

付款：新的PSP輸入v2，其中「status」/「decline_reason」得到了擴展；在網關上，mapping v1 → v2進行報告。
KYC： MINOR添加了「pep_screening」字段,v1客戶機忽略,v2-要求。
負責任的遊戲/限制：MAJOR改變了限制模式（每日/每周）。雙重導出到EOL v1之前的報告。
向監管機構報告：固定日期版本：「reporting-2025-01」。

19）迷你政策（示例wiki）

模型：用於外部API-「URI/vN/」；對於內部-「Accept：…… vN+json」或「X-API-Version： N」。
SemVer：規範和SDK發布為'N。minor.patch`.MAJOR需要RFC/ADR。
兼容性：MINOR/PATCH-無中斷更改。僅通過MAJOR打破→。
Deprecation/EOL：≥90天公告；標題中的日落日期；面向關鍵客戶的LTS分支。
控制：OpenAPI diff/buf breaking在CI, CDC中用於關鍵集成。
觀察力：帶有「api_version」標簽的度量/邏輯。
發行版本：canary 5% ≥ 24小時，然後在綠色指標下分階段高達100%。

結果

轉化不是關於「/v2 in URL」，而是關於過程：明確的進化規則，自動兼容性檢查，托管發行版和對集成的尊重。輸入清晰的策略,自動控制和可觀察性-更改將不再是對產品的威脅。

技術和基礎設施→轉化API

buf breaking для protobuf.

結果

與我們聯繫

快速聯繫

影片即將更新

我們目前正忙於各項專案