自动化 API 交付——什么是 APIOps？

本章内容包括：

• 扩展 API 设计与交付所面临的挑战
• 将 DevOps 与 GitOps 应用于 API 的 APIOps 概念
• APIOps 的原则
• 使用 OpenAPI 进行 APIOps 的优势与挑战

许多组织都希望构建高质量、有良好文档、易于使用的 API，但在实践中却很难实现。
他们可能制定了 API 治理标准与治理职能，甚至采用了 设计优先（Design-First） 的 API 开发方法。
然而，即便如此，他们仍然会发现 治理标准与实际落地之间存在巨大的执行差距。

这种差距常常导致交付的 API 无法满足可用性和安全标准，缺乏完善的文档，不具备可发现性和可访问性。除此之外，这些 API 还可能存在性能、可靠性和可扩展性方面的问题。
在组织层面，他们的 API 开发过程可能既昂贵又低效，从 API 产品构想到投入市场的周期（Lead Time）非常长。

APIOps 旨在解决的，正是这种差距。
可以把 APIOps 理解为：通过自动化 API 交付工作流，更高效地 设计、构建、测试与部署 API 产品。

APIOps 将自动化引入到 API 定义和 API 配置文件的管理中，并将其整合到持续集成/持续交付（CI/CD）流水线中。它是一种基于 DevOps 与 GitOps 原则的 端到端 API 生命周期自动化 方法，帮助 API 提供者向 API 使用者交付更多价值（DevOps 与 GitOps 的概念会在后文解释）。

通过将手动 API 治理替换为自动化检查（如 API 代码规范检查、破坏性变更检测），APIOps 可以实现 API 设计治理自动化。
它还能通过基于 Git 控制的 API 配置部署，提高 API 发布的可靠性，并增强审计性、合规性，以及开发与运维团队在 API 部署过程中的协作。
这样一来，APIOps 既能提升 API 交付与部署的速度，又能通过自动化的标准治理和策略检查提高 API 的一致性。

下面我们用一个例子来说明。

1.1 扩展 API 交付：问题的出现

假设有一家虚构的电商公司——BookInc，经营着一家在线书店。
他们的核心产品 BookStore API 是一个云原生平台，允许合作伙伴替 BookInc 推广图书。

在 API 项目初期，BookInc 的工程师可以自由设计并部署 BookStore REST API 的变更。
由于没有任何 API 质量关卡，他们能非常快速地做出更改。

然而，随着 BookInc 业务规模扩大、更多开发团队参与到 API 变更中，BookStore API 开始变得不一致。
API 使用者抱怨：

• 同一个资源在 API 不同部分被命名成不同的名字
• 各个端点的错误消息格式不统一
• 缺少 API 参考文档
• 有的端点不安全
• 还有一些端点始终无法正常工作

为应对这些问题，BookInc 组建了一个 集中化的 API 平台团队 来治理 BookStore API 的变更：

• 制定 API 标准，并确保 API 变更遵循这些标准
• 运营 API 网关并负责部署 API
• 编写功能测试，确保外部 API 与已发布的 API 文档一致

在 API 设计治理方面，平台团队会 人工审核 开发团队提交的 API 设计变更，确保它们符合标准。
他们在 API 标准文档中宣传最佳实践，并要求团队认真阅读并严格遵循。
为了确保最终产出有良好的用户体验，平台团队倡导 设计优先（Design-First） 的 API 开发方法，要求团队先用 OpenAPI 规范（OAS）完成 API 设计，并在开始后端实现之前，提交设计进行审查与验证。

听起来一切都很合理，平台团队引入的质量关卡也是出于好意。
但随着 BookInc 规模扩大、功能团队增加，出现了以下问题：

1. 变更审核造成瓶颈
   功能团队必须提交工单或预约会议，才能让平台团队审查 API 变更。
   随着提交数量增加，平台团队积压了大量待审变更，导致 API 变更部署周期拉长（Lead Time 增加）。
2. 人工审核易出错
   平台团队的人工合规检查虽然提高了一致性，但也容易漏掉问题。
   有些重要问题直到 API 上线并被用户使用后才被发现。
3. 审查频率下降
   随着 API 部署频率增加、自动化测试维护成本上升，平台团队压力过大，只能把审查频率降到每周一次，以腾出精力处理其他工作。
4. 团队绕过设计优先
   在长时间等待设计反馈的情况下，一些开发团队为了赶进度，绕过了设计优先的方法，直接开始后端微服务开发。
   如果最终批准的设计与他们的实现差异很大，就会造成大量返工和挫败感。
5. 开发团队认知负担加重
   功能团队必须自己记住并理解所有标准，还要随时跟进标准变更，增加了认知负担。

