故事
工位上，小貓一邊擼著程式碼，一邊吐槽著前人設計的介面。
如下：
「我去，貨架模型明明和商品SKU模型是一對多的關系，介面入參的時候偏偏要以最小粒度的SKU將重復入參進行平鋪」。
「一個介面居然做了多件事情，傳入參數復雜異常，不是一塊業務型別的東西，非得全部揉在一起」。
「如此長的業務流程，介面能快起來麽，難怪天天收到介面慢的告警」。
「這都啥啊，這名字怎麽能這麽取呢，這也太隨意了吧....」
小貓一邊寫著 V2 版本的新介面，一邊罵著現狀介面。
聊聊APi設計
在日常開發過程中，相信大家在維護老程式碼的時候也多多少少會像小貓一樣吐槽現有介面設計。很多計畫經過歷史沈澱以及業務驗證，介面設計問題就慢慢放大暴露出來了。具體原因是這樣的：
第一種情況可能是業務發展的必然趨勢：不同技術人員對業務的看法和理解不同，一個介面可能經過多人的維護開發叠代，很多時候，新增功能也只是在原有的介面上直接拓展，當業務需求比較緊急的時候，大部份的研發一般都會選擇快速去實作，而不會太過去考慮現有介面拓展的合規性。
第二種情況可能是本身開發人員自身能力問題，對業務的把控以及評估不合理導致的最終介面設計缺陷問題。
在系統軟體開發過程中，一個好的UI設計可以讓使用者更好地使用一款產品。那麽深入一層，一個好的API設計則可以讓開發者高效地使用一個系統的能力，尤其是現在很多大型微服務計畫中，API設計更加重要，因為此時的API呼叫方不僅僅是前端，甚至直接是其他服務。
那麽接下來，和大家從下面的幾個方面探討一下，日常開發中我們應該如何去設計API。
API設計需要明確邊界
在實際職場中，部門與部門之間、管理員與管理員之間容易出現扯皮、推諉現象。當然在系統和系統之間API的互動中其實往往也存在這樣的情況。打個比方客戶端的互動細節讓後端程式碼透過介面來兜，你覺得合理不？
所以這就要求我們遵循下面兩個點，咱們分別從兩個維度來看，一個是「面向於服務和服務之間的API」，另一個是「面向客戶端和服務之間的API」。
1、我們在設計API的過程中應該聚焦軟體系統需要提供的服務或者能力。API是系統和外部互動的介面，至於外部如何使用，透過什麽途徑使用並不是重點。
2、對於面向UI的API設計中，我們更應該避免去過多關註UI的互動細節。互動屬於客戶端範疇，不同的終端裝置，其互動必然也是不一樣的。
API 設計思路盡量面向結果設計而不是程序導向設計
相信大家應該都知道物件導向編程和程序導向編程吧。
雖說這裏的面向結果設計其實和物件導向的概念有點類似。這種情況下的API應該是根據物件的行為來封裝具體的業務邏輯，呼叫方直接發起請求需要什麽就能給出一個最終的結果性質的東西，而不是中間過程中某個狀態性質的東西。上層業務無需多次呼叫底層介面進行組裝才能獲取最終結果。
如下圖：
舉個例子。
銀行提現邏輯中，
如果面向執行過程設計的API應該是這樣的，先查詢出余額，然後再進行扣減。於是有了下面這樣的虛擬碼。
publicinterfaceBankService{
AccountInfo getAccountByUserName(String userName);
voidupdateAccount(AccountInfoReq accountInfoReq);
}
如果是面向結果設計，那麽應該就是這樣的虛擬碼。
publicinterfaceBankService{
AccountInfo withdraw(String userName,Long amount);
}
API設計需要盡量保證職責單一
在設計API的時候，應該盡力要求一個API只做一件事情，職責單一的API可以讓API的外觀更加穩定，沒有歧義。並且上層呼叫層也是一目了然，簡單易用。
對於一個API如果符合下面條件的時候，咱們就可以考慮對其進行拆分了。
1、一個API內部完成了多件事情。例如：一個API既可以釋出新商品資訊，又能更新商品的價格、標題、規格資訊、庫存等等。如果這些行為在一個介面進行呼叫，介面復雜度可想而知。另外的介面的效能也是需要考慮的一部份，再者如果後續涉及許可權粒度拆分，其實這種設計就不便於許可權管控了。
2、一個API用於處理不同型別物件的業務。例如：一個API編輯不同的商品型別，由於不同型別的商品對應的模型通常是不同的（例如出行類的商品以及卡券類的商品差別就很大）， 如果放在一個API中，API的輸入和輸出參數會非常復雜，使用和維護成本就很高。
API不應該基於實作去設計
在API設計過程中，我們應該避免實作細節。一個API有多種實作，在API層面不應該暴露實作細節，從而誤導使用者。
例如生成token是最為常見的，生成token的方式也會有很多種。可以透過各種演算法生成token， 有的是根據使用者資訊的hash演算法生成，或者也可以用base64生成，甚至雪花演算法直接生成。如果對外暴露更多實作細節，其實內部實作的可拓展性就會相當差。我們來看一下下面的程式碼。
//反例:暴露實作細節
publicinterfacetokenService{
TokenInfo generateHashTokenByUserName(String userName);
}
//正例:足夠抽象、便於拓展
publicinterfacetokenService{
TokenInfo generateToken(Object key);
}
API的命名相當重要
一個好的API名字無疑是相當重要的，使用者一看API的命名就能知道如何使用，可以大大降低呼叫方的使用成本。所以我們在設計API的時候需要註意下面幾個方面。
1、API的名字可以自解釋，一個好的API的名稱可以清晰準確概括出API本身提供的能力。
2、保持對稱性。例如read/write,get/set。
3、基本的API的拼寫務必準確。API一旦釋出之後，只能增加新的API去訂正，舊API完全沒有請求量之後才能廢棄，錯誤的API的拼寫可能會帶給呼叫方理解上的歧義。
API設計需要避免標誌性質的參數
所謂標誌性的參數，就是一個介面為了相容不同的邏輯分支，增加參數讓呼叫方去抉擇。這塊其實和上述提及的API設計保證職責單一有點重復，但是很重要，所以還是單獨拎出來細說一下。舉個例子，上述提及的釋出商品，在釋出商品中既有更新的原有商品資訊的功能在，又有新增商品的功能在。於是就有了這樣錯誤的設計，如下：
public classPublishProductReq{
private String title;
private String headPicUrl;
private List<Sku> skuList;
//是否為更新動作，isModify就是所說的標誌性質的參數
private Boolean isModify;
.....
}
那麽對應的原始的釋出介面為：
//反例：內部入參透過isModify抉擇區分不同的邏輯
publicinterfacePublishService{
PublishResult publishProduct(PublishProductReq req);
}
比較好的邏輯應將其區分開來,移除原來的isModify標誌位：
publicinterfacePublishService{
PublishResult addProduct(PublishProductReq req);
PublishResult editProduct(PublishProductReq req);
}
API設計出入參需要保證風格一致
這裏所說的出入參的風格一致主要指的是欄位的定義需要保持一個，例如對外的訂單編號，一會叫做outerNo,一會叫做outerOrderNo。相關的使用者在呼叫的時候八成是會罵娘的。
比如對接供應商的相關API，呼叫對方建立發貨訂單之後返回的訂單編號是orderNo，後來使用者側完成訂單需要通知供應商，入參是outerNo。作者此時是懵逼的，都不知道這個 outerNo又是個什麽，後來找到對面的研發溝通了一輪才知道原來outerNo就是之前返回的orderNo。
於是 「好坑啊！」 收尾.....
API設計的時候考慮效能
最後再聊聊API效能，維護了很多的計畫，發現很多小夥伴在設計介面的時候並不會考慮介面效能。或者說當時那麽設計確實不會存在介面的效能問題，可是隨著業務的增長，數據量的增長， 介面效能問題就暴露出來了。就像上面小貓吐槽的，介面又又又慢了，又在報介面慢警告了。
舉個例子，查詢API，當數據量少的情況下，一個List作為最終返回搞定沒有問題的。但是隨著時間的推移，數據量越來越大，List能夠cover嗎？顯然是不行的，此時就要考慮是否需要透過分頁去做。所以原來的List的介面就必須要改造成分頁介面。
當然關於API效能的最佳化提升，有如下方式。
1、緩存：CRUD的讀寫效能畢竟是有限的。所以對某些數據進行頻繁的讀取，這時候，可以考慮將這些數據緩存起來，下次讀取時，直接從緩存中讀取，減少對資料庫的存取，提升API效能。
2、索引最佳化：很多時候介面慢是由於資料庫效能瓶頸，如果不用上述提及的緩存，那麽我們就需要看一下介面究竟是慢在哪個環節，可能是某個查詢，可能是更新，所以我們就要分析 執行的SQL情況去添加一些索引。當然這裏涉及如何進行MYSQL索引最佳化的知識點了，在此不展開。
3、分頁讀取：如上述例子中，針對的是那種隨著數據量增長暴露出來的，那麽我們就要對這些數據進行分頁讀取處理。
4、異步操作：在一個請求中開啟多工模式。
舉個例子：訂單支付中，支付是核心鏈路，支付後信件通知是非核心鏈路，因此，可以把這些非核心鏈路的操作，改成異步實作， 這樣就可以提升API的效能。常用的異步方式有：執行緒池，訊息佇列，事件匯流排等。當然自從Java8之後還有比較好用的CompletableFuture。
5、Json序列化：JSON可以將復雜的數據結構或物件轉換為簡單的字串，以便在網路傳輸、儲存或與其他程式互動時進行數據交換。最佳化JSON序列化過程可以提高API效能。使用高效的序列化庫，減少不必要的數據欄位，以及采用更緊湊的數據格式，都可以減少響應體的大小，從而加快數據傳輸速度和解析時間。
6、其他提升效能方案：例如運維側提升頻寬以及網速等等
上述羅列了相關API效能提升的一些措施，如果大家還有其他不錯的方法，也歡迎留言。
總結
談及軟體中的設計，無論是架構設計還是程式設計還是說API設計，
原則其實都差不多，要能夠松耦合、易擴充套件、註意效能。遵循上述這些API的設計規則，
相信大家都能設計出比較絲滑的API。當然如果還有其他的API設計中的註意點也歡迎在評論區留言。
👇🏻 點選下方閱讀原文，獲取魚皮往期編程幹貨。
往期推薦
