deprecation-and-migration

name	deprecation-and-migration
description	管理弃用和迁移。在移除旧系统、API 或功能时使用。在将用户从一个实现迁移到另一个实现时使用。在决定是否维护或淘汰现有代码时使用。

弃用与迁移

概述

代码是负债，而非资产。每一行代码都有持续的维护成本——需要修复的缺陷、需要更新的依赖项、需要应用的安全补丁以及需要培训的新工程师。弃用是移除不再值得保留的代码的纪律，迁移是将用户安全地从旧系统转移到新系统的过程。

大多数工程组织擅长构建东西。很少擅长移除东西。本技能填补了这一空白。

何时使用

• 用新的系统、API 或库替代旧的
• 淘汰不再需要的功能
• 整合重复实现
• 移除无人拥有但人人依赖的死代码
• 规划新系统的生命周期（弃用规划始于设计阶段）
• 决定是维护遗留系统还是投资迁移

核心原则

代码是负债

每一行代码都有持续的成本：它需要测试、文档、安全补丁、依赖项更新，以及任何在附近工作的人的心智开销。代码的价值在于它提供的功能，而非代码本身。当相同的功能可以用更少的代码、更少的复杂度或更好的抽象来提供时——旧代码就应该消失。

Hyrum 定律使移除变得困难

当用户足够多时，每个可观察的行为都会被依赖——包括缺陷、时序怪癖和未记录的副作用。这就是为什么弃用需要主动迁移，而不仅仅是公告。当用户依赖替换系统无法复制的行为时，他们无法"直接切换"。

弃用规划始于设计阶段

在构建新东西时，问："我们在 3 年后将如何移除它？"具有清晰接口、功能标志和最小暴露面的系统比到处泄漏实现细节的系统更容易弃用。

弃用决策

在弃用任何东西之前，回答这些问题：

1. 这个系统是否仍然提供独特的价值？
   → 如果是，维护它。如果不是，继续。

2. 有多少用户/消费者依赖它？
   → 量化迁移范围。

3. 是否存在替代方案？
   → 如果没有，先构建替代方案。不要在没有替代方案的情况下弃用。

4. 每个消费者的迁移成本是多少？
   → 如果可以简单自动化，就自动化。如果是手动且高成本的，与维护成本进行权衡。

5. 不弃用的持续维护成本是多少？
   → 安全风险、工程师时间、复杂度的机会成本。

建议性弃用 vs 强制性弃用

类型	何时使用	机制
建议性	迁移是可选的，旧系统是稳定的	警告、文档、提示。用户按自己的时间表迁移。
强制性	旧系统有安全问题、阻碍进展，或维护成本不可持续	硬性截止日期。旧系统将在日期 X 被移除。提供迁移工具。

默认为建议性。 仅当维护成本或风险证明强制迁移是合理的时候才使用强制性。强制性弃用需要提供迁移工具、文档和支持——你不能只宣布一个截止日期。

迁移流程

步骤 1：构建替代方案

在没有可工作的替代方案之前不要弃用。替代方案必须：

• 覆盖旧系统的所有关键用例
• 具有文档和迁移指南
• 在生产环境中被证明有效（而不仅仅是"理论上更好"）

步骤 2：公告和文档化

## 弃用通知：OldService

**状态：** 自 2025-03-01 起已弃用
**替代方案：** NewService（见下方迁移指南）
**移除日期：** 建议性——尚无硬性截止日期
**原因：** OldService 需要手动扩缩容且缺乏可观测性。
         NewService 自动处理这两者。

### 迁移指南
1. 将 `client "example.com/old-service"` 替换为 `client "example.com/new-service"`
2. 更新配置（见下方示例）
3. 运行迁移验证脚本：`go run ./cmd/migrate-check`

步骤 3：增量迁移

逐个迁移消费者，而非一次性全部迁移。对于每个消费者：

1. 识别与已弃用系统的所有接触点
2. 更新为使用替代方案
3. 验证行为匹配（测试、集成检查）
4. 移除对旧系统的引用
5. 确认无回归

变更规则： 如果你拥有正在被弃用的基础设施，你有责任迁移你的用户——或提供不需要迁移的向后兼容更新。不要仅发布弃用公告然后让用户自行解决。

步骤 4：移除旧系统

仅在所有消费者都已迁移之后：

1. 验证零活跃使用（指标、日志、依赖分析）
2. 移除代码
3. 移除相关测试、文档和配置
4. 移除弃用通知
5. 庆祝——移除代码是一项成就

迁移模式

绞杀模式

并行运行新旧系统。逐步将流量从旧系统路由到新系统。当旧系统处理 0% 流量时，移除它。

阶段 1：新系统处理 0%，旧系统处理 100%
阶段 2：新系统处理 10%（灰度）
阶段 3：新系统处理 50%
阶段 4：新系统处理 100%，旧系统空闲
阶段 5：移除旧系统

适配器模式

创建一个适配器，将调用从旧接口转换到新实现。消费者继续使用旧接口，而你在后台迁移。

// 适配器：旧接口，新实现
type LegacyTaskService struct {
	newService *NewTaskService
}

// 旧方法签名，委托给新实现
func (s *LegacyTaskService) GetTask(id int) (*OldTask, error) {
	task, err := s.newService.FindByID(strconv.Itoa(id))
	if err != nil {
		return nil, err
	}
	return toOldFormat(task), nil
}

功能标志迁移

使用功能标志逐个将消费者从旧系统切换到新系统：

