OpenAPI 版本治理与兼容（Deprecation、合同测试 与验证）

概述API版本治理通过路径或头部表达版本, 使用弃用标记提示迁移窗口。合同测试在CI中校验请求与响应的Schema兼容, 防止破坏性变更。关键实践与参数版本策略: 路径 `/v1` `/v2` 或 `Accept-Version`弃用声明: `deprecated: true` 并在文档中注明移除时间兼容规则: 新增字段为可选, 保持类型与语义稳定合同测试: 使用Schema校验请求/响应示例/配置/实现openapi: 3.0.3 info: { title: Shop API, version: "1.1.0" } paths: /v1/items: get: responses: "200": content: application/json: schema: type: object properties: id: { type: string } name: { type: string } desc: { type: string, deprecated: true } import Ajv from 'ajv' const ajv = new Ajv({ allErrors: true }) const schema = { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' } }, required: ['id', 'name'] } const validate = ajv.compile(schema) function test(resp) { return validate(resp) } 验证兼容性: 旧客户端在新增字段为可选时仍正常工作弃用提示: 文档与响应中明确标记弃用字段合同测试: CI对主要接口进行Schema校验通过发布安全: 不兼容变更被阻止或要求新版本路径注意事项版本窗口需明确与可见避免静默移除字段, 提前通知并提供迁移指南合同测试覆盖主路径与错误响应与网关的路由与监控协同