自动化代码生成工具 Snips 开发实践

前言

在开发工作中,经常会遇到新产品、服务上线后,需要将其 API 编写不同语言的 SDK。但不同语言 SDK 中都有很大一部分内容是用来进行 API 的描述,而且这部分代码量是最大的,手写起来也枯燥易错。所以我们需要一种 Data-Driven 的开发方式,通过工具(Snips)来自动化的生成准确、优雅的代码,让开发者减少重复无意义的工作,将更多精力放在产品以及业务上。

本文共 4420 字,阅读大概需要 18 分钟。

今天的内容包括:


•    QingStor SDK 简介
•    QingStor SDK 开发流程的改变
•    API Specification
•    SDK 生成工具 Snips
•    场景化测试
•    使用 Snips 开发 QingStor Go SDK


正文

大家好,我是青云 QingCloud 系统工程师 Aspire 。今天我来和大家分享一下 QingStor SDK 以及自动化 SDK 生成工具 Snips 的开发经验。

今天交流的内容包括:

  • QingStor SDK 简介

  • QingStor SDK 的开发流程

  • API Specification

  • SDK 生成工具 Snips

  • 场景化测试

  • 使用 Snips 开发 QingStor Go SDK

1. QingStor SDK 简介

QingStor™ 对象存储为用户提供可无限扩展的通用数据存储服务,在 QingCloud Console (青云控制台)中可以直接创建、使用和管理对象存储 Bucket ,可以方便的上传下载文件。我们也提供了命令行工具(如 qingcloud-cli, qsctl) 来在各种场景下进行数据的存取。但是面对海量数据的操作时,图形化的界面和命令行工具是不够的。另外,我们的用户也需要在代码层面使用 SDK 或者直接请求 API 来接入 QingStor 对象存储。自上线以来我们就开放了一套标准、规范且简洁的 RESTful API ,以及一个 Python 的 SDK 。虽说 Python 的用户量非常大,但是显然只有这一种的 SDK 是无法满足用户需求的,再加上 QingStor 的 API 是遵循 RESTful 标准的,直接使用 API 来接入 QingStor 的成本也会高一些。(不过好在我们已在今年上半年兼容了 AWS S3 的 API ,所以用户也可以使用 S3 的 SDK 来接入 QingStor 。)

这里将 QingStor API 和 QingCloud IaaS 的 API 做个简单比较:

相比之下用户使用 API 来接入 QingStor 的难度会高一些,对 SDK 的需求也就更强烈。

目前 QingStor 提供了包括 Go 、 JavaScript 、 Ruby 、 PHP 、 Swift 、 Java 、 Python 在内 7 种语言的 SDK ,已经可以做到覆盖主流编程语言,而且有了 Snips 的帮助,开发者也能够在短时间内开发出另一种语言的 SDK 。

同时,此次我们将 QingCloud IaaS 和 QingStor 的 SDK 进行了拆分,例如 qingcloud-sdk-swift (尚未发布) 和 qingstor-sdk-swift 。这样做主要是考虑到移动端对空间比较敏感,所引入的第三方库越小越好,由于 QingCloud IaaS 目前开放的 API 数量是 QingStor 的三倍,将两者合并为一个包会造成空间的浪费,对于一个仅需要 QingStor 做为存储的 App 来讲,只引入 QingStor 的 SDK 就足够了。

QingStor SDK 的中文使用文档可以参考 https://docs.qingcloud.com/qi... ;另外这些 SDK 也已开源在 GitHub ,可以访问 https://github.com/yunify 来获取,也欢迎大家给我们提 Issue 和 Pull Request 。

2. QingStor SDK 的开发流程

首先可以回顾一下我们 Python SDK 的开发方式,就是在 API 发生改变之后,手动增加 SDK 中与之对应部分的代码,这种做法效率不高,维护起来也让人头疼。

再加上 QingCloud IaaS 和 QingStor 共有两百多个开放 API ,并且不断有新的 API 伴随产品或功能上线,要做到 SDK 的实时跟进比较困难。而且现在只有一个 Python 的 SDK ,如果再加上其他语言的,每种语言都手动维护,会耗费工程师很多不必要的精力。还有一个问题比较麻烦,如果有用户对一些小众语言的 SDK 有需求,我们也没法立即进行支持,这点行业内基本都有类似的情况。

