聊聊APi設計

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

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

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

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

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

API設計需要明確邊界

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

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

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

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

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

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

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

API設計需要盡量保證職責單一

在設計API的時候，應該盡力要求一個API只做一件事情，職責單一的API可以讓API的外觀更加穩(wěn)定，沒有歧義。并且上層調用層也是一目了然，簡單易用。

對于一個API如果符合下面條件的時候，咱們就可以考慮對其進行拆分了。

1、一個API內部完成了多件事情。例如：一個API既可以發(fā)布新商品信息，又能更新商品的價格、標題、規(guī)格信息、庫存等等。如果這些行為在一個接口進行調用，接口復雜度可想而知。另外的接口的性能也是需要考慮的一部分，再者如果后續(xù)涉及權限粒度拆分，其實這種設計就不便于權限管控了。

2、一個API用于處理不同類型對象的業(yè)務。例如：一個API編輯不同的商品類型，由于不同類型的商品對應的模型通常是不同的（例如出行類的商品以及卡券類的商品差別就很大）， 如果放在一個API中，API的輸入和輸出參數(shù)會非常復雜，使用和維護成本就很高。

API不應該基于實現(xiàn)去設計

在API設計過程中，我們應該避免實現(xiàn)細節(jié)。一個API有多種實現(xiàn)，在API層面不應該暴露實現(xiàn)細節(jié)，從而誤導用戶。

例如生成token是最為常見的，生成token的方式也會有很多種?？梢酝ㄟ^各種算法生成token， 有的是根據(jù)用戶信息的hash算法生成，或者也可以用base64生成，甚至雪花算法直接生成。如果對外暴露更多實現(xiàn)細節(jié)，其實內部實現(xiàn)的可拓展性就會相當差。我們來看一下下面的代碼。

API的命名相當重要

一個好的API名字無疑是相當重要的，使用者一看API的命名就能知道如何使用，可以大大降低調用方的使用成本。所以我們在設計API的時候需要注意下面幾個方面。

1、API的名字可以自解釋，一個好的API的名稱可以清晰準確概括出API本身提供的能力。

2、保持對稱性。例如read/write,get/set。

3、基本的API的拼寫務必準確。API一旦發(fā)布之后，只能增加新的API去訂正，舊API完全沒有請求量之后才能廢棄，錯誤的API的拼寫可能會帶給調用方理解上的歧義。

API設計需要避免標志性質的參數(shù)

所謂標志性的參數(shù)，就是一個接口為了兼容不同的邏輯分支，增加參數(shù)讓調用方去抉擇。這塊其實和上述提及的API設計保證職責單一有點重復，但是老貓覺得很重要，所以還是 單獨領出來細說一下。舉個例子，上述提及的發(fā)布商品，在發(fā)布商品中既有更新的原有商品信息的功能在，又有新增商品的功能在。

API設計出入參需要保證風格一致

這里所說的出入參的風格一致主要指的是字段的定義需要保持一個，例如對外的訂單編號，一會叫做outerNo,一會叫做outerOrderNo。相關的用戶在調用的時候八成是會罵娘的。

老貓最近其實在對接供應商的相關API，調用對方創(chuàng)建發(fā)貨訂單之后返回的訂單編號是orderNo，后來用戶側完成訂單需要通知供應商，入參是outerNo。老貓此時是懵逼的，都不知道這個 outerNo又是個什么，后來找到對面的研發(fā)溝通了一輪才知道原來outerNo就是之前返回的orderNo。

于是“我艸,坑筆啊”收尾.....

API設計的時候考慮性能

最后再聊聊API性能，維護了很多的項目，發(fā)現(xiàn)很多小伙伴在設計接口的時候并不會考慮接口性能。或者說當時那么設計確實不會存在接口的性能問題，可是隨著業(yè)務的增長，數(shù)據(jù)量的增長， 接口性能問題就暴露出來了。就像上面小貓吐槽的，接口又又又慢了，又在報接口慢警告了。

舉個例子，查詢API，當數(shù)據(jù)量少的情況下，一個List作為最終返回搞定沒有問題的。但是隨著時間的推移，數(shù)據(jù)量越來越大，List能夠cover嗎？顯然是不行的，此時就要考慮是否需要通過分頁去做。所以原來的List的接口就必須要改造成分頁接口。

當然關于API性能的優(yōu)化提升，老貓整理了如下提升方式。

1、緩存：CRUD的讀寫性能畢竟是有限的。所以對某些數(shù)據(jù)進行頻繁的讀取，這時候，可以考慮將這些數(shù)據(jù)緩存起來，下次讀取時，直接從緩存中讀取，減少對數(shù)據(jù)庫的訪問，提升API性能。

2、索引優(yōu)化：很多時候接口慢是由于數(shù)據(jù)庫性能瓶頸，如果不用上述提及的緩存，那么我們就需要看一下接口究竟是慢在哪個環(huán)節(jié)，可能是某個查詢，可能是更新，所以我們就要分析 執(zhí)行的SQL情況去添加一些索引。當然這里涉及如何進行MYSQL索引優(yōu)化的知識點了，老貓在此不展開。

3、分頁讀取：如上述老貓舉的例子中，針對的是那種隨著數(shù)據(jù)量增長暴露出來的，那么我們就要對這些數(shù)據(jù)進行分頁讀取處理。

4、異步操作：在一個請求中開啟多任務模式。