redux-persist 使用指南

---

1. 项目介绍

redux-persist 是一个用于 Redux 应用程序的持久化库，它允许开发者将 Redux 状态存储在本地存储（如 localStorage）或其他类型的存储中，在浏览器刷新或应用重启后仍能保持状态不变。这一特性对于提升用户体验尤其重要，因为它可以维持用户的操作上下文或者设置，实现状态的无缝衔接。

此库支持多种存储引擎，包括但不限于本地存储、sessionStorage、Realm 数据库，以及适用于 Web 扩展的特定存储。通过配置，你可以选择性地持久化特定的 Redux 子树，控制数据的合并策略，以及利用 PersistGate 来优雅地处理持久化的加载过程。

---

2. 快速启动

安装

首先，确保你的项目已经安装了 Redux 及其相关依赖。接下来，安装 redux-persist 和必要的存储适配器：

npm install redux-persist@latest
npm install --save-dev @react-redux/react-redux
# 假设你想使用localStorage作为存储
npm install redux-persist/lib/storage

配置 Redux Store

在你的 Redux 设置中集成 redux-persist：

import { createStore } from "redux";
import { persistReducer } from "redux-persist";
import storage from "redux-persist/lib/storage"; // 选用localStorage
import rootReducer from "./yourReducerFile";

const persistConfig = {
  key: "primary",
  storage,
};

const persistedReducer = persistReducer(persistConfig, rootReducer);

const store = createStore(persistedReducer);
const persistor = persistStore(store); // 创建持久化处理器

export { store, persistor };

使用PersistGate延迟渲染

在React应用的根组件处包裹 PersistGate，以等待持久化数据加载完毕后再渲染UI：

import { PersistGate } from "redux-persist/integration/react";

function App() {
  return (
    <Provider store={store}>
      <PersistGate loading={null} persistor={persistor}>
        <YourApp />
      </PersistGate>
    </Provider>
  );
}

---

3. 应用案例和最佳实践

自定义重合策略

有时你可能希望控制如何合并远程和本地状态，例如使用 autoMergeLevel2 来浅合并状态：

import { autoMergeLevel2 } from "redux-persist/lib/stateReconciler";

const persistConfig = {
  ...,
  stateReconciler: autoMergeLevel2,
};

版本控制

管理状态的版本更新，以便在升级应用时正确地迁移或清除旧数据：

const persistConfig = {
  ...,
  version: 0, // 初始化版本号
};

黑白名单控制持久化

指定哪些部分的state需要被持久化或忽略：

const persistConfig = {
  ...,
  whitelist: ['auth', 'settings'], // 持久化这些reducer
  blacklist: ['tempData'], // 忽略这个reducer
};

---

4. 典型生态项目

在实际开发中，redux-persist常与其他生态系统内的工具结合使用，比如与redux-thunk或redux-saga共同管理异步逻辑，以及与redux-toolkit一起简化Redux应用的开发流程。虽然这些组合并非直接属于redux-persist生态，但它们是构建现代Redux应用的常见搭配。

为了优化开发体验，考虑使用redux-persist-transform-filter这样的插件进行更精细的数据过滤，或者redux-persist-exclude-shallow来排除不需要深度保存的状态分支。

记住，合理选择并整合这些工具，能够帮助你构建出既高效又灵活的应用程序。

---

以上就是对 redux-persist 的简要介绍和基础使用指南，根据具体需求调整配置，可以使你的应用程序具备更加丰富和人性化的状态管理能力。