总的来看，BookInc 从去中心化、追求速度的 API 管理模式，转向了集中化、追求质量与可靠性的模式。
在这个过程中，他们牺牲了交付速度。
同时，新的 API 变更部署流程对开发者并不友好——涉及工单、邮件、会议安排、长队列等待、反馈周期过长等交接过程，增加了摩擦与挫败感，甚至影响了公司文化。

好的，以下是你提供的 "1.2 Tackling the scaling problem" 的完整中文翻译，保持了原文的技术细节和结构。

1.2 解决扩展问题

这里的问题在于，随着 BookInc 的扩张，公司不得不在 API 交付速度 与 API 质量 之间做出权衡。
不过，有一个成熟的软件交付范式可以应对这一挑战——DevOps。熟悉 DevOps 的人会发现，这种 API 开发团队与 API 平台或运维团队之间的摩擦，正是 DevOps 旨在解决的问题。

DevOps 是将精益原则应用到整个技术价值流（包括开发与运维），以快速且可靠地为客户交付价值。
DevOps 的一个重要好处是：

• 缩短交付周期（更快完成有价值的工作）
• 降低变更失败率（提高质量）

这正好可以应用到 BookInc 的 API 开发流程中。

正如 G. Kim 在《DevOps 手册》（第二版，IT Revolution Press，2021）中描述的那样，DevOps 基于三大原则：

1. 加速价值在价值流中从左向右的流动（从开发到交付）
2. 实现反向反馈流，快速发现并修复问题
3. 建立持续学习、共享与实验的文化，打造高信任的工作环境

DevOps 实践基于这些原则，包括：

• 版本控制（Version Control）
  跟踪代码和配置文件的修订与变更历史，便于回顾、恢复或修正错误。多个开发者可以协作编写代码，并记录每一次修改。例如流行的版本控制系统 Git。
• 持续集成与持续交付（CI/CD）
  在持续集成中，开发团队每天多次将已测试的代码集成到共享分支，构建系统会将其打包成可部署的制品。持续交付则将这些制品自动部署到测试和生产环境，使团队始终拥有可部署的软件版本。
• 基础设施即代码（IaC）
  使用描述性模型定义和管理系统资源（网络、虚拟机、负载均衡器等），并将其存储在版本控制中，避免手动配置和环境漂移。典型工具包括 Terraform、Ansible、AWS CloudFormation。
• 配置即代码（CaC）
  用描述性模型管理应用程序配置，并存储在版本控制中，支持模板化、回滚与追踪变更。
• 持续监控与度量
  收集、分析并共享生产系统指标，支持改进循环，包括监控与可观测性。监控设定预定义指标、仪表盘与告警，可观测性则通过查询与分析系统行为来定位无法预料的问题。
• 从故障中学习
  通过无责事后分析、混沌工程、应急演练（Game Day）、红队演练等方式理解系统在极端条件下的表现，从而改进韧性与安全性。

DevOps 还包含其他产品、流程与文化实践，比如收集用户反馈、小批量交付、轻量审批、持续测试、支持团队试验与协作。
衡量 DevOps 软件交付性能的四个关键指标是：

• 部署频率
• 变更交付周期
• 变更失败率
• 服务恢复平均时间（MTTR）

回到 BookInc 中 开发者不友好的 API 设计变更审批流程，我们可以借鉴另一个成熟的软件交付范式——GitOps。

GitOps 是一种面向开发者的云原生应用与基础设施变更管理方式。
在 GitOps 模型中，工程师用 Git 存储与更新系统的“期望状态”，交付流水线会自动将 Git 中的状态应用到目标环境中。
禁止通过 UI 手动更改配置，所有变更必须通过 Git Pull Request（PR）提交。

GitOps 的好处之一是 自助化工作模式：

• 传统上，基础设施变更由运维团队接收工单执行，随着开发团队数量增加，这种集中式模式容易形成瓶颈。
• 在 GitOps 中，开发者可以自己提交 PR，运维团队只需审核与批准，随后自动流程会将变更应用到环境中。
• 回滚也很简单，执行 git revert 即可。

另一个好处是 内置合规性与可审计性：

• 配置文件在版本控制中，任何人都可以查看是谁、何时、改了什么。
• 可以运行自动化检查验证配置是否符合组织标准。

GitOps 工作组（opengitops.dev）提出的四大原则：

1. 声明式（Declarative）——用声明式规范描述系统期望状态（应用与基础设施），不写执行步骤，只定义结果。
2. 版本化且不可变（Versioned & Immutable）——状态存储在版本控制系统中，保留完整历史。
3. 自动拉取（Pulled Automatically）——软件代理自动从源拉取状态，比较与已部署配置的差异，并发出警告。
4. 持续调和（Continuously Reconciled）——如果实际状态与期望状态有偏差，软件代理会自动修正，使其一致。

