Google API 設計指南－版本控制

翻譯自 API Design Guide - Versioning

這一章是網絡 API 的版本控制指南。由於一個 API 服務 能夠（may） 提供多個 API 接口，API 版本策略應用在 API 接口上而不是 API 服務。爲了方便，下面的 API 表示 API 接口。

網絡 API 應該（should） 使用 Semantic Versioning。對於版本號 MAJOR.MINOR.PATCH：

1. 有不兼容的升級時，增長 MAJOR

2. 添加了能向後兼容的新功能時，增長 MINOR

3. 修改了能向後兼容的 BUG 時，增長 PATCH

根據 API 版本的不一樣，major 版本號使用不一樣的規則：

• 對於 version 1(v1)，major 部分 應該（should） 加上 proto 的包名字，例如 google.pubsub.v1。若是包名包含穩定的類型而且接口不會有不兼容的改變，major 部分 能夠（may） 忽略版本號，例如：google.protobuf 和 google.longrunning。

• 對於除 v1 外的全部版本，major 版本號 必須（must） 加上 proto 的包名字。例如 google.pubsub.v2。

對於 pre-GA 的發佈（例如 alpha 和 beta），推薦在版本號中添加後綴，後綴 應該（should） 以 pre-release 的版本名（例如 alpha、beta）和可選的 pre-release 版本號組成。

版本進度的例子：

| Version | Proto Package | Description |
| - | - | - |
| v1alpha | v1alpha1 | v1 alpha 發佈 |
| v1beta1 | v1beta1 | v1 beta 第一次發佈 |
| v1beta2 | v1beta2 | v1 beta 第二次發佈 |
| v1test | v1test | 帶有假數據的內部測試版 |
| v1 | v1 | major 的版本是 v1，可正式使用 |
| v1.1beta1 | v1p1beta1 | 對 v1 版的首次小版本（minor）修改的 beta 發佈 |
| v1.1 | v1 | 小版本升級到 v1.1 |
| v2beta1 | v2beta1 | v2 beta 第一次發佈 |
| v2 | v2 | major 的版本是 v2，可正式使用 |

minor 和 patch 的版本號 應該（should） 表如今 API 配置和文檔中，必定不要（must not） 寫在 proto 的包名中。

注意：Google API 平臺目前沒有原生支持 minor 和 patch。對於每個 major 版本只有一套文件和客戶端的庫。API 做者須要經過文檔和發佈日誌手動記錄 minor 和 patch。

新的 major 版本號 必定不要（must not） 依賴 相同 API 以前的 major 版本。在瞭解相關聯的依賴性和穩定性風險後，API 能夠（may） 依賴其餘 API。一個穩定的 API 版本 必須（must） 只依賴其餘 API 的最新穩定版本。

在一段時間內，相同 API 的不一樣版本 必須（must） 在單個客戶端中同時工做。這樣才能幫助客戶端從舊版 API 平滑遷移到新版 API。

只有當沒有依賴後舊版本 API 才能被刪除。

被多個 API 共享的通用穩定的數據類型（例如日期和時間） 應該（should） 定義在單獨的 proto 包中。若是有必要進行不兼容的修改，則 必須（must） 引入新的類型或包含新 major 版本的包。

向後兼容

定義什麼是向後兼容的修改是比較困難的。

下面列出了一些，但若是你有任何疑問，點擊這裏查看詳情。

保持向後兼容的修改

• 向 API 服務中添加 API 接口

• 向 API 接口中添加方法

• 向方法添加 HTTP 綁定

• 向請求信息添加字段

• 向響應信息添加字段

• 向枚舉添加值

• 添加只輸出（output-only）的資源字段

破壞向後兼容的修改

• 刪除/重命名服務、接口、字段名、方法或枚舉值

• 修改 HTTP 綁定

• 修改字段類型

• 修改資源名的格式

• 修改已有請求的可見性（visible behavior）

• 在 HTTP 定義中修改 URL 格式

• 在資源消息中添加讀/寫字段

查看其餘章節