react-state

为 React 应用实现 Zustand v5 全局状态管理：v5 柯里化语法（`create()((set) => ({...}))`）、选择器模式（`useStore((s) => s.field)`）、使用 `useShallow` 处理数组/对象选择器以避免不必要的重新渲染，以及中间件组合（devtools → persist → immer；顺序会影响 TypeScript）。

介绍按领域拆分 store（auth、cart、ui、theme），而非使用一个庞大的 store；遵循 SOLID 的文件组织方式（store.ts、store.interface.ts、use-store.ts）；以及禁止的模式（持久化 auth 令牌、使用 v4 语法、跳过 useShallow）。这是 Zustand 的纯 React 版本（不涉及 App Router 请求隔离问题）。关于 Next.js App Router，请参阅 nextjs-zustand；对于服务端状态，请使用 TanStack Query，而非此技能。

React 的 Zustand

借助 React 18+ 的 useSyncExternalStore，实现精简、可扩展的状态管理。

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每个 Agent 调用一次并指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有 store 和状态模式
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 Zustand v5 文档
3. mcp__context7__query-docs - 检查中间件和 TypeScript 模式

实现完成后，运行 fuse-ai-pilot:sniper 进行验证。

---

概览

适用场景

• 管理 React 应用中的全局状态
• 需要在组件间共享状态
• 将状态持久化到 localStorage/sessionStorage
• 构建 UI 状态（模态框、侧边栏、主题、购物车）
• 用于替代复杂状态场景中的 React Context

为什么选择 Zustand v5

特性	优势
极简 API	简单的 create() 函数，无需样板代码
原生支持 React 18	使用 useSyncExternalStore，无需垫片
TypeScript 优先	通过柯里化模式实现完整类型推断
中间件栈	devtools、persist、immer 可组合使用
包体积	gzip 压缩后约 2KB，是最小的状态管理库
无需 Provider	可直接访问 store，无需 Context 包装器

---

关键规则

1. 数组/对象使用 useShallow - 避免不必要的重新渲染
2. 使用 v5 柯里化语法 - create<State>()((set) => ({...}))
3. 遵循 SOLID 路径规范 - Store 放在 modules/[feature]/src/stores/
4. 拆分 store - 每个领域使用一个 store（auth、cart、ui、theme）
5. 服务端状态另行管理 - 服务端状态使用 TanStack Query

---

SOLID 架构

模块结构

按功能模块组织 store：

• modules/cores/stores/ - 共享 store（主题、UI）
• modules/auth/src/stores/ - Auth 状态
• modules/cart/src/stores/ - 购物车状态
• modules/[feature]/src/interfaces/ - Store 类型

文件组织

文件	用途	最大行数
store.ts	使用 create() 创建 store	50
store.interface.ts	TypeScript 接口	30
use-store.ts	带选择器的自定义 Hook	20

---

核心概念

Store 创建（v5 语法）

TypeScript 类型推断需要使用双括号。柯里化模式可确保完整的类型安全。

中间件组合

按顺序叠加中间件：devtools -> persist -> immer。顺序会影响 TypeScript 类型。

选择器模式

为提升性能，始终使用 useStore((s) => s.field)。数组/对象选择器使用 useShallow。

---

参考指南

需求	参考资料
初始设置	installation.md
Store 模式	store-patterns.md
中间件	middleware.md
TypeScript	typescript.md
Slices 模式	slices.md
自动选择器	auto-selectors.md
重置状态	reset-state.md
订阅 API	subscribe-api.md
测试	testing.md
从 v4 迁移到 v5	migration-v5.md

---

最佳实践

1. 选择器模式 - 始终使用 useStore((s) => s.field) 以提升性能
2. useShallow - 对数组/对象选择器使用包装器，避免重新渲染
3. 分离 Store - 每个领域使用一个 Store（auth、cart、ui、theme）
4. 将服务器数据放在其他位置 - 使用 TanStack Query 管理服务器状态
5. 仅在开发环境中使用 DevTools - 使用 process.env 检查来包装 devtools
6. 精简持久化数据 - 只持久化必要字段，绝不持久化令牌

---

禁用模式

模式	原因	替代方案
持久化身份验证令牌	安全漏洞	httpOnly cookies
对象未使用 useShallow	过度重新渲染	useShallow(selector)
v4 语法	TypeScript 类型推断失效	v5 柯里化写法 create<T>()()
巨型单体 Store	难以维护	Slices 或分离 Store