本文将介绍 REST API 开发方法并带大家了解代码优先的方法。 设计优雅的 REST 风格 API 对于微服务至关重要,而对于 API 方法中的 Code-First 方法,则与企业战略类似:根据业务计划,直接对 API 进行编码,而后从中生成相应人员或机器可读的文档,诸如大家熟悉的 Swagger 文档。
正文开始前我们可以回顾了解下:REST API 简介 - RESTful Web 服务
本文概览
- 什么是代码优先 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 生成的 [获取所有宠物] 的文档内容:
这份输出文档包含我们要接收的响应消息的类型以及响应状态,我们还可以从 Apifox 调用对应的服务获取响应。 例如,如果需要向 “ /pet” 发送 POST 请求,Apifox 文档会输出请求信息并指明各个字段的格式、响应类型以及响应码。这种由 Apifox 从代码生成的内容被称为合同。
代码先行的优点
这种策略的主要优点如下:
- 生成投入成本最小合同:因为这种合同是服务开发的副产品,它可以从代码中自动生成,不需要额外的劳力。
- 代码和契约的同步:契约由代码生成,相互同步
代码先行的缺点
这种方式的主要缺点如下:
没有并行开发
服务生产者和服务消费者的工作不能并行展开:必须先开发服务,然后生成契约,最后才能编写遵守契约的消费者代码。如果不了解合同,服务消费者就无法开发。
团队没有目标
因为相关的服务方在开发前无法知道契约,如果开发过程中出现各个利益相关者没有达成一致的情况,这种预期偏差就需要对 API 文档重新修订了。
没有跨平台兼容性
由于各种原因,一些老平台想要从代码生成合约比较困难,生成的合约通常不支持跨平台兼容。
写在最后
本文探讨了构建 REST API 的代码优先方法。虽然基于代码开发的方式站在开发人员的角度来看是比较有效率的,但如果从服务供应商 - 服务消费者共同开发的角度,它就会遇到比较窘迫的情况。
Apifox 提供了非常适合契约团队的 API 开发方式,无论你选择哪一种:Apifox 是一体化 API 协作平台,可以实现 API 文档、API 调试、API Mock、 API 自动化测试,是更先进的 API 设计/开发/测试工具。Apifox 提供了一种全面的 API 管理解决方案。使用 Apifox ,你可以在一个统一的平台上设计、调试、测试以及协作你的 API,消除了在不同工具之间切换和数据不一致的问题。 简化了你的 API 工作流,并确保了前端、后端和测试人员之间的高效协作。
知识扩展:
REST API 还有很多其他值得学习的相关文章。如果你想了解更多 REST API 相关知识,可查看下方链接: