导读

在以云计算为主角的开发者视界中，OpenAPI 是绝对的主角。要发短信，用 OpenAPI；要管理资源，用 OpenAPI；要管理权限，用 OpenAPI。如果一个 OpenAPI 解决不了你的问题，那就再来一个。在今天，开放平台及 OpenAPI 随处可见，它是系统与系统之间集成的重要桥梁。但 OpenAPI 用起来是否真的舒服，这要打一个大大的问号。本文将介绍 OpenAPI 领域下的难题和一些解决方案。

背景

阿里云有位工程师叫朴灵，热爱开源，是活跃在 Github 上的国内技术大牛之一。在阿里工作 6 年之际，朴灵产生了离职的想法，打算去一家创业公司再战高峰。走之前，朴灵做了一些研究工作，他发现阿里云在功能和产品上可以说是一流的云计算厂商，是创业公司的首选，但由于过去的业务中写过大量的 Node.js SDK，对开发者体验有着自己的体感，他觉得在开发者体验关怀上，阿里云做得还不够好。来自一个热血工程师最朴素的想法，自己何不先留下来，去把这件事情做好，于是，朴灵加入了阿里云开放平台负责 SDK 业务，期间，他和团队研发了专利 TeaDSL，下面朴灵将分享 TeaDSL 如何解决多语言 SDK 的问题。

使用 OpenAPI 的痛苦

在过去，我们经常说的 OpenAPI，通常的做法是，开发好服务端的接口，然后在文档里简单写几个参数描述，就直接丢给客户去用。反正我是开发好了，我这里是好的，客户能不能用起来我是不用管的。

图 1 第一代的 OpenAPI 通常仅由简单的文档及实际的接口构成

然而接下来的问题就来了。首先，文档上写得不清不楚的参数，没有试过，完全不知道它到底能不能 Work。其次，OpenAPI 总得有一定的权限认证吧，那么总得有一个签名啥的，每个客户都要写一遍，关键是总是没法写对。再次，不同的客户所使用的编程语言不一样，得把接口重新包装才能用。

总算费心费力调通了接口，以为可以高枕无忧的时候，咋接口老是报错，网络连不上，返回的数据不对，诸如此类。再往后，OpenAPI 可能总是要发生一点变化什么的，总是出现一些数据结构发生变化，不兼容之类的问题。

一个 OpenAPI 到最后，不光是用户使用起来觉得很气，作为维护者也是很艰难的。当公布一个 OpenAPI 后，第一步给出简单的文档后，会发现除了要把参数详情写得越来越完善准确外，还得给出签名算法，让不同语言的开发者来接入。然而给出签名算法后，会发现只有一些开发者能顺利完成，大部分的开发者只能眼巴巴地请你帮忙提供一个 SDK。好吧，那就提供一下我最拿手的 Java 语言的签名，提供一个核心 SDK 呗。

图 2 第二代的 OpenAPI 会有 SDK 的实现，但仅有少许的语言支持

随着这个 OpenAPI 接口的用户越来越多，一个客户说我要用 C++ 来对接你，另一个客户说我要用 Python 来对接你，于是，我一个 Java 程序员，怎么就要写那么多语言的 SDK 呢。没有办法，如果不提供良好的 SDK，客户说，没有 IDE 提示呢，我怎么写代码呢。

总而言之，在 OpenAPI 的应用过程中，一件简单的事情，会变得非常复杂：

需要提供良好的 API 文档，作为最基本的要求
需要提供 SDK，保障开发者的编码体验，封装细节，代码提示等
需要提供 Code Sample，更理解接口的使用效果
如果有 CLI 就更好了，这样连 bash 脚本写起来也更方便
如果没有 Test Cases 作为日常的持续集成，接口质量可能存在问题

上面这些要求，如果加上多种编程语言的条件，就会演变为一件细碎而又繁多的体力活。并且这中间不能有任何的变动，因为仅仅是一点点的 OpenAPI 变动，就需要连带整个下游发生变化。如果一个地方没有保持一致，那么客户问题就会出现。

图 3 当用户量变多，OpenAPI 的提供者需要提供完善的工具及更多的编程语言支持

通常为了解决此类的问题，以及 OpenAPI 的诸如签名校验，限流，生成 SDK、文档等等，业界通常会使用 API 网关来承担这些横向的责任。

