本文将介绍 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 相关知识，可查看下方链接：