将 DevOps 与 GitOps 的原则结合并应用到 API 设计与交付，就得到了 APIOps 的定义：

APIOps 是通过自动化工作流，实现 API 生命周期的端到端自动化，以更高效地设计与交付 API。

本书将 APIOps 讨论的背景限定为：

• 构建基于微服务架构的 RESTful API 产品
• 使用 OpenAPI 作为 API 定义语言

关于其他 API 规范格式的 APIOps

虽然 OpenAPI（前身是 Swagger）是主流 HTTP API 定义语言，但并非唯一：

• RAML（RESTful API Modeling Language）——基于 YAML
• API Blueprint——基于 Markdown
• AsyncAPI——面向消息驱动 API，可描述 AMQP、MQTT、WebSockets、Kafka、STOMP 等
• gRPC + Protobuf——高性能 RPC 框架与数据序列化格式

本书讨论的某些 APIOps 原则（如 API Lint 检查）也适用于这些格式，但不深入展开。

我会介绍如何在 整个 API 生命周期 中应用 APIOps 原则，通过自动化管理：

• API 定义文件
• API 合规性测试
• API 网关配置

以缩短交付周期，同时确保治理与质量标准（见图 1.1）。

APIOps 是关于自动化 API 生命周期的，但在深入讨论之前，我想先解释什么是 API 产品，以及它与 API（仅仅是一个集成服务） 有何不同。

1.3 API 与 API 产品

应用程序编程接口（API，Application Programming Interface）定义了一组函数和协议，供软件系统彼此通信使用。它是软件系统之间进行信息交换的共享边界。API 解决方案有多种类型，例如 REST API、SOAP API、RPC API、GraphQL API 和 WebSocket API。

另一方面，API 产品是一种经过打包的 API 解决方案，它向 API 使用者暴露功能，以解决特定问题。它是安全的，并配备了完善的文档和支持渠道。通常会有一个专门的 API 团队负责管理其生命周期（从创意到下线），并理解 API 使用者的需求、改善用户体验，以及确保该 API 达成关键业务指标。

如果作为收费服务提供，API 产品会制定定价计划，说明 API 提供方如何计量并收取服务使用费用。API 产品还应具备服务级别协议（SLA） ，明确其服务质量特性（例如正常运行时间和速率限制）。

API 产品的九个组成部分如图 1.2 所示。

API 产品可以是面向外部的 API（暴露业务能力），也可以是面向内部的 API（暴露技术能力，例如内部的权限 API）。使它成为“API 产品”的关键在于它是按产品方式来管理的。
这意味着 API 团队首先会识别并理解 API 使用者所面临的问题，以及该 API 应该为他们带来的价值；然后，团队会设计满足该需求的 API，对设计进行验证，并实现、编写文档、发布打包好的 API 解决方案；在整个生命周期中，他们还会根据用户反馈和运维反馈持续监控并改进 API。

这种以产品为驱动的 API不同于那种纯粹作为企业集成接口的 API 解决方案，因为后者在文档、支持或用户体验上的投入都不足。本书所讨论的 APIOps 原则和实践主要针对 API 产品。

在产品管理中，用来理解和管理产品的模型叫产品生命周期——它描述了产品从开发、成长、成熟到衰退的各个阶段。理解产品生命周期有助于产品经理思考和沟通产品开发、规划和预测。同样，我们也可以将 API 产品看作有一个从构思到下线的生命周期。围绕 API 产品生命周期建立统一的术语，有助于 API 团队更好地规划、构建和治理 API。不过，各个组织定义 API 生命周期的方式有所不同。

在本书中，我采用以下简化的生命周期模型：

• 规划与设计 — 生成并记录新的 API 创意，识别和分析功能性与非功能性需求，创建概念领域模型，将需求转化为 API 定义，并与潜在用户一起审查和验证 API 定义。
• 构建 — 在后端微服务中实现 API，包括编码、单元测试和打包。同时对 API 设计进行 Mock，以便上游 API 使用者可以并行开发。
• 部署与测试 — 在 API 网关中配置微服务，将 API 部署到非生产环境进行验收测试。
• 发布 — 将 API 文档和发布说明发布到开发者门户。
• 运行 — 在生产环境中部署和运行 API，并监控其在功能、性能和安全性方面的健康状况。

