聊聊 API 管理-开源版到 SaaS 版

> API 管理这个话题近些年听到的频次越来越多，这本质上是个 web 领域的发展有关，也和开发协作方式有关--前后端分离代替了全栈工程师 hold all 的局面，强调的更多的是 API 复用、分工和协作细化。 > API 管理的重要性不言而喻，每家公司随着业务的发展，多多少少都会涉及到；从开源社区的产品到国内各类商业化产品，可以看到大家对于 API 管理是越来越重视的。 ## 为什么需要管理 API ### Little story 结合自身的开发经历，我们先讨论下，为什么需要管理 API - 1、在实习的时候是在一家小的游戏公司，人不多，一个产品；当时技术经理的安排是一个后端+一个前端的组合开发，大家都在一个办公室，接口 API 交付依赖的是“讲一声”；这种形式减少了接口定义、审核以及一些文档的编写，面向指定接口的一对一交付；其实这个过程很顺利，还可以培养同事之间的关系；直到有一天，我对接的前端同事离职了，来了一个新的伙伴，然后我们也刚好要产品升级；每当我改一个接口，前端同学或者测试同学就说，接口不行了。后来我也走了，换了新的后端，“口口相传” API 就断代了。  - 2、第二个 case 是做一个 web 项目(应用元数据管理)，前后端分离的；我们是先定义有哪些接口，然后再定义参数、返回结果以及这个字段的含义；是面向文档交付的；每个接口开发完之后发布到测试环境，然后他去编写前端接口调用测试；这种耦合度非常高，前端的节奏受制于后端的节奏。  - 3、前面两种面向的都是一个端，再到后来，开始做基础平台，面向的有 web、app（安卓、IOS），各种三方，我们使用了开源社区的 Yapi 做了私有化部署，能够基本满足日常的需求（也比较痛苦，后面会提到）。  ### API 管理带来的好处 从前一节的 case 来看，API 管理的过程是在逐步完善的，从以工程师视角管理到更规范化的基于管理工具的管理；“口口相传”会随着工程师的更替而逐渐失去管控，直到无法追溯；基于文档的管理，从实际情况来看，两次变更之后就会慢慢的弱化文档的地位（改一次接口，就得改一次文档），取而代之的还是工程师主导；还有一点是，不管是基于“口头协定”还是文档，接口在没有交付之前是不具备可测试性的，而且面向的主体单一，一旦使用端的数量多了，资源分散和协调的人力成本将指数级增长。 API 管理不仅仅是提高技术能力，而是帮助推动业务更上一层楼，好的 API 管理可以带给我们的收益是非常大的。 - **【敏捷开发和快速业务支撑】**：协助我们能够快速的创建、共享、监控和调整 API，不需要额外的协同沟通成本而导致生产力下降。 - **【工作流程自动化】**：可以从 coding 到 CI 再到 API 管理工作实现自动化同步，绕过繁琐的 API 设计、审核、测试沟通等等；与现有的基础设施绑定起来，提高效率。 - **【维护数据完整性和安全性】**：不会随着人员变动而导致 API 数据丢失，API 的变更可以通过管理平台的 log 逐一追溯。 <a name="Ai31e"></a> ## 我们现在是怎么做的，有哪些问题 关于 API 管理这块，我们现在还有专门的 API 技术工作组来负责统筹所有服务的 API 相关事项，包括设计规范、自动化工具套件建设、API 管理建设等等。但是由于多语言栈、历史接口文档零散、开源工具停止维护等原因，导致相关工作推进起来非常麻烦。 - 历史接口文档有的在 confluence，有的在飞书，有的在 yapi，维护不同工具之间数据一致性非常困难、低效。 - 随着使用的深入，开源产品功能上的一些 bug 会被放大（需要进行二次开发，修复版本问题、权限问题等等），而且开源产品的持续维护性没有保障，在统一工具上很难达成统一。 - 对于需要编排的接口，处理起来很麻烦，需要额外的指导文档，step by step，又会导致数据一致性问题产生（指导文档和接口在不同地方管理） 这些问题也迫使我们在不断寻求各种解决方案，也包括各种商业 API 管理工具的调研，以便于能够给我带来新的解题思路；国内目前企业级的主要 Apifox、ShowDoc、，国外有 boomi、apigee 等（国外的相较于国内的产品要贵不少）；下面主要从功能上对比当前使用 Yapi 和 在调研 Apifox（**公网 SaaS 版免费**）。 ## Apifox & Yapi 下面主要是从功能上来看，从持续维护方面来说，Yapi 是社区驱动，没有多少利益牵扯，从 github 上看已经有很久没有新的提交了，issue 也缺乏跟进（情怀很重要，但是吃饭更重要，维护一个产品真的很难，是需要给 Yapi 开发小伙伴点赞的）；Apifox 是商业产品，在持续维护和技术支持上不用怎么担心。 ### 快速部署 工具调研除了功能之外，最核心的是易上手性；从我们维护部署的 Yapi 来看，环境配置这块是有些复杂的，这一点网上也有相同的痛点<br /><br />单部署和环境配置来说，Yapi 有很多文章介绍，说明官方文档本身对于不同环境的适配性有点欠缺，毕竟免费。<br />Api fox 入手极简，这个是有点出乎意料的，不管是客户端版本和 Web 端，创建账户之后即可使用（托管 SaaS，屏蔽了这些环境和配置上的差异）。 ### 功能区分布 - YAPI  - Apifox  **结论：总体来说 SaaS 版本的 Apifox 相比于 Yapi 来说，功能面板更加丰富些；包括了项目统计，在线分享，代码生成等。操作上来说，Yapi 需要从分类 -> 项目 -> 接口，个人感觉内部的功能 tab 没有 apifox 的合理。** ### 接口详情 - Yapi  - Apifox  **结论：接口信息整体差异不大，功能上多了云端 Mock 和快速请求，Apifox 直观感受更加丰富和聚焦。** ### Mock 能力 - Yapi  - Apifox  **结论：区别不大，但是 Apifox 有独立的数据模型管理(**可复用的数据结构，定义接口返回数据结构及请求参数数据结构（仅 JSON 和 XML 模式）时可直接引用。支持模型直接嵌套引用，直接 JSON/XML 智能导入，支持 oneOf、allOf 等高级组合模式**)，Yapi 没有。** ### 数据导入导出 - Yapi  - Apifox  **结论：apifox 在支持的导入源上更丰富，可以满足企业的不同诉求。（Yapi 好像不支持 Swagger 1）** ### Special #### 1、数据库操作 支持读取数据库数据，作为接口请求参数使用。支持读取数据库数据，用来校验(断言)接口请求是否成功。<br /><br />这个其实挺有意思的，在很多情况下，我们的测试其实需要依赖具体的数据库才能模拟出更贴合实际场景的用例；测试用例上，大多都是基于 H2 这种内存数据库，而依赖 mock 和实际场景又会有一些差异；尤其对于多云环境部署的，不同的云提供的 DB 服务还有一些特殊（比如使用的数据库不同，有的是 Mysql，有的是 Oracle），代码层面的适配无法通过 mock 来体现，那 Apifox 这个就非常赞了。 #### 2、自动化测试 提供接口集合测试，可以通过选择接口（或接口用例）快速创建测试集。**这一点在前文的介绍中有说过，这个是我们当前的痛点之一，就是组合接口的自动化测试。** <br />更骚的是还能给出完整的测试报告（支持导出），再也不用担心前端同学说“你不行了”。<br /> #### 3、生成在线接口文档 我们当前对外部合作的三方是不友好的，由于业务迭代速度和一些定制化的需求，开放平台能提供的接口 API非常有限。大多数情况下，我们都是通过文档将接口的调用逻辑、参数及返回结果语义发送给外部用户（出于安全管控，外部没法直接访问我们的 API 平台，API 接口截图也会留痕）。<br />**Apifox 项目可“在线分享” API 文档，分享出去的 API 文档可设置为公开或需要密码访问，非常方便与外部团队协作，完成协作之后也不用担心合作方会把接口扩散出去（变更密码或者关闭授权）。** > **可以感受下：**[https://www.apifox.cn/apidoc/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285](https://www.apifox.cn/apidoc/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285) 1-3 所提供的能力确实是戳中了我们的痛点，这可能也是绝大多数公司所共有的问题，Apifox 这几点在产品上的设计个人觉得还是非常优秀的。 ## 总结 本文主要结合自身的一些经历以及当前工作中所遇到的问题，对正在使用的开源产品 Yapi 和在调研的 Apifox 做了一些对比和介绍；**整体来看 Apifox SaaS (免费版) 相较于 Yapi 来说，还是有不少优势的**。 如果是个人开发者，小团队，或者研发预算有限的公司来说（**没有任何功能限制，没有团队使用人数限制，也没有项目和接口数量限制**），白嫖即可；对于常规保密级别的项目， SaaS 版本其实已经够用了。如果对于安全和保密要求较高， 可以考虑私有化部署。关于 Apifox 更多可以见其官网 [www.apifox.cn](https://www.apifox.cn/?utm_source=liam)。