react-refactor

React 重构最佳实践

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

适用场景

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

规则类别

类别	影响程度	规则数	主要主题
组件架构	关键	8	复合组件、无头模式、组合优于属性、客户端边界
状态架构	关键	7	状态就近放置、状态机、URL 状态、派生值
Hook 模式	高	6	单一职责、命名、依赖稳定性、组合
组件拆分	高	6	滚动测试、按变更原因提取、视图与逻辑分离
耦合与内聚	中	4	依赖注入、循环依赖、稳定导入、不使用汇总导出文件
数据与副作用	中	4	服务端优先获取数据、TanStack Query、错误边界
重构安全性	低至中	5	特征测试、行为测试、集成测试

快速参考

关键模式——优先做好这些：

• 使用复合组件，避免属性膨胀
• 将状态就近放置在使用它的组件中
• 对复杂的 UI 工作流使用状态机
• 将容器逻辑与展示组件分离

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

• 只有一个组件读取状态，却将状态提升到 App
• 使用 context 管理快速变化的值
• 使用同时负责获取、转换和缓存的单体 Hook
• 测试实现细节，而不是行为

目录

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