告别数据丢失：Redux持久化完全指南——从基础到高级实战-优快云博客

告别数据丢失：Redux持久化完全指南——从基础到高级实战

【免费下载链接】redux-persist persist and rehydrate a redux store 项目地址: https://gitcode.com/gh_mirrors/re/redux-persist

你是否曾遇到过这样的尴尬：用户填写了一半表单，不小心刷新页面后所有数据瞬间消失？或者应用重启后，用户的个性化设置全部归零？这些问题的根源在于Redux状态（State）存储在内存中，一旦页面刷新或应用重启就会丢失。而Redux Persist（持久化）正是解决这一痛点的利器，它能将Redux状态持久化到本地存储，并在应用重启时自动恢复。本文将带你从基础配置到高级应用，全面掌握Redux状态持久化技术，让你的应用体验提升一个档次。

一、Redux Persist核心概念与安装

Redux Persist的核心原理是通过persistReducer和persistStore两个核心API，实现Redux状态的持久化存储和自动恢复。简单来说，它就像一个"状态管家"，会在适当的时机把Redux store中的数据保存到本地存储（如localStorage、AsyncStorage等），并在应用启动时将数据从本地存储"唤醒"并重新注入到Redux store中。

1.1 快速安装

使用npm或yarn安装Redux Persist：

npm install redux-persist
# 或
yarn add redux-persist

1.2 核心文件结构

Redux Persist的核心功能主要通过以下文件实现：

src/persistReducer.ts: 创建持久化增强的reducer，负责状态的持久化和恢复逻辑。
src/persistStore.ts: 创建persistor对象，管理持久化过程的控制（如暂停、继续、清除等）。
src/storage/: 提供不同存储引擎的实现，如localStorage、sessionStorage等。
src/stateReconciler/: 提供状态合并策略，控制如何将持久化状态与初始状态合并。

二、基础配置：3步实现状态持久化

2.1 配置持久化参数（persistConfig）

首先，我们需要创建一个持久化配置对象，指定存储引擎、持久化的键名等关键信息。默认情况下，Web环境使用localStorage作为存储引擎，移动环境（如React Native）则需要显式指定存储引擎（如AsyncStorage）。

// store/configureStore.js
import { persistReducer } from 'redux-persist';
import storage from 'redux-persist/lib/storage'; // 默认使用localStorage

const persistConfig = {
  key: 'root', // 存储的键名，会在localStorage中看到类似"persist:root"的键
  storage, // 指定存储引擎
  whitelist: ['user', 'settings'], // 只持久化user和settings这两个reducer的状态
  // blacklist: ['temp'], // 不持久化temp这个reducer的状态
};

配置参数说明：

key: 存储的键名前缀，最终在localStorage中的键为persist:${key}。
storage: 指定存储引擎，如localStorage、sessionStorage等，详细可参考存储引擎文档。
whitelist: 白名单，数组中的reducer状态会被持久化。
blacklist: 黑名单，数组中的reducer状态不会被持久化。

2.2 创建持久化Reducer

使用persistReducer函数包装你的根reducer，增强其持久化能力：

// store/configureStore.js
import { createStore } from 'redux';
import rootReducer from './reducers'; // 你的根reducer

// ... 上面的persistConfig配置

const persistedReducer = persistReducer(persistConfig, rootReducer);

2.3 创建持久化Store并启动持久化

使用persistStore函数创建persistor对象，并将其与store关联：

// store/configureStore.js
import { persistStore } from 'redux-persist';

export const store = createStore(persistedReducer);
export const persistor = persistStore(store); // 启动持久化

2.4 在React应用中使用PersistGate

在React应用的根组件中，使用PersistGate组件包裹应用内容，确保在状态恢复完成之前显示加载状态：

// App.js
import { Provider } from 'react-redux';
import { PersistGate } from 'redux-persist/integration/react';
import { store, persistor } from './store/configureStore';
import LoadingScreen from './components/LoadingScreen';

function App() {
  return (
    <Provider store={store}>
      {/* loading属性指定加载状态组件，persistor是上面创建的persistor对象 */}
      <PersistGate loading={<LoadingScreen />} persistor={persistor}>
        {/* 你的应用根组件 */}
        <RootComponent />
      </PersistGate>
    </Provider>
  );
}

