---
source: ../../../core/deprecation-standards.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-04-10
status: current
---

# 弃用与日落标准

> 版本: 1.0.0 | 最后更新: 2026-04-01

## 概述

本文件定义弃用全生命周期管理标准，涵盖 API 版本退役、功能日落、系统退役。结构化的弃用流程保护消费者、防止数据丢失，并确保基础设施干净。

---

## API 弃用

### Sunset 时间线

| 阶段 | 时间点 | 行动 |
|------|--------|------|
| **宣布** | T-6 个月 | 公布退役计划；发布 Sunset 日期；通知所有消费者 |
| **弃用** | T-3 个月 | 标记为 deprecated；加入 Deprecation 和 Sunset headers |
| **迁移** | T-3 到 T-1 个月 | 协助消费者迁移；提供迁移指南与工具 |
| **警告** | T-1 个月 | 发送最终警告；加入倒数信息 |
| **日落** | T | 停止服务；所有端点返回 410 Gone |
| **归档** | T+1 个月 | 归档文档与数据；移除基础设施 |

### HTTP 弃用 Headers

```
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/v3/docs>; rel="successor-version"
```

### 版本并行期

旧版本至少维持到以下两者中较晚者：
- 新版本 GA 后 **6 个月**
- 最后一个活跃消费者完成迁移后 **3 个月**

---

## 消费者通知策略

| 渠道 | 时机 | 内容 |
|------|------|------|
| **CHANGELOG** | 宣布阶段 | 退役计划、Sunset 日期、迁移指南链接 |
| **API Response Header** | 弃用阶段起 | Sunset header + successor-version 链接 |
| **Email / 通知** | 宣布 + 警告阶段 | 直接通知已知消费者 |
| **API 文档** | 宣布阶段起 | 明确标记为 deprecated |
| **Dashboard / 监控** | 弃用阶段起 | 追踪剩余消费者数量与流量 |

---

## 功能日落

### 影响分析 5 维度

| 维度 | 关键问题 |
|------|---------|
| **使用量** | 过去 30 天有多少用户？趋势如何？ |
| **依赖** | 哪些功能、服务或集成依赖此功能？ |
| **数据** | 是否产生或管理独特数据？需要迁移或归档？ |
| **合同** | 是否有 SLA、合同义务或合规要求？ |
| **替代方案** | 是否有替代品？用户是否知道如何迁移？ |

---

## 系统退役

7 阶段退役流程：

| 阶段 | 行动 | 验证 |
|------|------|------|
| 1. 依赖分析 | 识别所有上下游依赖 | 依赖图无未解节点 |
| 2. 消费者迁移 | 协助所有消费者迁移 | 流量降至 0 |
| 3. 数据归档 | 依合规要求归档数据 | 归档完整性已验证 |
| 4. DNS/重定向 | 旧端点返回 410 或重定向 | 响应已验证正确 |
| 5. 基础设施清理 | 移除服务器、数据库、队列 | 资源释放已确认 |
| 6. 监控移除 | 移除告警、仪表板、Runbook | 无孤立告警 |
| 7. 文档归档 | 标记文档为已归档 | 文档索引已更新 |

---

## 退役指标

| 指标 | 定义 | 目标 |
|------|------|------|
| **消费者迁移率** | 已迁移 / 总消费者 | Sunset 时 100% |
| **剩余流量** | 每日 deprecated 端点请求数 | Sunset 时 0 |
| **依赖清理率** | 已清理 / 总依赖 | Archive 时 100% |
| **数据归档完成率** | 已归档 / 需归档总数 | Archive 时 100% |

---

## 快速参考卡

### Sunset 时间线摘要
```
T-6 个月   → 宣布（发布计划）
T-3 个月   → 弃用（加入 headers）
T-3 到 T-1 → 迁移（协助消费者）
T-1 个月   → 警告（最终通知）
T          → 日落（410 Gone）
T+1 个月   → 归档（清理）
```

---

## 许可

本标准以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。
