@modern-js/main-doc 0.0.0-next-20221116121040

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

@@ -0,0 +1,348 @@
+---
+sidebar_position: 4
+title: 运行时框架
+---
+
+如前面章节所说，目前 Modern.js 的 BFF 支持 4 种主流的 Server 框架，可以根据自身偏好选择。
+
+多框架支持也是【 一体化 BFF 】中重要的一环，多数情况下，开发者直接使用钩子文件来扩展 BFF 函数，无需关心通过框架启动服务、日志输出等应用级别的问题。
+
+所有框架均支持 BFF 函数的所有能力，并且使用方式是相同的，例如：
+
+- RESTful API
+- Schema 模式
+- Hooks(useContext)
+- 不同的数据类型
+- 动态路由
+- 一体化调用
+
+Modern.js BFF 中兼容了这些框架大部分的规范，开发者可以直接使用对应 Server 框架的约定和生态。
+
+每一种框架都提供了两类扩展写法 BFF 函数的方式，分别是【 函数写法 】和【 框架写法 】。
+
+## 函数写法
+
+在上一章节中，简单的演示了 Express 扩展 BFF 函数的示例。
+
+函数写法就是通过添加钩子文件 `_app.ts` 的方式，编写中间件逻辑来扩展 BFF 函数。
+
+### [Express](https://expressjs.com/)
+
+Express 的函数写法，可以通过在 `_app.[tj]s` 下添加 `express` 的中间件：
+
+```ts
+import { hook } from "@modern-js/runtime/server";
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req, res, next) => {
+    req.query.id = "express";
+    await next();
+  });
+});
+```
+
+### [Nest](https://nestjs.com/)
+
+Nest 支持添加两种类型的内容：Express 的函数中间件和 Nest 中的 [Module](https:/docs.nestjs.com/modules)。
+
+Nest 的函数中间件的添加与 Express 段中的示例相同，Module 写法如下：
+
+```ts title=api/_app.ts
+import { hook } from "@modern-js/runtime/server";
+import { Module, Injectable, Controller, Get } from "@nestjs/common";
+
+@Controller("cats")
+export class CatsController {
+  constructor(private readonly catsService: CatsService) {}
+
+  @Get()
+  getHello() {
+    return this.catsService.getHello();
+  }
+}
+
+@Injectable()
+class CatsService {
+  getHello(): string {
+    return "Hello world!";
+  }
+}
+
+@Module({
+  controllers: [CatsController],
+  providers: [CatsService],
+})
+class CatsModule {}
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(CatsModule);
+});
+```
+
+### [Koa](https://koajs.com/)
+
+Koa 函数写法下，可以通过在 `_app.[tj]s` 下添加 koa 的中间件：
+
+```ts
+import { hook } from "@modern-js/runtime/server";
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx, next) => {
+    console.info(`access url: ${ctx.url}`);
+    next();
+  });
+});
+```
+
+### [Egg](https://eggjs.org/)
+
+Egg 函数写法下，可以通过在 `_app.[tj]s` 下添加 egg 的中间件：
+
+```ts
+import { hook } from "@modern-js/runtime/server";
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware((options) => async (ctx, next) => {
+    console.info(`access url: ${ctx.url}`);
+    next();
+  });
+});
+```
+
+也可以添加 egg 第三方的中间件，且给第三方中间件注入参数：
+
+```ts
+import { hook } from "@modern-js/runtime/server";
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware([
+    "eggMiddleware", // 此处为包名
+    {
+      name: "modernjs",
+    },
+  ]);
+});
+```
+
+## 框架写法
+
+框架写法是一种使用框架分层结构来扩展 BFF 函数的方式。
+
+和函数写法相比，框架写法虽然能够利用更多框架的结构，在复杂场景下让整个 BFF Server 更加清晰，但也相的更加复杂，需要关心更多框架层面的内容。
+
+:::info 注
+多数情况下，函数写法就能覆盖大多数 BFF 函数的定制需求。只有当你的项目服务端逻辑比较复杂，代码需要分层，或者需要使用更多框架的元素时（如 egg 插件），才需要使用框架写法。
+:::
+
+框架写法中，所有的 BFF 函数都需要写在 `api/lambda/` 目录下，并且无法使用钩子文件 `_app.[tj]s`。
+
+### Express
+
+Express 的框架写法支持可在 `api/app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，甚至扩展原有框架等。
+
+:::info 注
+注意这里是 `app.[tj]s`，而不是函数写法中的钩子文件 `_app.[tj]s`。
+:::
+
+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;
+```
+
+如果需要在 BFF 函数注册路由后添加中间件，错误处理等，可以使用 [`afterLambdaRegisted`](/docs/apis/app/runtime/bff-server/after-lambda-registed) hook，该 hook 中的代码会在 BFF 函数注册路由后执行：
+```ts title="api/app.ts"
+const app = express();
+// 其他代码...
+export default app;
+
+export const afterLambdaRegisted = (app: Express) => {
+  const errorHandler = (
+    err: Error,
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ) => {
+    if (res.headersSent) {
+      return next(err);
+    }
+    res.status(500).send('some error message');
+  }
+  app.use(errHandler);
+}
+```
+
+### Nest
+
+Nest 虽然有定制的启动器，但本质与 Express、Koa 相同，所以 Modern.js 沿用了 Nest 定制启动器的默认入口：`api/main.ts`。
+
+按照 Nest 官方生成器生成的项目结构，在 Modern.js 中使用 Nest 框架写法时，`api/` 目录结构为：
+
+```markdown
+.
+├── app.controller.ts
+├── app.module.ts
+├── app.service.ts
+├── lambda
+│ └── hello.ts
+└── main.ts
+```
+
+其中 `api/main.ts` 中的内容与 Nest 官方生成器生成模版有所不同，应用工程中支持了两种模式：
+
+不包含内置 Module：
+
+```ts title=api/main.ts
+import { defineCustom } from "@modern-js/plugin-nest";
+import { NestFactory } from "@nestjs/core";
+import { Module } from "@nestjs/common";
+import { AppModule } from "./app.module";
+
+export default NestFactory.create(AppModule);
+```
+
+包含内置 Module：
+
+```ts title=api/main.ts
+import { defineCustom } from "@modern-js/plugin-nest";
+import { NestFactory } from "@nestjs/core";
+import { Module } from "@nestjs/common";
+import { AppModule } from "./app.module";
+
+export default defineCustom(async (modules) => {
+  @Module({
+    imports: [AppModule, ...modules],
+  })
+  class MainModule {}
+
+  return NestFactory.create(MainModule);
+});
+```
+
+### Koa
+
+Koa 框架写法与 Express 类似，支持在 `app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，扩展原有框架等。
+
+:::info 注
+注意这里是 `app.[tj]s`，而不是函数写法中的钩子文件 `_app.[tj]s`。
+:::
+
+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;
+```
+
+### Egg
+
+#### 目录结构
+
+Modern.js 在 egg 框架写法中添加的初始样板文件较为简单，但 Modern.js 允许开发者使用 egg 框架约定的几乎所有文件（如中间件，定时器，控制器等）。
+
+```bash title="egg 框架写法的初始结构"
+.
+├── api/
+│   ├── app/
+│   │   └── middleware/
+│   │       └── trace.ts
+│   ├── config/
+│   │   └──  config.default.ts
+│   └── lambda/
+│       └── hello.ts
+├── src/
+├── modern.config.js
+├── package.json
+├── pnpm-lock.yaml
+├── tsconfig.json
+```
+
+#### Modern.js 的 一体化 BFF 函数 和 egg 中的 controller 有什么不同？
+
+- `lambda/` 下的 BFF 函数文件拥有定义路由和处理 API 逻辑两种功能，当你写一体化 BFF 函数的时候；就无需再写 controller 和 router。
+- `lambda/` 目录通过文件的目录结构定义路由，Egg 通过在 `router.ts` 文件编写代码定义路由。
+- `lambda/` 下可以写 BFF 函数，去处理 BFF 的逻辑；Egg 需要定义 class 声明 `controller`，BFF 函数的样板代码更少。
+- `lambda/` 下的文件可以使用 Modern.js 提供的 BFF API，如 `useContext`。
+- `lambda/` 下的 BFF 函数可以和 `egg` 的 `router`，`controller` 等混合使用，但通常不建议这么做。
+
+#### 调用 service
+
+在 egg 的框架写法下，同 egg 框架的使用方式一致，开发者也可以通过 `ctx` 调用定义的 service。
+
+假设有以下目录结构和文件：
+
+```js {4-5}
+.
+├── api/
+│   ├── app/
+│   │   └── service/
+│   │       └── user.ts
+│   ├── config/
+│   │   ├── config.default.ts
+│   └── lambda/
+│       └── hello.ts
+```
+
+```ts title=/app/service/user.ts
+import { Service } from "egg";
+
+class UserService extends Service {
+  async find(uid) {
+    const user = await this.ctx.db.query(
+      "select * from user where uid = ?",
+      uid
+    );
+    return user;
+  }
+}
+
+export default UserService;
+```
+
+在 `lambda` 目录下定义的 BFF 函数中，可以使用 `useContext` API 获取 egg 请求上下文
+
+```ts title=/api/lambda/hello.ts
+import { useContext } from "@modern-js/runtime/server";
+
+export const get = async () => {
+  const ctx = useContext();
+  const userId = ctx.params.id;
+  const user = await ctx.service.user.find(userId);
+  return user;
+};
+```
+
+#### 自定义启动逻辑
+
+在 egg 的框架写法中，同样支持启动自定义，`api/app[tj]s` 和 `agent.[tj]s` 遵循 egg 的规范。
+
+具体可见[启动自定义](https://eggjs.org/zh-cn/basics/app-start.html)。

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

@@ -0,0 +1,236 @@
+---
+sidebar_position: 1
+title: BFF 函数
+---
+
+在[一体化 Web 专题](/docs/guides/basic-features/routes)中，介绍过 Modern.js 的 Serverless Web Development 开发方式，包括自动化路由、内置 Web Server、一体化 SSG/SSR/SPR 等。其中的 SSR 技术，可以称作 Serverless SSR，实现了 SSR 在开发、运行、部署全流程中的 Serverless。
+
+这一专题中会详细介绍另一部分：Serverless BFF。跟 SSR 一样，能实现 BFF（Backends for Frontends）在开发、运行、部署全流程中的 Serverless。
+
+在**前后端分离**概念出现后一段时间发展中，前端部分能够做的事越来越多，前端需要一些面向 UI 的数据接口，因此业界引入了 BFF 这一概念。
+
+它主要为了解决的问题包括：
+
+* 根据自身业务需求，对更底层 API 的聚合、映射、裁剪、代理。
+* 对一些特定场景的数据进行缓存，提高性能，进而提升用户体验。
+* 根据已有接口快速开发新产品。
+* 与第三方系统对接，例如登陆鉴权。
+
+Modern.js 提供了**一体化 BFF 方案**来进一步强化 BFF 能力，主要包括以下能力：
+
+* 快速开发调试上线，在同一项目中运行、构建、部署 BFF 代码。
+* 极简的纯函数调用，在前端直接 import BFF 函数，调用时能自动转换成 HTTP 请求。
+* 无私有协议，遵循 RESTful API 规范，所有 BFF 接口都是标准化的。
+* 完善的 TypeScript 支持。
+* 满足用户使用偏好，支持多框架扩展写法。
+* 接口调用安全，提供 schema 的接口定义方式。
+
+## 一体化调用
+
+Modern.js 允许可以在 `src` 目录下的 React 组件中直接引入并调用在 `api` 目录下定义好函数。
+
+[开启 BFF 功能](/docs/tutorials/first-app/c09-bff/9.2-enable-bff)之后，创建 `api/hello.ts` 文件，这里定义一个最简单的 BFF 函数：
+
+```ts title="api/hello.ts"
+export const get = async () => 'Hello Modern.js';
+```
+
+接着在 `src` 下的 `App.tsx` 中直接 import 函数调用：
+
+```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://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/hello-modern.png)
+
+## 函数路由
+
+Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，也是一种**约定式路由**。
+
+函数模式下 `api` 下的所有文件中的每个 BFF 函数都会映射为一个接口，框架模式下 `api/lambda` 下的所有文件中的每个 BFF 函数都会映射为一个接口。
+
+以下的 `$BASENAME` 指的是 BFF 函数的[路由前缀](/docs/configure/app/bff/prefix)，可以在 `modern.config.js` 中进行配置，默认值为 `/api`。
+
+:::info 注
+你可以通过 [prefix](/docs/configure/app/bff/prefix) 设置公共路由的前缀。
+:::
+
+### 默认路由
+
+以 `index.[jt]s` 命名的文件会被映射到上一层目录。
+
+* `api/index.ts` -> `$BASENAME/`
+* `api/user/index.ts` -> `$BASENAME/user`
+
+### 嵌套路由
+
+支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。
+
+* `api/hello.ts` -> `$BASENAME/hello`
+* `api/user/list.ts` -> `$BASENAME/user/list`
+
+### 动态路由
+
+同样的，你可以通过创建命名带有 `[xxx]` 的文件夹或者文件来支持动态的命名路由参数。
+
+* `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
+* `api/user/username/[action].ts` -> `$BASENAME/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 工程方案',
+  };
+};
+```
+
+* 应用工程 中支持了 9 种 Method 定义，即：`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 函数需要遵循一定的入参规则。
+
+Modern.js 函数定义分为普通函数与带有 schema 的函数，这一小节先介绍普通函数。
+
+普通函数参数分为两块，分别是请求路径中的动态部分和请求选项 `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
+}
+```
+
+当函数文件使用动态路由规则时，动态路由会在 `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/code-split.md

@@ -0,0 +1,68 @@
+---
+title: 代码分割
+sidebar_position: 6
+---
+
+代码分割是优化前端资源加载的一种常用手段，本文将介绍 Modern.js 支持的三种代码分割方式：
+
+- `import`
+- `React.lazy`
+- `loadable`
+
+## import
+
+使用动态 `import()` 语法，`import` 接收的 JS 模块将作为一个新的打包入口被打包到单独的 JS 文件中。例如：
+
+```ts
+import("./math").then(math => {
+  console.log(math.add(16, 26));
+});
+```
+
+`./math` 路径对应的 JS 模块会被打包到单独的 JS 文件中。
+
+## loadable
+
+使用 `loadable` API，示例如下：
+
+```ts
+import loadable from '@modern-js/runtime/loadable'
+
+const OtherComponent = loadable(() => import('./OtherComponent'));
+
+function MyComponent() {
+  return <OtherComponent />
+}
+```
+
+`loadable` 更多用法请见 [loadable API](/docs/apis/app/runtime/utility/loadable/loadable_)。
+
+:::info 注
+`loadable` 开箱即用的支持 SSR。
+:::
+
+## React.lazy
+
+React 官方提供的组件代码分割的方式，**缺点是不支持 SSR**。
+
+```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)。