FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

工具

客户改 API 之前,Pact 先告诉你集成会不会坏

契约来自你自己的测试:客户可以随意新增字段,只有改坏你实际用到的部分才会被拦下。

分享微博

要点速览

  • 在 Pact 中,没有人手写契约:契约是在消费者测试针对模拟提供者运行时生成的。
  • 只有提供者删除或修改了消费者需要的数据时验证才会失败;新增字段照样通过。
  • can-i-deploy 返回退出码 0 或 1,因此可以在流水线中直接拦下不兼容的版本。
决策树:客户修改 API 时,要看这次改动是否涉及你读取的字段。如果不涉及,比如新增第 31 个字段,验证通过。如果涉及,比如重命名某个字段,验证会在客户的 CI 中失败,版本在部署前就被拦下。
API 返回 30 个字段,契约只记录你的代码读取的 3 个。客户可以随意新增字段,但重命名你用到的字段会在他们自己的 CI 中被拦下。来源:Pact 文档;示例出自本文,仅作说明。

在 Pact 中,没有人需要坐下来手写契约。契约是在 API 调用方的自动化测试运行时生成的,这也是它比大多数集成测试方法更适合前线部署工程师(FDE)的原因。

这种场景大家并不陌生:你的集成调用客户系统,平稳运行了好几周,某天早上突然出错,原因是对方团队改了一个字段名。

没有人提前通知你,因为他们并不知道你的代码用到了这个字段。Pact 会准确记录你这一侧依赖哪些内容,并把这份清单放进对方的 CI,让故障在部署前暴露,而不是部署后。

Pact 到底检查什么?

Pact 的官方文档由 Pact Foundation 维护,文档将它描述为一款代码优先的工具,用契约测试来测试 HTTP 和消息集成。需要理解的两个角色是消费者(consumer)和提供者(provider)。Pact 对消费者的定义是:借助另一个应用的功能或数据来完成自身工作的应用。

在客户项目中,消费者通常是你:你构建的 Agent、数据管道或集成服务。提供者是客户的 API。由于契约来自消费者的测试,其中只包含消费者真正用到的内容。其余部分,提供者可以随意修改。

这个思路比 Pact 早了好几年。2006 年,Ian Robinson 在 Martin Fowler 的网站上发表了《Consumer-Driven Contracts: A Service Evolution Pattern》,用“消费者驱动契约”一词指代按消费者需求塑造的提供者契约。Pact 把这一模式变成了可用的工具。

一个端到端示例

假设你正在对接一家零售客户的订单服务。获取订单的接口返回 30 个字段,但你的代码只读取其中 3 个:订单 ID、状态和总额。这就是你需要保护的契约。

第一步,针对这个请求编写消费者测试,声明一个只包含这 3 个字段的预期响应。下面的示意只用来说明场景的含义,并不对应任何 Pact 库的语法:

当消费者发送:     GET /orders/123
提供者必须返回:   status 200
响应体至少包含:   order_id, status, total

测试运行时,Pact 会启动一个模拟提供者:它将你的代码实际发出的请求与预期请求比对,然后返回声明好的响应。你的代码把这个响应当作真实响应处理,测试运行结束后产出一个 pact 文件。

第二步发生在客户一侧。pact 文件被用来验证真实的提供者:Pact 将文件中的每个请求重放到对方的服务上,并检查响应。根据 Pact 文档,只要每个响应至少包含契约中描述的数据,验证就会通过。

设想客户对 API 做了两处修改。他们为会员积分计划新增了第 31 个字段:验证照样通过,因为你需要的 3 个字段都还在。他们把 status 字段改了名:验证立即在对方的 CI 中失败,这个版本到不了生产环境,你的集成也不会在半夜崩掉。

第一份契约的三个常见错误

最常见的错误是仅仅因为 API 返回 30 个字段,就把 30 个字段全部声明。这样一来,契约会把客户绑死在 27 个你从未读取的字段上,对方任何无害的改动都会让验证变红,用不了多久,客户团队就会把验证步骤当成噪音。

规则很简单:打开你的代码,只有确实有某一行读取了某个字段,才把它写进契约。

第二个错误恰恰相反:写完消费者测试、生成 pact 文件就停下了。模拟提供者只能证明你的代码能处理你自己描述的响应。真正的价值在于用 pact 文件验证真实的提供者,所以在客户一侧跑起验证之前,不要认为工作已经完成。

第三个错误是只写“正常路径”场景。如果你的代码还处理订单不存在的情况,那就是契约需要的另一个场景,因为 Pact 只保护你写了测试的内容。

用退出码拦截部署

pact 文件需要有地方存储和共享,这就是 Pact Broker 的职责。Broker 了解各应用之间的依赖关系,因此 can-i-deploy 命令可以回答一个非常具体的问题:即将部署的版本,是否与目标环境中正在运行的其他应用版本兼容?

答案是一个退出码:0 表示可以部署,1 表示不行。这样它就能直接接入任何流水线,无需有人去读报告。如果客户需要单点登录(SSO)、用户管理或更好的界面,Pact 文档介绍了 PactFlow,它是 Pact Broker 的一个商业分支。

Pact 替代不了什么

第一个局限就写在 Pact 对自己的描述里。项目的 FAQ 称它是“contract by examples”(基于示例的契约),区别于描述所有可能状态的 schema。Pact 只保护你写了测试的场景;你忘记声明的字段,它不会替你守护。

第二个局限:FAQ 列出了一些不适合用 Pact 的情况,其中包括消费者多到无法与每一个保持直接联系的 API。服务成千上万客户的公共 API 就属于这一类。而对于客户内部服务、你的集成只是少数几个消费者之一的情况,Pact 非常合适。

第三个局限关乎人,而不是技术。只有客户团队同意在他们的 CI 中运行验证步骤,Pact 才有价值。实用的建议是:不要一开口就说“装上 Pact”,而是从一次具体的事故谈起,并带上一份已经针对出事接口写好的小契约。

先学什么

先掌握消费者和提供者这两个角色,其他一切都围绕它们展开。然后用项目所用语言的 Pact 库,为一个 HTTP 接口编写消费者测试;Pact 支持多种语言,其中包括面向 TypeScript 的 pact-js,因此你很少需要更换技术栈。

仔细阅读生成的 pact 文件,之后再去学 Broker 和 can-i-deploy。如果你的集成走的是消息队列而不是 HTTP,可以等熟悉 HTTP 流程之后,再去看 V3 规范起提供的消息契约(message pact)。

在简历上,写一句“将契约测试引入客户 CI,在部署前拦截会破坏集成的 API 变更”,比在技能列表里写“Pact”更有说服力。阅读 FDE 招聘启事时,“与客户系统集成”“集成可靠性”这类表述,正是讲这段经历的地方。

与客户的集成很少因为你的代码写错而出问题。更常见的原因是双方团队都不清楚对方依赖什么,而 pact 文件就是把这些依赖写下来,让机器替你检查。

这篇文章对你有帮助吗?

7 个信源
路线图上的下一篇 · 阶段 6: 价值度量一行 k6 配置,把变慢的构建挡在生产环境外p95 阈值不达标时 k6 以非零码退出,CI 直接判红,性能退化不必等客户投诉才发现。