实现 API 优先设计的重要性和实现方式

[vocalman]

应用 API 优先的方法意味着设计 API 时，使其具有一致性和适应性，无论应用于哪些开发项目。对 API 使用 API 描述语言（如 OpenAPI ）是关键，因为它有助于建立 API 与其他程序通信的枢纽，即使这些系统各自的语言不同。当然，API 不存在于单独的真空中，因此与其利益相关者的协作和规划对于设计过程同样重要，设计过程早在任何代码实际编写之前就开始了。简而言之，实施 API 优先的策略需要你在设计流程开始前就已经确定下了。

为什么 API 优先设计很重要？

传统上，一旦发现问题并且有人意识到新系统能够提供必要的解决方案，软件设计过程就开始了。一旦建立了广泛的草图，下一步通常就会深入挖掘以评估可能需要的任何用例和正在创建的系统所需的交互形式。当然，所有这一切都必须考虑到用户体验（ UX ），因为拥有一个有效的系统是不够的; 对于即将与之交互的开发人员和使用者而言，它也需要对用户友好，无论是在后端还是在前端。

有时问题甚至更简单，如果你有一个内部应用程序，其中包含你希望通过 API 访问其他系统的数据。但是，该系统有自己的逻辑，可以告知其行为和与他人的交互方式。因此，你创建的任何 API 都将围绕这些特性和规则构建。一旦你的内部应用程序作为 API 连接的一部分，开发人员就会根据系统的内部结构进行交互并附加上它。如果这是你想要的，那可能没问题，但如果你以后需要对你的内部模型进行更改，就会出现问题。使用 API 优先方法进行设计意味着构建一个不仅仅是内部系统副产品的 API。

开发人员应该能够快速又轻松地了解 API 的工作方式，并与其他应用程序集成在一起。只有这样，他们才能编写优雅的代码，以便与其他系统进行有效的交互，标准就是正确运行 API 时，它既向后兼容又往前扩展。

API 优先设计方法的优点

1.开发团队可以并行工作

签订协议允许开发人员同时在 API 开发的不同阶段工作，而无需等待应用程序更新所需的时间。因此，开发人员可以根据预先建立的计划模拟 API 并有效地测试任何相关的参数项，这样就会无形中提高了整体的开发效率。

2.降低开发应用程序的成本

API 优先设计方法的可重用性允许代码从一个项目转移到另一个项目，以便开发团队始终拥有可以使用的基线架构。通过消除每次都要从头开始编码的需要，任何相关的时间和财务成本也同样降低。此外，开发人员能够更快速地解决 API 问题，而且无需新建任何代码，从而可以更顺畅地与其他应用程序集成。

3.加快发布速度

自动化支持的“可直观查看” API 使新手开发人员能够快速轻松地与 API 文档进行交互。实际上，许多 API 构建过程可以使用具有可视 API 编辑器的工具自动化，可以导入 API 定义文件并自动生成文档，甚至模拟 API 的返回结果。这些工具大大缩短了开发时间，提高了产品发布的速度。

最重要的是，使用 API 优先的方法，你仍然可以灵活地添加新的应用程序产品功能，而无需重新设计 API 体系结构。这是敏捷开发的环境管理的一个明显优势，因此预计应用程序更新将根据最终用户需求快速发布。

4.改善开发者体验

开发人员每天都与 API 进行交互，因此创建一个提供积极的开发人员体验（ DX ）的 API 至关重要。API 第一种设计方法产生的 API 经过精心设计，并且具有良好的文档记录并且与其核心保持一致。开发人员可以使用 API 更轻松地与其他应用程序集成，快速解决出现的任何问题，甚至可以在更短的时间内登陆其他开发人员，这要归功于不那么强大的学习曲线。

5.降低失败风险

对于大多数企业而言，API 是开发环境中不可或缺的一部分，涉及从营销和销售到代表其品牌的、面向使用者的应用程序等所有内容。任何部分的 API 故障都可能是毁灭性的。但是，采用 API 设计优先的方法，由于设计和实现的固有的可靠性，稳定性和一致性，大大降低了出错的可能性。

应用集成环境下的 API 设计

API 为系统之间的通信提供了统一的结构，无论是新的还是传统的，允许数据传输进行转换。但 API 实施不仅仅是一个 IT 问题，必须根据整个组织的目标设计 API。通过将 API 策略置于设计流程的最前面，可以改进系统之间的应用程序集成和互操作性，并在许多情况下进行优化。而且如果更改，你仍然可以选择用其他方式进行开发。

精心设计的 API 有什么特点？

最有效的 API 设计包括以下属性：

1.易于阅读和使用：详细全面且简洁的 API 文档易于阅读，并提供支持开发人员使用的简单示例。引用和参数都非常直观，因此易于学习和记忆。

2.难以滥用：实现和集成 API 方式很容易区分，使开发人员很难滥用它，即使在编写代码时也是如此。它还包含信息反馈，同时允许开发人员具有相当程度的灵活性。

3.完整而简洁：API 非常全面，允许开发人员使用其通信的数据，在可预见的未来，逐步构建完整的应用程序。这种稳定可用性和灵活性代表了每个 API 创建者应该追求的设计理念的类型。

API 优先设计的工具

现在，有很多许多工具和标准可以支持 API 优先开发，如 EOLINKER、RAML、Swagger，都提供了出色的编辑工具来支持 API 优先设计的策略。EOLINKER 主要在文档页面清晰，编辑逻辑简易，支持自定义 MOCK 测试，而且支持 UI 直观化的自动化测试，读取代码注释生成文档也可以胜任，而 Raml 和 Swagger 页面显示也不错，可以编辑、测试等基本功能，不过相比 EOLINKER，在自动化测试功能方面略显不足，而且只有前者是支持中文的，后两种只支持英文语言。这些 API 编辑器都能轻松地实现 API 版本的控制，使得更容易在更短的时间内完成整个开发测试流程。

附上 EOLINKER 网址：https://www.eolinker.com

附上 RAML 网址： https://raml.org

最后的想法

API 优先的方法可以对 API 的使用产生巨大的影响。如果你设计的 API 目标包括高使用率和保留率，或者提供给开发人员出色的开发体验，那更是如此。最有效的 API 设计通过易于理解的内容和明确的目标导向提供直接的使用者体验，从而实现快速集成和使用。同样，随着学习曲线的降低，API 才会享受其可重用性和让开发人员的持续参与。

参考资料：David Brown，Implementing an API-First Design Methodology 原文地址： https://dzone.com/articles/implementing-an-api-first-design-methodology