api-contract-testing

API 契约测试

目录

• 概述
• 适用场景
• 快速开始
• 参考指南
• 最佳实践

概述

契约测试用于验证 API 是否遵守消费者与提供者之间的契约。它能确保服务变更不会破坏依赖它的消费者，而无需进行完整的集成测试。契约测试会独立验证请求/响应格式、数据类型和 API 行为。

适用场景

• 测试微服务之间的通信
• 防止 API 发生破坏性变更
• 验证 API 版本管理
• 测试消费者与提供者之间的契约
• 确保向后兼容性
• 验证 OpenAPI/Swagger 规范
• 测试第三方 API 集成
• 在 CI 中捕获契约违规

快速开始

最简可运行示例：

// tests/pact/user-service.pact.test.ts
import { PactV3, MatchersV3 } from "@pact-foundation/pact";
import { UserService } from "../../src/services/UserService";

const { like, eachLike, iso8601DateTimeWithMillis } = MatchersV3;

const provider = new PactV3({
  consumer: "OrderService",
  provider: "UserService",
  port: 1234,
  dir: "./pacts",
});

describe("User Service Contract", () => {
  const userService = new UserService("http://localhost:1234");

  describe("GET /users/:id", () => {
    test("returns user when found", async () => {
      await provider
        .given("user with ID 123 exists")
        .uponReceiving("a request for user 123")
        .withRequest({
          method: "GET",
          path: "/users/123",
          headers: {
// ... (see reference guides for full implementation)

参考指南

references/ 目录中的详细实现：

指南	内容
Pact 的消费者驱动契约	Pact 的消费者驱动契约
OpenAPI Schema 验证	OpenAPI Schema 验证
JSON Schema 验证	JSON Schema 验证
Java 的 REST Assured	Java 的 REST Assured
使用 Postman 进行契约测试	使用 Postman 进行契约测试
Pact Broker 集成	Pact Broker 集成

最佳实践

✅ 应该做

• 从消费者的角度测试契约
• 使用匹配器实现灵活匹配
• 验证 Schema 结构，而非特定值
• 为契约设置版本
• 测试错误响应
• 使用 Pact broker 共享契约
• 在 CI 中运行契约测试
• 测试向后兼容性

❌ 不应该做

• 在契约测试中测试业务逻辑
• 在契约中硬编码特定值
• 跳过错误场景
• 在契约测试中测试 UI
• 忽略契约版本管理
• 未经契约验证就部署
• 测试实现细节
• 模拟契约测试