@modern-js/main-doc 2.1.0 → 2.2.0

package/zh/guides/topic-detail/model/model-communicate.mdx

@@ -0,0 +1,220 @@
+---
+sidebar_position: 7
+title: Model 通信
+---
+# Model 通信
+
+Model 通信，既指不同 Model 间的通信，也指同一个 Model 内部 Effects、Actions 之间的通信。
+
+## Model 间通信
+
+Model 之间不是孤立的，是可以进行通信的。主要分为两种场景：
+
+1. 在 Model 中访问其它 Model 的 State 和 Actions。
+2. 在 Model 中监听其它 Model 变化。
+
+这里将 [快速上手](/guides/topic-detail/model/quick-start) 一节的简单计数器应用改造成一个可设置步频的计数器应用。可以通过设置步频，从而影响每次计数器增加的幅度。
+
+我们抽象出两个 Model，分别为 `stepModel`（步频）、`counterModel`（计数器）：
+
+```ts
+import { model } from '@modern-js/runtime/model';
+
+const stepModel = model('step').define({
+  state: 1,
+});
+
+const counterModel = model('count').define((context, { use, onMount }) => {
+  const [, , subscribeStep] = use(stepModel);
+
+  onMount(() => {
+    return subscribeStep(() => {
+      console.log(
+        `Subscribe in counterModel: stepModel change to ${use(stepModel)[0]}`,
+      );
+    });
+  });
+
+  return {
+    state: {
+      value: 1,
+    },
+    actions: {
+      add(state) {
+        const step = use(stepModel)[0];
+        state.value += step;
+      },
+    },
+  };
+});
+
+export { stepModel, counterModel };
+```
+
+`stepModel` 只声明一个 `state`，初始值为 1。
+
+`counterModel` 通过 `use` 函数加载 `stepModel`，拿到返回的 `subscribeStep` 函数，用来监听 `stepModel` 状态的变更。 `onMount` 是 Model 挂载完成后的钩子函数，`counterModel` 挂载完成后开始订阅 `stepModel` 状态的变更，打印出 `stepModel` 的最新值。
+
+`counterModel` 通过 `use` 函数访问 `stepModel`，在 `add` 里可以获取到当前 `stepModel` 的值（步频），以此值来做自增。
+
+:::caution 注意
+当需要访问其他 Model 的 State 时，必须要在当前 Actions 或 Effects 函数（本例中对应 `add` 函数 ）真正执行的阶段调用 `use`，以保证获取的 State 是最新值。因此，我们虽然在 `define` 的回调函数中也调用了 `use(stepModel)`，但是我们并没有解构 `stepModel` 的 `state` 值，因为 `define` 的回调函数是在 Model 的挂载阶段执行的，这个时候获取到的 `stepModel` 的 `state` 可能和 `add` 执行时获取到的值是不同的。
+
+:::
+
+修改 **App.tsx**
+
+```tsx
+import { useModel } from '@modern-js/runtime/model';
+import { counterModel, stepModel } from './models/count';
+
+function Counter() {
+  const [state, actions] = useModel(counterModel);
+  const [step, stepActions] = useModel(stepModel);
+
+  return (
+    <div>
+      <div>step: {step}</div>
+      <button onClick={() => stepActions.setState(step + 1)}>add step</button>
+      <div>counter: {state.value}</div>
+      <button onClick={() => actions.add()}>add counter</button>
+    </div>
+  );
+}
+
+export default function App() {
+  return <Counter />;
+}
+```
+
+:::info 补充信息
+Modern.js 默认开启 [自动生成 actions](./auto-actions.md)，所以 `stepModel` 中虽然没有手动定义 Actions，但可以使用自动生成的 `setState`。
+
+:::
+
+- 点击 **add step** 增加步频。
+- 点击 **add counter** 触发计数器增加。
+
+最终效果如下：
+
+![communicate-models](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/models-communicate.gif)
+
+:::info 补充信息
+- 本节完整的[示例代码](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/models-communication)。
+- 相关 API 的更多介绍，请参考：[model](/apis/app/runtime/model/model_#函数类型)。
+
+:::
+
+前面 `counterModel` 的例子，我们是在 Actions 的函数内部调用 `use` 获取其他 Model 对象的。如果只需要调用其它 Model 的 Actions，因为 Actions 都是函数，不存在值过期问题，所以也可以在 `define` 的回调函数中调用 `use` 获取 Model 的 Actions。例如：
+
+```ts
+const barModel = model('bar').define({
+  // 省略
+});
+
+const fooModel = model('foo').define((context, utils) => {
+  // 获取 barModel 的 actions
+  const [, actions] = utils.use(barModel);
+  return {
+    // 省略 state、actions
+    effects: {
+      async loadA() {
+        // 省略副作用逻辑
+        // 调用 barModel 的 action
+        barModel.actionA();
+      },
+      async loadB() {
+        // 省略副作用逻辑
+        // 调用 barModel 的 action
+        barModel.actionB();
+      },
+    },
+  };
+});
+```
+
+这样，我们不需要在 `loadA`、`loadB` 中重复获取 `barModel` 对象，简化了代码逻辑。
+
+## Model 内通信
+
+Model 内通信，也主要分为两种场景：
+
+1. Effects 函数调用自身 Model 的 Actions 函数、或其他 Effects 函数。
+2. Actions 函数调用自身 Model 的 其他 Actions 函数。
+
+在 [副作用管理](/guides/topic-detail/model/manage-effects) 一节，我们演示过 Effects 函数如何调用 Actions 函数。
+
+这里我们再来举一个例子：
+
+```ts
+const fooModel = model('foo').define((context, { use, onMount }) => ({
+  state: {
+    a: '',
+    b: '',
+  },
+  actions: {
+    setA(state, payload) {
+      state.a = payload;
+    },
+    setB(state, payload) {
+      state.a = payload;
+    },
+  },
+  effects: {
+    async loadA() {
+      // 通过 use 获取当前 Model 的 actions
+      const [, actions] = use(fooModel);
+      const res = await mockFetchA();
+      actions.setA(res);
+    },
+    async loadB() {
+      // 通过 use 获取当前 Model 的 actions
+      const [, actions] = use(fooModel);
+      const res = await mockFetchB();
+      actions.setB(res);
+    },
+  },
+}));
+```
+
+这个例子中，`fooModel` 的两个 Effects 函数，需要调用自身的 Actions 函数。这里我们在每个 Effects 函数中，都调用了一次 `use`，为什么不能像 Model 间通信的例子中，在 `define` 的回调函数中，统一调用 `use` 获取 Model 自身的 Actions 呢？这是因为调用 `use` 获取 Model 时，会先检查这个 Model 是否已经挂载，如果还没有挂载，会先执行挂载逻辑，而 `define` 的回调函数又是在 Model 的挂载阶段执行的，这样一来，在挂载阶段调用 `use` 获取 Model 自身，会出现死循环（代码实际执行过程会抛出错误）。所以，**一定不能在 `define` 的回调函数中，调用 `use` 获取 Model 自身对象。**
+
+不过，我们可以利用 `onMount` 这个钩子函数，在 Model 挂载完成后，再通过 `use` 获取 Model 自身对象：
+
+```ts
+const fooModel = model('foo').define((context, { use, onMount }) => {
+  let actions;
+
+  onMount(() => {
+    // fooModel 挂载完成后，通过 use 获取当前 Model 的 actions
+    [, actions] = use(fooModel);
+  });
+
+  return {
+    state: {
+      a: '',
+      b: '',
+    },
+    actions: {
+      setA(state, payload) {
+        state.a = payload;
+      },
+      setB(state, payload) {
+        state.a = payload;
+      },
+    },
+    effects: {
+      async loadA() {
+        const res = await mockFetchA();
+        actions.setA(res);
+      },
+      async loadB() {
+        const res = await mockFetchB();
+        actions.setB(res);
+      },
+    },
+  };
+});
+```
+
+这样，我们也可以实现代码的简化。

package/zh/guides/topic-detail/model/performance.mdx

@@ -0,0 +1,171 @@
+---
+sidebar_position: 8
+title: 性能优化
+---
+# 性能优化
+
+Reduck 内部已经做了大量性能优化工作，一般情况下不需要考虑性能问题。不过当对性能比较敏感、或者遇到了性能问题，可以考虑从以下 3 个方面，进行更有针对性的性能优化。
+
+## Model 拆分
+
+当 `useModel` 返回 Model 对象的完整 State 时，State 任意部分的变化都会导致调用了 `useModel` 的组件重新渲染。
+
+例如：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    a: '',
+    b: '',
+  },
+  actions: {
+    setA(state, payload) {
+      state.a = payload;
+    },
+    setB(state, payload) {
+      state.b = payload;
+    },
+  },
+});
+
+function ComponentA() {
+  const [state] = useModel(fooModel);
+
+  return <div>{state.a}</div>;
+}
+```
+
+组件 `ComponentA` 虽然只需要使用 `a` 状态，但当 `b` 状态发送变化时， `ComponentA` 仍然会重新渲染。这种情况，我们可以考虑把 `fooModel` 拆分，`a`、`b` 分别由不同的 Model 负责管理：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    a: '',
+  },
+  actions: {
+    setA(state, payload) {
+      state.a = payload;
+    },
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    b: '',
+  },
+  actions: {
+    setB(state, payload) {
+      state.b = payload;
+    },
+  },
+});
+```
+
+## 状态筛选
+
+`useModel` 支持传入 selector 函数，对返回给组件的 State 和 Actions 做筛选。我们可以通过 selector 函数，确保返回给组件的 State 是组件直接需要使用的，从而保证组件不会因为其他无关状态的变化而重新渲染。
+
+对于上面同样的例子，我们采用 selector 函数进行性能优化，代码如下：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    a: '',
+    b: '',
+  },
+  actions: {
+    setA(state, payload) {
+      state.a = payload;
+    },
+    setB(state, payload) {
+      state.b = payload;
+    },
+  },
+});
+
+function ComponentA() {
+  // 通过传入 selector 函数，只返回 a 状态给组件
+  const [stateA] = useModel(fooModel, state => state.a);
+
+  return <div>{stateA}</div>;
+}
+```
+
+## 衍生状态缓存
+
+当 Model 存在 `computed` 时，每次调用`useModel` 都会执行 `computed` 函数。
+
+考虑如下代码：
+
+```ts
+const barModel = model('bar').define({
+  state: {
+    value: 'bar',
+  },
+  computed: {
+    combineA: [
+      fooModel, // fooModel 定义同上
+      (state, fooState) => {
+        return state + fooState.a;
+      },
+    ],
+  },
+  actions: {
+    setValue(state, payload) {
+      state.value = payload;
+    },
+  },
+});
+
+function ComponentB() {
+  const [state, actions] = useModel(fooModel);
+  const [{ combineA }] = useModel(barModel);
+  // 省略
+}
+```
+
+`barModel` 的衍生状态 `combineA` 依赖 `barModel` 自身状态 和 `fooModel` 的状态 `a`，但是即使是 `fooModel` 的状态 `b` 发生了变化，组件重新渲染时， `combineA` （更准确的说法是 `combineA` 的最后一个函数类型的元素 ）依然会被调用执行。
+
+一般情况下，`computed` 函数中的逻辑都是非常轻量的，但当 `computed` 函数逻辑比较复杂时，我们可以考虑对计算逻辑做缓存。例如，我们使用 [reselect](https://github.com/reduxjs/reselect) 对 `barModel` 的 `combineA` 做缓存：
+
+```ts
+import 'createSelector' from 'reselect';
+
+// 创建缓存函数
+const selectCombineA = createSelector(
+  (state) => state.bar.value,
+  (state) => state.foo.a,
+  (barState, fooState) => {
+    return barState + fooState;
+  }
+);
+
+const barModel = model("bar").define({
+  state: {
+    value: "bar",
+  },
+  computed: {
+    combineA: [
+      fooModel,
+      (state, fooState) => {
+        return selectCombineA({
+          foo: fooState,
+          bar: state,
+        });
+      },
+    ],
+  },
+  actions: {
+    setValue(state, payload) {
+      state.value = payload;
+    },
+  },
+});
+```
+
+我们创建缓存函数 `createSelector`，仅当 `barModel` 的状态发生改变或 `fooModel` 的 `a` 状态发生改变时，才会重新计算 `combineA` 的值。
+
+:::info 补充信息
+本节完整的[示例代码](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/performance-optimization)
+
+:::

package/zh/guides/topic-detail/model/quick-start.mdx

@@ -0,0 +1,113 @@
+---
+sidebar_position: 1
+title: 快速上手
+---
+# 快速上手
+
+import ReduckMigration from "@site-docs/components/reduck-migration"
+
+<ReduckMigration />
+
+[Reduck](https://github.com/modern-js-dev/reduck) 是 Modern.js 团队开发的遵循 MVC 模式的状态管理库，底层状态存储基于 [Redux](https://redux.js.org/) 实现，同时提供更高层级的抽象，并完全兼容 Redux 生态。
+
+Reduck 的目标是以 MVC 模式组织 React 应用开发结构，将业务逻辑维护在 Model 层，业务逻辑与 UI 解耦，让开发业务逻辑更集中、更简单，同时通过更高层级的抽象，减少重复工作（样板代码）。
+
+Reduck 在 MVC 模式中，扮演 M(Model) 的角色，React UI Component 对应 V(View)，从 Reduck 中获取 Model 并修改 Model 的 React Container Component 对应 C(View Controller/Container)。
+
+Modern.js 的状态管理解决方案，是通过内置 Reduck 实现的。在 Modern.js 中使用 Reduck，不仅免去了手动集成的环节，而且所有 Reduck API 都可以从 Modern.js 的 Runtime 包中直接导入使用，具有更好的一致性体验。
+
+:::info 注
+1. Modern.js 中使用 Reduck API，需要先设置 [runtime.state](/configure/app/runtime/state) 以启用状态管理插件。
+2. Reduck 也可以脱离 Modern.js 作为状态管理库[单独使用](/guides/topic-detail/model/use-out-of-modernjs)。
+
+:::
+
+## 核心概念
+
+Reduck 中的核心概念只有 4 个： Model、State、Actions、Effects。
+
+Model: 对独立模块的逻辑和所需状态的封装，由 State、Actions、Effects 组成。
+
+State: Model 中保存的状态。
+
+Actions: 用于修改 State 的纯函数，函数必须是**同步**的。
+
+Effects: 用于修改 State 的带有副作用的函数，函数可以是**异步**的。Effects 中可以调用自身或其他 Model 的 Actions 和 Effects。
+
+Reduck 数据流如下图所示：
+
+![Reduck 数据流](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/reduck-concept.svg)
+
+## 基本用法
+
+下来我们以一个简单的 **计数器** 应用为例，演示 Reduck 的基本用法。
+
+首先，我们定义一个名为 `count` 的 Model：
+
+```js
+import { model } from '@modern-js/runtime/model';
+
+const countModel = model('count').define({
+  state: {
+    value: 1,
+  },
+});
+
+export default countModel;
+```
+
+我们使用 API `model` 创建 `countModel`，`countModel` 当前只包含存储计数器值的状态，即代码中的 `value`。
+
+我们定义一个 action，用于计算器自增加 1：
+
+```js
+import { model } from '@modern-js/runtime/model';
+
+const countModel = model('count').define({
+  state: {
+    value: 1,
+  },
+  actions: {
+    add(state) {
+      state.value += 1;
+    },
+  },
+});
+
+export default countModel;
+```
+
+在 `add` action 中，我们可以直接修改 state 的值，进行加 1 操作，而不需要把 state 作为不可变对象进行操作，这是因为 Reduck 集成了 [immer](https://github.com/immerjs/immer)，可以直接修改原 state 对象。
+
+接下来，我们演示如何在组件中使用 Model。
+
+新建一个组件 Counter，在组件内通过 `useModel` API 使用 `countModel`：
+
+```js
+import { useModel } from '@modern-js/runtime/model';
+import countModel from './models/count';
+
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  return (
+    <div>
+      <div>counter: {state.value}</div>
+      <button onClick={() => actions.add()}>add</button>
+    </div>
+  );
+}
+```
+
+`useModel` 获取 `countModel` 的 `state` 和 `actions`，组件展示当前计算器的值，点击 `add` 按钮，计数器自增 1。
+
+:::info 注
+由于使用的案例比较简单，这里并没有严格按照 MVC 模式进行分层，组件 `Counter` 同时起到了 V 和 C 两层的作用。
+
+:::
+
+最终演示效果如下：
+
+![countModel](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/simple-count-model.gif)
+
+这样，我们就完了一个简单的计数器应用。本节完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model)查看。

package/zh/guides/topic-detail/model/redux-integration.mdx

@@ -0,0 +1,24 @@
+---
+sidebar_position: 11
+title: Redux 生态集成
+---
+# Redux 生态集成
+
+Reduck 基于 Redux 实现，因此可以使用 Redux [生态的库](https://redux.js.org/introduction/ecosystem)，实现功能增强。通过 [`Provider`](/apis/app/runtime/model/Provider) 、[`createApp`](/apis/app/runtime/model/create-app) 和 [`createStore`](/apis/app/runtime/model/create-store) 等 API ，可以设置使用 Redux 的 [中间件](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware) 和 [Store Enhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer)；使用 [`createStore`](/apis/app/runtime/model/create-store) 还可以完全掌控 Store 的创建过程。
+
+例如，我们希望使用中间件 [`redux-logger`](https://github.com/LogRocket/redux-logger)，示例代码如下：
+
+```ts
+ReactDOM.render(
+  <Provider config={{ middlewares: [logger] }}>
+    // 通过 Provider 的 config 参数设置 中间件
+    <App />
+  </Provider>,
+  document.getElementById('root'),
+);
+```
+
+:::caution
+Reduck 基于 Redux 底层 API 做了上层封装，屏蔽了 Redux 的一些底层概念，如 Reducer 等。Reduck 对于 Model 是动态挂载的，而 Redux 是在 Store 创建时就会挂载应用所需的全部状态。基于这些实现上的差异，有些 Redux 生态的库是无法直接在 Reduck 中使用的。
+
+:::

package/zh/guides/topic-detail/model/test-model.mdx

@@ -0,0 +1,45 @@
+---
+sidebar_position: 9
+title: 测试 Model
+---
+# 测试 Model
+
+好的测试对代码的稳健性至关重要。下面以 [快速上手](/guides/topic-detail/model/quick-start) 的 `countModel` 为例，演示在 Modern.js 中，如何对 Model 进行单元测试。
+
+使用测试功能，需要先开启该功能。在项目根目录下，执行 `pnpm run new`，进行如下选择：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「单元测试 / 集成测试」功能
+```
+
+即可开启测试功能支持。
+
+新增 `count.test.ts` 文件，代码如下：
+
+```ts
+import { createStore } from '@modern-js/runtime/testing';
+import countModel from './count';
+
+describe('test model', () => {
+  it('count value should plus one after add', () => {
+    const store = createStore();
+    const [state, { add }] = store.use(countModel);
+
+    expect(state).toEqual({ value: 1 });
+
+    add();
+
+    expect(store.use(countModel)[0]).toEqual({ value: 2 });
+  });
+});
+```
+
+:::info 注
+这里使用的 [`createStore`](/apis/app/runtime/model/create-store) 是从 `@modern-js/runtime/testing` 导入的，内部会使用 [`runtime.state`](/configure/app/runtime/state) 的配置去创建 `store`。
+
+:::
+
+在测试用例里，我们新建一个 `store` 来挂载 `countModel`，通过 `store.use` 获取 `countModel` 的 State 和 Actions。然后调用 `add` Action 更新状态，并断言更新后的状态值。
+
+执行 `pnpm run test` 命令，触发测试用例的执行。

