Darabonba 是阿里云致力于更好的描述 OpenAPI 而开发的特定领域编程语言，不仅可以兼容多网关、描述任意风格的 OpenAPI，并且可通过编写 Darabonba 的文件自动化生成多语言的 SDK，是节省开发成本的不二之选。由于 Darabonba 具备编程的灵活性，所以不仅能为 OpenAPI 生成 SDK 还可以通过 Darabonba 编写关于 SDK 中OpenAPI 使用的场景化 CodeSample，为 SDK 的使用者提供了最为实用的指导。本篇文章将通过三个示例循序渐进的帮助大家生成属于自己的 CodeSample。

如何创建 CodeSample 项目

首先，我们可以点击本次 Code Sample 全民赛码挑战赛的主页面，点击下面的快速开始：

这里没有登录的同学可能需要使用阿里云账号登录，在登陆成功后即可跳转到 CodeSample 项目创建页面，这里只需要填写本次 CodeSample 的项目标题和描述即可，其他的信息已经填写好了包括等会儿需要用的 Console 模块，在依赖库中也帮大家默认填写了，所以在输入了标题后描述后直接点击下一步就好了：

在第二步的页面中，可以看到下面编辑框中已经为大家准备好了一段可以生成各语言的初始代码，大家可以通过修改字符串并点击编辑框下方的查看生成代码来感受通过 Darabonba 生成的各语言代码，最后可以通过提交来保存这段代码：

在保存成功后，会跳转到我的示例列表页面中，通过点击下面的详情按钮，我们就可以进入这个 CodeSample 项目的详情页面了：

在详情页面中，我们可以通过编辑按钮，再次编辑我们之前用 Darabonba 编写的 Hello,World 文档，在编辑完成并成功保存后，就可以点击发布新版本的按钮将写好的 CodeSample 代码提交到 Code Sample 全民赛码参加评比了（评委会以每个项目的最后一次提交代码为准）。

使用 Darabonba 编写 CodeSample

Darabonba快速上手

Darabonba作为一门描述性语言，也有自己简单易用的语法，为了方便大家学习 Darabonba ，这里我们为大家提供了5分钟上手 Darabonba 指南和详细的 Darabonba 语言使用文档。而下面我们会通过两个示例为大家演示如何 Darabonba 编写 CodeSample 正确打开方式。

单个API的 CodeSample

当然，如果只是提交 Hello,World 文档是不能获得大赛奖品的，Darabonba 的 CodeSample 代码是为OpenAPI SDK 服务的，所以我们下面将通过为一个 OpenAPI 写CodeSample来为大家描写一个示例。
首先需要再新建一个API的项目，这里我们在依赖库中会加入我们将要编写 CodeSample 所对应的 SDK 模块，相关模块可以直接点击右侧边栏中的模块仓库，通过仓库可以寻找到云产品的 SDK 模块：

我们选取阿里云的短信服务的 SDK 模块 alibabacloud: Dysmsapi20170525 来编写其对应的CodeSample，首先我们进入模块的详情页面；在详情页面中，我们可以看到这个SDK 相关的一些跟 OpenAPI 请求相关的方法和定义了入参、出参的 Model。这里我们选取最为经典发送短信的 `
SendSms
方法来编写相关 CodeSample ，并可以点击其对应的入参类型 SendSmsRequest 和出参类型 SendSmsResponse` 来了解其如何使用，其中在入参中标记红星的为必选参数。

在对这个方法有一定的了解以后我们就接着来创建我们的项目，这次跟上次最大的区别就是：在依赖库中我们需要填入Dysmsapi20170525 相关的依赖。

而在下一步中，我们就可以在代码中使用到 SDK 相关的模块编写其 CodeSample了：

import Dysmsapi;
import RPC;
import Console;

// 使用AK&SK初始化账号Client  
static function createClient (accessKeyId : string , accessKeySecret : string , regionId : string) : Dysmsapi{
    var config = new RPC.Config{};
    config.accessKeyId = accessKeyId;
    config.accessKeySecret = accessKeySecret;
    config.regionId = regionId;

}

