第三方服务接入云平台的统一方案

摘要：的特点通过状态码能知道操作结果，通过方法能知道操作类型增删改查，通过能知道操作的资源对象。平台只通过状态码来判断操作成功与否。

今年，我的任务是为公司的私有云平台（ PaaS ）开发对应的云服务平台（我们称之为插件平台），这个云服务平台的主要任务，是为云平台接入一些服务，服务包括但不限于mysql、redis、cdn等存储服务，天气预报等http服务。这个系列文章，希望总结本人在开发这个平台时的得与失。
下面将云服务平台简称为平台（插件平台），所接入的服务，简称为第三方服务（插件）

统一接入方案，是指可以帮助插件平台更快接入第三方服务的一种统一方案

首先要回答的第一个问题，是为什么需要插件平台：

云平台，是一个强大的开发平台，帮助开发人员完成从机器申请，项目部署，维护（动态扩容……）等一系列操作，像阿里云、腾讯云，都是国内这方面做的比较大的平台。一个完整的云平台，必然会接入一些第三方服务。简单的做法，当然是云平台自己完成这个事情。但随着平台及人员规模的扩大，一个很合理的分工，是将接入、管理、维护第三方服务的功能，作为一个独立的模块、平台。这样符合软件开发的解耦原则，具体来讲，会有以下收益：

当云平台要升级改造时，不会直接影响到第三方服务。过往的逻辑链路，是云平台绑定了 N 个第三方服务，而有了插件平台，这个链路变成：云平台-> 插件平台 -> N个第三方服务。过往的情况是，云平台的一些变动，N个第三方服务可能要跟着修改。而现在，只需要由插件平台统一做变更，而插件平台到N个第三方服务这条链路，可以保持之前约定的规则不变。另外，云平台的一些部署、变更，也能尽量少地影响到插件服务。

插件平台更专注于插件这个事情，可以把插件接入、维护这件事情做得更加极致。

一个插件平台，可以对接多个云平台 。作为一个中间站，插件平台可以按照它和每个云平台的约定进行对接，然后再按照插件平台自己的标准流程，和多个第三方服务进行对接。这样，每个云平台上，等于都能接入插件平台提供的第三方服务。

能与开源社区结合，打造闭环“广大开发人员开源组件->孵化成熟->成为云平台第三方服务”，从而提供更多丰富的插件。这是我们的实践结果。插件平台不仅为云平台提供第三方服务，同时，我们还开发了这么一个网站，每个开发人员，可以到这个网站开源自己写的组件，如果觉得合适，还可以将这个组件转成云平台适用的第三方服务。

其次，解答统一接入方案的重要性和必要性：说到底是为了两个字,"效率"。没有统一接入方案时，每来一个新的第三方服务，云平台开发人员就需要和第三方服务开发人员讨论确定接口，然后一方（第三方服务）写接口，一方（平台）写调用逻辑，最后进行联调，非常麻烦。有没办法改善呢？当然是有，就是提供一个统一的接入方案，不管是什么第三方服务，都按照这套规范。平台的逻辑是通用的，要接入新的第三方服务时，无需开发。第三方服务要按照规范开发几个接口，再通过页面配置信息，然后就能接入了。从之前的两方联调模式，变成单边适配。

首先做第一层抽象，以一个MySql服务为例，用户可能需要：创建、删除、变更、查看（基本参数）一个MySql实例。MySql服务在插件平台正式上线前，平台需要知道，如何调用MySql服务的哪些接口以做增删改差服务资源。因此，统一接入，其实就是解决平台和第三方服务如何对接这四个接口的问题。

调用第三方服务这几个接口时，如何判定操作是成功的（特别是创建、删除操作）

创建一个第三方服务实例，不同的用户，需要创建的实例类型，可能是不一样的。如何统一？例如，有些项目需要创建带从库的 MySql ，有些项目不用。

平台发送请求时，要带上哪些参数。不同服务，所需参数不一样，怎么在不改平台带代码的情况下，让平台根据服务的不同，带上不同的参数。

操作成功及失败时，分别要返回哪些信息给用户。如何从第三方服务的接口响应内容中，提取对应的信息

如何让第三方服务开发者可以自己调试协议，而无需平台开发介入

在第三方服务正式上线时，平台管理员如何快速检查接口是否符合约定

