契约测试实战：Pact 与消费者驱动契约驱动的微服务安全演进

问题一：环境耦合
  要测 A 调 B，必须先部署 B + B 的依赖 C + C 的依赖 D……
  整个调用链都得起来，任何一个服务挂了，测试全红

问题二：反馈太慢
  E2E 集成环境一周只能跑几次，等到失败已经过去好几天

问题三：定位困难
  A 调 B 失败，是 A 的请求错了，还是 B 的实现错了？
  还是 C 拖垮了 B？还是网络问题？——黑盒里分不清

测试层级：
  单元测试        → 单个服务内部，快、隔离
  契约测试        → 服务之间接口约定，构建时验证
  集成/组件测试   → 单个服务 + 真实依赖（数据库/缓存）
  端到端测试      → 整条链路的少量冒烟

契约测试回答的问题：
  "我（Consumer）发的请求，Provider 能正确处理吗？"
  "Provider 的响应，我能正确解析吗？"
  "Provider 升级后，会破坏我的调用吗？"

传统思路（Provider 驱动）：
  Provider 定义 API 文档 → Consumer 去适配
  问题：Provider 不知道 Consumer 到底怎么用，文档与实现漂移

CDC（Consumer 驱动）：
  Consumer 定义它"期望"的接口 → Provider 必须满足
  为什么合理：真实的使用者才最清楚需求的形状

注意：CDC 不等于"Consumer 说了算"
  契约是双方的承诺：Consumer 承诺只这样调用，
  Provider 承诺这个调用会得到这样的响应

{
  "provider": "order-service",
  "consumer": "payment-service",
  "interactions": [
    {
      "description": "按 id 查询订单",
      "request": {
        "method": "GET",
        "path": "/orders/1001",
        "headers": { "Authorization": "Bearer ..." }
      },
      "response": {
        "status": 200,
        "body": {
          "id": 1001,
          "status": "PAID",
          "amount": 500.00
        },
        "matchingRules": {
          "body.$.id": { "matchers": [{ "match": "integer" }] },
          "body.$.amount": { "matchers": [{ "match": "decimal" }] }
        }
      }
    }
  ]
}

# consumer_test.py — Payment 服务调用 Order 服务
from pact import Consumer, Provider, format_term
import requests

pact = Consumer("payment-service").has_pact_with(Provider("order-service"))
pact = pact.with_host("localhost").with_port(8080)

@pact.consume("按 id 查询订单")
def test_get_order():
    pact.setup()  # 启动 Mock Server
    (pact
     .given("订单 1001 存在")
     .upon_receiving("查询订单")
     .with_request("GET", "/orders/1001", headers={"Authorization": "Bearer xxx"})
     .will_respond_with(200, body={
         "id": format_term(1001, "integer"),
         "status": "PAID",
         "amount": format_term(500.00, "decimal")
     }))
    with pact:
        resp = requests.get("http://localhost:8080/orders/1001",
                            headers={"Authorization": "Bearer xxx"})
        assert resp.json()["status"] == "PAID"
    pact.verify()  # 断言请求/响应符合预期
    pact.verify_mock_server()

test_get_order()
pact.publish_to_broker("http://pact-broker:9292", version="1.2.3")

# provider_verification.py — Order 服务验证阶段
pact-verifier \
  --provider-base-url=http://localhost:9000 \
  --provider order-service \
  --consumer payment-service \
  --pact-broker-url=http://pact-broker:9292 \
  --publish-verification-results \
  --provider-app-version=$CI_SHA

# 结合 pytest：Provider 端验证通过 = 满足所有已发布契约
def test_verify_pacts():
    verifier = Verifier(provider="order-service",
                        provider_base_url="http://localhost:9000")
    ok, _ = verifier.verify_pacts_from_broker(
        broker_url="http://pact-broker:9292",
        publish_results=True,
        provider_version="sha123")
    assert ok

Pact Broker 不是"存储契约的网盘"，而是：
  · 契约 + 验证结果的版本化仓库
  · 依赖图：谁依赖谁、哪个版本验证过哪个版本
  · 矩阵查询：can-i-deploy 的依据
  · 版本兼容关系：tag（test/prod）管理环境

# Provider 发布前：问 Broker "我能部署吗？"
can-i-deploy \
  --provider=order-service \
  --provider-version=$CI_SHA \
  --to-environment=production
# 输出：CONSUMER payment-service 最新版本已验证 ✓
#       → 通过（exit 0），否则失败（exit 1），阻断发布

can-i-deploy 的判定逻辑：
  Consumer 的"最新已部署到生产"版本（按 tag 判断）
  vs 我的这个 Provider 版本
  → 若该 Consumer 版本已验证通过 → 可以部署
  → 若存在未验证的 Consumer → 阻断并提示

这就是"Consumer 驱动"在发布环节的落地：
  谁在用我？用的哪个版本？我是否满足它？——全部可查询

