feat: support cache statistics

Author: yimingjfe

.changeset/yellow-dolls-fail.md

@@ -0,0 +1,6 @@
+---
+'@modern-js/runtime-utils': patch
+---
+
+feat: support cache statistics
+feat: 支持缓存命中率统计

packages/document/main-doc/docs/en/guides/basic-features/data/data-cache.mdx

@@ -4,7 +4,7 @@ sidebar_position: 4
 ---
 # Data Caching
 
-The `cache` function allows you to cache the results of data fetching or computation.
+The `cache` function allows you to cache the results of data fetching or computation, Compared to full-page [rendering cache](/guides/basic-features/render/ssr-cache), it provides more fine-grained control over data granularity and is applicable to various scenarios such as Client-Side Rendering (CSR), Server-Side Rendering (SSR), and API services (BFF).
 
 :::info
 X.65.5 and above versions are required
@@ -217,6 +217,68 @@ const getUserD = cache(
 );
 ```
 
+#### `onCache` Parameter
+
+The `onCache` parameter allows you to track cache statistics such as hit rate. It's a callback function that receives information about each cache operation, including the status, key, parameters, and result.
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+// Track cache statistics
+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 can be 'hit', 'miss', or 'stale'
+      stats.total++;
+
+      if (status === 'hit') {
+        stats.hits++;
+      } else if (status === 'miss') {
+        stats.misses++;
+      } else if (status === 'stale') {
+        stats.stales++;
+      }
+
+      console.log(`Cache ${status} for key: ${String(key)}`);
+      console.log(`Current hit rate: ${stats.hitRate() * 100}%`);
+    }
+  }
+);
+
+// Usage example
+await getUser(1); // Cache miss
+await getUser(1); // Cache hit
+await getUser(2); // Cache miss
+```
+
+The `onCache` callback receives an object with the following properties:
+
+- `status`: The cache operation status, which can be:
+  - `hit`: Cache hit, returning cached content
+  - `miss`: Cache miss, executing the function and caching the result
+  - `stale`: Cache hit but data is stale, returning cached content while revalidating in the background
+- `key`: The cache key, which is either the result of `customKey` or the default generated key
+- `params`: The parameters passed to the cached function
+- `result`: The result data (either from cache or newly computed)
+
+This callback is only invoked when the `options` parameter is provided. When using the cache function without options (for SSR request-scoped caching), the `onCache` callback is not called.
+
+The `onCache` callback is useful for:
+- Monitoring cache performance
+- Calculating hit rates
+- Logging cache operations
+- Implementing custom metrics
+
 ### Storage
 
 Currently, both client and server caches are stored in memory.

packages/document/main-doc/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 及以上版本
@@ -214,6 +214,68 @@ const getUserD = cache(
 );
 ```
 
+#### `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` 参数时被调用。当使用不带选项的缓存函数（用于 SSR 请求范围内的缓存）时，不会调用 `onCache` 回调。
+
+`onCache` 回调对以下场景非常有用：
+- 监控缓存性能
+- 计算命中率
+- 记录缓存操作
+- 实现自定义指标
+
 ### 存储
 
 目前不管是客户端还是服务端，缓存都存储在内存中，默认情况下所有缓存函数共享的存储上限是 1GB，当达到存储上限后，使用 LRU 算法移除旧的缓存。

packages/toolkit/runtime-utils/src/universal/cache.ts

@@ -16,6 +16,15 @@ export const CacheTime = {
   MONTH: 30 * 24 * 60 * 60 * 1000,
 } as const;
 
+export type CacheStatus = 'hit' | 'stale' | 'miss';
+
+export interface CacheStatsInfo {
+  status: CacheStatus;
+  key: string | symbol;
+  params: any[];
+  result: any;
+}
+
 interface CacheOptions {
   tag?: string | string[];
   maxAge?: number;
@@ -25,6 +34,7 @@ interface CacheOptions {
     fn: (...args: Args) => any;
     generatedKey: string;
   }) => string | symbol;
+  onCache?: (info: CacheStatsInfo) => void;
 }
 
 interface CacheConfig {
@@ -155,6 +165,7 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
     maxAge = CacheTime.MINUTE * 5,
     revalidate = 0,
     customKey,
+    onCache,
   } = options || {};
   const store = getLRUCache();
 
@@ -198,10 +209,11 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
         }
       }
     } else if (typeof options !== 'undefined') {
-      const key = generateKey(args);
+      const genKey = generateKey(args);
       const now = Date.now();
 
-      const cacheKey = getCacheKey(args, key);
+      const cacheKey = getCacheKey(args, genKey);
+      const finalKey = typeof cacheKey === 'function' ? genKey : cacheKey;
 
       tags.forEach(t => addTagKeyRelation(t, cacheKey));
 
@@ -211,17 +223,34 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
       }
 
       const storeKey =
-        customKey && typeof cacheKey === 'symbol' ? 'symbol-key' : key;
+        customKey && typeof cacheKey === 'symbol' ? 'symbol-key' : genKey;
 
       const cached = cacheStore.get(storeKey);
       if (cached) {
         const age = now - cached.timestamp;
 
         if (age < maxAge) {
+          if (onCache) {
+            onCache({
+              status: 'hit',
+              key: finalKey,
+              params: args,
+              result: cached.data,
+            });
+          }
           return cached.data;
         }
 
         if (revalidate > 0 && age < maxAge + revalidate) {
+          if (onCache) {
+            onCache({
+              status: 'stale',
+              key: finalKey,
+              params: args,
+              result: cached.data,
+            });
+          }
+
           if (!cached.isRevalidating) {
             cached.isRevalidating = true;
             Promise.resolve().then(async () => {
@@ -252,6 +281,7 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
       }
 
       const data = await fn(...args);
+
       cacheStore.set(storeKey, {
         data,
         timestamp: now,
@@ -260,6 +290,15 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
 
       store.set(cacheKey, cacheStore);
 
+      if (onCache) {
+        onCache({
+          status: 'miss',
+          key: finalKey,
+          params: args,
+          result: data,
+        });
+      }
+
       return data;
     } else {
       console.warn(