Archived
snowy-yang
8716617d5d
为什么：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 沙箱）。