自动化测试 | 如何在 API 开发中践行“设计优先”方法？SwaggerHub 助您一臂之力

与 SmartBear 合作的很多公司都处于 API 旅程中的不同阶段。其中有些刚刚意识到他们需要一个 API 策略，而另一些则有整个团队去定义和实施一个 API 策略。但无论他们身处哪个阶段，他们都在寻找并想采用一种叫“API 设计优先（API Design First）”的方法。

 “设计优先”是什么意思

乍一看，您可能会觉得如果团队没有使用“设计优先”方法，那么他们可能会推迟设计，或者完全跳过设计阶段。但这并不是“设计优先”的真正意思。

相反的是，“设计优先”是指人们以一种人类和计算机都能理解的方式书写他们的 API 设计。其他方法也可能鼓励在软件开发过程中提前进行设计，但这些设计可能无法在后续的自动化或开发者工具中使用。

“设计优先”意味着团队中的每个人都使用相同的术语和概念，确保各种开发工具都可以使用相同的设计规范。采用这种方法的公司和团队可以减少设计和开发之间的鸿沟，这种 API 设计风格有许多优点，包括：

• 基于产品的 API——团队可以在 API 设计过程的早期让产品经理和质量保证工程师加入进来，帮助塑造 API 的功能，从而使 API 的设计更加注重产品的需求和目标。

• 基于设计的开发——API 开发人员可以利用 API 设计来推动开发工作。自动化工具可以指导他们应该构建什么，并确保他们根据设计构建 API。

• 并行工作——在 API 本身完成之前，就可以开始构建 API 客户端。这让 API 使用者、API 生产者和技术编写者能够并行工作，不必相互等待。

• 更短的反馈循环——API 团队可以通过使用自动化工具来获取更快的反馈，验证他们的设计。团队可以在编写过程中设计并查看文档，不用等待开发人员交付可工作的代码。

• 帮助 DevOps——DevOps 团队可以在 API 部署到生产环境之前，使用 API 设计来测试 API。他们可以使用自动化工具来检查实现的 API 是否符合设计规范，不用手动检查。

• 适应后期更改——团队可以在整个开发阶段持续地影响 API 设计。借助合适的工具，他们可以将设计作为一个持续演进的过程，而不是仅仅是开发之前的一个步骤。

采用“设计优先”方法对企业来说既有短期商业价值，也有长期商业价值。团队能够根据正确的设计来生产正确的软件。团队在工作时能够充满信心，知道自己走在正确的道路上。企业降低了发布错误软件的风险，并带来了更一致的用户体验。

“设计优先”方法有助于将设计和开发阶段融合在一起，使这两个阶段相互影响。采用这种方法的企业可以更快适应不断变化的需求，这种对变化的适应能力会转化为企业的竞争优势。

“代码优先（Code First）”方法的挑战

通常情况下，“代码优先”方法指的是团队从代码中生成机器可读的 API 定义，而不是自己去编写。他们将生成的文档作为构建资产而不是设计资产使用。“代码优先”方法并不代表团队忽略了设计，而是将设计隐藏在 Jira 工单、Confluence 页面或文本文档中，而这可能会造成遗漏。

使用“代码优先”方法的团队错过了在整个开发过程中利用 API 设计的好处，而不仅仅是在编写代码时，而这也导致了一些潜在问题：

• 沮丧的用户——如果 API 文档没有发布、不完整或与实际部署的 API 不一致，API 用户可能会感到沮丧并选择其他解决方案。

• 错误的 API——如果团队没有自动化工具来指导设计，团队可能会构建和部署错误的 API。

• 错失良机——如果团队没有发布其 OpenAPI 文档的过程，那么其他团队将无法看到，这可能会导致重复工作并错失良机。

• 不一致的开发人员体验——如果团队不使用工具来指导其使用的标准，他们可能会产生与其他团队不同的 API 实践与体验。

但说实话，任何团队要转向“设计优先”方法都需要付出一定的努力。尤其是对于大型企业来说，它们需要有专门负责引导过渡的人员。不过，无论公司的规模如何，都需要有明确的转向意愿和意识，因为从传统的代码优先转向设计优先是不会自动发生的。

“代码优先”的团队如何转为“设计优先”？

“代码优先”团队可以采取一些实际的方法来改进他们的工作方式，向“设计优先”方式迈进。

• 可信数据来源——团队可以找到将生成的文档用于更多的用途。他们可以将 API 定义视为在其 DevOps 流程中进行测试和部署的可信数据来源。

• API 发现——团队可以将文档发布到一个中央位置，供其他团队发现和试用。这有助于他们分享知识，并帮助其他人找到他们的 API。

• 已发布和当前的文档处理——团队可以确保自动化发布文档的过程，以便文档始终保持最新。

• 邀请合适的人员——团队可以让更多的开发人员参与 API 设计讨论，包括产品经理、QA 工程师和 DevOps 工程师等。

“代码优先”团队可以通过认真改进开发人员体验，并增加团队之间的沟通来降低一些风险。他们也可以使用这些步骤逐渐向“设计优先”过渡。

SwaggerHub 如何提供帮助？

无论采用何种方法，SwaggerHub 都可以融入您的开发工作流程。SmartBear 认为重要的是让产品在用户的 API 开发过程中提供支持，所以提供了很多工具，帮助团队实现这一目标。

• 设计工具——您可以尝试使用 SwaggerHub 编辑器来编写 OpenAPI 文档、用标准化的工具编写一致的 API，以及使用协作工具来讨论 API 的设计。

• 快速反馈工具——您可以尝试 API 自动模拟以获得快速反馈，并在开发人员构建之前尝试设计。

• 集成工具——您可以尝试使用源代码管理集成将 API 设计导入开发工作流，也可以尝试使用 API 管理工具来自动执行 API 部署。

• DevOps 和自动化——您可以尝试使用 SwaggerHub API 注册表，将 SwaggerHub 集成到 DevOps 流程中，并构建将 SwaggerHub 视为事实来源的自动化工作流程。

• 开发者工具——您可以尝试使用 SmartBear 的 Codegen 来生成客户端 SDK，以便在软件项目中轻松使用 API。它还可以生成服务器存根，用于启动 API 提供商的开发过程。

• 开源工具——您可以联系SmartBear授权合作伙伴——龙智，试用业界最佳的 OpenAPI 开源工具，如 Swagger 编辑器和 Swagger UI。

SwaggerHub 为团队提供了构建出色 API 所需的工具，无论他们使用的是“代码优先”方法还是“设计优先”方法。

开始使用 SwaggerHub

SwaggerHub是一个优秀的 API 设计和协作平台，致力于使 API 设计成为开发过程中的可信数据来源。SmartBear 为企业提供实施 API 策略所需的工具，并为处于 API 旅程任何阶段的人们提供帮助。

文章来源：https://smartbear.com/blog/embracing-an-api-design-first-approach/