PHP中用Pact做CDC的核心是契约文件生成、验证及触发三步；需用pact-php显式调用PactBuilder生成JSON，确保路径/方法/头严格匹配，通过Pact Broker集成CI并精确实现provider state。
PHP 项目里用 Pact 做消费者驱动契约（CDC），核心不是“能不能跑”，而是“契约文件怎么生成、怎么验证、谁来触发验证”——这三步错一步，契约就变成摆设。
如何让 PHP 消费者生成有效的 pact 文件
PHP 本身不原生支持 Pact，得靠 pact-php（官方维护的绑定）或社区版 pact-net 的 PHP 封装。目前最稳定的是基于 pact-php + pact-cli 的组合。
- 必须在测试中显式调用
PactBuilder，不能只写 PHPUnit 断言——否则不会输出.json契约文件 - 每个测试方法对应一个独立的
interaction，given描述提供方状态（如 “用户已存在”），uponReceiving和willRespondWith定义请求与响应细节 - 生成的
pact文件默认存到tests/pacts/，路径需和后续验证阶段的--pact-dir一致，否则提供方找不到契约 - 别在
setUp()里复用同一个PactBuilder实例——会导致多个 interaction 写进同一个 JSON 对象，验证时解析失败
为什么 pact verify 总报 No interactions found
这是最常卡住的环节：消费者生成了文件，但提供方验证时读不到 interaction。根本原因通常是契约内容与提供方实际接口行为不匹配，而非文件没找到。
- 检查
pact文件里的request.path是否带前缀（比如消费者写了/api/v1/users，但提供方路由是/v1/users）——Pact 不做路径重写，必须完全一致 -
request.method大小写敏感，GET和get是两个东西；request.headers中的Content-Type如果声明为application/json，但提供方返回text/plain，验证直接失败 - 提供方启动的 mock server 端口要和契约里
providerStatesSetupUrl指向的地址一致；如果提供方用 Laravel，需确保artisan serve或 Swoole 进程在验证期间持续运行 - 执行
pact verify时加--log-level=DEBUG，看日志里是否加载了目标.json文件，以及是否成功发起对 provider state 接口的POST调用
如何在 CI 中安全集成 Pact 验证
把 Pact 验证塞进 CI 不是加一行 vendor/bin/pact-verify 就完事。关键在于隔离性与可重现性。
立即学习“PHP免费学习笔记（深入）”；
- 消费者侧上传
pact到 Pact Broker 用pact-broker publish，而不是直接 scp 到提供方机器——Broker 才能做版本关联和触发式验证 - 提供方 CI 中不要用本地
pact文件路径验证，改用--broker-base-url+--broker-username拉取最新契约，避免本地缓存污染 - CI 环境里提供方数据库必须清空或用 transaction rollback 模式初始化 provider state，否则上次测试残留数据会让本次验证结果不可靠
- 别让 Pact 验证和单元测试混在同一 job：Pact 验证耗时长、依赖外部服务，失败应单独告警，不影响主干构建通过率
契约不是文档，是可执行的接口协议。最容易被忽略的是 provider state 的实现粒度——写成 “用户存在” 这种模糊描述，不如明确成 “数据库 users 表中有 id=123 的记录且 status=active”。Pact 不会帮你查数据库，它只信你提供的 setup 接口返回的结果。
