微服務構建持久API的7大規則分別是什么

這篇文章給大家介紹微服務構建持久API的7大規則分別是什么，內容非常詳細，感興趣的小伙伴們可以參考借鑒，希望對大家能有所幫助。

前 言

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

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

2. API參數變化或返回結果變化而導致客戶端行為不一致，依賴客戶端需要大量重構，團隊不能專注在創新型工作

3. API 易用性差， 使用方技術棧不統一，各自進行API抽象及封裝，容易出錯

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

5. 閉門造車，產出微服務往往不能滿足需求，運行一段時間就會逐漸廢棄

SparkPost經過多年的探索與實踐，總結了大量最佳實踐，指導他們構建持久穩定的微服務API。現如今，它們的API被成千上萬的客戶使用，包括Pinterest、Zillow和Intercomto，每月發送超過150億封電子郵件。

七大原則

一、Restful是最好的，但要實用，不需要學究式

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

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

2. resources : 這些是HTTP操作人員執行的實體。

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

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

當我們創建SparkPost API時，我們試著不要太過學究式地使用純粹的REST模型，而是選擇易于使用。下面是兩個可能不遵循RESTful最佳實踐的示例:

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

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

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

二、發展進化并管理變化

我們有許多開發人員和團隊在使用我們的API的微服務，并在持續的變更。當工程師確定它已經通過了我們的測試時，我們就會自動將變更部署到生產中。

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

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

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

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

· 請求主體中的非預期查詢參數和JSON字段應該被忽略。

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

· 一個新的API資源、端點或現有資源上的操作。

· 一個新的可選參數或JSON字段。

· 在JSON響應主體中返回的新字段。

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

· 更改字段的數據類型。

· 一個新的必需參數或JSON 字段。

· 刪除現有端點或請求方法。

· 現有資源方法的實質性行為差異，例如將選項的默認值改為“true”

三、做任何修改時不要制造破壞 

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

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

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

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

· 我們發了一封郵件或發表了一篇博客文章，里面包含了關于改變的詳細信息以及我們為什么要做這些改變。

· 我們在API文檔中提供了升級指導。

四、“一個版本”規則

在過去的三年里，我們對API進行了數千次的修改，現在仍然是第一個版本。我們很早就決定不將API的版本超過第一個版本，因為這樣做會增加不必要的復雜性，從而減慢用戶對我們最新和最強大功能的使用。對API的版本控制也會減緩開發和測試，讓監控變得復雜，讓用戶文檔變得混亂。

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

· 把這個版本放到URL中: 容易做，但是從語義的角度來看是一個不好的選擇，因為這個實體在v1和v2之間沒有變化。

· 添加一個自定義的標題 : 也很容易做，但是語義不強。

· 在accept標頭中放置這個版本: 語義強但是最復雜的方法。

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

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

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

六、“文檔優先”的策略

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

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

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

七、聽取用戶的意見

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

隨著微服務架構的發展，微服務快速增長，有的企業內部運維了超過1000的微服務，且仍在不斷增長，每個微服務包含數十API，如何持續管理微服務API 變化將成為企業的關注點，SparkPost 根據這些規則和最佳實踐，為他們的業務從提供現場電子郵件基礎設施到以完全基于云計算的電子郵件發送服務提供了堅實的基礎。

關于微服務構建持久API的7大規則分別是什么就分享到這里了，希望以上內容可以對大家有一定的幫助，可以學到更多知識。如果覺得文章不錯，可以把它分享出去讓更多的人看到。