当 Erda 遇上 API 生命周期管理，好戏开始了！

作者 ｜ 陈忠润
来源 ｜ Erda 公众号
​

写在前面

API 全生命周期管理（Full Life Cycle API Management）是指对 API 从规划、设计到实施、测试、发布、运行、调用直至版本变更与退出的整个周期的管理。
​
一般来说，API 全生命周期可以分为三个层面和六个阶段。
​
三个方面是指：设计，实施，管理，如下图所示：

Mulesoft 对 API 管理三个层面的图示
​
六个阶段是指：
​

• 规划与设计阶段
• 开发阶段
• 测试阶段
• 部署与运行时阶段
• 运维监控阶段
• 版本管理与弃用阶段

用以支持 API 全生命周期管理的工具应当具备以下能力：
​

• API 集市，用于 API 提供者发布文档展示应用程序的服务能力，API 的使用者查阅服务接口进而开发客户端。
• API 网关和访问管理工具，用于 runtime 管理、访问管理、安全管理、数据收集等。
• 监控管理工具，用于监控 API 相关指标。
• 接口测试工具，用于测试接口。
• API 设计工具，用于设计和编写 API 文档。

近年来谷歌收购 Apigee、Red Hat 收购 3scale 等事件无一不在证明 API 生命周期管理越来越被业界所重视。
​
如下图所示，是 Ganter 出具的 API 全生命周期管理“魔力象限”相关报告：
​

Magic Quadrant for Full Life Cycle API Management by gartner.com
（图片来源：http://gartner.com）
​
魔力象限将参与角色分为四大象限：
​

• 领导者（第一象限）
• 挑战者（第二象限）
• 观望者（第三象限）
• 探索者（第四象限）

我们可以看到：Google、Mulesoft、Microsoft、IBM、Kong 等众多熟悉的身影出现在了领导者第一象限；Amazon Web Services、TIBCO Software、Broadcom 等也紧随其后。
​

不同阶段解读

API 管理的核心是需要服务 API 的整个生命周期并启用关联的生态系统。 API-First 方法将 API 视为产品并对其进行管理，强调整个生命周期的重要性。通过精心设计、管理和维护的 API 可为开发人员提供良好体验，为组织带来价值。
​
API 全生命周期管理设计的产物是 API 文档，实施的产物是 API 的服务实例，它们都是被管理对象。下面我们将针对 API 生命周期管理的不同阶段进行详细解读。
​

1. 规划与设计阶段

规划与设计阶段要规划应用程序功能，设计 API，编写、评审以及发布 API 文档。
​
当开始规划应用程序新的功能点时，就要着手构思应用程序要呈现怎样的 API。API 涉及哪些资源、哪些操作、什么样的权限、什么样的场景等等，都是这个阶段的思考重点。设计 API 时需要充分考虑，如接口易用性、实现难度、价值等。如果不在此阶段思虑充分，就会设计出不可靠的 API，以至于开发出“腐烂”的代码和不可靠的功能，为组织带来风险。
​
设计阶段共有四个主要任务：
​

1. 设计：确定业务流程和需求，对资源合行为进行抽象。
2. 建模：API 资源建模，API 操作与方法建模，请求/响应有效负载/代码建模等。
3. 反馈：开发人员间互相反馈，完善设计稿。
4. 验证：根据开发人员的反馈适当修改 API 设计，继续验证。

API 设计的目标是产生一份 API 协议，一般是一份具有可读性的 API 文档。这种先行设计 API 的方法被称为“API-First”。
​
API-First 是 DevOps 实践中发展出来的，在项目开发中致力于开发出一致可重用的 API 方法论。顾名思义，API-First 就是 API 先行，在计划开发应用程序时，先设计应用程序接口，然后实现接口功能。与之相对的是 Code-First，即先实现应用程序功能，然后在此基础上根据外部需求抽象出接口。
​
相较于 Code-First，API-First 更加敏捷。API-First 的思路使得功能易于解耦，更加适合微服务拆分；API-First 通过接口发布功能，小巧轻快，能提高迭代速率；通过文档协调开发者间协作，可以提升开发效率；通过版本化的 API 持续集成，符合 DevOps 的精神内核。
​

2. 开发阶段

