📚 课程目录第4章组件间契约测试设计

4. 组件间契约测试设计：接口契约、数据契约、异常契约的定义、验证与版本管理

在微服务或模块化架构中，组件间的信任不能依赖“它应该懂我的数据结构”这种隐性共识，而必须由显式、可验证的契约来承载。契约测试的核心，是以消费者驱动的模式，为每个服务间交互定义接口、数据格式和异常行为的三维约束。本章围绕这三种契约的定义、验证自动化以及版本兼容性管理展开，确保在边界处提前暴露而非运行时才爆发问题。

4.1 三种契约的边界与职责

接口契约、数据契约与异常契约分别对应通信方式、消息荷载和故障路径三个维度。它们共同构成一个组件对外承诺的完整信任基线。

契约维度	边界定义	验证重点	版本管理粒度
接口契约	端点 URL、方法、请求/响应头、超时策略	路径可达性、HTTP 状态码范围、首部字段存在性	大版本号（破坏性变更）
数据契约	请求体/响应体的 JSON Schema 或 Protobuf 定义	字段类型、必选/可选、嵌套结构、枚举值范围	小版本号（向后兼容新增）
异常契约	错误响应结构、错误码枚举、重试语义、降级标志	非 2xx 响应体完整性、错误码覆盖率、幂等标识	补丁版本号（修复说明）

实践要点： 优先为每个提供方服务生成 OpenAPI 3.x 规范 作为接口契约的持久化载体，再从中提取 JSON Schema 片段作为数据契约的验证依据。异常契约建议单独维护一份枚举清单，避免与正常逻辑混杂。

4.2 契约定义与验证策略

4.2.1 接口契约：静态签名与动态协商

接口契约在组件边界处声明“我能接受什么形式的请求、我会返回何种结构的响应”。静态部分通过 OpenAPI / RAML 描述，动态部分通过消费者驱动的 Pact 或 Spring Cloud Contract 框架生成测试桩。

典型定义片段：

paths:
  /api/v2/orders:
    get:
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, shipped, cancelled]
      responses:
        '200':
          description: 订单列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderSummary'

验证路径： 消费者提供预期请求-响应配对 ➜ 提供方运行契约验证任务 ➜ 比对实际响应与预期 Schema、状态码、头字段 ➜ 输出差异报告。

4.2.2 数据契约：Schema 校验与字段级兼容

数据契约的验证不仅是字段存在性检查，还需涵盖新增字段是否为 opt-in、字段类型是否收紧、枚举值是否移除。推荐使用 JSON Schema 的 additionalProperties 与 oneOf 约束来定义宽松与严格模式。

兼容性规则	消费者期望	提供方变更	结果
新增可选字段	忽略未知字段	增加 optional 属性	✅ 兼容
缩小枚举值	使用已移除的值	移除某枚举项	❌ 破坏
字段类型放宽	传递窄类型	int → long	✅ 兼容

4.2.3 异常契约：错误模式的显式承诺

异常契约经常被忽略，但它是信任链路中最关键的降级参考。每个非正常路径的响应必须包含：code（业务错误码）、message（人类可读描述）、retryable（是否可重试）、traceId（链路追踪 ID）。

常见陷阱： 一些团队只在正常路径上做契约测试，导致出现 429 时响应体结构未知、错误码格式不一致、重试指示缺失。这会让消费方在边界异常处理中不得不写“猜锁代码”，从而引入隐蔽缺陷。

4.3 版本管理与兼容性矩阵

组件演进必然带来契约变更。采用 SemVer + 自动兼容性检查 的方式确保消费者不被意外破坏。每个契约版本发布前，由 CI 流水线执行以下决策流程：

对比基线：提取当前主分支上的契约文件与 MR 分支的 diff。
分类变更：新增字段 → minor；删除字段/收紧类型 → major；修正文档 → patch。
计算兼容性：对每位已知消费者执行 mock 验证，若任一消费者验证失败则标记为 major。
标记/阻断：major 变更必须显示标注“breaking change”并通知所有消费团队窗口期。

# 兼容性检查输出示例
[Contract Compatibility Report]
Provider: order-service.v2
Consumer: billing-service
  - Added field 'discount' (optional) — OK (minor)
  - Changed 'shippingDate' from string to date — OK (widening)
  - Removed enum value 'hold' — FAIL (breaking)
Result: MAJOR — requires consumer coordination

4.4 契约测试落地步骤与验收标准

将契约测试嵌入交付流水线的具体步骤：

步骤 1：在提供方仓库中维护契约描述文件（OpenAPI + 异常枚举 YAML）。
步骤 2：消费者以依赖方式引入契约 jar/pom，并编写 Pact/Spring Cloud Contract 测试。测试只验证消费者自己使用的路径。
步骤 3：提供方 CI 中运行contract-verifier任务，自动拉取所有注册消费者的契约期望并逐一验证。
步骤 4：检查通过后，才允许合并到主分支并生成新版本号。
步骤 5：将契约变更日志 push 到统一的契约注册中心（如 Apicurio / Schema Registry），为其他团队提供发现订阅。

验收标准： 每个服务在部署前必须通过 所有已注册消费者的契约验证，不存在未覆盖的异常路径，且版本号语义与兼容性检查结果一致。

4.5 契约设计与验证体系关系图

以下 SVG 展示了从消费者定义期望、注册中心存储、提供方验证到 CI 阻断的完整流程：