如圖所示，我們從這五件事情上來(lái)完成一個(gè)好的API接口設(shè)置
1. 標(biāo)準(zhǔn)化
對(duì)于web API標(biāo)準(zhǔn)化而言， 非常好的案例就是RESTful API ,目前業(yè)界的Open API 多數(shù)是基于RESTfun API 規(guī)范設(shè)計(jì)的，而RESTful API 已經(jīng)具有成熟度的模型，如下
其中Level 0 就是普通的請(qǐng)求響應(yīng)模式，Level 1引入了資源的概念，可以單獨(dú)創(chuàng)建URI，與Level0相比，通過(guò)資源的分而治之的方法來(lái)處理復(fù)雜的問(wèn)題，Level 2引入了一套標(biāo)準(zhǔn)的HTTP協(xié)議，通過(guò)遵守HTTP協(xié)議定義的動(dòng)詞（GET,POST,PUT,DELETE,PATCH），并配合HTTP響應(yīng)狀態(tài)碼來(lái)規(guī)范化Web API的標(biāo)準(zhǔn)，Level 3中使用超媒體，可以使協(xié)議擁有自我描述的能力。通常情況下，level等級(jí)達(dá)到2級(jí)就已經(jīng)非常好了。在RESTful API中，每個(gè)URI代表一種資源，URI就是每個(gè)唯一的資源定位符，因?yàn)镽ESTful API 可以通過(guò)GET ,POST,PUT,PATCH,DELETE等方式對(duì)服務(wù)端資源進(jìn)行操作，所以在定義接口的是，通常需要制定 請(qǐng)求方式/版本號(hào)/資源名稱(chēng)/資源ID
比如查看用戶(hù)編號(hào)是1001的用戶(hù)信息：
[GET] /v1/users/1001
當(dāng)一個(gè)資源變化難以用RESTful API命名的時(shí)候，可以考慮特殊的action命名，比如修改密碼
[PUT] /v1/users/1001/password/actions/modify
另外 不要?jiǎng)?chuàng)建自己的錯(cuò)誤碼，和返回錯(cuò)誤機(jī)制 , 很多時(shí)候我們覺(jué)得提供更多的自定義錯(cuò)誤碼有助于傳遞信息，但其實(shí)如果只是傳遞信息的話(huà)，錯(cuò)誤信息字段可以達(dá)到同樣的效果，此外對(duì)于客戶(hù)端來(lái)說(shuō)，很難關(guān)注到過(guò)多的錯(cuò)誤細(xì)節(jié)，這樣的設(shè)計(jì)就會(huì)讓API的處理更加復(fù)雜，難于理解。因此，建議是遵守RESTful API 規(guī)范，使用HTTP協(xié)議規(guī)范的錯(cuò)誤碼。比如，200表示請(qǐng)求成功，404表示無(wú)法找到，400表示錯(cuò)誤請(qǐng)求，403表示無(wú)權(quán)，500表示服務(wù)內(nèi)部錯(cuò)誤等等。當(dāng)響應(yīng)的是非200的HTTP錯(cuò)誤碼響應(yīng)時(shí)，可以采用全局的異常結(jié)構(gòu)響應(yīng)信息
響應(yīng)的異常結(jié)構(gòu)中，響應(yīng)信息中每個(gè)字段的含義
2. 兼容性
接口需要向下兼容，以前的業(yè)務(wù)不能受到影響。例如接口提供給了PC,Android，IOS不同端服務(wù)調(diào)用，在業(yè)務(wù)邏輯上處理會(huì)有些許的不同，如果不做兼容處理，則客戶(hù)端必須升級(jí)到最新的版本，用戶(hù)顯然是無(wú)法接受這樣的請(qǐng)求，所以就引入了版本的概念，來(lái)實(shí)現(xiàn)API的兼容
3.抽象性
通常情況下，我們的接口抽象都是基于業(yè)務(wù)需求的，因此一方面需要定義出清晰的業(yè)務(wù)問(wèn)題域模型，例如數(shù)據(jù)模型和領(lǐng)域模型，并建立起某個(gè)問(wèn)題的現(xiàn)實(shí)映射，實(shí)現(xiàn)抽象就能很好地屏蔽具體的業(yè)務(wù)實(shí)現(xiàn)細(xì)節(jié)，為我們提供更好的可擴(kuò)展性
4. 簡(jiǎn)單性
就是遵守最少知識(shí)原則，就是客戶(hù)端不需要知道那么多服務(wù)的API接口，以及這些API接口的調(diào)用細(xì)節(jié)，比如設(shè)計(jì)模型的外觀(guān)模式和中介則模式。一個(gè)接口對(duì)多個(gè)服務(wù)的調(diào)用封裝在一起，客戶(hù)端只需要調(diào)用這一個(gè)接口即可，不需要知道具體的內(nèi)部實(shí)現(xiàn)邏輯
5.高性能
外觀(guān)接口雖然保證了簡(jiǎn)單性，但是增加了服務(wù)器的業(yè)務(wù)復(fù)雜度，多個(gè)服務(wù)之間的聚合，也會(huì)導(dǎo)致接口的性能下降，所以在入?yún)⒆侄蔚慕M合上，我們需要考慮到數(shù)據(jù)庫(kù)的性能問(wèn)題，很多時(shí)候我們會(huì)暴露太多的字段給外部使用，在字段要求上沒(méi)有做處理，導(dǎo)致在查詢(xún)數(shù)據(jù)庫(kù)的時(shí)候沒(méi)有命中索引或者本身就沒(méi)有對(duì)應(yīng)的索引，導(dǎo)致全表掃描，性能急速下降。因此我們可以提供只存在索引的字段組合，給外部調(diào)用
