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

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

原文: https://fdetimes.net/zh/tools/pact-contract-testing-client-api-changes/

在 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 库的语法：

```text
当消费者发送：     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 文件就是把这些依赖写下来，让机器替你检查。

**本周动手试试:**

- 选一个调用客户 API 的集成，准确列出代码读取的字段，再与该 API 返回的字段数量做对比。
- 用项目所用的语言为单个接口编写一个 Pact 消费者测试，然后打开生成的 pact 文件读一遍。
- 在正式提议引入 Pact 之前，先问问客户团队，他们的 CI 能否多跑一个验证步骤。

## 信源

- [Pact Docs (docs.pact.io)](https://docs.pact.io/)

- [How Pact works](https://docs.pact.io/getting_started/how_pact_works)

- [Can I Deploy - Pact Docs](https://docs.pact.io/pact_broker/can_i_deploy)

- [Pact FAQ](https://docs.pact.io/faq)

- [Pact Foundation · GitHub](https://github.com/pact-foundation)

- [pact-foundation/pact-specification](https://github.com/pact-foundation/pact-specification)

- [Consumer-Driven Contracts: A Service Evolution Pattern](https://martinfowler.com/articles/consumerDrivenContracts.html)
