什么是API优先开发？

 API-First 是几种 API 开发方法之一。那么，我们来定义一下什么是“API 开发方法”，并探讨一下可用的选项。 API 开发方法是一种设计、开发、部署和管理 API（应用程序编程接口）的方法论。它提供了一个创建 API 的框架，包括规划、文档编写、实现、测试和维护。最常采用的三种 API 开发方法是： * Code-First * Design-First * API-First 您不需要单独采用这些方法。相反，您可以使用更适合项目需求的变体或混合方法。 最终，您应该根据项目复杂性、团队动态、前期规划需求、需求灵活性以及集成需求来选择合适的方法。 

深入探讨：API 开发方法

方法一：Code-First

 Code-First 的 API 开发方法涉及通过代码来设计和实现 API。API 规范是在构建 API 之后才生成的。 开发人员跳过了正式的设计阶段。相反，他们根据基本需求来定义 API 端点、请求/响应模式以及业务逻辑。然后，他们使用诸如 OpenAPI 之类的工具和框架来生成 API 规范、文档和其他制品。 使用这种方法，“代码”是 API 规范的唯一事实来源。 以下是 Code-First 方法的概述： 

重点：

• 通过编码设计API，随后生成相关工件。

优势：

• 没有设计阶段来拖慢开发进度。 

• 开发团队可以自由地根据项目需求的变化来实施更改。

挑战：

• 团队之间缺乏清晰度、有效沟通、一致性和协调性。 

• 在开发过程中进行更改比在设计阶段成本更高。

以下是代码优先方法关键组成部分的概述：

通过代码设计

开发者不是从正式的API规范或设计文档开始，而是首先编写实现API端点及相关逻辑的实际代码。然后，他们在代码中定义API的请求/响应模型、身份验证机制以及其他方面。

框架与注解

开发者使用框架和库来为代码添加API详情的注解。这些框架可以解析代码并生成API规范。利用该规范，他们使用像Swagger这样的工具来生成开发文档、客户端SDK和工件。自动化有助于确保一致性，并减少维护文档的手动工作量。

迭代开发

这种方法非常灵活，因为它允许开发者迭代API设计并快速进行更改，从而实现更快的开发周期。

与实现的紧密结合

在API需要与实现要求及底层业务逻辑紧密对齐的场景中，API代码与规范的紧密耦合是有益的。

方法 #2：设计优先

设计优先是一种协作方法，来自业务各方的利益相关者使用“对所有人都易于理解”的语言和工具共同参与API设计。编写规范先于开发，甚至在编写规范之前还有一个“设计”阶段。利益相关者通过使用“更高层次”的语言解读基本需求，在概念上规划API的功能。

一旦需求明确且各方达成共识，团队就可以解读项目需求，使用图形化工具创建API的结构、端点和数据格式。

请注意，在整个过程中，开发人员和非开发人员会协作完善规范。

以下是设计优先方法的概述：

关注点：

• 跨职能的利益相关者在编写代码之前，预先设计和记录API规范。 

• API规范在开发过程中充当合同。

优点：

• 通过对API规范的共同理解，实现清晰一致的团队沟通。 

• 前端和后端团队可以并行工作。

• 在设计阶段进行更改成本更低。

挑战：

• 预先的设计工作和团队协调是资源密集型的。 

• 跨职能沟通的延迟和官僚层级可能会拖慢进度。

以下是设计优先方法关键组成部分的概述：

广泛的設計階段

利益相關者，包括開發人員，必須以一種『共享語言』進行溝通。

開發人員和非開發人員使用一套共享的工具進行協作，這通常包括視覺化的 API 設計工具。然後，他們可以生成機器可讀格式的 Open API 規範。

規範即契約

API 規範成為所有相關利益相關者在 API 開發過程中的單一事實來源。因此，對 API 的更改需要所有利益相關者的認可。

文檔

API 規範充當 API 的設計契約和文檔。採用設計優先方法，團隊可以在其 API 規範中徹底記錄他們的 API。這項工作需要協作來確定需求、功能和預期行為。

驗證和模擬

採用規範語言允許您使用工具根據標準、最佳實踐和錯誤來驗證和測試 API 規範。模擬工具可以根據規範生成模擬響應。客戶端開發人員可以開始使用虛擬 API 工作，提供早期反饋機會。

當然，您也可以使用代碼優先方法實現原型和模擬。然而，設計優先只需要您的規範，而代碼優先則需要 API 實現代碼。

方法 #3：API 優先

公司可能提供各種產品和服務。然而，API 優先公司將 API 視為連接所有其他產品的最關鍵產品。因此，他們會優先考慮其開發。

以下是 API 優先方法的概述：

关注点:

• 将API开发置于其他软件组件之上 

• 创建一个API生态系统，其中每个API都扮演特定角色

优势:

• 跨API提供一致的开发者体验 

• API可独立演进，减少依赖关系

• 标准定义了系统组件的交互方式

挑战:

• 需要宣传推广，向业务方阐明为何应优先考虑API 

• 缺乏与前端团队的并行开发

以下是API优先方法关键组成部分的概述。

顺序

API是连接所有可交互和交换数据的独立软件、服务或应用程序的主要接口。因此，采用API优先策略的企业会在构建依赖该API的服务、组件和用户界面之前，首先构建API。

相比之下，设计优先或代码优先可能不会将API构建置于其他组件之上。例如，团队可能希望在创建API的同时创建用户界面。

模块化与可复用性

采用API优先方法，每个API都被视为API生态系统中的一个“产品”。因此，团队可以使用他们认为最适合该API的技术栈来构建API。此外，通过保持与组合中其他API的独立性，API可以独立演进和改进。

互操作性

API优先强调标准化，首先从开发API规范开始，将其作为集成外部服务、第三方平台或开发者生态系统的接口。

开发者体验 (DX)

在组织的整体 API 生态系统中，每个 API 都承担着特定的职责。这种方法与那种缺乏对整体产品“清晰愿景”而开发互不关联的 API 的倾向形成了鲜明对比。其结果是由于具有一致性，带来了更好的开发者体验。

混合方法：API优先与设计优先

将 API 优先与设计优先相结合，可以让你兼得两者之长。你可以优先开发你的 API，同时也能利用通用语言和共享工具进行协作。

这种混合方法具有若干优势，有助于提高效率、灵活性和可扩展性。以下是一些关键优势。

设计清晰性与一致性

当你将 API 置于其他软件组件之上优先考虑时，你可以专注于设计 API，使其发挥最大效用。团队可以创建一个明确定义的契约，概述端点、数据结构和预期行为。这种清晰度确保了不同组件间的一致性，并促进了团队间的有效沟通。

可扩展性与敏捷性

一个设计良好的 API 提供了一个可扩展的架构。它允许在不影响前端实现的情况下添加或替换后端服务。这种灵活性支持敏捷开发实践，使得应用程序能够随着时间的推移更容易地适应和发展。

创新与协作

客户端开发者可以创建企业最初未曾设想的创新解决方案。企业可以利用这些新用例来改进API。如果公司能营造协作环境，客户端开发者就能以新颖创新的方式共同构建解决方案。

版本控制与维护

将API规范与API实现分离，使得对API应用版本控制变得更加容易。通过使用版本控制，您可以在确保向后兼容性、减少对现有客户端干扰的同时，为API添加新功能和变更。

API优先/设计优先面临的挑战

结合使用API优先和设计优先方法，会带来一些团队需要考虑的挑战。最常见的挑战如下。

前期设计

创建定义明确的API规范需要更多的前期设计工作。这可能是资源密集型的，并且需要团队之间进行仔细规划和协作，而团队之间的优先事项有时并不相同。

API变更

随着需求的演变而更改API提供了灵活性，但也可能导致复杂且成本高昂的变更。此外，在迭代过程中，一个挑战是保持与现有客户端的向后兼容性。