static async function main(args: [string]): void {
    var client = createClient("accessKeyId","accessKeySecret","regionId");
    var request = new Dysmsapi.SendSmsRequest{
        phoneNumbers= "13888888888",
        // 短信签名名称。请在控制台签名管理页面签名名称一列查看。  
        signName= "aliyun",
        // 短信模板ID。请在控制台模板管理页面模板CODE一列查看。
        templateCode = "SMS_153055065",  
    };
    var response = client.sendSms(request);
    Console.log(response.message);
}

通过查看生成代码，确定生成无误以后，我们就可以保存该 CodeSample 并通过上面介绍的在详情页面中直接点击发布新版本提交该 CodeSample 了。

完整的场景化 CodeSample

在了解了如何通过 Darabonba 的生态来编程实现多语言 CodeSample 以后，接下来我们就来做一件挑战的事情，就是通过组合多个 API 形成一个场景，这里我们以阿里云容器服务的 OpenAPI 为例实现一个，从创建集群->查看集群状态->扩容集群->查看集群节点状态->删除节点的示例。
首先还是新建一个项目，在依赖项中这次我们要用到仓库中容器服务相关的 SDK 模块:

通过引入对应的模块，我们就可以通过使用这些模块中对应的方法来实现上述的流程了，再加上相应的注释，一个完成的 CodeSample 示例就完成了，代码如下：

import CS;
import ROA;
import Util;
import Console;

/**
 * 使用AK&SK初始化账号Client
 * @param accessKeyId
 * @param accessKeySecret
 * @param regionId
 * @param endpoint
 * @return Client
 * @throws Exception
 */  
 static async function createClient (accessKeyId : string , accessKeySecret : string , regionId : string)throws : CS{
    var config = new ROA.Config{};
    // 您的AccessKey ID
    config.accessKeyId = accessKeyId;
    // 您的AccessKey Secret
    config.accessKeySecret = accessKeySecret;
    // 您的可用区ID
    config.regionId = regionId;
    return new CS(config);
}

/**
 * 创建集群
 * @param client
 * @return CreateClusterResponse
 * @throws Exception
 */
static async function createCluster (client: CS)throws :  CS.CreateClusterResponse{
    var createClusterRequestBody = new CS.CreateClusterBody{
      // 失败是否回滚
      disableRollback=true,
      // 集群名称
      name="my-test-Kubernetes-cluster",
      // 集群创建超时时间
      timeoutMins=60,
      // 集群类型，ManagedKubernetes
      clusterType="ManagedKubernetes",
      // 地域
      regionId="cn-beijing",
      // VPC ID
      vpcid="vpc-2zegvl5etah5requ0****",
      // 容器POD CIDR
      containerCidr="172.20.0.0/16",
      // 服务CIDR
      serviceCidr="172.21.0.0/20",
      // 是否开放公网SSH登录
      sshFlags=false,
      // 是否安装云监控插件
      cloudMonitorFlags=false,
      // 节点SSH登录密码，和key_pair二选一
      loginPassword="Test_1234",
      // Worker节点付费类型PrePaid|PostPaid
      workerInstanceChargeType="PostPaid",
      // Worker实例规格多实例规格参数
      workerInstanceTypes=["ecs.sn2.3xlarge"],
      // 一台或多台虚拟交换机 ID，N 的取值范围为 [1, 5]
      workerVswitchIds=["vsw-2ze48rkq464rsdts****"],
      // Worker系统盘类型
      workerSystemDiskCategory="cloud_efficiency",
      // Worker节点系统盘大小
      workerSystemDiskSize=120,
      // Worker节点数
      numOfNodes=3,
      // 是否配置SNATEntry
      snatEntry=true,
      // 是否公网暴露集群endpoint
      endpointPublicAccess=false,
      // 节点端口范围，默认30000-65535
      nodePortRange="30000-32767",
      // 网络模式, 可选值iptables|ipvs
      proxyMode="iptables",
      // 是否开启集群删除保护，防止通过控制台或api误删除集群
      deletionProtection=true,
      // 运行pod的主机的操作系统类型，例如：linux，Windows等
      osType="linux",
    };
    var createClusterReq = new CS.CreateClusterRequest{
      body=createClusterRequestBody
    };
    return client.createCluster(createClusterReq);

}

/**
 * 查询集群状态
 * @param client
 * @param clusterId
 * @return DescribeClusterDetailResponse
 * @throws Exception
 */