然而，作为笔者所在的环境下，会发现，我们身边的网关有点多。于是不同的网关有不同的风格，不同的签名算法，不同的序列化格式。于是上述的过程要根据不同网关的数量，进行翻倍：

图 4 当一个企业变得庞大时，不同风格的 OpenAPI 及网关都会出现

当我们在抱怨使用不同产品的 OpenAPI/SDK 体验不一致，文档不对，Demo 出错等等问题时，真不是因为做这些事情太难，而是太多，太琐碎。一件简单的事情，需要做一百次，也就不是简单的事情了。

TeaDSL 的解决之道

TeaDSL 是由阿里云开放平台 SDK 团队主导设计的一门领域特定语言。主要用于解决如下问题：

通过一门中间语言，可以支持不同风格的网关。即使网关下的 OpenAPI 风格各异，也能一致地表达到。
可以通过翻译的能力，实现对不同编程语言的代码生成。也就是可以基于统一的中间表达，生成多语言的 SDK。
基于中间表达，我们可以将一组 OpenAPI 视为一个 library，因此可以在这个基础上实现 OpenAPI 接口的 Code Sample 编写。进而实现多语言的 Code Sample 统一生成。

因此 TeaDSL 的核心能力就是通过一种中间语法来描述 OpenAPI，提供类似编程语言的能力，来将 OpenAPI、SDK、Code Sample 等场景及语言有机地结合在一起。

在没有 TeaDSL 之前，对于不同的网关，我们要为它制定独立的工作流程，即从 OpenAPI 定义到不同语言的 SDK 生成，是独特的。换一个新的网关风格，就要重新实现这套流程。

图 5 M 个网关都要支持 N 种编程语言，整个工作量是 M * N 的关系

而具有 TeaDSL 后，我们则形成一个中间层。可以将原来的工作收敛起来，我们仅需要关注不同的网关到 TeaDSL 的转换工作，以及 TeaDSL 到各个编程语言的生成工作。

图 6 经过中间层的隔离，整个工作量变为 M + N 的关系

也就是说，TeaDSL 是在做一件 M * N 到 M + N 的工作。当网关越多，支持的编程语言越多，收益则越大。

一旦这个中间层建立起来，整个 OpenAPI 的应用形式都可以基于它来构建。比如，编写一个 OpenAPI 的 Code Sample，Test Case 等。

接下来简单介绍 TeaDSL 是如何实现支持任意风格的网关和多种编程语言的。

如何支持任意风格的网关

对于不同的 API 网关，或者不同产品的 OpenAPI 而言，它们之间的风格可能都千差万别，因此在很大的程度上，每种风格的 OpenAPI 都有它自己的元数据定义格式。为了减少网关、风格带来的差异化，业界主要推动的方式是尽量采用标准的定义格式。比如 Swagger 就是其中的佼佼者，它依托于 OpenAPI Specification ，以 RESTful 风格的 OpenAPI 作为基准，形成了一套业界标准。

但这个世界就是这样不完美，我们现有的大量 OpenAPI 并不是 RESTful 风格的。这导致很多的产品现存的 OpenAPI 在文档、SDK等场景下，无法使用上 Swagger 这样强大的生态工具链。

为了解决这些问题，我们需要进行两步操作：

设立一套新的标准，来包容不同风格的 OpenAPI
以这套新的标准，来建设生态工具链

如果完成这两个步骤，那么现实世界上的每一个 OpenAPI，RESTful 或者非 RESTful 的，不需要做任何迁移，也能具有强大的工具链支持。

新标准的设计

通过我们的研究发现，无论 OpenAPI 的参数是如何组成的，传输是 JSON，还是 XML，乃至自定义协议，OpenAPI 都是基于 HTTP 协议栈进行提供的。也就是说，万变不离其宗的是 HTTP 协议本身。因此我们确立的基本模型是这样的：

{
  protocol: string, // http or https
  port: number,         // tcp port
  host: string,         // domain
  request: {
    method: string, // http method
    pathname: string, // path name
    query: map[string]string, // query string
    headers: map[string]string,  // request headers
    body: readable      // request body
  },
    response: {
    statusCode: number, // http method
    statusMessage: string, // path name
    headers: map[string]string,  // response headers
    body: readable      // response body
  },
}

