@modern-js/main-doc 2.59.0 → 2.60.0

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/>

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

@@ -1,16 +1,12 @@
----
-sidebar_position: 4
-title: 自定义请求 SDK
----
-# 自定义请求 SDK
+# 扩展一体化调用 SDK
 
-Modern.js 的 BFF 在 CSR 和 SSR 是同构的。在浏览器端依赖了[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)，在服务端依赖了 [node-fetch](https://www.npmjs.com/package/node-fetch)。但在很多业务场景下我们需要对请求或响应做一些额外的处理，例如：
+BFF 函数的一体化调用在 CSR 和 SSR 是同构的。Modern.js 封装的请求 SDK，在浏览器端依赖了 [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)，在服务端依赖了 [node-fetch](https://www.npmjs.com/package/node-fetch)。但在实际业务场景下，有时需要对请求或响应做一些额外的处理，例如：
 
 - 在请求头中写入鉴权信息
 - 对响应的数据或错误进行统一的处理
 - 特定平台无法使用浏览器的原生 fetch 函数，需要使用其他方式发送请求
 
-针对上述的场景，Modern.js 提供了 `configure` 函数，自定义能力从低到高，可以用它配置 ssr 透传请求头，拦截器，请求 SDK。
+针对上述的场景，Modern.js 提供了 `configure` 函数，开放了一系列扩展能力，可以用它配置 ssr 透传请求头，添加拦截器，自定义请求 SDK。
 
 :::caution 注意
 `configure` 函数的调用需要在所有 BFF 请求发送前调用，以确保覆盖默认的请求配置。
@@ -18,42 +14,42 @@ Modern.js 的 BFF 在 CSR 和 SSR 是同构的。在浏览器端依赖了[Fetch
 :::
 
 
-```ts title="App.tsx"
+```tsx title="routes/page.tsx"
 import { configure } from '@modern-js/runtime/bff';
 
-configure({
-  request: customRequest
+configure({ 
+  // ... 
 })
+
+const Index = () => <div>Hello world</div>
+export default Index;
 ```
 
-## 配置 ssr 透传请求头
+## 配置 SSR 透传请求头
 
-在同时使用 Modernjs SSR 和 BFF 的场景下，常常需要将 SSR 页面请求上的一些请求头信息，透传给 BFF 服务。
+在同时使用 Modern.js SSR 和 BFF 的场景下，常常需要将 SSR 页面请求上的一些请求头信息，透传给 BFF 服务。
 
 例如项目有页面地址是 `https://website.com`，该页面是 SSR 的，在组件中会调用 API 接口 `https://website.com/api/info`，该接口需要用户的 cookie 信息做鉴权。页面在请求该 API 接口时，需要将 SSR 页面请求的 `cookie` 传给 BFF。
 
 目前以下请求头在 Modernjs 中是自动透传的：
 
-- cookie
-- x-tt-logid
-- user-agent
-- x-tt-stress
-
-可以通过 `configure` 配置请求头。例如以下例子，Modern.js 会自动将 SSR 页面请求的 cookie 信息透传给 BFF 服务：
+```ts
+['cookie', 'user-agent', 'x-tt-logid', 'x-tt-stress']
+```
 
-```tsx title="App.tsx"
-import { configure } from '@modern-js/runtime/bff';
+可以通过 `configure` 配置请求头。例如以下例子，Modern.js 会自动将 SSR 页面请求的 `x-uid` 信息透传给 BFF 服务：
 
+```tsx
 configure({
   allowedHeaders: ['x-uid']
 })
 ```
 
-## 配置拦截器
+## 添加拦截器
 
-在有些业务场景下需要对请求和响应进行一些统一的处理，这种场景下可以配置拦截器满足需求：
+在有些业务场景下需要对请求和响应进行统一的处理，这种场景下可以通过**配置拦截器**满足需求：
 
-```tsx title="App.tsx"
+```tsx
 configure({
   // 这里的 request 是一体化默认的请求工具，interceptor 函数需返回一个新的 request。
   // 新 request 的出参必须是 parse body 之后的结果
@@ -66,16 +62,11 @@ configure({
 });
 ```
 
-## 配置自定义请求 SDK
-
-如果仅仅通过配置拦截器无法满足需求，需要对请求的 SDK 做进一步的自定义，可以通过 `configure` 函数配置自定义请求 SDK：
-
-:::caution 注意
-在 SSR 和一体化调用的场景下，在 SSR 向 BFF 服务发送请求时，Modern.js 会通过**服务发现**找到 BFF 服务内网 IP，并通过 IP 发送请求，以提高性能。如果使用自定义请求 SDK 会**失去这种优化**。
+## 自定义请求 SDK
 
-:::
+如果仅仅通过配置拦截器无法满足需求，希望自定义请求函数，也可以通过 `configure` 进行配置：
 
-```tsx title="App.tsx"
+```tsx
 import nodeFetch from 'node-fetch';
 
 const customFetch = (input: RequestInfo | URL, init: RequestInit) => {
@@ -92,13 +83,13 @@ configure({
 });
 ```
 
-配置自定义请求 SDK 有以下约定：
+配置自定义请求函数有以下约定：
 
-- 通过 `configure` 函数可以配置一个 `request` 函数，这个函数的入参与浏览器中的 Fetch 或 node-fetch 对齐，所有的一体化 BFF 函数会通过该函数发送请求。
-- `request` 函数出参必须是接口实际返回的数据，不能是 Promise，否则会导致一体化 BFF 函数无法正常返回数据。
-- 如果是 SSR 项目，`request` 必须要同时支持浏览器端和服务器端发送请求。
+- 函数的入参与浏览器中的 Fetch 或 node-fetch 对齐，所有 BFF 函数的一体化调用会通过该函数发送请求。
+- 函数出参必须是接口实际返回的数据，不能是 Promise，否则会导致 BFF 函数无法正常返回数据。
+- 如果是 SSR 项目，函数必须要同时支持浏览器端和服务器端发送请求。
 
-使用 axios 定制自定义请求 SDK 的示例：
+下面是使用 axios 定制自定义请求函数的示例：
 
 ```tsx title="App.tsx"
 import { configure } from '@modern-js/runtime/bff';

package/docs/zh/guides/advanced-features/build-performance.mdx

@@ -9,13 +9,17 @@ Modern.js 默认对构建性能进行了充分优化，但是随着业务场景
 本文档提供了一些可选的提速策略，**开发者可以根据实际场景选取其中的部分策略**，从而进一步提升构建速度。
 
 :::tip 📢 注意
-在[优化产物体积](/guides/advanced-features/optimize-bundle.html)一文中介绍的策略也可以用于提升构建性能，这里不再重复介绍。
+在[优化产物体积](/guides/advanced-features/page-performance/optimize-bundle)一文中介绍的策略也可以用于提升构建性能，这里不再重复介绍。
 :::
 
 ## 通用优化策略
 
 以下是一些通用的优化策略，对开发环境和生产环境均有提速效果，其中部分策略对包体积也有优化。
 
+### 使用 Rspack 构建（推荐）
+
+如果你还未使用 Rspack 构建，可以切换到 Rspack 构建模式来提升 5~10 倍的构建速度，请参考 [使用 Rspack](/guides/advanced-features/rspack-start.html) 来进行切换。
+
 ### 升级 Node.js 版本
 
 通常来说，将 Node.js 更新到最新的 [LTS 版本](https://github.com/nodejs/release#release-schedule)，有助于提升构建性能。
@@ -40,25 +44,6 @@ nvm default 18
 node -v
 ```
 
-### 使用 Rspack 构建
-
-如果你对构建性能有更极致的需求，可以一键切换到 Rspack 构建模式，请参考 [使用 Rspack](/guides/advanced-features/rspack-start.html) 来进行切换。
-
-### 使用 SWC 或 esbuild 编译
-
-[SWC](https://swc.rs/) (Speedy Web Compiler) 是基于 `Rust` 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。在 Polyfill 和语法降级方面可以和 Babel 提供一致的能力，并且性能比 Babel 高出一个数量级。
-
-[esbuild](https://esbuild.github.io/) 是一款基于 Golang 开发的前端构建工具，具有打包、编译和压缩 JavaScript 代码的功能，相比传统的打包编译工具，esbuild 在性能上有显著提升。
-
-Modern.js 提供了 SWC 插件和 esbuild 插件，让你能使用 SWC 或 esbuild 代替 babel-loader、ts-loader 和 terser 等库进行代码编译和压缩。详见：
-
-- [SWC 插件文档](/configure/app/tools/swc.html)
-- [esbuild 插件文档](/configure/app/tools/esbuild.html)
-
-:::tip SWC vs esbuild
-SWC 编译产物的兼容性较好，支持注入 core-js 等 Polyfill，并且功能更加完备，因此推荐优先使用 SWC 插件。
-:::
-
 ### 避免使用 ts-loader
 
 默认情况下，Modern.js 使用 Babel 编译 TS 文件，开启 [tools.tsLoader](/configure/app/tools/ts-loader.html) 选项后，会使用 `ts-loader` 编译 TS 文件。
@@ -118,7 +103,7 @@ export default {
 
 ### 调整 Browserslist 范围
 
-这项优化的原理与[「提升 Browserslist 范围」](/guides/advanced-features/optimize-bundle.html#adjust-browserslist)类似，区别在于，我们可以为开发环境和生产环境设置不同的 browserslist，从而减少开发环境下的编译开销。
+这项优化的原理与[「提升 Browserslist 范围」](/guides/advanced-features/page-performance/optimize-bundle#adjust-browserslist)类似，区别在于，我们可以为开发环境和生产环境设置不同的 browserslist，从而减少开发环境下的编译开销。
 
 比如，你可以在 `package.json` 中添加以下配置，表示在开发环境下只兼容最新的浏览器，在生产环境下兼容实际需要的浏览器：
 

package/docs/zh/guides/advanced-features/page-performance/_meta.json

@@ -0,0 +1 @@
+["code-split", "inline-assets", "optimize-bundle"]

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -39,7 +39,7 @@ export default defineConfig({
 ```
 
 :::tip
-如果你当前版本低于 MAJOR_VERSION.59.0, 可通过执行 `npx modern upgrade` 进行升级。
+如果你当前版本低于 MAJOR_VERSION.59.0，可通过执行 `npx modern upgrade` 进行升级。
 :::
 
 import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPrecautions.md';
@@ -104,7 +104,7 @@ export default defineConfig<'rspack'>({
 
 ![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/20240110-155444.png)
 
-#### 修改内置 Rspack 版本
+### 修改内置 Rspack 版本
 
 可以使用 pnpm / yarn / npm 等包管理工具自带的依赖升级功能来将 Rspack 强制升级到指定版本。