refactor: 删除 aiohttp_compat 垫片，music_api 改走原生 core.http_client

core/aiohttp_compat 是「同步转异步」迁移期的 requests 同形异步垫片：它存在的唯一理由是让既有 `requests.post/get + raise_for_status()` 风格的代码以最小改动迁到异步。其两个调用方（music_api/api.py、music_api/client.py）**本就已是 async def**——垫片只剩「保留 requests 语义」这一层包装，属于迁移残留。改动： - api.py：23 处 requests.post/get → await core.http_client.request()。该文件每处都在请求后立刻 raise_for_status() 才取 .json()，从不把 4xx 当数据读，故「_once 对非 2xx 直接抛 UpstreamHTTPError」与旧语义等价（原 raise_for_status 抛的 HTTPError 也一律落入 RequestException 分支）； except requests.RequestException → except UpstreamError。 - client.py：两个自管重试的方法改用新公开的 core.http_client.request_once() （单次、不重试），保留原有「5xx 退避重试一次 / 4xx 立即失败」的分流—— 把 status_code>=500 的判断换成 UpstreamHTTPError.status，行为逐条对齐（4xx=风控不重试，网络/5xx 重试一次）。响应体上限交由客户端 max_bytes 统一把关。 post_request_full 返回类型改为 HTTPResult（qr.py 用到的 .text/.cookies/.headers 三者在 HTTPResult 上齐备）。 - core/http_client：_once 更名并公开为 request_once（自管重试的调用方需要它）。注：这是为「删垫片」而补的唯一一个小口子，不是新增抽象。注意一处**有意的行为变化**：api.py 原经垫片请求零重试，现在 request() 自带「网络异常/5xx 退避重试一次、4xx 不重试」（core.http_client 既定口径）。 429/460 属 4xx 不重试，不加剧风控。 - 删除 core/aiohttp_compat.py；web/app.py 去掉其 close()；pyproject 去掉其 per-file-ignore；core/http_errors.py 注释更正为「仅供 core.sync_http」。 - 测试：test_aiohttp_compat.py 拆解为 test_async_bridge.py（只留桥的两条契约，垫片自身的 4 条随垫片消亡）；test_search_music / test_playlist_detail 的替身边界从 api.requests.post 换成 api._http.request，异常类型换成 UpstreamNetworkError。门禁：ruff 全过 / pyright 0-0 / pytest 383 项全绿（0 失败；383=387-6+2，账面吻合）。
2026-09-28 19:17:03 +08:00
1 parent b089dadac2
commit 65adfc9089
@@ -18,7 +18,6 @@ from .api import (
    NeteaseAPI,
 )
 from .client import (
-    _MAX_UPSTREAM_JSON_BYTES,
    HTTPClient,
    _as_dict,
    _ensure_dict,
@@ -48,7 +47,6 @@ from .qr import (

 __all__ = [
    'DEFAULT_COOKIE_FILE',
-    '_MAX_UPSTREAM_JSON_BYTES',
    'APIConstants',
    'APIException',
    'CryptoUtils',
@@ -10,7 +10,8 @@ from collections.abc import Callable
 from random import randrange
 from typing import Any

-from core import aiohttp_compat as requests  # 异步 HTTP 垫片（requests 同形 API）
+from core.http_client import UpstreamError
+from core.http_client import client as _http

 from .client import (
    HTTPClient,
@@ -71,9 +72,8 @@ async def _collect_playlist_tracks(track_ids: list[str], headers: dict[str, str]
        except (TypeError, ValueError):
            continue

-        song_resp = await requests.post(APIConstants.SONG_DETAIL_V3, data=song_data,
+        song_resp = await _http.request('POST', APIConstants.SONG_DETAIL_V3, data=song_data,
                                        headers=headers, cookies=cookies, timeout=30)
-        song_resp.raise_for_status()

        song_result = song_resp.json()
        if not isinstance(song_result, dict):
@@ -222,9 +222,8 @@ class NeteaseAPI:
                'User-Agent': APIConstants.USER_AGENT,
                'Referer': APIConstants.REFERER
            }
-            response = await requests.post(APIConstants.SONG_DETAIL_V3, data=data,
+            response = await _http.request('POST', APIConstants.SONG_DETAIL_V3, data=data,
                                     headers=headers, timeout=30)
-            response.raise_for_status()

            result = response.json()
            # 合法 JSON 但非对象（null/数组）时给明确错误，不让 AttributeError 失真
@@ -234,7 +233,7 @@ class NeteaseAPI:
                raise APIException(f"获取歌曲详情失败: {result.get('message', '未知错误')}")

            return result
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"获取歌曲详情请求失败: {e}") from e
        except json.JSONDecodeError as e:
            raise APIException(f"解析歌曲详情响应失败: {e}") from e
@@ -270,9 +269,8 @@ class NeteaseAPI:
                'Referer': APIConstants.REFERER
            }

-            response = await requests.post(APIConstants.LYRIC_API, data=data,
+            response = await _http.request('POST', APIConstants.LYRIC_API, data=data,
                                   headers=headers, cookies=cookies, timeout=30)
-            response.raise_for_status()

            result = response.json()
            _ensure_dict(result, 'get_lyric 接口响应异常（非标准 JSON 对象）')
@@ -280,7 +278,7 @@ class NeteaseAPI:
                raise APIException(f"获取歌词失败: {result.get('message', '未知错误')}")

            return result
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"获取歌词请求失败: {e}") from e
        except json.JSONDecodeError as e:
            raise APIException(f"解析歌词响应失败: {e}") from e
@@ -310,9 +308,8 @@ class NeteaseAPI:
                'Referer': APIConstants.REFERER
            }

-            response = await requests.post(APIConstants.SEARCH_API, data=data,
+            response = await _http.request('POST', APIConstants.SEARCH_API, data=data,
                                   headers=headers, cookies=cookies, timeout=30)
-            response.raise_for_status()

            result = response.json()
            # 非 dict 响应（null/数组）给明确错误
@@ -323,7 +320,7 @@ class NeteaseAPI:

            result_data = result.get('result') or {}
            return _collect_search_items(result_data, search_type)
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"搜索请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析搜索响应失败: {e}") from e
@@ -348,9 +345,8 @@ class NeteaseAPI:
                'Referer': APIConstants.REFERER
            }

-            response = await requests.post(APIConstants.PLAYLIST_DETAIL_API, data=data,
+            response = await _http.request('POST', APIConstants.PLAYLIST_DETAIL_API, data=data,
                                   headers=headers, cookies=cookies, timeout=30)
-            response.raise_for_status()

            result = response.json()
            # 非 dict 响应（null/数组）给明确错误
@@ -384,7 +380,7 @@ class NeteaseAPI:
                info['failed_batches'] = failed_batches

            return info
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"获取歌单详情请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析歌单详情响应失败: {e}") from e
@@ -409,8 +405,7 @@ class NeteaseAPI:
                'Referer': APIConstants.REFERER
            }

-            response = await requests.get(url, headers=headers, cookies=cookies, timeout=30)
-            response.raise_for_status()
+            response = await _http.request('GET', url, headers=headers, cookies=cookies, timeout=30)

            result = response.json()
            _ensure_dict(result, 'get_album_detail 接口响应异常（非标准 JSON 对象）')
@@ -440,7 +435,7 @@ class NeteaseAPI:
                })

            return info
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"获取专辑详情请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析专辑详情响应失败: {e}") from e
@@ -460,8 +455,7 @@ class NeteaseAPI:
                'Referer': APIConstants.REFERER
            }

