故事

工位上，小貓一邊擼著代碼，一邊吐槽著前人設計的接口。

如下：

“我艸，貨架模型明明和商品SKU模型是一對多的關系，接口入參的時候偏偏要以最小粒度的SKU將重復入參進行平鋪”。

“一個接口居然做了多件事情，傳入參數復雜異常，不是一塊業務類型的東西，非得全部揉在一起”。

“如此長的業務流程，接口能快起來么，難怪天天收到接口慢的告警”。

業務告警

“這都啥啊，這名字怎么能這么取呢，這也太隨意了吧....”

小貓一邊寫著V2版本的新接口，一邊罵著現狀接口。

聊聊APi設計

在日常開發過程中，相信大家在維護老代碼的時候也多多少少會像小貓一樣吐槽現有接口設計。很多項目經過歷史沉淀以及業務驗證，接口設計問題就慢慢放大暴露出來了。具體原因是這樣的：

第一種情況可能是業務發展的必然趨勢：不同技術人員對業務的看法和理解不同，一個接口可能經過多人的維護開發迭代，很多時候，新增功能也只是在原有的接口上直接拓展，當業務需求比較緊急的時候，大部分的研發一般都會選擇快速去實現，而不會太過去考慮現有接口拓展的合規性。

第二種情況可能是本身開發人員自身能力問題，對業務的把控以及評估不合理導致的最終接口設計缺陷問題。

在系統軟件開發過程中，一個好的UI設計可以讓用戶更好地使用一款產品。那么深入一層，一個好的API設計則可以讓開發者高效地使用一個系統的能力，尤其是現在很多大型微服務項目中，API設計更加重要，因為此時的API調用方不僅僅是前端，甚至直接是其他服務。

那么接下來，老貓會和大家從下面的幾個方面探討一下，日常開發中我們應該如何去設計API。

概覽

API設計需要明確邊界

在實際職場中，部門與部門之間、管理員與管理員之間容易出現扯皮、推諉現象。當然在系統和系統之間API的交互中其實往往也存在這樣的情況。打個比方客戶端的交互細節讓后端代碼通過接口來兜，你覺得合理不？

所以這就要求我們遵循下面兩個點，咱們分別從兩個維度來看，一個是“面向于服務和服務之間的API”，另一個是“面向客戶端和服務之間的API”。

1、我們在設計API的過程中應該聚焦軟件系統需要提供的服務或者能力。API是系統和外部交互的接口，至于外部如何使用，通過什么途徑使用并不是重點。

2、對于面向UI的API設計中，我們更應該避免去過多關注UI的交互細節。交互屬于客戶端范疇，不同的終端設備，其交互必然也是不一樣的。

API設計思路盡量面向結果設計而不是面向過程設計

相信大家應該都知道面向對象編程和面向過程編程吧。

老貓雖說的這里的面向結果設計其實和面向對象的概念有點類似。這種情況下的API應該是根據對象的行為來封裝具體的業務邏輯，調用方直接發起請求需要什么就能給出一個最終的結果性質的東西，而不是中間過程中某個狀態性質的東西。上層業務無需多次調用底層接口進行組裝才能獲取最終結果。

如下圖：

面向執行過程API設計

面向最終結果API設計

舉個例子。

銀行提現邏輯中，

如果面向執行過程設計的API應該是這樣的，先查詢出余額，然后再進行扣減。于是有了下面這樣的偽代碼。

public interface BankService {
  AccountInfo getAccountByUserName(String userName);
  void updateAccount(AccountInfoReq accountInfoReq);
}

如果是面向結果設計，那么應該就是這樣的偽代碼。

public interface BankService {
  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生成，甚至雪花算法直接生成。如果對外暴露更多實現細節，其實內部實現的可拓展性就會相當差。我們來看一下下面的代碼。

//反例:暴露實現細節
public interface tokenService {
  TokenInfo generateHashTokenByUserName(String userName);
}
//正例:足夠抽象、便于拓展
public interface tokenService {
  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 class PublishProductReq {
  private String title;
  private String headPicUrl;
  private List<Sku> skuList;

  //是否為更新動作，isModify就是所說的標志性質的參數
  private Boolean isModify;
  .....
}

那么對應的原始的發布接口為：

//反例：內部入參通過isModify抉擇區分不同的邏輯
public interface PublishService {
  PublishResult publishProduct(PublishProductReq req);
}

比較好的邏輯應將其區分開來,移除原來的isModify標志位：

public interface PublishService {
  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。