一次类改名，IDE 的 "Rename" 报了 32 处改动，编译通过、测试全绿。上线后两个功能失效：一个是配置里用字符串指定的类名（type: com.foo.OldName），一个是反射调用的 Class.forName("com.foo.OldName")。
IDE 的重命名只改"语法层面的引用"，而字符串、配置、注解、SQL、序列化这五处的"名字"是数据，不是语法。这个区分的关键是"名字出现在哪里"：出现在语法里的名字，IDE 知道；出现在数据里的名字，IDE 不知道——而后者同样"是名字"。
于是"安全重命名"从来不是"按一个快捷键"，而是"按一个流程"。
1. IDE 能改的四类引用
| 类别 | IDE 是否能改 |
|---|---|
| 类型引用（new/ex第五项（上线后才暴露）的判据是"这条路径在测试里是否被走到"：如果它是"管理员才能触发的"或"每月跑一次的"，那它在测试里几乎必然被漏。 | |
| tends/参数） | 能 |
| 方法/字段引用 | 能 |
| 同包内文件路径 | 能（随类名迁移） |
| XML/注解中的类名 | 部分（取决于插件） |
第四项是"部分"：Spring 的 @Component(beanName)、MyBatis 的 typeAlias、Spring 的 XML bean 的 class 有的能被识别，有的不能。
所以"IDE 说改完了"只覆盖了"语法引用"这个子集。第四项的"部分"取决于插件：IDE 能识别"注解里的类引用"（因为那是语法），但识别不了"注解里的字符串值"——而 @Component("x") 里的 "x" 正是字符串。
2. 改不到的五处
| 位置 | 例子 |
|---|---|
| 配置文件 | type: com.foo.OldName、class: |
| 反射调用 | Class.forName("…OldName") |
| 序列化/存储 | JSON 的 @type、数据库里的类名 |
| SQL / 视图 | 存储过程里引用类名（少见但存在） |
| 运维脚本 | 启动参数 --class=… |
第三项的"暴露延迟"最长：它要等"有人读到那条旧数据"才报错——可能是几天后、可能是从来没读过的归档数据，而"写的时候一切正常"。
第三项最危险：已经落盘的数据里带着旧类名，于是"代码改了、历史数据读不出来"。
// 一次真实故障的三处遗漏（类名改动的案例）
1 application.yml: beans.legacy.class=com.foo.OldService ← 改不到
2 Redis 里的缓存值：{"@type":"com.foo.OldService",...} ← 改不到
3 运维脚本：java -cp app.jar com.foo.OldMain ← 改不到
// 三处都"看起来不像代码"，于是都不在"重命名"的心智模型里
3. 安全重命名的五步流程
| 步骤 | 动作 |
|---|---|
| 1 全局搜旧名（含字符串） | 所有引用面 |
| 2 IDE 重命名 | 语法引用 |
| 3 处理字符串/配置 | 逐处确认 |
| 4 编译 + 测试 + 启动 | 覆盖反射路径 |
| 5 灰度观察 | 覆盖运行期序列化 |
第一步的搜索要"不含引号的字面搜索"：grep -r "OldService" 而不是"按类型搜索"，因为后者只找语法引用。第一步的"完整性"还可以用一个技巧验证：搜"旧名去掉包路径的短名"（OldService 而不是 com.foo.OldService）——因为配置与数据里常只写短名或全名两种形态之一。
// 五类位置的搜索（五条命令，覆盖全部）
grep -rn "OldService" --include=*.java --include=*.kt src/
grep -rn "OldService" --include=*.yml --include=*.yaml --include=*.properties .
grep -rn "OldService" --include=*.xml . # MyBatis/Spring XML
grep -rn "OldService" --include=*.sql --include=*.json . # 数据/序列化样例
grep -rn "OldService" . --exclude-dir=.git # 兜底：脚本与文档
4. 改名 vs 加别名
| 策略 | 代价 |
|---|---|
| 直接改名 | 破坏历史数据/配置 |
| 改名 + 保留别名（deprecated） | 兼容期，代码冗余 |
| 全新类 + 迁移 | 最稳，工作量最大 |
第二项的"成本"是"多一段映射代码 + 一个清理期限"：映射不能永久留着，否则"两个名字都有效"成为事实标准——而它会让下一次改名更难。
第二项在"序列化数据"场景里常用：新类名生效，同时保留"旧类名 → 新类"的映射（如 Jackson 的 @JsonAlias 或自定义 TypeResolver）。
于是"改代码"与"处理历史数据"被分开：代码立刻可用新名，历史数据仍能读。
"改名流程"可以固化成一条检查单，五步写在 PR 模板里：
// 改名 PR 的检查单（五步）
[ ] 字面搜索旧名：java / yml / xml / sql / json / sh 六类文件
[ ] IDE 重命名（语法引用）
[ ] 处理"字符串引用"（配置项、反射、注解的 beanName）
[ ] 编译 + 全量测试 + 本地启动（覆盖反射与可选注入）
[ ] 灰度观察 24h（覆盖历史数据反序列化）
// 任一未勾 → 不合入；缺第 5 步时必须在 PR 里写明"为何可跳过"
5. 什么名字不值得改
| 情况 | 原因 |
|---|---|
| 已被外部依赖的名字 | 改名=破坏契约 |
| 序列化落盘的类型名 | 需兼容映射 |
| 大量字符串引用（低收益） | 回归风险高于收益 |
| 即将废弃的代码 | 白改 |
第一项在"公开 SDK/API"上：类名就是契约的一部分（客户端 import 时用它）。第三项的"量化"可以这样算：字符串引用越多，改名收益越被摊薄。因为"改名的收益"是"可读性"，而"风险"是"漏一处就静默失效"。
第三项的判据是"字符串引用的数量"：如果它有 50 处字符串引用，而 IDE 只能改 20 处，那这次改名的收益（可读性）可能低于风险。
"反序列化失败"的兼容写法值得给一个具体例子，因为它是最容易漏的一类：
// 兼容旧类名：注册"别名 → 新类"的映射（Jackson 为例）
@JsonTypeName("OldService")
public class NewService { ... }
// 或全局注册（多态反序列化的 type 字段）
mapper.registerSubtypes(new NamedType(NewService.class, "OldService"));
// 关键：新类名 + 旧别名同时可用，于是"历史数据能读、新代码用新名"
6. 排错：五种"改名后的问题"
| 现象 | 成因 | 处理方向 |
|---|---|---|
| 配置不生效 | 配置文件里的旧类名 | 搜配置 |
启动报 ClassNotFound |
反射/脚本文本 | 搜字符串 |
| 反序列化失败 | 历史数据带旧类名 | 加别名映射 |
| 某功能静默失效 | 注解里的 beanName | 搜注解与 XML |
| 上线后才暴露 | 只在特定路径用到 | 灰度覆盖 |
第四项的"静默"机制是"按类型注入仍然工作、按名字注入失效"：于是"大部分地方正常，少数地方拿到 null"——而报错点离改名点很远。
第四项最隐蔽：@Component("oldName") 里的 beanName 不随类名变，于是"按名字注入"的地方取不到 bean——而启动不报错（因为它是懒加载或可选注入）。
最后一个"度量"：统计"字符串引用数 / 语法引用数"的比值。它决定了这次改名的风险等级。
// 三类改名的风险（用比值判断）
比值 < 0.05（几乎全在代码里）：IDE 改名即可，风险低
比值 0.05–0.3：按五步流程，重点看配置与注解
比值 > 0.3：改名收益可能低于风险，考虑"加注释说明"而非改名
7. 边界：什么情况重命名是安全的
| 场景 | 为什么 | 做法 |
|---|---|---|
| 内部私有类（无字符串引用） | 只有语法引用 | IDE 改名即可 |
| 单元测试覆盖充分 | 出错会被发现 | IDE + 测试 |
| 无序列化/无配置引用 | 无"数据里的名字" | IDE 即可 |
| 全新代码（未上线） | 无历史数据 | IDE 即可 |
判断口径一句话：这个类的名字"有没有出现在代码之外"（配置、数据、脚本、文档）。没有，IDE 改名是安全的；有，就必须按五步流程走完。
8. 自测
- IDE 能改的四类引用是什么？为什么"XML/注解"只能算"部分"？
- 五种"改不到"的位置里，哪一种最危险？为什么它"只在历史数据上暴露"？
- 安全重命名的第一步为什么用"字面搜索"而不是"按类型搜索"？
- "改名 + 保留别名"解决了什么问题？它把哪两件事分开了？
- 为什么"注解里的
beanName"会造成静默失效？ - 判断"重命名是否安全"的那个问题是什么？