所有概念模型都会简化周边的复杂性以突出重点，这个模型也不例外。我会用它来解释 APIOps 的实践，以及 API 团队可以在 API 产品生命周期的高层阶段应用的治理措施。它并不穷尽所有细节，也不涵盖 API 实际设计与交付的低层流程（那些通常发生在更迭代、更敏捷的工作流中）。如需更详细的生命周期讨论，可参考 Luis Weir 的《Enterprise API Management》（Packt 出版，2019）。

1.4 为什么你应该关心 APIOps？

使用 APIOps，你可以自动化治理和部署 API 产品的过程。但在此之前，你需要先理解当前 API 产品的价值流——即从客户需求到 API 在生产环境部署之间的关键活动与阶段。明确工作流可以帮助你识别最需要自动化的优先领域。在第 2 章中，我会进一步讨论如何绘制 API 设计与交付的价值流。

本书讨论 APIOps 的背景是为微服务架构构建 RESTful API 产品。在微服务项目中，API 产品的构建和管理是一个高度协作、反复迭代的过程，需要组织内多个角色参与——开发人员、架构师、产品经理、安全工程师、技术文档人员、运维团队等。APIOps 的目标是在让多团队多角色高效协作进行 API 设计、开发与运维的同时，通过引入自动化来减少手工任务、延迟和交接环节。

为了说明这一点，我们先看看微服务架构的组成部分。微服务架构由多个小型、松耦合的服务组成，每个服务在限定的业务上下文中实现单一业务能力。每个微服务由一个小团队管理，有自己的代码库，负责持久化自己的数据，并且可以独立部署。微服务都有明确定义的 API，这些 API 可以打包成 API 产品，并通过 API 网关向外界暴露。

注：限定上下文（bounded context）是领域驱动设计（DDD）中的概念，指的是在更大应用的一个子领域内，特定的术语和规则在这个边界内保持一致。

API 网关是一个反向代理，作为 API 产品的入口点。除了将来自 API 产品的请求路由到后端微服务 API 之外，API 网关还可以提供安全性、流量管理、分析、消息转换和编排等能力。API 网关将 API 产品接口暴露给 API 使用者（API 消费者）。API 消费者通常是开发集成该 API 的软件应用的开发人员。开发者门户则用于发布有关 API 的文档，通常包括 API 参考文档、用户指南和 API 产品教程（见图 1.3）。

每个 API 产品都有一个 API 定义，用于描述该 API 产品向 API 使用者提供的操作与资源。API 网关也有一个 API 配置，用于描述外部请求如何被路由到内部微服务，同时定义接口的其他限制，例如速率限制与安全机制。

API 规范、API 定义与 Swagger

在本书中，当我提到 API 规范（API Specification） 时，指的是 OpenAPI 规范（OAS） 。这是业界标准的 REST API 描述方式，既方便人类阅读，也可被机器理解。你可以在 spec.openapis.org/oas/latest.… 查看最新版本（写作时为 3.1.0）。该标准由 OpenAPI Initiative（OAI） 维护，OAI 是隶属于 Linux 基金会的行业专家联盟。

当我提到 API 定义（API definition） 或 OpenAPI 定义 时，指的是使用 OAS 格式描述某个特定 API 的文件。API 定义文件通常是 YAML 或 JSON 格式。换句话说，当你用 OAS 描述 API 时，你创建的就是一个 API 定义文件。它是一份契约，详细说明了 API 支持的操作、使用的安全机制、每个操作的请求格式以及可能的响应内容。

由于 OpenAPI 标准的广泛采用，许多工具都能读取 API 定义文件，包括 GUI 编辑器、文本编辑器、SDK 生成器、Mock 服务器以及文档生成工具。一个不错的工具列表在 OpenAPI.tools 可以找到。

需要注意的是，OAS 曾经被称为 Swagger 规范。2015 年 11 月，SmartBear Software 将 Swagger 规范捐赠给 OAI，并将其改名为 OpenAPI 规范。OpenAPI 3.0 是改名后的首个版本。现在，Swagger 这个名字专指 SmartBear 提供的一套与该规范配合使用的开源、免费和商业工具套件，包括 Swagger Editor、Swagger UI、Swagger Codegen 和 SwaggerHub。

在本书中，这两个文件——API 定义文件 与 API 网关配置文件——是 APIOps 讨论的核心。在 API 产品生命周期中，不同角色会参与创建、更新、审查、部署和发布这些文件，APIOps 的目标就是让这一过程高效且符合质量与合规要求。

1.5 结合 OpenAPI 的 APIOps 核心原则

本书的重点是实现 使用 OpenAPI 作为 API 定义语言的 API 产品开发端到端自动化，基于这一目标，总结出以下六大原则：

1. 采用设计优先（Design-First）的 API 开发方式
2. 将 API 定义存储在版本控制中
3. 自动化 API 标准合规性检查
4. 运行 API 一致性检查，确保实现与设计相符
5. 将声明式 API 配置存储在版本控制中
6. 持续对比 API 网关配置的期望状态与实际状态

1.5.1 设计优先（Design-First）API 开发

第 1.3 节介绍的产品驱动 API 构建方法，本质上是先设计 API，再收集潜在 API 使用者与团队成员的反馈来验证设计，然后才编写代码实现。这与产品管理中的 原型验证 类似——先做原型验证是否满足客户需求，再开始真正开发产品。

在这个类比下，你可以将 OpenAPI 定义文件 视作一个高保真原型，既可渲染为文档，也可用于 Mock 出一个模拟 API。先创建 API 定义文件，可以让你尽早让潜在 API 使用者验证它是否具备核心的问题解决能力。

在定义 API 产品的阶段，团队不仅要考虑 API 设计的功能性方面，还要考虑非功能性要求与业务指标，包括安全机制、破坏性变更策略、API 弃用政策、速率限制与使用计划等。

先定义并达成一致的好处是可以并行工作：

• 后端团队可开始实现 API 服务
• 测试团队可基于定义创建测试用例
• 客户端系统可根据 Mock API 开发集成

这样可显著缩短开发周期。

设计优先（Design-First）与 API 优先（API-First）

设计优先（Design-First） 又称 规范优先（Specification-First） 或 契约优先（Contract-First） ，即在实现代码之前反复迭代 API 定义文件。这是将 API 当作产品进行管理的重要步骤——先考虑 API 的目标使用者、为他们解决的核心问题，并通过原型验证设计的有效性，然后才进入开发。

设计优先的优势：

• 强价值与可用性定位：先理解用户目标，再与产品经理、业务分析师等协作设计满足这一目标的 API
• 获取早期反馈：通过文档与 Mock 早期发现设计缺陷，降低后期修复成本
• 并行开发：接口已定，下游团队可同步构建与测试
• 可复用性：更容易发现与复用组织内的 API 组件与设计模式
• 自动化支持：可基于定义文件生成服务端/客户端代码、测试代码、安全策略与 API 配置

相比之下，代码优先（Code-First） 是直接实现 API 再反向生成定义文件，优点是简单快速，缺点是往往忽略了 API 的可用性与一致性。

API 优先（API-First） 则是一种业务战略，强调将 API 视为系统的一等公民与关键资产，组织应将 API 当作最重要的应用或平台接口。

最后，不需要手写 YAML/JSON，可以使用如 Stoplight、Apicurio Studio、Postman 等 GUI 工具来辅助创建 API 定义文件。

1.5.2 将 API 定义存储在版本控制中

你的 OpenAPI 定义文件应该存储在版本控制系统（如 Git）中，以确保不可变性并保留文件的完整版本历史。这能为你提供可审计性，并使你能够通过 CI/CD 流水线使用基于 Git 的流程来驱动自动化。团队成员还可以通过正常的 Git 工作流（如发起 PR）来协作修改 API 定义文件。

我建议你为存储 API 定义专门创建一个 Git 仓库。这样团队成员可以方便地发现 API 定义、遵循通用模式，并复用共享的 API 组件。Git 不仅能提供出色的审计历史记录，还能启用大量集成选项，让你将 OpenAPI 定义文件集成到 CI/CD 流水线中。

💡 提示：一些厂商的 API 设计协作工具允许你在其平台上存储 API 定义文件。我的建议是将 Git 仓库作为 API 定义的主存储，并让厂商工具从中读取或更新文件。这样不仅可以获得使用 Git 仓库的全部 CI/CD 自动化优势，还能避免厂商锁定，并在需要时使用其他工具编辑 API 定义文件。

将 API 定义存储在 Git 中，并通过 PR 来更改文件，可以让同事像审查代码变更一样审查 API 定义；同时，你也可以在 PR 上运行自动化合规性检查。这就引出了下一个原则。

另外，存储 API 定义文件的另一种方式是使用 API 注册表（API Registry）。API 注册表是一种服务器，允许用户存储、浏览、搜索、查看、更新或删除 API 定义文件。但我更推荐使用 Git 这样的版本控制系统，因为 PR 工作流对开发者更友好，而且 GitHub、Bitbucket 等版本控制平台提供了许多集成选项，有些甚至有插件可以直接在仓库中渲染 OpenAPI 定义。我会在第 9 章详细介绍这一点。

1.5.3 自动化 API 标准合规性

