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

## 概述 API版本治理通过路径或头部表达版本, 使用弃用标记提示迁移窗口。合同测试在CI中校验请求与响应的Schema兼容, 防止破坏性变更。 ## 关键实践与参数 - 版本策略: 路径 `/v1` `/v2` 或 `Accept-Version` - 弃用声明: `deprecated: true` 并在文档中注明移除时间 - 兼容规则: 新增字段为可选, 保持类型与语义稳定 - 合同测试: 使用Schema校验请求/响应 ## 示例/配置/实现 ```yaml 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 } ``` ```js 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校验通过 - 发布安全: 不兼容变更被阻止或要求新版本路径 ## 注意事项 - 版本窗口需明确与可见 - 避免静默移除字段, 提前通知并提供迁移指南 - 合同测试覆盖主路径与错误响应 - 与网关的路由与监控协同