怎樣設(shè)計(jì)出優(yōu)美的Web API

這篇文章主要為大家分析了怎樣設(shè)計(jì)出優(yōu)美的Web API的相關(guān)知識(shí)點(diǎn)，內(nèi)容詳細(xì)易懂，操作細(xì)節(jié)合理，具有一定參考價(jià)值。如果感興趣的話，不妨跟著跟隨小編一起來(lái)看看，下面跟著小編一起深入學(xué)習(xí)“怎樣設(shè)計(jì)出優(yōu)美的Web API”的知識(shí)吧。

• 概述

WEB API的應(yīng)用場(chǎng)景非常豐富，例如：將已有系統(tǒng)的功能或數(shù)據(jù)開(kāi)放給合作伙伴或生態(tài)圈；對(duì)外發(fā)布可嵌入到其他網(wǎng)頁(yè)的微件；構(gòu)建前后端分離的WEB應(yīng)用；開(kāi)發(fā)跨不同終端的移動(dòng)應(yīng)用；集成公司內(nèi)部不同系統(tǒng)等等。在上述場(chǎng)景里，你可能是WEB API的使用者，也可能是設(shè)計(jì)者，但你知道如何評(píng)判WEB API的優(yōu)劣嗎？

• 評(píng)判標(biāo)準(zhǔn)

我們可以從三個(gè)維度來(lái)評(píng)判一個(gè)WEB API的優(yōu)劣：

• 易于使用：WEB API的用戶是程序還是人？我覺(jué)得首先是人，然后是程序。為什么這么說(shuō)呢？是否采用某個(gè)WEB API的決定是人做出的，一個(gè)好的WEB API必須符合人的審美，例如：簡(jiǎn)短易記、通俗易懂、便于輸入等。從程序角度看，WEB API應(yīng)該遵循行業(yè)規(guī)范，在調(diào)用時(shí)不需要做特殊化處理，有利于復(fù)用已有的代碼或工具。

• 便于更改：一個(gè)WEB API發(fā)布上線之后，免不了要根據(jù)真實(shí)用戶的反饋或者業(yè)務(wù)發(fā)展的需要做更新修改，這些更新修改必須盡量不影響用戶。要么提供多版本支持，要么給用戶提供切實(shí)可行的更新策略等等。

• 健壯穩(wěn)定：對(duì)外公開(kāi)的WEB API存在被攻擊的風(fēng)險(xiǎn)，以及無(wú)法準(zhǔn)確預(yù)估的訪問(wèn)量等，一個(gè)好的WEB API必須要有防注入、防篡改、防重放等安全機(jī)制，還要在訪問(wèn)量急劇上漲時(shí)避免服務(wù)被擊穿。

做到了上述三個(gè)方面，我們才有底氣將一個(gè)WEB API對(duì)外開(kāi)放，接受公眾的檢驗(yàn)。好的WEB API不僅方便使用，還助于提升個(gè)人或企業(yè)的技術(shù)影響力，從而形成正向循環(huán)，帶來(lái)越來(lái)越多的業(yè)務(wù)價(jià)值。為了設(shè)計(jì)出優(yōu)美的WEB API，我們需要了解與之相關(guān)的設(shè)計(jì)規(guī)范和事實(shí)標(biāo)準(zhǔn)，并且在設(shè)計(jì)開(kāi)發(fā)過(guò)程中盡量遵循它們。

• 設(shè)計(jì)規(guī)范

URI

• 便于輸入的URI，簡(jiǎn)短不冗余。每個(gè)WEB API都是一個(gè)服務(wù)，那下面反例當(dāng)中的“service”就是冗余的，而且“api”也重復(fù)出現(xiàn)了兩次，這種冗余都不利于記憶和輸入：

• 容易讀懂的URI，不要隨意采用縮寫(xiě)，縮寫(xiě)必須要符合國(guó)際標(biāo)準(zhǔn)規(guī)范，不要憑空發(fā)明創(chuàng)造，例如：國(guó)家代碼定義（ISO3166）。反例中出現(xiàn)了兩處縮寫(xiě)“sv”、“u”，在沒(méi)有附加說(shuō)明的情況下，用戶壓根不知道含義：

