@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/guides/basic-features/data/data-fetch.mdx

@@ -0,0 +1,421 @@
+---
+title: 数据获取
+sidebar_position: 3
+---
+
+# 数据获取
+
+Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过这些 API，在项目中获取数据。需要注意的是，这些 API 并不帮助应用发起请求，而是帮助开发者更好地管理数据，提升项目的性能。
+
+## 什么是 Data Loader
+
+Modern.js 推荐使用[约定式路由](/guides/basic-features/routes/routes)做路由的管理，每个路由组件（`layout.ts`，`page.ts` 或 `$.tsx`）都可以有一个同名的 `.data` 文件。这些文件可以导出一个 `loader` 函数，我们称为 Data Loader，它会在对应的路由组件渲染之前执行，为组件提供数据。如下面示例：
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        ├── layout.data.ts
+        ├── page.tsx
+        └── page.data.ts
+```
+
+在 `routes/user/page.data.ts` 文件中，可以导出一个 `loader` 函数：
+
+```ts title="routes/user/page.data.ts"
+export type ProfileData = {
+  /*  some types */
+};
+
+export const loader = async (): Promise<ProfileData> => {
+  const res = await fetch('https://api/user/profile');
+  return await res.json();
+};
+```
+
+在路由组件中，你可以通过 `useLoaderData` 函数获取数据：
+
+```ts title="routes/user/page.tsx"
+import { useLoaderData } from '@modern-js/runtime/router';
+import type { ProfileData } from './page.data.ts';
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+:::caution
+路由组件和 `.data` 文件共享类型，要使用 `import type` 语法，避免引入预期之外的副作用。
+:::
+
+在 CSR 项目中，`loader` 函数会在客户端执行，`loader` 函数内可以使用浏览器的 API。
+
+在 SSR 项目中，不管是首屏还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
+
+当在浏览器端导航时，基于[约定式路由](/guides/basic-features/routes/routes)，Modern.js 能够支持所有的 `loader` 函数并行执行（请求）。即当访问 `/user/profile` 时，`/user` 和 `/user/profile` 下的 `loader` 函数都会并行执行（请求），这种方式解决了部分请求、渲染瀑布流的问题，较大的提升了页面性能。
+
+:::tip
+`loader` 的职责是数据获取，入参已提供路由参数和请求信息，一般无需访问浏览器 API。建议保持环境无关性，以便未来使用 SSR。
+:::
+
+## `loader` 函数
+
+`loader` 函数有两个入参，分别用于获取路由参数和请求信息。
+
+### params
+
+`params` 是当路由为[动态路由](/guides/basic-features/routes/routes#动态路由)时的动态路由片段，会作为参数传入 `loader` 函数：
+
+```tsx title="routes/user/[id]/page.data.ts"
+import { LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+// 访问 /user/123 时，函数的参数为 `{ params: { id: '123' } }`
+export const loader = async ({ params }: LoaderFunctionArgs) => {
+  const { id } = params;
+  const res = await fetch(`https://api/user/${id}`);
+  return res.json();
+};
+```
+
+### request
+
+`request` 是一个 [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) 实例。一个常见的使用场景是通过 `request` 获取查询参数：
+
+```tsx
+import { LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+export const loader = async ({ request }: LoaderFunctionArgs) => {
+  const url = new URL(request.url);
+  const userId = url.searchParams.get('id');
+  return queryUser(userId);
+};
+```
+
+### 返回值
+
+`loader` 函数的返回值**只能是两种数据结构之一**，可序列化的数据对象或者 [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 实例：
+
+```tsx
+const loader = async (): Promise<ProfileData> => {
+  return {
+    message: 'hello world',
+  };
+};
+export default loader;
+```
+
+默认情况下，`loader` 返回的响应 `Content-type` 是 `application/json`，`status` 为 200，你可以通过自定义 `Response` 来设置：
+
+```tsx
+const loader = async (): Promise<ProfileData> => {
+  const data = { message: 'hello world' };
+  return new Response(JSON.stringify(data), {
+    status: 200,
+    headers: {
+      'Content-Type': 'application/json; utf-8',
+    },
+  });
+};
+```
+
+## 在不同环境使用 Data Loader
+
+`loader` 函数可能会在服务端或浏览器端执行。在服务端执行的 `loader` 函数，我们称为 Server Loader，在浏览器端执行的称为 Client Loader。
+
+在 CSR 应用中，`loader` 函数会在浏览器端执行，即默认都是 Client Loader。
+
+在 SSR 应用中，`loader` 函数只会在服务端执行，即默认都是 Server Loader。在 SSR 渲染时，Modern.js 会直接在服务端调用对应的 `loader` 函数。在浏览器端切换路由时，Modern.js 会发送一个 http 请求到 SSR 服务，同样在服务端触发 `loader` 函数。
+
+:::note
+SSR 应用的 `loader` 函数只在服务端执行可以带来以下好处：
+
+- **简化使用方式**：保证 SSR 应用获取数据的方式是同构的，开发者无需根据环境区分 `loader` 函数执行的代码。
+- **减少浏览器端 bundle 体积**：将逻辑代码及其依赖，从浏览器端移动到了服务端。
+- **提高可维护性**：将逻辑代码移动到服务端，减少了数据逻辑对前端 UI 的直接影响。此外，也避免了浏览器端 bundle 中误引入服务端依赖，或服务端 bundle 中误引入浏览器端依赖的问题。
+
+:::
+
+我们推荐在 `loader` 函数中使用 `fetch` API 发起请求。在 Modern.js 中默认对 `fetch` API 做了 polyfill，允许服务端使用该 API 发起请求，这意味你都可以在 CSR 和 SSR 时同构的获取数据：
+
+```tsx
+export async function loader() {
+  const res = await fetch('URL_ADDRESS');
+  const data = await res.json();
+  return {
+    message: data.message,
+  };
+}
+```
+
+## 错误处理
+
+### 基本用法
+
+在 `loader` 函数中，可以通过 `throw error` 或者 `throw response` 的方式处理错误，当 `loader` 函数中有错误被抛出时，Modern.js 会停止执行当前 `loader` 中的代码，并将前端 UI 切换到定义的 [`ErrorBoundary`](/guides/basic-features/routes/routes#错误处理) 组件：
+
+```tsx
+// routes/user/profile/page.data.ts
+export async function loader() {
+  const res = await fetch('https://api/user/profile');
+  if (!res.ok) {
+    throw res;
+  }
+  return res.json();
+}
+
+// routes/user/profile/error.tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError() as Response;
+  return (
+    <div>
+      <h1>{error.status}</h1>
+      <h2>{error.statusText}</h2>
+    </div>
+  );
+};
+
+export default ErrorBoundary;
+```
+
+### 修改 HTTP 状态码
+
+在 SSR 项目中你可以通过在 `loader` 函数中 `throw response` 的方式，控制页面的状态码，展示对应的 UI。
+
+如以下示例，页面的状态码将与这个 `response` 保持一致，页面也会展示为 `ErrorBoundary` 的 UI:
+
+```ts
+// routes/user/profile/page.data.ts
+export async function loader() {
+  const user = await fetchUser();
+  if (!user) {
+    throw new Response('The user was not found', { status: 404 });
+  }
+  return user;
+}
+
+// routes/error.tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError() as { data: string };
+  return <div className="error">{error.data}</div>;
+};
+
+export default ErrorBoundary;
+```
+
+:::tip
+`throw` 和上文介绍的 `return` Response 都可以修改状态码，区别是 `throw` 会进入 `ErrorBoundary`，而 `return` 不会。
+:::
+
+## 获取上层组件的数据
+
+很多场景下，子组件需要获取到上层组件 `loader` 中的数据，你可以通过 `useRouteLoaderData` 方便地获取到上层组件的数据：
+
+```tsx
+// routes/user/profile/page.tsx
+import { useRouteLoaderData } from '@modern-js/runtime/router';
+
+export function UserLayout() {
+  // 获取 routes/user/layout.data.ts 中 `loader` 返回的数据
+  const data = useRouteLoaderData('user/layout');
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <h2>{data.age}</h2>
+    </div>
+  );
+}
+```
+
+`userRouteLoaderData` 接受一个参数 `routeId`。在使用约定式路由时，Modern.js 会为你自动生成 `routeId`，`routeId` 的值是对应组件相对于 `src/routes` 的路径，如上面的例子中，子组件想要获取 `routes/user/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `user/layout`。
+
+在多入口场景下，`routeId` 的值需要加上对应入口的名称，入口名称非指定情况下一般是入口的目录名，如以下目录结构：
+
+```bash
+.
+└── src
+    ├── entry1
+    │     └── routes
+    │           └── layout.tsx
+    └── entry2
+          └── routes
+                └── layout.tsx
+```
+
+如果想获取 `entry1/routes/layout.tsx` 中 `loader` 返回的数据，`routeId` 的值就是 `entry1_layout`。
+
+## Loading UI (Experimental)
+
+:::info Experimental
+此功能当前是实验性功能，后续 API 可能有调整。
+:::
+
+创建 `user/layout.data.ts`，并添加以下代码：
+
+```ts title="routes/user/layout.data.ts"
+import { defer } from '@modern-js/runtime/router';
+
+export const loader = () =>
+  defer({
+    userInfo: new Promise(resolve => {
+      setTimeout(() => {
+        resolve({
+          age: 1,
+          name: 'user layout',
+        });
+      }, 1000);
+    }),
+  });
+```
+
+在 `user/layout.tsx` 中添加以下代码：
+
+```tsx title="routes/user/layout.tsx"
+import { Await, defer, useLoaderData, Outlet } from '@modern-js/runtime/router';
+
+export default function UserLayout() {
+  const { userInfo } = useLoaderData() as { userInfo: Promise<UserInfo> };
+  return (
+    <div>
+      <React.Suspense fallback={<p>Loading...</p>}>
+        <Await
+          resolve={userInfo}
+          children={userInfo => (
+            <div>
+              <span>{userInfo.name}</span>
+              <span>{userInfo.age}</span>
+              <Outlet />
+            </div>
+          )}
+        ></Await>
+      </React.Suspense>
+    </div>
+  );
+}
+```
+
+:::tip
+`<Await>` 组件的具体用法请查看 [Await](https://reactrouter.com/en/main/components/await)，`defer` 的具体用法请查看 [defer](https://reactrouter.com/en/main/guides/deferred)。
+:::
+
+## 数据缓存
+
+在路由导航时，Modern.js 只会加载路由变化的部分的数据。如当前路由是 `a/b`，`a` 路径对应的 Data Loader 已经执行过，当从 `/a/b` 跳转到 `/a/c`时，`a` 路径对应的 Data Loader 不会重新执行，`c` 路径对应的 Data Loader 会执行，并获取了数据。
+
+这种默认的优化策略避免了无效重复数据的请求。此时你可能会疑惑，如何更新 `a` 路径对应 Data Loader 的数据？
+
+在 Modern.js 中，以下几种情况，Modern.js 会重新加载对应路由路径的数据：
+
+1. 在 [Data Action](/guides/basic-features/data/data-write.md) 触发后
+2. URL 参数发生变化后
+3. 用户点击的链接与当前页面的 URL 相同
+4. 在路由组件中定义了 [`shouldRevalidate`](#/shouldrevalidate) 函数，该函数返回 `true`
+
+:::tip
+如果你在路由上定义了 [`shouldRevalidate`](#/shouldrevalidate) 函数，会先检查该函数，判断是否需要重新加载数据。
+:::
+
+### `shouldRevalidate`
+
+:::warning
+目前 `shouldRevalidate` 只会在 CSR 和 Streaming SSR 下生效。
+:::
+
+在路由组件（`layout.tsx`，`page.tsx`，`$.tsx`）中，我们可以导出一个 `shouldRevalidate` 函数。每次项目中的路由变化时，这个函数会被触发，该函数可以控制要重新加载哪些路由中的数据。如果这个函数返回 `true`，Modern.js 就会重新加载对应路由的数据。
+
+```ts title="routes/user/layout.tsx"
+import type { ShouldRevalidateFunction } from '@modern-js/runtime/router';
+export const shouldRevalidate: ShouldRevalidateFunction = ({
+  actionResult,
+  currentParams,
+  currentUrl,
+  defaultShouldRevalidate,
+  formAction,
+  formData,
+  formEncType,
+  formMethod,
+  nextParams,
+  nextUrl,
+}) => {
+  return true;
+};
+```
+
+:::tip
+`shouldRevalidate` 函数的更多信息可以参考 [react-router](https://reactrouter.com/start/data/route-object#shouldrevalidate)。
+:::
+
+## 错误用法
+
+1. `loader` 中只能返回可序列化的数据，在 SSR 环境下，`loader` 函数的返回值会被序列化为 JSON 字符串，然后在浏览器端被反序列化为对象。因此，`loader` 函数中不能返回不可序列化的数据（如函数）。
+
+:::warning
+目前 CSR 下没有这个限制，但我们强烈推荐你遵循该限制，且未来我们可能在 CSR 下也加上该限制。
+
+:::
+
+```ts
+// This won't work!
+export default () => {
+  return {
+    user: {},
+    method: () => {},
+  };
+};
+```
+
+2. Modern.js 会帮你调用 `loader` 函数，你不应该自己调用 `loader` 函数：
+
+```ts
+// This won't work!
+export const loader = async () => {
+  const res = fetch('https://api/user/profile');
+  return res.json();
+};
+
+import { loader } from './page.data.ts';
+export default function RouteComp() {
+  const data = loader();
+}
+```
+
+3. 不能从路由组件中引入 `loader` 文件，也不能从 `loader` 文件引入路由组件中的变量，如果需要共享类型的话，应该使用 `import type`
+
+```ts
+// Not allowed
+// routes/layout.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+import { ProfileData } from './page.data.ts'; // should use "import type" instead
+
+export const fetch = wrapFetch(fetch);
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+
+// routes/layout.data.ts
+import { fetch } from './layout.tsx'; // should not be imported from the routing component
+export type ProfileData = {
+  /*  some types */
+};
+
+export const loader = async (): Promise<ProfileData> => {
+  const res = await fetch('https://api/user/profile');
+  return await res.json();
+};
+```
+
+4. 在服务端运行时，`loader` 函数会被打包为一个统一的 bundle，所以我们不推荐服务端的代码使用 `__filename` 和 `__dirname`。
+
+## 常见问题
+
+1. `loader` 和 BFF 函数的关系是什么？
+
+在 CSR 项目中，`loader` 在浏览器端执行，在 `loader` 可以直接调用 BFF 函数进行接口请求。
+
+在 SSR 项目中，每个 `loader` 也是一个服务端接口。我们推荐使用 `loader` 替代 HTTP Method 为 GET 的 BFF 函数，避免多一层转发和执行。

package/docs/zh/guides/basic-features/data/data-write.mdx

@@ -0,0 +1,234 @@
+---
+title: 数据写入
+sidebar_position: 4
+---
+
+# 数据写入
+
+在[数据获取](/guides/basic-features/data/data-fetch)章节中，介绍了 Modern.js 获取数据的方式，你可能会遇到两个问题：
+
+1. 如何更新 Data Loader 返回的数据？
+2. 如何将新的数据传递到服务器?
+
+在 Modern.js 中，可以通过 Data Action 解决和实现。
+
+## 什么是 Data Action
+
+Modern.js 推荐使用[约定式路由](/guides/basic-features/routes/routes)做路由的管理，每个路由组件（`layout.ts`，`page.ts` 或 `$.tsx`）都可以有一个同名的 `.data` 文件。这些文件可以导出一个 `action` 函数，我们称为 Data Action，开发者可以在合适的时机调用它：
+
+```bash
+.
+└── routes
+    └── user
+        ├── layout.tsx
+        └── layout.data.ts
+```
+
+在 `routes/user/layout.data.ts` 文件中，可以导出一个 Data Action 函数：
+
+```ts title="routes/user/layout.data.ts"
+import type { ActionFunction } from '@modern-js/runtime/router';
+
+export const action: ActionFunction = async ({ request }) => {
+  const newUser = await request.json();
+  const name = newUser.name;
+  return updateUserProfile(name);
+}
+```
+
+在路由组件中，你可以通过 `useFetcher` 获取对应 `submit` 函数，执行并触发 Data Action：
+
+```tsx title="routes/user/layout.tsx"
+import {
+  useFetcher,
+  useLoaderData,
+  useParams,
+  Outlet
+} from '@modern-js/runtime/router';
+
+export default () => {
+  const userInfo = useLoaderData();
+  const { submit } = useFetcher();
+  const editUser = () => {
+    const newUser = {
+      name: 'Modern.js'
+    }
+    return submit(newUser, {
+      method: 'post',
+      encType: 'application/json',
+    })
+  }
+  return (
+    <div>
+      <button onClick={editUser}>edit user</button>
+      <div className="user-profile">
+        {userInfo}
+      </div>
+      <Outlet context={userInfo}></Outlet>
+    </div>
+  )
+}
+```
+
+当执行 `submit` 后，会触发定义的 `action` 函数。在 `action` 函数中，可以通过[入参](/guides/basic-features/data/data-write.html#入参)获取提交的数据，最终发送数据到服务端。
+
+`action` 函数执行完后，Modern.js 将自动执行 `loader` 函数代码，并更新对应的数据和视图。
+
+![action flow](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-flow.png)
+
+## `action` 函数
+
+与 `loader` 函数一样，`action` 函数有两个入参，`params` 和 `request`。
+
+### params
+
+`params` 是当路由为[动态路由](/guides/basic-features/routes/routes#动态路由)时动态路由片段，会作为参数传入 `action` 函数：
+
+```tsx title="routes/user/[id]/page.data.ts"
+import { ActionFunctionArgs } from '@modern-js/runtime/router';
+
+// 访问 /user/123 时，函数的参数为 `{ params: { id: '123' } }`
+export const action = async ({ params }: ActionFunctionArgs) => {
+  const { id } = params;
+  const res = await fetch(`https://api/user/${id}`);
+  return res.json();
+};
+```
+
+### request
+
+`request` 是一个 [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) 实例。通过 `request`，可以在 action 函数中获取到浏览器端提交的数据，如 `request.json()`，`request.formData()`，`request.text()` 等。具体使用哪个 API，请参考[数据类型](#数据类型)。
+
+```tsx title="routes/user/[id]/page.data.ts"
+import { ActionFunctionArgs } from '@modern-js/runtime/router';
+
+export const action = async ({ request }: ActionFunctionArgs) => {
+  const newUser = await request.json();
+  return updateUser(newUser);
+};
+```
+
+### 返回值
+
+`action` 函数的返回值可以是任何可序列化的内容，也可以是一个 [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 实例，
+可以通过 [`useActionData`](https://reactrouter.com/en/main/hooks/use-action-data) 访问 response 中内容。
+
+## useSubmit 和 useFetcher
+
+### 区别
+
+你可以通过 [`useSubmit`](https://reactrouter.com/en/main/hooks/use-submit) 或 [`useFetcher`](https://reactrouter.com/en/main/hooks/use-fetcher) 调用 Data Action。它们的区别是通过
+`useSubmit` 调用，会触发浏览器的导航，通过 `useFetcher` 则不会触发浏览器的导航。
+
+useSubmit:
+
+```ts
+const submit = useSubmit();
+submit(null, { method: "post", action: "/logout" });
+```
+
+useFetcher:
+
+```ts
+const { submit } = useFetcher();
+submit(null, { method: "post", action: "/logout" });
+```
+
+`submit` 函数有两个入参，第一个入参是传递到服务端的 `formData`。第二个入参是可选参数，其中
+- `method` 相当于表单提交时的 `method`，大部分写入数据的场景下，`method` 可以传入 `post`。
+- `action` 用来指定触发哪个路由组件的 Data Action，如果未传入 `action` 入参，默认会触发当前路由组件的 action，即 `user/page.tsx` 组件或子组件中执行 submit，会触发 `user/page.data.ts` 中定义的 action。
+
+:::info
+
+更多 API 的信息可参考相关文档：[`useSubmit`](https://reactrouter.com/en/main/hooks/use-submit)、[`useFetcher`](https://reactrouter.com/en/main/hooks/use-fetcher)。
+
+:::
+
+
+### 数据类型
+
+`submit` 函数的第一个入参，可以接受不同类型的值。
+
+如 `FormData`：
+
+```ts
+let formData = new FormData();
+formData.append("cheese", "gouda");
+submit(formData);
+// In the action, you can get the data by request.json
+```
+
+或 `URLSearchParams` 类型的值：
+
+```ts
+let searchParams = new URLSearchParams();
+searchParams.append("cheese", "gouda");
+submit(searchParams);
+// In the action, you can get the data by request.json
+```
+
+或任意 `URLSearchParams` 构造函数可接受的值：
+
+```ts
+submit("cheese=gouda&toasted=yes");
+submit([
+  ["cheese", "gouda"],
+  ["toasted", "yes"],
+]);
+// In the action, you can get the data by request.json
+```
+
+默认情况下，如果 `submit` 函数中的第一个入参是一个对象，对应的数据会被 encode 为 `formData`：
+
+```ts
+submit(
+  { key: "value" },
+  {
+    method: "post",
+    encType: "application/x-www-form-urlencoded",
+  }
+);
+
+// In the action, you can get the data by request.formData
+```
+
+你也可以通过第二个参数，指定为编码方式：
+
+```tsx
+submit(
+  { key: "value" },
+  { method: "post", encType: "application/json" }
+);
+
+submit('{"key":"value"}', {
+  method: "post",
+  encType: "application/json",
+});
+
+// In the action, you can get the data by request.json
+```
+
+或提交纯文本：
+
+```ts
+submit("value", { method: "post", encType: "text/plain" });
+// In the action, you can get the data by request.text
+```
+
+## 为什么要提供 Data Action
+
+Modern.js 中提供 Data Action 主要是为了使 UI 和服务器的状态能保持同步，通过这种方式可以减少状态管理的负担，
+传统的状态管理方式，会在浏览器端和远程分别持有状态：
+
+![traditional state manage](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-state-manage.png)
+
+而在 Modern.js 中，我们希望通过 Loader 和 Action 帮助开发者自动的同步浏览器端和服务端的状态：
+
+![state manage](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-state-manage1.png)
+
+如果项目中组件共享的数据主要来自于服务端的状态，则无需在项目引入浏览器端状态管理库。可以使用 Data Loader 请求数据，通过 [`useRouteLoaderData`](/guides/basic-features/data/data-fetch.md) 在子组件中共享数据，使用 Data Action 修改和同步服务端的状态。
+
+
+## CSR 和 SSR
+
+与 Data Loader 一样，SSR 项目中，Data Action 是在服务端执行的（框架会自动发请求触发 Data Action），而在 CSR 项目中，Data Action 是在浏览器端执行的。

package/docs/zh/guides/basic-features/debug/_meta.json

@@ -0,0 +1 @@
+["mock", "proxy", "rsdoctor", "using-storybook"]