@jolibox/implement 1.2.5 → 1.2.6

package/src/common/cache/request-cache-service.ts

@@ -1,393 +0,0 @@
-/**
- * 通用请求缓存服务基类
- * 支持部分数据缓存，部分数据实时获取的混合模式
- */
-
-export interface CacheConfig<TCacheData, TServerData> {
-  /** 缓存持续时间，默认10分钟 */
-  duration?: number;
-  /** 请求超时时间，默认3秒 */
-  timeout?: number;
-  /** 缓存键生成函数 */
-  keyGenerator?: <TRequest>(endpoint: string, params?: TRequest) => string;
-  /** 数据一致性校验函数 */
-  consistencyChecker?: (cached: TCacheData, serverData: TServerData) => boolean;
-}
-
-export interface CacheEntry<T> {
-  data: T;
-  timestamp: number;
-  expiresAt: number;
-  key: string;
-  sequence: number; // 请求序列号
-  metadata?: Record<string, unknown>;
-}
-
-export interface CacheStats {
-  cacheCount: number;
-  validCount: number;
-  expiredCount: number;
-}
-
-export interface RequestAdapter<TRequest, TResponse, TCacheData, TRealTimeData> {
-  /** 执行实际的网络请求 */
-  execute(endpoint: string, options?: TRequest): Promise<TResponse>;
-  /** 从响应中提取需要缓存的部分（不变数据） */
-  extractCacheableData?(response: TResponse): TCacheData;
-  /** 从响应中提取实时数据部分（变化数据） */
-  extractRealTimeData?(response: TResponse): TRealTimeData;
-  /** 合并缓存数据和实时数据 */
-  mergeData?(cached: TCacheData, realTime: TRealTimeData): TResponse;
-  /** 处理纯缓存场景的数据，当没有新的网络请求时 */
-  processCachedData?(cached: TCacheData): TResponse;
-}
-
-export abstract class RequestCacheService<TRequest, TResponse, TCacheData, TRealTimeData> {
-  private cache = new Map<string, CacheEntry<TCacheData>>();
-  private readonly config: {
-    duration: number;
-    timeout: number;
-    keyGenerator: <TReq>(endpoint: string, params?: TReq) => string;
-    consistencyChecker: (cached: TCacheData, serverData: TCacheData) => boolean;
-  };
-
-  // 请求去重：每个key只允许同时有一个正在进行的请求
-  private pendingRequests = new Map<string, Promise<TResponse>>();
-
-  // 请求序列号：防止晚到的请求覆盖早发出的请求结果
-  private requestSequence = 0;
-  private cacheSequences = new Map<string, number>();
-
-  constructor(
-    protected requestAdapter: RequestAdapter<TRequest, TResponse, TCacheData, TRealTimeData>,
-    config: Partial<CacheConfig<TCacheData, TCacheData>> = {}
-  ) {
-    this.config = {
-      duration: 10 * 60 * 1000, // 10分钟
-      timeout: 3000, // 3秒
-      keyGenerator: <TReq>(endpoint: string, _params?: TReq) => endpoint,
-      consistencyChecker: () => true,
-      ...config
-    };
-  }
-
-  /**
-   * 带缓存的请求方法 - 缓存优先 + 实时数据混合模式 + 请求去重
-   */
-  async request(endpoint: string, options?: TRequest): Promise<TResponse> {
-    const cacheKey = this.config.keyGenerator(endpoint, options);
-
-    // 检查是否有正在进行的请求，如果有则等待其完成
-    const pendingRequest = this.pendingRequests.get(cacheKey);
-    if (pendingRequest) {
-      console.log(`[RequestCacheService] Reusing pending request for ${endpoint}`);
-      return pendingRequest;
-    }
-
-    // internal request promise for background update
-    const internalRequestPromise = this.requestInternal(endpoint, options);
-
-    // createTimeoutPromise
-    const timeoutPromise = this.createTimeoutPromise();
-
-    // usePromiseRace
-    const racedPromise = Promise.race([internalRequestPromise, timeoutPromise]).catch(async (error) => {
-      // if timeout error, try to get data from cache as fallback
-      if (error.message.includes('timeout')) {
-        const cachedData = this.getValidCachedData(cacheKey);
-        if (cachedData) {
-          console.warn(`[RequestCacheService] Request timeout, falling back to cache for ${endpoint}`);
-          return this.requestAdapter.processCachedData
-            ? this.requestAdapter.processCachedData(cachedData)
-            : (cachedData as TResponse);
-        }
-      }
-      throw error;
-    });
-
-    this.pendingRequests.set(cacheKey, racedPromise);
-
-    // ensure internal request can be completed in background for cache update
-    internalRequestPromise
-      .then((result) => {
-        // 成功时不需要特殊处理，requestInternal 已经更新了缓存
-        console.log(`[RequestCacheService] Background request completed successfully for ${endpoint}`);
-      })
-      .catch((error) => {
-        console.warn(`[RequestCacheService] Background request failed for ${endpoint}:`, error);
-      });
-
-    try {
-      const result = await racedPromise;
-      return result;
-    } finally {
-      // 请求完成后清理 pending request
-      this.pendingRequests.delete(cacheKey);
-    }
-  }
-
-  private async requestInternal(endpoint: string, options?: TRequest): Promise<TResponse> {
-    const cacheKey = this.config.keyGenerator(endpoint, options);
-    const currentSequence = ++this.requestSequence; // 生成请求序列号
-
-    const cachedData = this.getValidCachedData(cacheKey);
-
-    console.log('[RequestCacheService] requestInternal start', endpoint, 'cached:', cachedData);
-    if (cachedData) {
-      if (this.requestAdapter.extractRealTimeData && this.requestAdapter.mergeData) {
-        try {
-          const freshResponse = await this.requestAdapter.execute(endpoint, options);
-          const realTimeData = this.requestAdapter.extractRealTimeData(freshResponse);
-
-          const serverCacheableData = this.requestAdapter.extractCacheableData?.(freshResponse);
-          if (serverCacheableData && !this.config.consistencyChecker(cachedData, serverCacheableData)) {
-            console.log(`[RequestCacheService] Cache invalidated due to data change for ${endpoint}`);
-            this.setCachedDataWithSequence(cacheKey, serverCacheableData, currentSequence);
-            return freshResponse;
-          }
-
-          return this.requestAdapter.mergeData(cachedData, realTimeData);
-        } catch (error) {
-          console.warn(
-            `[RequestCacheService] Failed to fetch real-time data, using cache only for ${endpoint}:`,
-            error
-          );
-          return this.requestAdapter.processCachedData
-            ? this.requestAdapter.processCachedData(cachedData)
-            : (cachedData as TResponse);
-        }
-      }
-
-      console.log(`[RequestCacheService] use cache for ${endpoint}`);
-      return this.requestAdapter.processCachedData
-        ? this.requestAdapter.processCachedData(cachedData)
-        : (cachedData as TResponse);
-    }
-
-    console.log(
-      `[RequestCacheService] Cache miss, fetching fresh data for ${endpoint} (sequence: ${currentSequence})`
-    );
-    const freshResponse = await this.requestAdapter.execute(endpoint, options);
-
-    const serverCacheableData = this.requestAdapter.extractCacheableData?.(freshResponse);
-    if (serverCacheableData) {
-      this.setCachedDataWithSequence(cacheKey, serverCacheableData, currentSequence);
-    }
-
-    return freshResponse;
-  }
-
-  /**
-   * timeout
-   */
-  private createTimeoutPromise(): Promise<never> {
-    return new Promise((_, reject) => {
-      setTimeout(() => {
-        reject(
-          new Error(`[RequestCacheService] Request timeout after ${this.config.timeout / 1000} seconds`)
-        );
-      }, this.config.timeout);
-    });
-  }
-
-  /**
-   * get valid cached data
-   */
-  private getValidCachedData(key: string): TCacheData | null {
-    const cached = this.cache.get(key);
-
-    if (!cached) {
-      return null;
-    }
-
-    // 检查过期
-    if (Date.now() > cached.expiresAt) {
-      this.cache.delete(key);
-      return null;
-    }
-
-    return cached.data;
-  }
-
-  /**
-   * 设置缓存数据 (带序列号检查)
-   */
-  private setCachedDataWithSequence(
-    key: string,
-    data: TCacheData,
-    sequence: number,
-    metadata?: Record<string, unknown>
-  ): void {
-    const existing = this.cache.get(key);
-
-    // 如果已有缓存且序列号更新（说明当前请求是过时的），则不更新缓存
-    if (existing && existing.sequence > sequence) {
-      console.log(
-        `[RequestCacheService] Ignoring stale cache update for ${key} (current: ${existing.sequence}, incoming: ${sequence})`
-      );
-      return;
-    }
-
-    const now = Date.now();
-    this.cache.set(key, {
-      data: JSON.parse(JSON.stringify(data)), // 深拷贝
-      timestamp: now,
-      expiresAt: now + this.config.duration,
-      key,
-      sequence,
-      metadata
-    });
-
-    this.cacheSequences.set(key, sequence);
-    console.log(`[RequestCacheService] Updated cache for ${key} with sequence ${sequence}`);
-  }
-
-  /**
-   * refresh cache
-   */
-  async refreshCache(endpoint: string, options?: TRequest): Promise<TResponse> {
-    const cacheKey = this.config.keyGenerator(endpoint, options);
-    this.cache.delete(cacheKey);
-
-    return this.request(endpoint, options);
-  }
-
-  /**
-   * force request and update cache
-   */
-  async forceRequest(endpoint: string, options?: TRequest): Promise<TResponse> {
-    const cacheKey = this.config.keyGenerator(endpoint, options);
-    const currentSequence = ++this.requestSequence;
-
-    console.log(`[RequestCacheService] Force request for ${endpoint} (sequence: ${currentSequence})`);
-
-    const freshResponse = await this.requestAdapter.execute(endpoint, options);
-
-    const serverCacheableData = this.requestAdapter.extractCacheableData?.(freshResponse);
-
-    if (serverCacheableData) {
-      this.setCachedDataWithSequence(cacheKey, serverCacheableData, currentSequence);
-      console.log(`[RequestCacheService] Force updated cache for ${endpoint}`);
-    }
-
-    return freshResponse;
-  }
-
-  /**
-   * warmup cache - 避免与正在进行的请求冲突
-   */
-  async warmupCache(endpoint: string, options?: TRequest): Promise<void> {
-    const cacheKey = this.config.keyGenerator(endpoint, options);
-
-    // 如果有正在进行的请求，跳过 warmup
-    if (this.pendingRequests.has(cacheKey)) {
-      console.log(`[RequestCacheService] Skipping warmup for ${endpoint} - request in progress`);
-      return;
-    }
-
-    // 如果已有有效缓存，跳过 warmup
-    if (this.hasValidCache(cacheKey)) {
-      console.log(`[RequestCacheService] Skipping warmup for ${endpoint} - valid cache exists`);
-      return;
-    }
-
-    try {
-      console.log(`[RequestCacheService] Warming up cache for ${endpoint}`);
-      await this.forceRequest(endpoint, options);
-    } catch (error) {
-      console.warn(`[RequestCacheService] Cache warmup failed for ${endpoint}:`, error);
-    }
-  }
-
-  /**
-   * clear cache with target key
-   */
-  clearCache(key?: string): void {
-    if (key) {
-      this.cache.delete(key);
-      this.cacheSequences.delete(key);
-      this.pendingRequests.delete(key);
-      console.log(`[RequestCacheService] Cleared cache for ${key}`);
-    } else {
-      this.cache.clear();
-      this.cacheSequences.clear();
-      this.pendingRequests.clear();
-      this.requestSequence = 0; // 重置序列号
-      console.log('[RequestCacheService] Cleared all cache');
-    }
-  }
-
-  /**
-   * clear expired cache
-   */
-  clearExpiredCache(): void {
-    const now = Date.now();
-    for (const [key, entry] of this.cache) {
-      if (now > entry.expiresAt) {
-        this.cache.delete(key);
-        this.cacheSequences.delete(key);
-      }
-    }
-    console.log('[RequestCacheService] Cleared expired cache entries');
-  }
-
-  /**
-   * get cache stats
-   */
-  getCacheStats(): CacheStats & { pendingRequestCount: number } {
-    const now = Date.now();
-    let validCount = 0;
-    let expiredCount = 0;
-
-    for (const entry of this.cache.values()) {
-      if (now > entry.expiresAt) {
-        expiredCount++;
-      } else {
-        validCount++;
-      }
-    }
-
-    return {
-      cacheCount: this.cache.size,
-      validCount,
-      expiredCount,
-      pendingRequestCount: this.pendingRequests.size
-    };
-  }
-
-  /**
-   * get all cache keys
-   */
-  getCacheKeys(): string[] {
-    return Array.from(this.cache.keys());
-  }
-
-  /**
-   * check if the target key has valid cache
-   */
-  hasValidCache(key: string): boolean {
-    const cached = this.cache.get(key);
-    return cached ? Date.now() <= cached.expiresAt : false;
-  }
-
-  /**
-   * get pending request keys for debugging
-   */
-  getPendingRequestKeys(): string[] {
-    return Array.from(this.pendingRequests.keys());
-  }
-
-  /**
-   * check if a request is currently pending
-   */
-  hasPendingRequest(key: string): boolean {
-    return this.pendingRequests.has(key);
-  }
-
-  /**
-   * get cache sequence for a specific key
-   */
-  getCacheSequence(key: string): number | undefined {
-    return this.cacheSequences.get(key);
-  }
-}