• 沒(méi)有大小寫(xiě)混用的URI。HTTP協(xié)議（RFC7230）規(guī)定：除了模式（schema）和主機(jī)名以外，URI的其他信息都要區(qū)分字母的大小寫(xiě)。下述兩個(gè)反例大小寫(xiě)混用，不方便記憶。

• 易于修改的URI，命名存在可預(yù)見(jiàn)的規(guī)律。下述正例我們可以很容易猜測(cè)改變最后的ID就可以訪問(wèn)其他商品的信息。

• 不會(huì)暴露服務(wù)端架構(gòu)的URI，URI只需要體現(xiàn)功能、數(shù)據(jù)結(jié)構(gòu)和含義，無(wú)需暴露服務(wù)端如何運(yùn)作的信息。這些信息對(duì)用戶來(lái)說(shuō)沒(méi)有意義，還存在潛在的風(fēng)險(xiǎn)，惡意用戶或者黑客會(huì)利用這些信息來(lái)尋找漏洞，發(fā)起對(duì)服務(wù)的攻擊。

• 規(guī)則統(tǒng)一的URI，確保采用統(tǒng)一的規(guī)則和風(fēng)格，方便用戶記憶和使用。下述反例中第一個(gè)URI采用了查詢(xún)參數(shù)，第二個(gè)URI采用了路徑參數(shù)，這兩者沒(méi)有保持一致，容易造成混亂。

• URI最好由名詞組成。URI的全稱(chēng)是統(tǒng)一資源定位符（Uniform Resource Identifier），用于標(biāo)識(shí)資源在互聯(lián)網(wǎng)上的位置，類(lèi)似于郵寄地址，而地址都是由名詞組成的。在名詞使用上也有一些需要注意的事項(xiàng)：其一，使用名詞復(fù)數(shù)形式；其二，盡量采用多數(shù)API中使用的表示相同含義的單詞；其三，通過(guò)盡可能少的單詞來(lái)表示；其四，盡可能不用奇怪的縮略語(yǔ)等。

• 不使用空格及需要編碼的字符，例如在URI中使用中文等。

• 使用連接符（-）來(lái)連接多個(gè)單詞，推薦脊柱法：首先，URI里的主機(jī)名（域名）允許使用連字符而禁止使用下劃線，且不區(qū)分大小寫(xiě)。其次，點(diǎn)字符具有特殊含義，為了與主機(jī)名的規(guī)則保持一致。

查詢(xún)參數(shù)

• 許多場(chǎng)景下需要通過(guò)API分批次獲取數(shù)據(jù)，我們會(huì)經(jīng)常糾結(jié)采用什么樣的查詢(xún)參數(shù)，業(yè)界有兩種常用的參數(shù)設(shè)計(jì)（per-page與page、limit與offset），用于標(biāo)識(shí)每次獲取的數(shù)據(jù)量和起始位置。在分批次獲取數(shù)據(jù)的過(guò)程中，數(shù)據(jù)集合中的記錄可能發(fā)生增刪改變，我們需要注意采用相對(duì)位置或絕對(duì)位置所帶來(lái)的不同效果。

• 在設(shè)計(jì)過(guò)濾的參數(shù)時(shí)，業(yè)界也有一些事實(shí)標(biāo)準(zhǔn)可供參考。如果我們期望查詢(xún)結(jié)果的特定屬性取值跟過(guò)濾參數(shù)的取值完全相同，那過(guò)濾參數(shù)的名稱(chēng)通常為屬性名；如果我們期望查詢(xún)結(jié)果任意屬性部分包含過(guò)濾參數(shù)的取值，那過(guò)濾參數(shù)的名稱(chēng)通常為“q”。

• URI是否可以包含動(dòng)詞“search”？通常以搜索為主的在線服務(wù)API可以包含，除此之外建議采用名詞復(fù)數(shù)形式。常用英文單詞“search”和“find”都有查找的含義，但兩者還是有一些細(xì)微的差別，其中“search”用于模糊搜索，而“find”用于精準(zhǔn)查詢(xún)。

