Composer大型任务与跨文件重构技术实践指南

一、Composer是什么？

Composer是Cursor的多文件编辑界面（快捷键为Cmd/Ctrl + Shift + I），它提供持久化的工作会话，允许同时操作任意数量的文件，并在一次会话内完成多轮对话与迭代。与传统的Chat（侧边栏）相比，Composer支持更复杂的场景，如系统级改造和跨模块重构。以下是Composer与Chat的主要区别：

二、跨文件重构的难点与Composer的解法

传统重构的痛点

随着业务的增长，代码库中会出现各种“历史欠债”，如模块间直接依赖、命名不一致、逻辑散落在多个文件以及旧框架版本升级等问题。手动重构这些问题需要搜索所有引用、逐一修改和反复验证。Composer的价值在于给AI完整的上下文后，它可以一次性规划所有变更，生成一致的改动方案。

三、实战：把Class组件全部迁移到Hooks（React）

步骤1：分析阶段（让AI先规划再动手）

请先不要修改任何文件。

先帮我分析 src/components/ 目录下所有使用 React.Component 或 
PureComponent 的 Class 组件，列出：
1. 文件路径
2. 组件名称
3. 使用了哪些生命周期方法（componentDidMount 等）
4. 是否有 local state
5. 迁移到 Hooks 的难度评估（简单/中等/复杂）

AI会扫描所有文件并给出一份清单。先拿到清单，再动手，这是大型重构的黄金法则。

步骤2：从简单的开始，建立模式

先迁移评估为"简单"的这几个组件：
- src/components/ui/Button.tsx
- src/components/ui/Badge.tsx
- src/components/layout/Header.tsx

迁移要求：
- 移除 class 声明，改为函数组件
- componentDidMount → useEffect(() => {...}, [])
- componentWillUnmount → useEffect cleanup
- this.state → useState
- 保持 props 接口完全不变（不能影响调用方）
- 迁移后在文件顶部加注释：// Migrated from class component - [日期]

步骤3：建立模式后批量处理

等简单组件验证没问题后，可以开始批量处理评估为“中等”的组件。

四、实战：重命名贯穿全项目的核心概念

场景：产品把「订单（Order）」改名为「工单（Ticket）」

需要同步修改数据库、API、前端、测试所有层面。正确的做法是使用Composer规划完整的重命名方案，确保没有遗漏。

五、实战：架构升级 — 引入依赖注入

为了解决后端代码各模块直接互相import导致测试困难的问题，可以引入依赖注入容器。Composer可以帮助规划和执行这一改造。

六、使用@引用控制Composer的上下文

Composer中，你可以用@符号精确指定AI需要阅读的内容。这有助于精确控制上下文，提高Composer的效果。

七、重构后的验证策略

7.1 自动验证（让AI帮你写验证脚本）

重构完成后，帮我写一个验证脚本 scripts/verify-refactor.ts：
1. 扫描所有文件，确认没有残留的 "Order"（非注释、非文档中的）
2. 运行 TypeScript 类型检查（tsc --noEmit）
3. 运行所有测试
4. 生成一份验证报告 refactor-report.txt

7.2 逐层验证顺序

1. 类型检查先行：tsc --noEmit，确保TypeScript编译通过
2. 单元测试：确认业务逻辑没有破坏
3. 集成测试：确认模块间协作正常
4. 手动冒烟测试：走一遍核心用户路径

7.3 保留回退路径

重大重构前，建议创建一个feature branch，不要直接在main上操作。

八、Composer的局限性与边界

Composer在处理超出Context窗口的巨型代码库、精细的视觉调整、理解业务意图和保证重构正确性方面存在局限性。

九、小结

Composer的核心价值在于给AI完整的上下文，让它生成全局一致的变更方案。高效使用的关键包括先让AI分析、给计划，你审查后再执行；用@精确控制上下文；分阶段重构，每阶段结束后commit一次；重构后必须验证。下一章我们将探讨高效Prompt工程：如何设计提示词，让Cursor第一次就给出100%符合预期的代码。感谢关注。