你可以将 API 风格指南转换为一组可执行规则，用来检查 API 定义文件是否符合这些标准。此外，你还可以通过 API linter（API 静态检查工具）来实现部分规则的自动化验证——它会解析你的规则集，并报告静态 API 定义不符合规范的地方。对于一些更特殊的规则，你可能需要额外编写脚本。例如，如果你的 API 指南规定不得引入破坏性变更（breaking changes），你可能需要一个脚本或工具来比较 API 定义文件修改前后的版本，以检测是否存在破坏性 API 设计变更。

这里的指导假设你的组织已经有一份 API 风格指南。如果没有，从零开始创建一份组织级 API 风格指南是一项大工程，但你可以参考一些开源示例作为基础。

要让 API 遵循你的标准，关键是要自动化合规性检查。例如，将 API 标准编码成规则，让 API linter 或脚本验证 API 定义是否符合标准。将这一自动化检查集成到 CI/CD 流水线中，为开发者提供快速反馈，这是 DevOps 的重要实践，也是 APIOps 的基石之一。

当 API 定义通过了自动化标准检查，并且已与相关方验证设计后，你就可以进入构建阶段。这并不意味着 API 定义之后不能更改（API 设计是迭代的），但如果发生更改，你可以通过快速自动化流程再次检查其合规性。

1.5.4 运行 API 一致性检查

在你实现 API 之后，需要验证实际实现的 API 是否与 OpenAPI 定义中商定的设计一致。你可以运行 API 一致性测试（从 OpenAPI 定义文件自动生成的测试）来验证 API。
这些测试会通过调用 API 定义中规定的操作，并检查返回结果是否与定义一致，来确认 API 定义的正确性。
它包括：

• 检查响应对象的模式是否正确
• 检查是否存在未实现的操作
• 进行模糊测试（fuzzy testing）：向 API 发送随机、意外的数据，看它是否返回了定义文件中未记录的响应

如果你的 API 一致性测试通过，就可以确信测试所用的 API 定义文件准确描述了你的 API 实现。

1.5.5 将声明式 API 网关配置存储在版本控制中

当你实现了后端 API 服务后，需要将它们部署到 API 网关 中作为 API 产品，供 API 使用者访问。
为此，需要创建或更新 API 网关的部署配置。

这些配置应采用声明式格式（Declarative Format），并存储在环境的 Git 仓库中。
所有 API 配置更新都应通过 Git 完成，而不是直接在 API 网关 UI 中点击修改。

API 网关配置包含的信息包括：

• 每个 API 产品要路由到哪些后端服务
• 如何识别和认证 API 客户端
• 每个客户端应用哪些使用计划
• 每个客户端的限流规则
• 如何记录和监控 API 请求
• 其他相关配置

配置应以声明式的方式定义，明确描述每个环境的期望状态（Desired State）。

📌 注意：

• 声明式配置：用文件描述系统的目标状态（如设置和属性），只需写出属性值，由软件工具或代理（agent）读取该文件并执行必要操作来使系统匹配目标状态。你不需要知道具体执行了哪些命令或顺序。
• 命令式配置（Imperative） ：在脚本中明确指定每个命令及其执行顺序，运行时按脚本内容一步步设置目标状态。

将 API 配置以不可变、版本化的文件存储在版本控制系统（如 Git）中，团队就可以用 Git 工作流协作管理。
这种方式是 配置即代码（Configuration as Code） 和 GitOps 方法（1.2 节提到）的应用。

不同 API 网关有不同的声明式配置方式：

• 有的允许在 API 定义中用 OpenAPI 厂商扩展直接指定（如 Amazon API Gateway、Kusk API Gateway）
• 有的用单独的声明式配置文件（如 Apigee Edge）
• 有的作为 Kubernetes Ingress Controller 部署时，用 Kubernetes CRD 形式存放在 manifest 文件中（如 Kong Gateway 的 Kubernetes Ingress Controller、Tyk Gateway 的 Tyk Operator Ingress Controller）

无论哪种方式，声明式配置都应存储在版本控制中，以支持 APIOps 流程。

1.5.6 持续对齐期望状态与实际状态

你需要有软件代理（Software Agents）持续比较环境仓库中存储的 API 网关配置期望状态与实际环境中的当前状态。

漂移（Drift） 可能发生在：

• 系统状态被直接更改（如通过 API 网关 UI）
• 环境仓库中的期望状态被有意修改

无论漂移如何产生，软件代理都会检测到，并将实际状态改回到期望状态。
这种持续对齐期望状态与实际状态的做法是 GitOps 的核心原则之一。

软件代理（如 Kubernetes 控制器）会自动创建、配置和管理已部署的应用：

• 检测系统期望状态与运行时状态之间的漂移
• 发生差异时发出告警，并自动部署期望状态
• 形成反馈与控制回路，确保系统自愈（Self-healing）

