分享是最有效的學習方式。
部落格：https://blog.ktdaddy.com/
故事
工位上，小貓一邊擼著程式碼，一邊吐槽著前人設計的介面。
如下：
“我艹，貨架模型明明和商品SKU模型是一對多的關係，介面入參的時候偏偏要以最小粒度的SKU將重複入參進行平鋪”。
“一個介面居然做了多件事情，傳入引數複雜異常，不是一塊業務型別的東西，非得全部揉在一起”。
“如此長的業務流程，介面能快起來麼，難怪天天收到介面慢的告警”。
“這都啥啊，這名字怎麼能這麼取呢，這也太隨意了吧....”
......
小貓一邊寫著V2版本的新介面，一邊罵著現狀介面。
聊聊APi設計
在日常開發過程中，相信大家在維護老程式碼的時候也多多少少會像小貓一樣吐槽現有介面設計。很多專案經過歷史沉澱以及業務驗證，介面設計問題就慢慢放大暴露出來了。具體原因是這樣的：
第一種情況可能是業務發展的必然趨勢：不同技術人員對業務的看法和理解不同，一個介面可能經過多人的維護開發迭代，很多時候，新增功能也只是在原有的介面上直接擴充，當業務需求比較緊急的時候，大部分的研發一般都會選擇快速去實現，而不會太過去考慮現有介面擴充的合規性。
第二種情況可能是本身開發人員自身能力問題，對業務的把控以及評估不合理導致的最終介面設計缺陷問題。
在系統軟體開發過程中，一個好的UI設計可以讓使用者更好地使用一款產品。那麼深入一層，一個好的API設計則可以讓開發者高效地使用一個系統的能力，尤其是現在很多大型微服務專案中，API設計更加重要，因為此時的API呼叫方不僅僅是前端，甚至直接是其他服務。
那麼接下來，老貓會和大家從下面的幾個方面探討一下，日常開發中我們應該如何去設計API。
API設計需要明確邊界
在實際職場中，部門與部門之間、管理員與管理員之間容易出現扯皮、推諉現象。當然在系統和系統之間API的互動中其實往往也存在這樣的情況。打個比方客戶端的互動細節讓後端程式碼透過介面來兜，你覺得合理不？
所以這就要求我們遵循下面兩個點，咱們分別中兩個維度來看，一個是“面向於服務和服務之間的API”，另一個是“面向客戶端和服務之間的API”。
1、我們在設計API的過程中應該聚焦軟體系統需要提供的服務或者能力。API是系統和外部互動的介面，至於外部如何使用，透過什麼途徑使用並不是重點。
2、對於面向UI的API設計中，我們更應該避免去過多關注UI的互動細節。互動屬於客戶端範疇，不同的終端裝置，其互動必然也是不一樣的。
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有多種實現，在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。當然如果還有其他的API設計中的注意點也歡迎在評論區留言。