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

package/docs/zh/guides/advanced-features/bff/cross-project.mdx

@@ -0,0 +1,112 @@
+import { PackageManagerTabs } from '@theme';
+
+# 跨项目调用
+
+基于 BFF 架构，Modern.js 提供了跨项目调用的能力，即在一个项目中创建的 BFF 函数可以被其他项目进行一体化调用，实现项目间的函数共享和功能复用。
+跨项目调用分为 BFF 的**生产端**和**消费端**。生产端负责创建和提供 BFF 服务、生成一体化调用 SDK，而消费端通过调用 SDK 发起接口请求。
+
+## BFF 生产端
+
+你可以将已启用 BFF 能力的项目视为 BFF 生产端，也可以单独创建独立的 BFF 应用。
+当执行 `dev` 或 `build`，都会自动生成供消费端使用的产物，包括：
+
+- `dist/client` 目录下的接口函数
+- `dist/runtime` 目录下的运行时配置函数
+- `package.json` 中 `exports` 定义接口函数出口
+- `package.json` 中 `files` 指定发布到 npm 包的文件列表
+
+### 已启用 BFF 的项目
+
+1. 开启跨项目调用
+
+确保当前项目已启动 BFF 能力，并在 `api/lambda` 目录下定义接口文件。完成如下配置：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+2. 生成 SDK 类型文件
+
+为一体化调用 SDK 提供类型提示，需要在 `TypeScript` 的 `tsconfig.json` 文件中打开 `declaration` 选项，配置如下：
+
+```ts title="tsconfig.json"
+"compilerOptions": {
+  "declaration": true,
+}
+```
+
+## BFF 消费端
+
+:::info
+你可以在任意框架的项目中通过调用 SDK 向 BFF 生产端发起接口请求。
+:::
+
+### 同一 Monorepo 内调用
+
+如果生产端和消费端在同一 Monorepo 中，可以直接引入 SDK。接口函数位于 `${package_name}/api` 目录下，示例如下：
+
+```ts title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '${package_name}/api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    hello().then(setText);
+  }, []);
+  return <div>{text}</div>;
+};
+```
+
+### 独立项目间调用
+
+当生产端和消费端不在同一个 Monorepo 中时，生产端需要通过 `npm publish` 将 BFF 生产端项目发布为包，调用方式与 Monorepo 内相同。
+
+### 配置域名及扩展功能
+
+实际应用场景中，跨项目调用需要指定 BFF 服务的域名。可以通过以下配置函数实现：
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+
+configure({
+  setDomain() {
+    return 'https://your-bff-api.com';
+  },
+});
+```
+
+`${package_name}/runtime` 目录下的 `configure` 函数，支持通过 `setDomain` 配置域名，`configure` 同样支持添加拦截器和自定义请求 SDK 能力。
+当需要在同一页面中同时对**当前项目**和**跨项目**的一体化调用 SDK 进行扩展，建议采用以下配置：
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+import { configure as innerConfigure } from '@modern-js/plugin-bff/client';
+import axios from 'axios';
+
+configure({
+  setDomain() {
+    return 'https://your-bff-api.com';
+  },
+});
+
+innerConfigure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string,
+      method: params?.method as Method,
+      data: params?.body,
+      headers: {
+        'x-header': 'innerConfigure',
+      },
+    });
+    return res.data;
+  },
+});
+```

package/docs/zh/guides/advanced-features/bff/data-platform.mdx

