React

面向生产环境的 React 工程实践。该技能将彻底改变你构建 React 应用的方式——从组件架构到部署全流程。

适用场景

• 构建 React 组件、页面或功能模块
• 实现状态管理（useState、Context、Zustand、TanStack Query）
• 使用 React 19（服务端组件、use()、Actions）
• 性能优化（memo、lazy、Suspense）
• 调试渲染问题、无限循环、闭包过期等
• 搭建项目架构与目录结构

架构决策

编写代码前，请先明确以下决策：

规则：服务端状态（API 数据）与客户端状态（UI 状态）是完全不同的两类状态，严禁混用。

组件规范

// ✅ 正确模式
export function UserCard({ user, onEdit }: UserCardProps) {
  // 1. Hook 声明置于最前（始终如此）
  const [isOpen, setIsOpen] = useState(false)
  
  // 2. 衍生状态（禁止使用 useEffect 计算）
  const fullName = `${user.firstName} ${user.lastName}`
  
  // 3. 事件处理器
  const handleEdit = useCallback(() => onEdit(user.id), [onEdit, user.id])
  
  // 4. 提前返回
  if (!user) return null
  
  // 5. JSX（最多 50 行）
  return (...)
}

状态管理

是否来自 API？
├─ 是 → 使用 TanStack Query（禁止使用 Redux 或 Zustand）
└─ 否 → 是否在多个组件间共享？
    ├─ 是 → 使用 Zustand（简单场景）或 Context（变更频率极低时）
    └─ 否 → 使用 useState

TanStack Query（服务端状态）

// 查询键工厂 —— 防止拼写错误
export const userKeys = {
  all: ['users'] as const,
  detail: (id: string) => [...userKeys.all, id] as const,
}

export function useUser(id: string) {
  return useQuery({
    queryKey: userKeys.detail(id),
    queryFn: () => fetchUser(id),
    staleTime: 5 * 60 * 1000, // 5 分钟
  })
}

Zustand（客户端状态）

// 轻量级 Store，每个 Store 关注单一职责
export const useUIStore = create()((set) => ({
  sidebarOpen: true,
  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
}))

// 务必使用 selector —— 避免不必要的重渲染
const isOpen = useUIStore((s) => s.sidebarOpen)

React 19

服务端组件（Next.js App Router 默认启用）

// 服务端组件 —— 在服务端执行，零 JS 下发至客户端
async function ProductList() {
  const products = await db.products.findMany() // 直接访问数据库
  return 
{products.map(p => )}
}

// 客户端组件 —— 必须添加 'use client' 指令
'use client'
function AddToCartButton({ productId }: { productId: string }) {
  const [loading, setLoading] = useState(false)
  return  addToCart(productId)}>Add
}

use() Hook

// 在渲染中读取 Promise（配合 Suspense）
function Comments({ promise }: { promise: Promise }) {
  const comments = use(promise) // 暂停渲染直至 Promise 解析完成
  return 
{comments.map(c => 
{c.text}
)}
}

useActionState（表单）

'use client'
async function submitAction(prev: State, formData: FormData) {
  'use server'
  // ... 服务端逻辑
  return { success: true }
}

function Form() {
  const [state, action, pending] = useActionState(submitAction, {})
  return (
    

      
      {pending ? 'Saving...' : 'Save'}
      {state.error && 
{state.error}
}
    
  )
}

性能优化

React Compiler（React 19+）：自动 memo 化。请移除所有手动的 memo/useMemo/useCallback。

常见陷阱

渲染陷阱

// ❌ 当 count 为 0 时渲染字符串 "0"
{count && }

// ✅ 显式布尔判断
{count > 0 && }

// ❌ 直接修改原数组 —— React 无法检测到变化
array.push(item)
setArray(array)

// ✅ 创建新引用
setArray([...array, item])

// ❌ 每次渲染都生成新 key —— 导致组件被销毁重建


// ✅ 使用稳定 key

Hook 陷阱

// ❌ useEffect 不支持异步函数
useEffect(async () => { ... }, [])

// ✅ 在内部定义并调用异步函数
useEffect(() => {
  async function load() { ... }
  load()
}, [])

// ❌ 缺少清理逻辑 —— 可能导致内存泄漏
useEffect(() => {
  const sub = subscribe()
}, [])

// ✅ 返回清理函数
useEffect(() => {
  const sub = subscribe()
  return () => sub.unsubscribe()
}, [])

// ❌ 将对象放入依赖数组 —— 每次渲染都会触发
useEffect(() => { ... }, [{ id: 1 }])

// ✅ 提取基础类型或使用 memoize
useEffect(() => { ... }, [id])

数据获取陷阱

// ❌ 串行请求 —— 性能差
const users = await fetchUsers()
const orders = await fetchOrders()

// ✅ 并行请求
const [users, orders] = await Promise.all([fetchUsers(), fetchOrders()])

// ❌ 竞态条件 —— 无中止机制
useEffect(() => {
  fetch(url).then(setData)
}, [url])

// ✅ 使用 AbortController
useEffect(() => {
  const controller = new AbortController()
  fetch(url, { signal: controller.signal }).then(setData)
  return () => controller.abort()
}, [url])

AI 易犯错误（需规避）

AI 助手在 React 开发中常犯的典型错误：

速查手册

常用 Hook

推荐目录结构

src/
├── app/                 # 路由（Next.js）
├── features/            # 功能模块
│   └── auth/
│       ├── components/  # 功能相关组件
│       ├── hooks/       # 功能相关 Hook
│       ├── api/         # API 请求封装
│       └── index.ts     # 公共导出入口
├── shared/              # 跨功能复用
│   ├── components/ui/   # Button、Input 等通用组件
│   └── hooks/           # useDebounce 等通用 Hook
└── providers/           # Context Provider

初始化配置

首次配置请参阅 setup.md。项目跟踪使用 memory-template.md。

核心规则

1. 服务端状态 ≠ 客户端状态 —— API 数据交由 TanStack Query 管理，UI 状态使用 useState/Zustand；二者严禁混用。
2. 仅使用具名导出 —— 使用 export function X，禁止 export default；保障安全重构能力。
3. 先就近共置，再按需提升 —— 初始将状态放在使用处附近；仅当多处需要时才提取提升。
4. 禁止用 useEffect 计算衍生状态 —— 应内联计算：const total = items.reduce(...)；useEffect 仅用于副作用。
5. 始终使用稳定 key —— 动态列表必须使用 item.id，禁止使用 index。
6. JSX 最多 50 行 —— 超出即拆分为子组件；单文件上限为 300 行。
7. TypeScript 启用 strict: true —— 禁止使用 any，禁用隐式 null/undefined；在编译期捕获类型错误。

关联技能

如用户确认，可通过 clawhub install 安装：

• frontend-design-ultimate —— 使用 React + Tailwind 构建完整 UI
• typescript —— TypeScript 最佳实践与严格配置
• nextjs —— Next.js App Router 与部署实践
• testing —— 使用 Testing Library 测试 React 组件

反馈

• 若本技能有用：clawhub star react
• 保持更新：clawhub sync