云平台SDK攻略

作为一个云原生的开发者，你会最关注哪方面的开发体验？在你的应用中与云上的资源进行交互肯定是你非常在意的吧，不管是往Service Bus中发送一条消息，亦或是为更大的运算需求创建新的虚拟机。你可以利用云平台的SDK，比如Azure SDK来完成所有这些操作，那么Azure SDK是如何写出来的呢？一个云平台的SDK和一个传统的SDK有何区别？

传统SDK和云平台SDK之间的不同

传统SDK， 比如说.NET SDK或者JAVA SDK，都是.NET运行时（.NET CLR）或者JAVA运行时（JVM）的编程接口，他们之间的“通讯协议”是在进程内的，基于二进制的。
云平台SDK通常基于OpenAPI定义。OpenAPI更像是一个跨进程的基于RESTFul HTTP APIs的通讯协议，OpenAPI云计算的世界中无处不在，但是OpenAPI有其自己的局限性。

利用OpenAPI和Azure进行交互时候会遇到的问题

OpenAPI是一个REST API Service的接口定义，对于任何一个程序语言来说，他都不是一个开箱即用的解决方案。当一个开发者想要开始使用OpenAPI, 他通常会遇到下面的一些问题：

• 异常处理
• 长时间运行操作的处理
• 分页操作处理
• HTTP Client生命周期管理
  为这些处理构建健壮的代码并不是一件容易的事情。这种情况下，引入SDK就变成了一种很自然地选择。

微软是如何从OpenAPI中生成Azure SDK的

Azure SDK的设计遵从了通用SDK库设计指导，这份指导纲要确保了在不同Azure Service之间一致的SDK使用体验，从2022年3月31号开始，我们对不符合指导纲要版本的SDK库开始了逐步淘汰。

为一个新的Azure Service创建SDK，Azure SDK团队紧密合作，常见的工作步骤如下：

• Azure Service团队定义好OpenAPI说明（Swagger file），并且在REST API specification repository起一个PR。
• Azure SDK 团队会审核新的OpenAPI说明，确保里面没有破坏性变更，语法错误等等。
• Azure SDK 团队利用AutoRest从OpenAPI说明当中生成客户端库。AutoRest是微软创建的一个开源客户端库生成工具来访问Restful web services. AutoRest利用不同语言的拓展来为不同编程语言生成Restful web service的客户端库。
• 我们会审核生成出来的客户端库，并起一个PR到相应语言SDK的Github repository. 我们有一个非常棒的内部工程平台对这些客户端库进行测试，以确保我们不会引入任何regression issue。这些测试包括自动生成的测试和手写测试，但是在未来我们会更多的依赖自动生成的测试用例。
• 一旦所有检查都通过了，这个新生成的客户端库就会被合并到相应语言的SDK Github Repository。
  在客户端库被合并到相应语言的SDK Github repository之后，相应的持续集成和部署管线就会被触发，如果一切无误，新的客户端库就会被发布到相应语言的包管理器，如nuget, npm等等。
• 所有SDK相关文档，样例代码也会陆续得到更新。
  AutoRest是整个客户端库生成过程当中的关键。AutoRest知道常见模式的REST API调用，并在客户端库中将这些调用暴露成对于开发者友好的编程接口。比如说，长时间运行的操作（Long-running operation, LRO）以及一些资源创建，删除等无法立即知道操作结果的REST API调用。这些情况下，服务器会返回一个201（Created）或者202（Accepted）状态码，并附带一个链接来持续监测请求的完成状态。这个操作行为对于直接的RESTFul API调用是合理的，但是从编程语言的角度来看这是有问题的，这种操作应该被转变成一个带回调函数的异步操作，回调函数允许开发者为LRO操作的成功或失败编写相应代码。OpenAPI, 很不幸的，没有这种异步语法上的支持。为了能够支持这种操作，微软定义了一系列AutoRest OpenAPI拓展来丰富OpenAPI的语法。

现在让我们回到之前的LRO场景。我们可以在OpenAPI中定义一个x-ms-long-running-operation。比如说，下面的定义是一个创建/更新Azure VM的OpenAPI定义（完整定义可在这里找到）

"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}": {
      "put": {
        "tags": [
          "VirtualMachines"
        ],
        "operationId": "VirtualMachines_CreateOrUpdate",
        "description": "The operation to create or update a virtual machine. Please note some properties can be set only during virtual machine creation.",
        "parameters": [
          {
            "name": "resourceGroupName",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "The name of the resource group."
          },
          {
            "name": "vmName",
            "in": "path",
                        "required": true,
            "type": "string",
            "description": "The name of the virtual machine."
          },
          {
            "name": "parameters",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/VirtualMachine"
            },
            "description": "Parameters supplied to the Create Virtual Machine operation."
          },
          {
            "$ref": "#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/SubscriptionIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/VirtualMachine"
            }
          },
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/VirtualMachine"
            }
          },
          "default": {
            "description": "Error response describing why the operation failed.",
            "schema": {
              "$ref": "#/definitions/CloudError"
            }
          }
        },
        "x-ms-long-running-operation": true
      }
   }

有了上面的OpenAPI定义，我们生成的客户端库中的BeginCreateOrUpdate方法调用就变成了下面的样子，以Go语言为例（完整代码可在这里找到）

pollerResponse, err := vmClient.BeginCreateOrUpdate(ctx, resourceGroupName, vmName, parameters, nil)
    if err != nil {
        return nil, err
    }

    resp, err := pollerResponse.PollUntilDone(ctx, 10*time.Second)
    if err != nil {
        return nil, err
    }
}

上述代码中的Poller类来自于Azure Core项目。Azure Core提供了整个Azure SDK的基础架构，比如说HTTP Client的生命周期管理，异常处理。利用Azure Core, 我们就可以在OpenAPI中定义更多的拓展，并将这些拓展转变成更加开发者友好的客户端库语法，常见的OpenAPI拓展有：

• X-ms-error-response：该拓展可以确定是否把一些http返回状态码映射成为一个错误
• X-ms-pageable：该拓展可以将返回的list映射成为一个可分页的结果
  更多的拓展，请参见AutoRest Extensions for OpenAPI

通用SDK库设计指导:
https://azure.github.io/azure-sdk/general_introduction.html
REST API specification repository:
https://github.com/Azure/azure-rest-api-specs
AutoRest:
https://github.com/Azure/AutoRest
AutoRest OpenAPI拓展:
https://github.com/Azure/autorest/tree/main/docs/extensions
完整定义在这里:

https://github.com/Azure/azure-rest-api-specs/blob/d48ca7ed92cbb4f972eb6214bdb3200edaf78369/specification/compute/resource-manager/Microsoft.Compute/stable/2021-11-01/compute.json#L3624
完整代码在这里：
https://github.com/Azure-Samples/azure-sdk-for-go-samples/blob/e42648befd65a0b92ae55f92912f3ba91a771dec/sdk/resourcemanager/compute/createVM/main.go#L528
Azure Core：
https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/azcore
AutoRest Extensions for OpenAPI：
https://github.com/Azure/autorest/tree/main/docs/extensions

我们讨论了使用云SDK的好处以及微软构建云SDK的流程，感谢您的阅读。

文章转自公众号：openGauss