API管理平台之系统设计篇

Original 董威一 58技术 2022-03-15

导语

根据接口开发过程中的一系列痛点，提供接口文档管理，接口Mock，接口调试、测试等有效解决方案，使前后端接口相关工作更加高效。

背景

互联网的高速发展，API变得至关重要。随着API数量持续增多，我们发现在API文档维护，接口调试，用例编写、管理，数据Mock等方面工作效率是非常低下的，基于此背景，58Api管理平台（Aapi平台）应运而生。

API解决方案

58接口类型主要分为HTTP和SCF两种。简单介绍一下SCF，SCF （Service Communication Framework）是58自主研发的RPC框架，致力于在分布式环境下提供高性能、高可靠、多语言和透明化的解决方案。

我们期望有一个完整的接口工具，可以支持两种接口的全研发流程，并整合接口开发过程中的所有工具。在说方案之前，先总结一下在开发过程中的一些问题，比如：

1、接口字段变更，前端和测试同学消息滞后；

2、前端开发完成，后端服务尚未完成，前端同学无法自测；

3、请求参数特别多时，构造一个请求非常耗时，API文档已录入参数，测试时又要重新写一遍，产生大量重复工作；

4、scf接口测试测试同学需编写大量的java代码，并手动构建，用例编写成本高；

。。。。。。

以上问题出现在项目的不同阶段，导致工作效率降低，基于这些痛点，我们制定了Api综合解决方案，如下所示：

整个系统以产品方向维度划分业务模块，每个产品方向可创建多个项目，权限管理有效的对各产品方向及各项目进行隔离。项目成员在所在项目下创建接口，编写接口文档，完成接口信息录入后，一切都可以Run起来了。前端同学可以Mock接口，通过模拟数据和后端服务并行开发。后端开发同学可以进行接口调试及自测，平台历史模块可查询测试记录，通过回填功能，测试同学可在研发自测基础上修改参数值，有效节省了测试时间。

通过任务方式对用例进行分类管理，可执行任务，查看结果报告。平台还支持Excel和PostMan用例的批量导入功能。

环境配置模块和公司四套环境保持一致，分别为：测试环境、沙箱环境、稳定环境和线上环境。接口测试及任务执行时选择特定环境，自动完成环境切换。测试环境配置效果如下图所示：

数据看板模块从产品、任务、用例和人员四个维度提供统计数据，可查看本周或近一个月的数据，亦可进行数据对比：

整个方案的设计过程，不仅需要考虑API工具的整合，还需结合整个项目流程，把工作流转的各节点和自动化工具有效结合，如下图所示：

根据项目成员角色，我们把平台用户角色分为五类：PM、RD、FE、QA和游客。

工作流转过程为：

1、项目成立初期，首先由管理员创建产品方向；

2、随着后续的迭代，每个版本由PM创建项目；

3、技术设计阶段，由RD同学创建接口，编写接口文档；

4、开发阶段，RD同学可进行接口调试/自测，同时FE同学Mock接口，和后端接口并行开发，QA同学开始编写接口用例。

5、提测后，QA同学进行接口测试，并创建用例集任务，用于在预上线阶段回归验证及后续发布后的线上验证。

项目管理

随着版本的迭代，API数越来越多，如何把接口进行分类？回顾整个开发流程，接口依附于项目做变更，也就是先有项目，再有接口变更，而项目又依附于某个大的产品方向。所以这部分的设计思路是，按某一产品方向下的项目为划分，来创建管理接口。

项目管理又涉及权限问题，不同产品方向之间或同一产品方向下不同项目之间能够做到有效隔离。Aapi把扁平化管理模式引入到产品权限管理中，超级管理员拥有最高权限，并将权限分给若干产品方向管理员，超级管理员只需管理产品方向管理员即可；产品方向管理员拥有产品方向下的所有权限，对产品方向及项目负责，并可将权限分给若干项目管理员，项目管理员拥有项目下的所有权限。

单接口测试

系统支持http、scf两种接口测试，如下图所示：

http接口测试大家通常都会使用postman等类似的工具，所以在GUI交互设计上借鉴了postman的风格。目前平台支持get、post请求，支持http，https两种协议，支持上下文关联接口，支持登录功能。

SCF接口测试方案在《API管理平台之SCF服务测试篇》会详细介绍，大家敬请期待！