@@ -0,0 +1,118 @@
+---
+title: Data Platform
+---
+
+# Data Platform
+
+Modern.js 的 Effect BFF 已支持基于请求信封（request envelope）的数据平台契约，适用于 Module Federation 与微前端场景下的稳定数据编排。
+
+## 解决的问题
+
+- Host / Remote 间稳定的操作标识（operation identity）。
+- 按命名空间、来源、用户/租户隔离缓存键。
+- 请求载荷与选择计划（selection plan）完整性校验。
+- 服务端边界可选严格校验（strict mode）。
+- 跨命名空间失效策略更安全（默认不跨应用）。
+- 分布式链路追踪上下文连续传递。
+
+## 运行时契约工具
+
+可通过 `@modern-js/plugin-bff/data-platform` 使用以下能力：
+
+```ts
+import {
+  createOperationId,
+  buildScopeKey,
+  buildQueryKey,
+  createRequestEnvelope,
+  validateRequestEnvelope,
+  createHydrationEnvelope,
+  validateHydrationEnvelope,
+  createInvalidationEvent,
+  shouldApplyInvalidation,
+} from '@modern-js/plugin-bff/data-platform';
+```
+
+## Effect 运行时校验
+
+可在 `modern.config.ts` 中开启严格的服务端 envelope 校验：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      dataPlatform: {
+        requireEnvelope: true,
+        expectedNamespace: 'my-app',
+        selection: {
+          maxDepth: 6,
+          maxFields: 200,
+        },
+      },
+    },
+  },
+});
+```
+
+当启用 `validateOrigin` 时，Effect 运行时会优先使用请求中的 `Origin` 头进行 origin 校验；若不存在 `Origin`，则回退到请求 URL 的 origin。
+
+## Effect 客户端自动行为
+
+使用生成的 Effect 客户端（`@api/effect/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
+
+Envelope 默认包含：
+
+- operation 元数据
+- scope 缓存标识
+- request mode
+- selection plan 哈希
+- 可选 trace 上下文
+
+对于浏览器跨域请求，默认不会附加 envelope 请求头，以避免在跨项目/微前端场景下引入额外 CORS 预检失败。
+
+若必须跨域携带 envelope 请求头，可设置 `request.dataPlatform.allowCrossOriginEnvelope = true`，并在服务端 CORS 中放行该请求头。
+
+## 网络批处理
+
+生成的 Effect 客户端默认会对 GET 请求启用微批处理。在同一短时间窗口内的请求会合并为一次对 `/_data/batch`（位于 BFF 前缀下）的 POST 调用，并保持逐条响应语义。
+
+批处理特性：
+
+- 默认仅批处理 GET（可通过 `allowedMethods` 调整）。
+- 对相同请求进行 in-flight 去重。
+- 当批处理端点不可用时自动回退为单请求。
+- 条目级隔离：单条失败不会影响同批次其他条目。
+- 保持链路追踪：批处理网关会从条目请求头或 envelope 元数据转发 `traceparent`。
+
+服务端可通过 `bff.effect.dataPlatform.batch` 配置：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      dataPlatform: {
+        batch: {
+          endpoint: '/_data/batch',
+          maxBatchSize: 16,
+          maxBatchBytes: 64 * 1024,
+          flushIntervalMs: 8,
+          maxConcurrency: 4,
+          requestTimeoutMs: 10000,
+          allowedMethods: ['GET'],
+        },
+      },
+    },
+  },
+});
+```
+
+## 推荐策略
+
+- 保持 `validateOrigin` 开启。
+- 为每个应用/远程模块配置 `expectedNamespace`。
+- 客户端全部迁移后，在生产开启 `requireEnvelope`。
+- 除非你能明确保证 mutation 顺序与幂等性，否则保持仅 GET 批处理。
+- 在 MF 场景下，Host/Remote 各自维护本源 batch endpoint，不要将所有流量汇聚到单一共享源。
+- 跨应用失效必须显式声明 `targetNamespaces`，并由订阅方显式 opt-in。

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

@@ -0,0 +1,125 @@
+# 扩展 BFF Server
+
+部分应用中，开发者可能希望对所有 BFF 函数做统一的处理，例如鉴权、日志、数据处理等。
+
+Modern.js 支持用户通过 [Middleware](/guides/advanced-features/web-server.html#middleware) 的方式来自由扩展 BFF Server。
+
+## 使用中间件
+
+:::tip 版本一致性
+在使用中间件之前，需要先安装 `@modern-js/server-runtime` 依赖。请确保 `@modern-js/server-runtime` 的版本与项目中 `@modern-js/app-tools` 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布，版本不一致可能导致兼容性问题。
+
+请先查看 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/server-runtime`：
+
+```bash
+# 查看当前 @modern-js/app-tools 的版本
+pnpm list @modern-js/app-tools
+
+# 安装相同版本的 @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<版本号>
+```
+
+:::
+
+开发者可以在 `server/modern.server.ts` 中通过配置 middlewares 来使用中间件。下面介绍如何手写一个 BFF 中间件，添加权限校验：
+
+```ts title="server/modern.server.ts"
+import {
+  type MiddlewareHandler,
+  defineServerConfig,
+  getCookie,
+} from '@modern-js/server-runtime';
+
+const requireAuthForApi: MiddlewareHandler = async (c, next) => {
+  if (c.req.path.startsWith('/api') && c.req.path !== '/api/login') {
+    const sid = getCookie(c, 'sid');
+    if (!sid) {
+      return c.json({ code: -1, message: 'need login' }, 400);
+    }
+  }
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'require-auth-for-api',
+      handler: requireAuthForApi,
+    },
+  ],
+});
+```
+
+然后添加一个普通的 BFF 函数 `api/lambda/hello.ts`：
+
+```ts title="api/lambda/hello.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+
+export const get = async () => {
+  return {
+    code: 0,
+    message: '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)
+
+以上代码模拟了在 `server/Modern.server.ts` 中定义中间件的方式，实现了简易的登录功能。同样，可以在这个配置文件中实现其他功能来扩展 BFF Server。

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

@@ -0,0 +1,118 @@
+---
+sidebar_position: 3
+title: 运行时框架
+---
+
+# 运行时框架
+
+Modern.js 目前支持两种 BFF 运行时框架：
+
+- `effect`（默认）：使用 `api/effect/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
+- `hono`：使用 `api/lambda/**` 的文件约定 BFF 处理函数。
+
+`effect` 与 `hono` 为严格模式，两者之间不会自动回退。
+
+## 切换到 Effect 运行时
+
+```ts title="modern.config.ts"
+import { bffPlugin } from '@modern-js/plugin-bff';
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [bffPlugin()],
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      openapi: {
+        path: '/openapi.json',
+      },
+    },
+  },
+});
+```
+
+先在共享目录中定义 Effect HttpApi 契约（前后端共享类型）：
+
+```ts title="shared/effect/api.ts"
+import {
+  HttpApi,
+  HttpApiEndpoint,
+  HttpApiGroup,
+  Schema,
+} from '@modern-js/plugin-bff/effect-client';
+
+export const bffEffectApi = HttpApi.make('MyApi').add(
+  HttpApiGroup.make('hello').add(
+    HttpApiEndpoint.get('ping', '/effect/ping', {
+      success: Schema.String,
+    }),
+  ),
+);
+```
+
+然后在 `api/effect/index.ts` 中实现 Effect BFF 入口：
+
+```ts title="api/effect/index.ts"
+import {
+  Schema,
+  Effect,
+  HttpApiBuilder,
+  defineEffectBff,
+  Layer,
+  ServiceMap,
+} from '@modern-js/plugin-bff/effect-server';
+import { bffEffectApi } from '../../shared/effect/api';
+
+class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
+  'GreetingUnavailableError',
+  {
+    message: Schema.String,
+  },
+) {}
+
+class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingService', {
+  make: Effect.succeed({
+    hello: Effect.fn('GreetingService.hello')(function* () {
+      if (Date.now() < 0) {
+        return yield* Effect.fail(
+          new GreetingUnavailableError({
+            message: 'Greeting service is unavailable',
+          }),
+        );
+      }
+      return yield* Effect.succeed('pong');
+    }),
+  }),
+}) {
+  static readonly layer = Layer.effect(this, this.make);
+}
+
+const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
+  handlers.handle('ping', () =>
+    GreetingService.use(service => service.hello()).pipe(
+      Effect.catchTag('GreetingUnavailableError', error =>
+        Effect.succeed(error.message),
+      ),
+    ),
+  ),
+);
+
+const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
+  Layer.provide(group),
+  Layer.provide(GreetingService.layer),
+);
+
+export default defineEffectBff({ api: bffEffectApi, layer });
+```
+
+在浏览器端通过 `@api/effect/index` 调用接口：
+
+```ts title="src/routes/page.tsx"
+import effectBff from '@api/effect/index';
+
+const response = await effectBff.client.hello.ping({});
+```
+
+import Hono from '@site-docs/components/hono';
+
+<Hono />