要解决这些问题,就需要换一种思路。我们可以看到,不同语言的 SDK 中都有很大一部分内容是用来进行 API 的描述(或者叫定义),而且这部分代码量是最大的,手写起来枯燥易错。所以我们采用了一种新的 SDK 的开发流程,使用标准的数据来生成代码,之后通过场景化的测试来进行验证,其中用到了我们自己写的一个代码生成工具━━ Snips 。

Snips 使用 API 的标准化描述和代码模版来生成各种语言 API 调用的那部分代码,除了生成出来的代码,还需要手动编写的代码,每种语言都不一样,不适合统一生成代码,比如错误处理,文件读写,网络请求等。这样做比起纯手工打造一个 SDK ,需要开发的代码量会小很多,开发效率能够得到很大的提升。

上面是利用 Snips 开发一种新的语言的 SDK 的示意图。下面具体说明一下。

新增一种语言的 SDK :

  • 手写哪些错误处理、网络请求等相关的的代码

  • 编写代码模版

  • 使用 Snips 生成代码

  • 通过场景化测试

  • 发布

更新 SDK :

  • 更新 API 描述

  • 重新生成代码

  • 通过场景化测试

  • 发布

这里的 API 的描述我们是通过 Git Submodule 的形式引入到各个 SDK 项目中,这样如果是 API 的变更,完全不需要手动编写 SDK 的代码就可以做到 SDK 的更新。

下面会逐个讲一下 API 描述规范 ( API Specification )、 Snips 和 场景化测试( Scenario Based Testing )这几个部分,我们是怎么做的。

3. API Specification

要实现上述的流程,得先有 API 的描述,我们花了很长时间来确定使用怎样的 API 描述规范,也走了一些弯路。

起初我们自己制定了一个 API Specification 的 Schema :

  • 这个 Schema 的目标是描述 HTTP API

  • 每一个 API Specification 文件呈现一个 Service (如 QingCloud IaaS 或者 QingStor )

  • Service 中可以有 SubService

  • 同时 Service 和 SubService 中都包含 Metadata 、 Properties 、 Operations 、 Endpoint 等信息

  • Operation 是具体的 API 请求,其中包含 Request 和 Response 的描述以及其他基本信息

  • 定义了 boolean 、 integer 、 timestamp 、 binary 、 list 、 object 等几种基本的数据类型,及自定义的数据类型 CustomizedType, CustomizedType 可以出现多级引用

之后使用这套 Schema ,去描述了 QingStor 的 所有 API ,并且写了解析器,快速实现了从 API 描述生成 Go SDK 的代码。但是 Review 时我们发现这个自己定义的 Schema 还是太简陋,没有经过足够的数据进行验证,很多情况都没有考虑到,还有一些 Corner Case 也难以描述,并且这个 Schema 本身的校验效果也不理想。而且如果使用这套自己定义的 Schema 来描述 QingStor 和 QingCloud API ,无论是在内部使用还是开放出去,都是让人比较难以接受的,这种自立门户的做法也没有太大意义。

然后我们对比了几个目前可以用到的几个 API Specification 的规范,最后选择了 Swagger 。

Swagger 是一个描述 RESTful API 的规范, Swagger 具体的 Specification 大家可以访问它的网站来查看: http://swagger.io

今年的一月份 Swagger 更名为 OpenAPI Specification ,由 Linux 基金会赞助成立了 OpenAPI Initiative 来继续 OpenAPI Specification 的开发。在 Google 、 Microsoft 等大厂的支持下, Swagger 俨然已经成了业界标准,相关的生态和工具也已比较齐全,用它来作我们 API 的描述规范再合适不过,所以我们最终选择了 Swagger 来重新描述了 QingStor APIs ,并且实现了用 Swagger 描述规范来生成代码。

使用 Swagger 规范无疑是正确的,因为 Swagger 的工具和生态相对比较完善。以 Swagger Editor 为例,它是一个 API Specification 的 Web 编辑器,可以在编辑的同时提供代码补全、高亮和实时语法验证功能,感兴趣的朋友可以在 http://editor.swagger.io 体验一下。