func getTaskService(userID string) TaskService {
	if featureFlags.Enabled("new-task-service", userID) {
		return NewTaskService()
	}
	return NewLegacyTaskService()
}

数据库 Schema 迁移（扩展/收缩）

Schema 变更是风险最高的迁移，因为数据是唯一无法通过回滚部署来撤销的东西。失败模式是将 schema 变更与代码变更耦合：在同一个发布中重命名列并同时开始使用新名称，在滚动发布窗口期间——当新旧代码同时运行时——其中之一会查询一个不存在的列。修复方法是永远不要原地修改列。以增量添加的阶段进行迁移，使新旧代码在每个步骤都有效。

扩展 ──────────────→ 迁移 ──────────────→ 收缩
添加新列，可为空，    回填现有行，从应用    一旦没有代码再读取旧列，
与旧列并存             层双写新旧两列        在稍后的独立部署中删除它

具体示例——将 name 重命名为 full_name：

1. 扩展。 添加可为空的 full_name 列。部署。（旧代码忽略它；没有东西出错。）
2. 双写。 应用在每次插入/更新时同时写入 name 和 full_name。部署。
3. 回填。 为现有行将 name 复制到 full_name，分批进行，以免锁表。
4. 切换读取。 将应用指向 full_name，继续双写。部署并观察。
5. 收缩。 停止写入 name，然后——在单独的、稍后的部署中——删除该列。

每一步都是可独立部署和可逆的：如果步骤 4 出现问题，回滚代码，而 full_name 仍然在写入。将每个阶段视为薄垂直切片——参见 incremental-implementation 技能。

规则：

• 先添加，最后和单独进行破坏性操作。 添加（新的可为空列、新表、新索引）在任何部署中都是安全的；删除和重命名应在没有代码再引用旧结构之后，在它们自己的部署中进行。
• 每个迁移都有经过测试的 down 路径。 不可逆的迁移就是不可回滚的部署。在合并之前编写并运行 down。
• 在热路径之外分批回填。 对上百万行的单个 UPDATE 会锁表；分块并限流。
• 构建大索引时不阻塞写入（例如 Postgres 的 CREATE INDEX CONCURRENTLY）。
• 在切换有风险时通过功能标志与代码解耦，完全如上方的功能标志迁移模式。

僵尸代码

僵尸代码是无人拥有但人人依赖的代码。它没有被积极维护，没有明确的所有者，并累积安全漏洞和兼容性问题。迹象：

• 6 个月以上无提交但存在活跃消费者
• 没有指定的维护者或团队
• 失败的测试无人修复
• 带有已知漏洞的依赖项无人更新
• 文档引用不再存在的系统

应对措施： 要么指定所有者并妥善维护它，要么通过具体的迁移计划弃用它。僵尸代码不能留在无人区——它要么得到投入，要么被移除。

常见合理化借口

合理化借口	现实
"它还能用，为什么要移除它？"	能工作但无人维护的代码会累积安全债务和复杂度。维护成本在无声地增长。
"可能以后有人需要它"	如果以后需要，可以重新构建。保留"以防万一"的未使用代码的成本高于重新构建的成本。
"迁移太贵了"	将迁移成本与 2-3 年的持续维护成本进行比较。长期来看，迁移通常更便宜。
"我们完成新系统后再弃用"	弃用规划始于设计阶段。等到新系统完成时，你会有新的优先级。现在规划。
"用户会自己迁移的"	他们不会。提供工具、文档和激励——或自己完成迁移（变更规则）。
"我们可以无限期地维护两个系统"	两个做同样事情的系统意味着双倍的维护、测试、文档和培训成本。
"只是重命名一列，就一行代码"	在滚动发布期间，新旧代码同时运行——其中之一会查询一个不再存在的列。扩展/收缩，永远不要原地重命名。
"我会在同一迁移中添加列并删除旧列"	这会将安全的新增与破坏性的删除耦合。删除操作在它们自己的部署中进行，在没有代码再引用旧结构之后。
"需要时我们再写回滚脚本"	没有 down 路径的迁移就是不可回滚的部署。在合并之前编写并运行 down。

红旗警告

• 已弃用的系统没有可用的替代方案
• 弃用公告没有迁移工具或文档
• "软"弃用已建议多年却无进展
• 没有所有者但有活跃消费者的僵尸代码
• 向已弃用的系统添加新功能（应投入到替代方案中）
• 未衡量当前使用量就弃用
• 未验证零活跃消费者就移除代码
• Schema 变更和依赖它的代码在同一个部署中发布
• 原地重命名或删除列，而非通过扩展/收缩
• 迁移合并时没有经过测试的 down 路径，或回填操作锁表

验证

完成弃用后：

• 替代方案已在生产中得到验证并覆盖所有关键用例
• 迁移指南存在，包含具体步骤和示例
• 所有活跃消费者已迁移（通过指标/日志验证）
• 旧代码、测试、文档和配置已完全移除
• 代码库中没有对已弃用系统的残留引用
• 弃用通知已移除（它们已完成使命）

完成数据库 schema 迁移后：

• 变更是以增量添加阶段发布的（扩展 → 回填 → 收缩），而非单次原地编辑
• 新旧代码在每个部署步骤中对该 schema 都有效
• 每个迁移都有经过测试的 down 路径；回填运行在限流批处理中
• 破坏性步骤（删除/重命名）在它们自己的部署中发布，在没有代码再引用旧结构之后