@modern-js/main-doc 2.0.0-beta.3 → 2.0.0-beta.4

package/zh/tutorials/first-app/c09-bff/9.2-enable-bff.md

@@ -1,95 +0,0 @@
----
-title: 启用 BFF
----
-
-和之前章节一样，我们同样使用生成器来启用 BFF。
-
-在项目根目录下执行 `pnpm run new` 命令：
-
-```bash
-# 启用可选功能
-❯ 启用「BFF」功能
-  ...
-
-# 请选择 BFF 类型
-❯ 函数写法
-  框架写法
-
-# 请选择运行时框
-❯ Express
-  Koa
-```
-
-:::info 注
-函数模式与框架模式都是基于 Modern.js 的 BFF 函数的，两种模式的主体都是函数，也都需要运行时框架的支持，这里的提问是为了提供不同的样板文件。更多相关内容可以查看[一体化 BFF 专题](/docs/guides/advanced-features/bff/function)。
-:::
-
-我们先选择【 函数写法 】，并选择运行时框架为 Express，项目结构将变成：
-
-```md
-.
-├── .eslintrc.js
-├── .gitignore
-├── .husky
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── .vscode
-├── README.md
-├── api
-│   ├── _app.ts
-│   ├── index.ts
-│   └── info
-│       └── [type].ts
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── src
-│   ├── .eslintrc.js
-│   ├── contacts
-│   │   ├── index.test.ts
-│   │   └── routes
-│   │       ├── archives
-│   │       │   └── page.tsx
-│   │       ├── components
-│   │       │   ├── Avatar
-│   │       │   │   ├── index.stories.tsx
-│   │       │   │   └── index.tsx
-│   │       │   └── Item
-│   │       │       ├── index.test.tsx
-│   │       │       └── index.tsx
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       ├── page.tsx
-│   │       └── styles
-│   │           └── utils.css
-│   ├── landing-page
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       └── page.tsx
-│   └── modern-app-env.d.ts
-└── tsconfig.json
-```
-
-新增的 `api/` 目录，跟 `src/` 目录一样是源代码目录，目录中有几个示范用法的样板文件
-
-`package.json` 中则会增加 BFF 插件：
-
-```json
-+ "@modern-js/plugin-bff"
-+ "@modern-js/plugin-express"
-+ "express"
-```
-
-在函数写法中，BFF 的 API 路由也遵循类似【 约定式路由 】的生成逻辑。
-
-Modern.js Serverless BFF 的默认前缀为 `/api`，例如上述目录结构可以得到两个 API 路由：
-
-`http://localhost:8080/api`
-
-`http://localhost:8080/api/info/:type`
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c09/hello-modern-2)。

package/zh/tutorials/first-app/c09-bff/9.3-fetch-bff.md

@@ -1,131 +0,0 @@
----
-title: 从 BFF 获取数据
----
-
-上一小节中，我们创建了【 函数写法 】的 BFF，这一小节中，我们将用该模式为联系人列表实现一个数据接口。
-
-我们首先把不需要的样板文件清理掉，把 `index.ts` 重命名为 `contacts.ts`，执行以下命令：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-rm -r api/info api/_app.ts
-mv api/index.ts api/contacts.ts
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-rm -r api/info
-rm api/_app.ts
-mv api/index.ts api/contacts.ts
-```
-
-</TabItem>
-</Tabs>
-
-
-此时 API 路由将变为 `/api/contacts`。
-
-我们使用 [faker](https://github.com/Marak/Faker.js) 来 mock 需要的数据，首先安装依赖：
-
-```bash
-pnpm add faker@5.5.3
-```
-
-将 `api/contacts.ts` 内容改为：
-
-```js
-import { name, internet } from 'faker';
-
-export const get = async () => {
-  const mockData = new Array(20).fill(0).map(() => {
-    const firstName = name.firstName();
-    return {
-      name: firstName,
-      avatar: `https://avatars.dicebear.com/api/identicon/${firstName}.svg`,
-      email: internet.email(),
-    };
-  });
-
-  return { code: 200, data: mockData };
-};
-```
-
-:::info 注
-数据同样可以从远端接口获取，此处仅为了演示。
-:::
-
-执行 `pnpm run dev`，访问 `http://localhost:8080/api/contacts`：
-
-![browser-result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/08/api-result.png)
-
-接下来我们把 `src/routes/contacts/page.tsx` 里硬编码的 `getMockData` 改成从 BFF 加载:
-
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-import { List } from 'antd';
-import 'ladda/dist/ladda.min.css';
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import './styles/utils.css';
-
-import { useState, useEffect } from 'react';
-import { get as contacts } from '@api/contacts';
-import Item from './components/Item';
-
-function Index() {
-  const [list, setList] = useState(
-    [] as Array<{ name: string; email: string; avatar: string }>,
-  );
-  const loadMockData = async () => {
-    const { data } = await contacts();
-    setList(data);
-  };
-  useEffect(() => {
-    if (!list.length) {
-      loadMockData();
-    }
-  });
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>All</title>
-      </Helmet>
-      {(list.length && (
-        <List
-          dataSource={list}
-          renderItem={info => <Item key={info.name} info={info} />}
-        />
-      )) || (
-        <div className="p-4 items-center border-gray-200 border-b border-t custom-text-gray">
-          Pending...
-        </div>
-      )}
-    </div>
-  );
-}
-
-export default Index;
-```
-
-在 Modern.js 中，可以通过调用函数（前后端一体化）的方式，直接调用 BFF 接口，调用时无需关心域名、路径等。
-
-:::info 注
-在使用 `pnpm run new` 创建 BFF 时，Modern.js 已经默认在 `tsconig.json` 中注入了别名。这也是之前提到的，生成器在项目创建之后并不会被抛弃，仍旧可以在开发过程中不断为项目提供新的内容。
-:::
-
-执行 `pnpm run dev`，再打开页面`http://localhost:8000/contacts`，可以看到页面加载后，会先初始化联系人数据（显示 pending），之后每次切换到 All 列表，也会重新请求联系人数据：
-
-![browser-result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/08/browser-result.png)
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c09/hello-modern-3)。
-

