@modern-js/main-doc 2.1.0 → 2.2.0

package/zh/guides/advanced-features/bff/frameworks.mdx

@@ -0,0 +1,152 @@
+---
+sidebar_position: 3
+title: 运行时框架
+---
+# 运行时框架
+
+Modern.js 的 BFF 支持不同的运行时框架，当前 Modern.js 的 BFF 支持两种运行时框架 [Express.js](https://expressjs.com/) 和 [Koa.js](https://koajs.com/)。
+
+## 函数写法
+
+在函数写法下，各类运行时框架仅中间件写法存在差异，其他实现基本相同。这里以 Express 为例，介绍如何在 `api/_app.ts` 中，手写一个中间件，添加权限校验：
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+import { Request, Response, NextFunction } from 'express';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req: Request, res: Response, next: NextFunction) => {
+    if (req.url !== '/api/login') {
+      const sid = req?.cookies?.sid;
+      if (!sid) {
+        res.status(400);
+        res.json({ code: -1, message: 'need login' });
+      } else {
+        next();
+      }
+    } else {
+      next();
+    }
+  });
+});
+```
+
+然后添加一个普通的 BFF 函数 `/api/hello.ts`：
+
+```ts
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+最后在前端 `src/App.tsx` 添加接口的访问代码，直接使用一体化的方式调用：
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchMyApi() {
+      const { message } = await hello();
+      setText(message);
+    }
+
+    fetchMyApi();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+然后 `pnpm run dev` 启动项目，访问 `http://localhost:8080/` 会发现 `/api/hello` 的请求被拦截了：
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+
+最后再修改前端代码 `src/App.tsx`，在访问 `/api/hello` 前先调用登录接口：
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+import { post as login } from '@api/login';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchAfterLogin() {
+      const { code } = await login();
+      if (code === 0) {
+        const { message } = await hello();
+        setText(message);
+      }
+    }
+    fetchAfterLogin();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+刷新页面，可以看到 `/api/hello` 访问成功：
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
+
+以上代码模拟了在 `/api/_app.ts` 中添加中间件的方式，实现了简易的登录功能。同样，可以在这个钩子文件中实现其他功能来扩展 BFF Server。
+
+## 框架写法
+
+框架写法下，Modern.js 不会收集 `api/_app.ts` 中的中间件，运行流程由插件自行控制。
+
+### Express
+
+Express 的框架写法支持可在 `api/app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，甚至扩展原有框架等。
+
+BFF 函数定义的路由会在 `app.ts` 文件定义的路由之后注册，所以在这里你也可以拦截 BFF 函数定义的路由，进行预处理或是提前响应。
+
+```ts title="api/app.ts"
+import express from 'express';
+
+const app = express();
+
+app.put('/user', function (req, res) {
+  res.send('Got a PUT request at /user');
+});
+
+app.use(async (req, res, next) => {
+  console.info(`access url: ${req.url}`);
+  next();
+});
+
+export default app;
+```
+
+### Koa
+
+Koa 框架写法与 Express 类似，支持在 `app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，扩展原有框架等。
+
+BFF 函数定义的路由会在 `app.ts` 文件定义的路由之后注册，所以在这里你也可以拦截 BFF 函数定义的路由，进行预处理或是提前响应。
+
+:::caution 注意
+在框架写法下，当没有 `app.ts` 的时候，Modern.js 默认会添加 `koa-body`；当有 `app.ts` 时，如果开发者希望使用带有 Body 的 BFF 函数，需要确保 `koa-body` 中间件已经添加。
+
+:::
+
+```ts title=api/app.ts
+import koa from 'koa';
+
+const app = new Koa();
+
+app.put('/user', function (req, res) {
+  res.send('Got a PUT request at /user');
+});
+
+app.use(async (ctx, next) => {
+  console.info(`access url: ${ctx.url}`);
+  await next();
+});
+
+export default app;
+```

package/zh/guides/advanced-features/bff/function.mdx

