📚 课程目录第2章契约测试基础

2、契约测试基础：消费者驱动契约、提供者验证、Pact框架核心概念

契约测试的核心思想是“先定契约，再写代码”。在微服务架构中，服务之间的交互依赖接口定义与数据格式。契约测试通过一份显式的“契约”文件，将消费者（Consumer）对提供者（Provider）的期望固化下来，再让提供者侧验证自己是否满足这些期望。本章将系统讲解消费者驱动契约、提供者验证以及Pact框架的核心概念。

2.1 消费者驱动契约（Consumer-Driven Contracts, CDC）

传统集成测试往往由提供者定义接口，消费者被动适配。消费者驱动契约则反转了这一关系：由消费者定义它对提供者的期望，提供者只需保证自己满足所有消费者的契约即可。

对比维度	传统提供者驱动	消费者驱动契约（CDC）
契约定义方	提供者	消费者
验证方向	消费者测试提供者	提供者验证消费者期望
变更影响	消费者被动适配	提供者主动感知消费者变更
测试粒度	端到端集成	接口契约级
反馈速度	慢（依赖全链路部署）	快（可独立运行）

  关键原则：消费者驱动契约不是“消费者说了算”，而是“消费者说清楚自己要什么，提供者确认自己能给什么”。双方通过契约文件达成一致，避免因接口理解偏差导致的集成失败。

2.2 提供者验证（Provider Verification）

提供者验证是契约测试的另一半。当消费者生成契约文件后，提供者需要运行验证套件，检查自己的真实API响应是否与契约中的每个交互期望匹配。验证通过意味着提供者可以安全发布；验证失败则说明提供者做出了破坏性变更，需要回退或与消费者协商。

提供者验证的核心步骤：

获取契约文件：从消费者端（或契约仓库）拉取最新的契约。
解析交互列表：提取每个请求的路径、方法、请求体、头信息以及期望的响应状态码、响应体结构。
执行真实请求：向提供者服务发送请求，获取实际响应。
比对结果：将实际响应与契约中的期望进行匹配（状态码、字段类型、值范围等）。
生成验证报告：输出通过/失败详情，失败时标明具体字段差异。

实践建议：提供者验证应集成到CI/CD流水线中，每次代码提交后自动运行。只有验证通过，才能合并到主分支或部署到测试环境。

2.3 Pact框架核心概念

Pact是目前最流行的契约测试框架，支持多种语言（Java、JavaScript、Python、Go等）。它围绕“契约文件”和“交互”两个核心抽象展开。

2.3.1 核心术语

术语	说明
交互（Interaction）	一次完整的请求-响应描述，包含请求方法、路径、头、体以及期望的响应状态码、响应体。
契约文件（Pact File）	JSON格式的文本文件，包含消费者名称、提供者名称以及一组交互列表。是消费者与提供者之间的“合同”。
消费者测试（Consumer Test）	在消费者侧编写，使用Pact模拟提供者，生成契约文件。
提供者验证（Provider Verification）	在提供者侧运行，加载契约文件，验证真实API是否满足契约。
Pact Broker	契约文件的中央仓库，支持版本管理、依赖关系可视化和Webhook触发。

2.3.2 Pact工作流程

下图展示了Pact框架在消费者与提供者之间的完整交互流程：

2.3.3 消费者测试示例（JavaScript）

以下是一个使用Pact JS编写的消费者测试片段，模拟报表导出接口的调用：

const { PactV3, MatchersV3 } = require('@pact-foundation/pact');
const { like, eachLike } = MatchersV3;

const provider = new PactV3({
  consumer: 'ReportExportFrontend',
  provider: 'ReportExportService',
});

describe('Report Export API', () => {
  it('should return export task status', async () => {
    // 定义交互期望
    provider
      .given('存在一个导出任务')
      .uponReceiving('查询导出任务状态')
      .withRequest({
        method: 'GET',
        path: '/api/export/task/123',
        headers: { 'Accept': 'application/json' },
      })
      .willRespondWith({
        status: 200,
        headers: { 'Content-Type': 'application/json' },
        body: like({
          taskId: '123',
          status: 'completed',
          progress: 100,
          downloadUrl: 'https://cdn.example.com/report.xlsx',
        }),
      });

    // 执行测试（模拟消费者调用）
    await provider.executeTest(async (mockServer) => {
      const response = await fetch(`${mockServer.url}/api/export/task/123`);
      const data = await response.json();
      expect(data.status).toBe('completed');
    });
  });
});

2.3.4 提供者验证示例（Java）

提供者侧使用Pact JVM验证契约：

@Provider("ReportExportService")
@PactBroker(url = "https://pact-broker.example.com")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class ReportExportProviderPactTest {

    @LocalServerPort
    int port;

    @TestTemplate
    @ExtendWith(PactVerificationInvocationContextProvider.class)
    void pactVerificationTestTemplate(PactVerificationContext context) {
        context.verifyInteraction();
    }

    @BeforeEach
    void before(PactVerificationContext context) {
        context.setTarget(new HttpTestTarget("localhost", port));
    }
}

2.4 契约测试与报表导出回放场景的结合

在报表导出回放场景中，消费者（前端或调度服务）需要调用提供者（报表服务）的导出接口。契约测试可以确保：

接口稳定性：提供者修改导出参数或响应结构时，契约验证会立即发现破坏性变更。
回放兼容性：历史回放请求的格式与当前契约一致，避免回放失败。
独立测试：前端可以在不部署报表服务的情况下，基于契约模拟后端进行开发。

注意：契约测试不能替代端到端测试。它只验证接口契约的一致性，不验证业务逻辑的正确性。在报表导出场景中，仍需配合单元测试和集成测试覆盖文件生成、权限校验等核心逻辑。

2.5 本章小结

消费者驱动契约让消费者主动定义期望，提供者被动验证，从而在微服务间建立清晰的接口边界。Pact框架通过契约文件、消费者测试、提供者验证和Pact Broker四个核心组件，将这一理念落地为可工程化的实践。掌握这些基础概念，是后续实现报表导出回放场景契约测试的基石。