API规模化开发需采纳工程实践，遵循四大原则：万物皆代码、单一真相来源、自动化、AI辅助。这能简化API生命周期管理，提高效率和质量。
译自：4 Core Principles for Scaling Your API Engineering Practice
作者：Matthias Biehl
遵循可预测的 API 开发生命周期模式来设计和部署 API 似乎很容易。API 开发者可能不会多想，在开始他们的第一个 API 时就直接上手。
然而，随着 API 成为企业中每个系统和服务的数字基石，您必须开发和管理数百甚至数千个 API——而轻量级的工程模式可能很快就会被证明不足以应对日益增长的复杂性。
随着您将每个 API 的不同版本部署到日益复杂的环境中，混乱可能会随之出现：随着工件数量的增长，团队规模也必须扩大。
这就是为什么当您将 API 规模从几个 API 扩展到数百甚至数千个 API 时，API 工程实践需要成熟。
理解 API 开发生命周期及其工件
第一步，将 API 视为拥有自己的生命周期，从诞生到消亡，这会很有用。在其生命周期中，API 会经历各个阶段。根据我的经验，这包括以下内容：
- 需求启发
- 编写和演进 API 规范
- 实现 API 服务
- 配置网关策略
- 应用治理规则
- 运行测试
- 部署整个系统
- 可观测性与维护
- 弃用与淘汰
在每个阶段，您都需要处理 API 工件：OpenAPI 文档、策略定义、配置文件、测试套件、治理规则集等等。在理想世界中，您总是知道哪些工件属于一起，最新版本在哪里，以及更改如何流经 API 生命周期。在现实中，事情往往会变得更混乱。
现代 CI/CD 实践有助于自动化重复任务并保持代码质量。但这种自动化只有当所有相关工件都以代码形式存在时才有效——即您可以进行版本控制、差异对比、验证、测试和部署的东西。不幸的是，情况并非总是如此。
是的，我说的就是你，API 网关策略。虽然 API 背后的 Spring Boot 服务很容易在 CI/CD 管道中管理，但网关层通常可能被锁定在某个工具特定的用户界面（UI）中，这使得自动化、协作和治理变得痛苦。
但事情不一定非得如此。
如果您想以规模化方式——一致、可靠且快速地——开发 API，您需要 API 规范、网关策略、测试和治理规则遵循相同的原则：将它们视为代码。
以下是四个指导原则，可以帮助您转变 API 开发生命周期。
原则一：万物皆代码
每个 API 工件——规范、策略、测试定义、治理规则——都应该以代码形式表示。不是作为隐藏在工具内部的不透明内部模型，而是以可移植、人类可读和机器可读的格式存储在存储库中。
这解锁了整个现代开发工具包。在我看来，这应该包括：
- 版本控制
- 拉取请求和代码审查
- 自动化质量检查
- 可重现的发布
- CI/CD 集成
话虽如此，纯代码编辑可能会令人望而生畏，尤其是对于新手。解决方案是提供多种可编辑视图，以适应开发人员的偏好和经验。开发人员应该能够在代码和基于表单的引导式 UI 之间无缝切换。专家可以在 YAML 中快速操作；休闲或偶尔使用的用户可以依赖视觉引导。两种视图都会即时反映更改，因此开发人员可以来回切换。
通过将万物视为代码，开发人员可以灵活地使用他们喜欢的编辑器和工具——无论是基于网络的工具、桌面工具、编码工具还是基于表单的工具——只要它能生成代码作为最小公分母。
原则二：单一真相来源
当 API 规范或网关策略存在于多个地方——不同的控制台、工具或云产品——没有人真正知道哪个版本是规范的。对于少数几个 API，你可能可以蒙混过关。但对于几十甚至上百个 API，治理实践很可能会崩溃。
可扩展的实践要求：
- 每个 API 有一个单一真相来源，理想情况下是在版本控制中。
- 所有相关工件与 API 一起存储。
- 完整的历史记录、可追溯性和回滚。
- 在更改时触发自动化操作（通知、验证、测试）。
这使得团队能够并行工作而互不干扰。
将万物视为代码（原则一），您可以将所有内容检入一个标准的版本控制系统，一个用于所有工件的代码存储库。既然可以利用 GitHub 等现有技术，何必重新发明这样的系统呢？
原则三：自动化一切（除了您的创造力）
所有重复性工作都应自动化，包括：
- 运行功能测试和契约测试。
- 检查样式指南（例如，Spectral 规则）。
- 验证模式一致性。
- 强制执行治理约束。
- 触发构建和部署工作流。
自动化是“左移”（尽早验证）和“下移”（委托给工具）实践的支柱。开发人员获得更快的反馈、更高的质量和更可预测的发布。使用 CI/CD 系统进行自动化，基于您的 API 存储库作为单一真相来源（原则二）和万物皆代码（原则一）。
原则四：将繁琐工作外包给 AI
您不应该为每个新的 API 项目编写样板代码。将重复性任务卸载给 AI，这样您就可以专注于架构、领域建模和问题解决——您擅长的部分。
- 协助创建或扩展 API 规范。
- 推荐标准或自定义网关策略供审查。
- 识别文档空白并提出改进建议。
- 帮助起草功能、安全和性能测试。
- 提供关于重构或重组工件的指导。
即使是经验丰富的开发人员也能从降低认知负荷和避免手动繁琐工作中受益。
这些 API 工程原则如何在实践中发挥作用
我建议您首先在首选编辑器中将 OpenAPI 规范和网关策略定义为代码。根据您的舒适度，在代码和基于表单的编辑之间切换；两种编辑视图应保持完全同步。如果您确切知道要做什么，代码编辑可能更快，但对于新手（或偶尔开发 API 的人）来说，基于表单的编辑器提供的指导会非常有帮助。
像 Spectral 这样的工具可以强制执行组织样式指南，并确保您的产品组合保持一致性。
AI 可以帮助您创建或完善工件、填补缺失的文档或根据您的规范生成测试。忘记填写那些繁琐的描述字段了吗？让 AI 生成描述的第一个提案。
一旦您满意，将所有内容检入版本控制——单一真相来源。这样不仅所有东西都有其位置，而且每当有人更改它时，都可以进行质量检查。自动化会在将最新版本的工件部署到测试环境之前触发检查，例如：
- 模式验证
- 代码检查和指南检查
- 安全扫描
- 测试执行
- 部署到测试环境
当 API 投入生产时，它是通过设计而不是偶然通过了质量关卡。
今天就开始扩展您的 API 实践
如果您认真对待扩展 API 开发并减少操作摩擦，这些原则应该构成您实践的基础。可以考虑使用像 IBM API Connect 中的 API Studio 这样采纳这些概念并帮助团队顺利采用的工具。
构建 API 应该感觉像工程，而不是考古。将万物视为代码，建立单一真相来源，严格自动化，并将繁琐工作委托给 AI，可以使您的团队从手动工作转向可持续的效率。
