在微服務的動態世界中，任何事情都可能發生變化——任何元件都可以使用不同的語言、使用不同的框架和架構進行重寫。 只有契約應該保持不變，以便微服務可以在某種永久的基礎上與外部交互，而不管內部發生變化。 今天我們將討論選擇描述合約的格式的問題並分享我們發現的工件。
後期準備 и
微服務。 在開發 Acronis Cyber Cloud 時，我們意識到我們無法逃脫它們。 如果沒有形式化契約（代表微服務的介面），設計微服務是不可能的。
但是，當產品包含多個元件，而合約開發成為常規活動時，您就會情不自禁地開始考慮流程最佳化。 很明顯，介面（契約）和實作（微服務）必須相互匹配，不同的元件必須以相同的方式做相同的事情，如果沒有對所有這些決策進行集中決策，每個團隊將被迫花時間一次又一次地得到它們。
亞馬遜微服務圖來自 Werner Vogelis，亞馬遜首席技術官
困境是什麼？ 事實上，微服務互動有兩種方式──HTTP Rest 和 Google 的 gRPC。 不想陷入 Google 的技術堆疊，我們選擇了 HTTP Rest。 HTTP REST 契約註釋最常採用兩種格式之一進行描述：RAML 和 OAS（以前稱為 Swagger），因此每個開發團隊都面臨著選擇其中一種標準的需要。 但事實證明，做出這樣的選擇可能非常困難。
為什麼需要註釋？
需要註釋，以便外部使用者可以輕鬆了解可以透過其 HTTP 介面對您的服務執行哪些操作。 也就是說，在基本層級上，註釋必須至少包含可用資源的清單、它們的 HTTP 方法、請求正文、參數清單、所需和支援的標頭的指示以及傳回代碼和回應格式。 合約註解的一個極其重要的元素是它們的口頭描述（「如果將這個查詢參數添加到請求中會發生什麼？」、「什麼情況下會返回代碼 400？」）
然而，當涉及到開發大量微服務時，您希望從書面註釋中提取額外的價值。 例如，基於 RAML/Swagger，您可以用大量程式語言產生客戶端和伺服器程式碼。 您也可以自動接收微服務的文件並將其上傳到您的開發人員入口網站:)。
結構化合約描述範例
根據合約描述測試微服務的做法較不常見。 如果您已經編寫了註釋和元件，那麼您可以建立一個自動測試來檢查服務與各種類型的輸入資料的充分性。 服務是否傳回註釋中未描述的回應代碼？ 它能夠正確處理明顯不正確的數據嗎？
此外，不僅合約本身的高品質實現，而且可視化註釋的工具也使得簡化微服務的工作成為可能。 也就是說，如果架構師定性地描述了契約，那麼基於它，設計者和開發者將在其他產品中實現該服務，而無需額外的時間成本。
為了啟用其他工具，RAML 和 OAS 都能夠新增標準未提供的元資料（).
一般來說，使用微服務合約的創造力範圍是巨大的…至少在理論上是如此。
刺蝟與蛇的比較
目前，Acronis 的優先開發領域是 Acronis Cyber Platform 的開發。 Acronis Cyber Platform 是第三方服務與 Acronis Cyber Cloud 和代理商部分的新整合點。 儘管我們對 RAML 中描述的內部 API 感到滿意，但發布 API 的需要再次引發了選擇問題：哪種註釋標準最適合我們的工作？
最初，似乎有兩種解決方案 - 最常見的開發是 RAML 和 Swagger（或 OAS）。 但事實證明，至少不是有2種選擇，而是3種或更多。
一方面是 RAML——一種強大而有效率的語言。 它很好地實現了層次結構和繼承，因此這種格式更適合需要大量描述的大公司- 即不是一個產品，而是許多具有契約公共部分的微服務- 身份驗證方案、相同的數據類型、錯誤體。
但RAML的開發商Mulesoft已經加入了Open API聯盟，該聯盟正在開發 。 因此，RAML暫停了其開發。 想像一下活動的形式，想像一下主要 Linux 元件的維護者離開去微軟工作。 這種情況為使用 Swagger 創造了先決條件，Swagger 正在動態開發，並且在最新的第三個版本中，在靈活性和功能方面幾乎趕上了 RAML。
如果不是因為一件事...
事實證明，並非所有開源實用程式都已更新至 OAS 3.0。 對於Go中的微服務來說，最關鍵的是缺乏適配性 取得該標準的最新版本。 然而，Swagger 2 和 Swagger 3 之間的差異是 。 例如，在第三個版本中，開發人員：
- 改進的認證方案描述
- JSON 模式支持
- 升級了添加範例的能力
情況很有趣：在選擇標準時，您需要將 RAML、Swagger 2 和 Swagger 3 作為單獨的替代方案來考慮。 然而，只有 Swagger 2 對開源工具有很好的支援。 RAML 非常靈活……而且複雜，而 Swagger 3 缺乏社區支持，因此您必須使用專有工具或商業解決方案，而這些工具或商業解決方案往往非常昂貴。
而且，如果Swagger中有很多不錯的功能，例如現成的門戶 ，您可以在其上上傳註釋並通過詳細描述、鏈接和連接獲得其可視化，那麼對於更基礎且不太友好的 RAML 則沒有這樣的機會。 是的，您可以在 GitHub 上的專案中搜尋某些內容，在那裡找到類似的內容並自行部署。 然而，無論如何，都必須有人維護門戶，這對於基本使用或測試需求來說不太方便。 此外，swagger 更“無原則”，或者說更自由——它可以從程式碼中的註釋生成，這當然違背了 API 優先原則，並且不受任何 RAML 實用程式的支援。
有一次我們開始使用 RAML 作為更靈活的語言，因此我們必須自己做很多事情。 例如，其中一個項目使用實用程式 在單元測試中，僅支援 RAML 0.8。 因此我們必須添加拐杖，以便該實用程式可以「吃掉」RAML 1.0 版本。
需要選擇嗎？
在致力於完成 RAML 解決方案的生態系統之後，我們得出的結論是，我們需要將 RAML 轉換為 Swagger 2，並在其中進行所有自動化、驗證、測試和後續優化。 這是利用 RAML 的靈活性和 Swagger 的社群工具支援的好方法。
為了解決這個問題，有兩個開源工具應該提供合約轉換：
- 是目前不受支援的實用程式。 在使用它時，我們發現它存在許多與「分佈」在大量文件上的複雜 RAML 相關的問題。 程式用 JavaScript 編寫，並執行語法樹的遞歸遍歷。 由於動態類型，要理解這段程式碼變得很困難，因此我們決定不浪費時間為垂死的實用程式編寫補丁。
- - 來自同一家公司的工具，聲稱可以在任何方向上轉換任何東西。 迄今為止，已宣布支援 RAML 0.8、RAML 1.0 和 Swagger 2.0。 然而，在我們研究時，效用仍是 潮濕且無法使用。 開發人員創建了一種 ，使他們能夠在未來快速添加新標準。 但到目前為止還行不通。
這還不是我們遇到的所有困難。 我們管道中的步驟之一是驗證儲存庫中的 RAML 相對於規格是否正確。 我們嘗試了幾種實用程式。 令人驚訝的是，他們都在不同的地方、用完全不同的髒話咒罵我們的註解。 而且並不總是切中要點:)。
最後，我們選擇了一個現已過時的項目，該項目也存在許多問題（有時它會突然崩潰，在使用正規表示式時出現問題）。 因此，我們沒有找到一種方法來解決基於免費工具的驗證和轉換問題，並決定使用商業實用程式。 未來，隨著開源工具變得更加成熟，這個問題可能會變得更容易解決。 同時，「完成」的勞動力和時間成本對我們來說似乎比商業服務的成本更重要。
結論
畢竟，我們想分享我們的經驗，並指出，在選擇描述合約的工具之前，您需要明確定義您想從中獲得什麼以及您願意投入多少預算。 如果我們忘記開源，已經有大量的服務和產品可以幫助您檢查、轉換和驗證。 但它們很昂貴，有時甚至非常昂貴。 對於大公司來說，這樣的成本是可以忍受的，但對於新創公司來說，它們可能會成為一個很大的負擔。
確定您稍後將使用的工具集。 例如，如果您只需要顯示合同，那麼使用 Swagger 2 會更容易，它具有漂亮的 API，因為在 RAML 中您必須自己建置和維護服務。
你的任務越多，對工具的需求就越廣泛，而且不同平台的工具也不同，最好立即熟悉可用的版本，以便做出將來成本最小化的選擇。
但值得注意的是，當今存在的所有生態系統都是不完美的。 因此，如果公司裡有粉絲喜歡在RAML工作，因為“它可以讓你更靈活地表達想法”，或者相反，更喜歡Swagger，因為“它更清晰”，那麼最好讓他們繼續工作他們已經習慣了並且想要它，因為任何格式的工具都需要使用文件進行修改。
至於我們的經驗，在接下來的文章中，我們將討論我們基於 RAML-Swagger 架構進行哪些靜態和動態檢查，以及我們從合約中產生哪些文檔，以及它們是如何運作的。
只有註冊用戶才能參與調查。 ， 請。
您使用什麼語言來註釋微服務契約？
-
隨機存取記憶體0.8
-
隨機存取記憶體1.0
-
招搖2
-
OAS3（又稱）
-
藍圖
-
其他
-
不使用
100 位用戶投票。 24 名用戶棄權。
來源： www.habr.com