• 某個(gè)屬性究竟是作為URI路徑的構(gòu)成元素還是作為查詢(xún)參數(shù)呢？我們可以按照以下規(guī)則來(lái)判斷：如果該屬性信息可以唯一定位資源，那么它就適合作為路徑構(gòu)成元素，否則就作為查詢(xún)參數(shù)；如果該屬性可以省略，那么它就是適合作為查詢(xún)參數(shù)。

HTTP方法

按照HTTP協(xié)議設(shè)計(jì)的本意，URI用于標(biāo)識(shí)被操作的目標(biāo)對(duì)象（資源），而HTTP方法則是表示操作方法。基于HTTP協(xié)議的簡(jiǎn)單對(duì)象訪問(wèn)協(xié)議SOAP逐漸被RESTful的原生HTTP協(xié)議取代，我們也沒(méi)有必要畫(huà)蛇添足，最好就是吃透HTTP協(xié)議，充分利用它的特性。

• GET，獲取資源

• POST，新增資源

• PUT，更新已有資源

• DELETE，刪除資源

• PATCH，更新部分資源

• HEAD，獲取資源的元信息

如果遇到上述HTTP方法無(wú)法覆蓋的場(chǎng)景，那通常是資源的設(shè)計(jì)粒度太大了，我們可以把粗粒度的資源分解成多個(gè)細(xì)粒度的資源。在使用HTTP協(xié)議設(shè)計(jì)WEB API的專(zhuān)業(yè)能力上，業(yè)界將其劃分為四個(gè)層級(jí)，LEVEL3相對(duì)較理想化，缺乏實(shí)施的基礎(chǔ)，LEVEL2是切實(shí)可行的：

• LEVEL 0：使用HTTP

• LEVEL 1：引入資源的概念

• LEVEL 2：引入HTTP動(dòng)詞（GET/POST/PUT/DELETE等）

• LEVEL 3：引入HATEOAS概念

響應(yīng)數(shù)據(jù)

常用的數(shù)據(jù)格式有：HTML、XML、JSON、YAML等，如果我們的服務(wù)在響應(yīng)時(shí)支持不同類(lèi)型的數(shù)據(jù)格式，那應(yīng)用在調(diào)用服務(wù)時(shí)如何獲得期望格式的響應(yīng)數(shù)據(jù)呢？通常我們可以考慮采用下述幾種指定數(shù)據(jù)格式的方法：

• 使用查詢(xún)參數(shù)的方法：

• 使用擴(kuò)展名的方法：

• 使用在請(qǐng)求首部指定媒體類(lèi)型的方法，優(yōu)先推薦此種方法：

響應(yīng)數(shù)據(jù)應(yīng)該包含哪些信息呢？是否越多越好？亦或越少越好，僅僅包含ID？建議是按需返回，根據(jù)業(yè)務(wù)功能所需返回相應(yīng)的數(shù)據(jù)。如果一個(gè)WEB API需要提供給不同業(yè)務(wù)場(chǎng)景使用，不同業(yè)務(wù)場(chǎng)景對(duì)數(shù)據(jù)屬性信息的要求不同，或多或少，這種情況我們可以讓用戶來(lái)選擇響應(yīng)的內(nèi)容，選擇方法就是通過(guò)查詢(xún)參數(shù)指定：

響應(yīng)數(shù)據(jù)的結(jié)構(gòu)應(yīng)該盡量扁平化，不要嵌套太深，減少?zèng)]有具體含義的信息載荷，這樣既可以壓縮報(bào)文尺寸，又可以節(jié)省帶寬的。當(dāng)然，如果層級(jí)結(jié)構(gòu)更具優(yōu)勢(shì)，也可以采用。

出錯(cuò)信息

建議通過(guò)HTTP協(xié)議首部的狀態(tài)碼來(lái)表示出錯(cuò)信息，而不是再封裝一層，遵守協(xié)議規(guī)范的好處是可以減少溝通的成本，也可以利用許多成熟的軟硬件產(chǎn)品來(lái)處理異常出錯(cuò)信息。HTTP協(xié)議定了了五種類(lèi)型的狀態(tài)碼：

