Code First 方法是构建 API 的一种更传统的方法,在制定业务需求之后进行代码开发,最终从代码生成文档。Design First 方法提倡在编写任何代码之前先设计 API 的契约。这是一种相对较新的方法,但很快就会流行起来,尤其是在使用 OpenAPI 规范格式的情况下。
- 设计优先:计划被转换为人类和机器可读的合约 (API),例如 Swagger 文档,从中构建代码
- Code First:根据业务计划,直接对API进行编码,从中可以生成人类或机器可读的文档,例如Swagger文档
系统开发周期
这两种方法各有优缺点,归根结底,选择正确的方法归结为您希望通过 API 解决的直接技术和战略需求。让我们深入探讨何时以及为何选择“设计优先”或“代码优先”方法。
为了更好地理解这两种方法,让我们看一下 API 生命周期中遵循的一般过程。
- 与任何产品一样,API 的概念始于业务团队识别机会。战略家、分析师和其他业务人员对机会进行了分析,并在文本文档中创建了利用它的计划。
- 然后将该文档传递给开发团队,在那里该计划采用某种有形的形式。他们可以选择代码优先或设计优先的方法。
- 最后,在 API 运行后,对其进行充分测试,然后部署到合适的主机。
设计优先方法——当重用和可扩展性很重要时
API 优先方法意味着对于任何给定的开发项目,您的 API 都被视为一等公民,这有助于避免忽略所需的功能或将大量时间和精力投入到不需要的功能上。这类似于以客户为中心的精益产品设计,在这种设计中,设计师在详细介绍任何技术规格之前呈现概念并征求消费者的反馈。
API 优先的方法涉及开发一致且可重用的 API,这可以通过使用 API 描述语言来建立 API 应该如何表现的契约来实现。建立合同涉及花费更多时间考虑 API 的设计。它还经常涉及额外的规划和与利益相关者的协作,在编写任何代码之前提供有关 API 设计的反馈。
代码优先方法——当交付速度很重要时
如果开发人员直接从需求文档开始对 API 进行编码,则他们可以更快地开始实现 API。如果您的上市策略强调速度和敏捷性是 API 计划成功的重要因素,那么这一点很重要。这种方法可确保您的定义与您的实施保持一致,并且团队成员可能会发现它更容易和更简单,尤其是对于一次性和小型定制应用程序。
可视化 REST API 设计器
Visual Paradigm 的 API 设计工具使您能够以完全图形化的方式设计、描述和记录 RESTful API。您可以通过创建一个简单的类图来轻松设计 RESTful API,如下所示。图形设计方法以及我们屡获殊荣的图表界面使 API 设计变得简单、直接且无错误。
生成 Swagger/API 蓝图格式的 API
无需编写一行代码,API 设计人员就可以按照 Swagger 2 或 API Blueprint 规范生成完整的 API 定义。该 API 完全根据您的可视化 API 设计详细说明其所有资源和操作。
生成交互式 API 文档
生成美观的交互式 API 文档,让您的开发团队和最终消费者能够轻松开始使用您的 API 资源。可视化 API 文档使后端开发和客户端消费都变得容易。
References