-            response = await requests.get(APIConstants.TOPLIST_API, headers=headers, timeout=30)
-            response.raise_for_status()
+            response = await _http.request('GET', APIConstants.TOPLIST_API, headers=headers, timeout=30)

            result = response.json()
            _ensure_dict(result, 'get_toplist 接口响应异常（非标准 JSON 对象）')
@@ -481,7 +475,7 @@ class NeteaseAPI:
                    'topTitle': item.get('ToplistType', '')
                })
            return toplists
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"获取榜单请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析榜单响应失败: {e}") from e
@@ -505,8 +499,7 @@ class NeteaseAPI:
                'Referer': APIConstants.REFERER
            }

-            response = await requests.get(url, headers=headers, timeout=30)
-            response.raise_for_status()
+            response = await _http.request('GET', url, headers=headers, timeout=30)

            result = response.json()
            _ensure_dict(result, 'get_artist_hot_songs 接口响应异常（非标准 JSON 对象）')
@@ -535,7 +528,7 @@ class NeteaseAPI:
                },
                'songs': songs
            }
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"获取歌手信息请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析歌手信息响应失败: {e}") from e
@@ -561,8 +554,7 @@ class NeteaseAPI:
                'Referer': APIConstants.REFERER
            }

-            response = await requests.get(url, headers=headers, timeout=30)
-            response.raise_for_status()
+            response = await _http.request('GET', url, headers=headers, timeout=30)

            result = response.json()
            _ensure_dict(result, 'get_song_comments 接口响应异常（非标准 JSON 对象）')
