name: qa-api-testing-contracts description: API 测试和契约验证，涵盖 REST (OpenAPI 3.1)、GraphQL (SDL) 和 gRPC (proto)。适用于模式 linting/验证、破坏性变更检测 (openapi diff、GraphQL schema diff、buf breaking)、消费者/提供者契约测试 (Pact 或基于模式)、负面/安全测试，以及 CI 质量门。
QA API 测试与契约
使用此技能将 API 模式转换为可强制执行的检查（lint、diff、契约和负面/安全案例），并将其集成到 CI 中，以防止破坏性变更无声发布。
请求输入
- API 类型和规范模式文件（OpenAPI 3.1、SDL、proto）及其在仓库中的位置。
- 环境、身份验证方法和如何提供稳定的测试身份/密钥。
- 关键端点/操作和业务流（按风险和收入影响排序）。
- 数据约束（幂等键、分页、排序）、速率限制和错误格式（对于 REST，建议使用 RFC 7807
application/problem+json）。 - 版本化和弃用策略、消费者清单和发布节奏。
- 当前测试工具/CI 以及“阻止”对您的组织意味着什么。
输出（生成内容）
- 集成到 PR 的最小 CI 门集合（lint + 破坏性 diff + 契约套件）。
- 从模式派生的覆盖图（优先处理关键操作）。
- 对齐 OWASP API 风险的负面/安全基线。
快速开始
- 对模式进行 lint（语法 + 最佳实践规则），在编写测试之前修复问题。
- 在每个 PR 上添加针对基础分支的破坏性变更检查。
- 选择契约策略（CDC、基于模式或两者结合）并在 CI 中针对临时环境运行。
- 添加身份验证、验证和错误处理的负面/安全案例。
- 明确门控（什么阻止合并/发布）并发布结果。
工作流
1) 建立契约工件（事实来源）
- REST：单个 OpenAPI 3.1 文件或编译工件；避免片段之间的漂移。
- GraphQL：检入的 SDL（如果相关，包括联邦/组合配置）。
- gRPC：检入的
.proto+buf.yaml（或等效物），具有稳定的模块布局。
2) 验证模式（快速、确定）
- 运行规范 linting（Spectral / GraphQL Inspector / buf lint）。
- 强制实施一个小而明确的规则集（命名、描述、身份验证注释、一致的错误模型）。
3) 检测破坏性变更（PR 门）
- REST：使用破坏性变更策略（移除/重命名/类型变更/必需性）进行 OpenAPI diff。
- GraphQL：进行模式 diff 并检查破坏性（字段移除、类型变更、非空强化）。
- gRPC：
buf breaking（不要重用/重编号字段；避免不兼容地更改请求/响应形状）。
4) 执行契约测试（CI 门）
选择一种或结合：
- CDC（Pact）：当存在许多独立消费者且行为超出模式时最佳。
- 基于模式（Specmatic）：当模式是契约且您希望跨操作快速覆盖时最佳。
- 基于属性（Schemathesis）：当您希望系统化边缘案例和服务器强化时最佳。
5) 添加负面 + 安全案例（最小集）
- 身份验证/授权：缺少/过期的令牌（401）、权限不足/角色（403）、租户隔离。
- 验证：缺少必需字段、无效类型、边界值、空字符串、大负载。
- 错误处理：稳定的错误形状、安全消息、正确的状态代码、相关 ID。
- 滥用和限制：速率限制（429）、分页限制、幂等重放、重试安全语义。
- 对于 GraphQL，如果存在操作注册表（如 GraphOS/Hive 等），也验证操作检查（已知/持久查询）。
6) 定义 CI 质量门（合并 + 发布）
- 预合并：模式 lint + 破坏性变更 diff（阻止）。
- 预发布：契约套件（阻止），加上关键流的冒烟/功能测试。
- 报告：发布工件（diff 报告、契约验证、失败案例）并在 PR 中链接。
质量检查
- 快速失败：模式违规和破坏性变更阻止合并。
- 确定性：隔离数据，在需要时冻结时间，避免共享可变夹具。
- 无 flakes 卫生：将网络不稳定与契约失败分开；仅对已知瞬态类重试。
- 对齐：契约反映版本化/弃用策略和消费者清单。
- 范围控制：除非明确请求，否则将负载/弹性测试分开。
使用捆绑模板
- 覆盖计划：
assets/api-test-plan.md - 发布审查：
assets/contract-change-checklist.md - 工具地图：
assets/schema-validation-matrix.md
AI 辅助（谨慎使用）
- 使用 AI 起草测试、建议缺失边缘案例和收紧匹配器。
- 在根据模式和真实行为验证之前，将 AI 输出视为不受信任。
- 避免上传敏感负载；清理示例和日志。
- 有关工具比较和工作流，请阅读
references/ai-contract-testing.md。
需要时阅读
- 变更安全性和 CDC 模式：
references/contract-testing-patterns.md - AI 辅助工具和决策矩阵：
references/ai-contract-testing.md - 精选权威链接：
data/sources.json
相关技能
- 使用 dev-api-design 进行 API 设计决策。
- 使用 qa-testing-strategy 进行整体测试策略。
- 使用 qa-resilience 进行混乱和可靠性测试。
- 使用 software-security-appsec 进行 API 安全审查。