API Schema 演进与版本兼容（OpenAPI、语义版本、弃用与迁移）

API Schema 演进与版本兼容（OpenAPI、语义版本、弃用与迁移）概述API 的长周期演进需要严格的契约管理与兼容策略。语义版本与弃用流程保障客户端稳定。关键实践与参数语义版本：`MAJOR.MINOR.PATCH`；新增字段属兼容性变更（MINOR），删除/修改属破坏性（MAJOR）。路径/头版本：`/v1` 路径或 `Accept: application/vnd.company.resource+json;version=2`。弃用标记：OpenAPI 中 `deprecated: true` 并给出迁移说明与时间表。合同测试：针对 Schema 生成测试确保服务端/客户端兼容。示例（OpenAPI 片段）paths: /v1/orders: get: deprecated: true description: 请迁移到 /v2/orders 验证方法通过 OpenAPI 校验器与 Linter 检查破坏性变更。在 CI 中运行合同测试与回归；对客户端进行兼容性测试。指标：旧版本调用占比与迁移进度跟踪。注意事项明确弃用窗口与沟通计划；避免突发下线。各版本的认证与限流策略需一致或清晰区隔。生成 SDK 时保持版本对齐与发布说明。