refactor: 两个根级游离模块并入 music_api 包,消除分层倒置

为什么:podcast_api.py(560 行) 与 qr_login.py(397 行) 既不属于任何包、也不是
入口脚本,却同时被 services 层与 web 层引用——`services/downloads.py` 直接
`from qr_login import ...`、`services/podcast.py` 直接 `import podcast_api`,
业务层反向依赖顶层游离模块,是本次架构体检里唯一的无争议分层倒置。
两者本就依赖 music_api(前者取 url_v1/APIConstants/APIException,后者取
QRLoginManager),与 music_api 下已有的 qr.py / compat.py 是同一层的同类物。

迁移(git 保留重命名历史):
- podcast_api.py -> music_api/podcast.py
- qr_login.py    -> music_api/qr_client.py

**命名避让**:不叫 music_api/qr_login.py——music_api/__init__ 已经从 .compat
导出了一个**同名函数** qr_login,同名子模块会与之互相遮蔽。改叫 qr_client
(其核心导出即 QRLoginClient),并在验证里专门确认 music_api.qr_login 仍是
可调用函数、music_api.podcast 是模块,两者不冲突。

内部导入顺带改为精确子模块,不再绕道包门面:
- podcast.py:from music_api import APIConstants/APIException/url_v1
  → from .compat import url_v1 / from .constants import ... / from .errors import ...
- qr_client.py:删掉那层 try/except ImportError 包装(它给的是「请确保
  music_api.py 文件存在」这类顶层脚本时代的提示,作为包内模块已无意义),
  改 from .cookies/.errors/.qr 相对导入
- CLI 用法文本 python qr_login.py → python -m music_api.qr_client
  (相对导入后直接跑脚本会失败,必须走 -m;全仓确认无脚本/文档引用旧入口)
- 路径安全性已核对:qr_client 用的是 CWD 相对的 cookie.txt,不是 __file__ 相对,
  迁移不改其解析结果

引用点全部更新(AST 扫描确认覆盖全集,替换后残留 0):
- podcast:services/podcast.py(1 + 5 处调用) · web/routers/podcast.py(1 + 6)
  · web/routers/download.py(2 处函数内 + 3),导入名统一为 `podcast`
- qr_login:services/downloads.py · web/routers/admin.py · web/routers/user.py(×2)
- services/__init__.py 依赖自检列表去掉这两个名字(已并入 music_api)
- pyproject include 去掉两个顶层文件名(music_api 目录已覆盖)

验证:
- 11 + 3 个符号在新位置全部 hasattr 通过;podcast_api / qr_login 已
  ModuleNotFoundError;6 个调用方模块均可 import;services 依赖自检仍生效
- 门禁:ruff 0 · pyright 0 errors/0 warnings · pytest 184 passed
- 真实 uvicorn 冒烟 10/10,含 /podcast/parse 与 /podcast/hot 返回 401
  (模块导入失败会是 500,路由缺失会是 404,401 证明两者都正常)
- 生产 data/ 指纹 before == after
This commit is contained in:
snowy-yang committed 2026-09-26 15:03:47 +08:00
1 parent 1d86ec87ec
commit 095171e0b7
13 files changed
+37 -41

No files matched your search

+8 -9
View File
@@ -7,7 +7,7 @@
- POST/GET /api/v1/podcast/search ↔ Flask /podcast/search
- POST/GET /api/v1/podcast/hot ↔ Flask /podcast/hot
说明:podcast_api 仍是同步模块(requests),此处以 asyncio.to_thread 包装,
说明:music_api.podcast 是同步模块(底层 core.sync_http),此处以 asyncio.to_thread 包装,
让阻塞的上游调用不占用事件循环——行为不变,且不阻塞其它请求。
"""
import asyncio
@@ -15,9 +15,8 @@ from typing import Annotated
from fastapi import APIRouter, Depends, Request
import podcast_api
from core import media
from music_api import APIException
from music_api import APIException, podcast
from web import ratelimit
from web.deps import SiteUser, require_login
from web.request_utils import cookies as _cookies
@@ -53,7 +52,7 @@ async def podcast_parse(_user: LoginUser, request: Request):
cookies = _cookies()
try:
result = await asyncio.to_thread(
podcast_api.parse_podcast_ref, raw, cookies, page_size=page_size)
podcast.parse_podcast_ref, raw, cookies, page_size=page_size)
except APIException as e:
return error(str(e), 404)
except Exception:
@@ -66,7 +65,7 @@ async def podcast_parse(_user: LoginUser, request: Request):
if song_id:
try:
url_info = await asyncio.to_thread(
podcast_api.resolve_episode_url, song_id, cookies, quality)
podcast.resolve_episode_url, song_id, cookies, quality)
except Exception:
url_info = None
if url_info:
@@ -112,7 +111,7 @@ async def podcast_programs(_user: LoginUser, request: Request):
return error('无效的电台 ID')
try:
result = await asyncio.to_thread(
podcast_api.get_radio_programs, radio_id, _cookies(),
podcast.get_radio_programs, radio_id, _cookies(),
limit=limit, offset=offset, asc=asc)
return success(result, '获取单集列表成功')
except APIException as e:
@@ -136,7 +135,7 @@ async def podcast_search(_user: LoginUser, request: Request):
search_type = 'all'
try:
result = await asyncio.to_thread(
podcast_api.search_podcast, keyword, _cookies(),
podcast.search_podcast, keyword, _cookies(),
limit=limit, offset=offset, search_type=search_type)
return success(result, '播客搜索完成')
except APIException as e:
@@ -155,13 +154,13 @@ async def podcast_hot(_user: LoginUser, request: Request):
cate_id = data.get('cate_id') or None
try:
radios = await asyncio.to_thread(
podcast_api.get_hot_radios, _cookies(), limit=limit, offset=offset, cate_id=cate_id)
podcast.get_hot_radios, _cookies(), limit=limit, offset=offset, cate_id=cate_id)
except APIException as e:
return error(str(e), 404)
except Exception:
return error('服务暂时不可用,请稍后再试', 500)
try:
categories = await asyncio.to_thread(podcast_api.get_categories)
categories = await asyncio.to_thread(podcast.get_categories)
except APIException:
categories = []
# 满页视为可能还有更多