服務端 API 介面設計最佳實踐

在移動網際網路開發領域，我們經常需要針對移動裝置，提供資料訪問介面。在移動時代以前，介面設計並沒有面對這麼大的挑戰，因為那時期的應用開發，前後端的區分並沒有那麼明顯，需要專門設計介面的場景並不是很多。

讓我們來看看如今，在業內被廣泛採用的介面設計最佳原則。

api設計核心原則

採用restful urls 和 actions

如果說有乙個實踐，在世界範圍內被廣泛採用，那就是restful原則。restful這個原則是由roy fielding在他的學術**network based software architectures的第五章裡被第一次提到。

rest的核心思想是，把api按照邏輯上的資源來進行區分。這些資源被http的不同方法( get, post, put, patch, delete )進行請求，每個方法代表不同的含義。

舉個例子，如果我有乙個對使用者進行操作的介面。那麼，針對這個使用者的crud操作，採用restful的設計風格就是這個樣子的，

get /users- 獲取使用者列表

get /users/12- 獲取id等於12的使用者

post /users- 建立乙個新使用者

put /users/12- 更新id等於12的使用者

patch /users/12- 部分更新id等於12的使用者

delete /users/12- 刪除id等於12的使用者

rest的偉大之處在於，採用了既有的http methods，在乙個單獨的/users鏈結下，實現了多樣的功能操作。你不需要遵循任何的命名規範，僅僅需要乙個乾淨和整潔的url結構 /users。

總是使用https

總是使用https，沒有例外。當今，只要連線了網際網路，你的api就能夠在世界任何地方被訪問。不是所有的訪問都是安全的。有一些api資料沒有被加密，很容易遭到劫持並被篡改。

撰寫介面文件

好的文件，和好的介面同樣重要。介面文件需要被很容易地找到和訪問。大部分開發者會在進行介面開發之前，檢查並檢視介面文件。如果這些介面文件是寫在pdf文件裡，或者需要登入才能檢視，那將不僅僅是難於查詢，還不利於搜尋。

介面文件應該描述完整的 request/response cycle，並附上具體的例子。最好是，這些例子應該是真實可以訪問的，比如把鏈結複製到瀏覽器裡執行，或者用curl執行。github 和 stripe 的介面文件都寫得很不錯。

一旦你發布了乙個api，那意味著，在沒有通知呼叫者的情況下，你有責任不去破壞該介面的已有功能。如果你在今後修改該介面，需要及時更新介面文件，並且在發布介面的更新之前，及時通知你的介面呼叫者。

versioning

總是給你的api加上版本化。api版本化能夠讓你的api迭代地更快，防止老的請求訪問你的api最新版。這樣能夠讓你在進行api重大公升級時，能夠持續對老版本api進行一段時間的支援。

有很多的人在討論，api的版本化，應該體現在url上，還是在請求header裡。理論上講，應該放在header裡。

api被發布出來，不會永遠不變。變化是不可避免的。重要的是，我們怎麼去管理這種變化。

限制api返回的字段

api呼叫者有時候不希望資源的所有欄位都返回。如果能夠在呼叫時，選擇api能夠返回的字段，將減少網路傳輸流量，加速呼叫方的業務處理。

可以使用fields查詢引數來限制api返回的字段。比如，以下請求只返回需要的字段資訊：


get /users/12?fields=id,user_name,age

錯誤**

就像html頁面出錯了展示的錯誤訊息一樣，api在出錯時也應該提供乙個有用的錯誤訊息給呼叫方。

api應該總是返回合理的http狀態碼。api的錯誤通常分為兩類：客戶端呼叫錯誤使用的400系列狀態碼，和服務端處理錯誤使用的500系列狀態碼。

乙個json錯誤訊息應該包含這麼幾個部分，乙個有用的錯誤訊息，乙個唯一的錯誤碼( 方便在介面文件里查到更詳細的錯誤描述 )和乙個詳盡的錯誤描述。就像這樣：

對於資料校驗錯誤，錯誤訊息應該包含具體出錯的字段資訊，就像這樣：

,
]}

http狀態碼

http定義了一系列有意義的狀態碼，api可以直接採用這些狀態碼進行返回。這能幫助api呼叫方更好地處理返回結果。常用的http狀態碼有：

總結

api就是開發者的」user inte***ce」。花一點精力，確保api不僅僅是滿足功能，而是讓使用者感到愉悅。

譯自( 有刪減 )：

參考資料：

杏樹林研發 劉龍軍