API 契约定义、Schema 校验与变更测试

目标与适用范围

定义 API 契约，校验 Schema 和已捕获载荷，识别兼容性风险，并记录测试验收结果。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 准备 OpenAPI 或 JSON Schema；如果只有载荷，就准备一份有代表性的 JSON 样本。

• 先确定兼容性政策、必填字段、测试样例和验收门槛。

• 决策点: A：先用 OpenAPI，还是 B：先用 JSON 样本？. 已有契约并需要生成文档和类型时选 A。只有载荷时选 B，但要先审查推断出的 Schema，再把它作为正式契约。

按步骤完成工作流

1. 定义契约

从 OpenAPI 生成类型和文档，或从样本草拟 JSON Schema，并把来源版本与测试样例放在一起。 使用 openapi-to-typescript-generator, api-doc-generator, json-schema-generator.

2. 校验 Schema 并检查变更

校验正常和错误载荷，必要时转换为运行时校验代码，再对比版本并分类破坏性变更。 使用 json-schema-validator, json-schema-to-zod-schema-converter, openapi-diff-breach-detector, api-breaking-changes-detector-migration-planner.

3. 执行测试并记录验收

校验已捕获响应，对比已知载荷，生成边界或变异用例并记录发现；不将结果描述为部署或线上监控。 使用 api-response-contract-validator, api-response-diff-semantic-analyzer, api-contract-stress-tester, api-contract-mutation-tester, api-mock-server.

交付前验收结果

• 记录契约版本、请求和响应结构、必填字段，以及成功和错误样例。
• 有效样例通过 Schema 校验，无效样例明确失败，并记录变更报告和最终通过或不通过决定。

常见问题

• 这些工具会部署或监控真实 API 吗？ 不会。它们处理规范、样例、Mock 输入和已捕获响应；部署和生产监控不属于这个流程。
• 契约测试要准备什么？ 准备带版本的契约，并加入成功、校验错误、空值、边界和授权错误载荷。
• Schema 变更怎样验收？ 按兼容性政策对比差异，重跑相关检查，并用证据记录接受、修改、拒绝或版本化决定。