React应用架构重构指南Skill react-refactor

---

名称: react-refactor 描述: React应用程序架构重构指南，涵盖组件架构、状态架构、钩子模式、组件分解、耦合和内聚、数据流以及重构安全性。当重构React代码库、审查PR的架构问题、分解过大的组件或改进模块边界时使用。不涵盖React 19 API使用（参见react技能）或性能优化（参见react-optimise技能）。

React重构最佳实践

React应用程序的架构重构指南。包含7个类别的40条规则，按影响从关键（组件和状态架构）到增量（重构安全性）优先排序。

何时应用

• 重构现有React代码库或计划大规模重组
• 审查PR的架构问题和代码异味
• 将过大的组件分解为聚焦单元
• 从组件逻辑中提取可重用钩子
• 提高React代码的可测试性
• 减少功能模块之间的耦合

规则类别

类别	影响	规则数	关键主题
组件架构	关键	8	复合组件、无头模式、组合优于属性、客户端边界
状态架构	关键	7	状态共置、状态机、URL状态、衍生值
钩子模式	高	6	单一职责、命名、依赖稳定性、组合
组件分解	高	6	滚动测试、按变更原因提取、视图/逻辑分离
耦合与内聚	中等	4	依赖注入、循环依赖、稳定导入、无桶文件
数据与副作用	中等	4	服务器优先获取、TanStack查询、错误边界
重构安全性	低-中等	5	特征化测试、行为测试、集成测试

快速参考

关键模式 — 首先确保这些正确：

• 使用复合组件代替属性爆炸
• 将状态与使用它的组件共置
• 对复杂UI工作流使用状态机
• 分离容器逻辑与展示组件

常见错误 — 避免这些反模式：

• 当只有一个组件读取时，将状态提升到App
• 为快速变化的值使用上下文
• 获取+转换+缓存的单一钩子
• 测试实现细节而非行为

目录

1. 组件架构 — 关键
   • 1.1 对组件属性应用接口隔离 — 关键（防止30-50%的不必要重新渲染）
   • 1.2 按功能而非类型共置文件 — 关键（减少跨目录导航70%）
   • 1.3 将渲染属性转换为自定义钩子 — 关键（消除2-4层嵌套）
   • 1.4 提取无头组件以实现逻辑重用 — 关键（5倍更多重用场景）
   • 1.5 优先组合而非属性爆炸 — 关键（减少属性数量50-70%）
   • 1.6 分离容器逻辑与展示组件 — 关键（支持独立测试）
   • 1.7 使用复合组件进行隐式状态共享 — 关键（减少API表面60%）
   • 1.8 将客户端边界推到叶子组件 — 高（保持60-80%服务器渲染）
2. 状态架构 — 关键
   • 2.1 将状态与使用它的组件共置 — 关键（减少属性传递60%）
   • 2.2 衍生值而非同步状态 — 关键（消除双重渲染周期）
   • 2.3 仅在多个组件读取时提升状态 — 关键（消除不必要的父级重新渲染）
   • 2.4 仅对很少变化的值使用上下文 — 关键（5-50倍更少重新渲染）
   • 2.5 对复杂UI工作流使用状态机 — 关键（将有效状态从2^n减少到N）
   • 2.6 使用URL参数作为可分享视图的状态 — 关键（支持深度链接和分享）
   • 2.7 对多字段状态转换使用useReducer — 关键（消除不可能状态）
3. 钩子模式 — 高
   • 3.1 避免自定义钩子中的对象和数组依赖 — 高（防止每次渲染时效果重新执行）
   • 3.2 组合钩子而非嵌套它们 — 高（扁平化依赖图）
   • 3.3 当行为可命名时将逻辑提取到自定义钩子 — 高（组件缩短40-60%）
   • 3.4 遵循钩子命名约定以提高可发现性 — 高（减少导航时间40%）
   • 3.5 保持自定义钩子单一职责 — 高（3倍更易测试）
   • 3.6 使用Ref和回调稳定钩子依赖 — 高（防止无限循环）
4. 组件分解 — 高
   • 4.1 应用滚动测试以识别过大组件 — 高（代码审查快3倍）
   • 4.2 完全提取组件而非半途而废 — 高（支持独立测试和重用）
   • 4.3 按独立变更原因提取组件 — 高（每次变更触及的文件减少70%）
   • 4.4 从组件体中提取纯函数 — 高（单元测试快10倍）
   • 4.5 在重新提取前内联过早抽象 — 高（代码简化40-60%）
   • 4.6 分离视图层与业务逻辑 — 高（测试套件快5倍）
5. 耦合与内聚 — 中等
   • 5.1 使用中间模块打破循环依赖 — 中等（消除导入时未定义错误）
   • 5.2 仅从稳定公共API表面导入 — 中等（支持内部重构）
   • 5.3 使用无桶文件功能模块实现干净依赖 — 中等（构建减少200-800ms）
   • 5.4 为外部服务使用依赖注入 — 中等（测试设置快3倍）
6. 数据与副作用 — 中等
   • 6.1 默认在服务器上获取数据 — 中等（减少客户端JS 30-60%）
   • 6.2 在数据获取粒度放置错误边界 — 中等（错误隔离到受影响部分）
   • 6.3 使用上下文模块模式共置操作 — 中等（集中数据变更）
   • 6.4 对客户端服务器状态使用TanStack查询 — 中等（消除80%的获取样板代码）
7. 重构安全性 — 低-中等
   • 7.1 避免对重构组件进行快照测试 — 低-中等（消除错误测试失败）
   • 7.2 提取纯函数以提高可测试性 — 低-中等（测试执行快10倍）
   • 7.3 优先集成测试以验证组件 — 低-中等（捕获40%更多错误）
   • 7.4 测试组件行为而非实现细节 — 低-中等（测试更新少5倍）
   • 7.5 在重构前编写特征化测试 — 低-中等（捕获90%非预期变更）

参考文献

1. https://react.dev
2. https://react.dev/learn/thinking-in-react
3. https://kentcdodds.com/blog/application-state-management-with-react
4. https://testing-library.com/docs/guiding-principles
5. https://patterns.dev

相关技能

• 关于React 19 API最佳实践，参见react技能
• 关于应用程序性能优化，参见react-optimise技能
• 关于客户端表单处理，参见react-hook-form技能