react-patterns

React

概述

涵盖组件架构、性能优化、状态管理、数据获取和现代 React 19+ API。优先考虑与 React Compiler 的兼容性、Server Components，以及消除数据获取瀑布流。

适用场景： 构建 React 应用、优化性能、选择状态管理方案、实现数据获取、审查组件架构。

不适用场景： 非 React 框架、不使用 React 的纯服务端渲染、没有交互功能的静态站点。

快速参考

模式	API / 方案	要点
数据获取	use(dataPromise)	替代 useEffect+useState 获取数据的模式
表单处理	useActionState(action, init)	内置待处理状态和错误处理
乐观 UI	useOptimistic(state, updateFn)	服务端处理期间即时反馈
非紧急更新	useTransition()	将更新标记为可中断
Effect 事件	useEffectEvent(fn)	使用响应式值而不重新触发 effect
表单待处理状态	useFormStatus()	在子组件中读取父表单的待处理状态
唯一 ID	useId()	适用于水合的无障碍 ID
服务端状态	React Query / useSuspenseQuery	缓存、去重、后台重新获取
客户端状态（本地）	useState / useRef	单个组件或临时值
客户端状态（全局）	Zustand / Context	跨组件的纯客户端状态
派生状态	在渲染期间计算	切勿使用 effect 同步派生值
惰性初始化	useState(() => expensive())	避免每次渲染都进行即时计算
组件类型	Page、Feature、UI	路由入口、业务逻辑、可复用的基础组件
记忆化	首先信任 React Compiler	仅在需要时手动使用 useMemo/useCallback
ref 作为属性	函数组件上的 ref 属性	React 19 中无需 forwardRef
ref 清理	从 ref 回调返回函数	分离时运行清理函数，而不是调用 null
代码拆分	React.lazy() + Suspense	延迟加载大型组件
并行获取	Promise.all()	消除顺序等待造成的瀑布流
请求去重	React.cache()	按请求进行服务端去重
中止服务端工作	cacheSignal()	客户端断开连接时取消耗时的异步工作
资源预加载	prefetchDNS、preconnect、preload、preinit	优化组件中的资源加载
状态保留	<Activity>	隐藏 UI，同时保持状态挂载

常见错误

错误	正确做法
在 useEffect 中使用 useState 获取数据	使用 use() API 或 React Query 获取数据，并利用内置缓存
将派生值存储在状态中，并通过副作用同步	在渲染期间计算派生值；绝不要使用副作用同步状态
为所有内容都包上 useMemo 和 useCallback	优先信任 React Compiler；仅为开销较大的计算或经过 memoized 的子组件添加手动记忆化
使用会修改状态的 array.sort()	使用 array.toSorted() 进行不可变排序，避免意外重新渲染
使用 && 进行条件渲染	使用三元表达式 condition ? <Component /> : null，避免渲染 0 等假值
使用 Math.random() 或 Date 生成 ID	使用 useId() 生成适用于 hydration 的唯一标识符
将响应式值放入 effect 依赖项以读取最新值	使用 useEffectEvent 访问最新值，而不重新触发 effect
将对象字面量用作 effect 依赖项	将静态对象移到组件外部，或使用基本类型依赖项
在 React 19 项目中使用 forwardRef	直接将 ref 作为 prop 传递；forwardRef 在 React 19 中已弃用
在渲染期间修改 props 或状态	遵循 React 规则以兼容 React Compiler：保持渲染纯粹，不产生副作用

委派

• 探索组件架构并识别性能瓶颈：使用 Explore Agent 分析重新渲染、分析包大小并追踪数据获取瀑布流
• 使用恰当模式实现 React 功能：使用 Task Agent 按照 Server Component、Suspense 和 React 19 惯例构建组件
• 设计前端架构和状态管理策略：使用 Plan Agent 构建组件层级、选择状态管理方案并规划数据获取方式

如果有 shadcn-ui 技能，请将组件变体和主题相关问题委派给它。 如果有 tailwind 技能，请将实用优先的样式设计和设计令牌相关问题委派给它。 如果有 zustand 技能，请将全局客户端状态管理相关问题委派给它。

参考资料

• 组件模式、状态管理和 useEffect 决策
• 性能优化：瀑布流、包和重新渲染
• Hooks、Server Actions 和 React 19 API
• React Compiler 模式和重新渲染优化
• 服务端渲染和 React Server Components
• 反模式和故障排查指南