11.2 大型项目重构实战

重构的最佳实践

大型项目重构风险高、周期长，建议遵循以下流程：

1. 用计划模式（Ctrl+G）探索代码库，制定重构方案
2. 将方案拆分为多个小步骤，逐个执行
3. 每步完成后运行测试验证
4. 分叉会话（--fork-session）处理探索性任务，不打断主线
5. 提交时使用描述性的 commit 信息

计划模式重构流程

第一步：探索分析

cd /path/to/large-project
claude

# 进入计划模式
[Ctrl+G]

→ 重构 src/auth/ 模块，将 JWT 认证替换为 OAuth2
→ 需要涉及哪些文件？
→ 改动范围有多大？
→ 有什么潜在风险？

计划模式下 Claude 会探索代码库但不修改文件，输出详细方案。

第二步：分步骤执行

# 方案确认后，分步骤执行
→ 先重构用户登录部分，更换 Token 验证逻辑

# 运行测试
→ 运行 npm test -- --grep auth 验证

# 继续下一个模块
→ 重构 Session 管理部分

第三步：验证与提交

→ 运行全部测试套件

# 提交变更
→ 用清晰的 commit 信息提交，例如：
"refactor(auth): replace JWT with OAuth2, update session management"

上下文管理

大型项目重构时，上下文很快会填满。善用以下工具：

分叉会话示例

# 新终端窗口，分叉出探索会话
claude --fork-session "探索 GraphQL 迁移风险"

# 主会话继续日常工作
claude --continue

重构策略

渐进式重构

不要一次性大规模改动。将大型重构拆分为多个小 PR：

• PR 1：基础设施准备（如添加新的认证服务类）
• PR 2：数据层迁移（旧逻辑与新逻辑并存）
• PR 3：切换调用入口
• PR 4：清理旧代码

新旧并存策略

# 保留旧实现，通过配置切换
// auth/index.ts
export const auth = process.env.NEW_AUTH === 'true' ? newOAuthAuth() : oldJWTAuth()

测试策略

重构前确保有足够的测试覆盖，重构后逐个验证：

# 在重构前
→ 帮我检查 src/auth/ 的测试覆盖率

# 重构后验证
→ 运行 npm test -- --coverage 确认覆盖率未下降
→ 运行集成测试确认认证流程正常

典型重构场景

场景一：废弃 API 迁移

→ 查找项目中所有调用旧 API（/api/v1/users）的代码，
  替换为新 API（/api/v2/users），
  确保参数格式正确，处理响应差异。

场景二：技术栈升级

→ 将 src/utils/ 下的普通函数重构为 TypeScript 类型安全的版本，
  定义必要的接口和类型别名，
  确保不影响现有调用。

场景三：性能优化重构

→ 分析 src/api/product.js 中的数据库查询，
  找出 N+1 查询问题，
  优化为批量查询并验证性能提升。