Zustand 在大型项目中的状态管理架构Store 拆分、中间件与持久化方案Zustand 以极简的 API 设计和出色的 TypeScript 类型推断能力在 React 生态中快速获得认可。当项目规模从个人项目扩展到数十人协作的大型应用时Store 的组织方式、中间件组合和持久化策略就成为架构决策中的关键问题。一、Store 拆分的原则与模式Zustand 官方推荐的模式是小而多的 Store 拆分而非 Redux 式的单一大 Store。但拆分粒度需要根据业务耦合度来判断。1.1 拆分原则按业务域拆分每个独立的业务模块用户、订单、商品对应一个 Store。按变化频率拆分高频更新的状态表单输入、播放进度与低频状态用户信息、配置项分离减少不必要的重渲染。服务端状态外移服务端缓存、请求状态交给 TanStack Query / SWR 管理Zustand 只管理纯客户端状态。1.2 原子化 Store 示例// stores/auth.store.ts — 认证相关的独立 Store import { create } from zustand; interface User { id: string; nickname: string; avatar: string; role: user | admin; } interface AuthState { user: User | null; token: string | null; isAuthenticated: boolean; // Actions login: (token: string, user: User) void; logout: () void; updateUser: (partial: PartialUser) void; } export const useAuthStore createAuthState()((set) ({ user: null, token: null, isAuthenticated: false, login: (token, user) set({ token, user, isAuthenticated: true, }), logout: () set({ token: null, user: null, isAuthenticated: false, }), updateUser: (partial) set((state) ({ user: state.user ? { ...state.user, ...partial } : null, })), }));// stores/ui.store.ts — UI 状态独立管理 import { create } from zustand; type Theme light | dark | system; interface UIState { theme: Theme; sidebarCollapsed: boolean; globalLoading: boolean; toasts: Array{ id: string; message: string; type: info | error | success }; setTheme: (theme: Theme) void; toggleSidebar: () void; setGlobalLoading: (loading: boolean) void; addToast: (message: string, type?: info | error | success) void; removeToast: (id: string) void; } let toastCounter 0; export const useUIStore createUIState()((set) ({ theme: system, sidebarCollapsed: false, globalLoading: false, toasts: [], setTheme: (theme) set({ theme }), toggleSidebar: () set((s) ({ sidebarCollapsed: !s.sidebarCollapsed })), setGlobalLoading: (globalLoading) set({ globalLoading }), addToast: (message, type info) set((state) ({ toasts: [ ...state.toasts, { id: toast_${toastCounter}, message, type }, ], })), removeToast: (id) set((state) ({ toasts: state.toasts.filter((t) t.id ! id), })), }));二、中间件的组合使用Zustand 的中间件系统通过函数组合实现常用的有persist持久化、devtools调试、immer不可变更新。2.1 中间件叠加顺序中间件的叠加顺序会影响行为——devtools应放在最外层以捕获所有状态变化import { create } from zustand; import { persist, devtools } from zustand/middleware; import { immer } from zustand/middleware/immer; interface PreferencesState { language: string; fontSize: number; codeLineWrap: boolean; autoSave: boolean; setLanguage: (lang: string) void; setFontSize: (size: number) void; toggleCodeLineWrap: () void; } export const usePreferencesStore createPreferencesState()( // 1. devtools 最外层捕获所有 action devtools( // 2. persist 持久化层 persist( // 3. immer 不可变更新层 immer((set) ({ language: zh-CN, fontSize: 14, codeLineWrap: true, autoSave: true, setLanguage: (language) set((state) { state.language language; }), setFontSize: (fontSize) set((state) { state.fontSize fontSize; }), toggleCodeLineWrap: () set((state) { state.codeLineWrap !state.codeLineWrap; }), })), { name: preferences-storage, // localStorage key // 选择性持久化只持久化偏好不持久化中间状态 partialize: (state) ({ language: state.language, fontSize: state.fontSize, codeLineWrap: state.codeLineWrap, autoSave: state.autoSave, }), } ), { name: PreferencesStore } ) );2.2 自定义中间件日志记录import { StateCreator, StoreMutatorIdentifier } from zustand; /** * 自定义日志中间件 * 仅在开发环境打印状态变更前后的差异 */ interface LoggerConfig { enabled: boolean; /** 需要记录的 action 名称过滤器 */ actionFilter?: string[]; } const logger T extends object( config: LoggerConfig { enabled: import.meta.env.DEV } ) Mos extends [StoreMutatorIdentifier, unknown][] [], ( fn: StateCreatorT, [], Mos ): StateCreatorT, [], Mos (set, get, api) fn( (partial, replace, action) { const prevState get(); set(partial, replace, action); if (!config.enabled) return; const nextState get(); const actionName (action as string) || anonymous; // 检查 action 是否需要记录 if ( config.actionFilter !config.actionFilter.includes(actionName) ) { return; } // 计算变更的字段 const changes Object.keys(nextState).reduceRecordstring, unknown( (acc, key) { if (prevState[key as keyof typeof prevState] ! nextState[key as keyof typeof nextState]) { acc[key] { from: prevState[key as keyof typeof prevState], to: nextState[key as keyof typeof nextState], }; } return acc; }, {} ); if (Object.keys(changes).length 0) { console.group([Zustand] ${actionName}); console.log(变更字段:, changes); console.groupEnd(); } }, get, api );三、持久化方案的深度定制3.1 多存储后端支持import { persist, createJSONStorage, PersistStorage } from zustand/middleware; /** * 创建 IndexedDB 存储适配器 * 适用于大体积状态存储localStorage 有 5MB 限制 */ function createIndexedDBStorageT(): PersistStorageT | undefined { // 仅在浏览器环境创建 if (typeof window undefined) return undefined; const DB_NAME zustand-persist; const STORE_NAME state; let db: IDBDatabase | null null; return createJSONStorage(() ({ getItem: async (name: string) { return new Promisestring | null((resolve, reject) { const request indexedDB.open(DB_NAME, 1); request.onupgradeneeded () { request.result.createObjectStore(STORE_NAME); }; request.onsuccess () { db request.result; const transaction db.transaction(STORE_NAME, readonly); const store transaction.objectStore(STORE_NAME); const getRequest store.get(name); getRequest.onsuccess () resolve(getRequest.result ?? null); getRequest.onerror () reject(getRequest.error); }; request.onerror () reject(request.error); }); }, setItem: async (name: string, value: string) { return new Promisevoid((resolve, reject) { const request indexedDB.open(DB_NAME, 1); request.onsuccess () { db request.result; const transaction db.transaction(STORE_NAME, readwrite); const store transaction.objectStore(STORE_NAME); store.put(value, name); transaction.oncomplete () resolve(); transaction.onerror () reject(transaction.error); }; request.onerror () reject(request.error); }); }, removeItem: async (name: string) { return new Promisevoid((resolve, reject) { if (!db) { resolve(); // 未初始化则跳过 return; } const transaction db.transaction(STORE_NAME, readwrite); const store transaction.objectStore(STORE_NAME); store.delete(name); transaction.oncomplete () resolve(); transaction.onerror () reject(transaction.error); }); }, })); }3.2 版本迁移策略状态结构会随迭代而变化需要声明式迁移interface PreferencesStateV1 { theme: light | dark; } interface PreferencesStateV2 { theme: light | dark | system; fontSize: number; } export const usePreferencesStore createPreferencesStateV2()( persist( (set) ({ theme: system, fontSize: 14, setTheme: (theme: PreferencesStateV2[theme]) set({ theme }), setFontSize: (fontSize: number) set({ fontSize }), }), { name: preferences-v2, version: 2, // 当前版本 migrate: (persisted, version) { // 从 v1 迁移到 v2 if (version 1) { const v1 persisted as PreferencesStateV1; return { theme: v1.theme, fontSize: 14, // 新增字段的默认值 }; } return persisted as PreferencesStateV2; }, } ) );四、大型项目中的架构建议4.1 精确订阅避免重复渲染// 避免整个对象订阅任何字段变化都触发重渲染 const { user, token } useAuthStore(); // 不推荐 // 推荐按需订阅 const user useAuthStore((state) state.user); const token useAuthStore((state) state.token); // 使用 shallow 比较避免对象引用变化导致的渲染 import { useShallow } from zustand/react/shallow; const { width, height } useEditorStore( useShallow((state) ({ width: state.canvasWidth, height: state.canvasHeight, })) );4.2 跨 Store 通信Zustand 不提供类似 Redux 的全局 dispatch跨 Store 交互应在组件或自定义 Hook 层处理/** * 跨 Store 组合 Hook登录后重置购物车 */ export function useLoginFlow() { const login useAuthStore((s) s.login); const resetCart useCartStore((s) s.reset); return async (credentials: { username: string; password: string }) { const user await authAPI.login(credentials); login(user.token, user.profile); resetCart(); // 登录成功后清空购物车 }; }五、总结Zustand 在大型项目中的架构核心Store 拆分按业务域和变化频率拆分为小而独立的 Store。中间件组合devtools外层捕获变更persist中层持久化immer内层简化更新。持久化定制根据数据体量选择 localStorage 或 IndexedDB配置版本迁移策略。渲染优化使用精确 Selector 和useShallow减少不必要的重渲染。跨 Store 通信在组件层或自定义 Hook 层组合多个 Store 的 action保持 Store 本身的独立性。
Zustand 在大型项目中的状态管理架构Store 拆分、中间件与持久化方案Zustand 以极简的 API 设计和出色的 TypeScript 类型推断能力在 React 生态中快速获得认可。当项目规模从个人项目扩展到数十人协作的大型应用时Store 的组织方式、中间件组合和持久化策略就成为架构决策中的关键问题。一、Store 拆分的原则与模式Zustand 官方推荐的模式是小而多的 Store 拆分而非 Redux 式的单一大 Store。但拆分粒度需要根据业务耦合度来判断。1.1 拆分原则按业务域拆分每个独立的业务模块用户、订单、商品对应一个 Store。按变化频率拆分高频更新的状态表单输入、播放进度与低频状态用户信息、配置项分离减少不必要的重渲染。服务端状态外移服务端缓存、请求状态交给 TanStack Query / SWR 管理Zustand 只管理纯客户端状态。1.2 原子化 Store 示例// stores/auth.store.ts — 认证相关的独立 Store import { create } from zustand; interface User { id: string; nickname: string; avatar: string; role: user | admin; } interface AuthState { user: User | null; token: string | null; isAuthenticated: boolean; // Actions login: (token: string, user: User) void; logout: () void; updateUser: (partial: PartialUser) void; } export const useAuthStore createAuthState()((set) ({ user: null, token: null, isAuthenticated: false, login: (token, user) set({ token, user, isAuthenticated: true, }), logout: () set({ token: null, user: null, isAuthenticated: false, }), updateUser: (partial) set((state) ({ user: state.user ? { ...state.user, ...partial } : null, })), }));// stores/ui.store.ts — UI 状态独立管理 import { create } from zustand; type Theme light | dark | system; interface UIState { theme: Theme; sidebarCollapsed: boolean; globalLoading: boolean; toasts: Array{ id: string; message: string; type: info | error | success }; setTheme: (theme: Theme) void; toggleSidebar: () void; setGlobalLoading: (loading: boolean) void; addToast: (message: string, type?: info | error | success) void; removeToast: (id: string) void; } let toastCounter 0; export const useUIStore createUIState()((set) ({ theme: system, sidebarCollapsed: false, globalLoading: false, toasts: [], setTheme: (theme) set({ theme }), toggleSidebar: () set((s) ({ sidebarCollapsed: !s.sidebarCollapsed })), setGlobalLoading: (globalLoading) set({ globalLoading }), addToast: (message, type info) set((state) ({ toasts: [ ...state.toasts, { id: toast_${toastCounter}, message, type }, ], })), removeToast: (id) set((state) ({ toasts: state.toasts.filter((t) t.id ! id), })), }));二、中间件的组合使用Zustand 的中间件系统通过函数组合实现常用的有persist持久化、devtools调试、immer不可变更新。2.1 中间件叠加顺序中间件的叠加顺序会影响行为——devtools应放在最外层以捕获所有状态变化import { create } from zustand; import { persist, devtools } from zustand/middleware; import { immer } from zustand/middleware/immer; interface PreferencesState { language: string; fontSize: number; codeLineWrap: boolean; autoSave: boolean; setLanguage: (lang: string) void; setFontSize: (size: number) void; toggleCodeLineWrap: () void; } export const usePreferencesStore createPreferencesState()( // 1. devtools 最外层捕获所有 action devtools( // 2. persist 持久化层 persist( // 3. immer 不可变更新层 immer((set) ({ language: zh-CN, fontSize: 14, codeLineWrap: true, autoSave: true, setLanguage: (language) set((state) { state.language language; }), setFontSize: (fontSize) set((state) { state.fontSize fontSize; }), toggleCodeLineWrap: () set((state) { state.codeLineWrap !state.codeLineWrap; }), })), { name: preferences-storage, // localStorage key // 选择性持久化只持久化偏好不持久化中间状态 partialize: (state) ({ language: state.language, fontSize: state.fontSize, codeLineWrap: state.codeLineWrap, autoSave: state.autoSave, }), } ), { name: PreferencesStore } ) );2.2 自定义中间件日志记录import { StateCreator, StoreMutatorIdentifier } from zustand; /** * 自定义日志中间件 * 仅在开发环境打印状态变更前后的差异 */ interface LoggerConfig { enabled: boolean; /** 需要记录的 action 名称过滤器 */ actionFilter?: string[]; } const logger T extends object( config: LoggerConfig { enabled: import.meta.env.DEV } ) Mos extends [StoreMutatorIdentifier, unknown][] [], ( fn: StateCreatorT, [], Mos ): StateCreatorT, [], Mos (set, get, api) fn( (partial, replace, action) { const prevState get(); set(partial, replace, action); if (!config.enabled) return; const nextState get(); const actionName (action as string) || anonymous; // 检查 action 是否需要记录 if ( config.actionFilter !config.actionFilter.includes(actionName) ) { return; } // 计算变更的字段 const changes Object.keys(nextState).reduceRecordstring, unknown( (acc, key) { if (prevState[key as keyof typeof prevState] ! nextState[key as keyof typeof nextState]) { acc[key] { from: prevState[key as keyof typeof prevState], to: nextState[key as keyof typeof nextState], }; } return acc; }, {} ); if (Object.keys(changes).length 0) { console.group([Zustand] ${actionName}); console.log(变更字段:, changes); console.groupEnd(); } }, get, api );三、持久化方案的深度定制3.1 多存储后端支持import { persist, createJSONStorage, PersistStorage } from zustand/middleware; /** * 创建 IndexedDB 存储适配器 * 适用于大体积状态存储localStorage 有 5MB 限制 */ function createIndexedDBStorageT(): PersistStorageT | undefined { // 仅在浏览器环境创建 if (typeof window undefined) return undefined; const DB_NAME zustand-persist; const STORE_NAME state; let db: IDBDatabase | null null; return createJSONStorage(() ({ getItem: async (name: string) { return new Promisestring | null((resolve, reject) { const request indexedDB.open(DB_NAME, 1); request.onupgradeneeded () { request.result.createObjectStore(STORE_NAME); }; request.onsuccess () { db request.result; const transaction db.transaction(STORE_NAME, readonly); const store transaction.objectStore(STORE_NAME); const getRequest store.get(name); getRequest.onsuccess () resolve(getRequest.result ?? null); getRequest.onerror () reject(getRequest.error); }; request.onerror () reject(request.error); }); }, setItem: async (name: string, value: string) { return new Promisevoid((resolve, reject) { const request indexedDB.open(DB_NAME, 1); request.onsuccess () { db request.result; const transaction db.transaction(STORE_NAME, readwrite); const store transaction.objectStore(STORE_NAME); store.put(value, name); transaction.oncomplete () resolve(); transaction.onerror () reject(transaction.error); }; request.onerror () reject(request.error); }); }, removeItem: async (name: string) { return new Promisevoid((resolve, reject) { if (!db) { resolve(); // 未初始化则跳过 return; } const transaction db.transaction(STORE_NAME, readwrite); const store transaction.objectStore(STORE_NAME); store.delete(name); transaction.oncomplete () resolve(); transaction.onerror () reject(transaction.error); }); }, })); }3.2 版本迁移策略状态结构会随迭代而变化需要声明式迁移interface PreferencesStateV1 { theme: light | dark; } interface PreferencesStateV2 { theme: light | dark | system; fontSize: number; } export const usePreferencesStore createPreferencesStateV2()( persist( (set) ({ theme: system, fontSize: 14, setTheme: (theme: PreferencesStateV2[theme]) set({ theme }), setFontSize: (fontSize: number) set({ fontSize }), }), { name: preferences-v2, version: 2, // 当前版本 migrate: (persisted, version) { // 从 v1 迁移到 v2 if (version 1) { const v1 persisted as PreferencesStateV1; return { theme: v1.theme, fontSize: 14, // 新增字段的默认值 }; } return persisted as PreferencesStateV2; }, } ) );四、大型项目中的架构建议4.1 精确订阅避免重复渲染// 避免整个对象订阅任何字段变化都触发重渲染 const { user, token } useAuthStore(); // 不推荐 // 推荐按需订阅 const user useAuthStore((state) state.user); const token useAuthStore((state) state.token); // 使用 shallow 比较避免对象引用变化导致的渲染 import { useShallow } from zustand/react/shallow; const { width, height } useEditorStore( useShallow((state) ({ width: state.canvasWidth, height: state.canvasHeight, })) );4.2 跨 Store 通信Zustand 不提供类似 Redux 的全局 dispatch跨 Store 交互应在组件或自定义 Hook 层处理/** * 跨 Store 组合 Hook登录后重置购物车 */ export function useLoginFlow() { const login useAuthStore((s) s.login); const resetCart useCartStore((s) s.reset); return async (credentials: { username: string; password: string }) { const user await authAPI.login(credentials); login(user.token, user.profile); resetCart(); // 登录成功后清空购物车 }; }五、总结Zustand 在大型项目中的架构核心Store 拆分按业务域和变化频率拆分为小而独立的 Store。中间件组合devtools外层捕获变更persist中层持久化immer内层简化更新。持久化定制根据数据体量选择 localStorage 或 IndexedDB配置版本迁移策略。渲染优化使用精确 Selector 和useShallow减少不必要的重渲染。跨 Store 通信在组件层或自定义 Hook 层组合多个 Store 的 action保持 Store 本身的独立性。