package/zh/tutorials/first-app/c09-bff/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "9: 添加 BFF"
-}

package/zh/tutorials/first-app/c10-model/10.1-application-architecture.md

@@ -1,21 +0,0 @@
----
-title: 应用架构
----
-
-上一章节中，我们把硬编码的 `mockData` 改成从 BFF 加载，在 `pages.tsx` 组件里用 BFF 函数，获取到联系人数据之后，保存在 `Index` 的组件内部状态里，而 `archives/index` 组件暂时继续使用 mock 数据。
-
-本章节中，为了进一步实现项目功能，我们需要让两个组件都从 BFF 获取数据，还要实现【 Archive 】按钮，点击按钮能把联系人归档。
-
-业务逻辑变复杂之后，相关代码不可避免会变多，如果都写在组件里，都会让这个组件的可读性和可维护性变差，让做不同事情的代码混在一起。
-
-原本可以跟 UI 完全解耦的业务逻辑（比如网络请求、纯数据的操作、状态的管理等）跟 UI 逻辑（比如联系人列表如何展现）混在一起，当需要修改 UI 的时候，不得不跟 UI 无关的业务逻辑代码打交道，反过来也一样，不符合【 [单一职责原则（SRP）](https://zh.wikipedia.org/wiki/%E5%8D%95%E4%B8%80%E5%8A%9F%E8%83%BD%E5%8E%9F%E5%88%99)】，也做不到【 [关注点分离（SoC）](https://zh.wikipedia.org/wiki/%E5%85%B3%E6%B3%A8%E7%82%B9%E5%88%86%E7%A6%BB)】。
-
-从这里开始，我们发现如果这是个真实的项目，继续这样写下去会产生越来越多面条式代码，仅凭 React 组件这一种抽象方式，不足以让代码足够结构化，随着项目不断积累业务逻辑、复杂性和变更，技术债也会积累，最终可能变成没人愿意碰的祖传代码。
-
-像这样的项目，需要更健全的**客户端应用架构**。
-
-Modern.js 提供开箱即用的**应用架构**，支持几种扮演不同**角色（role）**、属于不同**分层（layer）**的代码模块类型，可以把业务逻辑解耦到不同类型的代码模块里，做到高[内聚](https://zh.wikipedia.org/wiki/%E5%85%A7%E8%81%9A%E6%80%A7_(%E8%A8%88%E7%AE%97%E6%A9%9F%E7%A7%91%E5%AD%B8))低[耦合](https://zh.wikipedia.org/wiki/%E8%80%A6%E5%90%88%E6%80%A7_(%E8%A8%88%E7%AE%97%E6%A9%9F%E7%A7%91%E5%AD%B8))。
-
-当前项目里 `components/` 目录中的 React 组件，是一种可以称作【 视图组件 】的代码模块，负责 UI、交互上的界面展现。
-
-本章节我们来把 `page.tsx` 中的 Index 组件中可以跟 UI 解耦的业务逻辑，移到一种叫【 Model（业务模型）】的代码模块里。

package/zh/tutorials/first-app/c10-model/10.2-add-model.md

@@ -1,185 +0,0 @@
----
-title: 实现 Model
----
-
-创建一个完整的 Model 首先需要定义**状态（state）**，包括状态中数据的名称和初始值。
-
-我们使用 Model 来管理联系人列表的数据，因此定义如下数据状态：
-
-```js
-const state = {
-  items: [],
-};
-```
-
-使用 TS 语法，可以定义更完整的类型信息，比如 items 里每个对象都应该有 `name`、`email` 字段；
-
-为了实现归档功能，还需要创建 `archived` 字段保存这个联系人是否已被归档的状态；
-
-我们还需要一个字段用来访问所有已归档的联系人，可以定义 **computed** 类型的字段，对已有的数据做转换：
-
-```js
-const computed = {
-  archived: ({ items }) => {
-    return items.filter(item => item.archived);
-  },
-};
-```
-
-:::info 注
-当前版本还未支持 computed，本章节后续部分会先使用其他方式实现 archived 列表，这里只做介绍。
-:::
-
-computed 类型字段的定义方式是函数，但使用时可以像普通字段一样通过 state 访问。
-
-Modern.js 支持的 Model 模块跟 React 组件一样，是基于 FP（Functional Programming）而不是 OOP（Object-Oriented Programming）的，对状态的管理是基于**不可变数据**的，不会修改状态中的数据，只会从一个状态转移到另一个状态，这样的好处很多，比如保障程序的可靠性、方便调试、方便记录和还原状态等。
-
-由于 JS 没有原生支持不可变数据，为了提高编写这种代码的效率，Modern.js 集成了 [Immer](https://immerjs.github.io/immer/)，能够像操作 JS 中常规的可变数据一样，去写这种状态转移的逻辑。
-
-实现 Archive 按钮时，我们需要一个 `archive` 函数，负责修改指定联系人的 `archived` 字段，我们把这种函数都叫作 **action**：
-
-```js
-const actions = {
-  archive(draft, payload) {
-    const target = draft.items.find(item => item.email === payload);
-    if (target) {
-      target.archived = true;
-    }
-  },
-};
-```
-
-action 函数是一种**纯函数**，确定的输入得到确定的输出（转移后的状态），不应该有任何副作用。
-
-函数的第一个参数是 Immer 提供的 Draft State，第二个参数是 action 被调用时传入的参数（后面会介绍怎么调用）。
-
-Model 里也可以定义 Side Effect，比如我们需要从 BFF 加载这个联系人列表的数据，这段业务逻辑可以写成：
-
-```js
-const effects = {
-  async load() {
-    const { data } = await contacts();
-    return data;
-  },
-};
-```
-
-一个 Side Effect 有多种实现方式，上面使用的是 Async 函数方式，这种方式是最简单直观的。Modern.js 会根据它返回的 Promise 对象的状态变化，自动触发不同的 action。
-
-因此一个 effect 总共有三个 action，命名里会用 Side Effect 的名称作为命名空间，在这个例子里，分别是：
-
-- `load.pending`：等待中
-- `load.fulfilled`：成功，得到结果
-- `load.rejected`：失败，得到错误信息
-
-Modern.js 虽然会自动定义和触发这些 action，但默认不会为这些 action 实现具体的业务逻辑（action 直接返回原本的状态，不做任何转换）。
-
-我们尝试自己实现它们：
-
-```js
-import _ from 'lodash';
-
-const state = {
-  items: [],
-  pending: false,
-  error: null,
-};
-
-const computed = {
-  archived: ({ items }) => {
-    return items.filter(item => item.archived);
-  },
-};
-
-const actions = {
-  archive(draft, payload) {
-    const target = draft.items.find(item => item.email === payload);
-    if (target) {
-      target.archived = true;
-    }
-  },
-  load: {
-    pending(draft) {
-      draft.pending = true;
-    },
-    fulfilled(draft, payload) {
-      draft.pending = false;
-      _.merge(draft.items, payload);
-    },
-    rejected(draft, payload) {
-      draft.pending = false;
-      draft.error = payload;
-    },
-  },
-};
-```
-
-上述实现里，成功时，payload 是 promise 的结果；失败时，payload 是错误信息。
-
-从上面这个例子里可以看到，可以用嵌套的写法，实现 `load.pending` 这样名称中包含命名空间的 action。
-
-为了做到高内聚低耦合，一个 Model 的 state、action、side effect 不应该分散在不同文件里。接下来我们把上面的代码连起来，放在同一个 Model 文件里，执行以下命令：
-
-```bash
-mkdir -p src/contacts/routes/models/
-touch src/contacts/routes/models/contacts.ts
-```
-
-`src/contacts/routes/models/contacts.ts` 的内容：
-
-```tsx
-import { model } from '@modern-js/runtime/model';
-import { get as contacts } from '@api/contacts';
-
-type State = {
-  items: {
-    avatar: string;
-    name: string;
-    email: string;
-    archived?: boolean;
-  }[];
-  pending: boolean;
-  error: null | Error;
-};
-
-export default model<State>('contacts').define({
-  state: {
-    items: [],
-    pending: false,
-    error: null,
-  },
-  computed: {
-    archived: ({ items }: State) => items.filter(item => item.archived),
-  },
-  actions: {
-    archive(draft, payload) {
-      const target = draft.items.find(item => item.email === payload)!;
-      if (target) {
-        target.archived = true;
-      }
-    },
-    load: {
-      pending(draft) {
-        draft.pending = true;
-      },
-      rejected(draft, payload) {
-        draft.pending = false;
-        draft.error = payload;
-      },
-      fulfilled(draft, p) {
-        draft.items = p;
-      },
-    },
-  },
-  effects: {
-    async load() {
-      const { data } = await contacts();
-      return data;
-    },
-  },
-});
-```
-
-我们把一个包含 state，action 等要素的 plain object 称作【 Model Spec 】，Modern.js 提供了 [Model API](/docs/apis/app/runtime/model/model_)，可以根据 Model Spec 生成【 Model 】。
-
-本小节中，我们联系人列表项目需要的 Model 实现。下一小节我们将会学习如何使用 Model。

package/zh/tutorials/first-app/c10-model/10.3-use-model.md

@@ -1,55 +0,0 @@
----
-title: 使用 Model
----
-
-上一小节中，我们实现了 Model，已经把 `page.tsx` `Index` 组件中原有的 UI 无关业务逻辑解耦出来。
-
-这一小节中，我们使用这个 Model 直接把 `page.tsx` `Index` 组件重新还原出来，实现变得更简洁清晰：
-
-```js title="src/contacts/routes/page.tsx"
-import { useEffect } from 'react';
-import { useLocalModel } from '@modern-js/runtime/model';
-import contacts from './models/contacts';
-import Item from './components/Item';
-
-function Index() {
-  const [{ items, error, pending }, actions] = useLocalModel(contacts);
-
-  useEffect(() => {
-    if (!items.length && !error && !pending) {
-      actions.load();
-    }
-  });
-  return (
-    <div className="container lg mx-auto">
-      {(items.length && (
-        <List
-          dataSource={items}
-          renderItem={info => <Item key={info.name} info={info} />}
-        />
-      )) || (
-        <div className="p-4 items-center border-gray-200 border-b border-t custom-text-gray">
-          Pending...
-        </div>
-      )}
-    </div>
-  );
-}
-
-export default Index;
-```
-
-以上代码跟上一章节中 `Index` 组件的代码等价。
-
-`useLocalModel` 是 Modern.js 提供的 hooks API，可以使用 Model，在组件中提供 Model 中定义的 state，或通过 actions 调用 Model 中定义的 side effect 与 action，从而改变 Model 的 state。
-
-Modern.js 的 Model 能够这样使用的原因是 Model 是基于 FP 的，不像 OOP 的 Model 那样自身持有和封装了状态，对外部提供方法访问和修改自身内部的状态。
-
-Model 是业务逻辑，是计算过程，本身不创建也不持有状态，只有在被组件用 hooks API 使用后，才在指定的地方（比如这个例子里，是组件内部的 state）创建状态。
-
-执行 `pnpm run dev`，可以看到跟上一章节一样的效果。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c10/hello-modern-3)。
-

package/zh/tutorials/first-app/c10-model/10.4-testing.md

@@ -1,69 +0,0 @@
----
-title: 测试 Model
----
-
-上一小节中我们学习了如何使用 Model。
-
-这一小节里我们来测试 Model。
-
-跟[测试组件​​​](../c06-css-and-component/6.6-testing.md)中一样，不需要做任何配置，可以直接给 Model 写测试用例。
-
-以 `models/contacts` 为例，我们创建对应的 `.test` 文件：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/contacts/routes/models/contacts.test.ts
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-ni src/contacts/routes/models/contacts.test.ts
-```
-
-</TabItem>
-</Tabs>
-
-在测试用例中可以使用 Modern.js 提供的 Model 模拟，可以调用这个对象的方法写断言。
-
-我们直接使用 createStore API 来编写测试文件，示例内容如下：
-
-```ts
-import { createStore } from '@modern-js/runtime/testing';
-import contactsModel from './contacts';
-
-const mockItem = {
-  avatar: '',
-  name: '李华',
-  age: '16',
-  email: 'lihua@gmail.com',
-  archived: false,
-};
-
-describe('test contracts model', () => {
-  it('actions works well', async () => {
-    const store = createStore();
-    const [state, actions] = store.use(contactsModel);
-
-    state.items.push(mockItem);
-    expect(store.use(contactsModel)[0].items.length).toBe(1);
-    expect(store.use(contactsModel)[0].items[0].archived).toBeFalsy();
-
-    await actions.archive('lihua@gmail.com');
-    expect(store.use(contactsModel)[0].items[0].archived).toBeTruthy();
-  });
-});
-```
-
-执行 `pnpm run test`，可以看到测试报告。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c10/hello-modern-4)。
-

package/zh/tutorials/first-app/c10-model/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "10: 添加业务模型"
-}