static async function describeClusterDetail (client: CS, clusterId: string)throws : CS.DescribeClusterDetailResponse{
    var describeClusterDetailReq = new CS.DescribeClusterDetailRequest{};
    return client.describeClusterDetail(clusterId,describeClusterDetailReq);
}

/**
 * 扩容
 * @param client
 * @param clusterId
 * @return ScaleOutClusterResponse
 * @throws Exception
 */
static async function scaleOutCluster (client: CS, clusterId: string) throws : CS.ScaleOutClusterResponse{
    var scaleOutClusterRequestBody = new CS.ScaleOutClusterBody{
        // keypair名称，和login_password 二选一
        keyPair="common",
        // 一台或多台虚拟交换机 ID，N 的取值范围为 [1, 3]
        vswitchIds=["vsw-uf684tfrpwup8gcsw****"],
        // Worker实例规格多实例规格参数
        workerInstanceTypes=["ecs.c5.xlarge"],
        // Worker系统盘类型
        workerSystemDiskCategory="cloud_efficiency",
        // Worker节点系统盘大小
        workerSystemDiskSize=120,
        // 是否挂载数据盘 true|false
        workerDataDisk=false,
        // 扩容的数量
        count=10,
    };
    var scaleOutClusterReq = new CS.ScaleOutClusterRequest{
        body=scaleOutClusterRequestBody
    };

    return client.scaleOutCluster(clusterId,scaleOutClusterReq);
}

/**
 * 查询节点，子账号AK访问会报权限错误
 * @param client
 * @param clusterId
 * @return DescribeClusterNodesResponse
 * @throws Exception
 */
static async function describeClusterNodes (client: CS, clusterId: string) throws : CS.DescribeClusterNodesResponse{
    var describeClusterNodesRequestQuery = new CS.DescribeClusterNodesQuery{
        // 可选 每页显示条数
        pageSize="18",
        // 可选 页码数
        pageNumber="1",
        // 可选 nodepool_id
        nodepoolId="nodepool_id",
        // 状态 
        state="running",
    };
    var describeClusterNodesReq = new CS.DescribeClusterNodesRequest{
      query=describeClusterNodesRequestQuery
    };

    return client.describeClusterNodes(clusterId,describeClusterNodesReq);
}

/**
 * 移除节点
 * @param client
 * @param clusterId
 * @return DeleteClusterNodesResponse
 * @throws Exception
 */
static async function deleteClusterNodes (client: CS, clusterId: string, instanceId: string) throws : CS.DeleteClusterNodesResponse{
    var deleteClusterNodesBody = new CS.DeleteClusterNodesBody{
        //要移除的node_name数组
        nodes=[ instanceId ],
        //是否同时释放ecs节点
        releaseNode="false"
    };
    var deleteClusterNodesReq = new CS.DeleteClusterNodesRequest{
        body=deleteClusterNodesBody
    };

    return client.deleteClusterNodes(clusterId, deleteClusterNodesReq);
}

static async function main(args: [string]): void {
    // 1. 初始化客户端
    var client = createClient("accessKeyId","accessKeySecret","regionId");

    // 2. 创建集群
    var createClusterRes = createCluster(client);
    var clusterId = createClusterRes.body.clusterId;
    
    // 3. 查询集群状态
    var describeClusterDetailRes = describeClusterDetail(client, clusterId);

    // 4. 当集群状态为“running” 时 进行扩容
    if(Util.equalString(describeClusterDetailRes.body.state, "running")) {
      var scaleClusterRes = scaleOutCluster(client, clusterId);
      Console.log(scaleClusterRes.body.requestId);
    }
    // 5. 查询节点
    var describeClusterNodesRes = describeClusterNodes(client, clusterId);
    var describeClusterNodesResHeaders = describeClusterNodesRes.headers;
    var node = describeClusterNodesRes.body.nodes[0];
    var instanceId = node.instanceId;
    
    // 6. 移除节点
    var deleteClusterNodesRes = deleteClusterNodes(client, clusterId, instanceId);
    Console.log(deleteClusterNodesRes.body.requestId);
    
}

Darabonba 场景化 CodeSample 编写指南

如何创建 CodeSample 项目

使用 Darabonba 编写 CodeSample

阿里云开放平台

热门文章

最新文章

相关电子书