Cursor 与 Codex:从技术债到现代化前端的工程化重构实战
接手一个遗留的 React 项目,就像走进一间堆满旧家具的仓库。组件文件动辄上千行,状态逻辑和 UI 渲染纠缠不清,样式表是十年前的技术栈,测试覆盖率几乎为零。每次新增功能都如履薄冰,生怕触动哪根脆弱的神经,导致整个应用崩溃。这种技术债的累积,不仅拖慢开发速度,更让团队士气低落。然而,现在你手中多了一件前所未有的利器——Cursor IDE 与 Codex 的深度联动。这不再仅仅是代码补全工具,而是一个能理解项目上下文、执行复杂工程任务、甚至能连续工作数小时的智能编程伙伴。本文将带你深入实战,看我们如何利用这套组合拳,对一个基于 React 16 和传统 CSS 的遗留学习应用,进行一场彻底的、工程化的现代化重构,最终将其升级为 React 18 + TypeScript + Chakra UI 的现代化应用。
1. 环境搭建与项目诊断:建立清晰的改造基线
在挥舞重构大锤之前,我们必须先给项目做一次全面的'体检'。盲目动手只会让混乱的代码更加混乱。我们的目标项目是一个名为'LingoLearn'的英语学习应用,代码库已经存在了三年,混合了 Class 组件和 Function 组件,样式直接写在 style 属性里,没有任何类型检查。
首先,我们需要在 Cursor 中配置好 Codex 环境。安装官方插件后,你会在侧边栏看到一个全新的机器人图标。关键一步是在项目根目录创建 AGENTS.md 文件。这个文件是 Codex 理解你项目规范、技术栈和重构目标的'项目圣经'。它远比简单的提示词有效,因为它能持续地为 AI 提供上下文。
# AGENTS.md - LingoLearn 重构项目指南
## 项目概述
本项目是一个遗留的英语学习单页应用(SPA),当前技术栈为 React 16 + 内联 CSS。本次重构的目标是将其现代化,提升可维护性、性能及开发体验。
## 目标技术栈
- **框架**: React 18 (使用严格模式)
- **语言**: TypeScript 5.x (启用严格类型检查)
- **UI 库**: Chakra UI v2.x (移动端优先的响应式设计)
- **构建工具**: Vite 5.x (替代 Create React App)
- **状态管理**: 逐步引入 Zustand,替换原有的 Context 滥用
- **测试**: Vitest + React Testing Library,目标覆盖率 > 80%
- **代码规范**: ESLint (Airbnb 配置扩展) + Prettier
## 重构核心原则
1. **渐进式重构**: 优先重构高频访问和即将修改的模块,确保业务连续性。
2. **关注点分离**: 将业务逻辑、状态管理和 UI 渲染拆分为独立单元。
3. **组件原子化**: 大型组件拆分为更小、可复用的 Presentational 组件和 Container 组件。
4. **类型安全**: 为所有函数、组件 Props 和 API 响应添加完整的 TypeScript 接口定义。
5. **性能优先**: 应用 React.memo、useCallback、useMemo,并对长列表实施虚拟滚动。

