Deprecation Migration Zh

---
name: deprecation-migration-zh
description: 系统下线、功能废弃、迁移方案、数据库字段改名不停机（expand/contract 扩展-收缩）。当用户说「怎么把老系统下掉」「这个接口要废弃」「用户还在用老版本怎么迁」「生产库改字段名怎么不停机」「删列会不会出事」「两套系统并行多久」「僵尸代码要不要删」时使用。核心：代码是负债、Hyrum 定律让删除变难、下线要在设计时规划；下线决策五问、劝导式 vs 强制式、迁移四步、绞杀者/适配器/特性开关三种模式、schema 迁移的扩展→回填→收缩、僵尸代码处理。也覆盖「不停机」「支付接口」「没人维护」这类说法。改编自 addyosmani/agent-skills 的 deprecation-and-migration（MIT）。
author: Captain
version: 0.1.1
display_name: "下线与迁移（扩展-收缩）"
display_name_en: "Deprecation & Migration (zh)"
description_zh: "把老系统、旧接口、旧字段安全下线：决策五问、迁移四步、绞杀者/适配器/开关模式、数据库 expand/contract 不停机改名、僵尸代码处理。"
description_en: "Retire old systems, APIs and columns safely: five decision questions, a four-step migration, strangler/adapter/flag patterns, zero-downtime expand/contract schema changes, zombie-code handling."
tags:
  - "系统下线"
  - "deprecation"
  - "迁移"
  - "migration"
  - "expand-contract"
  - "数据库迁移"
  - "僵尸代码"
examples_zh:
  - "生产库要把 name 改成 full_name，怎么做到不停机"
  - "老的支付接口要废弃，给我一个迁移计划"
  - "这个没人维护但很多人依赖的模块怎么处理"
examples_en:
  - "Rename name to full_name in production without downtime"
  - "Plan the deprecation of the old payment API"
  - "How to deal with a module nobody maintains but everyone depends on"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "🧯" } }
---

# 下线与迁移

多数团队擅长建东西，很少有团队擅长拆东西。这份技能补的就是这块。

## 三个前提

- **代码是负债。** 每一行都要测试、文档、安全补丁、依赖升级和新人理解成本；价值在功能，不在代码。同样的功能能用更少代码提供，旧的就该走。
- **Hyrum 定律让删除变难。** 用户够多时，每个可观察行为——包括 bug、时序怪癖、未文档化的副作用——都会被依赖。所以下线需要主动迁移，不是发个公告。
- **下线在设计时就要规划。** 建新东西时问一句："三年后怎么把它删掉？"接口干净、有开关、表面积小的系统好删。

## 下线决策五问

1. 它还提供独特价值吗？有就维护，没有再往下。
2. 多少消费者依赖它？量化迁移范围。
3. 替代品存在吗？不存在先建替代品，没有替代品不许下线。
4. 每个消费者的迁移成本？能自动化就做；手工且高成本就与维护成本权衡。
5. 不下线的持续成本？安全风险、工程师时间、复杂度的机会成本。

## 劝导式 vs 强制式

| 类型 | 何时用 | 机制 |
|---|---|---|
| 劝导式 | 迁移可选、老系统稳定 | 警告、文档、提示；用户按自己节奏迁 |
| 强制式 | 老系统有安全问题、阻碍进展、维护成本不可持续 | 硬截止日；提供迁移工具 |

默认劝导式；强制式必须配迁移工具、文档与支持——不能只宣布截止日。

## 迁移四步

1. **先建替代品**：覆盖老系统的关键用例、有文档与迁移指南、已在生产验证。
2. **公告并文档**：状态、替代品、下线日期（劝导式可先无硬日期）、原因、迁移指南（改 import、改配置、跑校验脚本）。
3. **逐个迁移**：对每个消费者——找出所有接触点 → 改成替代品 → 验证行为一致 → 删除对老系统的引用 → 确认无回归。**折腾规则**：你拥有被下线的基础设施，你就负责迁移你的用户，或提供不需迁移的向后兼容更新；别公告完就让用户自己想办法。
4. **删除老系统**：先验证零活跃使用（指标、日志、依赖分析）→ 删代码 → 删测试、文档、配置 → 删下线公告 → 庆祝，删代码是成就。

