From 7a70eef6365eb8afd70673b222f5fc9c29005492 Mon Sep 17 00:00:00 2001 From: snowy-yang <102860110+snowy-yang@users.noreply.github.com> Date: Sat, 26 Sep 2026 14:48:05 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E5=88=A0=E9=99=A4=20services.runti?= =?UTF-8?q?me=20=E5=85=BC=E5=AE=B9=E9=97=A8=E9=9D=A2=EF=BC=8C7=20=E5=A4=84?= =?UTF-8?q?=E8=B0=83=E7=94=A8=E7=82=B9=E7=9B=B4=E8=BF=9E=E7=9C=9F=E5=AE=9E?= =?UTF-8?q?=E5=AD=90=E6=A8=A1=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为什么：上一次分包重构把 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/ 指纹三项一致 --- services/__init__.py | 4 +- services/_shared.py | 2 - services/_taskcore.py | 2 - services/api_service.py | 2 - services/batch.py | 2 - services/downloads.py | 2 - services/podcast.py | 2 - services/runtime.py | 120 ---------------------------------------- services/streaming.py | 2 - services/tasks.py | 2 - web/routers/download.py | 34 +++++++----- web/routers/tasks.py | 9 +-- web/tasks_registry.py | 4 +- 13 files changed, 29 insertions(+), 158 deletions(-) delete mode 100644 services/runtime.py diff --git a/services/__init__.py b/services/__init__.py index 73504fd..a58399a 100644 --- a/services/__init__.py +++ b/services/__init__.py @@ -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``：限流桶、请求统计、命名与共享常量 diff --git a/services/_shared.py b/services/_shared.py index 64ddf4a..f3120a7 100644 --- a/services/_shared.py +++ b/services/_shared.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- """服务层共享状态与低层工具（限流桶、请求统计、命名与常量）。 - -（自 services/runtime.py 拆出，行为与原实现一致。） """ import collections diff --git a/services/_taskcore.py b/services/_taskcore.py index 44432d7..92b6bc7 100644 --- a/services/_taskcore.py +++ b/services/_taskcore.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- """任务生命周期原语（启动 / 终态 / 文件收尾 / 结算）。 - -（自 services/runtime.py 拆出，行为与原实现一致。） """ import threading diff --git a/services/api_service.py b/services/api_service.py index e12058d..d961cd3 100644 --- a/services/api_service.py +++ b/services/api_service.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- """服务类与进程级服务实例。 - -（自 services/runtime.py 拆出，行为与原实现一致。） """ import logging diff --git a/services/batch.py b/services/batch.py index c824553..e967f45 100644 --- a/services/batch.py +++ b/services/batch.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- """歌单/专辑批量打包 worker。 - -（自 services/runtime.py 拆出，行为与原实现一致。） """ import os diff --git a/services/downloads.py b/services/downloads.py index d46e383..9bfa2a5 100644 --- a/services/downloads.py +++ b/services/downloads.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- """单曲下载、账号探测与任务交付。 - -（自 services/runtime.py 拆出，行为与原实现一致。） """ import os diff --git a/services/podcast.py b/services/podcast.py index 9434593..5f97896 100644 --- a/services/podcast.py +++ b/services/podcast.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- """播客单集与整台打包 worker。 - -（自 services/runtime.py 拆出，行为与原实现一致。） """ import os diff --git a/services/runtime.py b/services/runtime.py deleted file mode 100644 index 2caf642..0000000 --- a/services/runtime.py +++ /dev/null @@ -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', -] diff --git a/services/streaming.py b/services/streaming.py index 5f703f2..a64beb2 100644 --- a/services/streaming.py +++ b/services/streaming.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- """同步流式响应垫片（音频分段透传）。 - -（自 services/runtime.py 拆出，行为与原实现一致。） """ diff --git a/services/tasks.py b/services/tasks.py index a6cc75c..2844f95 100644 --- a/services/tasks.py +++ b/services/tasks.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- """任务监控循环与设备心跳。 - -（自 services/runtime.py 拆出，行为与原实现一致。） """ import os diff --git a/web/routers/download.py b/web/routers/download.py index 1a3b3cb..19e02e1 100644 --- a/web/routers/download.py +++ b/web/routers/download.py @@ -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'}, '播客打包任务已提交') diff --git a/web/routers/tasks.py b/web/routers/tasks.py index 1d2637d..e26b54b 100644 --- a/web/routers/tasks.py +++ b/web/routers/tasks.py @@ -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'], diff --git a/web/tasks_registry.py b/web/tasks_registry.py index b42e9b2..338cb68 100644 --- a/web/tasks_registry.py +++ b/web/tasks_registry.py @@ -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)