开发阶段要实现规划与设计的全部接口，实现应用程序全部新功能。
​
开发阶段是产品功能从无到有的核心阶段，应用程序开发人员根据完善的 API 设计文档进行并行开发，以节约开发时间，提高开发效率。设计合理、表述清晰、风格统一、高一致性的 API 能令开发人员如沐春风，缩短学习时间，降低学习成本。
​
利用 API 管理工具，可以根据 API 文档生成服务端和客户端代码，多语言甚至框架级别的代码生成能力，能节约开发人员的编码成本；还可以生成接口测试代码和脚本，使得开发人员不必专门编写接口测试代码或者只需花少量的时间修改即可完成接口测试编写工作。
​
基于 API 文档的 mocking service 能很好地协调服务端和客户端开发人员的协作，当服务端 API 功能还未实现时，客户端开发人员可以利用 mocking service 调试开发，待服务端开发人员将阶段性成果部署到开发环境时，只需修改下客户端软件服务域名就可以联调。API 文档支持可编程 mocking，只需在文档中配置不同参数，就可以模拟不同场景下的接口响应，比如通过配置响应码模拟是否登录，通过配置 User-Agent 模拟不同来源的客户端等。
​

3. 测试阶段

测试阶段要对已实现的接口进行充分测试，验证接口功能是否按预期实现，它要求接口可用、准确、稳定、可靠（也有人将开发和测试作为一个阶段，因为开发测试总是交织在一起的）。
​
API 开发完成之后，要经过几轮 API 测试以确保其正常运行。如果测试顺利完成，则可以继续进行下一个生命周期阶段，但大多数情况下，API 会经历几轮测试和调整，然后再进行部署。API 全生命周期管理要求 API 测试自动化，因此不能仅仅依赖接口测试脚本、桌面接口测试工具来做接口测试，集成到持续交付和部署的 DevOps 流程中的自动化测试工具在这里至关重要。
​
以往的许多 API 管理工具，将 API 生命周期各个阶段割裂开来。就开发阶段与测试阶段而言，接口测试往往面临许多痛点，比如：
​

• 重复定义的问题：在 API 设计阶段，就已经设计过 API 接口，在测试阶段，又将接口要素重新编写一遍，从 URI 到各种参数，全要重新填写一遍。
• 编排接口能力不足的问题，一些传统的接口测试工具虽然能测试单个接口，但却将接口孤立的看待，没有将接口有机编排起来，难以串联成一个个完整的场景。

所以，必须将 API 生命周期的各个阶段有机地联系起来。用户在编写测试用例时，直接引用文档里的接口，就避免了重复定义的问题；在设计 API 时充分周全地建模，会让编排就变得十分自然。

4. 部署与运行时阶段

运行时阶段要将实现了特定 API 的应用部署到相应的环境，使 API 作为服务实例正式向外提供服务。
​
运行时阶段，可以从 API 角度对实例进行访问管理，授权客户端对实例进行访问，并限制它们的访问流量。还可以决定哪些接口可以被访问、哪些接口不可以被访问。每一个 API 的价值都值得单独考量，从商业运营角度看：

• 流量：可以给初级用户开放少量流量，给重要用户开放大量流量。
• 接口：给初级开放初级接口，给重要用户开放高级接口。

5. 运维监控阶段

运维监控阶段要维护和监控实例的运行状态，对 API 的调用量、错误分布、响应时间、流量大小等维度进行监控。通过对接口的运维监控，可以调整实例的服务质量，如流量大小、访问限制等，还可以分析接口压力，调整服务资源。
​

6. 版本管理与弃用阶段

版本管理是指添加新版 API、删除旧的 API、为版本标记语义化版本号等工作。弃用是指将某版本的 API 标记为弃用。由于服务的迭代更新，原来的 API 不再适应需求时，须需要进行版本管理或弃用。API 的订阅者收到版本变化的消息后，可以重新决定如何使用该系列接口。
​

Erda API 管理平台

API 管理产品构成
​
Erda API 管理产品形态如图所示，是一个以 API 集市为中心的，包含 API 设计、API 访问管理等贯穿 API 全生命周期的产品矩阵。
​
下面，我们从 API 设计开始，逐一了解 Erda API 管理是如何在 API 全生命周期中发挥生产力的。

