3. 弃用策略设计：通知周期、标准头与策略模板

API 弃用不是一次性的技术操作，而是一套面向消费者的沟通与治理流程。设计良好的弃用策略能够降低迁移摩擦、避免生产事故，并为灰度验证提供明确的观测窗口。本节围绕通知周期、HTTP 标准头（Deprecation & Sunset）、超链接语义以及可复用的策略模板展开。

3.1 弃用通知周期：时间窗口与阶段划分

通知周期定义了从“首次宣布弃用”到“完全移除”之间的时间线。不同成熟度的组织应采用不同的窗口长度，但核心原则是：给消费者至少一个完整发布周期的时间进行迁移。

3.2 Deprecation Header 标准

Deprecation 响应头是 RFC 8594 定义的标准字段，用于在运行时告知消费者当前版本已被标记为弃用。它不强制消费者立即行动，但提供了明确的信号。

Deprecation: true
Deprecation: Sat, 01 Mar 2025 00:00:00 GMT
Deprecation: true; sunset="2025-06-01T00:00:00Z"

字段语义说明：

• 布尔值：true 表示当前响应来自一个已弃用的 API 版本。
• HTTP-date：表示该版本被标记为弃用的时间点。
• sunset 参数：可选，指明计划移除的时间，与 Sunset Header 配合使用。

3.3 Sunset Header 与超链接

Sunset 响应头明确告知消费者该 API 版本将在何时停止服务。它通常包含一个 HTTP-date 值，并建议附带 Link 头指向迁移文档。

Sunset: Sun, 01 Jun 2025 00:00:00 GMT
Link: <https://api.example.com/docs/v2-migration>; rel="sunset"

超链接的 rel="sunset" 语义允许消费者自动发现迁移资源，实现机器可读的弃用流程。

3.4 弃用策略模板

以下模板可直接嵌入 API 网关或 BFF 层，实现标准化的弃用响应注入。

# 弃用策略配置模板 (YAML)
api_deprecation:
  # 全局弃用窗口
  default_sunset_days: 90
  # 按版本覆盖
  versions:
    v1:
      deprecated_at: "2025-03-01T00:00:00Z"
      sunset_at: "2025-06-01T00:00:00Z"
      migration_url: "https://api.example.com/docs/v1-to-v2"
      # 灰度比例：0-100
      traffic_percent: 100
    v2:
      deprecated_at: null
      sunset_at: null
      migration_url: null
      traffic_percent: 0
  # 响应头注入规则
  headers:
    deprecation: true
    sunset: "{{ .Version.sunset_at }}"
    link: '<{{ .Version.migration_url }}>; rel="sunset"'

3.5 弃用信号交互流程

下图展示了消费者与 API 网关之间的弃用信号交互过程，涵盖标准头传递与超链接发现。

3.6 策略模板与灰度验证的衔接

弃用策略模板不应孤立存在，它需要与灰度验证系统共享以下关键字段：

• 版本标识：v1、v2 等，用于路由和指标聚合。
• 流量比例：traffic_percent，灰度系统据此决定是否将请求转发至新版本。
• 弃用时间戳：灰度系统可据此触发告警或自动调整比例。