故事

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

如下：

“我艸，貨架模型明明和商品SKU模型是一對多的關(guān)系，接口入?yún)⒌臅r候偏偏要以最小粒度的SKU將重復(fù)入?yún)⑦M(jìn)行平鋪”。

“一個接口居然做了多件事情，傳入?yún)?shù)復(fù)雜異常，不是一塊業(yè)務(wù)類型的東西，非得全部揉在一起”。

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

業(yè)務(wù)告警

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

小貓一邊寫著V2版本的新接口，一邊罵著現(xiàn)狀接口。

聊聊APi設(shè)計

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

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

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

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

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

概覽

API設(shè)計需要明確邊界

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

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

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

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

API設(shè)計思路盡量面向結(jié)果設(shè)計而不是面向過程設(shè)計

相信大家應(yīng)該都知道面向?qū)ο缶幊毯兔嫦蜻^程編程吧。

老貓雖說的這里的面向結(jié)果設(shè)計其實(shí)和面向?qū)ο蟮母拍钣悬c(diǎn)類似。這種情況下的API應(yīng)該是根據(jù)對象的行為來封裝具體的業(yè)務(wù)邏輯，調(diào)用方直接發(fā)起請求需要什么就能給出一個最終的結(jié)果性質(zhì)的東西，而不是中間過程中某個狀態(tài)性質(zhì)的東西。上層業(yè)務(wù)無需多次調(diào)用底層接口進(jìn)行組裝才能獲取最終結(jié)果。

如下圖：

面向執(zhí)行過程API設(shè)計

面向最終結(jié)果API設(shè)計

舉個例子。

銀行提現(xiàn)邏輯中，

如果面向執(zhí)行過程設(shè)計的API應(yīng)該是這樣的，先查詢出余額，然后再進(jìn)行扣減。于是有了下面這樣的偽代碼。

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

如果是面向結(jié)果設(shè)計，那么應(yīng)該就是這樣的偽代碼。

public interface BankService {
  AccountInfo withdraw(String userName,Long amount);
}

API設(shè)計需要盡量保證職責(zé)單一

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

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

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

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

API不應(yīng)該基于實(shí)現(xiàn)去設(shè)計

在API設(shè)計過程中，我們應(yīng)該避免實(shí)現(xiàn)細(xì)節(jié)。一個API有多種實(shí)現(xiàn)，在API層面不應(yīng)該暴露實(shí)現(xiàn)細(xì)節(jié)，從而誤導(dǎo)用戶。

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

//反例:暴露實(shí)現(xiàn)細(xì)節(jié)
public interface tokenService {
  TokenInfo generateHashTokenByUserName(String userName);
}
//正例:足夠抽象、便于拓展
public interface tokenService {
  TokenInfo generateToken(Object key);
}

API的命名相當(dāng)重要

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

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

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

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

API設(shè)計需要避免標(biāo)志性質(zhì)的參數(shù)

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

public class PublishProductReq {
  private String title;
  private String headPicUrl;
  private List<Sku> skuList;

  //是否為更新動作，isModify就是所說的標(biāo)志性質(zhì)的參數(shù)
  private Boolean isModify;
  .....
}

那么對應(yīng)的原始的發(fā)布接口為：

//反例：內(nèi)部入?yún)⑼ㄟ^isModify抉擇區(qū)分不同的邏輯
public interface PublishService {
  PublishResult publishProduct(PublishProductReq req);
}

比較好的邏輯應(yīng)將其區(qū)分開來,移除原來的isModify標(biāo)志位：

public interface PublishService {
  PublishResult addProduct(PublishProductReq req);
  PublishResult editProduct(PublishProductReq req);
}

API設(shè)計出入?yún)⑿枰ＷC風(fēng)格一致

這里所說的出入?yún)⒌娘L(fēng)格一致主要指的是字段的定義需要保持一個，例如對外的訂單編號，一會叫做outerNo,一會叫做outerOrderNo。相關(guān)的用戶在調(diào)用的時候八成是會罵娘的。

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

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

API設(shè)計的時候考慮性能

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

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

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

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

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

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

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

異步操作模式

舉個例子：訂單支付中，支付是核心鏈路，支付后郵件通知是非核心鏈路，因此，可以把這些非核心鏈路的操作，改成異步實(shí)現(xiàn)， 這樣就可以提升API的性能。常用的異步方式有：線程池，消息隊列，事件總線等。當(dāng)然自從Java8之后還有比較好用的CompletableFuture。

5、Json序列化：JSON可以將復(fù)雜的數(shù)據(jù)結(jié)構(gòu)或?qū)ο筠D(zhuǎn)換為簡單的字符串，以便在網(wǎng)絡(luò)傳輸、存儲或與其他程序交互時進(jìn)行數(shù)據(jù)交換。優(yōu)化JSON序列化過程可以提高API性能。使用高效的序列化庫，減少不必要的數(shù)據(jù)字段，以及采用更緊湊的數(shù)據(jù)格式，都可以減少響應(yīng)體的大小，從而加快數(shù)據(jù)傳輸速度和解析時間。

6、其他提升性能方案：例如運(yùn)維側(cè)提升帶寬以及網(wǎng)速等等

上述羅列了相關(guān)API性能提升的一些措施，如果大家還有其他不錯的方法，也歡迎留言。

總結(jié)

談及軟件中的設(shè)計，無論是架構(gòu)設(shè)計還是程序設(shè)計還是說API設(shè)計， 原則其實(shí)都差不多，要能夠松耦合、易擴(kuò)展、注意性能。遵循上述這些API的設(shè)計規(guī)則， 相信大家都能設(shè)計出比較絲滑的API。