既然称之为统一方案，那么必定就是要做这几件事情：制订一套行之有效的标准流程，定义简洁清晰的接口规范，提供相关的接入工具。

最终的流程如下

开发者按照约定，开发服务的增删改查接口

在云服务平台填写服务信息，使用测试工具测试ok后，提交管理员审核

管理员审核并上线

这是很常见的一个接入流程。下面我们具体看看，我们是如何更简洁解决上面提到的问题。

第三方服务在收到请求时，当然需要判定请求来源是否合法，是否来自插件平台。我们提供了两种鉴权方式，供第三方服务开发者选择：

keystone
插件平台、公司的私有云平台，鉴权都基于 openstack 自身的 keystone 模块，该模块为服务间交互的鉴权，提供了一种统一方案。因此，和平台交互的第三方服务，也可以采用该方式。

这样有两个好处：

从云平台、插件平台、第三方服务，自上而下，鉴权都是统一、标准、可信任

不用自己造轮子

password
平台和服务之间约定一个密码，平台发起请求时，会在 Header 中带上该密码，服务在收到请求时，判断该密码是否和约定一致

这两个方式，前者略重，但安全可靠，后者略轻，却快速简单。 keystone 是 openstack 的标准方式，它的好处自不必说，而 password 这个方式，是考虑到我们是个私有云，可以减低安全要求，同时更要尽量快速简单地接入第三方服务。

和下面要展开的“请求参数格式"一样，这里的关键，是如何抽离区分，平台的统一参数及不同服务之间的差异参数。什么意思呢？哪些是统一的参数，哪些是差异参数。例如，不管是何种第三方服务，创建一个资源后，都需要返回操作的明确结果，资源的id。而其他的返回参数，则存在差异，例如一个 mysql 服务，还需要告知，资源的 url ，端口号，用户名，密码等，而图片服务，则可能提供一个存储路径 url 即可。

我们是这样做的：请求、响应设计，遵循 RESTful 设计。RESTful 的特点：通过 HTTP 状态码能知道操作结果，通过 HTTP 方法能知道操作类型（增删改查），通过 Url 能知道操作的资源对象。这些特点，刚好和服务接入的标准不谋而合。因此，我们约定：

请求响应码，操作成功返回200，否则返回4xx，5xx。平台只通过状态码来判断操作成功与否。

标准的返回内容（示例）如下：

{
    "id": "68788943-d109-416b-983d-e3df70a9463b",
    "config_vars": {
        "port": "3306",
        "host": "d9888.mysql.oa.com",
        "slave_host": "fd9888.slave.mysql.oa.com",
        "default_db": "db_name",
        "user": "a742e2fe34d6",
        "password": "12345678"
    },
    "message": "success!!!"
}

上面是 MySql 服务的返回例子。对于所有服务，我们都约定，返回格式统一使用 json，json第一级要包含 id ，message ，config_vars 这三个属性。其中，id 为资源 id，后续对该资源的删除，变更，都通过该id进行。message 为附带的消息，特别是操作失败时，方便告知用户失败的原因。config_vars 中，会包含跟服务相关的差异参数，不同服务的参数，是不一样的。在最终的信息配置页面，提供了如下的配置功能

在该页面中，开发者可以配置 config_vars 中的参数。而平台在收到实际请求时，也会去验证 config_vars 中是否包含这些参数，以确保请求有效性。

上面我们提到，同一个第三方服务，会有不同的类型，并对应不同的请求参数。还是以MySql为例，假设我们将参数的配置直接扔给用户，例如用户需要一个 MySql，页面提供好几个填写项：是否带从库、buffer 内容要多大，是否为 SSD 硬盘等等，用户自己填写，然后才能创建一个 MySql。这样是否会让用户觉得很懵呢？用户能懂怎么填吗？用户是否真的需要这些选项呢？

为了让用户选择更加简易，我们加入了套餐的概念。由第三方服务开发者定义几个套餐，例如，高级套餐对应配置比较高的服务，中级、低级套餐则配置低些。用户在选择时，可以先了解每个套餐对应哪些参数，然后再确定用哪个套餐。当用户选择套餐（无需输入参数值）后，平台在后台组装对应套餐的实际参数，并调用第三方服务的接口。

遵循 RESTful 设计，HTTP方法映射对应的操作

在请求Header中加上通用信息

