如何优雅地进行接口管理？（大厂内部分享）

Posted 2022-01-26 Java知音_

时间都去哪里了

敏捷迭代和团队协作，前后端分离的工作模式几乎是每个互联网公司的常规工作模式。

前后端分离，各自开发的优点很多，其中一项是它只需要提供一个统一的API接口，即可被web，ios，android等多个客户端使用，效率大大提高。

但生于敏捷，死于迭代，困于团队协作常常是这种软件研发模式的一大弊病。随着项目不断推进、变更，项目越来越大，维护成本也越来越高。

由于某些公司接口文档管理方式采用wiki及html，openapi形式，版本迭代较快，接口常常变更，成员间update和文档维护却常常跟不上。

在API管理方面越到后期越存在着可观且隐形的“人力资源”浪费：

1)文档老旧不可用，新人上手工作、熟悉项目靠“老人”的口口相传，造成人力双重浪费，团队成员自己的工作进度受阻，新人胜任任务的进度缓慢。

2)接口由于初期设计问题/功能扩展/需求变更问题而修改，但修改后往往难以及时同步到前端和测试等下游环节

3）接口在设计初期不规范，造成前端，测试在调试和测试理解上的困难，甚至部分接口需要重新返工

这些情况越到项目发展后期会越严重。以至于不少研发人员总是抱怨：写代码不累，沟通对接心累；工作不辛苦，就是命苦。

如何优雅地进行API管理

为了解决研发人员的问题，我们需要解决API管理中的各个痛点，换言之，一个完美的API管理工具应满足如下特征：

在接口设计阶段，能规范研发人员的接口设计

在接口调试阶段，提供多种功能充分调试，高度仿真实际工作情境

在接口维护过程中，维护成本低，且各项变更能及时update到下游工作环节的团队同事

一站式服务，一个工具就可完成接口的设计、调试、维护，测试过程，不需要反复导入导出，各个软件来回切换，提高效率。

最终的解决方案

笔者在网上找了很长时间，发现一款几乎能满足以上需求的解决方案软件--Apifox. 这个软件的主要特性：

可视化接口设计界面，支持 https 和 https 协议，遵循openApi和 Json Schema规范，各项http请求参数与接口描述直接填写即可。支持构建数据模型，可供多个请求参数复用。

媲美postman的接口调试功能，除此之外，还支持“零配置”mock高度仿真的业务数据，支持读取数据库

系统自动生成代码 根据接口及数据数据模型定义，系统自动生成接口请求代码、前端业务代码及后端业务代码

实时更新云端变更的数据到各个团队成员，避免数据不一致导致的重复工作和返工；代码更新和文档更新在同一软件全部完成，减少维护工作量

项目管理 为不同的项目角色分配不同执行权限，有效保护项目数据安全;支持openapi，postman格式的旧有项目导入apifox，实现项目无痛迁移，支持html格式，openapi等多种格式的接口数据导出。

接下来笔者再针对一些功能进行详细的介绍

1.接口设计

界面可视化，可以对接口信息进行编辑管理，get，post等常规的接口请求方法直接下拉框选择；query，body，header参数直接对应填写，返回参数支持JSON,XML格式导入，并能直接进行格式校验。接口描述部分支持Markdown格式的文本。

图片

2.接口调试

接口调试有两种模式，一种是不需要创建项目的快捷调试，直接校验接口请求 和返回参数， 一种是在项目里对单个接口调试， 这部分的功能基本等同于postman。可添加多种前后置操作：

图片

图片

校验返回response，检查返回状态和数据结构是否符合预期。

图片

图片

3.接口维护

当变更接口时直接在apifox内修改并生成新代码，同时说明文档就存放在同一个位置，顺手修改文档说明就变得非常方便。接口变更之后，协作成员能及时同步云端变更。

图片

4.项目管理

支持数据导入导出，自动生成接口代码

图片

图片

针对不同角色的成员，设置不同的数据权限。如后端研发可以修改接口数据，而前端和测试成员只有只读权限，项目外人员则只有访客权限只能查看到接口信息而无法查看数据类型。

图片

可针对开发调试，测试验证，线上使用配置不同的服务器：

图片

此外

Apifox不仅是一款针对研发人员的API管理工具，还能为测试人员提供接口测试，接口自动化测试，测试管理等一系列功能，后面有机会再为大家讲解。