API版本控制的生命週期方法 - nordicapis

“成功的軟體總是會改變。” -弗雷德裡克·P·布魯克斯

對於一般軟體而言，同樣適用於 API：成功的 API 會發生變化。原因很簡單：成功的 API 被各​​種 API 消費者使用，他們需要新功能、擴充套件、錯誤修復和優化。從這個角度來看，API 的變化是不可避免的。

但這只是故事的一半。各種消費者使用 API 並依靠它們來保持穩定。否則，它會破壞他們現有的整合。他們的軟體客戶端依賴於 API，即使 API 中的一個小改動也足以破壞這些客戶端。從這個角度來看，API 的變化是不可取的。

顯然，有一個兩難選擇。解決這個困境是 API 提供者的任務。在這篇文章中，我想給你一些處理它的技巧。

版本控制的生命週期方法

為了有效地處理變更和版本控制，我們需要採用生命週期方法：研究 API 及其從開始和設計一直到退役的處理變化的能力。我希望這不會讓你感到意外——應對變化也需要做好準備。這意味著在具體的變更提案出現之前考慮 API 變更方式。

我們可以將 API 的生命週期分為兩個主要階段：釋出 API 之前的設計階段和釋出 API 之後的階段。

在這兩個階段，您必須以非常不同的方式處理變化。事實上，當從一個階段過渡到下一個階段時，你對改變的心態需要轉換 180 度。

• 釋出 API 之前

當您最初設計 API 時，您甚至可能不會考慮未來的更改。但他們會來的。因此，這裡有關於如何在設計時支援 API 的演變和版本控制的三個技巧。

• 釋出 API 之前：歡迎在迭代 API 設計中提供反饋

在 API 釋出之前，改變是偉大的——你應該歡迎它並尋找它。使用迭代開發方法，從測試版客戶那裡獲得反饋，並根據您收到的 API 模擬和 API 測試版的反饋調整 API 規範。這種迭代開發應該確保您建立的 API 實際上是相對穩定的。它還應該減少近期發生變化的可能性。但是不要在這裡停留在您的 API 設計上，而是立即釋出 API。

• 釋出 API 之前：為版本控制準備 API 設計模式

從一開始就為版本控制建立 API 設計模式。在最初的設計時，這似乎是多餘的，但它允許您在未來推出一致的版本，併為 API 使用者設定正確的期望。理想情況下，為您的 API 選擇的版本控制 API 設計模式記錄在您的 API 設計風格指南中。

雖然最常見的模式將 API 版本控制作為 URI 路徑引數來實現，但有多種替代 API 設計模式可以使主要版本可訪問：

1. Accept 標頭中的 API 版本控制：客戶端可以使用 HTTP Accept 標頭明確指示 API 的版本。Accept 標頭仍然像往常一樣包含 MIME 型別，但另外附加了版本。API 的 URI 不包含任何版本資訊。對於新版本，URL 不會更改，但請求標頭會更改。
2. API 版本控制作為 URI 路徑引數：最常見的版本控制技術使用帶有版本號的 URI 引數。
3. 自定義 HTTP 標頭中的 API 版本控制：可以為版本定義自定義 HTTP 標頭。
4. API 版本控制作為查詢引數：可以為版本定義查詢引數。
5. API 版本控制作為新的子域：可以為新版本定義一個子域。

• 釋出 API 之前：預測未來的變化

預測您的 API 未來的變化，並在您的 API 設計中適應它。每個人都知道這很困難，因為沒有關於未來的確鑿事實。但它是為 API 的演變和版本控制所做的必要準備。根據經驗和領域知識進行評估。也許您知道您的領域中有一個即將到來的行業標準需要支援。也許您知道某些標量資料欄位將來可能需要變成陣列。重點是準備 API 規範，以便在不破壞更改的情況下可以朝著預期的方向發展。

釋出 API 後

API 釋出後，為了您現有 API 使用者的利益，您對 API 變化的態度需要更加保守。需要更嚴格地管理變革。基本規則是 API 的外部可觀察行為（從客戶端的角度）一旦釋出就不能更改。當然，規則的例外是建立 API 的新版本。

• 管理變革：第 0 步——變革真的有必要嗎？

