From 537e280fdd36caef0a4ed0fa5353ce12a813e66d Mon Sep 17 00:00:00 2001 From: chengww Date: Sun, 17 May 2026 23:07:58 +0800 Subject: [PATCH] =?UTF-8?q?refactor(persist):=20=E6=8A=BD=E5=85=AC?= =?UTF-8?q?=E5=85=B1=E9=98=B2=E6=8A=96=20storage=20=E4=B8=8E=20minifySong?= =?UTF-8?q?=20=E5=B7=A5=E5=85=B7=EF=BC=8Cplaylist/playerCore=20=E6=8E=A5?= =?UTF-8?q?=E5=85=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 把 9caaec3 在 playlist 内联的 minifySong + debouncedLocalStorage 抽到 utils 共用，playerCore 同步接入，为后续推广到 playHistory 做准备。 - 新增 utils/debouncedStorage.ts：高频状态变更（volume 拖动、isPlay 切换）2s 防抖落盘，beforeunload 钩子兜底刷盘；多 store 共用同一 pendingWrites map，flush 时一次写完所有 pending key - 新增 utils/persistedSong.ts：minifySong 剥离 base64 picUrl、仅保留 local:// 永不过期的 playMusicUrl；ar.length 守卫避免空数组吞掉 s.artists 兜底；al.id 守卫避免序列化出无 id 空壳 - playlist.ts 删除内联实现改用 import，行为不变 - playerCore.ts 切到防抖落盘并 minify playMusic；id 守卫避免空 playMusic 走 minify 后失去 Object.keys().length===0 判空能力， 下次启动会误恢复一首无 id 的空歌 Trade-off：极端非正常退出（kill -9 / 断电）下最近 2s 的 volume / isPlay / playMusic 变更会丢——这些状态丢一次无大碍，可接受 --- src/renderer/store/modules/playerCore.ts | 26 +++- src/renderer/store/modules/playlist.ts | 71 +-------- src/renderer/utils/debouncedStorage.ts | 68 ++++++++ src/renderer/utils/persistedSong.ts | 188 +++++++++++++++++++++++ 4 files changed, 282 insertions(+), 71 deletions(-) create mode 100644 src/renderer/utils/debouncedStorage.ts create mode 100644 src/renderer/utils/persistedSong.ts diff --git a/src/renderer/store/modules/playerCore.ts b/src/renderer/store/modules/playerCore.ts index 3c0ac05..21efd7f 100644 --- a/src/renderer/store/modules/playerCore.ts +++ b/src/renderer/store/modules/playerCore.ts @@ -4,6 +4,8 @@ import { computed, ref } from 'vue'; import { audioService } from '@/services/audioService'; import type { AudioOutputDevice } from '@/types/audio'; import type { SongResult } from '@/types/music'; +import { debouncedLocalStorage } from '@/utils/debouncedStorage'; +import { minifySong } from '@/utils/persistedSong'; /** * 核心播放控制 Store @@ -220,7 +222,12 @@ export const usePlayerCoreStore = defineStore( { persist: { key: 'player-core-store', - storage: localStorage, + // 使用 debouncedLocalStorage：volume 拖动 / 静音切换会高频触发 mutation， + // 直接写 localStorage 会导致每次都 stringify + minify 整个 state，浪费 I/O。 + // 防抖 2s 写一次足够，beforeunload 钩子兜底刷盘。 + // Trade-off：极端非正常退出（kill -9 / 断电 / 主进程崩溃）下 beforeunload 不触发， + // 最近 2s 的 volume / isPlay / playMusic 变更会丢——这些状态丢一次无大碍，可接受 + storage: debouncedLocalStorage, pick: [ 'playMusic', 'playMusicUrl', @@ -229,7 +236,22 @@ export const usePlayerCoreStore = defineStore( 'isMuted', 'isPlay', 'audioOutputDeviceId' - ] + ], + // playMusic 持久化前过 minifySong：剥离 base64 封面、lyric、song 等大字段。 + // 单首歌的 lyric 持久化后没有用（重启后会重新加载），但 picUrl 若是 base64 会 + // 拖累整个 player-core-store 写入失败（5MB 配额）。playMusicUrl 在 store 层级单独 + // 持久化，不受 playMusic 内部精简影响——本地音乐 local:// URL 仍保持可恢复。 + // id 守卫：空 playMusic 走 minifySong 会得到 {picUrl:'', ar:[]}（stripDataUrl + // 把 undefined 转成空串、ar 缺省返回空数组），下次启动 playbackController 的 + // Object.keys().length === 0 判空就会失效，误恢复一首无 id 的空歌 + serializer: { + serialize: (state: any) => + JSON.stringify({ + ...state, + playMusic: state.playMusic?.id ? minifySong(state.playMusic as SongResult) : {} + }), + deserialize: JSON.parse + } } } ); diff --git a/src/renderer/store/modules/playlist.ts b/src/renderer/store/modules/playlist.ts index 4b0a5f0..d0e5144 100644 --- a/src/renderer/store/modules/playlist.ts +++ b/src/renderer/store/modules/playlist.ts @@ -1,5 +1,4 @@ import { useThrottleFn } from '@vueuse/core'; -import { debounce } from 'lodash'; import { createDiscreteApi } from 'naive-ui'; import { defineStore, storeToRefs } from 'pinia'; import { computed, ref, shallowRef, triggerRef } from 'vue'; @@ -9,6 +8,8 @@ import { useSongDetail } from '@/hooks/usePlayerHooks'; import { preloadService } from '@/services/preloadService'; import type { SongResult } from '@/types/music'; import { getImgUrl } from '@/utils'; +import { debouncedLocalStorage } from '@/utils/debouncedStorage'; +import { minifySongList } from '@/utils/persistedSong'; import { performShuffle, preloadCoverImage } from '@/utils/playerUtils'; import { useIntelligenceModeStore } from './intelligenceMode'; @@ -22,74 +23,6 @@ const getMessage = () => { return _message; }; -/** - * 精简 SongResult 对象，只保留持久化必要字段 - * 排除大体积字段：lyric, song, backgroundColor, primaryColor - * - * picUrl/al.picUrl 若为 base64 Data URL 一律剥离：localStorage 仅 5MB 配额， - * 单张 base64 封面动辄几百 KB，几首就能撑爆导致整个 playList 写入失败。 - * 剥离后恢复时展示默认封面图，picUrl 仍是 http(s):// 或 local:// 短引用时原样保留。 - * - * 仅 local:// 的 playMusicUrl（永不过期）会被持久化，让本地音乐恢复后免重新解析； - * expiredAt 不持久化——本地音乐每次走 toSongResult 会重新生成，远程歌曲恢复后重新拉详情即可。 - */ -const stripDataUrl = (url: string | undefined): string => - !url || url.startsWith('data:') ? '' : url; - -const minifySong = (s: SongResult) => ({ - id: s.id, - name: s.name, - picUrl: stripDataUrl(s.picUrl), - ar: s.ar?.map((a) => ({ id: a.id, name: a.name })), - al: s.al && { id: s.al.id, name: s.al.name, picUrl: stripDataUrl(s.al.picUrl) }, - source: s.source, - dt: s.dt, - // 仅 local:// 永不过期，保留给本地音乐恢复后免重新解析；其他 URL 会过期，丢掉让恢复时重新拉 - // JSON.stringify 自动丢 undefined，无需条件 spread - playMusicUrl: s.playMusicUrl?.startsWith('local://') ? s.playMusicUrl : undefined -}); - -const minifySongList = (list: SongResult[] | undefined) => list?.map(minifySong) ?? []; - -/** - * 防抖 localStorage 包装，降低写入频率 - * 通过 pendingWrites 跟踪未写入数据，beforeunload 时刷新 - */ -const pendingWrites = new Map(); - -const safeSetItem = (key: string, value: string) => { - try { - localStorage.setItem(key, value); - } catch (error) { - console.error('[playlist] localStorage 写入失败（可能超出配额）:', error); - } -}; - -const flushPendingWrites = () => { - pendingWrites.forEach((value, key) => { - safeSetItem(key, value); - }); - pendingWrites.clear(); -}; - -const debouncedSetItem = debounce((key: string, value: string) => { - safeSetItem(key, value); - pendingWrites.delete(key); -}, 2000); - -const debouncedLocalStorage = { - getItem: (key: string) => localStorage.getItem(key), - setItem: (key: string, value: string) => { - pendingWrites.set(key, value); - debouncedSetItem(key, value); - } -}; - -// 正常关闭时刷新未写入的数据 -if (typeof window !== 'undefined') { - window.addEventListener('beforeunload', flushPendingWrites); -} - /** * 播放列表管理 Store * 负责：播放列表、索引、播放模式、预加载、上/下一首 diff --git a/src/renderer/utils/debouncedStorage.ts b/src/renderer/utils/debouncedStorage.ts new file mode 100644 index 0000000..2b24139 --- /dev/null +++ b/src/renderer/utils/debouncedStorage.ts @@ -0,0 +1,68 @@ +// 防抖 localStorage 包装：高频状态变更（volume 拖动、播放/暂停切换） +// 在 2s 内只落盘一次，正常关闭时通过 beforeunload 刷新未写入数据。 +// pinia-plugin-persistedstate 默认每次 mutation 都同步写入；换成这个包装即可 +// 降低 I/O 与 JSON.stringify/minify 的总开销。 +// +// 多 store 共用同一实例：debounce 的回调不带 key 参数，触发时 flush 整个 +// pendingWrites map。这样多个 key 在防抖窗口内交替写入也不会互相吞参数 +// （lodash debounce 只用最后一次的参数触发）。 + +import { debounce } from 'lodash'; + +const pendingWrites = new Map(); + +const safeSetItem = (key: string, value: string) => { + try { + localStorage.setItem(key, value); + } catch (error) { + // 配额超限是预期失败：上层 store 已通过 minifySong 兜底，这里仅记录方便定位 + console.error(`[debouncedStorage] localStorage 写入失败 key=${key}（可能超出配额）:`, error); + } +}; + +/** 把 pendingWrites 里所有未落盘的 key 一次性写入并清空 */ +const flushPendingWrites = () => { + pendingWrites.forEach((value, key) => { + safeSetItem(key, value); + }); + pendingWrites.clear(); +}; + +const debouncedFlush = debounce(flushPendingWrites, 2000); + +/** + * 与 localStorage 接口兼容的防抖写入实例 + * 多个 Pinia store 共用同一个，避免重复创建定时器/监听器 + * + * 注意：极端非正常退出（kill -9 / 系统断电 / 主进程崩溃）下 beforeunload + * 不一定触发，最近 2s 的写入可能丢失。对 volume / isPlay / playMusic 等 + * 「丢一次也无大碍」的状态可以接受；如果新增了不能容忍丢写的关键状态， + * 应直接用 localStorage 而非 debouncedLocalStorage。 + */ +export const debouncedLocalStorage = { + getItem: (key: string) => localStorage.getItem(key), + setItem: (key: string, value: string) => { + pendingWrites.set(key, value); + debouncedFlush(); + }, + removeItem: (key: string) => { + // 同步清掉 pendingWrites，防止已排队的 flush 把旧值又写回去 + pendingWrites.delete(key); + localStorage.removeItem(key); + } +}; + +/** + * 立即落盘所有 pending 写入并取消排队的 debounce + * 用于一次性的关键操作（如数据迁移完成后写 flag）：先 flush 再写 flag， + * 避免「flag 已写入、store 还在防抖窗口里」的不一致 + */ +export const flushDebouncedStorage = () => { + debouncedFlush.cancel(); + flushPendingWrites(); +}; + +// 模块级注册一次：beforeunload 时立即 flush 所有未写入数据，并取消排队的 debounce +if (typeof window !== 'undefined') { + window.addEventListener('beforeunload', flushDebouncedStorage); +} diff --git a/src/renderer/utils/persistedSong.ts b/src/renderer/utils/persistedSong.ts new file mode 100644 index 0000000..de6f588 --- /dev/null +++ b/src/renderer/utils/persistedSong.ts @@ -0,0 +1,188 @@ +// 持久化歌曲对象的精简工具 +// 三处 store 共用：playlist、playerCore、playHistory +// +// 为什么需要：localStorage 仅 5MB 配额。SongResult 直接持久化时，picUrl 可能是 +// 几百 KB 的 base64 Data URL（旧版本本地音乐扫描会注入），lyric/song/expiredAt 等 +// 字段也是只在运行时有意义的派生数据。一旦撑爆配额，整个 store 写入失败 → 历史记录、 +// 当前播放、播放列表全部丢失。 +// +// 现在源头（src/main/modules/localMusicScanner.ts + filePathToLocalUrl）已经把 +// 本地音乐封面落盘，picUrl 是 local:// 短引用；这个工具兜底两件事： +// 1. 老用户从 base64 版本升级上来时，剥离已写入 localStorage 的脏数据 +// 2. 远程音乐的 lyric/expiredAt 等大字段从持久化路径切走（重启后 API 重拉即可） +// +// 仅 local:// 的 playMusicUrl 会保留——本地音乐 URL 永不过期，恢复后免重新解析。 +// 其他 URL（云端、缓存代理）会过期，丢掉让恢复时重新拉。 + +import type { Artist, SongResult } from '@/types/music'; +import type { DjProgram } from '@/types/podcast'; + +/** + * 播客 program 持久化保留的最小字段集合 + * + * SongResult.program 在运行时是 any（来源接口透传），实际形态对齐 DjProgram。 + * 这里只保留 addPodcast/podcast 列表 UI 真正消费的字段，避免接口塞进来的冗余 + * 字段（评论列表、推荐位等）跟着持久化。仍要剥 coverUrl 的 base64 兜底。 + */ +export type MinifiedDjProgram = Pick< + DjProgram, + | 'id' + | 'name' + | 'mainSong' + | 'radio' + | 'coverUrl' + | 'description' + | 'createTime' + | 'listenerCount' + | 'commentCount' + | 'liked' + | 'likedCount' +>; + +/** + * 持久化保留的最小字段集合 + * + * ar/al 类型用 SongResult['ar' | 'al'] 而非自定义 Pick： + * Artist/Album 类型有几十个必填子字段，自定义 Pick 后无法回填成 Artist[]/Album, + * 调用 setPlay/SongItem 等期望 SongResult 的接口会全部报错。这里用类型断言把 + * "只填了 id/name/picUrl 的对象"伪装成 Artist/Album——运行时下游用 optional chain + * 访问，缺字段不会炸；类型层省下一大批 cast。 + * + * isPodcast/program 必须保留：playbackController.playTrack 用 music.isPodcast + * 决定写普通歌历史还是播客历史；缺失会让重启恢复后的播客被误记进 musicHistory。 + */ +export type MinifiedSong = { + id: SongResult['id']; + name: SongResult['name']; + picUrl: SongResult['picUrl']; + ar: SongResult['ar']; + // SongResult.al 是非 optional，但 minifySong 在 s.al 缺失时返回 undefined。 + // 用 NonNullable + ? 显式表达「可选且缺失即不存在」，下游 optional chain 访问更安全 + al?: NonNullable; + source?: SongResult['source']; + dt?: SongResult['dt']; + playMusicUrl?: SongResult['playMusicUrl']; + isPodcast?: SongResult['isPodcast']; + program?: MinifiedDjProgram; +}; + +/** 历史记录条目：精简歌曲 + 计数/时间戳 */ +export type MusicHistoryItem = MinifiedSong & { + count: number; + lastPlayTime?: number; +}; + +/** + * 剥离 base64 Data URL，其余 URL 原样返回 + * 旧版本注入的 data: 协议封面 → 空串（SongItem v-if 跳过渲染，展示默认封面） + */ +const stripDataUrl = (url: string | undefined): string => + !url || url.startsWith('data:') ? '' : url; + +/** + * 把 SongResult 精简到仅持久化必要字段 + * - 剥离 base64 picUrl + * - 仅保留 local:// 协议的 playMusicUrl（本地音乐 URL 永不过期） + * - 不持久化 lyric/song/backgroundColor/primaryColor/expiredAt/createdAt 等派生数据 + * + * JSON.stringify 自动丢 undefined，不需要条件 spread + */ +export const minifySong = (s: SongResult): MinifiedSong => { + // 兼容老数据：早期 SongResult 可能只填了 artists 没填 ar（接口字段历史回退路径）， + // 取一次合并后再精简，避免 minify 后丢失歌手名导致 heatmap/SongItem 显示 'Unknown Artist' + // 用 length 守卫而不是 ??：?? 只在 null/undefined 回退，ar:[] 是 truthy 会原样保留空数组, + // 旧数据里同时存在 ar:[] 和 artists:[填值] 时会丢歌手名 + const artistList = s.ar?.length ? s.ar : s.artists; + // program 透传可能塞接口冗余字段（评论列表、推荐位等），这里挑明保留 DjProgram 已知字段 + // id 守卫：缺 id 视作无效 program，避免序列化出空壳 + const minifyProgram = (p: any): MinifiedDjProgram | undefined => { + if (!p?.id) return undefined; + return { + id: p.id, + name: p.name, + mainSong: p.mainSong, + radio: p.radio, + coverUrl: stripDataUrl(p.coverUrl), + description: p.description, + createTime: p.createTime, + listenerCount: p.listenerCount, + commentCount: p.commentCount, + liked: p.liked, + likedCount: p.likedCount + }; + }; + return { + id: s.id, + name: s.name, + picUrl: stripDataUrl(s.picUrl), + // 类型断言：只回填 id/name 的 Artist 不满足全字段约束，但下游消费 ar 全是 optional chain + ar: (artistList?.map((a) => ({ id: a.id, name: a.name })) ?? []) as Artist[], + // 类型断言同 ar：Album 类型有几十个必填字段，这里只回填三个；下游用 optional chain 访问安全 + // id 守卫：truthy 但字段全空的对象（如 `{}`）会被过滤为 undefined，避免序列化出 + // `{name: undefined, picUrl: ''}` 这种无意义残骸（id undefined 被 JSON 丢弃，反而留下空串占位） + al: (s.al?.id + ? { + id: s.al.id, + name: s.al.name, + picUrl: stripDataUrl(s.al.picUrl) + } + : undefined) as MinifiedSong['al'], + source: s.source, + dt: s.dt, + playMusicUrl: s.playMusicUrl?.startsWith('local://') ? s.playMusicUrl : undefined, + // 必须保留 isPodcast/program：playbackController.playTrack 用 music.isPodcast 决定写 + // 普通歌历史还是播客历史；缺失会让重启恢复后的播客被误记进 musicHistory + isPodcast: s.isPodcast, + program: minifyProgram(s.program) + }; +}; + +export const minifySongList = (list: SongResult[] | undefined): MinifiedSong[] => + list?.map(minifySong) ?? []; + +/** 历史记录条目精简：在 minifySong 基础上附带 count/lastPlayTime */ +export const minifyHistoryEntry = ( + s: SongResult & { count?: number; lastPlayTime?: number } +): MusicHistoryItem => ({ + ...minifySong(s), + // 能进历史 = 至少播过一次，缺省给 1 而非 0；history 列表直接 {{ count }} 显示，0 会渲染成「0 次播放」 + count: s.count ?? 1, + lastPlayTime: s.lastPlayTime +}); + +export const minifyHistoryList = ( + list: (SongResult & { count?: number; lastPlayTime?: number })[] | undefined +): MusicHistoryItem[] => list?.map(minifyHistoryEntry) ?? []; + +/** + * 通用防御层：剥离任意对象上常见图片字段中的 base64 Data URL + * + * 给 podcast/playlist/album/podcastRadio 等历史记录做兜底： + * 即使源头注入了 base64 封面（可能来自爬虫、第三方接口、旧版本数据）， + * 持久化时也会被洗成空串，避免单张几百 KB 的 Data URL 撑爆 5MB 配额。 + * + * 覆盖三个常见字段名：picUrl（专辑/电台/单曲）、coverImgUrl（歌单）、coverUrl（电台节目）。 + * 用 readonly tuple 而不是字符串数组：让 TS 把 key 推断成字面量类型集合，未来加字段需显式扩展。 + * + * 已知盲区：仅扫顶层字段，嵌套结构（DjProgram.radio.picUrl、Playlist.creator.avatarUrl 等） + * 不在覆盖范围内。当前线上数据未观察到嵌套字段被注入 base64，所以暂不递归——避免无脑深度 + * 遍历影响每次序列化的开销。后续如果发现新的嵌套注入路径，再针对该字段做点对点处理 + * （参考 minifySong 对 al.picUrl 的专门洗法），不要把 stripBase64Covers 改成递归。 + */ +const PIC_KEYS = ['picUrl', 'coverImgUrl', 'coverUrl'] as const; + +export const stripBase64Covers = >(item: T): T => { + // 浅拷贝 + 仅扫顶层：嵌套字段是已知盲区（见上方 jsdoc） + // minifySong 已专门处理嵌套 al.picUrl，此处不重复 + const result: Record = { ...item }; + for (const key of PIC_KEYS) { + const value = result[key]; + if (typeof value === 'string' && value.startsWith('data:')) { + result[key] = ''; + } + } + return result as T; +}; + +export const stripBase64CoversList = >(list: T[] | undefined): T[] => + list?.map(stripBase64Covers) ?? [];