@@ -602,7 +594,7 @@ class NeteaseAPI:
                'hotComments': [_comment_dict(c) for c in (result.get('hotComments') or [])],
                'comments': [_comment_dict(c) for c in (result.get('comments') or [])],
            }
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"获取评论请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析评论响应失败: {e}") from e
@@ -622,9 +614,8 @@ class NeteaseAPI:
                'Referer': APIConstants.REFERER
            }

-            response = await requests.get(APIConstants.USER_ACCOUNT_API, headers=headers,
+            response = await _http.request('GET', APIConstants.USER_ACCOUNT_API, headers=headers,
                                    cookies=cookies, timeout=30)
-            response.raise_for_status()

            result = response.json()
            _ensure_dict(result, 'get_account_info 接口响应异常（非标准 JSON 对象）')
@@ -674,9 +665,8 @@ class NeteaseAPI:
            page_size = 100
            for _ in range(20):   # 有界翻页，防上游 more 异常导致无限循环
                params = {'uid': user_id, 'limit': page_size, 'offset': offset}
-                response = await requests.get(APIConstants.USER_PLAYLIST_API, params=params,
+                response = await _http.request('GET', APIConstants.USER_PLAYLIST_API, params=params,
                                        headers=headers, cookies=cookies, timeout=30)
-                response.raise_for_status()

                result = response.json()
                _ensure_dict(result, 'get_user_playlists 接口响应异常（非标准 JSON 对象）')
@@ -706,7 +696,7 @@ class NeteaseAPI:
                    break
                offset += page_size
            return playlists
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"获取用户歌单请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析用户歌单响应失败: {e}") from e
@@ -790,15 +780,14 @@ class NeteaseAPI:
                'User-Agent': APIConstants.USER_AGENT,
                'Referer': APIConstants.REFERER
            }
-            response = await requests.post(APIConstants.PLAYLIST_SUBSCRIBE_API, data=data,
+            response = await _http.request('POST', APIConstants.PLAYLIST_SUBSCRIBE_API, data=data,
                                     headers=headers, cookies=cookies, timeout=30)
-            response.raise_for_status()
            result = response.json()
            _ensure_dict(result, 'subscribe_playlist 接口响应异常（非标准 JSON 对象）')
            if result.get('code') != 200:
                raise APIException(f"收藏歌单失败: {result.get('message', '未知错误')}")
            return result
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"收藏歌单请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析收藏歌单响应失败: {e}") from e
@@ -824,15 +813,14 @@ class NeteaseAPI:
                'User-Agent': APIConstants.USER_AGENT,
                'Referer': APIConstants.REFERER
            }
-            response = await requests.post(APIConstants.ALBUM_SUBSCRIBE_API, data=data,
+            response = await _http.request('POST', APIConstants.ALBUM_SUBSCRIBE_API, data=data,
                                     headers=headers, cookies=cookies, timeout=30)
-            response.raise_for_status()
            result = response.json()
            _ensure_dict(result, 'subscribe_album 接口响应异常（非标准 JSON 对象）')
            if result.get('code') != 200:
                raise APIException(f"收藏专辑失败: {result.get('message', '未知错误')}")
            return result
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"收藏专辑请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析收藏专辑响应失败: {e}") from e
@@ -875,9 +863,8 @@ class NeteaseAPI:
                'User-Agent': APIConstants.USER_AGENT,
                'Referer': APIConstants.REFERER,
            }