package/zh/guides/topic-detail/model/typescript-best-practice.mdx

@@ -0,0 +1,71 @@
+---
+sidebar_position: 10
+title: TS 最佳实践
+---
+# TS 最佳实践
+
+Reduck 对 TS 提供了良好的支持，大部分使用场景下，无需任何额外工作，就可以直接获得 API 的 TS 类型提示。本节，将对其他的一些使用场景，做补充介绍。
+
+## 定义 Model 的 State 类型
+
+为 Model 的 State 声明类型信息，是在 TS 中使用 Reduck 的最佳实践。
+
+```ts title="示例"
+interface State {
+  data: string;
+}
+
+export const foo = model<State>('foo').define({
+  state: {
+    data: '',
+  },
+  computed: {
+    withSuffix: state => state.data + 'suffix',
+  },
+  actions: {
+    setData: (state, payload: string) => {
+      state.data = payload;
+    },
+  },
+});
+```
+
+当为 Model 的 State 声明类型信息后，Model 的 `computed`、`actions` 都能获取正确的类型信息。事实上，上面的示例代码中，即使我们不定义 State 类型信息，也会根据 `state` 的初始值信息自动推导出 State 的类型信息。不过，仍然建议你在定义 Model 时，声明 State 的类型信息，因为根据 `state` 的初始值信息推导出的 State 类型信息可能不完整(缺少字段或字段的类型信息缺少)，而且当使用[函数类型](/apis/app/runtime/model/model_#函数类型)定义 Model 时，State 的类型信息也是无法根据 `state` 的初始值信息自动推导的。
+
+## 衍生状态的依赖类型
+
+当 Model 的衍生状态依赖其他 Model 时，需要手动指定其他 Model 的 State。
+
+```ts title="示例"
+interface State {
+  data: string;
+}
+
+export const bar = model<State>('bar').define({
+  state: {
+    data: '',
+  },
+  computed: {
+    // 为 fooState 指定类型
+    withFoo: [foo, (state, fooState: FooState) => state.data + fooState.data],
+  },
+});
+```
+
+## 获取 Model 类型信息的 Hooks
+
+Reduck 提供了一组用于获取 Model 类型信息的工具类型：
+
+- `GetModelState`： 获取 Model 的 State（包含衍生状态）类型信息。
+- `GetModelActions`：获取 Model 的 Actions（包含 Effects 函数）类型信息。
+
+```ts title="示例"
+export const foo = model<State2>('foo').define({
+  // 省略
+});
+
+// 获取 foo 的 State 类型
+let fooActions: GetModelActions<typeof foo>;
+// 获取 foo 的 Actions 类型
+let fooState: GetModelState<typeof foo>;
+```