沟通与协作

跨职能团队之间必须紧密协作才能成功，这要求各方对API规范有共同的理解。

学习曲线

开发人员必须学习设计原则，并与非开发人员协作，使用可视化的API设计工具（而不是编码）来创建规范。

测试与验证

除了API代码之外，开发者还必须根据API规范进行测试和验证。这可能具有挑战性，通常需要专门的工具和专业知识。

治理

API需要进行治理，以确保其安全性、可扩展性，并与业务的整体目标保持一致。遗憾的是，建立适当的治理结构既复杂又耗费资源。

第三方依赖

通常，开发者不会自行构建用于设计和维护API规范的工具。相反，他们依赖第三方服务或平台，由于这些并非内部产品，可能会带来风险和复杂性。此外，第三方依赖项的变更可能影响API规范，并促使需要更新实现代码。

如何遵循API优先/设计优先方法？

要成功遵循这种混合方法，必须确保公司将API置于其他产品之上，并且团队致力于协作构建API。

采用API优先和设计优先的API开发方法，需要遵循一系列步骤和实践，优先考虑规范与实现代码的设计、文档编写和并行迭代。

采用这种混合方法的一般准则如下。

识别需求

在编写规范之前，通过确定API需要支持的核心功能、数据结构和交互，确保团队理解API的需求。

定义API合同

选择一种符合这些需求的API架构和规范语言。接下来，指定数据模型、操作和身份验证机制，然后使用适当的工具（如OpenAPI、RAML或API蓝图）来创建和生成API规范。

协作

API优先方法需要业务利益相关者、开发人员和其他各方之间的紧密协作，以维护API并遵守API合同。

验证

经常验证API规范，确保其满足客户端应用程序的需求。

模拟和原型

仅凭规范，您就可以使用工具生成模拟响应来模拟“真实”的API。即使API开发尚未完成，前端开发人员也可以开始使用虚假服务器响应构建客户端应用程序。原型设计提供了一个早期获取反馈的机会，以测试API设计的可用性。

实施

一旦规范经过验证并满足客户端应用程序的需求，开发团队就可以根据API规范实现API端点和业务逻辑。此外，框架和库允许您仅从API规范生成样板代码，用于实现您的API。

测试

彻底的测试确保API实现与API规范一致，并按预期运行。与其从头开始构建测试工具，不如利用维护良好的API测试框架和工具来验证规范，确保合规性。

文档和生成SDK

如果您的API符合OpenAPI等模式语言，您可以使用工具根据API规范生成文档。API参考文档至关重要，它能让API用户了解资源、端点、请求/响应模式、身份验证和授权，以及给开发者的任何其他指南，例如入门指南和操作教程。此外，根据API的不同，您还可以从API规范中生成客户端SDK和代码示例，以简化客户端应用程序的集成。

部署与版本管理

以下是关于API部署和版本管理的一些指导原则：

• 首先，将API部署到生产环境，以便客户端开发者能够访问该API。 

• 在网关上配置适当的安全机制。

• 确保实施负载均衡以分配传入需求，从而有效防止服务器过载。

• 确保启用版本管理，并且能够管理向后兼容性，以便进行不会对现有客户端产生负面影响的更改。

迭代

您可以根据从客户端开发者收集的反馈来完善API设计。相关的文档应通过自动化反映所做的更改。

总结

总体而言，API开发需要细致的规划、管理和协调，以克服保持规范与代码同步的挑战。此外，恰当的沟通、治理和协作对于设计、测试API并将其与组织的业务目标对齐至关重要。

每种 API 开发方法都有其优势和挑战。由于不存在“万能灵药”，总需要权衡利弊。团队需要根据需求、团队协作和开发偏好来决定如何最佳地实现 API。
Baklib 新一代数字内容体验云平台，帮助企业管理一站式内容中台，构建一体化数字体验站点。知识不需要管理，需要体验，通过Baklib 创建多场景、多站点、一致性的数字体验。