front/src/utils/safeStorage.ts

/**
 * 类型安全的 localStorage 封装，具备严格的 key 管理
 */
 
// 1. 定义应用程序使用的存储键名（防止使用任意字符串作为 key）
export enum AppStorageKey {
    PASSPORT_DATA  = 'passportData',
    PASSPORT_TOKEN = 'passportToken',
    MENU_DATA      = 'menuData', // 全部的菜单数据
    SLIDER_MENU    = 'sliderMenu', // 侧边栏菜单数据
    USER_INFO = 'userInfo',
    TOKEN = 'token',
    MODE = 'mode', // 日间夜间模式 
  }
  
  // 2. 存储值类型定义（用于内部处理）
  type StorageValue<T> = {
    __data: T;                            // 实际存储的数据
    __expiry?: number;                     // 可选的过期时间戳
  };
  
  // 3. 主存储类
  class SafeStorage {
    /**
     * 存储数据（自动处理 JSON 序列化）
     * @param key 预定义的存储键
     * @param value 要存储的值（支持所有 JSON 安全类型）
     * @param ttl 可选的时间有效期（毫秒）
     */
    static set<T>(key: AppStorageKey, value: T, ttl?: number): void {
      if (typeof window === "undefined") return;
      
      try {
        // 创建存储对象（包含数据值和过期时间）
        const storageValue: StorageValue<T> = {
          __data: value,
        };
        
        // 设置过期时间（如果提供）
        if (ttl !== undefined && ttl > 0) {
          storageValue.__expiry = Date.now() + ttl;
        }
        
        // 自动序列化并存储
        localStorage.setItem(key, JSON.stringify(storageValue));
      } catch (error) {
        console.error(`[存储] 保存失败 (key: ${key})`, error);
        this.handleStorageError(key, error);
      }
    }
  
    /**
     * 获取数据（自动反序列化并检查过期）
     * @param key 预定义的存储键
     * @returns 存储的值或 null（如果不存在或过期）
     */
    static get<T>(key: AppStorageKey): T | null {
      if (typeof window === "undefined") return null;
      
      try {
        // 获取原始数据
        const rawData = localStorage.getItem(key);
        if (!rawData) return null;
        
        // 解析为内部存储结构
        const storageValue = JSON.parse(rawData) as StorageValue<T>;
        
        // 检查是否过期
        if (this.isExpired(storageValue)) {
          this.remove(key);
          return null;
        }
        
        // 返回实际数据
        return storageValue.__data;
      } catch (error) {
        console.error(`[存储] 解析失败 (key: ${key})`, error);
        this.remove(key); // 移除无效数据
        return null;
      }
    }
  
    /**
     * 删除指定存储项
     * @param key 要删除的存储键
     */
    static remove(key: AppStorageKey): void {
      if (typeof window === "undefined") return;
      localStorage.removeItem(key);
    }
  
    /**
     * 清除应用相关的所有存储
     */
    static clearAppStorage(): void {
      if (typeof window === "undefined") return;
      
      // 遍历所有预定义的 key 进行删除
      Object.values(AppStorageKey).forEach(key => {
        localStorage.removeItem(key);
      });
    }
  
    // ----------------------------- 私有辅助方法 -----------------------------
    
    /**
     * 检查存储值是否过期
     */
    private static isExpired<T>(value: StorageValue<T>): boolean {
      return value.__expiry !== undefined && Date.now() > value.__expiry;
    }
  
    /**
     * 处理存储错误（配额不足等）
     */
    private static handleStorageError(key: AppStorageKey, error: unknown): void {
      // 处理存储空间不足错误
      if (error instanceof DOMException && error.name === 'QuotaExceededError') {
        console.warn('存储空间不足，尝试清理过期数据');
        this.clearExpiredItems();
        
        // 尝试重新存储（最多尝试一次）
        try {
          const raw = localStorage.getItem(key);
          if (raw) {
            const value = JSON.parse(raw) as StorageValue<unknown>;
            if (!this.isExpired(value)) {
              localStorage.setItem(key, raw);
              return;
            }
          }
        } catch (retryError) {
          console.error('重试存储失败', retryError);
        }
      }
    }
  
    /**
     * 清理所有过期的存储项
     */
    private static clearExpiredItems(): void {
      Object.values(AppStorageKey).forEach(key => {
        try {
          const raw = localStorage.getItem(key);
          if (raw) {
            const value = JSON.parse(raw) as StorageValue<unknown>;
            if (this.isExpired(value)) {
              localStorage.removeItem(key);
            }
          }
        } catch (e) {
          // 忽略无效数据
        }
      });
    }
  }
  
  export default SafeStorage;