不管服务如何变化，总有一些信息是不变的，都要带上的。对于这些通用的信息，我们会将其放在Header中。请求参数（ request param ）中不包含这些信息，更专注于跟服务相关的参数。
这些通用信息包括：

鉴权串。如上文提到的 keystone 串，password 串等

用户ID。哪个用户在控制台要求插件平台发起此次请求

项目ID。例如，告知 MySql 服务，是哪个项目要求创建一个 MySql 资源。

来源。控制台（前台）页面，是哪个系统。用户可以在私有云平台上创建一个第三方服务资源，也可以在插件平台界面上创建。这是个辅助信息，没前三个那么重要。

约定请求参数格式

一份请求内容示例：

{
    "plan": "xxxx",
    "config": {
        "DISK": "SSD",
        "plan": "BASIC02",
        "MEMORY": "2",
        "REPLICATION": "0"
    }
}

在调用POST（创建）请求时，会带上如上参数。和响应格式的约定一样，也是采用 json，第一级是约定的参数名plan，config。所有自定义参数会放在config中。在平台管理页面，提供了对应的配置能力。

通过下图所示，配置请求的参数名

通过下图所示，配置套餐及各个参数对应的参数值。支持配置接口参数值及在页面显示给用户的文本值。

用户在使用第三方服务前，可以通过页面了解该服务。我们定义了一些关键信息，要求服务开发者填写：

插件名称。包含中文、英文名字。英文名字用于程序、接口的交互

类别

摘要。几十个字概括说明

插件特点。对摘要的简单补充

图标。可以美化页面，一开始担心开发者抱怨图标不好找。后来发现恰恰相反，很多很赞的图标。

套餐。

文档。详细的说明、使用文档。文档约定使用markdown，以带来更统一的文档阅读体验。

我们提供了一个页面，帮助第三方服务开发者管理自己的插件（服务），包括了以下模块：

信息管理

基础信息编辑

服务配置，包括接口url，请求参数，响应参数，套餐配置

一个基于markdown的说明文档编辑器

接口测试工具

贡献率图表。通过云平台总项目数、插件数、使用量等，按公式计算贡献率，以反映该插件的价值

用户列表。使用该插件的项目列表。

第三方服务接入的一个痛点，就是两方要一起调试，这会浪费双方很多时间。因此，我们设计了一个简单易用的web测试工具。

先晒一下界面

这个工具可以帮助开发者、平台管理员，快速测试第三方服务接口。打开该工具，可以看到：

请求url

请求body

期望返回

实际返回

测试结论

当用户点击右上角的“测试"按钮时，将按照图中所示的url及请求body进行测试，测试完毕后，将显示实际返回，并和期望返回做对比，得出测试结论。

实践证明，该工具有效提高了联调的效率。第三方服务通过该工具可以自己检查接口是否符合规范，而无需平台管理员介入。

首先，开篇提出现状，我们需要为云平台提供一个平台，专门用于管理、接入第三方服务。当平台和第三方服务联调相应接口后，服务才能正式上线，普通用户才能通过平台来创建对应的第三方服务资源。为了更快地测试、接入第三方服务，平台需要定义一套对所有第三方服务都行之有效的规范。

然后，展开解决思路如下：

我们先是梳理了不同服务在接入时，接口、操作类型、请求参数、响应格式的相同点及不同点，发现了RESTful设计理念和我们接口设计相当契合，因此引入了RESTful来定义接口规范：同个服务的不同操作类型（增删改查）对应同个Url，通过HTTP 方法来表达具体的操作类型。

请求参数、响应格式设计，努力求同存异，通过HTTP状态码来表达操作的结果，简单明了；而内容则约定为json格式——当前最流行的HTTP内容格式；在请求及响应内容的第一级，都是约定的参数名，将有差异，自定义的内容都指定放于某个指定参数中的第二级中，从而在内容格式上取得统一。

开发者通过页面填写自定义参数、各种套餐。这样平台就不用为了新接入一个第三方服务写代码，直接读配置，就能组装对应的请求格式。当用户选择套餐时，平台将把套餐对应的参数值发给第三方服务。

最后，为了方便联调，提高效率，还提供了一个强大的在线测试工具。当然，如果没有上述的规范，也没有办法形成标准的测试流程，没办法打造这款测试工具。