API 治理

  • 5 分钟

API 治理的定义是跨所有组织 API 大规模定义和应用标准、策略和流程的做法。 API 中心使你能够通过以下操作完成该目标：

  • 跟踪 API 元数据，包括 API 标题、说明、版本、定义和部署。 此外，还可以指定你自己的自定义 API 元数据（如实时站点信息、源代码管理存储库等），以跟踪对组织重要的元数据（如前面的模块中所示）。
  • 确保所有 API 都设计为符合组织 API 设计理念
  • 确保及时检测具有中断性变更的 API 版本，以便无缝推出和与 API 使用者通信

在本单元中，我们将了解如何通过 API 中心大规模配置 API 治理。

先决条件

若要使用 API 中心治理 API，你需要：

  1. 安装 Azure CLI。
  2. 安装 Azure Developer CLI (azd)。
  3. 在订阅中注册事件网格资源提供程序。 如果需要注册事件网格资源提供程序，请参阅订阅合作伙伴使用 Azure 事件网格发布的事件。

API 设计一致性

API 平台团队通常负责为 API 生产者定义一组准则。 API 中心让你能够通过使用 Spectral 开源 Lint 分析引擎定义规则来编写 API 准则。 默认情况下，API 中心附带了提供的 Spectral 规则，但你始终可以构建自己的规则集或利用庞大的开源规则集社区。 每次上传 API 定义时，API 中心都会使用提供的规则集运行 Spectral Linter，以检查 API 定义是否符合规则。 它会生成 API 符合性报告，可在 API 中心查看。

若要为组织配置 API 设计符合性：

  1. 克隆 GitHub 存储库并在 Visual Studio Code 中打开它。

  2. 将目录更改为存储库中的 APICenter-Analyzer 文件夹。

  3. 在 resources/rulesets 文件夹中，可以找到一个 oas.yaml 文件。 此文件反映了你当前的 API 样式指南，你可以根据组织需求和要求修改它。

  4. 使用以下命令通过 Azure Developer CLI 和 Azure CLI 进行身份验证：

    azd auth login

az login

  5. 运行以下命令，将 linting 基础结构部署到 Azure 订阅。

    azd up

  6. 按照提示提供所需的部署信息和设置，例如环境名称和 API 中心名称。 有关详细信息，请参阅“使用 Azure Developer CLI (azd) 运行示例”。

    注意

    部署可能需要几分钟。

  7. 部署完成后，在 Azure 门户中导航到 API 中心。 在左侧菜单中，选择“事件>事件订阅”以查看已创建的事件订阅。

现在可以将 API 定义文件上传到 API 中心，触发事件订阅并运行 linting 引擎。

显示 Azure 门户中 API 分析合规性报告的屏幕截图。

左移 API 治理

最成功的治理计划总是包括开发人员自己。 通过应用传统的左移原则，API 平台团队可以确保 API 生产者确切地知道在开发周期早期发布 API 所必须满足的要求。 这样可以减少在开发周期的后期修正不符合的 API 的需求，从而节省宝贵的开发时间。

Visual Studio Code 的 API 中心扩展为 API 生产者提供了在生成 API 时直接在 Visual Studio Code 中运行 API 设计符合性检查的体验。 此外，API 生产者可以使用中断性变更检测功能来检测更改何时可能导致 API 使用者经历中断性变更。

Visual Studio Code 中的 API 设计符合性

API 中心扩展与 Spectral 集成，它是一项支持 OpenAPI 和自定义规则集的 JSON/YAML Linter。 该扩展让开发人员可以严格遵循提供的或推荐的 API 样式指南，确保不同团队开发的所有 API 的一致性。

注意

需要安装 API 中心和 Spectral 扩展才能使用此功能。

若要激活，

  1. 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 输入“Azure API 中心：设置活动 API 样式指南”，然后按“Enter”。
  2. 选择提供的默认规则之一，或者，如果你的组织已有样式指南，请使用“选择本地文件”或“输入远程 URL”，以在 Visual Studio Code 中指定活动规则集。 按“Enter”。 显示在 VS Code 上设置 API 样式指南的选项的屏幕截图

设置了活动的 API 样式指南后，打开任何基于 OpenAPI 或 AsyncAPI 的规范文件会触发 Visual Studio Code 中的本地 Lint 分析操作。 结果会在编辑器中内联显示，并在“问题”窗口中显示（“查看”>“问题”或 Ctrl+Shift+M）。显示 VS Code 上 Lint 分析检查结果的屏幕截图

检测 Visual Studio Code 中的中断性变更

发布会破坏使用者生产工作流的 API 版本会导致不可靠和失去信任。 API 中心扩展（使用 Optic）让开发人员可以轻松比较任何两个 API 版本，并在部署之前检测向 API 引入的任何中断性变更。

注意

需要安装 Optic 才能使用此功能。 使用以下命令安装。

*npm install -g @useoptic/optic*

那么：

  1. 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 键入“Azure API 中心: 检测中断性变更”，然后按“Enter”。
  2. 选择要比较的第一个 API 规范文档。 有效选项包括在 API 中心、本地文件或 Visual Studio Code 的活动编辑器中找到的 API 规范。
  3. 选择要比较的第二个 API 规范文档。 有效选项包括在 API 中心、本地文件或 Visual Studio Code 的活动编辑器中找到的 API 规范。

Visual Studio Code 会打开两个 API 规范之间的差异视图。 任何中断性变更都会在编辑器中内联显示，并在“问题”窗口中显示（“查看”>“问题”或 Ctrl+Shift+M）。显示在 VS Code 上检测中断性变更的屏幕截图