## 三种迁移模式

- **绞杀者**：新老并行，流量逐步从老切到新（0% → 10% 灰度 → 50% → 100%），老系统流量归零后删除。
- **适配器**：用老接口包一层新实现，消费者继续调老接口，你在后面换引擎。
- **特性开关**：按用户/租户逐个切到新实现，随时回切。

## 数据库 schema 迁移：扩展 → 回填 → 收缩

schema 变更是最危险的迁移，因为数据不能靠回滚部署来回退。失败模式是把 schema 变更和代码变更耦合在同一次发布：改列名的同一版本开始用新名，滚动发布期间新老代码并存，总有一个在查不存在的列。**永远不要原地改列。**

以 `name` → `full_name` 为例：
1. **扩展**：新增可空列 `full_name`，发布。老代码无视它，什么都不坏。
2. **双写**：应用每次写入同时写 `name` 与 `full_name`，发布。
3. **回填**：分批把 `name` 复制到 `full_name`，别锁表。
4. **切读**：应用读 `full_name`，仍双写，发布并观察。
5. **收缩**：停写 `name`；在**另一次、更晚的**发布里删列。

规则：先加后删，删除单独发布；每个迁移都有测试过的回退（down）；回填分批限速；大索引并发创建（如 Postgres `CREATE INDEX CONCURRENTLY`）；切换有风险就用特性开关解耦。

## 僵尸代码

没人拥有但大家依赖：6 个月无提交但有活跃消费者、无负责人、测试挂着没人修、依赖有已知漏洞没人升、文档引用已不存在的系统。处理：要么指定负责人正经维护，要么带具体迁移计划下线。不能悬在中间。

## 合理化借口对照

| 借口 | 现实 |
|---|---|
| "还能用，为什么删" | 没人维护的代码在无声积累安全债与复杂度 |
| "以后可能用得上" | 以后需要可以重建；"以防万一"留着比重建更贵 |
| "迁移太贵" | 对比未来 2–3 年的维护成本，迁移通常更便宜 |
| "新系统做完再规划下线" | 到那时你有新的优先级；现在就规划 |
| "用户会自己迁" | 不会。给工具、文档、激励，或者你替他们迁 |
| "两套一起维护" | 双倍的维护、测试、文档、培训 |
| "改列名就一行" | 滚动期间新老代码并存，总有一个在查不存在的列 |
| "加列和删列放一个迁移" | 把安全的加与破坏性的删耦合；删要单独一次发布 |
| "需要时再写回退" | 没有 down 的迁移就是不能回滚的发布 |

## 红灯

没有替代品就下线；公告了没有迁移工具与文档；"软下线"劝导了好几年没进展；僵尸代码无主但有消费者；往已下线的系统加新功能；不度量使用量就下线；未验证零消费者就删代码；schema 变更和依赖它的代码同一次发布；原地改名/删列；无 down 的迁移、锁表的回填。

## 验收

下线完成后：替代品已在生产验证并覆盖关键用例；迁移指南有具体步骤；所有活跃消费者已迁（指标/日志证明）；老代码、测试、文档、配置全部删除；仓库不再引用；下线公告已删。
schema 迁移后：按扩展→回填→收缩分阶段发布；每一步新老代码都合法；每个迁移有测试过的 down、回填分批限速；破坏性步骤单独发布且已无代码引用旧结构。

```
- [ ] 替代品已在生产验证并覆盖关键用例　- [ ] 迁移指南有具体步骤　- [ ] 所有活跃消费者已迁（指标/日志证明）
- [ ] 老代码、测试、文档、配置全部删除，仓库不再引用　- [ ] schema 迁移按扩展→回填→收缩分阶段发布
- [ ] 每个迁移有测试过的 down、回填分批限速　- [ ] 破坏性步骤单独发布且已无代码引用旧结构
```

---
改编自 [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) 的 `deprecation-and-migration`（MIT）。改动见 ATTRIBUTION.md。