Swagger 虽然发展的比较快,但并不是对所有 API 都友好。 QingCloud IaaS 的 API ,请求参数部分里会有数组( Array )和字典( Map )。例如 statics.n.router_static_name 、 statics.n.router_static_value 这种请求参数,用户实际提供的是一个由 Static 字典组成的数组,并且这个请求参数是位于 Request URL Query , SDK 会把数组和字典转换一下格式,构造出 statics.0.router_static_name=name&statics.0.router_static_value=value 这种形式的请求串。这样就会出现问题,在描述请求的时候需要定义数组和字典参数,由于 Swagger 的规范比较严格, Operation Parameter 不允许自定义类型出现,这时就只能将请求参数的描述放在 Request Body 里面来定义,这样就需要解析 Specification 的时候做一些特殊处理。

Swagger 标准也考虑到了 API 数量很多导致描述文件过长的情况,它支持使用 $ref 来引用其他文件,当然这个引用的功能其实是 JSON Reference 和 JSON Pointer 规范提供的,但是这里的 $ref ,只支持同一个文件内的引用,或者是引用某个 URL 链接。我们测试的解析器,包括 Swagger 官方的 swagger-codegen 都不支持文件间的引用,更不用提 Circle Reference 这种常用的情况了。不过这个问题我们在 Snips 中也解决掉了,可以看到我们的 QingStor API Specs 中的 API 描述是拆分成了很多文件的,具体内容等下 Snips 的部分会提到。

使用 Swagger API Specification 规范来描述 API ,其作用不仅仅可以用来生成代码,生成文档,更重要的是它的约束作用,它反过来可以规范 API 的开发和交付,进一步保证 QingCloud 的整体服务质量。对于 SDK 开发来讲则是一种 Data-Driven 的开发方式,这种思路可以让产出的各个 SDK 在功能上保持很强的一致性,不会出现某种语言的 SDK 缺失功能,或者是更新滞后,这种思路的优势也会随着更多产品和功能的上线变得越来越明显。

API Specification 文件本身也需要验证正确性,而使用 Swagger 标准可以轻而易举的使用 JSON Schema 来实现 Specification 数据的验证。

QingStor 的 API Specification 也放到了 GitHub ,这里是地址 https://github.com/yunify/qin...

4. 代码生成工具 Snips

接着讲讲代码生成工具,对于 Swagger 来讲,有官方的代码生成器 swagger-codegen ,还有其他的同类开源项目比如 go-swagger 。

它们虽说可以生成代码,但是生成出来的代码可控性和可读性都不高,并不能满足我们的需求,定制起来也比较麻烦。

例如采用 swagger-codegen 得 fork 过来,改它的 Java 代码,而且每增加一种语言的 SDK 基本上都要去增加对应的 Java 代码,这对于 Java SDK 之外的开发者来讲是非常不友好的。

除此之外还有很多其他细节上的问题,例如我们 API 的遗留问题,上面说到的 QingCloud IaaS 的请求参数不标准;例如 swagger-codegen 和 go-swagger 不支持文件引用的解析;生成出来的代码大小写控制不严格( acl 被转换成了 Acl ,而不是 ACL )等。

现有的代码生成器没有可以开箱即用的,都需要去进行不少的修改。但是去实现一个 Swagger 的解析器又太费时费力了,所以我们想到了一种折中的方案,使用开源的 Swagger 解析器来构建自己的生成器。