# 每次 Provider 构建都回写验证结果
pact-verifier --publish-verification-results ...
# Broker 自动记录：
#   provider version v1.5  → 已验证 consumer version v2.3 ✓
#   provider version v1.4  → 已验证 consumer version v2.3 ✓
#   provider version v1.3  → 已验证 consumer version v2.2 ✗

// src/test/resources/contracts/order/getOrder.groovy
import org.springframework.cloud.contract.spec.Contract

Contract.make {
    request {
        method 'GET'
        url '/orders/1001'
        headers { header('Authorization': 'Bearer xxx') }
    }
    response {
        status 200
        body([
            id   : 1001,
            status: 'PAID',
            amount: 500.00
        ])
    }
}

Spring Cloud Contract 从契约文件自动生成：
  Consumer 端：自动生成 HTTP 请求测试桩（Stub Runner）
    → 启动 WireMock 桩，Consumer 测试直接调用
  Provider 端：自动生成验证测试（@SpringBootTest）
    → 直接调用真实 Controller 验证契约

优势：
  · 契约驱动整个双端，无需手写双份
  · JVM 生态集成好（Stub Runner 可分发桩到测试环境）

// Consumer 端用 Stub Runner 消费桩
@AutoConfigureStubRunner(
    ids = "com.example:order-service:+:stubs:9000",
    stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class PaymentTest {
  // payment-service 调 http://localhost:9000 即被桩拦截
}

新增/变更接口的完整流程：
  1. Consumer 修改调用 → 本地生成新契约
  2. Consumer 推送到 Broker（新版本）
  3. Provider CI 检测到新契约 → 验证
     · 通过 → 回写结果，Consumer 可以部署
     · 失败 → 通知 Consumer，双方协调（改契约 or 改 Provider）
  4. Provider 发布前 → can-i-deploy 门禁
  5. 双方部署到生产 → Broker 更新 deployed tag

关键：契约是"协商产物"，不是单方面决定
  Consumer 不能随意要求 Provider 改接口
  Provider 也不能无视 Consumer 的使用方式

# GitHub Actions 示例
jobs:
  consumer-publish:          # Consumer 服务
    runs-on: ubuntu-latest
    steps:
      - run: pytest contract/       # 生成并校验契约
      - run: pact-broker publish consumer-pacts/ \
            --consumer-app-version=${{ github.sha }}

  provider-verify:           # Provider 服务
    runs-on: ubuntu-latest
    steps:
      - run: pact-verifier --provider order-service ... --publish-results
      - run: can-i-deploy --provider order-service \
            --provider-version=${{ github.sha }} \
            --to-environment=production

· Broker 提供"待验证契约"清单 → Provider 侧一眼看到谁在等我
· Webhook 通知：新契约发布 → 自动触发 Provider 验证
· 契约变更走评审：像改 API 一样认真（SemVer 意识）
  · breaking change → 通知所有 Consumer 评估
  · 新增可选字段 → 通常兼容，直接推进

反模式一：把契约测试当集成测试用
  在共享环境里跑双端 → 又回到部署耦合，失去独立演进价值

反模式二：契约里断言精确值
  不用 matchingRules，Provider 改个字段值就红
  → 契约应断言"形状"，值匹配只留给真的重要的地方

反模式三：只写不验证
  契约发布了，Provider 从不验证 → 契约变成"一纸空文"

反模式四：用契约测试替代所有测试
  契约只覆盖"接口形状"，业务逻辑正确性仍需单元/集成测试

反模式五：忽略异步/事件契约
  只覆盖 HTTP，消息队列的 schema 兼容没人管

阶段一：选一条核心链路试点
  如 payment → order，1 个 Consumer 1 个 Provider

阶段二：建立 Broker + can-i-deploy 门禁
  先让 Provider 构建自动验证，再逐步接入发布门禁

阶段三：扩大到全部 HTTP 服务间调用
  新服务入职即配契约；旧服务改造时补契约

阶段四：覆盖异步边界
  Schema Registry + 契约测试双轨；构建服务目录（谁依赖谁）

# 契约治理指标
pact_contracts_total                       # 契约总数
pact_provider_verification_failed_total    # 验证失败数
pact_can_i_deploy_blocked_total            # 被门禁阻断的发布
pact_broker_untested_contracts{consumer}   # 未验证契约数
# 告警：任何生产环境 can-i-deploy 失败

□ 确认链路边界：只给跨服务的同步调用建契约
□ Consumer 用 matchingRules 断言形状而非精确值
□ Provider 实现 state setup 端点
□ 契约推送到 Broker（版本化 + tag）
□ Provider 每次构建自动验证 + 回写结果
□ 发布前跑 can-i-deploy 门禁
□ 契约变更走评审（区分 breaking / additive）
□ 异步边界用 Schema Registry 补齐
□ 监控验证失败与门禁阻断
□ 渐进式铺开，避免一刀切

契约测试的目标不是"证明系统能跑"，而是"证明系统可以安全地独立演进"。