現在 OpenAPI 已經成爲完成系統之間集成的重要橋樑，OpenAPI 的可用性以及用戶在使用時的體驗就變得愈來愈重要，阿里雲前架構師曾說過："阿里雲的本質是一家賣 API 的公司。API 有沒有作好，是關乎生死的大事"。可是從平常來自用戶的反饋中咱們總結了如下比較通用的幾點 OpenAPI 體驗問題：git
- 雲產品 OpenAPI 沒有提供 SDK 或者 SDK 語言不全；
- 部分雲產品的 SDK 使用風格差別過大，致使使用成本增長；
- API 文檔缺失或者不夠清晰，不具有指導意義；
- 沒有場景化 Code Sample 或提供 CodeSample 沒法運行。
多語言 SDK 生成
提及生成多語言 SDK，你們第一時間想起的必定是當前業界內生成多語言 SDK 的通用方案——Swagger，開發者經過 Swagger 定義的 OpenAPI 標準並配合模板的方式來生成多語言 SDK。不過問題並無所以而獲得完美的解決。首先模版的生成方式相對生硬，雖然實現起來容易，但維護起來卻不那麼靈活；其次，大量 OpenAPI 並非 RESTful 風格的，這就致使不少產品現存的 OpenAPI 在文檔、SDK 等場景下，沒法使用上 Swagger 這樣強大的生態工具鏈。既然沒法沿用 Swagger 規範元數據的方法來解決這個問題，咱們就須要對咱們的工做從新進行抽象。在筆者看來，之因此沒有一套元數據能夠適用於全部的網關主要仍是由於每一個網關所對應的後端狀況不一樣，就像機器語言或者彙編語言會由於架構的不一樣而有所不一樣，可是其本質仍是描述如何經過操做寄存器、內存裏的數據來完成一個程序，高級語言就是經過 AST 兼容了各平臺的這些不一樣最後解決了這些問題。而對於 OpenAPI 來講也是一樣的道理，因此咱們經過從新定義一門 DSL 語言 Darabonba 來描述各類各樣的 OpenAPI。github
經過 Darabonba 對 OpenAPI 進行描述，其本質就是統一了元數據，只是這個元數據並非 JSON 或者 Yaml 這樣的方式來描述的，而是經過 DSL 代碼來描述。Darabonba 的編譯器則會將 Darabonba 的 DSL 代碼轉化爲 AST，經過 OpenAPI 描述轉化而來的 AST 不只包含了 OpenAPI 的信息，並且還包含整個 OpenAPI 的流程性描述，因此咱們只須要經過 AST 開發對應的各語言SDK就能夠生成多語言的 SDK了。Darabonba 具體的設計思路和理念可參考文章：Darabonba：支持任意 OpenAPI 網關的多語言 SDK 方案，這裏就再也不贅述。後端
模塊化設計
在經過元數據向生成 SDK 的過程當中，僅僅經過對 OpenAPI 的數據模型和請求/響應描述是不夠的，還須要各類參數處理，簽名生成，文件上傳，流操做等各類複雜的方法，以往經過模板生成 SDK 的時會選擇維護一個各語言的核心模塊來封裝這些方法，可是隨着支持的 OpenAPI 愈來愈多核心庫中的方法也是愈來愈多，就會產生如下的問題：api
- 客戶使用或者開發者接入核心庫的 SDK 開發者來講成本會愈來愈大；
- 核心庫的維護人員的維護成本也會愈來愈高，隨着方法愈來愈多也須要不斷的對核心庫進行重構，遇到不兼容性改動的可能性也會愈來愈高；
- 全部方法雜糅在一個核心庫中，在修改時容易牽一髮動全身，須要大量的測試用例保障。
在經過 Darabonba 生成的 SDK 時也會遇到一樣的問題，Darabonba 做爲一門 DSL 語言主要能力在於描述 OpenAPI ，爲了保障生成的 SDK 具有完整的功能一樣須要不少實現不少核心方法，而在總結以往維護核心庫的中遇到的問題之後，咱們選擇瞭如今在高級語言中很是常見的模塊化開發理念，並提供了相應的命令行工具 Darabonba CLI 和 Darabonba 模塊倉庫。架構
接口模塊
Darabonba 其核心能力是描述 OpenAPI，缺乏複雜邏輯實現的能力，爲了彌補這個能力 Darabonba 設計了接口模塊的概念。與 Java 中的 interface 接口類型定義相似，Darabonba 的接口模塊便是隻在 Darabonba 編寫的DSL 代碼中只定義方法體的集合而並不實現其具體邏輯，真正的邏輯則是由各語言分別實現。例如 Darabonba 中經常使用的 Console 模塊：併發
咱們只須要在模塊中申明模塊包含 log 方法並描述它的出參入參便可，而各語言則經過自身語言的特性來實現該方法便可，其具體實現可參考 Console 模塊源碼。在編寫好生成接口模塊之後能夠經過 Darabonba 提供的 Darabonba CLI 執行 dara publish 將模塊發佈到 Darabonba 模塊倉庫，就能夠在 Darabonba 代碼中使用了。下面就是咱們經過引入 Console 模塊來打印字符串的一段代碼：模塊化
經過接口模塊的設計理念將以往核心庫中的方法根據功能拆分紅一個個包含了特定功能的基礎模塊，不只使得生成的 SDK 更好用邏輯更清晰，同時也作到了足夠的抽象避免不少在生成 SDK 過程當中重複造輪子的工做。目前 Darabonba 官方提供了包含了經常使用方法的 Util 模塊、文件上傳所使用的 FileForm 以及 XML 模塊等，同時開發者也能夠編寫與本身業務邏輯相關的接口模塊併發布到 Darabonba 模塊倉庫。工具
OpenAPI 模塊
在 Darabonba 的模塊化設計中不止有接口模塊，事實上每個 Darabonba 的項目都是一個模塊，因此基於一組 OpenAPI 描述編寫的 Darabonba 代碼就是一個 OpenAPI 模塊。開發者在完成了 OpenAPI 描述的 Darabonba 代碼編寫之後，一樣能夠經過 Darabonba CLI 將描述 OpenAPI 的 Darabonba 模塊發佈到模塊倉庫中，這樣使用 SDK 的用戶就能夠經過模塊的詳情頁面查看 SDK 中包含的方法及各語言 SDK 的安裝說明等信息了。測試
基於一組 OpenAPI 發佈的 Darabonba 模塊不只能夠幫助用戶更好的瞭解這組 OpenAPI，更能夠在這個基礎上實現 OpenAPI 接口的 Code Sample 編寫，進而實現多語言的 Code Sample 統一輩子成。阿里雲
Code Sample 自動生成
能夠說對於簡單的 API 調用普通的 API 文檔就足夠了，可是隨着如今 OpenAPI 在系統與系統集成之間使用的愈來愈普遍，其複雜度也隨之提升，以往單純使用 API 文檔的方式已經不足以讓客戶順利的使用 OpenAPI 了。從阿里雲目前的工單狀況來看，SDK 相關的客戶諮詢至少有一半是由於沒有 Code Sample 形成的，其中更是有1/4的客戶是直接要求爲 SDK 提供 Code Sample。
這種狀況下，可以提供給用戶可運行、可調試的 Code Sample 示例就成了文檔中必不可少的一部分，可是如何可以編寫全語言的 Code Sample 而且保障其可運行，倒是一個極大的問題。若是經過人力來維護，很容易就出現語言不全，或是編寫的代碼沒有維護的問題，阿里雲中遇到最多的問題就是 OpenAPI 在迭代，而 Code Sample 卻忘記迭代了形成了提供出去的 Code Sample 沒法使用從而被用戶詬病。
經過引用模塊倉庫中 Darabonba 模塊編寫的 CodeSample 則能夠避免這樣的問題，首先多語言的自動生成，節約了大量的維護成本，並且風格統一利於用戶理解；同時 Darabonba 編譯時採用類型的強校驗，一旦 OpenAPI 的參數或者返回結果出現了不兼容的更新，CodeSample 則會生成失敗從而通知到開發者更新相關示例來解決這個問題。下面是阿里雲語音服務 SDK 相關的 CodeSample 示例，你們也能夠點擊示例連接嘗試生成：
Test Cases 自動生成
在 OpenAPI 公佈上線之後，如何可以保障 OpenAPI 持續可用就是一個很是重要的問題，若是沒有一個保障機制，極可能會出現 OpenAPI 出了問題就沒法及時發現，客戶的投訴也就隨之而來。並且 OpenAPI 和 SDK 也會遇到更新升級等狀況，如何能保障這些更新升級不會給正在使用 OpenAPI 的客戶形成問題也是 OpenAPI 提供方遇到的一個很是大的挑戰。爲了解決這些挑戰， 就須要 OpenAPI 提供方編寫 Test Cases 做爲平常的持續集成來檢驗 OpenAPI 的可用性，可是目前多語言的 SDK 的 Test Cases 大多存在如下的問題：
- 須要大量的人力去維護 Test Cases ，並且沒法保障全部語言的 SDK 都擁有 Test Cases；
- OpenAPI 的 Test Cases 少且更新頻率低，形成了對 OpenAPI 的覆蓋面低而沒法起到有效的保障做用；
- 各語言 SDK 的由各語言的開發同窗分別維護，因此用例不一樣步致使不一樣語言之間的測試結果有所差別。
而Darabonba 的多語言生成能力則能夠解決以上全部問題，只須要引用 SDK 在模塊倉庫中對應的 Darabonba 模塊與 Darabonba 官方提供的斷言模塊 Assert 模塊編寫對應的 Darabonba Test Cases 便可爲各語言 SDK 生成其對應的 Test Cases。經過 Darabonba 自動化生成 Test Cases 不只能夠解決人力不足 Test Cases 很難覆蓋各語言 SDK 的狀況，並且生成的各語言 Test Cases 標準一致，也能夠解決各語言 Test Cases用例不一樣步形成的測試差別問題。下面是一段經過 Darabonba 編寫的測試用例：
Darabonba 的主要能力是支持到不一樣風格的 OpenAPI，同時支持多語言的 SDK、Code Sample 目標生成。最終的目的仍然是打通從 OpenAPI 定義到文檔、到 SDK、CLI 等 OpenAPI 使用場景下的一致性。提供給用戶更統1、專業、一致的使用體驗。同時也大幅下降 OpenAPI 提供者用來支持用戶的成本，經過自動化的方式，節省精力的同時，還可減小人爲參與時致使的錯誤。
參與貢獻
Darabonba 的目標是讓用戶獲得極致的 OpenAPI 體驗，因此咱們也須要更多的人蔘與到咱們的開源項目來，你們能夠按之前的方式參與 Darabonba 的貢獻：
- 參與其餘語言生成器的生成，目前 Darabonba 只支持了比較經常使用的六門語言，還須要更多生成器的支持。
- 編寫更多底層工具模塊，使 Darabonba 可以生成更便捷的 SDK。
- 參與 Darabonba 編譯器及 CLI 工具的建設中來。
- 編寫更多 OpenAPI 元數據轉換到 Darabonba 的工具。
相關閱讀