第 13 章 · 场景案例四：安全重构（分步控范围）
本章目标：跟练 中等规模重构——抽取重复逻辑、迁移调用方；用 Ask 摸底 → 加兼容层 → 分批 SRX → 最后删旧码；配合 实施计划、影响面、Timeline、Git 四件套；SRX 毕业案例。
学时建议：4～5 小时（可分两天：摸底+兼容一天，迁移+删除一天）
前置：srx-v7 ch01～ch12；git-collab 分支与 commit 熟练。
重构是 SRX 最容易改乱仓的场景；本章强调 分步与 可回滚。
13.1 场景背景
| 项目 | 内容 |
|---|---|
| 需求 | UserService 订单相关方法重复，抽到 OrderHelper |
| 风险 | 十余处 import/call，改错一处全站挂 |
| 策略 | 四步：摸底 → 加新层兼容 → 分批迁移 → 删旧码 |
| 原则 | 每步可单独 commit、可回滚 |
与 ch10～12 区别：不是单点 bug/功能，而是 多文件、多阶段、高回滚需求。
13.2 学完你能
| 能力 | 验收 |
|---|---|
| 摸底 | Ask 只读列出调用关系 |
| 兼容层 | 第一步只「加」不「删」 |
| 分批 | 按目录拆 SRX 任务，每批 commit |
| 删除 | 确认无引用再删，否则 ✗ |
| 工具 | Plan + 影响面 + Timeline + Git |
| 毕业 | 完成四案例对照表 + 真实小 refactor |
13.3 第一步：Ask 摸底（只读，必做）
Ask：
项目里 UserService（或你项目中的 xxx Service）中与订单相关的方法有哪些？
哪些文件 import 或调用了这些方法？
请列出文件路径和调用关系，不要改任何代码。您要做：
- 与文件树对照 Ask 路径
- 复制关键路径供后续 @
- 评估：小重复是否值得重构——有时 不必动刀
你应该看到：调用关系列表；无审阅条。
记录表（自建）：
| 调用方目录 | 文件 | 调用的方法 |
|---|---|---|
| apps/order/ | ... | ... |
| apps/payment/ | ... | ... |
13.4 第二步：SRX 只「加」不「删」（任务 A）
git checkout -b refactor/order-helper-extract任务 A（新任务卡）：
【目标】新建 OrderHelper，将 UserService 中订单相关纯函数迁入
【范围】
- 新建 @pkg/orderhelper/helper.go（路径按项目改）
- 修改 @internal/user/service.go（UserService 内改为调用 OrderHelper，保留原方法签名对外不变）
【约束】
- 不删除 UserService 现有对外方法
- 不改变任何 HTTP 路由与对外函数名
- 不修改 migrations、.env、settings
- 若出现【实施计划】，顺序必须是「先 Helper 再委托」，不对则稍后
【验收】
- 现有测试仍通过（如有）
- UserService 旧方法内部委托给 OrderHelper，行为不变审阅重点：
- 旧签名仍在
- 委托逻辑无行为变化
- 无无关文件
git commit -m "refactor: 抽取 OrderHelper，UserService 委托（兼容层）"你应该看到：新文件 + Service 变薄；对外 API 不变。
13.5 第三步：分批迁移调用方（任务 B-1、B-2…）
不要一次全改。按 目录分批：
任务 B-1：
【目标】将 apps/order/ 下对 UserService 订单方法的调用改为 OrderHelper
【范围】仅 apps/order/ 内文件：（粘贴 Ask 给出的具体列表，并用 @ 钉）
【约束】
- 不改 apps/order/ 以外目录
- 不改 OrderHelper 与 UserService 实现
【验收】apps/order 相关功能冒烟通过；go test ./apps/order/... 通过审阅 → commit → 任务 B-2 改 apps/payment/ ……
绝学：每批 一个目录，审阅条文件数可控（ch03 ≤6 文件建议）。
执行中：
- 影响面清单 → 下一批任务输入（ch05）
- 某批错了 → Timeline 回滚到此（ch04）