refactor: download_music_file 拆解（205 行 / 圈 47 → 125 行 / 圈 20）

为什么：download_music_file 是**唯一**的音频落盘路径（单曲 worker、音乐批量 ZIP 都经它），205 行 / 圈复杂度 47 / 嵌套 7 的单体里叠着缓存校验、断点续传、内容嗅探、体积上限、取消语义、重试退避、元数据限流七件事，却**零直接测试覆盖** （test_zip_workers 里只有一个 stub）。任何一处被改坏都不会有测试报警。改法：拆成 8 个具名方法，主函数只留「5 步管线 + 重试策略」： _cached_result 锁内复查缓存（命中即返回，坏缓存删除重下） _promote_complete_part 已下完未改名的 .part 直接转正，不发起网络请求 _resume_offset 断点续传起点，并清理没有续传价值的残片 _transfer 占全局名额 + 选通道（aria2c / 内置 aiohttp） _size_mismatch_error 完整性判定（已知期望精确相等 / 未知期望至少非空） _publish 嗅探 → 原子转正 → 写元数据 _write_metadata_locked 标签信号量内的元数据写入（原三处重复的 with 收敛） _backoff_wait 退避秒数（原五处重复的 0.5*(attempt+1) 收敛）复杂度（同口径 AST 实测）： download_music_file 205 行 / 圈 47 / 嵌套 7 → 125 行 / 圈 20 / 嵌套 4 （125 行里 26 行是 docstring，正文 87 行）文件内嵌套 >=5 层 2 → 1（余下的是本次未动的 _fetch_via_http）文件内最大圈复杂度 47 → 35（同样落在未动的 _fetch_via_http 上）文件行数 614 → 710（+96，全是新签名与 docstring）等价性证据（两道，互相独立）： 1. 29 例行为契约测试**在未改动的原始实现上一次性全绿**（先写测试、后动代码；改完再跑仍全绿）——这批测试因此忠实编码了旧行为，构成等价性验证，而不是「照着新实现写的新行为测试」。断言只依赖返回值 / 磁盘上的文件 / 发往网络的请求，不引用任何内部函数名，故可跨后续重构复用。 2. AST 字面量多重集比对 + **逐条位置定位**：数值/布尔 27 种、字符串 80 种。差异全部归因，且**没有一条用户可见文案或阈值被改动**—— 0 +2：_resume_offset 的三个 return 0 取代原 resume_from = 0 0.0 +1、0.5 −3、1 −3：四处重复的 0.5*(attempt+1) 收敛进 _backoff_wait None +16：新增方法的 6 处类型标注 + 4 处 return None + 2 处 is not None '' +1：_size_mismatch_error 的内部哨兵（非用户可见）续传起点逻辑另做逐例核对：promote 命中 / existing<=0 / 超尺寸 / 部分四路等价。刻意保留的语义（是决定，不是疏漏）： - 退避睡眠仍在文件锁外执行——同名并发任务不陪睡。 - 缓存命中时若 write_meta 仍按本次请求重跑一次标签写入（幂等）；write_meta=False 则不写。 - 已转正（os.replace 之后）才发现取消时**不回滚文件**，只跳过元数据——原行为如此，已用 test_cancel_after_promote_keeps_file_but_skips_metadata 固化。 - 未知期望尺寸（file_size=0）走「非空即通过」+ 内容嗅探兜底；已知期望尺寸要求 **精确相等**（放宽到容差会交付截断的坏文件还照扣次数）。 - 缓存有效性用 st_size != file_size（而非 >=）：跨账号音质降级 / 上游变更都会让同 ID 同音质的实际文件不同，命中即返回会把旧文件当本次结果交付。测试：新增 tests/test_downloader.py（29 例）——正常落盘与 .part 转正、空分块跳过、进度回调（起点 / 每块 / 异常吞掉）、缓存命中不发请求、坏缓存重下、0 字节缓存拒绝、续传发 Range 并追加、服务器忽略 Range 时重写、完整残片免网络转正、超尺寸残片丢弃、 206 起点错位 / 206 缺 Content-Range / 416 三路从头重下、CDN 4xx 不重试、408 可重试、不完整保留 .part、下轮续传、未知尺寸非音频拒绝、体积上限、五种取消路径、元数据开关。验证：ruff 全过 · pyright 0/0 · pytest 274 passed（245→274）· 生产 data/ 未被触碰（全部用例走 tmp_path 沙箱）。
2026-09-27 07:56:01 +08:00
1 parent a05af4a880
commit 8716617d5d
@@ -290,6 +290,10 @@ class MusicDownloader:
            - per-file 锁：同名歌曲并发下载互斥，防止 .part 被交叉写入损坏
            - 连接复用：线程级 Session + keep-alive，避免每首歌重建 TCP/TLS 连接
            - 网络传输与 ffmpeg 元数据写入分离限流，互不抢占对方资源
