用 Pact 消费者驱动契约测试与…

当独立部署的消费者/提供者服务需要在不共享集成环境的前提下保证接口兼容时，用 Pact 契约测试 + Pact Broker + can-i-deploy 把破坏性变更拦在部署前。

适用场景

解决思路

1. 先检查 `.agents/qa-project-context.md`，若存在就用它并跳过其中已回答的问题；否则先确认：架构（微服务 / 带独立消费者的单体 / BFF）、契约所有权（消费者驱动还是提供者驱动）、API 版本策略（URL `/v1/`、header 还是无）、consumer-provider 对数（从流量最高或最脆弱的集成开始，不要一次全做）、是否已有 OpenAPI/Swagger 规范、是 HTTP 还是异步（Kafka/SNS/SQS 走 Pact message 契约）。
2. 在消费者和提供者两侧都把 `@pact-foundation/pact` 安装为 dev dependency。
3. 消费者侧写契约测试：声明需要的请求形状与期望响应，运行后生成 `pacts/<consumer>-<provider>.json`；用 `Matchers`（`Matchers.like`、`Matchers.eachLike`、`Matchers.integer`、`Matchers.string`、`Matchers.regex`）断言类型和格式，而不是脆弱的精确值。
4. 提供者侧做验证：让提供者用真实实现（不是 mock）跑消费者的 pact，用 `stateHandlers` 为每个 `given(...)` 状态准备数据，并把验证结果发布回 broker。
5. 注意 Pact-JS v16 的重命名：`PactV4` → `Pact`、`MatchersV3` → `Matchers`；旧名在 v16 已移除，从旧博客/示例复制的代码要改 import（API 行为不变）。
6. 事件驱动系统用同一个 `Pact` 类写 message pacts（Kafka、SNS/SQS、RabbitMQ）：消费者断言期望消息的形状，提供者验证其 producer 实际发出的内容。
7. 用 Docker Compose + Postgres 在本地跑 Pact Broker；消费者 CI 用 commit SHA 和 branch 作为 tag 发布 pact；所有凭据（Postgres 密码、broker DB URL、basic-auth 密码）从环境变量注入，broker 镜像固定到发布 tag 而非 `:latest`。
8. 按完整闭环执行：① 消费者写契约测试生成 pact JSON → ② 消费者 CI 发布 pact 到 broker（带 consumer version + branch tag）→ ③ broker webhook 触发提供者验证 → ④ 提供者 CI 拉最新 pact 运行验证 → ⑤ 提供者把验证结果发布回 broker（记录“provider v2.3.1 满足 consumer v1.5.0”）→ ⑥ 部署前跑 `can-i-deploy` 检查。
9. 在 Pact Broker 配置 webhook：新 pact 发布时向 `https://api.github.com/repos/myorg/user-service/dispatches` 发 `POST`，事件类型 `pact-changed`，由提供者流水线监听（`repository_dispatch` 触发）。
10. 增量接入时在提供者 `Verifier` 上设 `enablePending: true`（配合 `includeWipPactsSince`），让全新的消费者交互先只上报不失败，直到消费者把它标记为预期。
11. 提供者验证不要读本地 pact 文件：用 `pactBrokerUrl` + `consumerVersionSelectors` 从 broker 拉取，让验证反映真实在线的消费者版本。
12. 部署闸门：用 `can-i-deploy` 查 broker matrix 判断该版本与目标环境已部署内容是否兼容，部署成功后用 `record-deployment` 记录以保持矩阵准确；始终加 `--retry-while-unknown <n> --retry-interval <s>` 以避免“消费者刚发布、提供者还没验完”的竞态硬失败；`main` 上绝不跳过该检查。
13. 按场景选方法：consumer-first（Pact）适合不同客户端需求各异（移动端要的字段比 Web 少）、API 有机演进、微服务生态；schema-first（OpenAPI + 校验）适合面向公众的多消费者 API、先设计后实现、API 治理强的团队。
14. 混合做法：用 OpenAPI 做设计产物（提供者团队主导设计）→ 从 OpenAPI 规范生成 Pact 消费者测试作基线 → 消费者在基线之上补充具体交互 → 提供者按 Pact 契约（OpenAPI 规范的子集）做验证。
15. 双向下契约（PactFlow / SmartBear，付费非 Pact OSS）：提供者提供 OpenAPI spec、消费者提供 pact，PactFlow 检查兼容性而不要求提供者在 CI 跑 pact verification；适用于提供者团队不能/不愿跑 Pact verifier、或提供者已把 OpenAPI spec 当唯一真相的场景。它比完整 pact 验证更粗（只验 spec/契约重叠，不验精确运行时行为），作为上手坡道，双方接受后升级为完整验证。
16. OpenAPI 3.0 不是纯 JSON Schema（`nullable: true` 等）：原生 Ajv 默认 draft 2020-12，会误判真实 3.0 spec；要用 `ajv-formats` 把 Ajv 配置为 OpenAPI dialect，或改用 OpenAPI 感知的校验器。
17. 对 OpenAPI 优先的项目加 Schemathesis（v4.x）：直接从 spec 对运行中的 API 做属性化测试，生成大量合法+非法请求并校验响应符合性，捕捉 Pact 抓不到的编码、边缘 payload、状态码漂移类问题。与 Pact 搭配：Pact 管消费者驱动的“交互”，Schemathesis 管 spec 驱动的“覆盖”；CI 里优先用 `schemathesis/action@v3` Action 而不是裸 shell 命令。当前命令形式为 `schemathesis run ./openapi.yaml --url <base> --checks all`（v4 已移除 `--hypothesis-deadline`、把 `--base-url` 改名 `--url`，schema 变为位置参数，旧的 `--base-url` + `--hypothesis-deadline` 写法在 v4 已失效）。
18. 逐级验证产出物（先跑最小检查）：① `npm run test:contract`，确认写出 `pacts/<consumer>-<provider>.json` 且包含声明的交互（没有文件就等于没有契约）；② `npm run test:contract:provider`（测试数据库已启动），确认每条消费者交互对真实提供者全绿；③ 用 `pact-broker publish ./pacts --consumer-app-version=$GIT_COMMIT --branch=$GIT_BRANCH` 发布，确认 broker UI 里能看到 pact 和已记录的验证结果；④ 用 `pact-broker can-i-deploy --pacticipant=<name> --version=<sha> --to-environment=production --dry-run` 确认对已知良好版本返回明确的 yes/no 而不是 “unknown”。
19. 按完成标准收口：契约测试在 CI 每次运行都生成 pact 并发布到 broker（tag 为 commit SHA + branch）；提供者验证在每次提供者变更和每次新 pact 发布（经 broker `repository_dispatch` webhook）时运行且从 broker 拉契约；两个流水线在 `main` 上以带 `--retry-while-unknown` 的 `can-i-deploy` 把关并在契约破坏时 fail；为每个 consumer-provider 交互指定 owner/reviewer 的 `CONTRACTS.md` 或 `CODEOWNERS`；至少端到端跑过一次破坏性变更并确认被 `can-i-deploy` 在进生产前拦下。
20. 保持契约“薄”：只断言状态码、字段存在、字段类型、字段格式；业务规则放单元测试和集成测试。
21. 不要写无消费者输入的提供者驱动契约——那测的是提供者以为消费者需要的，而不是消费者真正使用的，抓不到真实集成失败。
22. 不要跳过 provider states：消费者期望 `given("user 123 exists")` 时，验证必须准备对应场景；在空库上跑的验证毫无意义。
23. 不要从本机发布 pact——必须由 CI 带已知 commit SHA 和 branch 发布，否则产生不可追溯的版本并污染 broker。
24. 不要忽略 `can-i-deploy` 失败：失败就修契约违约或与消费者团队协商变更，硬部署会打爆生产。
25. 不要做一个覆盖所有端点的巨型 pact：从关键集成点开始，借 pending pacts 随失败证据增量添加；500 条交互的 pact 不可维护。
26. 定期清理旧 pact：配置 Pact Broker 删除超过 90 天且未部署到任何环境的 pact 版本，否则拖慢验证并让 matrix 混乱。

适用边界 · 注意事项

• 不适用于给依赖打桩/打 mock 以隔离测试——那属于 service-virtualization；契约测试是证明两个真实服务对接口达成一致。
• 不适用于对自己拥有的 API 做通用 REST/GraphQL 端点断言（形状、状态码、鉴权、header）——那属于 api-testing。
• 非消费者-提供者接口场景（如复杂多步工作流的集成测试）仍需要集成测试，契约测试只替代“为了验接口而把消费者和提供者一起部署”的集成环境。