REST API 开发 - 代码优先详解

在 REST API 开发中,代码优先是一种常见的开发方式。本文将详细介绍代码优先的定义、特点和优势。

用 Apifox,节省研发团队的每一分钟

REST API 开发 - 代码优先详解

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

本文将介绍 REST API 开发方法并带大家了解代码优先的方法。 设计优雅的 REST 风格 API 对于微服务至关重要,而对于 API 方法中的 Code-First 方法,则与企业战略类似:根据业务计划,直接对 API 进行编码,而后从中生成相应人员或机器可读的文档,诸如大家熟悉的 Swagger 文档。

 

正文开始前我们可以回顾了解下:REST API 简介 - RESTful Web 服务

REST API 开发 - 代码优先详解

 

本文概览

  • 什么是代码优先 REST API 开发?
  • Code-First 方法的优点是什么?
  • Code-First 方法的缺点是什么?
  • 什么时候使用代码优先方法?

 

什么是代码先行?

无论选择 REST API 或 SOAP API 哪种策略,两者中,都可以在下面选择一项 API 方法:

  • 代码优先,而后从代码生成合同
  • API 优先,基于 API 的代码开发

 

为进一步解释上述两种方法,下面给出一个 Code First 的示例:

 

Spring Boot Code First REST API 示例

假设我们正在开发一个 RESTful Web 服务,使用 Spring Boot Framework 来生成 API。有: 在 retrieveAllPets() API 中,通过访问 “ /pet” URI 并调用服务方法返回所有的宠物( /pet资源):当定位到这个 URL 时,返回所有宠物。 其他服务方法的定义与此类似,每个方法都有自己的 URI。

 

在这个示例中,我们可以根据代码生成文档,这份文档会指定对应人员如何使用这个方法。例如,我们可以使用 Apifox 工具 (Apifox 允许我们从代码生成文档)。如下所示,是由 Apifox 生成的 [获取所有宠物] 的文档内容:

REST API 开发 - 代码优先详解
REST API 开发 - 代码优先详解
Swagger
REST API 开发 - 代码优先详解
Swagger

这份输出文档包含我们要接收的响应消息的类型以及响应状态,我们还可以从 Apifox 调用对应的服务获取响应。 例如,如果需要向 /pet” 发送 POST 请求,Apifox 文档会输出请求信息并指明各个字段的格式、响应类型以及响应码。这种由 Apifox 从代码生成的内容被称为合同。

 

代码先行的优点

这种策略的主要优点如下:

  • 生成投入成本最小合同:因为这种合同是服务开发的副产品,它可以从代码中自动生成,不需要额外的劳力。
  • 代码和契约的同步:契约由代码生成,相互同步

 

代码先行的缺点

这种方式的主要缺点如下:

没有并行开发

服务生产者和服务消费者的工作不能并行展开:必须先开发服务,然后生成契约,最后才能编写遵守契约的消费者代码。如果不了解合同,服务消费者就无法开发。

 

团队没有目标

因为相关的服务方在开发前无法知道契约,如果开发过程中出现各个利益相关者没有达成一致的情况,这种预期偏差就需要对 API 文档重新修订了。

 

没有跨平台兼容性

由于各种原因,一些老平台想要从代码生成合约比较困难,生成的合约通常不支持跨平台兼容。

 

写在最后

本文探讨了构建 REST API 的代码优先方法。虽然基于代码开发的方式站在开发人员的角度来看是比较有效率的,但如果从服务供应商 - 服务消费者共同开发的角度,它就会遇到比较窘迫的情况。

 

Apifox 提供了非常适合契约团队的 API 开发方式,无论你选择哪一种:Apifox 是一体化 API 协作平台,可以实现 API 文档、API 调试、API Mock、 API 自动化测试,是更先进的 API 设计/开发/测试工具。Apifox 提供了一种全面的 API 管理解决方案。使用 Apifox ,你可以在一个统一的平台上设计、调试、测试以及协作你的 API,消除了在不同工具之间切换和数据不一致的问题。 简化了你的 API 工作流,并确保了前端、后端和测试人员之间的高效协作。

Apifox

知识扩展:

REST API 还有很多其他值得学习的相关文章。如果你想了解更多 REST API 相关知识,可查看下方链接: