refactor(music-cache): 模糊匹配时按音质优先级自动选择最佳缓存 (#1009)

laoshuikaixue · MoYingJi · web-flow · commit bea6f8f9b828 · 2026-04-06T19:33:48.000+08:00
* Add environment variables for web and API configuration

* Update API URL to use HTTPS

* Update API URL in .env file

* feat(electron): 优化音乐缓存服务的音质优先级和MD5验证机制

- 添加音质优先级映射表，支持多种音质等级排序
- 实现缓存元数据文件管理，存储MD5和文件大小信息
- 新增getMetaPath、readMeta、writeMeta等元数据操作方法
- 实现pickCandidates方法按音质优先级和修改时间选择候选缓存
- 重构hasCache方法支持按音质优先级自动选择最佳缓存
- 改进MD5验证逻辑，添加元数据缓存减少重复计算
- 优化下载完成后的元数据写入流程

* config: 移除环境变量配置文件

* fix(cache): 解决音乐缓存服务异常处理和元数据写入问题

- 添加了精确缓存检查和获取候选缓存的错误捕获及警告日志
- 将元数据写入改为异步执行避免阻塞主流程
- 添加了元数据写入失败的错误处理和警告日志
- 保持了文件重命名和缓存大小记录功能的正常执行

* Update electron/main/services/MusicCacheService.ts

Co-authored-by: MoYingJi &lt;moyingjiaw@outlook.com&gt;

* refactor(music-cache): 优化音乐缓存元数据存储机制

- 移除文件系统元数据文件读写，改用缓存服务存储
- 删除不再使用的 getMetaPath 方法
- 更新 readMeta 方法以从缓存中读取元数据
- 修改 writeMeta 方法将元数据写入缓存服务
- 调整 removeCacheWithMeta 方法使用缓存服务删除元数据
- 简化元数据键名生成逻辑

* fix(cache): 修复音质优先级匹配问题

- 将音质优先级映射中的键值从大写改为小写
- 修改getQualityWeight方法以支持大小写不敏感的音质匹配
- 确保音质比较时统一转换为小写进行匹配

* refactor(music-cache): 移除私有缓存文件删除方法并内联实现

- 删除了 private removeCacheFile 方法
- 将文件删除逻辑直接内联到调用处
- 保持相同的错误处理行为

* docs: 补充代码注释

* refactor(music): 简化音质优先级配置

- 移除注释中的枚举值兼容性说明
- 统一音质键名的字符串格式
- 删除冗余的音质选项如lossless、flac、exhigh等
- 保留核心音质等级配置
- 优化对象结构提高可读性

---------

Co-authored-by: MoYingJi &lt;moyingjiaw@outlook.com&gt;
diff --git a/electron/main/services/MusicCacheService.ts b/electron/main/services/MusicCacheService.ts
@@ -13,6 +13,19 @@ export class MusicCacheService {
   private static instance: MusicCacheService;
   private cacheService: CacheService;
   private downloadingTasks: Map<string, Promise<string>> = new Map();
+  /** 音质优先级 */
+  private readonly qualityPriority: Record<string, number> = {
+    "master": 100,
+    "dolby": 95,
+    "spatial": 90,
+    "surround": 85,
+    "hi-res": 80,
+    "sq": 70,
+    "hq": 60,
+    "mq": 50,
+    "lq": 40,
+    "standard": 40,
+  };
 
   private constructor() {
     this.cacheService = CacheService.getInstance();
@@ -34,6 +47,54 @@ export class MusicCacheService {
     return `${id}_${quality}.sc`;
   }
 
+  /**
+   * 从缓存文件名中提取音质标识
+   */
+  private getQualityFromKey(id: number | string, key: string): string | null {
+    const prefix = `${id}_`;
+    if (!key.startsWith(prefix) || !key.endsWith(".sc")) {
+      return null;
+    }
+    return key.slice(prefix.length, -3);
+  }
+
+  /**
+   * 获取音质权重
+   */
+  private getQualityWeight(quality: string): number {
+    return this.qualityPriority[quality.toLowerCase()] ?? 0;
+  }
+
+  /**
+   * 按音质优先级和最近修改时间筛选候选缓存
+   */
+  private async pickCandidates(
+    id: number | string,
+  ): Promise<Array<{ filePath: string; quality: string }>> {
+    const items = await this.cacheService.list("music");
+    const result: Array<{ filePath: string; quality: string; weight: number; mtime: number }> = [];
+    for (const item of items) {
+      const quality = this.getQualityFromKey(id, item.key);
+      if (!quality) {
+        continue;
+      }
+      const filePath = this.cacheService.getFilePath("music", item.key);
+      result.push({
+        filePath,
+        quality,
+        weight: this.getQualityWeight(quality),
+        mtime: item.mtime,
+      });
+    }
+    result.sort((a, b) => {
+      if (b.weight !== a.weight) {
+        return b.weight - a.weight;
+      }
+      return b.mtime - a.mtime;
+    });
+    return result.map(({ filePath, quality }) => ({ filePath, quality }));
+  }
+
   /**
    * 计算文件 MD5
    */
@@ -49,60 +110,62 @@ export class MusicCacheService {
 
   /**
    * 检查缓存是否存在
-   * 如果 quality 为 undefined，则返回任意一个匹配 id 的缓存（如果存在）
-   * 如果提供了 expectedMD5，则会校验文件 MD5，不一致则删除缓存并返回 null
+   * 指定 quality 时仅检查目标音质
+   * 未指定 quality 时按音质优先级和最近修改时间选择候选缓存
+   * 提供 expectedMD5 时会校验文件哈希，不一致则删除旧缓存
    */
   public async hasCache(
     id: number | string,
     quality?: string,
     expectedMD5?: string,
   ): Promise<string | null> {
-    let filePath: string | null = null;
-
-    // 1. 精确查找：如果指定了音质，直接检查对应文件是否存在
+    const candidates: Array<{ filePath: string; quality: string }> = [];
     if (quality) {
       const key = this.getCacheKey(id, quality);
       try {
         const p = this.cacheService.getFilePath("music", key);
         if (existsSync(p)) {
-          filePath = p;
+          candidates.push({ filePath: p, quality });
         }
-      } catch {
-        // ignore
+      } catch (e) {
+        cacheLog.warn(`[MusicCache] 检查精确缓存失败，ID: ${id}, 音质: ${quality}:`, e);
       }
     } else {
-      // 2. 模糊查找：如果未指定音质，查找该 ID 下的任意缓存文件
       try {
-        const items = await this.cacheService.list("music");
-        // 查找以 id_ 开头且以 .sc 结尾的文件
-        const prefix = `${id}_`;
-        const match = items.find((item) => item.key.startsWith(prefix) && item.key.endsWith(".sc"));
-        if (match) {
-          filePath = this.cacheService.getFilePath("music", match.key);
-        }
-      } catch {
-        // ignore
+        candidates.push(...(await this.pickCandidates(id)));
+      } catch (e) {
+        cacheLog.warn(`[MusicCache] 获取候选缓存失败，ID: ${id}:`, e);
       }
     }
 
-    // 如果找到文件且需要校验 MD5
-     if (filePath && expectedMD5) {
-       try {
-         const fileMD5 = await this.calculateMD5(filePath);
-         if (fileMD5.toLowerCase() !== expectedMD5.toLowerCase()) {
-            cacheLog.info(
-              `[MusicCache] 缓存 MD5 不匹配，删除旧缓存。ID: ${id}, 期望: ${expectedMD5}, 实际: ${fileMD5}`,
-            );
-            await unlink(filePath).catch(() => {});
+    for (const candidate of candidates) {
+      const { filePath, quality: candidateQuality } = candidate;
+      // 无需校验哈希时，命中即返回
+      if (!expectedMD5) {
+        return filePath;
+      }
+      try {
+        const fileMD5 = await this.calculateMD5(filePath);
+        if (fileMD5.toLowerCase() !== expectedMD5.toLowerCase()) {
+          cacheLog.info(
+            `[MusicCache] 缓存 MD5 不匹配，删除旧缓存。ID: ${id}, 音质: ${candidateQuality}, 期望: ${expectedMD5}, 实际: ${fileMD5}`,
+          );
+          await unlink(filePath).catch(() => {});
+          if (quality) {
             return null;
           }
-       } catch (error) {
-         cacheLog.error(`[MusicCache] Failed to calculate MD5 for ${filePath}:`, error);
-         return null;
-       }
-     }
+          continue;
+        }
+        return filePath;
+      } catch (error) {
+        cacheLog.error(`[MusicCache] 校验缓存 MD5 失败，路径: ${filePath}:`, error);
+        if (quality) {
+          return null;
+        }
+      }
+    }
 
-    return filePath;
+    return null;
   }
 
   /**
