refactor: 删除 services.runtime 兼容门面，7 处调用点直连真实子模块

为什么：上一次分包重构把 1900 行巨石按职责拆成 9 个子模块后，留了一个 runtime.py 作为「原样再导出」的兼容门面，好让调用点零改动。但迁移期结束后没有一个调用点迁走——门面成了永久中间层：每次读代码都要先跳一层才知道符号真正住在哪，pyright 也无法从门面追溯定义位置。改法：保持「函数内延迟导入」的形式不变，只把导入目标换成真实子模块。 **刻意不提到模块顶部**——services/__init__.py 里有依赖自检（缺 auth_system/podcast_api/music_api/music_downloader/qr_login 就 sys.exit(1)），提到顶层会让「import web.*」这一步就触发该自检，改变启动语义，超出本次范围。 7 处调用点（AST 精确扫描确认全集）： - web/routers/download.py ×4：download / download_batch_zip / podcast_download / podcast_batch_zip，分别直连 services.downloads / batch / podcast / tasks 外加 _shared._build_download_base 与 api_service.api_service - web/routers/tasks.py ×2：_semaphores 取 _shared.BATCH_ZIP_SEM + api_service， topen 取 _shared.ENDPOINT_NAMES - web/tasks_registry.py ×1：start_task 直连 _taskcore._start_task_thread 子模块短名统一加 `services_` 前缀别名（services_tasks 等），避免与函数内既有局部名相撞。顺带清理：9 个子模块 docstring 里「（自 services/runtime.py 拆出……）」的历史说明在门面删除后已成悬空引用，一并去掉；包的模块划分说明改为「不再有兼容门面层」。验证： - 符号可达：11 个被引符号在真实子模块上全部 hasattr 通过； services.runtime 已 ModuleNotFoundError；api_service 仍是同一实例对象 - 三个调用方模块均可正常 import - 门禁：ruff 0 · pyright 0 errors 0 warnings · pytest 175 passed - 真实 uvicorn 冒烟 8/8（含 POST /auth/login 400），临时数据目录独立落库 9 张表，生产 data/ 指纹三项一致
2026-09-26 14:48:05 +08:00
1 parent 3ed2f36b18
commit 7a70eef636
@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 """服务层：从原 Flask 巨石中剥离的框架无关实现（不含任何 Flask 依赖）。

-模块划分（原先集中在 runtime.py 的 1900 行，现按职责拆分；`services.runtime`
-保留为兼容门面，原样再导出下列全部符号，既有调用点零改动）：
+模块划分（原先集中在单个 1900 行模块，现按职责拆分；调用方直接
+``from services import <子模块>``，不再有兼容门面层）：

 - ``api_service``：MusicAPIService 与进程级实例（config / api_service）
 - ``_shared``：限流桶、请求统计、命名与共享常量
@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 """服务层共享状态与低层工具（限流桶、请求统计、命名与常量）。
-
-（自 services/runtime.py 拆出，行为与原实现一致。）
 """

 import collections
@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 """任务生命周期原语（启动 / 终态 / 文件收尾 / 结算）。
-
-（自 services/runtime.py 拆出，行为与原实现一致。）
 """

 import threading
@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 """服务类与进程级服务实例。
-
-（自 services/runtime.py 拆出，行为与原实现一致。）
 """

 import logging
@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 """歌单/专辑批量打包 worker。
-
-（自 services/runtime.py 拆出，行为与原实现一致。）
 """

 import os
@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 """单曲下载、账号探测与任务交付。
-
-（自 services/runtime.py 拆出，行为与原实现一致。）
 """

 import os
@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 """播客单集与整台打包 worker。
-
-（自 services/runtime.py 拆出，行为与原实现一致。）
 """

 import os
@@ -1,120 +0,0 @@
-# -*- coding: utf-8 -*-
-"""网易云音乐API服务主程序
-
-提供网易云音乐相关API服务，包括：
- 歌曲信息获取
- 音乐搜索
- 歌单和专辑详情
- 音乐下载
- 健康检查
-"""
-
-# 兼容门面：实现已按职责拆分到同包各子模块，此处原样再导出。
-# 用 `__all__` 声明再导出（ruff F401 与 pyright 均据此认定「有意再导出」），
-# 使既有调用点（services.xxx / from services import Y）零改动。
-
-from ._shared import (
-    _COUNTED_LOWER,
-    _LEDGER_LAST_CLEANUP,
-    _LEDGER_LAST_RECOVER,
-    _MONITOR_ERR_TS,
-    _QUIET_LOG_PATHS,
-    _TASKS_SWEEP_LAST,
-    BATCH_ZIP_SEM,
-    COUNTED_PATHS,
-    ENDPOINT_NAMES,
-    _build_download_base,
-    _rate_ok,
-    _record_log,
-    _sweep_rate_buckets,
-)
-from ._taskcore import (
-    _mark_task_terminal,
-    _settle_batch_billing,
-    _start_task_thread,
-    _task_files,
-)
-from .api_service import (
-    APIConfig,
-    APIResponse,
-    MusicAPIService,
-    api_service,
-    config,
-)
-from .batch import (
-    _batch_zip_worker,
-)
-from .downloads import (
-    _admin_client,
-    _detect_vip,
-    _global_music_u,
-    _parse_cookie_str,
-    _single_download_worker,
-    _task_delivery_copy,
-    _user_client,
-    _vip_name,
-)
-from .podcast import (
-    _podcast_cleanup_files,
-    _podcast_download_worker,
-    _podcast_resolve_audio,
-    _podcast_safe_name,
-    _podcast_stream_download,
-    _podcast_zip_worker,
-)
-from .streaming import (
-    _stream_open,
-    _SyncStreamResponse,
-)
-from .tasks import (
-    _quiesce_tasks_for_restore,
-    _sweep_download_cache,
-    _task_monitor_loop,
-    _touch_device,
-)
-
-__all__ = [
-    'BATCH_ZIP_SEM',
-    'COUNTED_PATHS',
-    'ENDPOINT_NAMES',
-    '_COUNTED_LOWER',
-    '_LEDGER_LAST_CLEANUP',
-    '_LEDGER_LAST_RECOVER',
-    '_MONITOR_ERR_TS',
-    '_QUIET_LOG_PATHS',
-    '_TASKS_SWEEP_LAST',
-    'APIConfig',
-    'APIResponse',
-    'MusicAPIService',
-    '_SyncStreamResponse',
-    '_admin_client',
-    '_batch_zip_worker',
-    '_build_download_base',
-    '_detect_vip',
-    '_global_music_u',
-    '_mark_task_terminal',
-    '_parse_cookie_str',
-    '_podcast_cleanup_files',
-    '_podcast_download_worker',
-    '_podcast_resolve_audio',
-    '_podcast_safe_name',
-    '_podcast_stream_download',
-    '_podcast_zip_worker',
-    '_quiesce_tasks_for_restore',
-    '_rate_ok',
-    '_record_log',
-    '_settle_batch_billing',
-    '_single_download_worker',
-    '_start_task_thread',
-    '_stream_open',
-    '_sweep_download_cache',
-    '_sweep_rate_buckets',
-    '_task_delivery_copy',
-    '_task_files',
-    '_task_monitor_loop',
-    '_touch_device',
-    '_user_client',
-    '_vip_name',
-    'api_service',
-    'config',
-]
@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 """同步流式响应垫片（音频分段透传）。
-
-（自 services/runtime.py 拆出，行为与原实现一致。）
 """


@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 """任务监控循环与设备心跳。
-
-（自 services/runtime.py 拆出，行为与原实现一致。）
 """

 import os
@@ -115,8 +115,11 @@ async def download(user: Annotated[SiteUser | None, Depends(current_user)], requ
            lyric_format = 'lrc'
        need_zip = str(data.get('zip', 'false')).lower() in ('1', 'true', 'yes')

-        import services.runtime as services
-        downloader = services.api_service.downloader
+        from services import downloads as services_downloads
+        from services import tasks as services_tasks
+        from services._shared import _build_download_base
+        from services.api_service import api_service
+        downloader = api_service.downloader

        if return_format == 'json':
            try:
@@ -127,7 +130,7 @@ async def download(user: Annotated[SiteUser | None, Depends(current_user)], requ
                await billing.refund_open('rejected')
                return error('获取失败：歌曲不存在或暂无版权', 404)
            base = await asyncio.to_thread(
-                services._build_download_base, filename_format,
+                _build_download_base, filename_format,
                {'name': info.name, 'artist_string': info.artists})
            filename = f'{base}.{info.file_type}'
            try:
@@ -165,7 +168,7 @@ async def download(user: Annotated[SiteUser | None, Depends(current_user)], requ

        # file 模式：注册后台任务
        device_id = str(data.get('device_id') or '').strip()[:64]
-        await asyncio.to_thread(services._touch_device, device_id)
+        await asyncio.to_thread(services_tasks._touch_device, device_id)
        task = _single_task(data, music_id, quality, filename_format, write_meta,
                            meta_fields, lyric_format, need_zip, cookies, ip, device_id)
        reg_err = await register_download_task(billing, task, str(data.get('task_id') or '').strip())
@@ -173,7 +176,7 @@ async def download(user: Annotated[SiteUser | None, Depends(current_user)], requ
            await billing.refund_open('rejected')
            return error(reg_err, 429)
        task_id = task['task_id']
-        start_err = await start_task(task_id, services._single_download_worker, (task_id,))
+        start_err = await start_task(task_id, services_downloads._single_download_worker, (task_id,))
        if start_err:
            return error(start_err, 500)
        return success({'task_id': task_id, 'status': 'queued'}, '下载任务已提交')
@@ -248,8 +251,9 @@ async def download_batch_zip(user: Annotated[SiteUser | None, Depends(current_us

        cookies = _cookies()
        device_id = str(data.get('device_id') or '').strip()[:64]
-        import services.runtime as services
-        await asyncio.to_thread(services._touch_device, device_id)
+        from services import batch as services_batch
+        from services import tasks as services_tasks
+        await asyncio.to_thread(services_tasks._touch_device, device_id)
        task = {
            'type': 'batch',
            'total': len(ids), 'done': 0, 'failed': 0,
@@ -269,7 +273,7 @@ async def download_batch_zip(user: Annotated[SiteUser | None, Depends(current_us
            await billing.refund_open('rejected')
            return error(reg_err, 429)
        task_id = task['task_id']
-        start_err = await start_task(task_id, services._batch_zip_worker, (task_id,))
+        start_err = await start_task(task_id, services_batch._batch_zip_worker, (task_id,))
        if start_err:
            return error(start_err, 500)
        return success({'task_id': task_id, 'status': 'queued', 'total': len(ids)},
@@ -330,8 +334,9 @@ async def podcast_download(user: Annotated[SiteUser | None, Depends(current_user
            cookies = _cookies()

        device_id = str(data.get('device_id') or '').strip()[:64]
-        import services.runtime as services
-        await asyncio.to_thread(services._touch_device, device_id)
+        from services import podcast as services_podcast
+        from services import tasks as services_tasks
+        await asyncio.to_thread(services_tasks._touch_device, device_id)
        task = {
            'type': 'single',
            'total': 1, 'done': 0, 'failed': 0,
@@ -346,7 +351,7 @@ async def podcast_download(user: Annotated[SiteUser | None, Depends(current_user
            await billing.refund_open('rejected')
            return error(reg_err, 429)
        task_id = task['task_id']
-        start_err = await start_task(task_id, services._podcast_download_worker, (task_id,))
+        start_err = await start_task(task_id, services_podcast._podcast_download_worker, (task_id,))
        if start_err:
            return error(start_err, 500)
        return success({'task_id': task_id, 'status': 'queued'}, '播客单集下载任务已提交')
@@ -405,8 +410,9 @@ async def podcast_batch_zip(user: Annotated[SiteUser | None, Depends(current_use

        billed = _podcast_billing_count(data)
        device_id = str(data.get('device_id') or '').strip()[:64]
-        import services.runtime as services
-        await asyncio.to_thread(services._touch_device, device_id)
+        from services import podcast as services_podcast
+        from services import tasks as services_tasks
+        await asyncio.to_thread(services_tasks._touch_device, device_id)
        task = {
            'type': 'batch',
            'total': 0, 'done': 0, 'failed': 0,
@@ -428,7 +434,7 @@ async def podcast_batch_zip(user: Annotated[SiteUser | None, Depends(current_use
            await billing.refund_open('rejected')
            return error(reg_err, 429)
        task_id = task['task_id']
-        start_err = await start_task(task_id, services._podcast_zip_worker, (task_id,))
+        start_err = await start_task(task_id, services_podcast._podcast_zip_worker, (task_id,))
        if start_err:
            return error(start_err, 500)
        return success({'task_id': task_id, 'status': 'queued'}, '播客打包任务已提交')
@@ -58,14 +58,15 @@ def _owned_by(task: dict[str, Any], user: SiteUser) -> bool:

 def _semaphores():
    """批量打包/下载信号量（懒取，与 core.state 中的同一对象共享计数）。"""
-    import services.runtime as services
-    return services.BATCH_ZIP_SEM, services.api_service.downloader._download_semaphore
+    from services._shared import BATCH_ZIP_SEM
+    from services.api_service import api_service
+    return BATCH_ZIP_SEM, api_service.downloader._download_semaphore


@router.api_route('/api/topen', methods=['GET', 'POST'])
 async def topen(request: Request):
    """接口请求统计（实时）——锁内快照，避免 total 与明细不一致。"""
-    import services.runtime as services
+    from services._shared import ENDPOINT_NAMES
    with STATS_LOCK:
        snapshot = {p: dict(v) for p, v in REQUEST_STATS.items()}
    endpoints = []
@@ -73,7 +74,7 @@ async def topen(request: Request):
    for path, info in snapshot.items():
        endpoints.append({
            'path': path,
-            'name': services.ENDPOINT_NAMES.get(path, path),
+            'name': ENDPOINT_NAMES.get(path, path),
            'count': info['count'],
            'percent': round(info['count'] / total * 100, 1) if total else 0,
            'last': info['last'],
@@ -75,5 +75,5 @@ async def start_task(task_id: str, worker: Callable, args: tuple = ()) -> str |
    """启动 worker 线程（复用 services 的 _start_task_thread，失败收敛终态并退费）。"""
    import asyncio

-    import services.runtime as services
-    return await asyncio.to_thread(services._start_task_thread, task_id, worker, args)
+    from services._taskcore import _start_task_thread
+    return await asyncio.to_thread(_start_task_thread, task_id, worker, args)