微服務(wù)構(gòu)建持久API的7大規(guī)則分別是什么

這篇文章給大家介紹微服務(wù)構(gòu)建持久API的7大規(guī)則分別是什么，內(nèi)容非常詳細(xì)，感興趣的小伙伴們可以參考借鑒，希望對大家能有所幫助。

前 言

近年來，微服務(wù)架構(gòu)發(fā)展迅速，SparkPost就是早期落地微服務(wù)架構(gòu)公司之一，他們發(fā)現(xiàn)落地微服務(wù)過程中，不光需要考慮服務(wù)發(fā)現(xiàn)、服務(wù)注冊、服務(wù)調(diào)用跟蹤鏈等等架構(gòu)問題，也需要重視微服務(wù)API的變更管理。微服務(wù)的一大特性就是獨(dú)立發(fā)布，快速迭代，但前提是足夠穩(wěn)定，他們在使用微服務(wù)構(gòu)建API的過程中就遇到很多問題：

1. 客戶（微服務(wù)使用方）經(jīng)常反饋API 升級變更后不可用，有時(shí)影響范圍不可控，導(dǎo)致該微服務(wù)上線延期，甚至線上故障，違背了微服務(wù)初衷

2. API參數(shù)變化或返回結(jié)果變化而導(dǎo)致客戶端行為不一致，依賴客戶端需要大量重構(gòu)，團(tuán)隊(duì)不能專注在創(chuàng)新型工作

3. API 易用性差， 使用方技術(shù)棧不統(tǒng)一，各自進(jìn)行API抽象及封裝，容易出錯(cuò)

4. 缺少文檔及使用引導(dǎo)，需要大量支持工作

5. 閉門造車，產(chǎn)出微服務(wù)往往不能滿足需求，運(yùn)行一段時(shí)間就會逐漸廢棄

SparkPost經(jīng)過多年的探索與實(shí)踐，總結(jié)了大量最佳實(shí)踐，指導(dǎo)他們構(gòu)建持久穩(wěn)定的微服務(wù)API?，F(xiàn)如今，它們的API被成千上萬的客戶使用，包括Pinterest、Zillow和Intercomto，每月發(fā)送超過150億封電子郵件。

七大原則

一、Restful是最好的，但要實(shí)用，不需要學(xué)究式

首先，也是最重要的一步，我們采取的步驟是決定使用REST作為API。我們的理念是選擇以下三個(gè)要素作為我們的API的基礎(chǔ):。

1. HTTP : 這包括響應(yīng)代碼和操作符。操作符包括POST、GET、PUT和DELETE，它們可以映射到基本CRUD(創(chuàng)建、讀取、更新、刪除)操作。

2. resources : 這些是HTTP操作人員執(zhí)行的實(shí)體。

3. JSON (JavaScript對象表示法) : 這是一種通用的數(shù)據(jù)交換格式。

這三個(gè)元素提供了實(shí)用REST API所需的一切，包括簡單性、可移植性、互操作性和可修改性。在構(gòu)建了API之后，用戶可以輕松地對其進(jìn)行集成，而不考慮他們的編程語言，包括C#、PHP和Node。Js, Java，甚至是Shell中的CURL。他們可以不用擔(dān)心潛在的技術(shù)發(fā)展，包括多種微服務(wù)。

當(dāng)我們創(chuàng)建SparkPost API時(shí)，我們試著不要太過學(xué)究式地使用純粹的REST模型，而是選擇易于使用。下面是兩個(gè)可能不遵循RESTful最佳實(shí)踐的示例:

1. GET /api/v1/account?include=usage

2. POST/api/v1/sending-domains/example.domain.com/verify

第一個(gè)示例使用查詢字符串參數(shù)來過濾實(shí)體中返回的內(nèi)容。在第二個(gè)示例中，我們在終端名稱中使用“verify”這個(gè)動詞，這可能不符合Restful。我們會討論每個(gè)新的用例，并盡力確保它的一致性和易于使用。

