阿里云 x Apifox 云原生技术实践营，分享 API First 最佳实践

7 月 16 日，由阿里云与 Apifox 合作举办的云原生技术实践营在广州顺利开展。Apifox 高级产品经理王逍（Sean）作为本次技术沙龙活动的演讲嘉宾之一，围绕《从文档到测试， 多样化 API 技术的 API Design-First 实践》展开分享，与百余位参与活动的开发者沟通讨论 API Design-First 模式，以及面向不同的 API 技术，从 API 定义到 API 测试的工作流实践。

以下内容整理自 Apifox 高级产品经理王逍（Sean）的演讲：

API Design-First 的优势

著名的测试金字塔是迈克·科恩（Mike Cohn）提出的一个概念，形象地描述了在一个项目内，不同类型的测试应该占据的比例。测试金字塔从下至上是单元测试、服务测试和 UI 测试。

原始的测试金字塔告诉我们，应该编写大量小而快速的单元测试，适当的更粗粒度的服务测试，少量的 UI 测试。因为在测试金字塔内，级别越高，集成度就越高、运行速度就越慢，因此数量应该越少。

但 JetBrains 2022 年开发者生态系统报告显示，大家的项目中单元测试、UI 测试较多，服务/API 测试是最少的，而且自动化测试的比例很低，这是一种典型的测试金字塔的反模式，即漏斗模式，两头大中间小。这种反模式意味着，有一个非常出色的开发团队，他们会去编写单元测试，并且还有一个 QA 团队去编写 UI 测试，但并没有人编写服务/API 测试。

在测试金字塔中，UI 测试非常依赖 QA 工程师对业务/使用流程的充分理解，否则无法去遍历每种可能的用户操作路径，因此创建成本较高。此外，由于 UI 存在多变性，可能一个页面在调整过后，元素的 id 和 class 会发生变化，这样就需要调整之前的自动化用例，导致维护成本、回归成本很高。

服务/API 测试依赖于 API 定义/文档，且需要合适的工具来进行测试。相对来说，创建并维护 API 定义的成本是较低的，因为 API 一般不会频繁而剧烈的变动，而且市场上也有非常多的 API 测试工具可供使用。单元测试则依赖于开发者的素质与习惯，也与团队的工作流程相关，如果要写好单元测试并保证覆盖率，成本也是较高的。

从成本与收益的⻆度，API 测试是位于单元测试和 UI/E2E 测试之间的一个均衡点。而降低 API 测试用例的维护成本的有效方法，就是贯彻 API Design-First 理念。

API Design-First 是在开发过程中把 API 定义当做最优先考虑事项的一种模式。它与传统的 Code First 模式最明显的差异是，当 API 完成了定义之后，所有的团队成员可以同步并行开展工作，并在之后进行成本相对较低的 API 测试。

创建人类和机器都能理解的 API 定义

一份好的 API 定义需要让⼈类和机器都能理解，因此，API 定义和 API 文档是不同的。

一般来说，API 文档是指人类阅读友好的文档。比如一些团队会使用 Word 文档或者 Markdown 文档去描述 API，这个就不能被称之为 API 定义，但它是 API 文档。

根据 Postman 2023 年的 API 调研报告，HTTP （包含 REST、Webhooks、Server-Sent Events）仍然是使用率最高的 API 技术，占据绝对优势地位，但是 WebSocket、GraphQL、gRPC 等新兴 API 技术的使用率也不可忽视。

几乎每种 API 技术，都有约定俗成的 API 描述语言。比如 Swagger/OpenAPI 用来描述 HTTP，ProtoBuf 用来描述 gRPC，AsyncAPI 用来描述 WebSocket、Kafka 等。

贯彻 API Design-First 理念的第⼀步，就是使用合适的 API 描述语言，去创建良好的 API 定义。

如果你有一个全新项目，决定使用 API Design-First 工作流，那么可以通过 Apifox 的可视化界面，从零开始创建 API 定义。如果你有一个历史项目，希望迁移到 API Design-First 工作流，也可以通过 Apifox 调试接口来创建 API 定义。

针对 HTTP 项目，如果接口数量较多，你还可以借助 Apifox IDEA 插件直接从代码中提取 API 定义，非常方便快捷。针对 gRPC 项目，你可以直接导入 .proto 文件。而针对 Dubbo 项目，Apifox 支持从阿里云 EDAS 导入 API 定义，并且支持后续的调试和文档管理。

Apifox 为每种 API 技术使用相匹配的通用 API 描述语言，以便于和其他工具进行集成、协作、打通，也降低了供应商锁定的风险。比如在 Apifox 内设计的 HTTP 接口，导出为 Swagger/OpenAPI 文件后，再使用 SwaggerUI 渲染为 API 文档，是完全没有问题的。

从文档到测试

基于 API 定义，后端、前端、测试可以并⾏开展⼯作。

创建 API 定义后，Apifox 可以将其转换为人类阅读友好的且美观的 API 文档，并且可以在浏览器中访问。如果在对外公开文档时设置了 API 的环境，文档阅读者还可以直接在浏览器中调试 API，无需下载安装任何工具。

由于 API 定义的存在，通过使⽤ Apifox，后端可以⼀键⽣成样板代码，前端可以使⽤ Mock 进⾏联调，测试可以进⾏零配置断⾔，极⼤地提升团队效率，简化 API 工作流，并确保了团队成员之间的高效协作。

Apifox 作为国内领先的 API 一体化协作平台，围绕 API 全生命周期协同与管理需求，提供 API 文档、API 调试、API Mock、API 自动化测试等能力，致力于为全球研发团队提高 API 开发与协作效率，节省研发团队的每一分钟。

Apifox 在活动现场收获了大量参会者的肯定与支持。我们会继续努力，致力于为用户提供更优秀的产品功能和更极致的使用体验，持续推动 API 研发管理领域的创新和发展，以满足研发团队不断变化的需求。

感兴趣的小伙伴可以扫描下方二维码或点击「云原生技术技术实践营」前往查看本场演讲的回放视频~

活动精彩瞬间