本文将探讨如何基于契约的方法来开发 REST API。 在 API 先行的策略中，基于 API 优先的服务契约管理成为微服务架构的重要原则之一。我们可以将 API 先行视为与商业契约类似，一旦需要与其他各方开展重要的业务，我们需要首先签订契约，或是双方达成某种协议。
文章概览
- 什么是基于契约优先的 REST API 开发？
- 契约优先方法的优点是什么？
- 契约优先方法的缺点是什么？
- 什么时候使用契约优先方法？
Web 服务的概念
Web 服务有两种类型：REST Web 服务 和 SOAP Web 服务。它们的共同点是都需要以下服务方：
- 服务提供者
- 服务消费者
消费者想要从服务提供者获取资源的详情，就需要签订合同，这种合同一般约定好如下内容：
- 服务的输入和输出分别是什么？
- 该服务在哪个 URL 可用？
- 如何发送授权？
契约优先法
使用 Contract First 方法，需要首先定义合同，然后注入服务。举例如下：
WSDL
Web 服务定义语言 WSDL 的用例：
WSDL 通常与 SOAP/XML 网络服务一起使用：
合同约定是什么意思？
约定合同就代表定义了 WSDL，通过这种方式可以与我们的消费者共享信息。这些都发生在我们实施服务并提供消息可用之前。 合同会告知消费者请求和响应的交换方式。合同签订后，服务提供商可以根据合同提供服务，服务消费者也可以开发应用程序供其使用。
合同优先方法的好处
团队并行开发
在编码基于合同的契约下，服务提供商和服务消费者都清楚地了解沟通的方式和细节，这样两者就可以同时进行开发。
团队联调模拟
因为编码是基于合同的，服务生产者和服务消费者都会清楚彼此的期望。因此，如果由于开发节奏不同而无法进行联调，也可以使用软件来模拟对方基于合约的行为。
跨平台兼容性
由于服务的参数仅取决于合同，因此用于开发服务的实际软件结构并不重要。服务提供者和服务消费者可以使用不同的技术。
允许使用重用模式
用于定义服务契约的模式在 WSDL 中得到了很好的定义。因此，如果部分服务在其他服务中重复，那么相应的模式也可以重用。
合同优先方法的缺点
需要额外的启动成本
这些额外成本的消耗，大部分都是因为服务协议的原因。我们可以通过确保合同定义，以及避免经常更改，来减少或控制这部分的支出。
合同续签和交换机制
在服务生命周期内，如果续签合同，会影响所有其他相关方。因此，必须有一种适当的机制来将更改传播到不同的消费者。
契约优先最佳实践
在本文中，我们讨论了 Web 服务上下文中的契约优先方法。契约优先的要点就在团队要事先约定好接口的设计，再依此进行开发，以提高后期联调的成功概率， Apifox 提供了非常适合契约优先团队的 API 工具，帮助你更好地在团队内部施行契约优先。
Apifox 是一体化 API 协作平台，可以实现 API 文档、API 调试、API Mock、 API 自动化测试，是更先进的 API 设计/开发/测试工具。Apifox 提供了一种全面的 API 管理解决方案。使用 Apifox ，你可以在一个统一的平台上设计、调试、测试以及协作你的 API，消除了在不同工具之间切换和数据不一致的问题。 简化了你的 API 工作流，并确保了前端、后端和测试人员之间的高效协作。
其中文档模式就是适用于契约优先的团队，调试模式适用于代码优先的团队。基于 Apifox 你可以非常轻松地实践契约优先。
基于 Apifox 轻松开发 REST API
- 前端（或后端）在 Apifox 上定好接口文档初稿。
- 前后端一起评审、完善接口文档，定好接口用例。
- 前端使用系统根据接口文档自动生成的 Mock 数据进入开发，无需手写 mock 规则。
- 后端使用接口用例 调试开发中接口，只要所有接口用例调试通过，接口就开发完成了。如开发过中接口有变化，调试的时候就自动更新了文档，零成本的保障了接口维护的及时性。
- 后端每次调试完一个功能就保存为一个接口用例。
- 测试人员直接使用接口用例测试接口。
- 所有接口开发完成后，测试人员（也可以是后端）使用集合测试功能进行多接口集成测试，完整测试整个接口调用流程。
- 前后端都开发完，前端从 Mock 数据切换到正式数据，联调通常都会非常顺利，因为前后端双方都完全遵守了接口定义的规范。
知识扩展：
了解更多 REST API 相关知识。