@modern-js/main-doc 2.67.3 → 2.67.5

package/docs/zh/guides/basic-features/data/data-cache.mdx

@@ -4,7 +4,7 @@ sidebar_position: 4
 ---
 # 数据缓存
 
-`cache` 函数可以让你缓存数据获取或计算的结果。
+`cache` 函数可以让你缓存数据获取或计算的结果，相比整页[渲染缓存](/guides/basic-features/render/ssr-cache)，它提供了更精细的数据粒度控制，并且适用于客户端渲染(CSR)、服务端渲染（SSR）、API 服务(BFF)等多种场景。
 
 :::info
 需要 x.65.5 及以上版本
@@ -12,6 +12,14 @@ sidebar_position: 4
 
 ## 基本用法
 
+:::note
+
+如果在 BFF 中使用 `cache` 函数，应该从 `@modern-js/server-runtime/cache` 导入相关函数
+
+`import { cache } from '@modern-js/server-runtime/cache'`
+
+:::
+
 ```ts
 import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
@@ -33,6 +41,8 @@ const loader = async () => {
   - `tag`: 用于标识缓存的标签，可以基于这个标签使缓存失效
   - `maxAge`: 缓存的有效期 (毫秒)
   - `revalidate`: 重新验证缓存的时间窗口（毫秒），与 HTTP Cache-Control 的 stale-while-revalidate 功能一致
+  - `getKey`: 简化的缓存键生成函数，根据函数参数生成缓存键
+  - `customKey`: 自定义缓存键生成函数，用于在函数引用变化时保持缓存
 
 `options` 参数的类型如下：
 
@@ -41,6 +51,12 @@ interface CacheOptions {
   tag?: string | string[];
   maxAge?: number;
   revalidate?: number;
+  getKey?: <Args extends any[]>(...args: Args) => string;
+  customKey?: <Args extends any[]>(options: {
+    params: Args;
+    fn: (...args: Args) => any;
+    generatedKey: string;
+  }) => string | symbol;
 }
 ```
 
@@ -146,6 +162,193 @@ const getComplexStatistics = cache(
 revalidateTag('dashboard-stats'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
 ```
 
+#### `getKey` 参数
+
+`getKey` 参数用于自定义缓存键的生成方式，例如你可能只需要依赖函数参数的一部分来区分缓存。它是一个函数，接收与原始函数相同的参数，返回一个字符串作为缓存键：
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    // 这里 options 可能包含很多配置，但我们只想根据 userId 缓存
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // 只使用第一个参数（userId）作为缓存键
+    getKey: (userId, options) => userId,
+  }
+);
+
+// 下面两次调用会共享缓存，因为 getKey 只使用了 userId
+await getUser(123, { language: 'zh' });
+await getUser(123, { language: 'en' }); // 命中缓存，不会重新请求
+
+// 不同的 userId 会使用不同的缓存
+await getUser(456, { language: 'zh' }); // 不会命中缓存，会重新请求
+```
+
+你也可以使用 Modern.js 提供的 `generateKey` 函数配合 getKey 生成缓存的键：
+
+:::info
+
+Modern.js 中的 `generateKey` 函数确保即使对象属性顺序发生变化，也能生成一致的唯一键值，保证稳定的缓存
+
+:::
+
+```ts
+import { cache, CacheTime, generateKey } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    getKey: (userId, options) => generateKey(userId),
+  }
+);
+```
+
+
+#### `customKey` 参数
+
+`customKey` 参数用于定制缓存的键，它是一个函数，接收一个包含以下属性的对象，返回值必须是字符串或 Symbol 类型，将作为缓存的键：
+
+- `params`：调用缓存函数时传入的参数数组
+- `fn`：原始被缓存的函数引用
+- `generatedKey`：框架基于入参自动生成的原始缓存键
+
+:::info
+
+一般在以下场景，缓存会失效：
+1. 缓存的函数引用发生变化
+2. 函数的入参发生变化
+3. 不满足 maxAge
+4. 调用了 `revalidateTag`
+
+`customKey` 可以用在函数引用不同，但希望共享缓存的场景，如果只是自定义缓存键，推荐使用 `getKey`
+
+:::
+
+这在某些场景下非常有用，比如当函数引用发生变化时，但你希望仍然返回缓存的数据。
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+// 不同的函数引用，但是通过 customKey 可以使它们共享一个缓存
+const getUserA = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => {
+      // 返回一个稳定的字符串作为缓存的键
+      return `user-${params[0]}`;
+    },
+  }
+);
+
+// 即使函数引用变了，只要 customKey 返回相同的值，也会命中缓存
+const getUserB = cache(
+  (...args) => fetchUserData(...args), // 新的函数引用
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => {
+      // 返回与 getUserA 相同的键
+      return `user-${params[0]}`;
+    },
+  }
+);
+
+// 即使 getUserA 和 getUserB 是不同的函数引用，但由于它们的 customKey 返回相同的值
+// 所以当调用参数相同时，它们会共享缓存
+const dataA = await getUserA(1);
+const dataB = await getUserB(1); // 这里会命中缓存，不会再次发起请求
+
+// 也可以使用 Symbol 作为缓存键（通常用于共享同一个应用内的缓存）
+const USER_CACHE_KEY = Symbol('user-cache');
+const getUserC = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: () => USER_CACHE_KEY,
+  }
+);
+
+// 可以利用 generatedKey 参数在默认键的基础上进行修改
+const getUserD = cache(
+  fetchUserData,
+  {
+    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
+  }
+);
+```
+
+#### `onCache` 参数
+
+`onCache` 参数允许你跟踪缓存统计信息，例如命中率。这是一个回调函数，接收有关每次缓存操作的信息，包括状态、键、参数和结果。
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+// 跟踪缓存统计
+const stats = {
+  total: 0,
+  hits: 0,
+  misses: 0,
+  stales: 0,
+  hitRate: () => stats.hits / stats.total
+};
+
+const getUser = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    onCache({ status, key, params, result }) {
+      // status 可以是 'hit'、'miss' 或 'stale'
+      stats.total++;
+
+      if (status === 'hit') {
+        stats.hits++;
+      } else if (status === 'miss') {
+        stats.misses++;
+      } else if (status === 'stale') {
+        stats.stales++;
+      }
+
+      console.log(`缓存${status === 'hit' ? '命中' : status === 'miss' ? '未命中' : '陈旧'}，键：${String(key)}`);
+      console.log(`当前命中率：${stats.hitRate() * 100}%`);
+    }
+  }
+);
+
+// 使用示例
+await getUser(1); // 缓存未命中
+await getUser(1); // 缓存命中
+await getUser(2); // 缓存未命中
+```
+
+`onCache` 回调接收一个包含以下属性的对象：
+
+- `status`: 缓存操作状态，可以是：
+  - `hit`: 缓存命中，返回缓存内容
+  - `miss`: 缓存未命中，执行函数并缓存结果
+  - `stale`: 缓存命中但数据陈旧，返回缓存内容同时在后台重新验证
+- `key`: 缓存键，可能是 `customKey` 的结果或默认生成的键
+- `params`: 传递给缓存函数的参数
+- `result`: 结果数据（来自缓存或新计算的）
+
+这个回调只在提供 `options` 参数时被调用。当使用无 options 的缓存函数时，不会调用 `onCache` 回调。
+
+`onCache` 回调对以下场景非常有用：
+- 监控缓存性能
+- 计算命中率
+- 记录缓存操作
+- 实现自定义指标
 
 ### 存储
 
