如此絲滑的API設(shè)計(jì)，用起來(lái)真香

分享是最有效的學(xué)習(xí)方式。

博客： https://blog.ktdaddy.com/

故事

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

如下：

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

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

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

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

......

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

聊聊APi設(shè)計(jì)

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

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

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

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

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

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

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

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

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

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

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

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

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

如下圖：

舉個(gè)例子。

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

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

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

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

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

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

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

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

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

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

其實(shí)關(guān)于API單一職責(zé)相關(guān)的話題，老貓?jiān)谥�前的文章中也有提及過(guò)，有興趣的小伙伴可以戳【 忍不了，客戶讓我在一個(gè)接口里兼容多種業(yè)務(wù)功能 】

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

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

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

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

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

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

1、API的名字可以自解釋?zhuān)�一個(gè)好的API的名稱(chēng)可以清晰準(zhǔn)確概括出API本身提供的能力。

2、保持對(duì)稱(chēng)性。例如read/write,get/set。

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

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

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

public class PublishProductReq {
  private String title;
  private String headPicUrl;
  private List skuList;

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

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

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

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

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

API設(shè)計(jì)出入?yún)⑿枰�保證風(fēng)格一致

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

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

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

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

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

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

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

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

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

3、分頁(yè)讀�。喝缟鲜隼县埮e的例子中，針對(duì)的是那種隨著數(shù)據(jù)量增長(zhǎng)暴露出來(lái)的，那么我們就要對(duì)這些數(shù)據(jù)進(jìn)行分頁(yè)讀取處理。

4、異步操作：在一個(gè)請(qǐng)求中開(kāi)啟多任務(wù)模式。

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

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

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

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

總結(jié)

談及軟件中的設(shè)計(jì)，無(wú)論是架構(gòu)設(shè)計(jì)還是程序設(shè)計(jì)還是說(shuō)API設(shè)計(jì)，
原則其實(shí)都差不多，要能夠松耦合、易擴(kuò)展、注意性能。遵循上述這些API的設(shè)計(jì)規(guī)則，
相信大家都能設(shè)計(jì)出比較絲滑的API。當(dāng)然如果還有其他的API設(shè)計(jì)中的注意點(diǎn)也歡迎在評(píng)論區(qū)留言。