+
+        本函数只保留编排与重试策略：缓存校验、续传起点、传输通道、完整性判定、
+        元数据限流各自见对应私有方法的 docstring（此前是 205 行 / 圈复杂度 47
+        的单体，任何一处改动都要通读全部步骤）。
        """
        if music_info is None:
            music_info = self.get_music_info(music_id, quality, cookies)
@@ -317,115 +321,34 @@ class MusicDownloader:
            # 同一目标文件的下载者串行化（不同文件之间仍然并行）
            with get_file_lock(file_path):
                try:
-                    # 其它线程可能刚好完成此文件，锁内复查
-                    if file_path.exists():
-                        # 缓存与本次期望不符（跨账号音质降级/上游变更都会让同 ID 同音质
-                        # 的实际文件不同）：视为缓存 miss 删除重下，而不是把旧文件
-                        # 当本次结果交付（原实现命中即返回、从不校验尺寸）。
-                        # 期望未知（file_size=0）时至少拒绝 0 字节坏文件
-                        st_size = file_path.stat().st_size
-                        cache_bad = ((music_info.file_size and st_size != music_info.file_size)
-                                     or (not music_info.file_size and st_size == 0))
-                        if cache_bad:
-                            self._unlink_quiet(file_path)
-                        else:
-                            # 缓存命中也尊重本次的元数据请求（重跑一次 ffmpeg，幂等）
-                            if write_meta:
-                                with self._tag_semaphore:
-                                    self._write_metadata(file_path, music_info, meta_fields)
-                            return DownloadResult(
-                                success=True,
-                                file_path=str(file_path),
-                                file_size=file_path.stat().st_size,
-                                music_info=music_info,
-                            )
+                    # 其它线程可能刚好完成此文件，锁内复查（命中即返回，不再下载）
+                    cached = self._cached_result(file_path, music_info,
+                                                 write_meta, meta_fields)
+                    if cached is not None:
+                        return cached

-                    # part_path 已在文件锁外绑定为 part_path0（同一路径），此处不再重复计算
-                    resume_from = 0
-                    if part_path.exists():
-                        existing = part_path.stat().st_size
-                        if music_info.file_size > 0 and existing == music_info.file_size:
-                            # 上次已下完但未改名：直接转正（转正后立即返回，
-                            # 不再发起网络请求——原实现离线时会把现成完整文件报为失败）
-                            # 改 >= 为 ==——超尺寸残片（上游多发货/坏分片）转正即交付坏文件
-                            os.replace(part_path, file_path)
-                            if write_meta:
-                                with self._tag_semaphore:
-                                    self._write_metadata(file_path, music_info, meta_fields)
-                            return DownloadResult(
-                                success=True,
-                                file_path=str(file_path),
-                                file_size=file_path.stat().st_size,
-                                music_info=music_info,
-                            )
-                        elif existing > 0:
-                            if music_info.file_size > 0 and existing > music_info.file_size:
-                                # 超尺寸残片没有续传价值（上游多发货/坏分片），
-                                # 丢弃从头下——否则下轮被 >= 误转正交付坏文件
-                                self._unlink_quiet(part_path)
-                            else:
-                                resume_from = existing  # 断点续传起点
-                        else:
-                            self._unlink_quiet(part_path)
+                    # 上次已下完但未改名的 .part：直接转正，不发起网络请求
+                    promoted = self._promote_complete_part(
+                        part_path, file_path, music_info, write_meta, meta_fields)
+                    if promoted is not None:
+                        return promoted

-                    # 排队改用可取消等待（的 acquire_cancellable）——
-                    # 原阻塞式 with 使取消后仍要等全局 10 名额腾出，任务卡死、退款延迟
-                    if not self._download_semaphore.acquire_cancellable(cancel_event, poll=0.5):
-                        raise DownloadCanceled("下载已取消")
-                    try:
-                        aria2_backend = get_backend()
-                        if aria2_backend is not None:
-                            # aria2c 通道：多连接 + 原生断点续传
-                            self._fetch_via_aria2(aria2_backend, music_info, part_path,
-                                                  cancel_event, progress_cb)
-                        else:
-                            # 内置通道：aiohttp 流式落盘 + Range 起点校验
-                            self._fetch_via_http(music_info, part_path, resume_from,
-                                                 cancel_event, progress_cb)
-                    finally:
-                        # 与 acquire_cancellable 配对释放（原 with 语义）
-                        self._download_semaphore.release()
+                    # part_path 已在文件锁外绑定为 part_path0（同一路径）
+                    self._transfer(music_info, part_path,
+                                   self._resume_offset(part_path, music_info),
+                                   cancel_event, progress_cb)

                    # 完整性校验（已知期望大小时必须精确相等；未知期望时至少非空）
-                    actual_size = part_path.stat().st_size
-                    if music_info.file_size > 0:
-                        complete = (actual_size == music_info.file_size)
-                    else:
-                        complete = (actual_size > 0)
-                    if not complete:
+                    mismatch = self._size_mismatch_error(part_path, music_info)
+                    if mismatch:
                        # 保留 .part 以便断点续传；下次续传从现有字节继续
-                        last_error = (
-                            f"下载不完整: 期望 {music_info.file_size or '未知'} 字节, "
-                            f"实际 {actual_size} 字节"
-                        )
-                        if attempt < retries:
-                            next_wait = 0.5 * (attempt + 1)   # 锁外睡眠
+                        last_error = mismatch
+                        next_wait = self._backoff_wait(attempt, retries)
                        continue

-                    # 转正前内容嗅探——未知期望尺寸（"非空即通过"口径）
-                    # 时 CDN 错误页/风控 JSON 曾可被存成音频交付
-                    if music_info.file_size <= 0 and not _sniff_audio_header(part_path):
-                        self._unlink_quiet(part_path)
-                        raise DownloadException("下载内容校验失败（非音频数据）")
-
-                    os.replace(part_path, file_path)
-
-                    # 元数据写入移出下载信号量（CPU 操作不占网络名额），
-                    # 但仍在文件锁内执行，保证其它请求看到的是已完成标记的最终文件
-                    if write_meta:
-                        # 元数据段入口补取消检查点——已取消的任务不再
-                        # 进入信号量排队/ffmpeg 等待（有界但可达 120s），收尾不再延迟
-                        if cancel_event is not None and cancel_event.is_set():
-                            raise DownloadCanceled("下载已取消")
-                        with self._tag_semaphore:
-                            self._write_metadata(file_path, music_info, meta_fields)
-
-                    return DownloadResult(
-                        success=True,
-                        file_path=str(file_path),
-                        file_size=file_path.stat().st_size,
-                        music_info=music_info,
-                    )
+                    # 完整性通过 → 嗅探 → 原子转正 → 写元数据
+                    return self._publish(part_path, file_path, music_info,
+                                         cancel_event, write_meta, meta_fields)

                except DownloadCanceled:
                    # 用户明确放弃：清理半截临时文件
@@ -438,8 +361,7 @@ class MusicDownloader:
                except _RetryFromScratch:
                    # .part 已清理，直接进入下一轮从头下载
                    last_error = "续传起点失效，重新下载"
-                    if attempt < retries:
-                        next_wait = 0.5 * (attempt + 1)   # 锁外睡眠
+                    next_wait = self._backoff_wait(attempt, retries)
                    continue
                except (requests.RequestException, OSError) as e:
                    # 网络错误：保留 .part 支持断点续传；
@@ -448,13 +370,11 @@ class MusicDownloader:
                        self._unlink_quiet(part_path)
                        raise DownloadCanceled("下载已取消") from e
                    last_error = f"下载请求失败: {e}"
-                    if attempt < retries:
-                        next_wait = 0.5 * (attempt + 1)   # 锁外睡眠
+                    next_wait = self._backoff_wait(attempt, retries)
                    continue
                except Exception as e:
                    last_error = f"下载过程中发生错误: {e}"
-                    if attempt < retries:
-                        next_wait = 0.5 * (attempt + 1)   # 锁外睡眠
+                    next_wait = self._backoff_wait(attempt, retries)
                    continue

        # 最后一次尝试仍失败：若任务已取消按取消收尾
@@ -463,6 +383,182 @@ class MusicDownloader:
            raise DownloadCanceled("下载已取消")
        return DownloadResult(success=False, error_message=last_error or "下载失败")

+    # ----------- 下载分步实现（download_music_file 的组成件） -----------
+
+    def _cached_result(
+        self,
+        file_path: Path,
+        music_info: MusicInfo,
+        write_meta: bool,
+        meta_fields: list[str] | None,
+    ) -> DownloadResult | None:
+        """锁内复查目标文件是否已是一份可用缓存；返回 None 表示需要真正下载。
+
+        缓存与本次期望不符时视为 miss 并删除重下，而不是把旧文件当本次结果交付
+        （跨账号音质降级 / 上游变更都会让同 ID 同音质的实际文件不同；原实现
+        命中即返回、从不校验尺寸）。期望未知（file_size=0）时至少拒绝 0 字节坏文件。
+        """
+        if not file_path.exists():
+            return None
+        st_size = file_path.stat().st_size
+        cache_bad = ((music_info.file_size and st_size != music_info.file_size)
+                     or (not music_info.file_size and st_size == 0))
+        if cache_bad:
+            self._unlink_quiet(file_path)
+            return None
+        # 缓存命中也尊重本次的元数据请求（重跑一次 ffmpeg，幂等）
+        if write_meta:
+            self._write_metadata_locked(file_path, music_info, meta_fields)
+        return DownloadResult(
+            success=True,
+            file_path=str(file_path),
+            file_size=file_path.stat().st_size,
+            music_info=music_info,
+        )
+
+    def _promote_complete_part(
+        self,
+        part_path: Path,
+        file_path: Path,
+        music_info: MusicInfo,
+        write_meta: bool,
+        meta_fields: list[str] | None,
+    ) -> DownloadResult | None:
+        """上次已下完但未改名的 .part：直接转正交付；返回 None 表示仍需下载。
+
+        尺寸要求**精确相等**——放宽为 >= 会把超尺寸残片（上游多发货/坏分片）
+        转正成坏文件；期望未知时不走此路（交给下载流程）。转正后立即返回，
+        不再发起网络请求，否则离线时会把现成的完整文件报为失败。
+        """
+        if not part_path.exists():
+            return None
+        if not (music_info.file_size > 0
+                and part_path.stat().st_size == music_info.file_size):
+            return None
+        os.replace(part_path, file_path)
+        if write_meta:
+            self._write_metadata_locked(file_path, music_info, meta_fields)
+        return DownloadResult(
+            success=True,
+            file_path=str(file_path),
+            file_size=file_path.stat().st_size,
+            music_info=music_info,
+        )
+
+    def _resume_offset(self, part_path: Path, music_info: MusicInfo) -> int:
+        """断点续传起点；返回 0 表示从头下载（顺带清理没有续传价值的残片）。"""
+        if not part_path.exists():
+            return 0
+        existing = part_path.stat().st_size
+        if existing <= 0:
+            self._unlink_quiet(part_path)          # 0 字节残片无续传价值
+            return 0
+        if music_info.file_size > 0 and existing > music_info.file_size:
+            # 超尺寸残片（上游多发货/坏分片）丢弃从头下——留着会被
+            # 「尺寸相等即转正」误交付
+            self._unlink_quiet(part_path)
+            return 0
+        return existing
+
+    def _transfer(
+        self,
+        music_info: MusicInfo,
+        part_path: Path,
+        resume_from: int,
+        cancel_event: threading.Event | None,
+        progress_cb,
+    ) -> None:
+        """占全局下载名额后落盘（产物恒为 part_path），异常语义由两条通道对齐。
+
+        aria2c 可用时优先（多连接 + 原生断点续传），否则走内置 aiohttp 流式通道。
+        """
+        # 排队用可取消等待：原阻塞式 with 使取消后仍要等全局 10 名额腾出，
+        # 任务卡死、退款延迟
+        if not self._download_semaphore.acquire_cancellable(cancel_event, poll=0.5):
+            raise DownloadCanceled("下载已取消")
+        try:
+            aria2_backend = get_backend()
+            if aria2_backend is not None:
+                # aria2c 通道：多连接 + 原生断点续传
+                self._fetch_via_aria2(aria2_backend, music_info, part_path,
+                                      cancel_event, progress_cb)
+            else:
+                # 内置通道：aiohttp 流式落盘 + Range 起点校验
+                self._fetch_via_http(music_info, part_path, resume_from,
+                                     cancel_event, progress_cb)
+        finally:
+            # 与 acquire_cancellable 配对释放（原 with 语义）
+            self._download_semaphore.release()
+
+    @staticmethod
+    def _size_mismatch_error(part_path: Path, music_info: MusicInfo) -> str:
+        """完整性判定：已知期望大小时精确相等，未知期望时至少非空。
+
+        通过返回空串；否则返回失败原因（.part 由调用方保留以供下轮续传）。
+        """
+        actual_size = part_path.stat().st_size
+        if music_info.file_size > 0:
+            complete = (actual_size == music_info.file_size)
+        else:
+            complete = (actual_size > 0)
+        if complete:
+            return ''
+        return (f"下载不完整: 期望 {music_info.file_size or '未知'} 字节, "
+                f"实际 {actual_size} 字节")
+
+    def _publish(
+        self,
+        part_path: Path,
+        file_path: Path,
+        music_info: MusicInfo,
+        cancel_event: threading.Event | None,
+        write_meta: bool,
+        meta_fields: list[str] | None,
+    ) -> DownloadResult:
+        """完整性通过后的收尾：内容嗅探 → 原子转正 → 写入元数据。
+
+        嗅探只在期望尺寸未知（"非空即通过"口径）时执行——该口径下 CDN 错误页/
+        风控 JSON 曾可被存成音频交付。转正走 os.replace，半截文件不会被当作已下载。
+        调用点必须在文件锁内（元数据也要求在锁内，其它请求才看到已完成标记的文件）。
+        """
+        if music_info.file_size <= 0 and not _sniff_audio_header(part_path):
+            self._unlink_quiet(part_path)
+            raise DownloadException("下载内容校验失败（非音频数据）")
+
+        os.replace(part_path, file_path)
+
+        # 元数据写入移出下载信号量（CPU 操作不占网络名额），
+        # 但仍在文件锁内执行，保证其它请求看到的是已写入标签的最终文件
+        if write_meta:
+            # 元数据段入口补取消检查点——已取消的任务不再
+            # 进入信号量排队/ffmpeg 等待（有界但可达 120s），收尾不再延迟
+            if cancel_event is not None and cancel_event.is_set():
+                raise DownloadCanceled("下载已取消")
+            self._write_metadata_locked(file_path, music_info, meta_fields)
+
+        return DownloadResult(
+            success=True,
+            file_path=str(file_path),
+            file_size=file_path.stat().st_size,
+            music_info=music_info,
+        )
+
+    def _write_metadata_locked(
+        self,
+        file_path: Path,
+        music_info: MusicInfo,
+        meta_fields: list[str] | None,
+    ) -> None:
+        """在标签信号量内写元数据：写标签会重写整个文件（IO 密集），与下载分离
+        限流——写满时只阻塞后来者，不占下载名额、不拖慢其它文件的传输。"""
+        with self._tag_semaphore:
+            self._write_metadata(file_path, music_info, meta_fields)
+
+    @staticmethod
+    def _backoff_wait(attempt: int, retries: int) -> float:
+        """失败后的退避秒数；已是最后一轮则不等待。锁外睡眠——同名并发任务不陪睡。"""
+        return 0.5 * (attempt + 1) if attempt < retries else 0.0
+

    # ----------- 传输通道（二选一，产物都是 part_path） -----------