---
name: react-state-management
when: '状态管理, 全局状态, useState, useContext, 状态共享, 跨组件通信, 全局数据, store, Context, 状态同步'
scope:
  - frontend
products:
  - '*'
id: ka-pattern-react-state-management
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 状态管理
  - 全局状态
  - useState
  - useContext
  - 状态共享
  - 跨组件通信
  - 全局数据
  - store
  - Context
  - 状态同步
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 组件内状态用 useState，禁止滥用全局 Context
- 跨组件共享状态用 Context + useReducer，禁止 props 层层传递超过 3 层
- 全局持久化状态（用户、权限）通过 Context + localStorage 提供
- API 数据必须在 custom hook 中局部管理，禁止存入全局 store
- 禁止引入 Redux/Zustand 除非项目已有约定
- 全局状态必须使用状态管理库（Zustand/Redux/Jotai），禁止通过 props drilling 传递超过 2 层
- 服务端状态必须使用 TanStack Query/SWR 管理，禁止手动 useState + useEffect 获取数据
- 状态更新必须使用不可变方式（immer/spread），禁止直接 mutate state
- 全局状态必须按领域分片（slice/store），禁止单个巨大 store 包含所有数据
- 持久化状态（如用户偏好）必须序列化到 localStorage，应用启动时恢复

## 验收项
- [AC-01] 组件内状态用 useState，未滥用 Context
- [AC-02] 全局状态通过 Context 提供
- [AC-03] API 数据在 custom hook 中管理
- [AC-04] 无 useEffect 依赖项导致的无限循环
- [AC-05] 全局状态使用状态管理库
- [AC-06] 服务端状态使用 TanStack Query
- [AC-07] 状态更新不可变方式
