zustand-patterns

Zustand 模式

使用 Zustand 5.x 进行现代状态管理——轻量、TypeScript 优先，无样板代码。

概览

• 无需 Redux 的复杂性即可管理全局状态
• 在组件间共享状态，无需逐层传递 props
• 使用 localStorage/sessionStorage 持久化状态
• 使用选择器计算/派生状态
• 使用需要中间件的状态（日志记录、开发工具、持久化）

上游文档覆盖范围（不再赘述）

Zustand 自身的文档是机制的权威来源。本技能仅在 references/ork-delta.md、rules/ 文件和检查清单中补充 OrchestKit 的差异内容。

主题	第一方来源
基本 store、create<State>()()、操作、异步操作	https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create.md
Slices 模式（拆分和组合 store）	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/slices-pattern.md
Slices 的类型定义和中间件 mutator 元组	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/advanced-typescript.md
Immer 中间件（draft 变更）	https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/immer.md
persist：partialize、version、migrate、onRehydrateStorage、存储适配器	https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md
devtools：操作名称、enabled、serialize、trace	https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/devtools.md
subscribeWithSelector 和非 React 订阅	https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/subscribe-with-selector.md
选择器和 useShallow 重渲染控制	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/prevent-rerenders-with-use-shallow.md
从 v4 迁移到 v5（createWithEqualityFn、最低 React 18）	https://github.com/pmndrs/zustand/blob/main/docs/reference/migrations/migrating-to-v5.md
SSR 和水合	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/ssr-and-hydration.md
Store 测试和重置	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/testing.md
服务端状态归属（使用 TanStack Query，而非 Zustand）	https://tanstack.com/query/latest/docs/framework/react/guides/does-this-replace-client-state

快速参考

// ✅ Create typed store with double-call pattern
const useStore = create<State>()((set, get) => ({ ... }));

// ✅ Use selectors for all state access
const count = useStore((s) => s.count);

// ✅ Use useShallow for multiple values (Zustand 5.x)
const { a, b } = useStore(useShallow((s) => ({ a: s.a, b: s.b })));

// ✅ Middleware order: immer → subscribeWithSelector → devtools → persist
create(persist(devtools(immer((set) => ({ ... })))))

// ❌ Never destructure entire store
const store = useStore(); // Re-renders on ANY change

// ❌ Never store server state (use TanStack Query instead)
const useStore = create((set) => ({ users: [], fetchUsers: async () => ... }));

关键决策

决策	选项 A	选项 B	建议
状态结构	单个 store	多个 store	在单个 store 中使用 Slices - 更便于跨 Slice 访问
嵌套更新	展开运算符	Immer 中间件	Immer 适用于深层嵌套状态（3 层及以上）
持久化	手动使用 localStorage	persist 中间件	使用带 partialize 的 persist 中间件
多个值	多个选择器	useShallow	选择 2-5 个相关值时使用 useShallow
服务端状态	Zustand	TanStack Query	使用 TanStack Query - Zustand 用于仅客户端状态
开发工具	始终启用	有条件启用	有条件启用 - enabled: process.env.NODE_ENV === 'development'

反模式与集成

禁止的模式（store 解构、派生状态、服务端状态、直接变更）以及 React Query 集成指南。

加载 Read("references/anti-patterns-and-integration.md")，查看反模式示例和 TanStack Query 分离模式。

相关技能

• react-server-components-framework - 使用 Zustand 时的 RSC 水合注意事项
• 服务端状态：https://tanstack.com/query/latest/docs/framework/react/guides/does-this-replace-client-state
• 表单状态：https://react-hook-form.com/docs/useform

能力详情

store-creation

关键词：zustand、create、store、typescript、state 解决问题：使用正确的 TypeScript 类型推断设置类型安全的 Zustand store

slices-pattern

关键词：slices、modular、split、combine、StateCreator 解决问题：将大型 store 组织为易于维护、面向特定领域的 Slice

middleware-stack

关键词：immer、persist、devtools、middleware、compose 解决的问题：按正确顺序组合中间件，实现不可变性、持久化和调试

selector-optimization

关键词：selector、useShallow、重渲染、性能、记忆化 解决的问题：通过恰当的 selector 模式避免不必要的重渲染

persistence-migration

关键词：persist、localStorage、sessionStorage、迁移、版本 解决的问题：通过版本间的架构迁移持久化状态

参考资料

使用 Read("references/<file>") 按需加载：

文件	内容
ork-delta.md	OrchestKit 专属规则：修正后的 zustand/shallow 标签、v5 最低版本、密钥处理、分级 slice 类型
anti-patterns-and-integration.md	禁止的模式和 React Query 集成

其他资源：

• 加载：Read("scripts/store-template.ts") - 可用于生产环境的 store 模板
• 加载：Read("checklists/zustand-checklist.md") - 实现检查清单