禁止通过 UI 手动修改 API 网关配置，工程师必须通过 Git PR 来进行更改。
由于配置文件在 Git 环境仓库中有版本控制，审计能力是内置的：

• 谁修改了
• 修改了什么
• 什么时候修改的

结合软件代理的自动部署能力，可以用 git revert 命令轻松回滚配置变更。
图 1.4 展示了这种 GitOps 方法。

关于采纳前面讨论的六项 APIOps 原则，第一步是落实第一个原则——组织需要在创建和更新 API 产品的 API 定义文件时，采用产品思维。接下来是第二个原则，确保 API 定义文件在 Git 中进行版本管理，以支持 CI/CD 自动化。这些原则层层递进，直到最后一个原则——基于对齐的自动化软件代理部署 API 配置。构建这些原则所涵盖的组织能力，可以用一个 APIOps 成熟度金字塔来表示，如图 1.5 所示。

这些原则会影响参与API产品工作的不同角色。稍后在第1.7节中，我将讨论这些原则如何影响其中的三个角色——开发人员、运营经理和API产品经理。

1.6 本书中你将学习的APIOps实践

在本书中，我将引导你学习如何在前文图1.1所示的API生命周期各个阶段，应用APIOps的六项原则。具体实践包括：

• 运行API语法检查（linting）。
• 运行自动化破坏性变更检查。
• 创建并执行API一致性测试。
• 从API定义文件生成服务器和客户端代码。
• 模拟API定义文件以支持并行开发。
• 创建并部署声明式API网关配置。
• 自动发布API参考文档到开发者门户。
• 从API配置和定义文件生成API发布元数据。
• 设置API的监控与分析。

在API产品的设计阶段，你将学习如何创建并执行语法检查规则，以在API定义文件中强制执行设计治理标准。借助这些自动化，你能聚焦于与同事一起对API设计进行人工审核的重点环节。你还将了解如何自动检测API定义文件不同版本间的破坏性变更。此外，你会学会创建API一致性测试，以验证实现是否符合设计。最后，你会看到如何在CI/CD流水线中运行API语法检查和破坏性变更检测。

在API产品的构建阶段，我将向你展示如何从API定义文件生成服务器存根（stub）和客户端代码。同时，你也将学习如何方便地模拟OpenAPI定义文件，以支持验收测试和集成代码的并行开发。

在部署和测试阶段，我将指导你如何利用基于Git的配置对齐方法（GitOps）创建和部署API网关配置。你还将学习如何执行设计阶段创建的API一致性测试。

在发布阶段，我将展示如何将API定义文件作为API参考文档发布到开发者门户。同时，你会学会如何从API定义和配置文件中指定的元数据生成发布说明数据。

最后，在生产阶段，我会介绍如何设置运行时监控和分析。此外，你还将了解如何使用产品分析提升API的体验和价值。

图1.6展示了上述实践在前文讨论的API生命周期模型中的位置。API团队在每个阶段通过APIOps活动获取反馈。请注意，这个简化模型仅展示了高层阶段和反馈循环，不是流程图，也不是构建API时的推荐流程。实际工作中，团队会在交付工作流的各阶段快速获得反馈。但这应能帮助你理解APIOps实践如何融入你组织独特的API生命周期。

除了产品生命周期各阶段的活动之外，你还将学习一些技巧，帮助你迭代改进现有的API交付工作流，逐步引入APIOps实践。

1.7 APIOps对API治理的影响

我已经讨论过APIOps对于需要加强API设计治理、提高API设计和交付速度，同时保持API一致性、质量、可靠性和安全性的组织来说有多么重要。在采用APIOps的过程中，组织在API治理方面通常会经历三大阶段。

第一种方式是没有集中管理的API标准。没有统一的API规范，开发团队各自定义并执行自己的API标准。这虽然加快了API的交付速度，但不同API因遵循不同标准，导致一致性差。这也增加了API消费者的认知负担，因为他们必须应对这种不一致性。图1.7对此做了说明。采用这种方式的组织起步较快，但随着规模扩大，不一致的API设计和API质量往往导致API采纳率低下，维护成本高企。

为了解决这些问题，组织可能会采用第二种方式——制定API标准作为所有团队必须遵守的API风格指南，并由一个集中管理的API治理团队对API设计进行人工审核，以确保遵循API风格规范。这种做法能够带来更一致、更优质且符合标准的API设计。

但人工集中式设计治理可能成为瓶颈。它会导致API交付变慢，因为团队可能需要等待较长时间才能获得审核，或者根据审核反馈反复进行人工审核。这种反复往返会进一步拖延进度。而且，人工审核本身也可能遗漏问题。图1.8展示了采用这种方式所带来的时间延迟。