PersistGate的作用是延迟渲染应用内容，直到持久化状态恢复完成。这对于避免因状态未恢复而导致的UI闪烁或错误非常重要。详细用法可参考PersistGate文档。

三、进阶配置：定制你的持久化策略

3.1 状态合并策略（State Reconciler）

Redux Persist提供了三种内置的状态合并策略，用于控制如何将持久化状态（inboundState）与初始状态（originalState）合并：

autoMergeLevel1（默认）：一级深度合并，只合并顶层状态。
autoMergeLevel2：二级深度合并，合并顶层和下一级状态。
hardSet：完全替换，用持久化状态完全覆盖初始状态。

例如，使用hardSet策略：

import hardSet from 'redux-persist/lib/stateReconciler/hardSet';

const persistConfig = {
  key: 'root',
  storage,
  stateReconciler: hardSet, // 使用hardSet合并策略
};

三种策略的详细区别和实现可参考src/stateReconciler/目录下的文件。

3.2 黑白名单控制持久化范围

通过whitelist和blacklist配置，可以精确控制哪些reducer的状态需要持久化：

whitelist：只持久化数组中指定的reducer状态。
blacklist：不持久化数组中指定的reducer状态。

// 只持久化user和cart这两个reducer的状态
const persistConfig = {
  key: 'root',
  storage,
  whitelist: ['user', 'cart'], // 白名单
};

// 不持久化temp和notification这两个reducer的状态
const persistConfig = {
  key: 'root',
  storage,
  blacklist: ['temp', 'notification'], // 黑名单
};

3.3 自定义存储引擎

Redux Persist支持多种存储引擎，除了默认的localStorage，你还可以选择sessionStorage、AsyncStorage（React Native）等，甚至自定义存储引擎。

使用sessionStorage：

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

const persistConfig = {
  key: 'root',
  storage: sessionStorage, // 使用sessionStorage
};

自定义存储引擎：

只要实现了getItem、setItem、removeItem三个方法（并返回Promise），就可以作为自定义存储引擎：

const customStorage = {
  getItem: (key) => Promise.resolve(localStorage.getItem(key)),
  setItem: (key, value) => Promise.resolve(localStorage.setItem(key, value)),
  removeItem: (key) => Promise.resolve(localStorage.removeItem(key)),
};

const persistConfig = {
  key: 'root',
  storage: customStorage, // 使用自定义存储引擎
};

更多存储引擎选项可参考存储引擎文档。

四、高级应用：迁移、转换与嵌套持久化

4.1 状态迁移（Migrations）

当应用版本升级，Redux状态结构发生变化时，需要对旧版本的持久化状态进行迁移，以适应新的状态结构。Redux Persist提供了createMigrate工具来简化这一过程。

创建迁移配置：

import { createMigrate } from 'redux-persist';

// 迁移规则：版本号为键，迁移函数为值
const migrations = {
  1: (state) => {
    // 将旧版本的user.name拆分为user.firstName和user.lastName
    return {
      ...state,
      user: {
        ...state.user,
        firstName: state.user.name.split(' ')[0],
        lastName: state.user.name.split(' ')[1],
        name: undefined, // 移除旧字段
      },
    };
  },
  2: (state) => {
    // 添加新的theme字段，默认值为'light'
    return {
      ...state,
      settings: {
        ...state.settings,
        theme: 'light',
      },
    };
  },
};

// 在persistConfig中配置迁移
const persistConfig = {
  key: 'root',
  storage,
  version: 2, // 当前版本号，用于确定是否需要迁移
  migrate: createMigrate(migrations, { debug: true }), // debug为true时会打印迁移日志
};

详细迁移指南可参考迁移文档。

4.2 状态转换（Transforms）

通过createTransform，可以在状态持久化到本地存储之前（inbound）和从本地存储恢复之后（outbound）对状态进行转换，如加密、压缩、过滤等。

示例：持久化Set类型

由于JSON.stringify无法正确序列化Set类型，我们可以使用Transform将Set转换为Array进行存储，恢复时再转换回Set：

import { createTransform } from 'redux-persist';