比对了几个开源项目之后,我们采用的解析器是 go-openapi/spec ( https://github.com/go-openapi/), 这个解析器的作者也是 go-swagger 的作者, go-swagger 是在这个解析器之上构建的。遗憾的是 go-openapi 也不支持文件引用,看到未来有支持文件引用功能的计划,不过不知道什么时候才会加上。于是我们简单熟悉了一下代码,之后提交了几个 PR 把这功能帮他们实现了,作者也欣然接受 “ With this PR go-swagger is the first library on go that fully supports json schema and ref resolving so very happy with it ?”。

随后就有了代码生成工具 Snips ,它是一个命令行工具,很好地支持着我们的 SDK 开发,以 Go 语言 SDK 为例,包括模版在内,手写的代码大约 6 千行左右,而生成出来的代码已经达到了 2 万多行,开发效率得到了不小的提升。

关于模版, Snips 会从指定路径加载模版文件,模版目录下需要有一个 manifest 文件,可以是 JSON 或者 YAML 格式,这个文件指定了一些生成规则,例如指定该目录下模版文件的格式,输出文件名的命名风格是 CamelCase 还是 snake_case ;输出文件的扩展名和前后缀,可以参考 example 下的 manifest.yaml 来查看所有支持的规则。模版文件格式目前只支持一种,是 Go 语言的 template 。

与代码生成有关的简单逻辑是放在模版里去实现的,同时生成器也提供了一些内置函数可以在模版中使用,如大小写风格的转换、字符串替换、数据传递等,从而做到了生成器与某种语言无关,新增语言不需要去修改生成器的代码。上文提到的 acl 转换成 Acl 的问题,使用 Snips 提供的函数就可以正确转换,例如 {{snakeCase "acl"}} 会转换成 “ ACL ”。

关于多版本 API , Snips 也有解决方案。

通过 -n (--service-api-version) 参数来指定使用的 API 版本,然后将代码生成到不同的目录,例如 latest version 的代码在 service 目录,特定版本的代码可以在 service-2016-01-06 中,再根据语言的不同看是否还需要相应的调整。以 Go 语言为例,用户使用的时候 import 不同的路径的 service 即可切换不同版本的 API ,如 import "github.com/yunify/qingstor-sdk-go/service-2016-01-06"。

Snips 目前已经开源, GitHub 地址: https://github.com/yunify/snips 。目前是针对 QingCloud IaaS 和 QingStor API 的代码生成工具, Snips 的思路和其他的 Swagger 生成器的思路不太一样,未来也可能会做成一个通用的代码生成器。

5. 场景化测试

SDK 开发出来了,除了单元测试之外,还需要在线上生产环境进行测试,保证交付的 SDK 可正常工作,我们称之为服务测试( Service Test )。

服务测试中我们采用 Cucumber ( https://cucumber.io),它是一个 Behaviour-Driven Development (BDD) 工具。 Cucumber 会读取通过自然语言描述的测试场景和数据,然后结合不同的测试实现去验证是否通过。 Cucumber 可以被称作是一种测试方式,基本上每种语言都有它的实现。

举个例子:

获取一个 Object , Cucumber 描述是这样的:

Ruby 中对应的测试实现是这样的:

Cucumber 会检查代码场景执行过程中的数据是否满足预期,给出一个完成的测试结果

这样以使用者的角度来真实的测试 SDK ,并且可以让所有 SDK 的测试用例保持一致,在保证 SDK 质量的同时,也可以做到各种语言 SDK 功能的一致性。

QingStor SDK 的测试场景也放在了 GitHub : https://github.com/yunify/qin...

6. 使用 Snips 开发 QingStor Go SDK

上面讲了整套的 QingStor 的 SDK 开发流程,下面用 QingStor Go SDK 来举例说明一下。

qingstor-sdk-go https://github.com/yunify/qin...

首先需要实现 SDK 最基础的部分,比如网络请求和签名处理、文件读写、错误处理等等,然后再使用 Snips 生成 API 相关的代码。

假设基础部分现在已经完成了,并且经过了单元测试。

接下来安装 Snips ,可以使用 go get -u github.com/yunify/snips 安装,或者直接访问 GitHub 下载编译好的二进制文件。

在代码仓库目录下以 git submodule 的形式引入 API Specification 和 Test Scenarios:

./specs/qingstor 引用 QingStor API specifications
./test/features 引用 QingStor 测试场景

然后便可编写代码模版,下图所示为 Go SDK 的模版文件:

具体的模板文件内容请见:
https://github.com/yunify/qin...

模板编写完成后,即可利用模版和 API Specifications 来生成代码。下图为生成代码的命令,生成完的代码有可能会难看,可以格式化一下代码,当然如果模版控制的严格,生成出来的代码足够漂亮,可以跳过格式化的步骤。

之后便可使用这些生成好的代码,实现测试场景,具体的代码请见这里: https://github.com/yunify/qin...

最后运行测试

7. 开发者激励活动

目前 QingStor 已经提供了七种语言的 SDK (其中 Python SDK 的新版也会使用 Snips 来重新生成),覆盖了主流的编程语言,但还有一些编程语言的 SDK 我们没有来得及开发,为激励更多的开发者参与进来贡献其它语言的 SDK ,我们特此发起 QingStor SDK 大赛活动,报名地址请见: https://jinshuju.net/f/0MB6w6

你可能感兴趣的:(自动化代码生成工具 Snips 开发实践)