APIOps倡导第三种方式——自动化API治理检查。这使得在保持高合规性和API质量标准的同时，实现快速的API交付流程成为可能。需要注意的是，自动化API治理并不意味着不再需要同事对API进行审核，以检查那些无法自动化或尚未实现自动化的事项。例如，负责API治理的同事或团队可能希望审核API资源模型，以确认团队内部对Web资源和属性的命名达成共识。这是一种集中式与分散式模型之间的平衡。自动化的API标准检查帮助处理标准合规性问题，让治理团队有更多时间专注于资源模型和API操作设计等更重要的问题。图1.9对此进行了说明。

当团队采用APIOps方式进行API治理和部署时，对开发者的主要好处如下：

• 更简化的API开发流程 —— APIOps建议将API定义文件和API配置存储在Git中，而大多数团队已经熟悉Git的使用。利用Git对API定义文件和配置进行版本控制，使得可以将与API相关的自动化集成到CI/CD流水线中，从而简化开发过程。
• 更快的反馈与减少挫败感 —— 开发者可以通过API设计编辑器中的自动API lint检查，以及CI/CD流水线中的自动检查，早期且快速地获得API设计的标准合规反馈。APIOps减轻了开发者的认知负担，他们无需记忆和阅读所有组织的API标准，避免了手动API审核中耗时且易出错的反复修改，减少了挫败感。
• 提升API发现与复用 —— 将API描述文件和API配置存储在共享的版本控制系统中，使开发者更容易搜索、发现和复用API组件及设计模式。

对API运维（平台）团队的主要好处包括：

• 更快更顺畅的API部署 —— APIOps消除了手动部署，所有API部署均通过Git仓库的PR审批及API CI/CD流水线进行。
• 更一致且合规的API —— APIOps使企业不必再在集中式但完全手动的API合规检查（前文提到的第二阶段）和无标准限制的快速交付（第一阶段）之间做选择。自动化合规检查和基于Git的部署流程确保API定义符合治理标准。
• 缩短恢复时间（MTTR） —— 当API配置出现故障时，软件部署代理通过持续调和API配置，使得回滚到之前正常工作的版本变得简单快捷，只需执行git revert命令即可。

注意：一些公司设有API网关团队，负责维护API网关、治理API，以及创建用于将微服务路由到API产品的网关配置。最后这点意味着API网关团队直接参与产品交付，实质上是一个技术组件团队。技术组件团队可能成为瓶颈，通常希望避免此类情况。在APIOps流程中，这类团队的职责发生了变化。他们的主要任务转为允许其他开发团队自助创建和更新API产品在API网关中的配置。他们负责审查API配置变更的PR，并可在API设计和治理方面提供咨询（同时仍维护API网关）。其角色从组件交付团队转变为API平台和赋能团队。

对API产品经理的关键好处包括：

• 缩短交付周期 —— APIOps减少了从API设计并提交至Git仓库，到最终部署的时间，减少了中间的交接和重复劳动，加快了产品上市速度。更重要的是，APIOps支持设计API定义文件优先的并行开发流程，在实现阶段即可开始编写测试脚本并与模拟的API定义集成。
• 产品驱动的API —— API产品经理不仅领导API产品定义，还能审查和理解API定义的变更。

1.8 采用OpenAPI实现APIOps的挑战

OpenAPI是定义RESTful API最流行的标准。然而，在API服务构建之前先创建OpenAPI定义文件是一大挑战：究竟如何创建OpenAPI定义？手写YAML格式的API定义既繁琐又耗时，因此需要好的工具支持。诸如Stoplight、Apicurio等工具，提供了图形界面以简化OpenAPI定义文件的创建。

无论选择哪种工具，都应与Git有良好的集成，Git作为API文件的主记录存储。虽然大多数开发团队熟悉Git，但需要提醒的是，APIOps方法要求任何更新API定义文件的人都必须熟悉Git及团队的Git工作流程。

如前所述，APIOps还需要投入自动化API价值流，以及建立合适的API平台团队来支持这一切。API平台团队专注于构建基础设施、库和工具，支持并赋能API开发团队以自助方式高效工作。这要求传统API网关组件团队的思维方式发生转变。

总结

API产品是由API团队管理的一个打包的API解决方案，旨在为客户提供核心的问题解决价值。
APIOps是基于DevOps和GitOps实践的端到端API生命周期自动化，帮助组织实现更短的交付周期，同时提升API标准合规性、质量和可靠性。

基于OpenAPI的APIOps依赖于将API定义文件和API配置存储在版本控制系统（如Git）中，并通过Git工作流构建自动化流程，以验证和部署这些制品。