使用 DevOps 和 CI/CD 发布 API

适用于：所有 API 管理层级

随着企业 API 的战略价值，采用 DevOps 持续集成（CI）和持续部署（CD）技术已成为 API 开发的重要方面。 本文讨论了在 API 管理中采用 DevOps 原则需要做出的决策。

API DevOps 由三个部分组成：

下面讨论了 API DevOps 管道的每个部分。

API 定义

API 开发人员通过提供要应用于 API 的规范、设置（例如日志记录、诊断和后端设置）和策略来编写 API 定义。 API 定义提供在 Azure API 管理服务上预配 API 所需的信息。 该规范可能基于基于标准的 API 规范（例如 WSDL、 OpenAPI 或 GraphQL），或者可以使用 Azure 资源管理器（ARM） API（例如描述 API 和作的 ARM 模板）定义该规范。 API 定义将随时间而变化，应被视为“源代码”。确保 API 定义存储在源代码控制下，并在采用之前进行适当的审查。

有多种工具可帮助生成 API 定义：

• Azure APIOps 工具包提供基于 git 源代码管理系统（如 GitHub 或 Azure Repos）生成的工作流。 它使用 提取程序 生成 API 定义，然后由 发布者应用到目标 API 管理服务。 APIOps 目前支持 REST 和 GraphQL API。
• dotnet-apim 工具将格式标准的 YAML 定义转换为 ARM 模板，以供之后部署之用。 该工具侧重于 REST API。
• Terraform 是 Azure 资源管理器在 Azure 中配置资源的替代工具。 可以创建 Terraform 配置（与策略）以与创建 ARM 模板相同的方式实现 API。

还可以将基于 IDE 的工具用于编辑器（如 Visual Studio Code）来生成定义 API 所需的项目。 例如，有 90 多个插件可用于在 Visual Studio Code 市场中编辑 OpenAPI 规范文件 。 此外，还可以使用代码生成器创建项目。 TypeSpec 语言允许你定义云服务 API 和形状，并且具有高度可扩展的基元，这些基元可以描述 REST、OpenAPI、gRPC 和其他协议中常见的 API 形状。

API 审批

生成 API 定义后，开发人员将提交 API 定义以供评审和审批。 如果使用基于 git 的源代码管理系统（如 GitHub 或 Azure Repos），开发人员可以通过 拉取请求提交。 拉取请求会通知其他人对 API 定义建议的更改。 确认审批入口后，审批者会将拉取请求合并到主存储库中，以表示可以将 API 定义部署到生产环境。 拉取请求过程使开发人员能够修正审批过程中发现的任何问题。

GitHub 和 Azure Repos 都允许配置提交拉取请求时运行的审批管道。 可以将审批管道配置为运行以下工具：

• API 规范 Linter（如 Spectral），用于确保定义符合组织所需的 API 标准。
• 使用 openapi-diff 等工具进行中断性变更检测。
• 安全审核和评估工具。 OWASP 维护安全扫描工具的列表。
• 自动化 API 测试框架。

注意

Azure API 必须符合一组严格的准则，这些准则可以作为你自己的 API 准则的起点。 Spectral 配置可用于强制执行准则。

运行自动化工具后，API 定义由人眼查看。 工具不会捕获所有问题。 人工评审者确保 API 定义符合组织对 API 的要求，包括遵从安全性、隐私性和一致性准则。

API 发布

API 定义通过发布管道发布到 API 管理服务。 用于发布 API 定义的工具取决于用于生成 API 定义的工具：

• 如果使用 Azure APIOps 工具包，请注意，该工具包包含将 API 定义写入目标服务的发布工具。
• 如果使用 dotnet-apim，则 API 定义将表示为 ARM 模板。 Azure Pipelines 和 GitHub Actions 中提供了可用于部署 ARM 模板的任务。
• 如果使用 Terraform CLI 工具，您可以在服务上部署 API 定义。 为 Azure Pipelines 和 GitHub Actions 提供了任务。

是否可以使用其他源代码控制和 CI/CD 系统？

能。 所述过程适用于任何源代码管理系统（尽管 APIOps 明确要求源代码管理系统基于 git）。 同样，可以使用任何 CI/CD 平台，只要该平台可以通过签入触发并运行可与 Azure 通信的命令行工具。

最佳实践

设置用于发布 API 的 DevOps 管道没有任何行业标准可遵循，而上述工具也不会适用于所有情况。 但是，大多数情况都通过使用以下工具和服务的组合来涵盖：

• Azure Repos 将 API 定义存储在 git 存储库中。
• Azure Pipelines 运行自动化 API 审批和 API 发布过程。
• Azure APIOps 工具包提供用于发布 API 的工具和工作流。

我们遵循以下做法，在客户部署中取得了最大的成功：

• 为源代码管理系统设置 GitHub 或 Azure Repos。 此选项还决定了您所选择的流水线运行器。 GitHub 可以使用 Azure Pipelines 或 GitHub Actions，而 Azure Repos 必须使用 Azure Pipelines。
• 为每个 API 开发人员设置 Azure API 管理服务，以便他们可以将 API 定义与 API 服务一起开发。 创建此服务时，请使用使用情况 SKU 或开发人员 SKU。
• 使用策略片段以减少开发人员需为每个 API 编写的新策略数目。
• 使用命名值和后端来确保策略是通用的，可以应用于任何 API 管理实例。
• 使用 Azure APIOps 工具包，以从开发人员服务中提取工作 API 定义。
• 设置对每个拉取请求运行的 API 审批过程。 API 审批过程应包括中断性变更检测、Lint 分析和自动化 API 测试。
• 使用 Azure APIOps 工具包发布工具将 API 发布到生产 API 管理服务。

若要更详细地了解如何使用 APIOps 配置和运行 CI/CD 部署管道，请参阅 Azure 体系结构中心的通过 APIOps 自动部署 API。

参考

• Azure DevOps 服务包括 Azure Repos 和 Azure Pipelines。
• Azure APIOps 工具包为 API 管理 DevOps 提供工作流。
• Spectral 为 OpenAPI 规范提供 Linter。
• openapi-diff 为 OpenAPI v3 定义提供中断性变更检测器。