4. API 版本管理：API 版本化策略、兼容性保证、弃用通知机制设计

在租户隔离的蓝绿部署场景中，API 版本管理是控制变更风险、保障多租户业务连续性的核心防线。版本管理不当会导致旧版客户端大面积 4xx/5xx 错误，甚至引发租户数据隔离失效。本节从版本化策略、兼容性保证、弃用通知机制三个维度展开。

4.1 API 版本化策略

云原生环境下主流的版本化策略分为 URI 路径版本、请求头版本 和 查询参数版本 三类。在租户隔离蓝绿部署中，推荐采用 URI 路径版本 + 请求头版本 的组合策略：路径版本用于粗粒度大版本（v1、v2），请求头版本用于细粒度小版本或租户灰度。

4.2 兼容性保证

兼容性保证分为 向后兼容（新 API 不破坏旧客户端）和 向前兼容（旧 API 能被新客户端正确处理）。在租户隔离场景下，需额外关注 租户级兼容性：同一 API 版本对不同租户可能返回不同字段。

4.2.1 兼容性检查清单

• 字段级兼容： 新增字段必须为 optional，禁止删除或重命名已有字段。
• 枚举值兼容： 枚举只增不减，旧客户端遇到新枚举值应降级处理。
• 语义兼容： 同一 HTTP 方法 + 路径的语义不能变更（如 GET 不能变为写操作）。
• 租户隔离兼容： 不同租户的响应结构差异应通过 X-Tenant-Id 头或租户专属 schema 区分，不改变公共契约。

4.2.2 兼容性保证流程

1. 契约先行： 每个 API 版本维护独立的 OpenAPI 规范文件，存储在版本控制中。
2. 自动化 diff： 每次 PR 触发 oasdiff，输出兼容性报告。
3. 租户 schema 映射： 在 API Gateway 层根据租户 ID 动态选择响应 schema 版本。
4. 降级策略： 旧客户端发送未知字段时，服务端忽略而非报错。

4.3 弃用通知机制设计

弃用通知是 API 版本管理的“最后一公里”。在租户隔离蓝绿部署中，弃用通知必须做到 可追溯、可配置、可观测。设计核心包括三个层次：

4.3.1 响应头通知

在 HTTP 响应头中嵌入弃用信息，客户端 SDK 可自动解析并告警。

HTTP/1.1 200 OK
Content-Type: application/json
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Deprecation: true
Link: </api/v2/orders>; rel="successor-version"
X-Tenant-Deprecation: tenant-abc; sunset="2025-06-30"

4.3.2 租户级弃用策略

不同租户的弃用时间线可能不同。需在配置中心维护租户-版本映射表，支持按租户粒度设置 sunset 日期。

4.3.3 通知渠道与频率

• 响应头通知： 每次 API 调用实时返回，频率由客户端调用量决定。
• 邮件/站内信： 在弃用前 90 天、30 天、7 天、1 天分别发送。
• Dashboard 告警： 在租户控制台显示“API 版本即将弃用”横幅。
• Webhook 回调： 允许租户注册回调 URL，弃用事件触发时推送 JSON 载荷。

4.4 版本生命周期管理

每个 API 版本应经历 活跃 → 弃用 → 仅日志 → 下线 四个阶段。在蓝绿部署中，版本生命周期与部署环境绑定：

• 活跃期： 版本在蓝/绿环境中均正常服务，支持全量租户。
• 弃用期： 版本仍在绿环境运行，但响应头携带 Deprecation: true，同时启动通知流程。
• 仅日志期： 版本返回 200 但记录所有请求的租户 ID、客户端 IP、User-Agent，用于排查未迁移客户端。
• 下线期： 版本从路由表中移除，返回 410 Gone。