1. API 设计中心

在 Erda API 设计中心，你几乎可以零学习成本地使用该产品编撰你的 API 文档。基于可视化的编辑方式，通过直观而友好的交互界面，不需要了解任何 REST API 规范_标准_，也无需具备任何关于 API 描述语言的知识，就可以轻松编写出一份具有专业水平的 API 文档。
​
而市面上现有的一些 API 设计平台，大多要求你必须充分了解 OAS 协议，并需要一个字母一个字母地敲出一篇 OAS 文档。光是学习 OAS 或 RAML 语言，就足以令人生畏。另一些平台虽然支持以比较友好的方式设计 API，但却使用私有协议或基于 OAS 定制个性化协议，破坏了文档兼容性和 API 文档协议生态，其输出的文档在其他平台甚至不能正确预览。
​
Erda API 设计中心完全兼容标准的 OAS3 协议，在其他平台托管的 API 文档、代码中生成的 swagger 文件等，都能轻松迁移到 Erda。Erda API 设计中心输出的文档完全符合 OAS3 协议标准，任何时候你都可以交付、迁出文档，一次设计，随处使用。
​

在 Erda API 设计中心可视化地设计 API 文档，完全符合主流协议，一次设计，随处使用
​
Erda API 设计中心将 API 文档托管到代码仓库中，使得接口描述和接口实现紧密绑定。开发人员进入代码仓库，就能设计 API。这一设计是基于将 API 文档视作应用程序代码一部分的理念。如果视 API 为应用程序或软件系统的基础设施，那么 API 文档就是其代码。通过将文档托管到 Git 仓库，可以从文档的角度来对 API 进行管理。这样的理念是从 GitOps 的基础设施即代码思想中衍生而来的。
​

基础设施即代码（Infrastructure as Code，IaC）是使用声明文件来配置和管理基础设施、并将声明文件存储为代码的一种做法。使用声明文件将基础设施结构编写为代码，并将它们像存储应用程序开发代码一般存储在 Git 仓库中，借助于版本控制、代码审查、CI/CD 等 DevOps 最佳实践，来达到基础设施配置自动化的目的。

API 文档设计流程与代码开发流程一致，都完全符合 gitflow。比如当有新的 feature 时，可以切出一个新的 feature 分支，在这个分支上编写相应的接口文档，然后合并回 devolop 分支。
​
通过评审的 API 文档可以发布到集市，在一定范围内公开，作为各方参考的正式依据。API 文档的发布过程，就是 API 的 release 过程，表示对 API 的确认和公开，表达了该版文档的正式性。除了手动发布文档外，更多的是将 API 文档发布流程嵌入到 CI/CD pipeline 中，使文档的 release 与应用程序的 release 同步一致，确保文档总是描述当前真实的服务的接口。
​
因此，文档与代码一同托管，视文档为代码，就显得很有必要了。
​
文档托管到仓库中，意味着可以基于分支进行文档协作。不同用户编写同一篇文档时，只要从源分支切出新的分支，在新的分支上编辑文档，然后以 MergeRequest 方式合并回源分支。这样做有诸多好处。首先是易于协作，同一服务的不同接口负责人，随时可以设计自己负责的接口，又随时合并回去，不会相互影响，更不会相互阻塞。
​
其次是符合 gitflow 流程。很多情况下，开发者只关注代码遵循 gitflow，而没关心文档遵循 gitflow。这是因为没有把文档当做工程的一部分，没有将 API 文档提升到 API-First 的方法论高度。基于 gitflow，可以在 API 的生命周期中插入许多自动或手动的流程，如：

• 接口兼容性检查，检查更新后的 API 是否与之前的 API 不兼容；
• 接口评审，在新分支合并回源分支时进行评审，决定当前文档是否要合并到主要分支；
• 与数据模型定义脚本、接口测试模块联动等等

如果一个应用仓库下包含多个微服务，还可以分别为每一个微服务设计文档，并按服务名为文档命名。值得一提的是，Erda 推荐的一个最佳实践是，数据模型定义脚本也托管到代码仓库的非侵入目录中，按微服务名归类。这样在设计 API 时，可以与数据模型联动，将数据模型定义脚本中创建的库表导入到 API 文档中。这样的联动大大提升了 API 设计的便捷性，将接口与模型联系起来，丰富了接口字段的语义。
​

