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 token、v4 语法、跳过 useShallow）。这是 Zustand 的纯 React 版本（没有 App Router 请求隔离方面的顾虑）——Next.js App Router 请参阅 nextjs-zustand；服务端状态则请使用 TanStack Query，而不是此技能。

Zustand for React

使用 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，无需 shim
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（theme、ui）
• modules/auth/src/stores/ - Auth 状态
• modules/cart/src/stores/ - Cart 状态
• modules/[feature]/src/interfaces/ - Store 类型

文件组织

文件	用途
store.ts	使用 create() 创建 store（最多 40 行，owner 规则）
store.interface.ts	TypeScript 接口
use-store.ts	带选择器的自定义 Hook

---

核心概念

创建 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
Subscribe 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. 对 persist 使用 Partialize - 仅持久化必要字段，绝不持久化令牌

---

禁止的模式

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