contract-tester

用途

contract-tester 用于对照 CTR（Contract）文档校验 API 实现，检测破坏性变更，并确保提供方（Provider）与消费方（Consumer）之间的兼容性，目标是在部署前阻止 API 合同违规。

主要能力

CTR YAML 模式校验：校验 YAML 结构是否符合模式、必填字段是否完整、数据类型是否正确、枚举值与格式规范（email、URL、UUID）是否合法。
OpenAPI/AsyncAPI 合规：将 CTR 转换为 OpenAPI 3.0/3.1 规范并校验，支持 AsyncAPI 事件驱动 API 校验、JSON Schema 校验、GraphQL schema 校验。
合同版本管理：语义化版本校验（MAJOR.MINOR.PATCH）、版本兼容性检查、弃用警告、迁移路径校验。
破坏性变更检测：检测被移除的端点/操作、变更的请求/响应模式、被移除的必填字段、字段类型变更、更严格的校验规则、认证要求变更。
Mock 服务器生成：从 CTR 生成 Mock API 服务器（真实感数据、可配置响应延迟、错误场景模拟、有状态 API 状态管理）。
消费者驱动合同测试：Pact 合同测试、提供方验证、消费方合同生成、双向合同测试、合同演进跟踪。
合同兼容性矩阵：提供方版本兼容性、消费方版本支持、弃用时间线跟踪、迁移要求。
API 文档生成：从 CTR 生成 API 文档、交互式 API 浏览器、多语言代码示例、认证指南。

工作流与使用方式

合同测试工作流包括：解析 YAML → 校验是否符合模式 → 版本检查 → 破坏性变更检测（若有上一版本则比较）→ 生成 Mock 服务器 → 运行合同测试 → 生成文档 → 验证完成。

常用命令：

校验 CTR 文档：

contract-tester validate --file ctrs/CTR-USER-V1.yaml

检测破坏性变更：

contract-tester diff \
  --previous ctrs/CTR-USER-V1.yaml \
  --current ctrs/CTR-USER-V2.yaml

生成 Mock 服务器：

contract-tester mock \
  --file ctrs/CTR-USER-V1.yaml \
  --port 8080 \
  --response-delay 100ms

运行消费者合同测试：

contract-tester test-consumer \
  --contract ctrs/CTR-USER-V1.yaml \
  --consumer user-frontend \
  --provider user-service \
  --output reports/contract-tests/

验证提供方实现：

contract-tester test-provider \
  --contract ctrs/CTR-USER-V1.yaml \
  --provider-url http://localhost:8000 \
  --output reports/provider-verification/

CTR 文档以 YAML 定义合同，包含 contract_id、version、service_name、protocol、base_path、metadata、authentication、endpoints、components（schemas）等字段。

破坏性变更规则

MAJOR（X.0.0）：移除端点、移除必填字段、变更字段类型、更严格校验、变更认证要求等。
MINOR（x.Y.0）：新增端点、新增可选字段、放松校验等非破坏性变更。
PATCH（x.y.Z）：文档更新、描述错误修复、拼写更正、示例更新等。

适用场景

在 CI/CD 流水线中进行合同校验，阻止带破坏性变更的部署。
为 API 生成 Mock 服务器以便联调测试。
通过 Pact 实现消费者驱动合同测试与提供方验证。
维护合同兼容性矩阵与迁移路径。
从 CTR 生成 API 文档与代码示例。

依赖与集成

所需工具能力：Read（读取 CTR YAML）、Write（生成测试文件与文档）、Bash（执行校验与测试工具）、Grep（搜索合同模式）。

所需库：pyyaml、jsonschema、openapi-spec-validator、pact-python、faker。

集成点：与 doc-flow（生成时校验 CTR、保证可追溯性、合同变更时更新文档）、test-automation（自动生成合同测试、集成测试套件、跟踪覆盖率）、code-review（校验实现与合同一致性、检测违规、建议合规修复）、devops-flow（CI/CD 合同校验、阻止破坏性变更部署、生成 API 网关配置）集成。

最佳实践与成功标准

最佳实践包括：严格遵循语义化版本、优先采用增量式变更、移除功能前给出弃用通知、在合同变更中纳入消费方反馈、为破坏性变更提供清晰迁移指南、发布前测试所有合同变更、至少支持 N-1 版本、维护完善的合同变更日志。

成功标准包括：100% 合同校验覆盖、零未检测到的破坏性变更、合同校验时间小于 5 分钟、同一 MAJOR 版本内 100% 消费方-提供方兼容、所有破坏性变更均附带迁移路径、所有合同均可提供 Mock 服务器。

限制

具体收费、价格与平台支持情况暂未提供。