设计 API 时便捷地导入库表模型字段
​

2. API 集市

API 集市是 API 的门户，用来发布、归档、公开以及调试 API，是 API 管理的一部分。API 集市将 API 视作一种资产或资源，将其集中起来，任人选用，所以称为 API 集市。
​

• API 所有者将设计好的文档发布到集市，以便后续管理、监控。
• API 使用者在 API 集市查阅、探索、调试、订阅 API。

集市是 API 所有者和使用者完成“交易”的地方。

API 集市 - 阅读文档
​
API 所有者将文档发布到 API 门户，并版本化地管理起来。文档的使用者在这里可以：
​

• 查阅自己所需的接口。
• 订阅系列接口，以及时获悉接口变更的消息。
• 对 API 关联的实例调试调用。

文档所有者在 API 管理平台管理已发布的文档。他可以决定是否公开文档、公开哪些文档，还可以标记文档版本，决定何时发布新版、撤销旧版。同一个集市资源，通常包含多个版本的文档，这些文档描述的是同一系列接口集合。

API 集市通过语义化的版本号来标记这些文档。版本号格式形如 major.minor.patch ，其中：
​

• major 为主版本号，主版本号的变化通常表示发生了重大变更或不向下兼容的变更。
• minor 是次版本号，次版本号的变化通常表示增加了新特性，仍向下兼容。
• patch 是修订号，修订号的变化通常表示对现有版本作较小的、局部的修正。

除语义化版本号外，还有一个称为“版本名称”的版本标记，它一般是有自解释性的单词或短语，表示当前文档版本的命名。版本名称与语义化版本号中的 major 是一一对应的，也就是说，版本名称是主版本号 major 的“别名”。
​

比如 macOS 的某个版本号 Big Sur 11.2.2 ，其中“Big Sur” 是操作系统的版本名，“11”是该版本名对应的主版本号，2.2 分别是次版本号和修订号。

这样版本化管理的好处是：将 API 文档的增长与应用程序的增长一视同仁，可以从 API 的角度审视应用程序的功能。版本号解释了服务更迭间的兼容性和依赖关系，不管是所有者还是使用者，都能根据版本号语义清晰地了解服务的变更情况。
​
API 资源可以关联到具体的项目、应用和实例。通过这样的关联，可以从 API 集市中对实例发起调用，这在调试接口和测试客户端授权情况时非常有用。这种关联也使得可以从 API 资源角度对实例进行访问管理，形成非常直观的访问管理方式。

API 集市 - 资源管理
​
Erda 提供了企业级一站式 DevOps 解决方案，其自动化接口测试平台支持将测试用例和计划集成到 CI/CD 流水线中，每次集成时，都能触发所有接口测试，保障了集成效率和质量。
​
许多测试工具编写接口测试都有一个共同痛点，就是用例中的重要属性都需要逐个手动输入，如需要从别处拷贝用例的 URL，然后在工具中粘贴，又要手动输入 header、body、query parameters 等各种参数，十分繁琐。而 Erda 自动化测试平台与 API 集市完全打通，在编写测试时，你可以方便地从集市中挑选需要测试的接口，自动填写 URL、请求参数、响应参数，做到“文档即用例”。

搜索接口名称或URI，从 API 集市选择接口生成用例
​
API 集市完全支持 Swagger 2（OAS2）和 OpenAPI 3（OAS3）协议的文档，支持灵活的发布方式，可以通过本地上传发布任何来源的文档；可以在 DevOps 流水线中插入 action 发布应用程序生成的文档；还可以在 API 设计中心将设计好的文档一键发布。总之，任何时候，都可以轻松迁移到 Erda 平台上来。
​

3. 访问管理

API 访问管理是指在向外部开放接口时，对被调用的 API 进行管理、保护和审计。向外开放 API 时，往往需要鉴别、约束以及审计客户端行为，此时就要为 API 资源创建访问管理。访问管理的具体手段是客户端认证和 SLA 访问级别管理。
​

1）访问管理流程

访问管理的流程如下：
​

