Easy-Peasy 从 V3 升级指南：新特性与重大变更解析

Easy-Peasy 从 V3 升级指南：新特性与重大变更解析

easy-peasy Vegetarian friendly state for React 项目地址: https://gitcode.com/gh_mirrors/ea/easy-peasy

前言

Easy-Peasy 是一个基于 Redux 的轻量级状态管理库，它通过简化 Redux 的复杂概念，让开发者能够更轻松地管理应用状态。本文将详细介绍从 V3 版本升级时需要注意的重要变更和新特性。

废弃功能

废弃 createComponentStore API

createComponentStore API 由于设计上较为冗长且功能有限，已被标记为废弃状态，并将在下一个主要版本中移除。作为替代方案，团队引入了全新的 useLocalStore hook。

重要新特性

1. useLocalStore Hook

useLocalStore 是 createComponentStore 的现代化替代方案，它为组件级别的状态管理提供了更简洁的 API。这个 hook 可以看作是 React 原生 useState 和 useReducer 的增强版。

function CounterComponent() {
  const [state, actions] = useLocalStore(() => ({
    count: 0,
    increment: action((_state) => {
      _state.count += 1;
    }),
  }));

  return (
    <div>
      {state.count}
      <button onClick={() => actions.increment()}>+</button>
    </div>
  );
}

2. effectOn 模型 API

effectOn 是一个强大的新 API，它允许你在模型中声明一个 effect，当目标状态发生变化时自动执行。这个功能非常适合处理副作用逻辑，如数据持久化或 API 调用。

const todosModel = {
  items: [],
  saving: false,
  setSaving: action((state, payload) => {
    state.saving = payload;
  }),
  onItemsChanged: effectOn(
    [(state) => state.items],
    async (actions, change) => {
      const [items] = change.current;
      actions.setSaving(true);
      await todosService.save(items);
      actions.setSaving(false);
    }
  ),
};

3. TypeScript 泛型支持

新版本解决了 TypeScript 中泛型状态的问题。现在你可以通过 Generic 类型和 generic 辅助函数来定义和使用泛型状态。

interface StoreModel<K> {
  data: Generic<K>;
  updateData: Action<StoreModel<K>, K>;
}

const numberStoreModel: StoreModel<number> = {
  data: generic(1337),
  updateData: action((state, payload) => {
    state.data = payload;
  }),
};

持久化改进

1. 持久化 API 增强

改进了 store 实例上的持久化 API，现在可以：

• 在应用导航离开前刷新持久化数据
• 等待持久化数据重新水合后再渲染应用

2. 动态模型持久化

修复了动态添加模型(store.addModel)时的持久化问题，并新增了 resolveRehydration 方法来等待异步存储引擎完成数据恢复。

const { resolveRehydration } = store.addModel('products', productsModel);
resolveRehydration().then(() => {
  console.log('数据恢复完成');
});

3. 合并策略修复

修复了 merge 和 mergeDeep 策略在模型结构演变时可能出现的数据类型对齐问题。现在系统会检查模型和持久化状态的数据类型是否匹配，确保类型安全。

TypeScript 改进

1. 移除了模型深度限制（原限制为6层）
2. 修复了类实例在状态中的类型推断问题
3. 优化了动作映射器，不再显示状态属性
4. 修正了计算属性状态解析器的类型推断
5. 改进了编辑器智能提示体验

其他重要变更

1. 用官方 immer 替代了 immer-peasy，得益于官方对计算属性的支持
2. 调整了内部 redux-thunk 绑定顺序，允许用户自定义中间件优先执行
3. 使用 microbundle 替代 rollup 进行库打包，减小了包体积

已知问题

计算属性可选标记问题

由于类型系统限制，计算属性不能直接使用 ? 标记为可选。替代方案是明确声明返回类型可能为 undefined：

interface StoreModel {
  products: Product[];
  totalPrice: Computed<StoreModel, number | undefined>;
}

升级建议

1. 首先替换所有 createComponentStore 为 useLocalStore
2. 检查项目中是否存在深度超过6层的模型结构（虽然限制已移除，但建议保持合理层级）
3. 对于使用泛型的模型，应用新的 Generic 类型方案
4. 考虑使用 effectOn 重构现有的副作用逻辑
5. 对于持久化场景，推荐使用 mergeDeep 策略并测试数据恢复行为

通过以上改进，Easy-Peasy V3.4 提供了更强大、更类型安全的状态管理体验，同时保持了库的简洁性和易用性。

easy-peasy Vegetarian friendly state for React 项目地址: https://gitcode.com/gh_mirrors/ea/easy-peasy