首先，評估提議的更改是否真的有必要。如果您可以避免更改：太好了。少一個問題。

• 管理變更：第 1 步 – 變更是否向後相容？

如果確實需要更改，請確定更改對 API 合同（通常是您的 Open API 規範）以及依賴 API 合同的 API 使用者意味著什麼。理想情況下，您擁有已釋出 API 的 API 規範和包含所有建議更改的新 API 規範。評估每個更改並確定它們是向後相容還是不相容。

向後相容的變化：

1. 新增查詢引數（它們應該始終是可選的）。
2. 新增標題或表單引數，只要它們是可選的。
3. 在 JSON 或 XML 資料結構中新增新欄位，只要它們是可選的。
4. 新增端點，例如新的 REST 資源。
5. 向現有端點新增操作，例如，在使用 SOAP 時。
6. 向請求介面新增可選欄位。
7. 將現有 API 中的必填欄位更改為可選欄位。

不相容的更改（又名破壞性更改）：

1. 移除或更改資料結構，即更改、移除或重新定義資料結構中的欄位。
2. 從請求或響應中刪除欄位（而不是使其可選）。
3. 將正文或引數中以前可選的請求欄位更改為必填欄位。
4. 將正文或引數中先前需要的響應欄位更改為可選欄位。
5. 更改 API 的 URI，例如主機名、埠或路徑。
6. 更改請求或響應欄位之間的結構或關係，例如，使現有欄位成為某個其他欄位的子項。
7. 向資料結構新增新的必填欄位。

• 管理變更：第 2 步——處理向後相容的變更

如果您沒有發現不相容的更改，只有向後相容的更改，那麼您應該能夠在不破壞客戶端的情況下實現它們。應用語義版本控制併為涵蓋更改的 API 版本提供新的次要版本。這個新的次要版本將取代已經發布的 API。舊客戶端不應受到更改的影響，而新客戶端可以從新功能中受益。更改存在一個普遍問題，即使它們是向後相容的。向後相容性基於 API 規範，即 OpenAPI 規範，作為與 API 使用者的“官方合同”。但是海侖定律 告訴我們，如果有足夠多的 API 使用者，就會有一個 API 使用者依賴於您的 API 的任何可觀察行為，而不僅僅是 OpenAPI 規範中描述的行為。

• 管理變更：第 3 步——處理重大變更

如果您發現至少一個不相容的更改，它將破壞依賴已更改功能的客戶端。該 API 需要一個新的主版本，並且這個新版本需要與之前的版本並行維護。此外，重要版本需要對消費者可見，並且消費者必須可以訪問它們。值得慶幸的是，如果您從一開始就遵循了本指南，那麼您已經擁有了一種用於選擇不同版本的機制。請參閱部分（為版本控制準備 API 設計模式）。

• 管理變革：第 4 步——日落

操作和維護多個版本的 API 需要 API 提供者方面的大量工作。遲早，舊版本的 API 必須被棄用。但這不應該是一個突然的事件，而是一個漸進的事件——就像日落一樣。這就是我們稱這個階段為API 日落階段的原因。

為 API 日落設定明確的期望，並儘早將其傳達給所有受影響的 API 消費者，讓他們儘可能多地處理日落並將其 API 客戶端提升到新版本。您必須獲取 API 使用者的聯絡方式，這些資訊通常在他們加入時收集。在郵件列表中獲取 API 使用者——不是為了營銷目的，而是為了產品變化。當 API 的新版本釋出時，在郵件列表中向所有 API 使用者傳送有針對性的訊息，包括關閉舊 API 的時間表。激勵您的 API 使用者及時切換到新版本，並說明使用最新版本的好處。

結論

更改 API 的影響可能難以管理。因此，開發人員必須在 API 生命週期的早期做好準備。我們已經看到 API 版本控制在引入第一個重大更改之前就開始了——甚至在 API 最初發布之前。一個設計合理的 API 很可能能夠在不破壞修改的情況下繼續存在，因為它是迭代設計的，並且已經預料到未來的變化，並且定義了版本控制模式。如果這些更改最終到來，您可以將這些更改歸類為向後相容和破壞性更改。然後，對次要和主要版本做出相應的反應，並最終淘汰舊的 API 版本。