契约兼容性测试

技能文档

---
name: kentoshimizu-testing-contract
title: 契约兼容性测试
category: 开发工具
description: 面向服务接口变更的提供者-消费者契约兼容性测试，通过可执行的契约检查在发布前守护接口兼容性。当用户修改 API、事件 Schema 并需要验证向后兼容、在 CI 中阻断破坏性变更时触发。触发词：契约测试、兼容性检查、接口变更、破坏性变更。
---

# 契约兼容性测试

## 概述
通过在 CI 中强制执行提供者-消费者契约，防止集成回归问题的发生。

## 适用边界
- 当生产者与消费者之间的接口兼容性构成发布风险时使用。
- 典型请求：
  - 「验证某个 API 响应变更不会破坏现有消费者。」
  - 「在 CI 中强制执行事件 Schema 兼容性检查。」
  - 「在合并前加入提供者-消费者契约门禁。」
- 不适用于：
  - 仅涉及视觉/UI 行为的验证（应使用端到端 UI 测试工具）。
  - 仅涉及孤立单元逻辑的验证（应使用单元测试）。

## 输入
- 契约定义与兼容性策略
- 提供者/消费者的版本约束
- 发布与回滚要求

## 输出
- 带版本管理的契约测试套件与兼容性矩阵
- 契约策略与迁移路径的决策记录
- 提供者与消费者流水线的验证清单

## 技能工作流

### 步骤1：定义兼容性策略
明确采用哪种兼容性策略：向后兼容、向前兼容或严格兼容，并形成书面约定。

### 步骤2：识别契约面与关键消费者
梳理所有对外暴露的契约面（API 响应、事件 Schema 等），并识别依赖这些契约的关键消费者。

### 步骤3：比较执行方案并说明理由
对比可选的契约执行方案（如契约测试框架、CI 门禁脚本等），选择其一并记录选择理由。

### 步骤4：填写兼容性矩阵
使用 `assets/contract-compatibility-matrix-template.md` 模板记录提供者-消费者兼容性状态。

### 步骤5：执行验证
分别运行提供者与消费者两侧的契约验证，收集可复现的执行证据。

### 步骤6：发布结果与风险
公布失败项、迁移行动项与剩余兼容性风险，并明确风险负责人。

## 质量门禁
- 兼容性策略明确且有测试强制执行。
- 破坏性变更附带迁移方案与沟通计划。
- 契约证据可在 CI 中复现。
- 剩余兼容性风险有负责人跟踪。

## 失败处理
- 当必需的兼容性策略被违反时，停止流程。
- 当不存在可行的迁移路径时，升级处理。

## 配套资源
- `references/trigger-and-examples.md`：触发模式、反模式与交付物预期。
- `assets/contract-compatibility-matrix-template.md`：兼容性与迁移跟踪矩阵。

使用说明

# 契约兼容性测试

在服务接口变更时，通过提供者-消费者契约检查与兼容性矩阵，在发布前发现并阻断破坏性变更，防止集成回归。

## 使用

对 Agent 说：

```
验证这次 API 响应变更不会破坏现有消费者，并生成契约兼容性矩阵。
```

或在 CI 合并前请求：

```
为提供者与消费者的契约验证添加 CI 门禁检查。
```

## 工作原理

技能引导完成六步流程：定义兼容性策略（向后/向前/严格兼容）→ 识别契约面与关键消费者 → 比较并选定契约执行方案 → 使用 `assets/contract-compatibility-matrix-template.md` 填写兼容性矩阵 → 分别执行提供者与消费者验证 → 公布失败项、迁移行动与剩余风险。所有契约证据要求在 CI 中可复现。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。