@@ -0,0 +1,253 @@
+---
+sidebar_position: 1
+title: 基础用法
+---
+# 基础用法
+
+通过 Modern.js 开发的应用，可以在 `api/` 目录下定义接口函数，前端可以调用这些接口函数，即可发起请求，无需写前后端胶水层代码，同时保证前后端类型安全。
+
+## 启用 BFF
+
+import EnableBFF from "@site-docs/components/enable-bff"
+
+<EnableBFF/>
+
+## BFF 函数
+
+允许通过一体化调用的函数，称为 **BFF 函数**。这里写一个最简单的 BFF 函数，创建 `api/hello.ts` 文件：
+
+:::caution
+如果是框架模式（有 `api/lambda` 目录），需要创建 `api/lambda/hello.ts`
+
+:::
+
+```ts title="api/hello.ts"
+export const get = async () => 'Hello Modern.js';
+```
+
+接着在 `src/App.tsx` 中直接引入函数并调用：
+
+```tsx title=src/App.tsx
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    hello().then(setText);
+  }, []);
+  return <div>{text}</div>;
+};
+```
+
+:::info 注
+Modern.js 生成器已经在 `tsconfig.json` 中配置 `@api` 别名，因此可以直接通过别名的方式引入函数。
+
+:::
+
+在 `src/App.tsx` 中引入的函数，会自动转换成接口调用，不需要再去通过 fetch 去调用接口。
+
+执行 `pnpm run dev` 打开 `http://localhost:8080/` 可以看到页面已经展示了 BFF 函数返回的内容，在 Network 中可以看到页面向 `http://localhost:8080/api/hello` 发送了请求：
+
+![Network](https://p6-piu.byteimg.com/tos-cn-i-8jisjyls3a/fd41750f8d414179a9b4ecb519919b36~tplv-8jisjyls3a-3:0:0:q75.png)
+
+## 函数路由
+
+Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，也是一种**约定式路由**。
+
+函数写法下 `api/` 下的所有文件中的每个 BFF 函数都会映射为一个接口。框架写法下 `api/lambda` 下的所有文件中的每个 BFF 函数都会映射为一个接口。
+
+:::note
+函数写法和框架写法会在下一节详细介绍。
+
+:::
+
+所有 BFF 函数生成的路由都带有统一的前缀，默认值为 `/api`。可以通过 [bff.prefix](/configure/app/bff/prefix) 设置公共路由的前缀。
+
+下面介绍几种路由的约定。
+
+### 默认路由
+
+以 `index.[jt]s` 命名的文件会被映射到上一层目录。
+
+- `api/index.ts` -> `{prefix}/`
+- `api/user/index.ts` -> `{prefix}/user`
+
+### 多层路由
+
+支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。
+
+- `api/hello.ts` -> `{prefix}/hello`
+- `api/user/list.ts` -> `{prefix}/user/list`
+
+### 动态路由
+
+同样的，创建命名带有 `[xxx]` 的文件夹或者文件，支持动态的命名路由参数。动态路由的函数参数规则可以看 [dynamac-path](/guides/advanced-features/bff/function#dynamic-path)
+
+- `api/user/[username]/info.ts` -> `{prefix}/user/:username/info`
+- `api/user/username/[action].ts` -> `{prefix}/user/username/:action`
+
+### 白名单
+
+默认 `api/` 目录下所有文件都会当作 BFF 函数文件去解析，但以下文件不会被解析：
+
+- 命名以 `_` 开头的文件。例如：`_utils.ts`。
+- 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
+- 测试文件。例如：`foo.test.ts`。
+- TypeScript 类型文件。例如：`hello.d.ts`。
+- `node_module` 下的文件。
+
+## RESTful API
+
+Modern.js 的 BFF 函数需要遵循 RESTful API 标准来定义, 遵循 HTTP Method 规范，并且不允许自由定义参数。
+
+:::info 注
+假设函数允许自由定义参数，产出的路由必然由**私有协议**进行调用（原因是无法区分请求参数与请求体），而无法实现任意的 RESTful API。
+
+如果服务仅用于应用本身不存在问题，但它**不标准的接口定义**无法融入更大的体系。 在多个系统共同工作的情况下（例如 BFF 低码搭建），会导致其他系统也需要遵循**私有协议**。
+
+:::
+
+### 函数具名导出
+
+Modern.js BFF 函数的导出名决定了函数对应接口的 Method，如 `get`，`post` 等。
+
+例如，按照以下例子，可导出一个 GET 接口。
+
+```ts
+export const get = async () => {
+  return {
+    name: 'Modern.js',
+    desc: '现代 web 工程方案',
+  };
+};
+```
+
+按照以下例子，则可导出一个 `POST` 接口
+
+```ts
+export const post = async () => {
+  return {
+    name: 'Modern.js',
+    desc: '现代 web 工程方案',
+  };
+};
+```
+
+- 对应 HTTP Method，Modern.js 也支持了 9 种定义，即：`GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`，即可以用这些 Method 作为函数导出的名字。
+
+- 名字是大小不敏感的，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。
+
+- 可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
+
+:::info 注
+需要注意的是，定义的函数都应该是异步的，与函数调用时类型有关，后面会提到。
+
+:::
+
+### 函数参数规则
+
+如上所述，为了满足 RESTful API 的设计标准，因此 Modern.js 中 BFF 函数需要遵循一定的入参规则。
+
+函数参数分为两块，分别是请求路径中的动态部分和请求选项 `RequestOption`。
+
+#### Dynamic Path
+
+动态路由会作为函数第一部分的入参，每个入参对应一段动态路由。例如以下示例，uid 会作为前两个参数传递到函数中：
+
+```ts title="api/[level]/[id].ts"
+export default async (level: number, id: number) => {
+  const userData = await queryUser(level, uid);
+  return userData;
+};
+```
+
+在调用时直接传入动态参数：
+
+```ts title="App.tsx"
+import { useState, useEffect } from 'react';
+import { get as getUser } from '@api/[level]/[id]';
+
+export default () => {
+  const [name, setName] = useState('');
+
+  useEffect(() => {
+    getUser(6, 001).then(userData => setName(userData.name));
+  }, []);
+
+  return <div>{name}</div>;
+};
+```
+
+#### RequestOption
+
+Dynamic Path 之后的参数是包含 querystring、request body 的对象 `RequestOption`，这个字段用来定义 `data` 和 `query` 的类型。
+
+在不存在动态路由的普通函数中，可以从第一个入参中获取传入的 `data` 和 `query`，例如：
+
+```ts title="api/hello.ts"
+import type { RequestOption } from '@modern-js/runtime/server';
+
+export async function post({
+  query,
+  data,
+}: RequestOption<Record<string, string>, Record<string, string>>) {
+  // do somethings
+}
+```
+
+这里你也可以使用自定义类型：
+
+```ts title="api/lambda/hello.ts"
+import type { RequestOption } from '@modern-js/runtime/server';
+
+type IQuery = {
+  // some types
+};
+type IData = {
+  // some types
+};
+
+export async function post({ query, data }: { query: IQuery; data: IData }) {
+  // do somethings
+}
+```
+
+当函数文件使用动态路由规则时，动态路由会在 `RequestOption` 对象参数前。
+
+```ts title="api/[sku]/[id]/item.ts"
+export async function post(
+  sku: string,
+  id: string,
+  {
+    data,
+    query,
+  }: RequestOption<Record<string, string>, Record<string, string>>,
+) {
+  // do somethings
+}
+```
+
+调用时也按照函数定义，传入对应的参数即可：
+
+```ts title="App.tsx"
+import { post } from '@api/[sku]/[id]/item';
+
+export default () => {
+  const addSku = () => {
+    post('0001' /* sku */, '1234' /* id */, {
+      query: {
+        /* ... */
+      },
+      data: {
+        /* ... */
+      },
+    });
+  };
+
+  return <div onClick={addSku}>添加 SKU</div>;
+};
+```
+
+之前提到，定义的函数都应该是异步的，是因为在前端调用时会自动转换成 HTTP 接口调用，所以为了保持类型定义与实际调用体验统一，需要在定义 BFF 函数时将它设置为异步。

package/zh/guides/advanced-features/bff/index.mdx

@@ -0,0 +1,21 @@
+---
+title: BFF
+---
+# BFF
+
+在**前后端分离**概念出现后一段时间发展中，前端部分能够做的事越来越多，前端需要一些面向 UI 的数据接口，因此业界引入了 BFF（Backends for Frontends）这一概念。
+
+它主要为了解决的问题包括：
+
+- 根据自身业务需求，对更底层 API 的聚合、映射、裁剪、代理。
+- 对一些特定场景的数据进行缓存，提高性能，进而提升用户体验。
+- 根据已有接口快速开发新产品。
+- 与第三方系统对接，例如登陆鉴权。
+
+Modern.js 官方支持了 BFF，并提供了**一体化 BFF 方案**来进一步强化 BFF 能力，主要包括以下能力：
+
+- 快速开发调试上线，在同一项目中运行、构建、部署 BFF 代码。
+- 极简的纯函数调用，在前端直接 import BFF 函数，调用时能自动转换成 HTTP 请求。
+- 无私有协议，遵循 RESTful API 规范，所有 BFF 接口都是标准化的。
+- 完善的 TypeScript 支持。
+- 满足用户使用偏好，支持多框架扩展写法。

package/zh/guides/advanced-features/bff/type.mdx

@@ -0,0 +1,46 @@
+---
+sidebar_position: 2
+title: 函数写法 & 框架写法
+---
+# 函数写法 & 框架写法
+
+运行时框架支持也是 **BFF** 中重要的一环。Modern.js 支持通过插件扩展 BFF 的运行时框架，并提供了一系列内置插件，开发者可以直接使用对应框架的约定和生态。
+
+插件中兼容了这些框架大部分的规范，每一种框架都需要提供两类扩展写法 BFF 函数的方式，分别是**函数写法**和**框架写法**。
+
+:::note
+当前 `api/` 目录结构是否为框架写法由对应的插件决定，Modern.js 并不关心。
+
+:::
+
+## 函数写法
+
+当插件认为当前为函数写法时，必须支持在 `api/_app.ts` 中编写中间件，用来扩展 BFF 函数。
+
+Modern.js 会收集 `api/_app.ts` 中的中间件，并传递给插件，由插件将中间件注入运行时，例如：
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(myMiddleware);
+});
+```
+
+:::note
+不同插件的中间件的写法不一定相同，详情可见[运行时框架](/guides/advanced-features/bff/frameworks)。
+
+:::
+
+## 框架写法
+
+框架写法是一种使用框架结构来扩展 BFF 函数的方式。和函数写法相比，框架写法虽然能够利用更多框架的结构，在复杂场景下让整个 BFF Server 更加清晰，但也相的更加复杂，需要关心更多框架层面的内容。
+
+框架写法中，所有的 BFF 函数都需要写在 `api/lambda/` 目录下，并且无法使用钩子文件 `_app.[tj]s`。
+
+多数情况下，函数写法就能覆盖大多数 BFF 函数的定制需求。只有当你的项目服务端逻辑比较复杂，代码需要分层，或者需要使用更多框架的元素时，才需要使用框架写法。
+
+:::note
+不同插件框架写法的目录结构不一定相同，详情可见[运行时框架](/guides/advanced-features/bff/frameworks)。
+
+:::

package/zh/guides/advanced-features/code-split.mdx

@@ -0,0 +1,80 @@
+---
+title: 代码分割
+sidebar_position: 6
+---
+# 代码分割
+
+代码分割是优化前端资源加载的一种常用手段，本文将介绍 Modern.js 支持的三种代码分割方式：
+
+:::info
+使用 Modern.js [约定式路由](/guides/basic-features/routes#约定式路由)时，默认会根据路由组件做代码分割，包裹 `Suspense` 组件，无需自行进行代码分割。
+
+:::
+
+- `import`
+- `React.lazy`
+- `loadable`
+
+## import
+
+使用动态 `import()` 语法，`import` 接收的 JS 模块将作为一个新的打包入口被打包到单独的 JS 文件中。例如：
+
+```ts
+import('./math').then(math => {
+  console.log(math.add(16, 26));
+});
+```
+
+`./math` 路径对应的 JS 模块会被打包到单独的 JS 文件中。
+
+## React.lazy
+
+React 官方提供的组件代码分割的方式。
+
+:::caution
+React 17 及以下版本不支持 SSR，建议 React17 的 SSR 应用使用 loadable。
+
+:::
+
+```ts
+import React, { Suspense } from 'react';
+
+const OtherComponent = React.lazy(() => import('./OtherComponent'));
+const AnotherComponent = React.lazy(() => import('./AnotherComponent'));
+
+function MyComponent() {
+  return (
+    <div>
+      <Suspense fallback={<div>Loading...</div>}>
+        <section>
+          <OtherComponent />
+          <AnotherComponent />
+        </section>
+      </Suspense>
+    </div>
+  );
+}
+```
+
+`React.lazy` 更多用法请见 [React lazy](https://zh-hans.reactjs.org/docs/code-splitting.html#reactlazy)。
+
+## loadable
+
+使用 `loadable` API，示例如下：
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+
+const OtherComponent = loadable(() => import('./OtherComponent'));
+
+function MyComponent() {
+  return <OtherComponent />;
+}
+```
+
+`loadable` 更多用法请见 [loadable API](/apis/app/runtime/utility/loadable)。
+
+:::info 注
+`loadable` 开箱即用的支持 SSR，但不支持和 Suspense 一起使用，如果是 CSR 项目可以使用 [loadable.lazy](https://loadable-components.com/docs/suspense/)
+
+:::

package/zh/guides/advanced-features/compatibility.mdx

@@ -0,0 +1,77 @@
+---
+title: 客户端兼容性
+sidebar_position: 5
+---
+# 客户端兼容性
+
+## Browserslist 配置
+
+Modern.js 支持在项目根目录 `package.json` 文件中的 `browserslist` 字段（或单独的 `.browserslistrc` 文件）指定项目覆盖的目标浏览器范围。该值会被 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 和 [`autoprefixer`](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
+
+Modern.js 中默认值如下:
+
+```js
+['> 0.01%', 'not dead', 'not op_mini all'];
+```
+
+可以在[这里](https://github.com/browserslist/browserslist)了解如何自定义浏览器范围。
+
+查看 Modern.js Builder 文档了解更多 [Browserslist](https://modernjs.dev/builder/guide/advanced/browserslist.html) 相关内容。
+
+:::note
+Modern.js 支持配置 [output.overrideBrowserslist](/configure/app/output/override-browserslist) 覆盖默认 browserslist 值。
+
+:::
+
+## Polyfill
+
+### 编译时 Polyfill
+
+Modern.js 在编译时默认通过 [core-js](https://github.com/zloirock/core-js) 引入对应的 Polyfill 代码。
+
+默认情况下会根据项目 Browserslist 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。
+
+:::info 注
+对于明确第三方依赖不需要 Polyfill 的场景，可以设置 [`output.polyfill`](/configure/app/output/polyfill) 为 `usage`, 这样 Babel 编译时只会根据代码中使用到的语法引入 Polyfill 代码。
+
+:::
+
+### 运行时按需 Polyfill
+
+Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，相比于 Babel 优势如下：
+
+- 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
+- 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。
+
+可以通过微生成器开启该功能：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「基于 UA 的 Polyfill」功能
+```
+
+执行命令后，在 `modern.config.ts` 中注册 Polyfill 插件:
+
+```ts title="modern.config.ts"
+import polyfillPlugin from '@modern-js/plugin-polyfill';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  plugins: [..., polyfillPlugin()],
+});
+```
+
+配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
+
+```js
+<script src="/__polyfill__" crossorigin></script>
+```
+
+在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:
+
+![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
+
+:::caution 注意
+该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。
+
+:::