API是軟件系統(tǒng)的核心，而我們在設(shè)計API接口的時候會面臨著非常多的挑戰(zhàn)：
場景上來看，它是多樣的，如何設(shè)計一個隨處適用的API?
我們所參與的業(yè)務(wù)不斷演進(jìn)的，如何設(shè)計一個有兼容性的API?
我們的軟件流程是協(xié)同開發(fā)的，那我們?nèi)绾螌?shí)現(xiàn)對API的統(tǒng)一認(rèn)知?
今天我想和大家探討一下如何設(shè)計一個良好的API接口，我覺得好的API設(shè)計需要同時考慮到這幾個要素：標(biāo)準(zhǔn)化、兼容性、抽象性、簡單性、高性能，可以說這幾個要素缺一不可。
標(biāo)準(zhǔn)化
對于Web API標(biāo)準(zhǔn)化而言，一個非常好的案例就是Restful API。目前業(yè)界的Open API多數(shù)是基于Restful API規(guī)范設(shè)計的。
1、等級模型
需要注意的是Restful API它具有成熟度的模型。
其中Level 0是普通的請求響應(yīng)模式。
Level 1引入了資源的概念，各個資源可以單獨(dú)創(chuàng)建URI，與Level 0相比，它通過資源分而治之的方法來處理復(fù)雜問題。
Level 2引入了一套標(biāo)準(zhǔn)的HTTP協(xié)議，它通過遵守HTTP協(xié)議定義的動詞并配合HTTP響應(yīng)狀態(tài)碼來規(guī)范化Web API的標(biāo)準(zhǔn)。
Level 3中，使用超媒體可以使協(xié)議擁有自我描述的能力。
通常情況下，成熟度模型中達(dá)到Level 2就已經(jīng)非常好了。
2、URI
在Restful API中，每一個URI代表著一種資源，是每一個資源的唯一定位符。所謂資源，它可以是服務(wù)器上的一段文本、一個文件、一張圖片、一首歌曲，或者是一種服務(wù)。
Restful API呢，規(guī)定了通過get/post/put/patch/delete等方式對服務(wù)端的資源進(jìn)行操作。
因此，我們在定義一個Web API的時候，需要明確定義出它的請求方式、版本、資源名稱和資源ID。
舉個例子，要查看用戶編碼是101的用戶信息，我可以定義get的請求方式，而他的版本是V1，資源名稱是users，資源ID是1001。
這里可以思考一下，如果存在多個資源組合的情況呢?
事實(shí)上還可引入子資源的概念，需要明確定義出它的請求方式、版本、資源名稱與資源ID，以及子資源名稱與此資源ID。
舉個例子，要查看用戶編碼是101的用戶的權(quán)限信息，我可以定義get的請求方式。而他的版本是V1，主資源名稱是Users，主資源ID是1001子資源名稱是Roles，資源ID是101。
有時候，當(dāng)一個自然變化難以使用標(biāo)準(zhǔn)的Restful API來命名時，就可以考慮使用一些特殊的actions命名。
比如密碼修改接口，我可以定義Put的請求方式，而他的版本是V，主資源名稱是users，主資源ID是101資源字段是password。然后定義一個action的操作是modify。
3、錯誤碼和返回機(jī)制
與此同時啊，建議不要試圖創(chuàng)建自己的錯誤碼和返回錯誤機(jī)制。
很多時候呢，我們覺得提供更多的自定義的錯誤碼有助于傳遞信息，但其實(shí)，如果只是傳遞信息的話，錯誤信息字段可以達(dá)到同樣的效果。
此外，對于客戶端來說，很難關(guān)注到那么多錯誤的細(xì)節(jié)，這樣的設(shè)計只會讓API的處理變得更加復(fù)雜，難于理解。
因此，我的建議是遵守Restful API的規(guī)范，使用HTTP規(guī)范的錯誤碼。例如，我們用200表示請求成功，用400表示錯誤的請求，而500則表示服務(wù)器內(nèi)部的錯誤。
當(dāng)Restful API接口出現(xiàn)非200的HTTP錯誤碼響應(yīng)時，可以采用全局的異常結(jié)構(gòu)響應(yīng)信息。
4、返回體結(jié)構(gòu)
這里列出了最為常用的幾個字段，講一下它們各自表示的含義。
其中code字段用來表示某類錯誤的錯誤碼，例如前面介紹的無效請求、缺少參數(shù)、未授權(quán)資源、未找到資源、已存在的錯誤。
而message字段用來表示錯誤的摘要信息，它的作用是讓開發(fā)人員能快速識別錯誤。
server_time字段，用來記錄發(fā)送錯誤時的服務(wù)器時間，他可以明確的告訴開發(fā)人員發(fā)生錯誤時的具體時間，便于在日志系統(tǒng)中根據(jù)時間范圍來快速定位錯誤信息。
此外，不常用字段會根據(jù)不同的情況做出有不同的響應(yīng)。
如果是單條數(shù)據(jù)，則返回一個對象的json字符串;如果是列表數(shù)據(jù)，則返回一個封裝的結(jié)構(gòu)體，其中涵蓋count字段和item字段。
count字段表示返回數(shù)據(jù)的總數(shù)據(jù)量。需要注意的是，如果接口沒有分頁的需求，盡量不要返回這個count字段，因?yàn)椴樵兛倲?shù)據(jù)量是耗性能的操作。
此外，item字段表示返回數(shù)據(jù)列表，他是一個json字符串的數(shù)組。
5、小結(jié)
總結(jié)一下，怎么來理解規(guī)范呢?可以說他就是大家約定俗成的標(biāo)準(zhǔn)，如果都遵守這套標(biāo)準(zhǔn)，自然溝通成本也就大大降低了。
兼容性
接著我們再來探討一下API接口的兼容性。由于我們參與的業(yè)務(wù)是不斷演進(jìn)的，設(shè)計一個有兼容性的API就顯得尤為重要了。如果接口不能夠向下兼容，業(yè)務(wù)就會受到很大影響。
例如：
我們的產(chǎn)品是涵蓋android、ios、pc端的，都運(yùn)行在用戶的機(jī)器上，這種情況下，用戶必須升級產(chǎn)品到最新的版本才能夠更好的使用。
同時，我們還可能遇到服務(wù)端不停機(jī)升級，由于API不兼容而遇到短暫的服務(wù)故障。
為了實(shí)現(xiàn)API的兼容性，我們引入了版本的概念，前面的案例URI中通過保留版本號實(shí)現(xiàn)了兼容多個版本。
舉個例子，針對要查看用戶編碼是1001的用戶信息，可以分別定義V1和V2兩個版本的API接口，然后分別讓他們對應(yīng)兩套不完全兼容的業(yè)務(wù)邏輯特性。
抽象性
通常情況下，我們的接口抽象都是基于業(yè)務(wù)需求的，因此我們一方面要定義出清晰的業(yè)務(wù)問題域模型，例如數(shù)據(jù)模型和領(lǐng)域模型等，并建立起某個問題的現(xiàn)實(shí)映射，這樣有利于不同的角色對API設(shè)計認(rèn)知的統(tǒng)一。
另一方面，API設(shè)計如果可以實(shí)現(xiàn)抽象，就可以很好的屏蔽具體的業(yè)務(wù)實(shí)現(xiàn)細(xì)節(jié)，為我們提供更好的可擴(kuò)展性。
簡單性
簡單性的主要宗旨是遵守最少的知識原則。
怎么來理解呢?其實(shí)就是客戶端不需要知道那么多服務(wù)的API接口，以及這些API接口的調(diào)用細(xì)節(jié)，比如設(shè)計模式的外觀模式和中介者模式都是它的應(yīng)用案例。
如圖所示，外觀接口將多個服務(wù)進(jìn)行業(yè)務(wù)封裝與整合，并提供了一個簡單的API調(diào)用給客戶端使用，這樣設(shè)計的好處是什么呢?就在于客戶端只需要調(diào)用這個外觀接口就行了，省去了一些繁雜的步驟。
性能
同時，我們還需要關(guān)注性能，就比如說外觀接口，雖然保證了簡單性，但是增加了服務(wù)端的業(yè)務(wù)復(fù)雜度，同時，由于多服務(wù)之間的聚合，導(dǎo)致他們的接口性能也不是太好。
此外，我們還需要考慮字段的各種組合會不會導(dǎo)致數(shù)據(jù)庫的性能問題。有時，我們可能暴露了太多字段給外部使用，導(dǎo)致數(shù)據(jù)庫沒有相應(yīng)的索引而發(fā)生全表掃描。這種情況在查詢的場景下非常常見，因此我們可以只提供存在索引的字段組合給外部調(diào)用。
Result agree(Long taskId，Long caseId，Configger configger)
在上面這個代碼案例中，要求調(diào)用方必填taskId和caseId來保證數(shù)據(jù)庫索引的使用，以進(jìn)一步保證服務(wù)提供方的服務(wù)性能。
總結(jié)
今天給大家側(cè)重探討的是如何設(shè)計一個良好的API接口。
好的API設(shè)計需要我們同時考慮到標(biāo)準(zhǔn)化、兼容性、抽象性、簡單性和高性能。
其中，標(biāo)準(zhǔn)化的關(guān)鍵在于盡可能少的創(chuàng)建自定義規(guī)范和機(jī)制，而是共同遵守業(yè)內(nèi)標(biāo)準(zhǔn)，例如HTTP規(guī)范和Restful API規(guī)范。
通常情況下，我們會采取版本號來解決多版本的兼容性的問題。
抽象性需要確保能夠定義出清晰的問題域模型，盡可能屏蔽具體的業(yè)務(wù)實(shí)現(xiàn)細(xì)節(jié)。
簡單性是相對的，需要遵守最少知識原則，讓調(diào)用方盡可能少的知道內(nèi)部的調(diào)用細(xì)節(jié)，性能注意的細(xì)節(jié)就多了，這里主要強(qiáng)調(diào)了業(yè)務(wù)組合和參數(shù)組合場景。
途傲科技為中小企業(yè)提供網(wǎng)站制作、網(wǎng)站建設(shè)、微信H5、微信小程序，多商戶平臺，多級分銷系統(tǒng)，APP開發(fā)，手機(jī)網(wǎng)站，HTML5多端自適應(yīng)網(wǎng)站，營銷型企業(yè)站建設(shè)，及對技術(shù)人才的培養(yǎng)等都積累與沉淀了豐富的心得和實(shí)戰(zhàn)經(jīng)驗(yàn)。
如果您有想法，可以將需求提交給我們【免費(fèi)提交需求，獲取解決方案】
免責(zé)聲明：文章部分內(nèi)容收集于互聯(lián)網(wǎng)，不代表本站的觀點(diǎn)和立場，如有侵權(quán)請聯(lián)系刪除。
