4. Redux持久化中间件实现：redux-persist库配置

在SPA应用中，Redux Store默认存储在内存中，页面刷新后状态全部丢失。redux-persist是一个中间件库，它将Redux状态序列化到持久化存储（如localStorage、IndexedDB），并在应用启动时自动恢复，从而实现跨会话的状态保持。

4.1 核心原理：持久化与恢复流程

下图展示了redux-persist的完整工作流程，从初始加载时的rehydration到每次状态变更后的自动持久化：

4.2 安装与基础配置

使用 redux-persist 需要安装核心库及所需的存储引擎适配器：

npm install redux-persist
# 如果使用 IndexedDB，额外安装：
npm install localforage   # 统一存储引擎
# 或
npm install idb-keyval    # 轻量级 IndexedDB 封装

基础配置流程分为 5 步：

1. 导入 persistReducer 和 persistStore
2. 配置 persistConfig 对象（key、storage、白名单/黑名单）
3. 用 persistReducer 包裹 rootReducer
4. 创建 store 时调用 persistStore
5. 在组件树根节点使用 PersistGate（可选，但推荐）

import { createStore } from 'redux';
import { persistStore, persistReducer } from 'redux-persist';
import storage from 'redux-persist/lib/storage'; // 默认 localStorage
import rootReducer from './reducers';

const persistConfig = {
  key: 'root',
  storage,
  whitelist: ['user', 'cart'],      // 只持久化 user 和 cart
  blacklist: ['ui', 'temporary'],    // 排除 ui 和 temporary
};

const persistedReducer = persistReducer(persistConfig, rootReducer);
const store = createStore(persistedReducer);
const persistor = persistStore(store);

export { store, persistor };

在应用的入口文件中使用 PersistGate：

import React from 'react';
import { Provider } from 'react-redux';
import { PersistGate } from 'redux-persist/integration/react';
import { store, persistor } from './store';
import App from './App';

const Root = () => (
  <Provider store={store}>
    <PersistGate loading={<div>Loading...</div>} persistor={persistor}>
      <App />
    </PersistGate>
  </Provider>
);

4.3 白名单与黑名单过滤

redux-persist 提供两种过滤机制，控制哪些 reducer key 被持久化：

配置示例（按模块划分持久化策略）：

// 按模块拆分 persistConfig
const userPersistConfig = {
  key: 'user',
  storage,
  whitelist: ['profile', 'preferences'],  // 只持久化 profile 和 preferences
};

const cartPersistConfig = {
  key: 'cart',
  storage,
  blacklist: ['couponCodes'],  // 不持久化优惠券码
};

// 每个 reducer 独立包裹
const userPersistReducer = persistReducer(userPersistConfig, userReducer);
const cartPersistReducer = persistReducer(cartPersistConfig, cartReducer);

4.4 存储引擎切换

redux-persist 通过 storage 属性解耦持久化实现。官方和社区提供了多种存储引擎适配器：

切换为 IndexedDB（使用 localForage）：

import { createStore } from 'redux';
import { persistStore, persistReducer } from 'redux-persist';
import localforage from 'localforage';
import rootReducer from './reducers';

// 自定义 IndexedDB 配置
localforage.config({
  name: 'MyAppStore',
  storeName: 'redux_persist',
  driver: localforage.INDEXEDDB,   // 强制使用 IndexedDB
  version: 1.0,
});

const persistConfig = {
  key: 'root',
  storage: localforage,   // 传入 localforage 实例作为存储引擎
  whitelist: ['user', 'cart', 'orders'],
};

const persistedReducer = persistReducer(persistConfig, rootReducer);
const store = createStore(persistedReducer);
const persistor = persistStore(store);

切换为 sessionStorage：

import storage from 'redux-persist/lib/storage/session';

const persistConfig = {
  key: 'root',
  storage,   // sessionStorage 实例
};

4.5 高级配置：序列化与转换器

redux-persist 默认使用 JSON.stringify/parse 进行序列化。若需处理 Date、Map、Set 等特殊类型，可自定义 serialize/deserialize 或使用 transform：

import { createTransform } from 'redux-persist';

// 示例：将 Date 对象转为 ISO 字符串后再存储
const dateTransform = createTransform(
  // 出库：写入存储前
  (inboundState, key) => {
    if (key === 'user') {
      return {
        ...inboundState,
        lastLogin: inboundState.lastLogin instanceof Date
          ? inboundState.lastLogin.toISOString()
          : inboundState.lastLogin,
      };
    }
    return inboundState;
  },
  // 入库：从存储读取后
  (outboundState, key) => {
    if (key === 'user' && typeof outboundState.lastLogin === 'string') {
      return {
        ...outboundState,
        lastLogin: new Date(outboundState.lastLogin),
      };
    }
    return outboundState;
  },
  { whitelist: ['user'] }
);

const persistConfig = {
  key: 'root',
  storage,
  transforms: [dateTransform],
};

4.6 常见错误与调试

4.7 性能优化建议

• 缩小持久化范围：只持久化必要的 slice（使用 whitelist），避免存储大型临时数据。
• 使用 IndexedDB：对于超过 5MB 的状态，优先选择 IndexedDB 存储引擎，避免 localStorage 的同步写入阻塞主线程。
• 节流写入：在 reducer 中减少不必要的 dispatch，或使用 throttle 包装 persistReducer 的写入：

import { createStore } from 'redux';
import { persistStore, persistReducer } from 'redux-persist';
import storage from 'redux-persist/lib/storage';
import throttle from 'lodash/throttle';

const persistConfig = {
  key: 'root',
  storage,
  whitelist: ['user', 'settings'],
  throttle: 1000,   // 每 1 秒最多写入一次
};

const store = createStore(persistReducer(persistConfig, rootReducer));
const persistor = persistStore(store);

• 分批 rehydration：使用 persistConfig.timeout 设置超时时间（默认 5000ms），避免应用等待过久。

const persistConfig = {
  key: 'root',
  storage,
  timeout: 3000,   // 3秒超时，超时后放弃加载持久化数据
};

4.8 配置清单

配置 redux-persist 完成后，可用下方清单检查完整性：