还在用单测？尝试契约测试保障 PHP 接口稳定性

在微服务架构大行其道的今天，PHP 接口不仅要面对浏览器请求，还要被各种服务、App、内部系统频繁调用。你是不是也有过这样的经历：单测全绿，自信满满地上线，结果接口一改，对方调用方立刻报错，排查半天才发现是字段类型变了、数组结构调整了。单测确实测了我们的代码逻辑，但它测不到接口“契约”——两个服务之间那纸无形的约定。

这让我想推荐另一种实践：契约测试（Contract Testing）。它解决的不是“我的函数对不对”，而是“我的接口是否还符合调用方的期待”。相比单测，它在保障接口稳定性这件事上，往往更对症。

单测的盲区：它不关心“对方怎么看”

单测是优秀的，它验证单元行为，保证我们自己的代码正确。但单测的视角是“生产者视角”——我们测试自己返回的数据、自己的逻辑分支。问题在于，当接口需要被外部系统消费时，单测根本无法检查“调用方是否也这么认为”。

举个典型 PHP 场景：你的 `UserService` 返回用户信息，单测断言了 `name` 字段存在，类型是 string。对方服务却约定 `name` 为可空，或者期待的是 `full_name`。即使你的单测全过，接口一旦变更，调用方依然会炸。单测没有地方去表达“两个服务之间的约定”，它自然也无法守护这种约定。

契约测试：把接口约定变成可执行的测试

契约测试的核心思路很简单：定义一份“契约”——消费者和提供者都认可的请求/响应格式，然后两方各自基于这份契约进行验证。最常见的是 Pact 风格的“消费者驱动的契约测试”。

具体做法是：
- 消费者（调用方）基于自己的期望，生成一份契约文件，写明“我会发送什么，我期待返回什么”。
- 提供者（API 服务方）运行契约测试，用这份契约来 mock 请求，验证自己的响应是否满足消费者的每个字段、类型、状态码。
- 两边分别跑通，再通过契约文件同步或协商，确保任何变更都能被及时发现。

这份契约不是空文档，它是可执行的代码。一旦提供方改了响应结构，消费者侧测试不通过，CI 就会亮红灯，问题在开发阶段就能暴露，而不是等到线上调用才发现。

PHP 中的实践：上手并不难

在 PHP 生态里，最常用的是 Pact-PHP，它对 PHPUnit 支持良好。以 Laravel 或任意框架为例，你可以在消费者项目中写一些特殊测试：

// 消费者测试：期望 GET /users/1 返回 name 和 email
$pactBuilder->service('UserService')
    ->given('user exists')
    ->uponReceiving('a request for user')
    ->with([
        'method' => 'GET',
        'path' => '/users/1',
    ])
    ->willRespondWith([
        'status' => 200,
        'body' => [
            'name' => 'Alice',
            'email' => 'alice@example.com'
        ],
    ]);

这段测试会生成一份契约 JSON，然后你把这个契约交给提供方。在提供方项目中，通过 Pact 验证器 `run` 跑一遍测试，自动模拟响应并对比。如果返回里少了个字段、类型变了、多出个非空判断，测试直接就红了。

很多人担心这个成本。实际上，PHPUnit 原本就集成在其中，你只需要为关键接口添加契约测试，不需要覆盖所有业务逻辑。单测依旧有用，两者是互补关系——单测守护内部逻辑，契约测试守护外部协议。对于核心服务之间的 API 稳定性，契约测试的投入产出比非常高。

什么时候最值得引入？

如果你的 PHP 服务被多个客户端调用，特别是团队之间通过 API 协作，契约测试几乎是为这种场景量身定做的。它能倒逼接口设计文档落地，让双方便于协同，减少“接口悄悄变了”带来的扯皮。

反之，如果你的服务只被自己的前端页面调用，且没有长期维护多个消费端，可能暂时用不上。但只要你经历过一次“对方说好了不改，结果偷偷改了”的悲剧，就会明白把契约控制在测试里有多重要。

总结

单测必须写，但它不该是保障接口稳定性的唯一防线。契约测试用“约定”补上了单测在跨服务场景下的盲区，让双方的预期被固化、验证、追踪。当你的 PHP 接口不再只是你一个人的代码，而是团队间的服务边界，试试用契约测试去守护边界。你会发现自己少了很多“半夜被叫起来查接口”的机会。