// 创建Transform
const setTransform = createTransform(
  // inbound: 持久化前将Set转换为Array
  (inboundState, key) => {
    return {
      ...inboundState,
      tags: Array.from(inboundState.tags), // 将Set转换为Array
    };
  },
  // outbound: 恢复时将Array转换为Set
  (outboundState, key) => {
    return {
      ...outboundState,
      tags: new Set(outboundState.tags), // 将Array转换为Set
    };
  },
  { whitelist: ['post'] }, // 只对post这个reducer应用转换
);

// 在persistConfig中配置transforms
const persistConfig = {
  key: 'root',
  storage,
  transforms: [setTransform], // 应用转换
};

4.3 嵌套持久化（Nested Persists）

对于大型应用，可能需要对不同的Redux状态分支使用不同的持久化策略（如不同的存储引擎、迁移规则等）。这时可以使用嵌套持久化，即对不同的reducer分别应用persistReducer。

示例：

import { combineReducers } from 'redux';
import { persistReducer } from 'redux-persist';
import storage from 'redux-persist/lib/storage';
import sessionStorage from 'redux-persist/lib/storage/session';

// 配置userReducer的持久化（使用localStorage，长期保存）
const userPersistConfig = {
  key: 'user',
  storage,
  whitelist: ['token', 'profile'], // 只持久化token和profile
};
const persistedUserReducer = persistReducer(userPersistConfig, userReducer);

// 配置cartReducer的持久化（使用sessionStorage，会话级保存）
const cartPersistConfig = {
  key: 'cart',
  storage: sessionStorage,
};
const persistedCartReducer = persistReducer(cartPersistConfig, cartReducer);

// 合并reducer
const rootReducer = combineReducers({
  user: persistedUserReducer, // 持久化的user reducer
  cart: persistedCartReducer, // 持久化的cart reducer
  ui: uiReducer, // 不持久化的ui reducer
});

// 根持久化配置（可选，可用于进一步控制）
const rootPersistConfig = {
  key: 'root',
  storage,
  blacklist: ['user', 'cart'], // 排除已单独持久化的reducer
};
const rootPersistedReducer = persistReducer(rootPersistConfig, rootReducer);

五、API参考与最佳实践

5.1 核心API速查表

API	作用	核心参数
`persistReducer(config, reducer)`	创建持久化增强的reducer	`key`, `storage`, `version`, `migrate`, `transforms`
`persistStore(store, config)`	创建persistor对象，启动持久化	`store`, `config.manualPersist`（是否手动启动持久化）
`createMigrate(migrations, config)`	创建迁移工具	`migrations`（迁移规则）, `config.debug`（调试日志）
`createTransform(inbound, outbound, config)`	创建状态转换	`inbound`（持久化前转换）, `outbound`（恢复后转换）

完整API文档可参考API文档。

5.2 最佳实践

合理选择存储引擎：Web应用优先使用localStorage或sessionStorage；React Native使用AsyncStorage；敏感数据考虑使用加密存储引擎。
控制持久化范围：使用whitelist只持久化必要的状态，减少本地存储占用和性能开销。
版本控制与迁移：每次状态结构变更时，更新version并编写对应的迁移函数。
避免持久化大型状态：对于大型列表数据，考虑使用分页加载或专门的数据库存储，而非全部放入Redux并持久化。
调试技巧：设置debug: true可以在控制台看到Redux Persist的详细日志，帮助排查问题。

六、总结与展望

Redux Persist通过简洁的API，为Redux应用提供了强大的状态持久化能力，解决了状态易失性的痛点。从基础的配置到高级的迁移和转换，Redux Persist都提供了灵活的解决方案。随着应用复杂度的提升，合理使用嵌套持久化、迁移和转换等高级特性，可以让状态管理更加高效和可靠。

未来，Redux Persist可能会进一步优化性能，提供更多内置的转换工具，并增强与Redux Toolkit等现代Redux工具的集成。掌握Redux Persist，将为你的应用带来更流畅、更稳定的用户体验。

如果你觉得本文对你有帮助，别忘了点赞、收藏、关注三连，后续我们还将带来更多Redux生态工具的实战教程！

【免费下载链接】redux-persist persist and rehydrate a redux store 项目地址: https://gitcode.com/gh_mirrors/re/redux-persist

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考