二、發(fā)展進(jìn)化并管理變化

我們有許多開發(fā)人員和團(tuán)隊(duì)在使用我們的API的微服務(wù)，并在持續(xù)的變更。當(dāng)工程師確定它已經(jīng)通過了我們的測試時(shí)，我們就會自動將變更部署到生產(chǎn)中。

我們很早就決定讓我們的API在使用慣例和如何管理變更方面保持一致。我們建立了一個(gè)治理小組，其中包括代表每個(gè)團(tuán)隊(duì)的工程師、產(chǎn)品管理組的成員和CTO。這個(gè)組建立了并強(qiáng)制我們遵守的API約定，并且是完全文檔化的。

文檔化的約定讓我們可以減少不一致，并且更容易定義每個(gè)新的端點(diǎn)。以下是我們建立的一些約定:

· 在單詞命名時(shí)，URL路徑是帶有連字符的小寫字母，并且區(qū)分大小寫。

· URL查詢參數(shù)和JSON字段也是小寫的下劃線，并且是大小寫敏感的。

· 請求主體中的非預(yù)期查詢參數(shù)和JSON字段應(yīng)該被忽略。

治理組還為如何進(jìn)行更改以及允許哪些類型的更改設(shè)置了基本規(guī)則。有一些很好的API更改對用戶是有益的，并且不會破壞它們的集成，包括:

· 一個(gè)新的API資源、端點(diǎn)或現(xiàn)有資源上的操作。

· 一個(gè)新的可選參數(shù)或JSON字段。

· 在JSON響應(yīng)主體中返回的新字段。

相反，一個(gè)破壞性的變化包括任何可能破壞用戶集成的東西，比如:

· 更改字段的數(shù)據(jù)類型。

· 一個(gè)新的必需參數(shù)或JSON 字段。

· 刪除現(xiàn)有端點(diǎn)或請求方法。

· 現(xiàn)有資源方法的實(shí)質(zhì)性行為差異，例如將選項(xiàng)的默認(rèn)值改為“true”

三、做任何修改時(shí)不要制造破壞 

即使它們是修復(fù)bug或不一致的結(jié)果，也應(yīng)該避免發(fā)生修改。通常在這種特殊的情況下運(yùn)行比破壞與客戶端的集成風(fēng)險(xiǎn)更大。如果變化是多樣的，我們會非常謹(jǐn)慎，尋找其他方法來實(shí)現(xiàn)我們的目標(biāo)。有時(shí)可以通過簡單地允許用戶通過帳戶設(shè)置或API參數(shù)更改其行為來實(shí)現(xiàn)。

然而,總會有一種情況引入變化對我們用戶的利益勝過任何潛在的不利因素,將引入的變化。但是在這些情況下，我們遵循了這些最佳實(shí)踐: 

· 我們分析了API日志，以了解更改可能會影響多少用戶。

· 我們給用戶至少30到60天的提前警告。

· 我們發(fā)了一封郵件或發(fā)表了一篇博客文章，里面包含了關(guān)于改變的詳細(xì)信息以及我們?yōu)槭裁匆鲞@些改變。

· 我們在API文檔中提供了升級指導(dǎo)。

四、“一個(gè)版本”規(guī)則

在過去的三年里，我們對API進(jìn)行了數(shù)千次的修改，現(xiàn)在仍然是第一個(gè)版本。我們很早就決定不將API的版本超過第一個(gè)版本，因?yàn)檫@樣做會增加不必要的復(fù)雜性，從而減慢用戶對我們最新和最強(qiáng)大功能的使用。對API的版本控制也會減緩開發(fā)和測試，讓監(jiān)控變得復(fù)雜，讓用戶文檔變得混亂。

另外，我們的API沒有版本控制，這意味著我們可以避免圍繞主題的爭論。有三種方法可以實(shí)現(xiàn)API的版本，所有這些都有潛在的缺陷:

· 把這個(gè)版本放到URL中: 容易做，但是從語義的角度來看是一個(gè)不好的選擇，因?yàn)檫@個(gè)實(shí)體在v1和v2之間沒有變化。

· 添加一個(gè)自定義的標(biāo)題 : 也很容易做，但是語義不強(qiáng)。

· 在accept標(biāo)頭中放置這個(gè)版本: 語義強(qiáng)但是最復(fù)雜的方法。

五、使用客戶端庫來幫助非javascript用戶

我們的一些用戶更喜歡Python、c#、Java或PHP而不是JavaScript。我們通過維護(hù)客戶端庫(為其代碼提供易于使用的函數(shù)庫)將API集成到應(yīng)用程序中，使其快速進(jìn)行集成。

隨著時(shí)間的推移，我們的客戶庫已經(jīng)發(fā)生了變化，我們也做了相應(yīng)的版本。我們已經(jīng)了解到，在包裝一個(gè)不斷增長的API時(shí)，抽象是很困難的，所以我們專注于提供一層薄薄的抽象，并使用一些語法快捷方式來簡化我們API的使用。這樣做可以讓我們的用戶快速地訪問我們?nèi)魏蜛PI，并且具有許多靈活性

六、“文檔優(yōu)先”的策略

我們將我們的文檔視為代碼，并在編寫或更改一個(gè)API代碼行之前使用它來記錄我們的API更改。這樣做可以幫助我們執(zhí)行我們的約定，使所有事情保持一致，并保持良好的客戶體驗(yàn)。它還削減了支持成本。

我們在GitHub中維護(hù)我們的文檔，這使得技術(shù)和非技術(shù)用戶可以很容易地做出更改。我們還發(fā)現(xiàn)，更容易審查變更的方式。我們使用API Blueprint Markdown格式和Jekyll生成HTML文檔，以及一個(gè)名為Algolia的強(qiáng)大搜索服務(wù)。這樣做讓我們能夠提供更好的客戶體驗(yàn)，包括移動設(shè)備。

對于那些不想“滾動升級自己”文檔的人來說，我們推薦OpenAPI(以前稱為“Swagger”)、Apiary和API Blueprint。避免使用不適合REST API文檔的工具是很重要的。我們建議在文檔中包含一個(gè)亮橙色的“在Postman中運(yùn)行”的按鈕，這樣可以很容易地試用一個(gè)API，以及成功和失敗場景的例子。

七、聽取用戶的意見

最后，我們建議所有開發(fā)人員注意他們的用戶的反饋。SparkPost有一個(gè)社區(qū)Slack的頻道，成千上萬的用戶可以方便地聯(lián)系我們的產(chǎn)品、支持、工程和執(zhí)行管理團(tuán)隊(duì)的成員。我們也有一個(gè)專門的開發(fā)人員關(guān)系團(tuán)隊(duì)，他們專注于與開發(fā)人員社區(qū)的合作。所有這些都讓我們能更好傾聽用戶的意見，并將他們的反饋整合到我們的API中。

隨著微服務(wù)架構(gòu)的發(fā)展，微服務(wù)快速增長，有的企業(yè)內(nèi)部運(yùn)維了超過1000的微服務(wù)，且仍在不斷增長，每個(gè)微服務(wù)包含數(shù)十API，如何持續(xù)管理微服務(wù)API 變化將成為企業(yè)的關(guān)注點(diǎn)，SparkPost 根據(jù)這些規(guī)則和最佳實(shí)踐，為他們的業(yè)務(wù)從提供現(xiàn)場電子郵件基礎(chǔ)設(shè)施到以完全基于云計(jì)算的電子郵件發(fā)送服務(wù)提供了堅(jiān)實(shí)的基礎(chǔ)。

關(guān)于微服務(wù)構(gòu)建持久API的7大規(guī)則分別是什么就分享到這里了，希望以上內(nèi)容可以對大家有一定的幫助，可以學(xué)到更多知識。如果覺得文章不錯(cuò)，可以把它分享出去讓更多的人看到。