历史记录模块可查看、编辑测试记录，还支持回填功能，回填后在历史测试数据基础上做简单修改，即可继续测试。

用例列表可搜索用例、查看用例详情。还可编辑、删除用例，废弃、启用用例，同时也支持回填功能。

1、登录过期

接口在请求时，往往需要登录。仿照postman可以把cookie信息写到header中，但问题来了，为了保障登录的安全性，一段时间后PPU会失效，导致用例执行失败。如何解决这一问题呢？58中台提供了通过用户名、密码生成登录信息的接口，在header模块录入用户名、密码，后台调用此接口动态生成登录信息，可解决cookie失效问题。但又会引发另外两个问题：用户名、密码重复录入和账号安全问题（用户密码作为参数输入，直接暴露在GUI页面）。最终的解决方案是把账号作为配置统一管理，同一账号一次录入多次使用，密码隐藏显示。

2、接口上下文关联

例如被测接口：获取车系，关联接口：获取某品牌ID，获取品牌ID接口的返回值某字段是获取车系接口的入参。结合Aapi平台，可把关联接口分为两种情况，一种是平台已有接口，另一种是新接口。新接口需要调试，验证返回数据正确性，为避免页面切换，影响体验，在同一窗口提供调试入口，调试成功一键关联。关联后，返回结果通过JsonPath获取期望字段value数据，如下图所示：

已关联的新接口，在历史记录中直接筛选即可，如下图所示：

另外一部分是平台已有接口，通过接口名或用例ID查找到已有用例进行关联，如下图所示：

另外有些公共接口，如城市ID、城市名称、类目ID等，通过筛选用例方式会降低效率，平台直接封装一键生成，如下图所示：

3、断言方案

列表、详情信息展示是QA关注的重点，帖子相关接口返回往往是数据量较大的json串，json串的精准验证便是我们关注的一个重点。内容准确性验证是最常见的断言方式，采用in的方式断言，如果接口返回类型是字符串，并没有歧义。但对于json串，不同的JsonPath可能有相同的value，断言不够严谨。我们把数据类型分为两种：Json和非Json（Text），Json数据在断言时，需要关注JsonPath，提供JsonPath和期望值，这样可精准断言。

还有一些场景，列表页第一页共展示150条帖子，需要验证接口返回的帖子总数。若接口提供Count字段，直接断言value值即可，但有些返回值并未提供这样的字段，需要统计List的长度。我们的解决方案是提供Length断言类型，输入JsonPath和期望返回的帖子总数，即可断言。另外二手车帖子可根据价格区间进行筛选，那么如何验证返回的所有车源都在此价格区间呢？同样平台提供了数据区间断言类型，输入JsanPath和期望的数据区间。断言示例如下图所示：

批量用例测试

系统通过任务对用例进行分类和管理。测试创建任务时，选择测试类型，HTTP接口测试或SCF接口测试，然后选择用例集，系统调起当前产品方向下所有接口，根据接口及用例标签筛选用例集，完成任务创建。平台还支持同一任务包含HTTP及SCF两种接口用例，选择某一接口类型用例集后可追加选择另一种接口类型用例集。通过配置中心选择测试环境，可运行任务。平台还提供了结果报告和运行历史查看功能。

目前支持四种任务调度方式：手动触发、提测触发、上线触发和定时触发。

提测触发：关联任务，定时监听提测版本部署状态，如提测成功，且版本更新触发任务执行。

上线触发：关联任务，定时监听发布状态，如发布成功，且版本更新触发任务执行。

定时触发：选择时间间隔，定时触发关联任务。

成果

API 接口管理平台极大的提高了研发效率，提效点总结如下：

1）后端开发：规范接口文档，丰富开发自测方案，提高开发质量；

2）前端开发：mock方案，解决前期模拟数据问题，便于调试，并行开发；

3）用例编写：QA无需编写测试代码，只需关注测试设计，学习成本低；

4）测试方面：接口文档和接口测试采用同一数据源，测试阶段无需手动录入接口字段；

5）测试方面：QA在RD自测基础上，只需简单字段修改即可完成测试，减少时间成本；

Aapi接口管理平台已推广到整个汽车技术部。目前共创建19个产品方向，80个项目，237个接口，接口Mock次数超过1500+次，累计用例2500+条，重点接口功能覆盖率达62%。