記得點擊上方“雲原生之路”關注哦

OpenAPI

熟悉公有云的同學對 OpenAPI 都不會陌生，OpenAPI 可以稱之為公有云與用戶之間的一座橋樑。直接使用公有云的大多是技術人員，而對於技術人員，尤其是開發者來說，往往並不滿足於只使用 Web UI 界面來與公有云交互，尤其是當使用的公有云產品日益增多時。由於 Web UI 是面向全體用戶設計，並不能滿足用戶的全部需求。這時 OpenAPI 就出現了，用戶通過 OpenAPI 將自己的系統直接對接公有云，並根據自己的使用場景和需求進行設計，開發出一套滿足自己需求的公有云管理系統或流程，這樣既提高了用戶本身的自動化水平，還降低了誤操作帶來的風險。

背景

最早的 OpenAPI 往往是雲廠商開放出來的一系列 RESTful API 接口，用戶需要根據接口要求自己封裝認證方法、傳入參數，但是由於部分 OpenAPI 並不是 RESTful 風格、產品升級導致的接口參數變化、文檔更新不及時等問題，導致雲廠商開始尋求新的解決辦法。SDK 就是一種解決辦法，通過雲廠商自己封裝的 SDK，可以提高用戶體驗並屏蔽部分直接使用 OpenAPI 帶來的麻煩，但是隨著雲產品的增加，需要開發的 SDK 越來越多，並且由於 SDK 往往是多語言的，雲廠商需要投入大量人手來維護這些 SDK，導致某些產品由於人力資源有限並沒有提供 SDK 或者 SDK 語言不全。

在這種背景下，阿里雲的同學提出了一種新辦法：他們重新定義了一門 DSL 語言 Darabonba 來描述各種各樣的 OpenAPI，就如題目所說給 OpenAPI 開發了一種編程語言，從某種程度上來說，可以稱之為：OpenAPI as code。

Darabonba

Darabonba(原名 TeaDSL)，是一種 OpenAPI 應用的領域特定語言。可以利用它為任意風格的接口生成多語言的 SDK、代碼示例、測試用例、接口編排等。

在筆者看來，操作雲產品的功能是開發者的目的，而 OpenAPI 是實現這個目的的手段，SDK 則簡化了這種手段，Darabonba 的作用則降低了開發 SDK 的成本，並提高了開發 SDK 的速度，對雲廠商的效率會有非常明顯的提升。同時 Darabonba 也為使用多種編程語言的團隊提供了一條捷徑，原先需要每種編程語言都要出人來參加 OpenAPI 的集成，現在只需要公有云維護團隊出一名或幾名同學即可完成全語言 SDK 的生成。而如果公司本身有需要開發大量的 OpenAPI，甚至可以直接使用 Darabonba，開發符合自己系統 OpenAPI 的工具，Darabonba 目前已經開源，使用 Apache-2.0 LICENSE。

組件

Darabonba 目前支持：Java、C#、TypeScript、PHP、Golang 和 Python 代碼的生成，除了解析器和多語言生成器，還提供了：

• VS Code 插件：提供語法高亮、代碼提示、代碼格式化、語法檢查等功能。
• CLI：命令行工具，快速在本地拉起一個 Darabonba 項目。
• Darabonba 模塊倉庫：模塊倉庫，提供 Darabonba 模塊的發佈和下載。

Darabonba 語言優勢

• 更寬泛的風格支持：支持 RESTful 風格的 OpenAPI，及其他所有基於 HTTP 協議的 OpenAPI。對非 RESTful 風格的 OpenAPI 更友好。
• 編程邏輯化：將 OpenAPI 從元數據定義走向編程化，封裝複雜的 HTTP 處理過程為簡單的方法接口。
• 運行時事務性支持：支持配置或設置 OpenAPI 的冪等、重試、超時、退避，將複雜的 OpenAPI 調用過程收斂在方法中。

快速上手

下圖可以看到完整的 Darabonba 運行流程，現在我們就來快速製作一套 Code Sample 吧。

安裝

阿里雲提供了Darabonba 的 Web UI 界面，但是在網頁上不好調試，我們選擇本地安裝 CLI 命令行工具。

# Darabonba CLI 是由 Node.js 開發的，使用 npm 來安裝
$ npm install -g @darabonba/cli

構建 Darabonba 模塊

我們假設要創建一個模塊為 sample_ecs，用來生成查詢 ECS 信息的 SDK 代碼。首先創建一個目錄：

$ mkdir sample_ecs
$ cd sample_ecs

初始化模塊，輸入相關信息：

$ dara init
package scope: guoxudong.io
package name: sample_ecs
package version: 0.0.1
main entry: main.dara

完成初始化後，會新建 2 個文件：

• Darafile：包描述文件
• main.dara：入口文件

安裝 VS Code 插件

打開 VS Code，按 F1 或 Ctrl + Shift + P 打開命令面板，選擇 Install Extension 並輸入 darabonba。

或啟動VS Code 快速打開（Ctrl + P），粘貼以下命令，然後按 Enter。

ext install darabonba.darabonba

之後就可以使用語法高亮、代碼提示、代碼格式化、語法檢查等功能了。

安裝依賴模塊

首先需要設置依賴倉庫地址：

$ dara config set registry https://darabonba.api.aliyun.com

之後就是將依賴寫入 Darafile 中：

