簡評：這是 fly.io分享的一篇文章，講了他們是怎么對自家 REST API 做版本控制的。另外還有很多其他的技術文章，個人感覺還不錯，感興趣的同學可以看一看。

API 設計是一個都快被說爛了的主題，已經有太多關于對 Web API 做版本控制很棒的文章了。比如：

但今天這里還是想分享一篇，希望看完能有所收獲。: )

API 版本控制

雖然還沒有一個絕對正確的方式來設計一個 API，但是有幾個關鍵想法是許多開發者都同意的，一個優秀的 Web API 應該是：

能保證一致性和穩定性；

版本的向后兼容；

RESTful。

為了能最好的實現這些理念，關于如何實現 API 的不同版本目前主要有三種做法：

在 URI 中標記版本

curl https://example.com/api/v2/lists/

通過解析 URI 中的版本號，客戶端可以訪問/v1/或/v2/等不同版本API。

在 Header 中標記版本

curl https://example.com/api/lists/3 \

-H 'Accept: application/vnd.example.v2+json'

直接不標記版本

curl https://example.com/api/lists/3

嗯，我們只有最新版本，趕緊去兼容吧。

不進行版本控制很有可能讓 API 變得混亂，因此現在很少人會不做 API 版本控制了。而這里，我們選擇同時在 URI 和 HTTP Header 中標記版本。下面讓我們來看一個例子：

假設我們正在為我們的 MightyList 應用構建一個 API，可以通過這個 API 來請求一組數據：

curl https://mightyapp.com/api/v1/lists/3

...

{

"listId": "3",

"shopping": "Shoes, tie, umbrella, snorkel",

"leisure": "Skiing, surfing, snorkeling ",

"food": "bananas, peanut butter, spinach",

"cost": "One hundred dollars"

}

我們先來看一個小的需求變化，在上面的例子中，cost

字段返回的是一個字符串。而現在我們的開發團隊希望將其變成數值類型。

curl https://mightyapp.com/api/v1/lists/3

...

{

"listId": "3",

"shopping": "Shoes, tie, umbrella, snorkel",

"leisure": "Skiing, surfing, snorkeling ",

"food": "bananas, peanut butter, spinach",

"cost": 100

}

這是一個很小的變動，但卻會破壞我們 API 的向后兼容性。像這種比較小，但卻會造成向后兼容性問題的變動，是應該進行版本號上的變動的。

還有一種就是比較重大的修改，比如：lists 變成了 superlists，又需要加入許多新的字段等等，這種大的升級基本都會破壞兼容性。這時通常做法都是將 URI 中的 /v1/變為/v2/。

因此理論上只要是影響到向后兼容性的改動都應該反應在版本號上，提供 Change Log 給使用者。但如果不論變動大小都升級 URI 中的版本號，這又會造成過多的版本。

為了保證我們應用狀態的清晰，我們希望在 URI 中有一個代表產品版本的版本號。當產品有了較大，或根本性的改變時，URI 版本將會改變。比如，MightyList V1 使用/api/v1/，MightyList V2 使用/api/v2/。

而對于當前版本內的較小修改，我們使用自定義的 HTTP Header 來表示。作者使用的自定義 Header 名為 API-Version，值為 day-month-year 格式的日期。

這樣我們就可以為 API 提供更新日志了，用戶也可以通過配置版本日期來訪問他們需要的 API 版本，就像這樣：

當然 API 設計有許多不同的理念和做法，這里也只是其中一種，或許能對你有所啟發。

總結

以上是生活随笔為你收集整理的java web api 版本控制_怎么做 Web API 版本控制？的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。