# API 管理的发展过程、痛点及解决方案
在过去，许多研发团队并不注重研发过程中的 API 管理，认为API管理无非是管理一下API文档，只需要用word文档或者wiki把API描述写一下，等到需要进行团队协作的时候再把API文档通过文件或者wiki的方式发给前端和测试人员即可。这时候的API管理方式粗放，我们把它称之为1.0时代。
但随着敏捷观念的不断普及，大家开始发现传统的API管理只侧重管理API文档是不行的，存在以下明显的问题：
1. API文档编写不规范：缺乏统一文档格式，简写、漏写或不写详细说明（开发人员总觉得自己看得懂即可）。
2. 储存平台不统一：公司内部每个项目团队都有自己的使用习惯，甚至一个项目内部可以同时存在多个API管理工具，平台不统一导致无法高效维护和协作。
3. 文档更新不及时：开发团队习惯于先开发后补文档，认为文档对于开发工作而已是一个附加的内容，导致更新不及时。
4. 变更历史不记录：由于没有及时维护文档，当需要回头检查项目或进行工作交接时就会发现看文档不如看代码，反而拖慢工作进度。
5. 测试人员无法快速编写测试用例：由于传统API文档仅仅是个文档，测试人员还需要使用其他工具编写测试用例。
6. 并没有降低沟通成本：由于上述原因，前端、后端、测试、运维等成员经常由于不清晰的文档而引发争论，有时候反而增加了沟通成本。
为了解决上述问题而出现2.0时代的工具，开始思考如何将开发与测试结合，比如通过代码注解生成API文档来减少后端开发编写文档的负担、可以基于API文档直接进行测试等。这个时代最突出的产品是 Swagger、Postman、Jmeter、SoupUI 等产品。
但是上述产品的设计基本是基于本地开发和仅为小型团队使用，因此当遇到越来越高的迭代速度和质量要求时便显得力不从心，从而出现以下问题：
1. 前端开发进度受制于后端；
2. 无法及时了解API变动；
3. 接口测试不方便；
4. 测试工作繁琐、重复；
5. 工作成果无法分享；
6. 测试工作不自动化；
7. 测试效果无法量化；
8. 测试工作被动等。
为了解决上述问题，Eolinker 推出新一代的 API 研发管理产品，帮助研发、测试及项目管理团队更好地完成 API 管理工作。
# 理论基础：文档与测试驱动开发（DTDD）
文档驱动开发指的是在开发之前先把文档写好，明确功能需求、入参出参定义、异常情况处理等之后再进行开发。这就好比我们在做题之前需要先了解清楚题目要求，否则不审题就下笔很容易导致最后返工。
而测试驱动开发指的是在开发之前先把测试方案/用例写好，要求开发人员开发的代码能够顺利通过测试，如果测试不通过则持续进行改进。这就好比我们考试前会先了解考试通过的标准，没有标准乱答一通肯定没有好结果。
以上两种开发方式进行结合后就是 Eolinker API研发管理平台 的设计理念：文档与测试驱动开发（DTDD）。简单地说就是：
1. 用标准文档代替口头约定和笔记文档，让开发、测试、运维、协作有迹可循；
2. 快速用测试结果推动开发进度，让团队沟通更充分、管理有事实依据，实现敏捷开发。
因此，在 Eolinker API研发管理平台 中，几乎所有的协作工作都是围绕着 API 文档进行的，当您创建了 API 文档之后，您可以随时查看 API 的改动情况、根据 API 文档发起 API 测试、编写 API 测试用例、创建 Mock API、进行 API 自动化测试等。
Eolinker API研发管理产品已经在包括奇安信、深信服、中化能源、纷享销客等知名企业中获得良好的使用效果，因此我们建议您开始尝试这种方式进行API管理工作。
# 初识 API研发管理平台
## 创建第一个 API 管理项目
在 Eolinker API研发管理平台 中，所有的 API 都是以项目的方式进行妥善管理，因此我们首先需要创建一个 API 管理项目。
同时我们也提供了一键导入功能，可以快速将Swagger、Postman、RAP、YAPI等产品内的数据快速迁移到 Eolinker 中。
## 创建 API 文档
在 API研发管理平台 中，您可以通过三种方式来创建API文档：
1. 手动创建API文档，API研发管理平台提供了非常全面的API文档格式，能够详细记录您的API信息。这种方式适合所有用户，并且也是我们推荐的方式。
2. 关联项目与Swagger URL，API研发管理平台自动从该地址获取最新API文档。这种方式适合之前已经在使用Swagger，并且倾向于将文档写在代码注解中的用户。但这种方式会带来代码入侵的问题，让代码中加入了许多无关的信息从而增加维护成本。
3. 关联项目与代码仓库，API研发管理平台自动从代码仓库中扫描代码注解生成API文档。目前这种方式支持Java以及PHP两种语言。这种方式也会带来代码入侵的问题。
当我们创建好 API 文档之后，可以在 API研发管理平台 中看到清晰的 API 文档信息，并且可以在此基础上进行测试API、编写API测试用例、编写Mock API、管理API版本等等的操作。
## 一键发起 API 测试
当我们创建好 API 文档之后，可以立刻对该 API 进行测试，API研发管理平台 提供了以下主要特性来帮助测试人员快速发起 API 测试：
1. 支持本地测试、局域网测试、在线测试等；
2. 支持一键切换测试环境，使用全局变量、增加额外请求参数、改变请求地址等；
3. 支持直接在界面编辑JSON、XML请求数据，不再需要手写JSON、XML等数据结构；
4. 支持将测试数据保存为测试用例，以后可以直接使用测试用例进行测试；
5. 支持批量测试 API，比如测试登录接口的多种情况并且返回实时测试数据；
6. 支持在测试过程中编写代码进行签名、加解密、生成随机数据等操作；
7. ...
> 下图：在测试界面可以直接编写JSON数据。
> 下图：一秒切换测试环境并且发起测试。
## 批量测试多个 API 用例，解放测试劳动力
在以往的协作方式中，测试人员工作总是排在最后进行，无法参与项目讨论，无法进行快速大范围回归测试，甚至无法按时完成测试任务，导致项目延期或带着忐忑上线。
在 API研发管理平台 中，由于协作是基于 API 文档进行的，当后端开发人员将 API 文档写好之后，测试人员就可以马上介入，在 API 文档的基础上编写测试用例，让测试工作前移。
当 API 开发完成之后，测试人员可以一键将 API 的测试用例全部测完，并且得到详细的测试报告。后端开发只需要看到测试结果就能够知道自己的 API 是否满足测试需求，如果有异常则可针对性改进。
当 API 发生改变后，测试人员只需要一键即可进行 API 回归测试，真正解放劳动力。
通过上述方式，后端和测试人员可以进行更紧密地沟通，让测试驱动开发完成。
> 下图：批量测试 API 的多种数据情况，并且获得详细测试报告，可以在报告中查看API异常原因。
## 构建 Mock API，让前端摆脱后端束缚
在瀑布流开发模式中，如果前端开发人员需要进行页面对接，需要后端先完成 API 的开发工作，因此前后端开发的进度会互相影响。
通过 Mock API，您可以事先编写好 API 的数据生成规则，由 API研发管理平台 动态生成 API 的返回数据。开发人员通过访问 Mock API 来获得页面所需要的数据，完成对接工作。
Mock API 支持根据不同的请求参数返回不同的 HTTP Status Code、Header、Body等数据。您可以在一个 API 文档里创建多个Mock API ，模拟前端发起的各种请求，方便对前端逻辑进行校验。
当项目正式发布时，只需将 Mock API 的地址前缀替换为实际的访问地址即可。
比如：同一个项目中的Mock API的地址前缀是相同的（如mock.eolinker.com/uasyd1/…），因此可以在代码中将Mock API的地址前缀作为全局变量，项目上线时仅需替换变量的值即可改变整个项目的 API 请求地址前缀。
> 下图：该API创建了多个Mock API，前端可以传递不同的请求参数获取相应的返回结果，比如用户名为 jack liu时返回登录成功，用户名为 percy时返回登录失败或随机字符串。
## 当 API 文档发生变更时自动通知相关成员
许多用户在维护 API 时，经常遇到 API 文档变更了，但是前端和测试人员却不知道的问题。为了解决这个痛点，API研发管理平台 提供了变更通知功能，当 API 发生变化时通过邮件和站内信自动通知相关成员，并且显示变更的内容。
并且在 API研发管理平台 中，我们将 API 的状态划分为以下阶段，方便成员在查看 API 文档时了解 API 当前所处的状态。
| 状态 | 描述 |
| ------------ | ------------ |
| 已发布 | API 已发布，可正常使用 |
| 设计中 | 等待或正在设计 API |
| 待确定 | API 已设计完成，等待相关成员确定 API 的内容 |
| 开发 | API 已确定内容，等待或正在开发 |
| 对接 | API 已开发完成，等待或正在对接 |
| 测试 | API 已对接完成，等待或正在测试 |
| 完成 | API 已测试完成，等待发布 |
| 异常 | API 出现异常，需要尽快排查 |
| 维护 | API 维护或升级中 |
| 废弃 | API 已废弃，不可正常使用 |
结合 API 变更通知的功能，我们就能够实现：
1. 当API状态变为“开发”时，通知后端开发；
2. 当API变为“对接”时，通知前端进行对接；
3. 当API变为“测试”时，通知测试人员进行测试；
4. 等等...
> 下图：设置当API删除或异常时，通知某位成员。
## 对 API 文档进行评论标注
您可以直接在 API 文档上发布评论，所有的沟通内容都会跟随 API 文档保留下来并且按照版本分类好，而不是零散地存在各种聊天工具中。这样避免后期沟通时找不到依据而浪费时间。
> 下图：在 API 文档中直接发表评论，并且@了项目中的另一位成员查看。
## 查看、回滚、对比API编辑历史
API研发管理平台 中还提供了非常强大的 API 版本管理功能，您可以随时回滚到任意一次 API 文档版本，并且还可以对比两个版本之间的差异。
当无法用语言沟通更新了什么时，不妨试试版本对比~
> 如下：当前版本相比历史版本，删减了某些参数，会在界面中以红色标出。
## 除此之外
API研发管理平台 的功能还远不止如此，您可以在项目中进行严格的人员权限管理、API状态码管理、项目文档管理、测试环境管理等等，一切都是为了让团队协作能够更加轻松高效。
网友评论