react-patterns

React 模式

构建适用于生产环境的 React 应用的原则。

---

1. 组件设计原则

组件类型

类型	用途	状态
Server	获取数据、静态内容	无
Client	交互	useState、effects
展示型	UI 展示	仅 Props
容器型	逻辑/状态	大量状态

设计规则

• 每个组件只负责一项职责
• Props 向下传递，事件向上传递
• 优先使用组合，而非继承
• 优先使用小型、专注的组件

---

2. Hook 模式

何时提取 Hook

模式	提取时机
useLocalStorage	需要复用相同的存储逻辑
useDebounce	存在多个需要防抖的值
useFetch	存在重复的 fetch 模式
useForm	表单状态复杂

Hook 规则

• Hook 只能在顶层调用；React 的 use API 是个例外，可在组件或 Hook 内的循环/条件语句中调用（不能在 try/catch 中）；参见 use
• 每次渲染时顺序相同
• 自定义 Hook 以 "use" 开头
• 组件卸载时清理 effects

---

3. 状态管理选择

复杂度	解决方案
简单	useState、useReducer
共享的本地状态	Context
服务端状态	React Query、SWR
复杂的全局状态	Zustand、Redux Toolkit

状态放置位置

范围	位置
单个组件	useState
父子组件	将状态提升到父级
子树	Context
整个应用	全局存储

---

4. React 19 模式

新 Hook

Hook	用途
useActionState	表单提交状态
useOptimistic	乐观 UI 更新
use	在渲染期间读取资源

编译器的优势

只有在构建中安装并启用 React Compiler 时才会生效，升级到 React 19 并不会自动启用；参见 installation。

• 自动记忆化
• 减少手动使用 useMemo/useCallback
• 专注于纯组件

---

5. 组合模式

复合组件

• 父组件提供上下文
• 子组件使用上下文
• 灵活的基于插槽的组合
• 示例：Tabs、Accordion、Dropdown

Render Props 与 Hook

使用场景	优先选择
可复用逻辑	自定义 Hook
渲染灵活性	Render Props
横切关注点	高阶组件

---

6. 性能原则

何时优化

信号	操作
渲染缓慢	先进行性能分析
列表很大	使用虚拟化
计算开销大	useMemo
回调稳定	useCallback

优化顺序

1. 确认是否真的很慢
2. 使用 DevTools 进行性能分析
3. 找出瓶颈
4. 有针对性地修复

---

7. 错误处理

错误边界的使用

范围	放置位置
整个应用	根级别
功能	路由/功能级别
组件	包裹有风险的组件

错误恢复

• 显示备用 UI
• 记录错误
• 提供重试选项
• 保留用户数据

---

8. TypeScript 模式

Props 类型定义

模式	用途
Interface	组件 Props
Type	联合类型、复杂类型
Generic	可复用组件

常见类型

需求	类型
子节点	ReactNode
事件处理器	MouseEventHandler
Ref	RefObject

---

9. 测试原则

级别	重点
单元测试	纯函数、Hook
集成测试	组件行为
E2E	用户流程

测试优先级

• 用户可见的行为
• 边界情况
• 错误状态
• 无障碍性

---

10. 反模式

❌ 不要	✅ 应该
层层传递 Props	使用 Context
巨型组件	拆分为更小的组件
什么都用 useEffect	在渲染期间推导值；仅将 effects 用于外部同步，并且只在支持的框架中使用服务端组件
过早优化	先进行性能分析
用索引作为 key	使用稳定的唯一 ID

---

11. 文件结构

将此图片作为参考，优化项目的文件结构

---

请记住： React 重在组合。构建小型组件，并谨慎组合。

适用场景

当需要执行概述中描述的工作流或操作时，可使用此技能。

示例

用户请求：

在此任务中使用 @react-patterns：现代 React 模式和原则。

限制

• 仅当任务与上述范围明确匹配时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请暂停并请求澄清。