---
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/) 授權釋出。
