Archived
snowy-yang
9cbd341e2e
为什么：_single_download_worker 是单曲下载的**唯一**后台执行路径（/download 的
file 模式由 start_task 启动它），177 行 / 圈复杂度 36 / 嵌套 5，且此前**零测试
覆盖**——改坏任意一处都不会有测试报警。它的三个 except 分支各写一遍「置终态 +
退款 + 删任务目录」（9 行 × 3），正文里又散着四处逐字相同的取消检查。
改法：一步一个具名函数，主函数只留线性流程。
SingleTaskParams 参数快照（frozen dataclass），免去每步重列长参数表
_begin_single_task 置 running + 取参数
_fetch_single_metadata 一次预取歌曲信息 + 算交付基础名
_single_progress_cb 构造字节级进度回调（限频 0.4s）
_abort_if_canceled 取消检查点（原三处逐字重复 → 一处）
_single_file_result 不打包的交付描述
_pack_single_zip 音频 + 歌词 + 封面 + info.txt 打成一包
_publish_single_task 置 done（已终态不覆盖）+ 结算 + 记日志
_fail_single_task 失败/取消统一收尾（原三处 × 9 行 → 一处）
复杂度（同口径 AST 实测，HEAD 与工作区由同一脚本测出）：
_single_download_worker 177 行 / 圈 36 / 嵌套 5 → 43 行 / 圈 8 / 嵌套 2
文件最大圈复杂度 36（就是它） → 9（_single_progress_cb，
节流回调本身的形状）
文件行数 234 → 310（+76，全是新签名与 docstring）· 函数数 3 → 11
等价性证据（三道，互相独立）：
1. 19 例行为契约测试**在未改动的原始实现上一次性全绿**（先写测试、后动代码；
改完再跑仍全绿）——这批测试因此忠实编码了旧行为，构成等价性验证，而不是
「照着新实现写的断言」。断言只依赖任务终态 / 磁盘文件 / ZIP 内容 / 账本行 /
余额，不引用任何内部函数名，可跨后续重构复用。
2. 反向注入验证：把 HEAD 版注入回 services.downloads（**sys.modules 与父包属性
两处都要挂**——否则 monkeypatch.resolve 走 getattr 父包拿到真模块），同一套
19 例**全过**，与第 1 条相互独立地再次证明测试忠实。
3. AST 字面量多重集比对 + 逐条位置归因：字符串 69 种**一个不少**——没有一条
用户可见文案被动过。数值差异全部归因：
0 4→2：三处 ledger_settle(task_id, 0, ...) 收敛成一处（理由参数化）
True 5→4：三处 rmtree(..., ignore_errors=True) 收敛成一处（另 +1 为新增
dataclass 的 frozen=True）
'任务已取消' 5→3：三处 raise DownloadCanceled 收敛进 _abort_if_canceled
刻意保留的语义（是决定，不是疏漏）：
- task_dir_path 仍在 try 外初始化、失败收尾仍用它判空——「下载未开始就失败」
时无目录可删，语义原样。
- 结算失败**不**把 done 改标 error（钱由重启对账兜底，宁可商家小损不坑用户），
已用 test_settle_failure_does_not_flip_done_to_error 固化。
- 末段「已终态不得覆盖为 done」的状态检查与取消检查合流进 _publish_single_task，
仍是先到先得；用 test_terminal_state_not_overwritten_by_late_success 固化。
- 日志调用移到各自 except 分支开头（原在收尾之后），仅调整同一分支内的顺序，
不影响任何可观察行为；三处格式串原样保留。
- music_id 保持**原样透传**：params 里是数字字符串，而下游签名声明 int，两侧
一直不一致、运行时靠字符串参与上游查询拼装而正常工作。顺手 int() 会把异常面
从「上游查不到」变成 ValueError，属行为变更，故只把标注写成 Any 并在
docstring 记明。
测试：新增 tests/test_single_worker.py（19 例）——正常交付与交付副本位置、
ZIP 四件套与 SRT 歌词、空歌词跳过、取封面失败仍发布、文件名格式、操作记录与
remote_ip 兜底、下载失败退费、未知异常泛化文案（上游细节不外泄）、下载中/下载
后/打包中三种取消、终态不被覆盖、进度回调三态（有总量 / 无总量 / 自身抛错）、
结算失败不影响已交付、worker 崩在结算前留给对账兜底。
顺带修正一处自己的假设错误：最初把「取封面失败」写成 fetch_cover_bytes 抛异常，
实测该函数契约是**失败返回 None**（内部已 except Exception），抛异常是不存在的
形状——改为注入 None 后才在旧实现上跑绿。测试要贴合生产的真实形状。
验证：ruff 全过 · pyright 0/0 · pytest 294 passed（275→294）· 生产 data/ 未被
触碰（全部用例走 tmp_path 沙箱）。