-            response = await requests.post(APIConstants.COMMENT_POST_API, data=body,
+            response = await _http.request('POST', APIConstants.COMMENT_POST_API, data=body,
                                     headers=headers, cookies=cookies or {}, timeout=30)
-            response.raise_for_status()

            text = response.text.strip()
            if not text:
@@ -889,7 +876,7 @@ class NeteaseAPI:
            if result.get('code') != 200:
                raise APIException(f"评论失败: {result.get('message', '未知错误')}")
            return result
-        except requests.RequestException as e:
+        except UpstreamError as e:
            raise APIException(f"评论请求失败: {e}") from e
        except (json.JSONDecodeError, KeyError) as e:
            raise APIException(f"解析评论响应失败: {e}") from e
@@ -7,7 +7,13 @@
 import asyncio
 from typing import Any

-from core import aiohttp_compat as requests  # 异步 HTTP 垫片（requests 同形 API）
+from core.http_client import (
+    HTTPResult,
+    UpstreamError,
+    UpstreamHTTPError,
+    UpstreamTooLarge,
+)
+from core.http_client import client as _http

 from .constants import (
    APIConstants,
@@ -41,7 +47,12 @@ class HTTPClient:
    async def post_request(url: str, params: str, cookies: dict[str, str]) -> str:
        """发送POST请求并返回文本响应。
        网络异常/5xx 做一次 1 秒退避重试（全站 API 调用此前零重试，
-        上游抖动即整首失败）；4xx（429/460 风控）不重试——立即重试会加剧风控。"""
+        上游抖动即整首失败）；4xx（429/460 风控）不重试——立即重试会加剧风控。
+
+        走 core.http_client.request_once（单次、不重试）：重试策略由本函数自管，
+        非 2xx 由 request_once 抛 UpstreamHTTPError，按 .status 分流——
+        与原先「垫片只在 raise_for_status() 时才抛 HTTPError」的分流等价。
+        """
        headers = {
            'User-Agent': APIConstants.USER_AGENT,
            'Referer': APIConstants.REFERER,
@@ -53,20 +64,21 @@ class HTTPClient:
        last_err = None
        for attempt in range(2):
            try:
-                response = await requests.post(url, headers=headers, cookies=request_cookies,
-                                         data={"params": params}, timeout=30)
-                if response.status_code >= 500 and attempt == 0:
+                response = await _http.request_once(
+                    'POST', url, headers=headers, cookies=request_cookies,
+                    data={"params": params}, timeout=30)
+                return response.text
+            except UpstreamHTTPError as e:
+                if e.status >= 500 and attempt == 0:
                    await asyncio.sleep(1.0)
                    continue
-                response.raise_for_status()
-                if len(response.content) > _MAX_UPSTREAM_JSON_BYTES:
-                    raise APIException("上游响应体异常（超过大小上限）")
-                return response.text
-            except requests.HTTPError as e:
                # 4xx（429/460 风控）不重试——原实现 HTTPError 落入
-                # 下方 RequestException 分支被重试一次，与 意图相反
+                # 下方异常分支被重试一次，与意图相反
                raise APIException(f"HTTP请求失败: {e}") from e
-            except requests.RequestException as e:
+            except UpstreamTooLarge as e:
+                # 响应体超限是确定性失败，重试无意义
+                raise APIException("上游响应体异常（超过大小上限）") from e
+            except UpstreamError as e:
                last_err = e
                if attempt == 0:
                    await asyncio.sleep(1.0)
@@ -74,7 +86,7 @@ class HTTPClient:
        raise APIException(f"HTTP请求失败: {last_err}")

    @staticmethod
-    async def post_request_full(url: str, params: str, cookies: dict[str, str]) -> requests.Response:
+    async def post_request_full(url: str, params: str, cookies: dict[str, str]) -> HTTPResult:
        """发送POST请求并返回完整响应对象（同 post_request 的有界重试）"""
        headers = {
            'User-Agent': APIConstants.USER_AGENT,
@@ -87,26 +99,21 @@ class HTTPClient:
        last_err = None
        for attempt in range(2):
            try:
-                response = await requests.post(url, headers=headers, cookies=request_cookies,
-                                         data={"params": params}, timeout=30)
-                if response.status_code >= 500 and attempt == 0:
+                response = await _http.request_once(
+                    'POST', url, headers=headers, cookies=request_cookies,
+                    data={"params": params}, timeout=30)
+                return response
+            except UpstreamHTTPError as e:
+                if e.status >= 500 and attempt == 0:
                    await asyncio.sleep(1.0)
                    continue
-                response.raise_for_status()
-                if len(response.content) > _MAX_UPSTREAM_JSON_BYTES:
-                    raise APIException("上游响应体异常（超过大小上限）")
-                return response
-            except requests.HTTPError as e:
                # 4xx 不重试（同上）
                raise APIException(f"HTTP请求失败: {e}") from e
-            except requests.RequestException as e:
+            except UpstreamTooLarge as e:
+                raise APIException("上游响应体异常（超过大小上限）") from e
+            except UpstreamError as e:
                last_err = e
                if attempt == 0:
                    await asyncio.sleep(1.0)
                    continue
        raise APIException(f"HTTP请求失败: {last_err}")
-
-
-# 上游 JSON 响应体上限——requests 已全量入内存，此处拦截的是
-# 异常/被劫持上游的超大 body 进入后续 .json() 解析与传播（音频/封面已有字节预算）
-_MAX_UPSTREAM_JSON_BYTES = 8 * 1024 * 1024