• 1XX：消息

• 2XX：成功

• 3XX：重定向

• 4XX：客戶端原因引起的錯(cuò)誤

• 5XX：服務(wù)器端原因引起的錯(cuò)誤

我們需要每種狀態(tài)碼的使用場(chǎng)景，確保正確使用狀態(tài)碼。除此之外，服務(wù)還需要向客戶端返回詳細(xì)的出錯(cuò)信息，我們通?？梢圆捎孟率鰞煞N方法來(lái)傳遞詳細(xì)的出錯(cuò)信息：

• 方法1：定義私有的首部，將其填入響應(yīng)消息的首部。

• 方法2：將詳細(xì)的出錯(cuò)信息放入消息體。

版本管理

隨著業(yè)務(wù)的發(fā)展，每個(gè)發(fā)布上線的WEB API都存在更新修改的可能，那就需要引入版本管理的機(jī)制。業(yè)界有三種常見(jiàn)的標(biāo)注WEB API版本的方法：

• 在URI中嵌入版本編號(hào)：

• 在查詢(xún)字符串里加入版本信息：

• 通過(guò)媒體類(lèi)型來(lái)指定版本信息

同樣，版本編號(hào)也存在業(yè)界規(guī)范：語(yǔ)義化版本控制（Semantic Versioning）規(guī)范，網(wǎng)站地址： semver.org。版本編號(hào)由點(diǎn)號(hào)連接的3個(gè)數(shù)字組成，例如：1.2.3，分別表示主版本編號(hào)、次版本編號(hào)、補(bǔ)丁版本編號(hào)，版本編號(hào)的增加遵循下述規(guī)則：

• 在對(duì)軟件進(jìn)行不向下兼容的變更時(shí)，增加主版本編號(hào)；

• 在對(duì)軟件進(jìn)行向下兼容的變更或廢除某些特定的功能時(shí)，增加次版本編號(hào)；

• 如果軟件的API沒(méi)有發(fā)生變更，只是修正了部分bug，則增加補(bǔ)丁版本編號(hào)。

按照版本編號(hào)增長(zhǎng)的規(guī)則，WEB API的版本編號(hào)只需要標(biāo)注主版本編號(hào)就可以了，因?yàn)榇伟姹揪幪?hào)、補(bǔ)丁版本編號(hào)的增加都可以做到向下兼容，不會(huì)影響用戶使用，唯有主版本編號(hào)增加才需要用戶更新升級(jí)。除了標(biāo)注版本信息之外，我們?cè)趯?duì)外發(fā)布WEB API時(shí)還需要設(shè)計(jì)好版本變更的策略，例如：老版本提供多久的過(guò)渡期、同時(shí)兼容多少個(gè)版本、特定版本的終止日期等等。

• 總結(jié)

何為優(yōu)美？就是符合大眾審美的，對(duì)于WEB API來(lái)說(shuō)，就是符合標(biāo)準(zhǔn)規(guī)范的，這有利于降低用戶學(xué)習(xí)和使用的成本，便于交流，不存在隱沒(méi)成本。通常，業(yè)界存在的標(biāo)準(zhǔn)規(guī)范和事實(shí)標(biāo)準(zhǔn)都是經(jīng)過(guò)實(shí)踐篩選出來(lái)的，從遵循模仿開(kāi)始，然后再找機(jī)會(huì)創(chuàng)新，而不是一上來(lái)就重復(fù)發(fā)明輪子。

WEB API設(shè)計(jì)領(lǐng)域的標(biāo)準(zhǔn)規(guī)范就是URI、HTTP等，我們要最大程度地利用這些協(xié)議規(guī)范，讓每個(gè)WEB API都是用戶友好（易于使用）、技術(shù)友好（支持緩存、易于更改）的。除此之外，我們還需要考慮WEB API的健壯性。

關(guān)于“怎樣設(shè)計(jì)出優(yōu)美的Web API”就介紹到這了,更多相關(guān)內(nèi)容可以搜索億速云以前的文章，希望能夠幫助大家答疑解惑，請(qǐng)多多支持億速云網(wǎng)站！