对于不同风格的 OpenAPI 而言，就像不同风格的建筑，它们的建筑材料都几乎相同，只是施工手法，组合形式不一样而已。我们看到的 OpenAPI 风格差异，实质则是序列化过程不同而带来的不同。我们序列化过程和数据模型分离，将用户更直观的数据结构提取出来。

比如从用户角度出发，一个数据模型是更直观的事物：

model User {
    username: string,
  age: number
}

在不同的网关下，它的传输形式可能是 JSON，也可能是 XML，但最终都是 readable，也就是可读的字节流。

toJSON(user: User): string
toXML(user: User): string

最终的结果就是：

__request.body = toJSON(user);
__request.body = toXML(user);

更进一步的过程是，我们会将一个 OpenAPI 的请求/响应包装为一个类似于编程代码的方法：

api getUser(username: string): User {
  __request.method = 'GET';
  __request.pathname = `/users/${username}`;
  __request.headers = {
    host = 'hostname',
  };
} returns {
  var body = readAsJSON(__response.body);
  return body;
}

尽管上面的代码不能实际运行，但大致也看出来我们包容不同的网关、风格的办法如下：

以 request / response 也就是 HTTP 协议作为核心模型
通过引入一些方法，如 toJSON / toXML / readAsJSON 等方法来分离数据结构和序列化过程
将整个过程包装成方法

这些方法在不同的编程语言下具有不同的实现，但我们只要定义好统一的签名，就能确保一致性：

function toXML(data: $Model): string;
function toJSON(data: $Model): string;

以上就是 TeaDSL 如何实现支持任意网关的方案。整个过程相对抽象，网关间的那些具有差异化的风格，统统交给这些方法去实现，留下来的就只有数据结构。

如何支持不同的编程语言

如果只是能通过一种描述方式来描述不同的 OpenAPI 调用过程，只是完成了一半的工作。另一半的工作是如何将这种描述语言落地到不同的编程语言下。在过去，我们支持不同的编程语言，主要是基于模版的形式来生成不同语言的实际代码。但这对我们来说仍然还有一些不足之处：

模版的生成方式相对生硬，实现起来容易，但维护起来不那么灵活
生成出来的代码容易带来命名冲突，语法错误等

从上面的形式也看到，这个方案，被我们设计成了一种 DSL 代码。因此它是具有自己的词法、语法、语义规则的，在生成目标编程语言代码之前，会有一套自身的校验。DSL 的这些能力是模版所不具备的。

可能对于别的场合，采用 DSL 的形式并不多见。但对于前端工程师而言，这些年已经见的较多了：CoffeeScript、Babel、JSX、TypeScript 等等。为此我们参考了诸多编程语言的设计，最终形成了自己的一套语法。并借鉴编译器领域的转译方式，因此我们可以在模型一致的情况，生成到各种不同的编程语言下。

整个 TeaDSL 的处理流程如下：

最终我们支持多种编程语言的场景主要有3个：

基本的多种语言的 SDK
OpenAPI 相关的多种语言的 Code Sample
OpenAPI 相关的多种语言的 Test Case

通过中间语言的强校验，生成到多种目标场景，可以解决编程语言支持不全面的问题。同时也大幅节约 OpenAPI 维护者的精力成本，不需要反复手工地编写不同编程语言下的 Code Sample。随着对不同编程语言的支持逐步完善，这些中间 TeaDSL 代码不需要任何操作，即可自动支持到新的编程语言下。

总结

TeaDSL 的主要能力是支持到不同风格的 OpenAPI，同时支持多语言的 SDK、Code Sample 目标生成。最终的目的仍然是打通从 OpenAPI 定义到文档、到 SDK、CLI 等 OpenAPI 使用场景下的一致性。提供给用户更统一、专业、一致的使用体验。同时也大幅降低 OpenAPI 提供者用来支持用户的成本，通过自动化的方式，节省精力的同时，还减少人为参与时导致的错误。

目前 TeaDSL 在阿里云的一些 SDK 上已经有所应用，如：https://github.com/aliyun/aliyun-ccp。阿里云开放平台在持续努力提升它的整个工具支持生态，以期望能建成比 Swagger 更适配的生态体系。

来源：oschina

链接：https://my.oschina.net/u/4300092/blog/3234742

标签

ucc