@modern-js/main-doc 2.59.0 → 2.60.1-alpha.0

package/docs/zh/guides/advanced-features/bff/extend-server.mdx

@@ -0,0 +1,156 @@
+# 扩展 BFF Server
+
+部分应用中，开发者可能希望对所有 BFF 函数做统一的处理，例如鉴权、日志、数据处理等。
+
+Modern.js 提供了两种方式，允许开发者根据运行时框架自由扩展 BFF Server。
+
+## 中间件
+
+开发者可以在编写 `api/_app.ts` 文件中编写中间件，用来扩展 BFF Server。以 Express 作为运行时框架为例，介绍如何手写一个中间件，添加权限校验：
+
+```ts title="api/_app.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/lambda/hello.ts`：
+
+```ts title="api/lambda/hello.ts"
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+接下来，在前端 `src/routes/page.tsx` 添加接口的访问代码，直接使用一体化的方式调用：
+
+```ts title="src/routes/page.tsx"
+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>;
+};
+```
+
+现在运行 `dev` 命令启动项目，访问 `http://localhost:8080/` 会发现 `/api/hello` 的请求被拦截了：
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+
+最后修改前端代码 `src/routes/page.tsx`，在访问 `/api/hello` 前先调用登录接口：
+
+:::note
+此处没有真实实现登录接口，代码仅作为演示。
+:::
+
+```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。
+
+:::info
+不同运行时框架中，中间件的写法不一定相同，详情可见[运行时框架](/guides/advanced-features/bff/frameworks)。
+
+:::
+
+## 定义 Server 实例
+
+除了中间件之外，还可以通过 `api/app.ts` 文件来定义 BFF Server 的实例。开发者需要默认导出一个能被运行时框架插件识别的实例。这里简单展示一下 Koa 和 Express 如何定义 Server 实例。
+
+import { Tabs, Tab as TabItem } from "@theme";
+
+<Tabs>
+  <TabItem value="express" label="Express.js" default>
+
+```ts title="api/app.ts"
+import express from 'express';
+
+const app = express();
+app.use(async (req, res, next) => {
+  console.info(`access url: ${req.url}`);
+  next();
+});
+
+export default app;
+```
+
+  </TabItem>
+  <TabItem value="koa" label="Koa.js">
+
+```ts title="api/app.ts"
+import koa from 'koa';
+
+const app = new Koa();
+app.use(async (ctx, next) => {
+  console.info(`access url: ${ctx.url}`);
+  await next();
+});
+
+export default app;
+```
+
+  </TabItem>
+</Tabs>
+
+在复杂的 BFF 逻辑中，定义 Server 实例可以更方便通过一个入口来组织代码逻辑，设计目录结构。在这个文件中，可以执行初始化逻辑，添加全局中间件，声明路由，甚至扩展原有框架。
+
+BFF 函数定义的路由会在 `app.ts` 文件定义的路由之后注册，所以在这里你也可以拦截 BFF 函数定义的路由，进行预处理或是提前响应。
+
+:::note
+此时，如果应用中同时存在 `api/_app.ts`，则定义的中间件会被放在 `api/app.ts` 导出实例的最后执行。多数情况下，中间件就能覆盖大多数 BFF 函数的定制需求。只有当应用的服务端逻辑比较复杂时，才需要自定义 Server 实例。
+:::
+
+:::caution
+当应用中没有 `api/app.ts` 的时候，Modern.js 默认会添加 [koa-body](https://www.npmjs.com/package/koa-body)。当应用中存在 `api/app.ts` 时，如果开发者希望使用带有 Body 的 BFF 函数，需要**自行添加** `koa-body`。
+:::

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

@@ -2,151 +2,85 @@
 sidebar_position: 3
 title: 运行时框架
 ---
+
 # 运行时框架
 
 Modern.js 的 BFF 支持不同的运行时框架，当前 Modern.js 的 BFF 支持两种运行时框架 [Express.js](https://expressjs.com/) 和 [Koa.js](https://koajs.com/)。
 
-## 函数写法
+使用不同运行时框架时，有部分 API 会存在差异。
 
-在函数写法下，各类运行时框架仅中间件写法存在差异，其他实现基本相同。这里以 Express 为例，介绍如何在 `api/_app.ts` 中，手写一个中间件，添加权限校验：
+## 获取请求上下文
 
-```ts
-import { hook } from '@modern-js/runtime/server';
-import { Request, Response, NextFunction } from 'express';
+在 BFF 函数中，有时需要获取请求上下文，来处理更多逻辑。此时，根据不同的运行时框架，你需要从通过不同的 API 来获取：
 