{
  "scope": "guoxudong.io",
  "name": "sample_ecs",
  "version": "0.0.1",
  "main": "main.dara",
  "libraries": {
    "Console": "darabonba:Console:*",
    "ECS": "alibabacloud:Ecs20140526:*",
    "RPC": "alibabacloud:RPC:*",
    "Util": "darabonba:Util:*"
  },
  "java": {
    "package": "aliyun.com.alibabacloud.sample"
  },
  "csharp": {
    "namespace": "Alibabacloud.Sample"
  },
  "php": {
    "package": "Alibabacloud.Sample"
  },
  "python": {
    "package": "alibabacloud_sample"
  }
}

這裡引入了4個模塊：

• Console：打印輸出模塊
• ECS：ECS 模塊
• RPC：RPC Client 模塊
• Util：工具模塊

值得注意的的是 libraries 中內容的 key，就是 .dara 文件中 import 導入依賴的名稱，所以這裡可以將 key 修改為好理解的值，然後 import 相應值就可以了。

修改完 Darafile 之後，安裝這些依賴：

$ dara install

之後就可以看到多了一個 .libraries.json 文件和一個 libraries 目錄，需要的所有依賴模塊就都已經安裝好了。

查看模塊內容

更多的模塊，可在模塊倉庫中搜索。這裡以 ECS 模塊為例

可以在 Detail 中看到所有可以調用的接口，通過還可以點擊其他 tab 可以查看版本、安裝方法等內容：

也可通過命令單獨安裝模塊：

$ dara install alibabacloud:Ecs20140526

代碼編寫

現在就可以編寫 Darabonba 代碼了，Darabonba 代碼的整體風格偏向於 Java，不是很難懂，這裡貼上一段簡單的代碼：

import ECS;
import RPC;
import Util;
import Console;

/**
* Initialization  初始化公共請求參數
*/
static function Initialization(regionId: string)throws : ECS{

    var config = new RPC.Config{};
    // 您的AccessKey ID
    config.accessKeyId = "<accessKeyId>";
    // 您的AccessKey Secret
    config.accessKeySecret = "<accessKeySecret>";
    // 您的可用區ID
    config.regionId = regionId;

    return new ECS(config);
}

/**
* DescribeZones    查詢一個阿里雲地域下的可用區
*/
static async function DescribeZones(client: ECS, regionId: string)throws: void{
    var req = new ECS.DescribeZonesRequest{};
    // 可用區所在的地域ID。您可以調用DescribeRegions查看最新的阿里雲地域列表
    req.regionId = regionId;
    // 根據漢語、英語和日語篩選返回結果。更多詳情，請參見RFC7231
    // 取值範圍：
    // zh-CN
    // en-US
    // ja
    // 默認值：zh-CN。
    req.acceptLanguage = "zh-CN";
    var resp = client.describeZones(req);
    Console.log("--------------------查詢地域下的可用區--------------------");
    Console.log(Util.toJSONString(resp));
}


static async function main(args: [string]) throws: void {
    // 可用區域Id （請自行配置）
    var regionId = "<regionId>";

    var client = Initialization(regionId);

    // 查詢阿里雲地域下的可用區
    DescribeZones(client, regionId)
}

這個代碼註釋很完善，這裡就不多講解了，本示例在官網有完整示例，有興趣的同學可以研究一下。而 Darabonba 的文檔，可以在 Github 上找到。

代碼生成

現在就可以生成代碼了，下面以生成 Python 代碼為例，執行命令：

$ dara codegen python ./tmp

命令執行成功後，就可以看到 Python 代碼已經生成了：

如果代碼還沒有寫完，想檢查是否有語法錯誤，可以使用 check 命令檢查：

$ dara check main.dara
Check success !

到這我們的代碼就生成成功了，但是這還不是結束，我們需要去測試一下生成的代碼能否正常運行，在實踐中就出現過代碼生成成功，但是運行報錯的情況。

如果生成的是 Python 代碼，這裡推薦使用 Python 3.6，經測 3.8 版本不支持 sdk 的一些語法。

同樣的，也可以在 OpenAPI Explorer Code Sample，通過 Web UI 來生成代碼，除了調試速度比較慢之外，其餘體驗都十分不錯。

Code Sample 全民賽碼

最近阿里雲還推出了這麼一個比賽，看了下獎品有機械鍵盤、無人機、雙肩包和內推資格，有興趣的同學可以關注一下，還是挺好玩的：傳送門

阿里雲開放平臺攜手開發者社區、內容設計部，聯合舉辦“OpenAPI 開發者挑戰賽第三期—— CodeSample 全民賽碼 ”，面向數萬開發者，招募阿里雲 OpenAPI 示例代碼（CodeSample）。無論您是入門開發，或是運維大神，無論是利用 OpenAPI 解決一個輕量場景，或是滿足一個小功能，通通到碗裡來！

結語

在這個項目叫 TeaDSL 的時候筆者就開始關注 Darabonba 了，由於筆者是 OpenAPI SDK 的重度使用用戶，之前開發的 devops 平臺以及 cms-grafana-builder 項目都大量使用了阿里雲 SDK。在4月份看到樸靈的《TeaDSL：支持任意 OpenAPI 網關的多語言 SDK 方案》時，認為其只是解決雲廠商 OpenAPI 開發的多語言困局，提升研發效率，和 OpenAPI 的使用者關係不大。但是在這次進行深入研究之後發現，Darabonba 甚至可以用來生成自己系統的 OpenAPI 多語言 SDK，並不是只能用於生成阿里雲的 SDK，非常的驚豔。