作者 | 陈忠润
起源 | 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/_