開發者必備——API設計問題

本文主要探討RPC和RESTFul兩種API風格的特色以及在開發中應該如何進行技術選型，截取了部分網上社區，文章關於API設計的想法和觀點供讀者參考取捨。

1，背景簡述

API學名：應用程序接口（Application Programming Interface）

通俗的打個比方，人與人之間經過語言來交流，而程序和程序之間經過API來交流。

目前市場主流的API設計包括RPC，RESTFul，GraphQL等設計思路，關於API風格優劣，好壞衆說紛紜，但客觀來講：RPC資歷最老，並沿用至今，RESTFul後來者居上，火了好大一陣，最新的GraphQL聽說會在Githup下一版投入使用。API的選擇問題絲絕不亞於跨端框架Flutter和RN的激烈鬥爭。但筆者堅持認爲：軟件開發沒有銀彈，技術終究會被歷史裹挾，不斷推動，但對於開發者來講，也許沒有永恆的銀彈，但在當下選擇適合本身業務場景的技術倒是舉足輕重。

本篇文章主要探討前兩種API設計的優缺點以供讀者進行技術決策的參考。

2，RPC以動詞爲核心

2.1 命名風格

RPC 形式的API一般是動賓結構：

getUserInfo，createUser，getUserById

因爲接口的個性化需求，添加新功能時，API中可能會引入其餘的動詞或介詞如By，With，create等等，這也是RESTFul征討RPC的主要緣由

• 一是嫌它醜
• 二是認爲它不夠通用（在服務端更新了以後，客戶端也須要閱讀文檔，適應服務端）

3.1 經常使用實踐

• 面向接口編程

  在參數傳遞過程當中使用接口而不是實現類，使程序更加靈活可擴展

  例如使用Map而不是HashMap，TreeMap，使用List而不是ArrayList，LinkedList

• 方法重載

  通俗來說，省去了方法名，使得API調用更加方便

3，RESTFul以名詞爲核心

「表述性狀態轉移」

3.1命名風格

/admin/users （查詢用戶） 
/admin/users （新增用戶） 
/admin/users （更新用戶） 
/admin/users （刪除用戶）

雖然有點不太恰當，但RESTFul的以名詞爲核心的API風格其實就是把動詞使用請求方法代替了，所謂的表述性狀態轉移實際上就是用請求方法屏蔽掉了API的部分實現。但不能否認的是，這樣對於API的可讀性的確有顯著提升。

@RequestMapping(value = "/user", method = RequestMethod.GET)
 @RequestMapping(value = "/user", method = RequestMethod.DELETE)

然而，RESTFul並不能很好適應API的複雜性，例如常見的登陸註冊功能使用RESTFul的風格難以對資源進行抽象。RESTFul對於單資源的增刪改查的確能夠實現API的升級，但因爲其接口粒度過粗，對於多資源的查詢操做難以設計出合理的API。

3.2 經常使用實踐

• 資源名使用複數

  不要混淆名詞單數和複數，爲了保持簡單，只對全部資源使用複數。

• 避免多級 URL（存在爭議）

  獲取某個做者的某一類文章
  GET /authors/12/categories/2
  
  GET /authors/12?categories=2
  
  ==============================
  查詢已發佈的文章
  GET /articles/published
  
  GET /articles?published=true

4，如何對RPC和RESTFul進行技術決策？

• 可讀性

  相對於RPC，RESTFul風格的API具備更強的可讀性，更加利於理解

• 兼容性

  RESTFul相對於RPC接口，粒度更大。

  RESTFul適合應用於開發API的增刪改查，而RPC適合更加精細化可定製的業務場景

在實現開發接口API，RESTFul有更好的表現。

在實現業務系統，RPC具備更高的定製化能力。

5，關於API接口設計的一些討論

參考文章

淺談如何設計API

restful與rpc風格

REST與RESTFul API最佳實踐

API 設計最佳實踐的思考

RESTful API 最佳實踐