-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();
-    }
-  });
-});
-```
+import { Tabs, Tab as TabItem } from "@theme";
 
-然后添加一个普通的 BFF 函数 `/api/hello.ts`：
+<Tabs>
+  <TabItem value="express" label="Express.js" default>
 
-```ts
-export default async () => {
-  return 'Hello Modern.js';
+```ts title="api/lambda/hello.ts"
+import { useContext } from '@modern-js/runtime/express'
+export const get = async () => {
+  const { req } = useContext();
+  console.info(`access url: ${req.url}`);
+  return 'Hello Modern.js'
 };
 ```
 
-最后在前端 `src/App.tsx` 添加接口的访问代码，直接使用一体化的方式调用：
+  </TabItem>
+  <TabItem value="koa" label="Koa.js">
 
-```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>;
+```ts title="api/lambda/hello.ts"
+import { useContext } from '@modern-js/runtime/koa'
+export const get = async () => {
+  const ctx = useContext();
+  console.info(`access url: ${req.url}`);
+  return 'Hello Modern.js'
 };
 ```
 
-然后 `pnpm run dev` 启动项目，访问 `http://localhost:8080/` 会发现 `/api/hello` 的请求被拦截了：
+  </TabItem>
+</Tabs>
 
-![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+:::info
+详细内容可以参考 [useContext](/apis/app/runtime/bff/use-context)。
+:::
 
-最后再修改前端代码 `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';
+在 BFF 函数中，有时需要使用中间件，来处理更多逻辑。此时，根据不同的运行时框架，你需要从通过不同的 API 来获取：
 
-export default () => {
-  const [text, setText] = useState('');
+<Tabs>
+  <TabItem value="express" label="Express.js" default>
 
-  useEffect(() => {
-    async function fetchAfterLogin() {
-      const { code } = await login();
-      if (code === 0) {
-        const { message } = await hello();
-        setText(message);
-      }
-    }
-    fetchAfterLogin();
-  }, []);
+```ts title="api/_app.ts"
+import { hook } from '@modern-js/runtime/express';
 
-  return <p>{text}</p>;
-};
+export default hook(({ addMiddleware }) => {
+  addMiddleware((req, res, next) => {
+    req.query.id = 'koa';
+    next();
+  });
+});
 ```
 
-刷新页面，可以看到 `/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
+  </TabItem>
+  <TabItem value="koa" label="Koa.js">
 
-Express 的框架写法支持可在 `api/app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，甚至扩展原有框架等。
+```ts title="api/_app.ts"
+import { hook } from '@modern-js/runtime/koa';
 
-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 hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx, next) => {
+    ctx.req.query.id = 'koa';
+    await 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` 中间件已经添加。
+  </TabItem>
+</Tabs>
 
+:::info
+详细内容可以参考 [hook](/apis/app/runtime/bff/hook)。
 :::
-
-```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/docs/zh/guides/advanced-features/bff/function.mdx

@@ -1,10 +1,8 @@
----
-sidebar_position: 1
-title: 基础用法
----
 # 基础用法
 
-通过 Modern.js 开发的应用，可以在 `api/` 目录下定义接口函数，前端可以调用这些接口函数，即可发起请求，无需写前后端胶水层代码，同时保证前后端类型安全。
+在 Modern.js 应用中，开发者可以在 `api/lambda` 目录下定义接口文件，并导出接口函数。在前端代码中，可以用文件引用的方式，直接调用这些接口函数，发起接口请求。
+
+这种调用方式我们称为**一体化调用**，开发者无需编写前后端胶水层代码，并天然地保证前后端类型安全。
 
 ## 启用 BFF
 
@@ -14,20 +12,15 @@ import EnableBFF from "@site-docs/components/enable-bff"
 
 ## BFF 函数
 
-允许通过一体化调用的函数，称为 **BFF 函数**。这里写一个最简单的 BFF 函数，创建 `api/hello.ts` 文件：
-
-:::caution
-如果是框架模式（有 `api/lambda` 目录），需要创建 `api/lambda/hello.ts`
-
-:::
+允许使用一体化调用的函数，我们称为 **BFF 函数**。这里写一个最简单的 BFF 函数，首先创建 `api/lambda/hello.ts` 文件：
 
-```ts title="api/hello.ts"
+```ts title="api/lambda/hello.ts"
 export const get = async () => 'Hello Modern.js';
 ```
 
-接着在 `src/App.tsx` 中直接引入函数并调用：
+接着在 `src/routes/page.tsx` 中直接引入函数并调用：
 
-```tsx title=src/App.tsx
+```tsx title="src/routes/page.tsx"
 import { useState, useEffect } from 'react';
 import { get as hello } from '@api/hello';
 
@@ -41,56 +34,49 @@ export default () => {
 };
 ```
 
-:::info
-Modern.js 生成器已经在 `tsconfig.json` 中配置 `@api` 别名，因此可以直接通过别名的方式引入函数。
+:::tip
+在调用 `new` 命令后，Modern.js 生成器会自动在 `tsconfig.json` 中配置 `@api` 别名，因此可以直接通过别名的方式引入函数。
 
 :::
 
-在 `src/App.tsx` 中引入的函数，会自动转换成接口调用，不需要再去通过 fetch 去调用接口。
+在 `src/routes/page.tsx` 中引入的函数，会自动转换成接口调用，不需要再通过请求 SDK 或 Web Fetch 调用接口。
 
-执行 `pnpm run dev` 打开 `http://localhost:8080/` 可以看到页面已经展示了 BFF 函数返回的内容，在 Network 中可以看到页面向 `http://localhost:8080/api/hello` 发送了请求：
+执行 `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
-函数写法和框架写法会在下一节详细介绍。
-
-:::
+Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，也是一种**约定式路由**。`api/lambda` 下的所有文件中的每个 BFF 函数都会映射为一个接口，下面介绍几种路由的约定。
 
+:::info
 所有 BFF 函数生成的路由都带有统一的前缀，默认值为 `/api`。可以通过 [bff.prefix](/configure/app/bff/prefix) 设置公共路由的前缀。
-
-下面介绍几种路由的约定。
+:::
 
 ### 默认路由
 
 以 `index.[jt]s` 命名的文件会被映射到上一层目录。
 
-- `api/index.ts` -> `{prefix}/`
-- `api/user/index.ts` -> `{prefix}/user`
+- `api/lambda/index.ts` -> `{prefix}/`
+- `api/lambda/user/index.ts` -> `{prefix}/user`
 
 ### 多层路由
 
 支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。
 
-- `api/hello.ts` -> `{prefix}/hello`
-- `api/user/list.ts` -> `{prefix}/user/list`
+- `api/lambda/hello.ts` -> `{prefix}/hello`
+- `api/lambda/user/list.ts` -> `{prefix}/user/list`
 
 ### 动态路由
 
-同样的，创建命名带有 `[xxx]` 的文件夹或者文件，支持动态的命名路由参数。动态路由的函数参数规则可以看 [dynamac-path](/guides/advanced-features/bff/function#dynamic-path)
+同样的，创建命名带有 `[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/lambda/user/[username]/info.ts` -> `{prefix}/user/:username/info`
+- `api/lambda/user/username/[action].ts` -> `{prefix}/user/username/:action`
 
 ### 白名单
 
-默认 `api/` 目录下所有文件都会当作 BFF 函数文件去解析，但以下文件不会被解析：
+默认 `api/lambda/` 目录下所有文件都会当作 BFF 函数文件去解析，但以下文件不会被解析：
 
 - 命名以 `_` 开头的文件。例如：`_utils.ts`。
 - 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
@@ -100,20 +86,18 @@ Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，
 
 ## RESTful API
 
-Modern.js 的 BFF 函数需要遵循 RESTful API 标准来定义, 遵循 HTTP Method 规范，并且不允许自由定义参数。
-
-:::info
-假设函数允许自由定义参数，产出的路由必然由**私有协议**进行调用（原因是无法区分请求参数与请求体），而无法实现任意的 RESTful API。
+Modern.js 的 BFF 函数需要遵循 RESTful API 标准来定义，开发者需要按照一系列规则来定义 BFF 函数。
 
-如果服务仅用于应用本身不存在问题，但它**不标准的接口定义**无法融入更大的体系。 在多个系统共同工作的情况下（例如 BFF 低码搭建），会导致其他系统也需要遵循**私有协议**。
+:::tip 设计原则
+BFF 函数不仅会在项目中被调用，也应该允许其他项目通过请求 SDK 或 Web fetch 调用。因此 Modern.js 没有在一体化调用时定义**私有协议**，而是通过标准的 HTTP Method，以及 `params`、`query`、`body` 等通用的 HTTP 请求参数来定义函数。
 
 :::
 
-### 函数具名导出
+### 函数导出规则
 
-Modern.js BFF 函数的导出名决定了函数对应接口的 Method，如 `get`，`post` 等。
+#### HTTP Method 具名函数
 
-例如，按照以下例子，可导出一个 GET 接口。
+Modern.js BFF 函数的导出名决定了函数对应接口的 HTTP Method，如 `get`，`post` 等。例如导出一个 GET 接口：
 
 ```ts
 export const get = async () => {
@@ -124,7 +108,7 @@ export const get = async () => {
 };
 ```
 
-按照以下例子，则可导出一个 `POST` 接口
+按照以下例子，则可导出一个 `POST` 接口：
 
 ```ts
 export const post = async () => {
@@ -139,24 +123,46 @@ export const post = async () => {
 
 - 名字是大小不敏感的，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。
 
-- 可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
+#### 使用 Async 函数
 
-:::info
-需要注意的是，定义的函数都应该是异步的，与函数调用时类型有关，后面会提到。
+Modern.js 推荐将 BFF 函数定义为 Async 异步函数，即使函数中不存在异步流程，例如：
 
-:::
+```ts
+export const get = async () => {
+  return {
+    name: 'Modern.js',
+    desc: '现代 web 工程方案',
+  };
+};
+```
 
-### 函数参数规则
+这是因为在前端调用时，BFF 函数会自动转换成 HTTP 接口调用，而 HTTP 接口调用时异步的，在前端通常会这样使用：
+
+```tsx title="src/routes/page.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>;
+};
+```
 
-如上所述，为了满足 RESTful API 的设计标准，因此 Modern.js 中 BFF 函数需要遵循一定的入参规则。
+因此，为了保持类型定义与实际调用体验统一，我们推荐在定义 BFF 函数时将它设置为异步函数。
 
-函数参数分为两块，分别是请求路径中的动态部分和请求选项 `RequestOption`。
+### 函数参数规则
+
+函数参数规则分为两块，分别是请求路径中的动态路由（Dynamic Path）和请求选项（RequestOption）。
 
 #### Dynamic Path
 
-动态路由会作为函数第一部分的入参，每个入参对应一段动态路由。例如以下示例，uid 会作为前两个参数传递到函数中：
+动态路由会作为 BFF 函数第一部分的入参，每个入参对应一段动态路由。例如以下示例，`level` 和 `id` 会作为前两个参数传递到函数中：
 
-```ts title="api/[level]/[id].ts"
+```ts title="api/lambda/[level]/[id].ts"
 export default async (level: number, id: number) => {
   const userData = await queryUser(level, uid);
   return userData;
@@ -165,7 +171,7 @@ export default async (level: number, id: number) => {
 
 在调用时直接传入动态参数：
 
-```ts title="App.tsx"
+```tsx title="src/routes/page.tsx"
 import { useState, useEffect } from 'react';
 import { get as getUser } from '@api/[level]/[id]';
 
@@ -186,7 +192,7 @@ Dynamic Path 之后的参数是包含 querystring、request body 的对象 `Requ
 
 在不存在动态路由的普通函数中，可以从第一个入参中获取传入的 `data` 和 `query`，例如：
 
-```ts title="api/hello.ts"
+```ts title="api/lambda/hello.ts"
 import type { RequestOption } from '@modern-js/runtime/server';
 
 export async function post({
@@ -216,7 +222,7 @@ export async function post({ query, data }: { query: IQuery; data: IData }) {
 
 当函数文件使用动态路由规则时，动态路由会在 `RequestOption` 对象参数前。
 
-```ts title="api/[sku]/[id]/item.ts"
+```ts title="api/lambda/[sku]/[id]/item.ts"
 export async function post(
   sku: string,
   id: string,
@@ -231,7 +237,7 @@ export async function post(
 
 调用时也按照函数定义，传入对应的参数即可：
 
-```ts title="App.tsx"
+```ts title="src/routes/page.tsx"
 import { post } from '@api/[sku]/[id]/item';
 
 export default () => {
@@ -250,4 +256,8 @@ export default () => {
 };
 ```
 
-之前提到，定义的函数都应该是异步的，是因为在前端调用时会自动转换成 HTTP 接口调用，所以为了保持类型定义与实际调用体验统一，需要在定义 BFF 函数时将它设置为异步。
+## 扩展 BFF 函数
+
+import ExtendBFF from "@site-docs/components/extend-bff-function"
+
+<ExtendBFF/>