契约开发学习成果分享

什么是契约测试：先确认“说话格式”

契约测试不判断系统功能是否完整，它只验证 Consumer 和 Provider 是否仍然“听得懂彼此”。

单元 / E2E / 契约：职责边界表

契约测试关注“协议稳定”，不替代单测，也不替代端到端。

CDCT 核心理念：前端是“甲方”

CDCT（Consumer-Driven Contract Testing）强调：消费者只声明“真正需要的字段”，推动提供者实现最小可用接口。

避坑指南：三个思维转变

这三条是契约实践成败分水岭，建议在团队代码评审中设为硬性检查项。

• 反模式一：把契约测试当集成测试。契约只管结构和类型，不测复杂业务规则。
• 反模式二：Consumer 和 Provider 各玩各的。契约必须围绕消费者真实使用路径协作演进。
• 反模式三：把业务边界值塞进契约。例如“负数金额触发哪条业务错误”应放到 Provider 单测。
• 关键动作：全部使用 Matchers 关注 Shape，不要硬编码具体内容值。

阶段小测：字段删改是否会拦截？

场景：前端已不再使用 user_avatar，BFF 删除该字段后会不会被契约阻断部署？

点击问题查看答案（可用于现场互动）

阶段二：BFF -> 后端 REST Pact（可直接讲解）

骨架流程：Mock Provider -> 定义 Interaction -> 执行真实客户端请求 -> 生成 Pact JSON。

import { PactV3, MatchersV3 } from '@pact-foundation/pact';

const provider = new PactV3({ consumer: 'BFFService', provider: 'BackendUserService' });

provider
  .uponReceiving('a request to get user profile')
  .withRequest({ method: 'GET', path: '/users/10' })
  .willRespondWith({
    status: 200,
    body: {
      id: MatchersV3.integer(10),
      username: MatchersV3.string('SampleUser')
    }
  });

await provider.executeTest(async (mockserver) => {
  // 调用真实 API Client
});

• 关键词：PactV3、MatchersV3、executeTest。
• 实践结论：不要测业务边界值，只测接口交互结构。

阶段二案例：同事想测 -99999 ID，该不该？

这是最常见误区：把契约测试当“业务规则验证场”。

阶段三：前端 -> BFF GraphQL Pact

GraphQL 痛点：统一入口 /graphql，请求体是 Query 字符串，响应字段强依赖前端选择集。

import { PactV3, GraphQLInteraction, MatchersV3 } from '@pact-foundation/pact';

const graphqlCase = new GraphQLInteraction()
  .withQuery(queryUser)
  .withVariables({ id: '123' })
  .withOperation('GetUserProfile')
  .willRespondWith({
    status: 200,
    body: {
      data: {
        user: {
          id: MatchersV3.string('123')
        }
      }
    }
  });

• 关键字必须理解：GraphQLInteraction、withQuery、withVariables。
• BFF 双身份：向上做 Provider、向下做 Consumer，各自契约独立演进。
• 治理建议：每个前端页面只声明自身真正消费字段，拒绝“预留一堆未来字段”。

阶段三思考：BFF 做 Provider 验证时怎么隔离下游？

当我们验证“前端 <-> BFF”契约时，BFF 对后端请求必须 mock，避免跨层耦合污染测试信号。

• 上游 Consumer 契约失败，说明 BFF 对前端承诺未满足。
• 下游 Consumer 契约失败，说明 BFF 调用后端的约定失真。
• 术语提醒：BFF 对前端是 Provider，但对下游服务是上游 Consumer。

阶段四：Broker + CI/CD 交通枢纽

Broker 负责版本矩阵与可视化依赖，流水线负责“未兼容就不准上线”。

# Consumer 发布契约
pact-broker publish ./pacts --consumer-app-version=$GIT_SHA --branch=main

# Provider 拉取并验证
Verifier --provider-base-url=http://localhost:8080 --broker-url=$PACT_BROKER

# 发布闸门
pact-broker can-i-deploy --pacticipant web-bff --version $GIT_SHA --to-environment production

契约毕业场景题：大促前删字段

场景：后端删掉 last_login_ip，前端契约仍预期该字段。

点击问题查看答案

补充篇：Provider 验证原理 + Code Review 要点

让团队不仅会“写 Pact”，还能在审查中识别坏味道。

Q&A 进阶：前端悄悄加字段会怎样？

这个问题最能体现契约“保护生产”的价值：不兼容需求不会被悄悄上线。

收尾：把契约精神固化为团队机制

建议将本页作为 onboarding 标准材料，并与模板仓库、CI 脚本、代码评审清单联动。