df-test-framework 4.1.0__tar.gz → 4.1.1__tar.gz

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/CHANGELOG.md

@@ -5,6 +5,43 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.1.1] - 2026-03-11
+
+### ✨ 新增功能
+
+- 🔄 **统一 Response 层**: `HttpClient`/`AsyncHttpClient` 的所有方法统一返回框架 `Response` 对象，不再返回 `httpx.Response`
+- ⏱️ **请求计时**: `Response` 新增 `elapsed` 字段（秒），自动记录每次请求耗时
+- 🧩 **Response 兼容方法**: 新增 `text` 属性、`json()` 方法、`raise_for_status()` 方法，兼容 httpx.Response 用法
+- 🏊 **AsyncBrowserPool**: 新增异步浏览器实例池，支持并发 UI 测试（Semaphore 控制并发，按最少 context 分配）
+- 🔙 **request_raw()**: `HttpClient` 新增 `request_raw()` 方法，供需要原始 `httpx.Response` 的场景使用
+- 🛠️ **fetch_swagger 增强**: 重构为 argparse，支持 `-H` 自定义请求头、`-d` 输出目录、中文文件名保留
+
+### 🔄 变更
+
+- ⚠️ **异常统一**: httpx 异常（`TimeoutException`/`ConnectError`/`HTTPError`）统一包装为框架 `HttpError`，原始异常通过 `__cause__` 保留
+- ⚠️ **BaseAPI 异常变更**: `_parse_response()` 中 HTTP 错误从 `httpx.HTTPStatusError` 改为 `HttpError`
+- 📏 **ResponseAssertions**: `assert_response_time` 兼容 `timedelta`（httpx）和 `float` 秒数（框架 Response）
+
+### 📚 文档
+
+- 📝 API 参考、认证指南、中间件指南中 `HTTPStatusError` 更新为 `HttpError`
+
+### ⚠️ 迁移指南
+
+用户项目中捕获 httpx 异常的代码需要更新：
+
+```python
+# 之前
+from httpx import HTTPStatusError
+with pytest.raises((BusinessError, HTTPStatusError)):
+    ...
+
+# 现在
+from df_test_framework.core.exceptions import HttpError
+with pytest.raises((BusinessError, HttpError)):
+    ...
+```
+
 ## [4.1.0] - 2026-03-03
 
 ### ✨ 新增功能

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.1.0
+Version: 4.1.1
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/docs/api-reference/core.md

