┌──────────────────────────────────────────────────────────────┐
│  消费者侧（写期望 → 生成契约）                                   │
│                                                              │
│  1. 消费者写测试：我调 GET /users/1，期望返回 { id, name }      │
│  2. Pact 在本地起一个 mock 服务，拦截这个请求                   │
│  3. 测试断言消费者的代码能正确处理这个响应                        │
│  4. 测试通过 → Pact 把"请求+期望响应"序列化成一份 JSON 契约文件    │
└──────────────────────────┬───────────────────────────────────┘
                           │  pact publish（推到 Broker）
                           ▼
┌──────────────────────────────────────────────────────────────┐
│  提供者侧（拉取契约 → 验证）                                     │
│                                                              │
│  1. 提供者从 Broker 拉取所有消费者定义的契约                     │
│  2. Pact 重放每个契约里的请求，打到真实的提供者服务上             │
│  3. 比对真实响应 vs 契约期望响应                                 │
│  4. 全部匹配 → 验证通过；任何一个字段不一致 → 挂掉                │
└──────────────────────────────────────────────────────────────┘

pnpm add -D @pact-foundation/pact @pact-foundation/pact-node

// src/tests/user-api.pact.test.ts
import path from 'node:path'
import { Pact, MatchersV3 } from '@pact-foundation/pact'
import { getUser } from '../api/user-api' // 你的真实 API 客户端

const { like, eachLike } = MatchersV3

// 创建一个 Pact mock provider
const provider = new Pact({
  consumer: 'web-frontend',
  provider: 'user-service',
  port: 4001,
  dir: path.resolve(__dirname, '../../pacts'),
  log: path.resolve(__dirname, '../logs/pact.log'),
})

describe('用户服务契约', () => {
  beforeAll(() => provider.setup())
  afterEach(() => provider.verify()) // 关键：验证真实请求和 mock 配置一致
  afterAll(() => provider.finalize()) // 关键：测试结束后生成契约文件

  describe('GET /users/:id', () => {
    it('根据 id 查询用户详情', async () => {
      // 第一步：声明期望——我调这个接口，期望它返回这样的结构
      await provider.addInteraction({
        uponReceiving: '一个查询用户详情的请求',
        withRequest: {
          method: 'GET',
          path: '/users/123',
          headers: { Accept: 'application/json' },
        },
        willRespondWith: {
          status: 200,
          headers: { 'Content-Type': 'application/json' },
          // like() 表示"结构要对，值不重要"——只校验类型
          body: {
            id: like(123),
            name: like('Alice'),
            email: like('[email protected]'),
          },
        },
      })

      // 第二步：用真实的 API 客户端去打 mock 服务
      // 注意 base url 要指向 Pact mock（localhost:4001）
      const user = await getUser(123, { baseUrl: 'http://localhost:4001' })

      // 第三步：断言你的业务代码正确处理了这个响应
      expect(user).toEqual({
        id: 123,
        name: 'Alice',
        email: '[email protected]',
      })
    })
  })
})

{
  "consumer": { "name": "web-frontend" },
  "provider": { "name": "user-service" },
  "interactions": [
    {
      "description": "一个查询用户详情的请求",
      "request": {
        "method": "GET",
        "path": "/users/123",
        "headers": { "Accept": "application/json" }
      },
      "response": {
        "status": 200,
        "headers": { "Content-Type": "application/json" },
        "body": { "id": 123, "name": "Alice", "email": "[email protected]" },
        "matchingRules": {
          "body": {
            "$.id": { "match": "type" },
            "$.name": { "match": "type" },
            "$.email": { "match": "type" }
          }
        }
      }
    }
  ]
}

// src/tests/pact-verification.test.ts
import path from 'node:path'
import { Verifier } from '@pact-foundation/pact'
import { app } from '../app' // 你的 Express/Fastify/Nest 应用实例

describe('Pact 契约验证', () => {
  const server = app.listen(8081)

  afterAll(() => server.close())

  it('满足 web-frontend 的所有契约', () => {
    const opts = {
      provider: 'user-service',
      providerBaseUrl: 'http://localhost:8081',
      // 从本地拉契约（演示用，生产环境从 Broker 拉）
      pactUrls: [path.resolve(__dirname, '../../pacts/web-frontend-user-service.json')],
      // Provider States：告诉提供者"现在要准备什么数据"
      stateHandlers: {
        '用户 123 存在': async () => {
          await db.user.upsert({ id: 123, name: 'Alice', email: '[email protected]' })
          return {} // 测试结束后的清理可以在这里做
        },
        '用户不存在': async () => {
          await db.user.deleteMany({ id: 999 })
          return {}
        },
      },
    }

    return new Verifier(opts).verifyProvider()
  })
})

await provider.addInteraction({
  uponReceiving: '一个查询用户详情的请求',
  // 声明：这个期望依赖提供者处于什么状态
  providerState: '用户 123 存在',
  withRequest: { /* ... */ },
  willRespondWith: { /* ... */ },
})

Verifying a pact between web-frontend and user-service
  一个查询用户详情的请求
    has status code 200 (OK)
    has a matching body (FAILED)

Failures:

1) Verifying a pact between web-frontend and user-service Given '用户 123 存在'
   expected response body to contain "email" but was missing
   at $.email

order-service (消费者) ──调用──> user-service (提供者)

// order-service 里
const provider = new Pact({
  consumer: 'order-service',
  provider: 'user-service',
  dir: path.resolve(__dirname, '../../pacts'),
})

it('下单时查询用户收货地址', async () => {
  await provider.addInteraction({
    uponReceiving: '下单时查询用户地址',
    providerState: '用户 123 有收货地址',
    withRequest: {
      method: 'GET',
      path: '/users/123',
      query: { fields: 'address' },
    },
    willRespondWith: {
      status: 200,
      body: {
        id: like(123),
        address: like({
          city: like('上海'),
          street: like('南京路 1 号'),
        }),
      },
    },
  })

  const order = await createOrder(123, { baseUrl: 'http://localhost:4001' })
  expect(order.shippingAddress.city).toBe('上海')
})

# 消费者侧：发布契约
pact-broker publish ./pacts \
  --consumer-app-version $(git rev-parse --short HEAD) \
  --broker-base-url https://broker.internal.company.com

# 提供者侧：从 Broker 拉取并验证
pact-broker verify \
  --provider user-service \
  --provider-base-url http://localhost:8081 \
  --broker-base-url https://broker.internal.company.com

pact-broker can-i-deploy \
  --pacticipant web-frontend \
  --version $(git rev-parse --short HEAD) \
  --to-environment production \
  --broker-base-url https://broker.internal.company.com