1. API 所有者在集市中将 API 集市与项目、应用及实例关联起来，形成 API 资源 - 实例 的关联。
2. API 资源关联到实例后，API 所有者为 API 资源创建访问管理，调用者就可以在 API 集市中申请调用该 API。
3. 所有者收到调用申请后进行审批，为客户端设置访问级别；获批的客户端获得访问资质，就可以从外部访问服务了。

API 使用方申请调用 API
​
这样的访问管理，实际上是联动了网关功能，但却不必把网关功能暴露在用户跟前，用户也不需要了解复杂的网关配置 —— 用户仅跟 API 打交道。
​

SLA 分级流控
​
获批的调用者可以在自己的客户端程序中使用客户端认证信息对服务进行访问，也可以在开发代码前先在 API 集市中测试访问效果，这个测试会发起对真实实例的访问调用，而不是访问一个 mocking service。还可以在访问管理中切换 API 版本，将请求转发到不同版本对应的服务实例上，从而在客户不感知的情况下进行 API 版本的升级或回滚。
​

关联了实例的 API，可以向实例发起调用测试这背后是基于网关的访问管理
​
API 访问管理可以从 API 视角，监控和审计接口流量。
​

访问管理首页可以查看当前版本的 API 流量概览还可以按客户端分别审计
​

2）客户端管理

客户端管理有两个视角：API 所有者视角和 API 使用者视角。

API 所有者和调用者间的交互都是通过客户端展开的：使用者用客户端申请调用，所有者授予、撤回、删除、调整客户端权限。

API 所有者在访问管理中按客户端查看流量审计
​

调用者视角的客户端管理页，可以在此处管理、审计客户端流量，申请变更 SLA，重置密钥等

在 Erda 平台实践 API 全生命周期管理

API 所有者（左）和使用者（右）的视角看 API 管理
​
API 设计中心在 API 设计阶段扮演着重要的角色，借助于 API 设计中心可视化的设计工具，API 所有者们可以方便地协作编写文档。接下来通过评审的 API 文档会被发布到 API 集市，如果文档仍有小幅度的修订，即可以追加修订版本的方式继续追加。
​
API 集市是进入开发阶段后经常光顾的地方。开发者在集市查阅文档，根据文档开发接口功能和客户端。API 集市暂无代码生成和 mocking 服务，后续会上线相关功能。对已绑定实例的 API 资源，API 使用者可以申请调用，在获得审批许可后可以在集市对实例发起调用测试。
​
测试阶段，API 所有者或测试人员在接口自动化测试平台编写、执行测试用例和计划。值得注意的是，测试驱动开发的理论要求一旦完成文档，就应当编写测试用例，而不是应用程序开发完成后。开发阶段开发人员应当随时调试测试，使接口功能通过测试用例。开发人员交付应用程序后，测试人员借助于接口测试平台对功能进行验收。接口测试还会被集成到 CI/CD 流程中，确保所有接口用例都被执行，且对应用程序的修改不会带来新的问题。
​
通过测试验收后，部署服务，进入部署与运行时阶段。这一阶段，可以在 API 集市中将文档与实例关联，从接口角度进行访问管理。访问管理的维度主要有：
​

1. API 资源与实例的对应关系，切换资源与实例的关系可以平滑地切换域名与实例的关联关系，从而在用户不感知的情况下对服务进行升降级；
2. 访问实例的权限，API 所有者通过调用申请审批机制决定授权哪些客户端可以访问服务，通过 SLA 限制不同客户端的流量。

运维阶段，API 所有者可以在访问管理查看 API 资源的流量概览，监控服务质量。API 使用者可以借助客户端流量审计监控名下客户端访问服务的情况。
​
版本管理与弃用阶段，API 所有者回到 API 集市，对 API 资源进行版本化管理，发布新版、删除错版、废弃旧版。
​
如果对于 Erda 项目你有其它想要了解的内容，欢迎**添加小助手微信（Erda202106）**加入交流群！
​

欢迎参与开源

Erda 作为开源的一站式云原生 PaaS 平台，具备 DevOps、微服务观测治理、多云管理以及快数据治理等平台级能力。点击下方链接即可参与开源，和众多开发者一起探讨、交流，共建开源社区。欢迎大家关注、贡献代码和 Star！

• Erda Github 地址：https://github.com/erda-project/erda
• Erda Cloud 官网：https://www.erda.cloud/