@@ -164,3 +367,4 @@ configureCache({
   maxSize: CacheSize.MB * 10, // 10MB
 });
 ```
+

package/docs/zh/guides/basic-features/routes.mdx

@@ -495,6 +495,78 @@ import Motivation from '@site-docs/components/convention-routing-motivation';
 
 <Motivation />
 
+## 升级到 react-router v7
+
+React Router v7 相比 React Router v6 减少了包体积（小约 15%），提供了更高效的路由匹配算法，对 React 19 和 TypeScript 也提供了更好的支持，
+相比 React Router v6 breaking change 非常少，同时 Modern.js 也对两个版本做了兼容，只需在项目中安装并注册相应的插件即可无缝升级。
+
+:::info
+
+更多 react router v6 到 react router v7 的变更，请查看[文档](https://reactrouter.com/upgrading/v6#upgrade-to-v7)
+
+:::
+
+### 环境要求
+
+React Router v7 对环境有一定要求：
+
+- Node.js 20+
+- React 18+
+- React DOM 18+
+
+### 安装插件
+
+首先，安装 Modern.js 的 React Router v7 插件：
+
+```bash
+pnpm add @modern-js/plugin-router-v7
+```
+
+### 配置插件
+
+在 `modern.config.ts` 中注册插件：
+
+```ts title="modern.config.ts"
+import { routerPlugin } from '@modern-js/plugin-router-v7';
+
+export default {
+  runtime: {
+    router: true,
+  },
+  plugins: [routerPlugin()],
+};
+```
+
+### 修改代码
+
+在 react router v7 中，不需要再使用 `defer` API 了，直接在 data loader 中返回数据即可：
+
+```ts title="routes/page.data.ts"
+import { defer } from '@modern-js/runtime/router';
+
+export const loader = async ({ params }) => {
+  // 推荐的 v7 风格
+  const user = fetchUser(params.id)
+  return { user };
+
+  // v6 风格，Modern.js 做了兼容，仍然可以继续使用
+  return defer({ data: 'hello' });
+};
+```
+
+react router v7 同样废弃了 `json` API：
+
+```ts title="routes/page.data.ts"
+export const loader = async ({ params }) => {
+  // 推荐的 v7 风格
+  return { data: 'hello' };
+
+  // v6 风格，Modern.js 做了兼容，仍然可以继续使用
+  return json({ data: 'hello' });
+};
+```
+
+
 ## 常见问题
 
 1. 为什么要提供 `@modern-js/runtime/router` 来导出 React Router API ?

package/docs/zh/plugin/cli-plugins/api.mdx

@@ -2,6 +2,12 @@
 
 本文档详细介绍了 Modern.js CLI 插件的 API。CLI 插件允许您在 Modern.js 项目的构建和开发过程中扩展和定制功能。
 
+:::info
+
+CLI 插件需要通过 `modern.config.ts` 中的 [`plugins`](/configure/app/plugins) 字段配置。
+
+:::
+
 ## 插件基础结构
 
 一个典型的 CLI 插件结构如下：

package/docs/zh/plugin/runtime-plugins/api.mdx

@@ -2,6 +2,12 @@
 
 Modern.js 的 Runtime 插件允许您在应用程序的 React 代码运行时扩展和修改其行为。通过 Runtime 插件，您可以轻松地执行初始化任务、实现 React 高阶组件（HOC）封装等功能。
 
+:::info
+
+Runtime 插件需要通过 `src/modern.runtime.ts` 中的 [`plugins`](/configure/app/runtime/plugins) 字段配置。
+
+:::
+
 ## 插件结构
 
 一个典型的 Runtime 插件如下所示：
@@ -151,16 +157,35 @@ await hooks.onBeforeRender.call(myContext);
 您可以组合使用多个钩子来实现更复杂的功能。例如，您可以使用 `onBeforeRender` 获取数据，然后使用 `wrapRoot` 将数据通过 Context 传递给整个应用：
 
 ```ts
-api.onBeforeRender(async (context) => {
-  const data = await fetchData(context.req);
-  context.data = data;
-});
-
-api.wrapRoot((App) => {
-  return (props) => (
-    <DataContext.Provider value={props.data}>
-      <App {...props} />
-    </DataContext.Provider>
-  );
-});
+import { RuntimePluginFuture, RuntimeReactContext } from '@modern-js/runtime';
+import { useContext, createContext } from 'react';
+
+export const ThemeContext = createContext<{ theme: string } | null>(null);
+
+export const themePlugin = (): RuntimePluginFuture => {
+  return {
+    name: 'theme-plugin',
+    setup: api => {
+      api.onBeforeRender(async context => {
+        const userPreference = await fetch('/api/user/theme-settings').then(
+          res => res.json(),
+        );
+        context.data = {
+          theme: userPreference.theme,
+        };
+      });
+
+      api.wrapRoot(App => {
+        return props => {
+          const context = useContext(RuntimeReactContext);
+          return (
+            <ThemeContext.Provider value={context.data}>
+              <App {...props} />
+            </ThemeContext.Provider>
+          );
+        };
+      });
+    },
+  };
+};
 ```

package/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.67.3",
+  "version": "2.67.5",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "2.67.3"
+    "@modern-js/sandpack-react": "2.67.5"
   },
   "devDependencies": {
     "@rspress/shared": "1.43.11",

package/src/i18n/index.ts

@@ -9,7 +9,7 @@ const translations = {
 
 export function useUrl(url: string) {
   const lang = useLang();
-  return withBase(lang === 'zh' ? url : `/en${url}`);
+  return withBase(lang === 'zh' ? `/zh${url}` : url);
 }
 
 export function useI18n() {