听说,阿里云给它的 OpenAPI 开发了一套编程语言

记得点击上方“云原生之路”关注哦

听说,阿里云给它的 OpenAPI 开发了一套编程语言

OpenAPI

熟悉公有云的同学对 OpenAPI 都不会陌生,OpenAPI 可以称之为公有云与用户之间的一座桥梁。直接使用公有云的大多是技术人员,而对于技术人员,尤其是开发者来说,往往并不满足于只使用 Web UI 界面来与公有# ` P云交互,尤其是当使用的公有云产品日益增多时。由于 Web UI 是面向全体用户设计,并不能满足用户的全部需求。这时 OpenAPI 就出现了,用户通过 OpenAPI 将自己的系统直接对接公有云,并根据自己的使用场景和需求进行设计,开发出一套满足自己需求的公有云管理系` S - 3 j 4 )统或流程,这样既提高了用户本身的自动化水平,还降低了误操作带来的风险。

背景

最早的 OpenAPI 往往是云厂商开放出来的一系列 RESTful API 接口,用户需要根据接口要求自己封装认证方法、传入参数,p k 4 Z但是由于部分 OpenAPI 并不是 RESTful 风格、产品升级导致的接口参数变化、文档更新不及时等问题,导致云厂商开始寻求新的解决办法。SD$ Y ] g ) ( V :K 就是一种解决办法,通过云厂商自己封装的 SDK,L O 3 5 = j可以提高用户体验并屏蔽部分直接使用 OpenAPI 带来的麻烦,但是随着云产品H { 3 3 _的增加,需要开发的 SDK 越来越多,并且由于 SDK 往往是多语言的,云厂商需要投入大量人手来维护这v $ S l Y ! s s些 S * c z -DK,导致某些产品由于人力资源有限并没有提g u 0供 SDK 或者 SDK 语言不全。

在这种背景下,阿里云的同学提出了一种新办法:他们重新定义了一门 DS$ z M {L 语言 Darabonba 来描述各种各样的 OpenAPI,就如题目所说给 OpenAPI 开发了一种编程语言,从某种程度上来说,可以称之为:OpenAPI as code

Darabonba

Darabonba(原名 TeaDSL),是一种 OpenAPI 应用的领域特定语言。可以利用它为任意风格的接口R r a生成多语言的 SDK、g { O * 9 @ ; 6 A代码示例、测试用例、R y p m V ! p # =接口编排等。

听说,阿里云给它的 OpenAPI 开发了一套编程语言

在笔者看来,操作云产品的功能是开发者的目的,而 OpenR 1 k 3 WAPI 是实现这个目的的手段,SDK 则简化了这种手段,Darabonba 的作用则降低了开发 SDK 的` M u W N C /成本,并提高了开发 SDK2 n } & & u e 的速度,对云厂商的效率会有非 W l c ^ f g ; O常明显的提升。同时 Darabonba 也为使用多种编程语言的团队提供了一条捷径,原先需要每种编程语言都要出9 2 Q g J )人来参加d t 5 4 P OpenAPI 的` e z 9 6 P A } E集成,现在只需要公有云维护团队出一名或几名同学即可完成全语言 SDK 的生成。而如果公司本身有需要开发大量的 OpenAPI,甚至可以直接使用 Darabonba,开发符合自己系统 OpenAPI 的工具,Darabonba 目前已经开源,使用 Apache-2.0 LIN K & J k A -CENSE。

组件

Darabonba 目前支持:JavaC#TypeScriptA B 1 $ MPHPGolangPython 代码的生# 1 [ o h t { ! G成,除了解析器和多语言生成器,还提供t 4 H /了:

  • VS Code 插件:提供语法高亮、代码提示、代码h * u 0 D Q y 1 /格式化、语法检查等功r r 2 #能。
  • CLIE c 1 5 S:命令行工具,快速在本地拉起一个 Darabonba 项目。
  • Darabonba 模块仓库:模块仓库,提供 Darabonba 模块的发布和下载。

Darabonba 语言优势

  • 更宽泛的风格支持:支持L D O p RESTful 风格的 OpenAPI,及其他所有基^ 4 { $ a u U于 HTTP 协议的 OpenAPIH j {。对非 RESTful 风格的 OpenAPI 更友好。
  • 编程逻辑化:将z t $ M 7 F A s OpenAPI 从元数据定义走向编程化,封装复杂的 HTTP 处理过程为a g C 8 O ] i , @简单的方法接口。
  • 运行时事务性支持:支持配置或设置 OpenAPI 的幂等、重试、超时、退避,将复杂的 OB 0 } Q k d I 2penAPI 调用过程收敛在方法中。

快速上手

下图可以看Y S :到完整的 Darabonba 运行流程,现在我们c 4 q : H V就来快速制作一套 Code Sample 吧。

听说,阿里云给它的 OpenAPI 开发了一套编程语言

安装

阿里云提供了M 1 Y $Darabonba 的 Web UI 界面,但是在网页上不好调试,我们选择本地安装 CLI 命令行工具。

# Darap 2 ;bonba CLI 是由 Node.js 开发的,使用 npm 来安l g @装
$ npm install -g @dar1 t u m [ 8abonba/cli

构建 Darabonba 模块

我们假设要创建一个模块为 sample_ecs,用来生成查询 ECS 信息的 SDK 代码。首先创建一个目录:

$ mkdir sample_ecs
$ cd sample_ecs

初始化模块,输入相关信息:

$ dara init
pacM y d ) z f @kage scope: guoxudong.io
package name: sample_ecs
package version: 0.0.1
main entry: main.dara

完成初始化后,会新建 2 个文件:

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

安装 VS Code 插件

打开 VS Code,按G k . m F1Ctrl + Shift + P 打开命令面板,选? ` q D p q 择 Install Extension 并输入 darabonba

A q ] O 4 E启动VS CodeE E , h ) 9 _ r 快速打开(Ctrl + P),粘贴以下命令,然后按 Enter。

ext install darabonba.darabon= q y t H U } O vba

之后就可以使用语法高亮、代码提示、代码格式化、语法检查等功能了。

听说,阿里云给它的 OpenAPI 开发了一套编程语言

安装依赖模块

首先需要设置依赖仓库地址:

$ dara config set registry htt= g 8 % S h f !ps://darabonba.api.aliyun.ct $ A Q ( 5om

之后就是将依赖写入 Darafile 中:

{
"scope": "guoxudong.io",
"name": "sample_ecs",
q c J * , P t H I"versi! o )on": "0.0.1",
"main": "main.dara",
"librS H baries": {
"Console": "darabonba:Console:*",
"ECS": "alibabacloud:Ecs20140526:*",
"RPC": "alibabacloud:RPC:*",
"Util": "darabonba:Util:*"
},
"java":v ~ n # i 2 P & u {
"package": "aliyun.comG 2 8 $ } W.alibaba# 4 Ecloud.sample"
},
"csharp": {
"namespaM   9 ? 5 ]ce": "Alibabacloud.Sample"
},
"php": {
"package": "Alibabacloud.Sample"
},
"pytho; u { g x N q }n"i : % p H: {
"package": "alibabac) ( :loud_sample"
}
}

这里引入了4个模块:

  • Co7 o )nsol* | 1 xe:打印输出模块
  • ECS:ECS 模块
  • RPC:RPC Client} . [ E 模块
  • Util:工具模块

值得注意的的是 libraries 中内容的 key~ ^ P [ | I c C,就是 .dara 文件中 import 导入依赖的名称,所以这里可以将 key 修改为好理解的值,然后 import 相应值就可以了。g R h )

修改Darafz 8 F } q :ile 之后,安装这些依赖:

$ dara install

之后就可以看到多了一个 .libraries.jh H j e m *son 文件和一个 librari[ J =es 目录,需要的所9 2 { A i q 4 v T有依赖模块就都已经安装好了。

查看模块内容

更多的模块,可在模块仓库中搜索。这里以 ECS 模块为例

听说,阿里云给它的 OpenAPI 开发了一套编程语言

可以在 Dq ! y petail 中看到所有可以调用的接口,通过还可以点击其他 tab 可以查看版本、安装方法等内容:

听说,阿里云给它的 OpenAPI 开发了一套编程语言

也可通过命令单独安装模块:

$ dara install alibabacloud:Ecs2H ) v C N c N0140526

代码编写

现在就可以编写 Da} $ ] ^ ? =rabonba 代码了,Darabonba 代码的整体风格偏向于 JavQ Y G L z ja,不是很难懂,这里贴上一段简单的代码:

import ECS;
import RPC;
import Util;
import Console;
/**
* Initialization  初始化公共请求参数
*/
static function Initialization(regionId: string)throws : ECS{
var config = new RPC.Cons 8 ]fig{};
// 您的AccessKey ID
config.accessKeyID | T Md = "<accessKeyId>";
// 您的AccessKee % A 6 W , x My Secret
config.acceW % TssKeySecret = "<accessKeySecret>";
// 您的可用- a q b 9 E P区ID
config.regionId = regionId;
return new ECS(con1 z r h c & 7fig);
}
/**
* DescribeZones    查询一个阿里云地域下的可用K N 1 _ U (区
*/
static async function DescribeZones(clien_ 8 ) ht: ECS, regionId: string)throws: void{
var re& Q ? % % Uq = new ECS.Desl # ` o R 1 z fcribeZonesRequest{};
// 可用区所在的地域ID。您可以调用DescribeRegions查看最新的阿里云地域列表
req.regionId = regionId;
// 根据汉语、英语和日语筛选返回结果。更多详情,请参见RFC7231
// 取值范围:
//D p I + 6  ~ m zh-CN
// en-US
// ja
// 默认值:zh-CN。
req.acceptLanguage = "zh-CN";
var resp = client.describeZones(req);
Console.log("--------------------查询地域下的可用区--------------------");
Console.log(UtilF @ 3 ~.toJSONString(resp));
}
static async function main(args: [string]) throws: voih * o ~ . h N S &d {
// 可0 , X用区域Id (请自行配置)
var regionId = "<regionId&b ) fgt;"B b h y @ k +;
var client = Initialization(regionId)= ! d S O K;
// 查/ r Y m ? . 2 F询阿里云地域下的可用区
DescribeZones(client, regionId)
}

这个代码注释很完善,这里d g G % ~ : 4 x `就不多讲解了,本示例在官网有完整I o { H C示例,有兴趣的同学可以研究一下。而 Darabonba 的文档,可以在 Github 上找到。

代码生成r e m

现在就可以生成代码了,下面以生成 Python 代码为例,执行命令:

$ dara codegen python ./tmp

命令执行成功后,就可以看到 Python 代码已经生成了:

听说,阿里云给它的 OpenAPI 开发了一套编程语言

如果代码还没有写完,想检查是否有语法错误,可以使用 check8 A Y 命令检查:

$ dara check mainA + T E 2.dara
Check success !

到这我们的代t | i 5 W F G ! k码就生成成功了,但是这还不是结束,我们需要去测试一下生成的代码能否正常运行,在实践中就出现过代码生成成功,但是运行报错的情况。

如果生成的是 Python 代码,这里推荐使用 Python 3.6,经测 3.8 版本不支持 sdk 的一些语法。

同样的,也可以在 OpenAPI Explorer Code Sample,通过 Web UI 来生成代码,除了调试速度比较慢之外,其余体验都十分不错。

听说,阿里云给它的 OpenAPI 开发了一套编程语言

Code Sample 全民赛码

最近阿里云还推出了这么一个比赛,看了下奖品有机械键盘、无人机、双肩包和内推资格,有兴趣的同学可以关注一下,还是挺好玩的:传送门

听说,阿里云给它的 OpenAPI 开发了一套编程语言

阿里云开放平台携手开发者社区、内容设计部,联合举办“OpenAPp h S ~ 6 x 1 X bI 开发者挑战赛第三期—— CodeSample 全民赛码 ”,面向数万开发者,招募阿里云 Opl 2 9 s B [enAPI 示例代码(CodeSample)。无论您是入门开发,或是运维大神, B = v & )无论是利用 OpenAPI 解决一个轻量场景,或是满足一个小功能,c s B通通到碗里来!

结语

在这个项目叫 TeaDSL 的时候笔者就开始关注 Darabonba 了,由于笔z L 6 t者是 OpenAPI SDK 的重度使用用户,之前开发的 devops 平台以及 cms-grafana-; L ybuilder 项目都大量使用了阿里云 SDK。在4月份看到y { Q ? l R H R朴灵的《TeaDSL:支持任意 OpenAPI 网关的多语言 SDK 方案》时,认为其只是解决云厂商 OpenAPI 开发的多语言困局,提升研发效率,和 OpenAPI 的使用者关系不大。但是在这次进行深入研究之后发现,Darabonba 甚至可以用来生成自己系统的 OpenAPI 多语言 SDK,并不是只能用于生成阿里云的 SDK,非常的惊艳。

听说,阿里云给它的 OpenAPI 开发了一套编程语言