@@ -85,12 +85,10 @@ def request(
 - `url`: 请求路径（相对于base_url）
 - `**kwargs`: 其他请求参数（params, json, data, headers等）
 
-**返回**: `httpx.Response` 对象
+**返回**: `Response` 对象（框架统一响应）
 
 **异常**:
-- `httpx.TimeoutException`: 请求超时（重试max_retries次后仍失败）
-- `httpx.HTTPStatusError`: HTTP状态错误
-- `httpx.RequestError`: 请求错误
+- `HttpError`: HTTP 请求错误（超时、连接失败、状态码错误等）
 
 **重试策略**:
 - ✅ **自动重试**: 超时异常和5xx服务器错误

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/docs/guides/auth_session_guide.md

@@ -205,7 +205,7 @@ http_client.clear_cookies()
 def test_full_auth_flow(admin_auth_api, settings):
     """测试完整的登录-获取用户-登出流程"""
     from df_test_framework import BusinessError
-    from httpx import HTTPStatusError
+    from df_test_framework.core.exceptions import HttpError
 
     username = settings.business.admin_username
     password = settings.business.admin_password
@@ -222,7 +222,7 @@ def test_full_auth_flow(admin_auth_api, settings):
     admin_auth_api.logout(token=token)
 
     # 4. 验证 Token 已失效
-    with pytest.raises((BusinessError, HTTPStatusError)):
+    with pytest.raises((BusinessError, HttpError)):
         admin_auth_api.get_current_user(token=token)
 
     # 5. 清理（确保不影响其他测试）
@@ -236,10 +236,10 @@ def test_full_auth_flow(admin_auth_api, settings):
 def test_get_current_user_without_login(admin_auth_api):
     """测试未登录状态下获取当前用户"""
     from df_test_framework import BusinessError
-    from httpx import HTTPStatusError
+    from df_test_framework.core.exceptions import HttpError
 
     # 使用 skip_auth=True 跳过认证中间件
-    with pytest.raises((BusinessError, HTTPStatusError)):
+    with pytest.raises((BusinessError, HttpError)):
         admin_auth_api.get_current_user(skip_auth=True)
 ```
 
@@ -311,7 +311,7 @@ admin_auth_api.logout(token=token)
 
 ```python
 # ✅ 推荐：使用 skip_auth 测试未登录场景
-with pytest.raises((BusinessError, HTTPStatusError)):
+with pytest.raises((BusinessError, HttpError)):
     admin_auth_api.get_current_user(skip_auth=True)
 ```
 

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/docs/guides/middleware_guide.md

@@ -286,7 +286,7 @@ client.use(middleware)
 ```python
 # 测试未登录场景（接口需要验证"未登录时返回 401"）
 def test_get_current_user_without_login(api):
-    with pytest.raises((BusinessError, HTTPStatusError)):
+    with pytest.raises((BusinessError, HttpError)):
         api.get_current_user(skip_auth=True)  # 不添加 Token
 ```
 
@@ -307,7 +307,7 @@ def test_full_auth_flow(api):
     api.logout(token=token)
 
     # 4. 继续用同一个 Token，验证已失效
-    with pytest.raises((BusinessError, HTTPStatusError)):
+    with pytest.raises((BusinessError, HttpError)):
         api.get_current_user(token=token)
 ```
 

df_test_framework-4.1.1/docs/releases/v4.1.1.md

@@ -0,0 +1,143 @@
+# v4.1.1 发布说明
+
+**发布日期**: 2026-03-11
+
+统一 HTTP 响应层，所有请求方法返回框架 `Response` 对象，异常统一为 `HttpError`。新增 `AsyncBrowserPool` 和 `fetch_swagger` 增强。
+
+---
+
+## 新增功能
+
+### 统一 Response 层
+
+`HttpClient` / `AsyncHttpClient` 的所有方法（`get`/`post`/`put`/`patch`/`delete`/`head`/`options`）统一返回框架 `Response` 对象，不再返回 `httpx.Response`。
+
+```python
+from df_test_framework.capabilities.clients.http.core.response import Response
+
+# 之前：返回 httpx.Response
+# 现在：返回框架 Response（包含 status_code, headers, body, json_data, elapsed, context）
+response = client.get("/users")
+assert isinstance(response, Response)
+assert response.elapsed > 0  # 请求耗时（秒）
+```
+
+**新增 `request_raw()` 方法**：需要原始 `httpx.Response` 时使用：
+
+```python
+httpx_response = client.request_raw("GET", "/users")  # 返回 httpx.Response
+```
+
+### Response 增强
+
+```python
+response.text        # 响应文本（兼容 httpx.Response.text）
+response.json()      # 获取 JSON 数据（兼容 httpx.Response.json()）
+response.elapsed     # 请求耗时（float 秒数）
+response.raise_for_status()  # 非 2xx 时抛出 HttpError
+```
+
+### 异常统一
+
+httpx 底层异常统一包装为框架 `HttpError`，原始异常通过 `__cause__` 保留：
+
+| httpx 异常 | 框架异常 | 错误消息 |
+|------------|---------|---------|
+| `httpx.TimeoutException` | `HttpError` | `请求超时: GET /url` |
+| `httpx.ConnectError` | `HttpError` | `连接失败: GET /url` |
+| `httpx.HTTPError` | `HttpError` | `HTTP错误: GET /url` |
+
+```python
+from df_test_framework.core.exceptions import HttpError
+
+try:
+    client.get("/slow-endpoint")
+except HttpError as e:
+    print(e.message)           # "请求超时: GET /slow-endpoint"
+    print(e.__cause__)         # 原始 httpx.TimeoutException
+    print(e.details)           # {"original_error": "ReadTimeout", "url": "/slow-endpoint"}
+```
+
+### AsyncBrowserPool
+
+异步浏览器实例池，管理多个 `AsyncBrowserManager` 实例，支持并发 UI 测试：
+
+```python
+from df_test_framework import AsyncBrowserPool
+
+pool = AsyncBrowserPool(max_browsers=3, max_contexts_per_browser=10)
+await pool.start()
+
+async with pool.acquire() as manager:
+    ctx = await manager.new_context()
+    page = await ctx.new_page()
+    await page.goto("https://example.com")
+    await page.close()
+    await ctx.close()
+
+print(pool.stats)  # {"total": 3, "active": 1, "idle": 2, ...}
+await pool.shutdown()
+```
+
+特性：
+- `asyncio.Semaphore` 控制总并发数
+- 按最少 context 数分配浏览器实例
+- `_PooledManager` 代理防止单次 acquire 创建多个 context
+- `start()` 失败自动回滚已启动的实例
+
+### fetch_swagger 增强
+
+重构为 `argparse`，新增自定义请求头和输出目录支持：
+
+```bash
+# 带认证头
+python scripts/fetch_swagger.py -H 'Authorization: Bearer token' http://example.com
+
+# 指定输出目录
+python scripts/fetch_swagger.py -d output/ http://example.com
+
+# 组合使用
+python scripts/fetch_swagger.py -H 'Cookie: sid=abc' -d docs/ http://localhost:8089/doc.html
+```
+
+改进：
+- 中文文件名保留（`unicodedata.normalize` + 正则清理）
+- JSON 解析容错（不再依赖 content-type 判断）
+- 输出目录自动创建
+
+---
+
+## 迁移指南
+
+### 异常捕获更新
+
+```python
+# ❌ 之前
+from httpx import HTTPStatusError
+with pytest.raises((BusinessError, HTTPStatusError)):
+    api.get_current_user(skip_auth=True)
+
+# ✅ 现在
+from df_test_framework.core.exceptions import HttpError
+with pytest.raises((BusinessError, HttpError)):
+    api.get_current_user(skip_auth=True)
+```
+
+### BaseAPI 用户（无需改动）
+
+`BaseAPI` 的 `get`/`post` 等方法内部已自动使用框架 `Response`，返回 Pydantic 模型或 `dict` 的用法不变。
+
+### 直接使用 HttpClient 的用户
+
+```python
+# ❌ 之前：返回 httpx.Response
+response = client.request("GET", "/users")
+response.raise_for_status()  # httpx 方法
+
+# ✅ 现在：返回框架 Response
+response = client.request("GET", "/users")
+response.raise_for_status()  # 框架方法（行为一致）
+
+# 如需原始 httpx.Response
+response = client.request_raw("GET", "/users")
+```

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "df-test-framework"
-version = "4.1.0"
+version = "4.1.1"
 description = "基于交互模式的现代化测试自动化框架，支持多种测试场景"
 authors = [{name = "DF QA Team", email = "qa@example.com"}]
 readme = "README_PYPI.md"

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/scripts/fetch_swagger.py

@@ -7,22 +7,26 @@
 - Spring Boot context-path
 
 用法：
-    python scripts/fetch_swagger.py [URL] [OUTPUT]
+    python scripts/fetch_swagger.py [OPTIONS] URL [OUTPUT]
 
 示例：
     python scripts/fetch_swagger.py http://localhost:8089/swagger-ui/index.html
-    python scripts/fetch_swagger.py http://localhost:8089/api/doc.html  # 带 context-path
+    python scripts/fetch_swagger.py http://localhost:8089/api/doc.html
     python scripts/fetch_swagger.py http://example.com swagger.json
+    python scripts/fetch_swagger.py -H 'Authorization: Bearer token' http://example.com
+    python scripts/fetch_swagger.py -d output/ http://example.com
 """
 
+import argparse
 import json
+import re
 import sys
+import unicodedata
 from pathlib import Path
 from urllib.parse import urlparse
 
 import httpx
 
-
 # 常见的 OpenAPI 文档端点（按优先级排序）
 COMMON_API_DOC_PATHS = [
     # OpenAPI 3.x
@@ -42,6 +46,45 @@ COMMON_API_DOC_PATHS = [
 ]
 
 
+def parse_args():
+    """解析命令行参数"""
+    parser = argparse.ArgumentParser(description="从 Swagger UI / Knife4j 获取 OpenAPI 文档")
+    parser.add_argument("url", help="Swagger UI 或 Knife4j 页面 URL")
+    parser.add_argument("output", nargs="?", default=None, help="输出文件名（可选）")
+    parser.add_argument(
+        "-H",
+        "--header",
+        action="append",
+        default=[],
+        help="自定义请求头（可多次使用），如: -H 'Authorization: Bearer token'",
+    )
+    parser.add_argument(
+        "-d",
+        "--output-dir",
+        default=".",
+        help="输出目录（默认当前目录）",
+    )
+    return parser.parse_args()
+
+
+def _parse_headers(header_list: list[str]) -> dict[str, str]:
+    """解析 -H 'Key: Value' 格式的请求头"""
+    headers = {}
+    for h in header_list:
+        if ":" in h:
+            key, value = h.split(":", 1)
+            headers[key.strip()] = value.strip()
+    return headers
+
+
+def _sanitize_filename(name: str) -> str:
+    """清理文件名，保留中文、字母、数字、连字符、下划线"""
+    name = unicodedata.normalize("NFKC", name)
+    name = re.sub(r"[^\w\u4e00-\u9fff\-]", "_", name)
+    name = re.sub(r"_+", "_", name).strip("_")
+    return name or "swagger"
+
+
 def get_base_url(url: str) -> str:
     """从 URL 中提取基础地址（包含 context-path）
 
@@ -58,10 +101,10 @@ def get_base_url(url: str) -> str:
 
     # 常见的 Swagger/Knife4j UI 页面路径（需要从 URL 中移除）
     ui_patterns = [
-        "/doc.html",           # Knife4j
-        "/swagger-ui.html",    # 旧版 Swagger UI
-        "/swagger-ui/",        # SpringDoc Swagger UI
-        "/webjars/",           # 静态资源
+        "/doc.html",  # Knife4j
+        "/swagger-ui.html",  # 旧版 Swagger UI
+        "/swagger-ui/",  # SpringDoc Swagger UI
+        "/webjars/",  # 静态资源
     ]
 
     # 提取 context-path：移除 UI 页面路径部分
@@ -94,17 +137,21 @@ def try_fetch_swagger_doc(base_url: str, client: httpx.Client) -> dict | list[di
         try:
             response = client.get(url, timeout=10)
             if response.status_code == 200:
-                content_type = response.headers.get("content-type", "")
-                if "json" in content_type or path.endswith(".json") or "?" in path:
+                try:
                     data = response.json()
-                    # 检查是否是有效的 OpenAPI 文档
-                    if "swagger" in data or "openapi" in data or "paths" in data:
-                        print(f"  ✅ 找到 OpenAPI 文档: {url}")
-                        return data
-
-                    # 可能是 swagger-resources 响应（Knife4j 多分组模式）
-                    if isinstance(data, list) and len(data) > 0:
-                        return _handle_swagger_resources(base_url, data, client)
+                except (json.JSONDecodeError, ValueError):
+                    continue
+
+                # 检查是否是有效的 OpenAPI 文档
+                if isinstance(data, dict) and (
+                    "swagger" in data or "openapi" in data or "paths" in data
+                ):
+                    print(f"  ✅ 找到 OpenAPI 文档: {url}")
+                    return data
+
+                # 可能是 swagger-resources 响应（Knife4j 多分组模式）
+                if isinstance(data, list) and len(data) > 0:
+                    return _handle_swagger_resources(base_url, data, client)
         except Exception as e:
             print(f"  ❌ 失败: {e}")
             continue
@@ -163,13 +210,18 @@ def _handle_swagger_resources(
     return docs
 
 
-def fetch_swagger(url: str, output: str | None = None) -> None:
+def fetch_swagger(
+    url: str,
+    output: str | None = None,
+    headers: dict[str, str] | None = None,
+    output_dir: str = ".",
+) -> None:
     """获取 Swagger 文档并保存"""
     base_url = get_base_url(url)
     print(f"基础地址: {base_url}")
     print("正在探测 OpenAPI 文档端点...")
 
-    with httpx.Client(follow_redirects=True) as client:
+    with httpx.Client(follow_redirects=True, headers=headers or {}) as client:
         # 尝试获取文档
         result = try_fetch_swagger_doc(base_url, client)
 
@@ -182,23 +234,24 @@ def fetch_swagger(url: str, output: str | None = None) -> None:
 
         # 处理多分组情况
         if isinstance(result, list):
-            _save_multiple_docs(result, output)
+            _save_multiple_docs(result, output, output_dir)
         else:
-            _save_single_doc(result, output)
+            _save_single_doc(result, output, output_dir)
 
 
-def _save_single_doc(doc: dict, output: str | None) -> None:
+def _save_single_doc(doc: dict, output: str | None, output_dir: str = ".") -> None:
     """保存单个文档"""
     # 确定输出文件名
     if not output:
         # 从文档中获取标题作为文件名
         title = doc.get("info", {}).get("title", "swagger")
-        # 清理文件名
-        safe_title = "".join(c if c.isalnum() or c in "-_" else "_" for c in title)
+        # 清理文件名（支持中文）
+        safe_title = _sanitize_filename(title)
         output = f"{safe_title}.json"
 
     # 保存文档
-    output_path = Path(output)
+    output_path = Path(output_dir) / output
+    output_path.parent.mkdir(parents=True, exist_ok=True)
     with open(output_path, "w", encoding="utf-8") as f:
         json.dump(doc, f, ensure_ascii=False, indent=2)
 
@@ -212,10 +265,13 @@ def _save_single_doc(doc: dict, output: str | None) -> None:
     print(f"   uv run df-test gen from-swagger {output_path.name}")
 
 
-def _save_multiple_docs(docs: list[dict], output: str | None) -> None:
+def _save_multiple_docs(docs: list[dict], output: str | None, output_dir: str = ".") -> None:
     """保存多个分组文档（Knife4j 多分组模式）"""
     print(f"\n📦 检测到 Knife4j 多分组模式，共 {len(docs)} 个分组")
 
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
     saved_files = []
     for doc in docs:
         group_name = doc.pop("_group_name", "unknown")
@@ -226,21 +282,21 @@ def _save_multiple_docs(docs: list[dict], output: str | None) -> None:
             # 用户指定了输出，添加分组后缀
             base_name = Path(output).stem
             suffix = Path(output).suffix or ".json"
-            safe_group = "".join(c if c.isalnum() or c in "-_" else "_" for c in group_name)
+            safe_group = _sanitize_filename(group_name)
             file_name = f"{base_name}_{safe_group}{suffix}"
         else:
             # 使用分组名作为文件名
-            safe_group = "".join(c if c.isalnum() or c in "-_" else "_" for c in group_name)
+            safe_group = _sanitize_filename(group_name)
             file_name = f"{safe_group}.json"
 
-        output_path = Path(file_name)
+        output_path = out_dir / file_name
         with open(output_path, "w", encoding="utf-8") as f:
             json.dump(doc, f, ensure_ascii=False, indent=2)
 
         saved_files.append((output_path, group_name, len(doc.get("paths", {}))))
         print(f"  ✅ {output_path.name} ({len(doc.get('paths', {}))} 个接口)")
 
-    print(f"\n📁 已保存 {len(saved_files)} 个文件")
+    print(f"\n📁 已保存 {len(saved_files)} 个文件到: {out_dir.absolute()}")
 
     # 提示使用方法
     print("\n🚀 使用方法:")
@@ -249,11 +305,6 @@ def _save_multiple_docs(docs: list[dict], output: str | None) -> None:
 
 
 if __name__ == "__main__":
-    if len(sys.argv) < 2:
-        print(__doc__)
-        sys.exit(0)
-
-    url = sys.argv[1]
-    output = sys.argv[2] if len(sys.argv) > 2 else None
-
-    fetch_swagger(url, output)
+    args = parse_args()
+    custom_headers = _parse_headers(args.header)
+    fetch_swagger(args.url, args.output, headers=custom_headers, output_dir=args.output_dir)

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/src/df_test_framework/__init__.py

@@ -144,7 +144,7 @@ v3.18.1 特性:
 - 🔄 Unit of Work 模式支持（v3.7）
 """
 
-__version__ = "4.1.0"
+__version__ = "4.1.1"
 __author__ = "DF QA Team"
 
 # ==============================================================================
@@ -246,6 +246,7 @@ from .capabilities.drivers.web import (
     AsyncAppActions,
     AsyncBasePage,
     AsyncBrowserManager,
+    AsyncBrowserPool,
     BasePage,
     BrowserManager,
     # 工具类
@@ -598,6 +599,7 @@ __all__ = [
     "AsyncAppActions",  # v4.0.0 异步
     "AsyncBasePage",  # v4.0.0 异步
     "AsyncBrowserManager",  # v4.0.0 异步
+    "AsyncBrowserPool",  # 浏览器实例池
     "AppActions",  # 同步兼容
     "BasePage",  # 同步兼容
     "BrowserManager",  # 同步兼容

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/src/df_test_framework/capabilities/clients/http/core/response.py

@@ -18,6 +18,7 @@ class Response:
     headers: dict[str, str]
     body: str
     json_data: dict[str, Any] | None = None
+    elapsed: float = 0.0  # 请求耗时（秒），默认 0.0 保持向后兼容
 
     # 继承request的context
     context: dict[str, Any] = field(default_factory=dict)
@@ -47,6 +48,32 @@ class Response:
         """
         return self.context.get(key, default)
 
+    @property
+    def text(self) -> str:
+        """响应文本（兼容 httpx.Response.text）"""
+        return self.body
+
+    def json(self) -> dict[str, Any] | None:
+        """获取 JSON 数据（兼容 httpx.Response.json()）"""
+        if self.json_data is not None:
+            return self.json_data
+        if self.body:
+            import json as _json
+
+            return _json.loads(self.body)
+        return None
+
+    def raise_for_status(self) -> None:
+        """状态码非 2xx 时抛出异常（兼容 httpx.Response.raise_for_status()）"""
+        if self.is_client_error or self.is_server_error:
+            from df_test_framework.core.exceptions import HttpError
+
+            raise HttpError(
+                message=f"HTTP {self.status_code}",
+                status_code=self.status_code,
+                response_body=self.body,
+            )
+
     @property
     def is_success(self) -> bool:
         """是否成功（2xx）"""

{df_test_framework-4.1.0 → df_test_framework-4.1.1}/src/df_test_framework/capabilities/clients/http/rest/httpx/async_client.py

@@ -57,6 +57,8 @@ v3.17.0 重构:
 from __future__ import annotations
 
 import re
+import time
+from dataclasses import replace
 from typing import TYPE_CHECKING, Any
 
 import httpx
@@ -71,6 +73,7 @@ from df_test_framework.capabilities.clients.http.middleware import (
     MiddlewareFactory,
     PathFilteredMiddleware,
 )
+from df_test_framework.core.exceptions import HttpError
 from df_test_framework.core.middleware import (
     Middleware,
     MiddlewareChain,
@@ -320,8 +323,27 @@ class AsyncHttpClient:
         if request.data is not None:
             params["data"] = request.data
 
-        httpx_response = await self.client.request(request.method, request.url, **params)
-        return self._parse_response(httpx_response)
+        try:
+            start_time = time.monotonic()
+            httpx_response = await self.client.request(request.method, request.url, **params)
+            elapsed = time.monotonic() - start_time
+            response = self._parse_response(httpx_response)
+            return replace(response, elapsed=elapsed)
+        except httpx.TimeoutException as e:
+            raise HttpError(
+                message=f"请求超时: {request.method} {request.url}",
+                details={"original_error": type(e).__name__, "url": request.url},
+            ) from e
+        except httpx.ConnectError as e:
+            raise HttpError(
+                message=f"连接失败: {request.method} {request.url}",
+                details={"original_error": type(e).__name__, "url": request.url},
+            ) from e
+        except httpx.HTTPError as e:
+            raise HttpError(
+                message=f"HTTP错误: {request.method} {request.url}",
+                details={"original_error": type(e).__name__, "url": request.url},
+            ) from e
 
     # ==================== 核心请求方法 ====================