df-test-framework 4.1.2__tar.gz → 4.2.2__tar.gz

df_test_framework-4.2.2/AGENTS.md

@@ -0,0 +1,204 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+---
+
+## 项目概述
+
+**DF Test Framework** - 现代化 Python 测试自动化框架
+
+- **版本**: v4.1.2
+- **更新时间**: 2026-03-16
+- **Python**: 3.12+
+- **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
+- **架构**: 五层架构 + 横切关注点（能力层驱动设计）
+
+### v4.0.0 重大变更
+
+**全面异步化**：
+- ✅ AsyncHttpClient - 并发性能提升 10-30 倍
+- ✅ AsyncDatabase - 基于 SQLAlchemy 2.0 AsyncEngine
+- ✅ AsyncRedis - 缓存操作提升 5-10 倍
+- ✅ AsyncAppActions + AsyncBasePage - UI 测试性能提升 2-3 倍
+- ✅ 完全向后兼容 - 同步 API 保留
+
+---
+
+## 核心开发命令
+
+```bash
+# 依赖管理
+uv sync                    # 同步开发依赖
+uv sync --all-extras       # 同步所有可选依赖
+
+# 测试
+uv run pytest -v                                    # 运行所有测试
+uv run pytest -v --ignore=tests/test_messengers/    # 排除 MQ 测试
+
+# 代码质量
+uv run ruff check --fix src/ tests/    # 检查 + 自动修复
+uv run ruff format src/ tests/         # 格式化
+uv run mypy src/                       # 类型检查，可以跳过
+
+# 覆盖率（目标 ≥80%）
+uv run pytest --cov=src/df_test_framework --cov-report=term-missing
+```
+
+---
+
+## 五层架构
+
+```
+Layer 4 ─── bootstrap/                  # 引导层：Bootstrap、Providers、Runtime
+Layer 3 ─── testing/ + cli/             # 门面层：Fixtures、CLI
+Layer 2 ─── capabilities/               # 能力层：HTTP/UI/DB/MQ/Storage
+Layer 1 ─── infrastructure/             # 基础设施：config/logging/events/plugins
+Layer 0 ─── core/                       # 核心层：纯抽象（无依赖）
+横切 ───── plugins/                     # 插件：MonitoringPlugin、AllurePlugin
+```
+
+**依赖规则**: 高层可依赖低层，反之不行。Layer 0 无任何依赖。
+
+**层级 ≠ 目录**: 层级是依赖规则，不是目录划分。同一层可以有多个顶级目录：
+- Layer 3 包含两个独立接口：`testing/`（pytest fixtures）、`cli/`（命令行）
+- 它们都是框架能力的"门面"，依赖 Layer 0-2，互相不依赖
+- 新增接口层时放在 `src/df_test_framework/` 下作为独立目录，不要嵌入 bootstrap/ 等其他层
+
+---
+
+## 核心模式
+
+### HTTP 与 UI 测试架构一致性 (v3.45.0)
+
+| 维度 | HTTP 测试 | UI 测试 |
+|------|-----------|---------|
+| **装饰器** | `@api_class()` | `@actions_class()` |
+| **基类** | `BaseAPI` | `AppActions` |
+| **自动加载** | `load_api_fixtures()` | `load_actions_fixtures()` |
+| **配置字段** | `test.apis_package` | `test.actions_package` |
+| **目录** | `apis/` | `actions/` |
+| **默认 scope** | `session` | `function` |
+
+### 脚手架项目类型
+
+```bash
+df-test init my-project --type api   # API 项目：apis/, models/
+df-test init my-project --type ui    # UI 项目：actions/, pages/, components/
+df-test init my-project --type full  # 完整项目：apis/ + actions/ + pages/
+```
+
+### 关键组件
+
+- **中间件系统**: 洋葱模型，SignatureMiddleware、BearerTokenMiddleware、RetryMiddleware
+- **EventBus**: 事件驱动，HTTP/UI 事件自动发布，Allure 自动记录
+- **配置系统**: YAML 分层配置 + 环境变量，WebConfig/HTTPConfig/DatabaseConfig
+
+---
+
+## 代码规范
+
+### 类型注解
+
+```python
+# ✅ 现代风格
+def create(name: str, items: list[str] | None = None) -> dict[str, Any]: ...
+
+# ❌ 旧式
+def create(name: str, items: Optional[List[str]] = None) -> Dict[str, Any]: ...
+```
+
+### 测试命名
+
+```python
+# ✅ 清晰描述场景
+def test_login_with_valid_credentials_returns_token(self): ...
+
+# ❌ 不清晰
+def test_login(self): ...
+```
+
+### Ruff 配置
+
+- 行长度: 100
+- 目标版本: Python 3.12
+
+---
+
+## 版本发布
+
+发布新版本时，严格按以下顺序执行：
+
+### Step 1: 更新文件
+
+1. `pyproject.toml` + `src/df_test_framework/__init__.py` 版本号
+2. `CHANGELOG.md` - 简洁摘要
+3. `docs/releases/vX.X.X.md` - 详细发布说明
+4. `docs/guides/xxx.md` - 功能使用指南（如有新功能）
+5. `cli/templates/` - 脚手架模板（如有影响）
+
+### Step 2: 代码质量检查（必须全部通过）
+
+```bash
+uv run ruff check --fix src/ tests/                 # lint 检查
+uv run ruff format src/ tests/                       # 格式化
+uv run pytest -v --ignore=tests/test_messengers/     # 测试（排除 MQ）
+```
+
+如果有格式化改动，合并到发布 commit 中。
+
+### Step 3: 提交发布
+
+```bash
+git add <相关文件>
+git commit -m "chore(release): 发布 vX.X.X 版本"
+git push origin master
+```
+
+**Commit Message**: `<type>(<scope>): <subject>`
+- Type: feat/fix/docs/test/refactor/chore
+- Subject: 中文描述
+
+---
+
+## 目录结构
+
+```
+src/df_test_framework/
+├── core/                # Layer 0: middleware/context/events/protocols
+├── infrastructure/      # Layer 1: config/logging/telemetry/events/plugins
+├── capabilities/        # Layer 2: clients/drivers/databases/messengers/storages
+│   ├── clients/         #   HTTP + GraphQL + gRPC
+│   ├── drivers/         #   Playwright (Web UI)
+│   ├── databases/       #   MySQL + Redis + Repository + UoW
+│   ├── messengers/      #   Kafka + RabbitMQ + RocketMQ
+│   └── storages/        #   LocalFile + S3 + OSS
+├── testing/             # Layer 3: fixtures/decorators/data/debugging
+├── cli/                 # Layer 3: commands + templates
+├── bootstrap/           # Layer 4: Bootstrap + Providers + Runtime
+└── plugins/             # 横切: MonitoringPlugin + AllurePlugin
+
+cli/templates/
+├── project/             # 项目初始化模板（api/ui/full）
+└── generators/          # 代码生成模板
+```
+
+---
+
+## 重要提示
+
+- `tests/test_messengers/` 需要外部服务（Kafka/RabbitMQ/RocketMQ），CI 中跳过
+- `engines/` 目录预留，暂未实现
+- Windows 平台使用 `start` 而非 `open` 打开报告
+
+---
+
+## 参考文档
+
+| 类型 | 路径 |
+|------|------|
+| 架构设计 | `docs/architecture/` |
+| 使用指南 | `docs/guides/` |
+| Web UI 测试 | `docs/guides/web-ui-testing.md` |
+| 版本发布 | `docs/releases/` |
+| 更新日志 | `CHANGELOG.md` |

{df_test_framework-4.1.2 → df_test_framework-4.2.2}/CHANGELOG.md

@@ -5,6 +5,48 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.2.2] - 2026-04-15
+
+### 🔧 修复
+
+- **枚举类迁移至 `StrEnum`** (`core/types`, `infrastructure/config`, `capabilities`): 依赖升级后，将所有 `class Foo(str, Enum)` 统一改为 `class Foo(StrEnum)`，符合 Python 3.11+ 规范（UP042）
+- **脚手架模板 `{{}}` 残留** (`cli/templates/project`): 修复 `conftest.py`、`full_conftest.py`、`ui_conftest.py`、`async_example_api.py` 中 Jinja2 转义符残留导致生成文件包含 `{{}}` 错误字典字面量，实际应为 `{}`
+
+---
+
+## [4.2.1] - 2026-04-15
+
+### ✨ 新增功能
+
+- 🧩 **`BaseComponent` 多种 root 定位方式** (`capabilities/drivers/web`):
+  - 新增 `css_selector` 参数：通过 CSS 选择器定位 root（适合 Ant Design 等无 `data-testid` 的组件库）
+  - 新增 `locator` 参数：直接传入 Playwright `Locator`（最灵活，适合动态定位）
+  - 所有定位参数改为 keyword-only，优先级：`locator > test_id > css_selector > page`
+
+### 🔧 修复
+
+- **`SingletonProvider.reset()` 异步 close() 处理** (`bootstrap/providers`): 修复 `AsyncHttpClient.close()` 为协程时直接调用导致的 `RuntimeWarning` 和连接池泄漏，改为检测返回值是否为协程并通过事件循环调度执行
+- **代码生成器保留字冲突** (`cli/generators`): `to_snake_case` 后新增 `safe_field_name` 检查，字段名为 `list`/`dict`/`class`/`type` 等 Python 保留字时自动加 `_` 后缀，配合 `alias` 机制保持 JSON 映射不变
+- **递归子包扫描** (`testing/decorators`): `load_api_fixtures`、`load_actions_fixtures`、`load_service_fixtures` 改用 `pkgutil.walk_packages` 替代 `iter_modules`，支持多层嵌套子包自动注册
+
+---
+
+## [4.2.0] - 2026-04-02
+
+### ✨ 新增功能
+
+- 🔧 **工具函数模块** (`infrastructure/helpers`):
+  - AES 加解密（CBC 模式，PKCS7 填充，需 `pycryptodome`）
+  - MD5 / SHA-256 哈希、HMAC-SHA256 签名
+  - API 签名计算（`compute_sign`）
+  - 公网 IP 探测（`get_public_ip`）
+- 🔌 **`@service_client` 装饰器**: 独立服务客户端自动注册，通过 `base_url_config` 配置路径注入 base_url
+- 📦 **`crypto` 可选依赖组**: `pycryptodome>=3.20.0`
+
+### 🔧 修复
+
+- 🧹 OmsReporterPlugin 移除未使用的 `json` import
+
 ## [4.1.2] - 2026-03-16
 
 ### ✨ 新增功能

{df_test_framework-4.1.2 → df_test_framework-4.2.2}/CLAUDE.md

@@ -8,8 +8,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **DF Test Framework** - 现代化 Python 测试自动化框架
 
-- **版本**: v4.1.2
-- **更新时间**: 2026-03-16
+- **版本**: v4.2.2
+- **更新时间**: 2026-04-15
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.1.2 → df_test_framework-4.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.1.2
+Version: 4.2.2
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework
@@ -40,7 +40,7 @@ Requires-Dist: pymysql>=1.1.0
 Requires-Dist: pypinyin>=0.53.0
 Requires-Dist: pytest-asyncio>=1.3.0
 Requires-Dist: pytest-timeout>=2.2.0
-Requires-Dist: pytest>=9.0.1
+Requires-Dist: pytest==9.0.3
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: questionary>=2.0.0
@@ -63,11 +63,14 @@ Requires-Dist: oss2>=2.18.0; extra == 'all'
 Requires-Dist: pika>=1.3.0; extra == 'all'
 Requires-Dist: playwright>=1.40.0; extra == 'all'
 Requires-Dist: prometheus-client>=0.19.0; extra == 'all'
+Requires-Dist: pycryptodome>=3.20.0; extra == 'all'
 Requires-Dist: pypinyin>=0.53.0; extra == 'all'
 Requires-Dist: rocketmq-python-client>=5.0.0; extra == 'all'
 Requires-Dist: selenium>=4.0.0; extra == 'all'
 Provides-Extra: codegen
 Requires-Dist: pypinyin>=0.53.0; extra == 'codegen'
+Provides-Extra: crypto
+Requires-Dist: pycryptodome>=3.20.0; extra == 'crypto'
 Provides-Extra: database-async
 Requires-Dist: aiomysql>=0.2.0; extra == 'database-async'
 Requires-Dist: aiosqlite>=0.20.0; extra == 'database-async'

{df_test_framework-4.1.2 → df_test_framework-4.2.2}/docs/api-reference/infrastructure.md

@@ -1,6 +1,6 @@
 # Infrastructure API 参考
 
-基础设施层的完整API参考，包含Bootstrap启动器、RuntimeContext运行时上下文、配置管理和Provider系统。
+基础设施层的完整API参考，包含Bootstrap启动器、RuntimeContext运行时上下文、配置管理、Provider系统和工具函数。
 
 ---
 
@@ -26,10 +26,22 @@ from df_test_framework.infrastructure.config import (
 # Provider系统
 from df_test_framework.infrastructure.providers import ProviderRegistry
 
+# 工具函数 (v4.2.0)
+from df_test_framework import (
+    md5,
+    sha256,
+    hmac_sha256,
+    compute_sign,
+    get_public_ip,
+)
+# AES 加解密（需 crypto 可选依赖）
+from df_test_framework import aes_encrypt, aes_decrypt
+
 # 或者从具体模块导入
 from df_test_framework.infrastructure.bootstrap import Bootstrap
 from df_test_framework.infrastructure.runtime import RuntimeContext
 from df_test_framework.infrastructure.config.schema import FrameworkSettings
+from df_test_framework.infrastructure.helpers import md5, sha256, hmac_sha256, compute_sign, get_public_ip
 ```
 
 ---
@@ -804,6 +816,68 @@ def test_with_config(runtime):
 
 ---
 
+## 🔧 工具函数 (v4.2.0)
+
+> **详细指南**: [helpers_guide.md](../guides/helpers_guide.md)
+
+### 哈希函数
+
+基于 Python stdlib `hashlib`，无额外依赖。
+
+| 函数 | 签名 | 返回值 |
+|------|------|--------|
+| `md5(text)` | `md5(text: str) -> str` | 32 位小写 hex |
+| `sha256(text)` | `sha256(text: str) -> str` | 64 位小写 hex |
+| `hmac_sha256(text, secret)` | `hmac_sha256(text: str, secret: str) -> str` | 64 位小写 hex |
+
+### compute_sign - API 签名计算
+
+```python
+def compute_sign(
+    params: dict[str, str],
+    secret: str,
+    *,
+    algorithm: Literal["md5", "sha256", "hmac-sha256"] = "md5",
+    concat_mode: Literal["values_only", "key_value"] = "values_only",
+    separator: str = "",
+    secret_position: Literal["append", "prepend"] = "append",
+) -> str
+```
+
+### aes_encrypt / aes_decrypt - AES 加解密
+
+需要 `crypto` 可选依赖（`pip install df-test-framework[crypto]`）。
+
+```python
+def aes_encrypt(
+    plaintext: str,
+    key: str | bytes,
+    iv: str | bytes | None = None,
+    *,
+    mode: Literal["CBC", "ECB"] = "CBC",
+    encoding: Literal["hex", "base64"] = "hex",
+) -> str
+
+def aes_decrypt(
+    ciphertext: str | bytes,
+    key: str | bytes,
+    iv: str | bytes | None = None,
+    *,
+    mode: Literal["CBC", "ECB"] = "CBC",
+    encoding: Literal["hex", "base64"] = "hex",
+) -> str
+```
+
+### get_public_ip - 公网 IP 探测
+
+```python
+def get_public_ip(timeout: int = 10) -> str
+```
+
+依次尝试 httpbin.org、ipify.org、ifconfig.me，任一成功即返回。
+
+---
+
 ## 🔗 相关文档
 
 ### v3架构文档

{df_test_framework-4.1.2 → df_test_framework-4.2.2}/docs/api-reference/testing.md

@@ -21,6 +21,17 @@ from df_test_framework.testing.fixtures.core import (
     redis_client,
 )
 
+# 测试装饰器
+from df_test_framework.testing.decorators import (
+    api_class,
+    actions_class,
+    service_client,         # v4.2.0 新增
+    load_api_fixtures,
+    load_actions_fixtures,
+    load_service_fixtures,  # v4.2.0 新增
+    get_service_registry,   # v4.2.0 新增
+)
+
 # Plugins（测试中使用）
 from df_test_framework.testing.plugins import (
     AllureHelper,
@@ -1120,6 +1131,48 @@ def test_create_card(
 
 ---
 
+## 🔌 @service_client 装饰器 (v4.2.0)
+
+> **详细指南**: [service_client_guide.md](../guides/service_client_guide.md)
+
+将独立服务客户端类自动注册为 pytest fixture，无需继承 `BaseAPI`。
+
+### 装饰器签名
+
+```python
+@service_client(
+    name: str | None = None,           # fixture 名称（默认从类名生成）
+    scope: str = "session",            # pytest fixture scope
+    base_url_config: str | None = None, # settings 配置路径（dot notation）
+    **dependencies: Any,               # 额外依赖映射
+)
+```
+
+### 辅助函数
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `load_service_fixtures` | `(module_globals, services_package=None) -> None` | 加载所有注册的服务客户端 fixture |
+| `get_service_registry` | `() -> dict` | 获取注册表副本 |
+| `create_service_fixture` | `(cls, fixture_name, scope, base_url_config, **deps) -> Callable` | 为单个类创建 fixture |
+
+### 与 @api_class 的对比
+
+| 维度 | @api_class | @service_client |
+|------|-----------|----------------|
+| 基类要求 | 必须继承 `BaseAPI` | 无要求 |
+| HTTP 客户端 | 共享框架的 `http_client` | 自行管理 |
+| base_url | 从框架配置统一获取 | 通过 `base_url_config` 注入 |
+| 认证方式 | 框架中间件统一处理 | 各客户端自行实现 |
+
+### 自动依赖推断
+
+如果 `__init__` 签名中的参数名匹配以下 fixture，框架会自动注入：
+
+`settings`、`database`、`async_database`、`redis_client`、`async_redis_client`、`runtime`、`rabbitmq_client`、`kafka_client`、`rocketmq_client`
+
+---
+
 ## 🔗 相关文档
 
 ### v3架构文档

{df_test_framework-4.1.2 → df_test_framework-4.2.2}/docs/architecture/CODE_STRUCTURE.md

@@ -1,8 +1,8 @@
 # 代码结构导航
 
 > **目标读者**: 框架开发者、问题修复者、代码贡献者
-> **更新日期**: 2026-03-16
-> **框架版本**: v4.1.2
+> **更新日期**: 2026-04-02
+> **框架版本**: v4.2.0
 
 ---
 
@@ -37,6 +37,7 @@ src/df_test_framework/
 │   ├── logging/             #   结构化日志（structlog）
 │   ├── telemetry/           #   OpenTelemetry 追踪
 │   ├── events/              #   事件基础设施
+│   ├── helpers/             #   工具函数（哈希/加密/签名/网络）
 │   └── plugins/             #   Pluggy 插件系统
 │
 ├── capabilities/            # Layer 2: 能力层（按交互模式组织）
@@ -75,7 +76,8 @@ src/df_test_framework/
 │   │   └── ui.py            #     UI 测试 fixtures
 │   ├── decorators/          #   装饰器
 │   │   ├── api_class.py     #     @api_class 装饰器
-│   │   └── actions_class.py #     @actions_class 装饰器
+│   │   ├── actions_class.py #     @actions_class 装饰器
+│   │   └── service_client.py #    @service_client 装饰器
 │   ├── data/                #   测试数据
 │   │   ├── builders/        #     Builder 模式
 │   │   └── cleanup/         #     数据清理
@@ -266,6 +268,31 @@ infrastructure/plugins/
 - `df_providers` - Provider 注册扩展
 - `df_post_bootstrap` - Bootstrap 后处理
 
+### 📁 infrastructure/helpers/
+
+> **引入版本**: v4.2.0
+
+**职责**：通用工具函数（哈希、加密、签名、网络探测）
+
+```
+infrastructure/helpers/
+├── __init__.py          # 统一导出
+├── hash.py              # MD5/SHA256/HMAC-SHA256（基于 stdlib）
+├── crypto.py            # AES 加解密（需 pycryptodome）
+├── signature.py         # API 参数签名计算
+└── network.py           # 公网 IP 探测
+```
+
+**关键函数**：
+- `md5(text)` / `sha256(text)` / `hmac_sha256(text, secret)` - 哈希函数
+- `aes_encrypt()` / `aes_decrypt()` - AES-CBC/ECB 加解密（需 `crypto` 可选依赖）
+- `compute_sign(params, secret)` - API 参数签名（支持 MD5/SHA256/HMAC-SHA256）
+- `get_public_ip()` - 公网出口 IP 探测
+
+**使用场景**：
+- 测试中需要计算 API 签名、加解密敏感参数
+- IP 白名单测试场景
+
 ---
 
 ## 🟡 Layer 2: 能力层 (capabilities/)
@@ -411,17 +438,19 @@ testing/fixtures/
 
 ### 📁 testing/decorators/
 
-**职责**：装饰器（自动加载 API/Actions 类）
+**职责**：装饰器（自动加载 API/Actions/服务客户端类）
 
 ```
 testing/decorators/
 ├── api_class.py         # @api_class 装饰器
-└── actions_class.py     # @actions_class 装饰器
+├── actions_class.py     # @actions_class 装饰器
+└── service_client.py    # @service_client 装饰器
 ```
 
 **关键装饰器**：
 - `@api_class(scope="session")` - 自动加载 API 类为 fixture
 - `@actions_class(scope="function")` - 自动加载 Actions 类为 fixture
+- `@service_client(base_url_config="...")` - 自动加载独立服务客户端为 fixture（v4.2.0）
 
 ### 📁 cli/commands/
 
@@ -631,5 +660,5 @@ from df_test_framework.capabilities.clients.http import HttpClient  # 违反依
 
 ---
 
-**最后更新**: 2026-03-16
+**最后更新**: 2026-04-02
 

{df_test_framework-4.1.2 → df_test_framework-4.2.2}/docs/guides/decorators_guide.md

@@ -1,7 +1,7 @@
 # 装饰器使用指南
 
-> **最后更新**: 2026-01-17
-> **适用版本**: v3.7.0+（通用装饰器），v3.45.0+（测试装饰器）
+> **最后更新**: 2026-04-02
+> **适用版本**: v3.7.0+（通用装饰器），v3.45.0+（测试装饰器），v4.2.0+（服务客户端装饰器）
 
 ## 概述
 
@@ -9,12 +9,14 @@ DF Test Framework 提供了两类装饰器，帮助简化测试代码和增强
 
 ### 测试装饰器（Testing Decorators）
 
-用于自动注册 API 类和 UI Actions 类为 pytest fixture，无需手动创建 fixture 函数。
+用于自动注册 API 类、UI Actions 类和独立服务客户端为 pytest fixture，无需手动创建 fixture 函数。
 
 - **@api_class**: 自动将 BaseAPI 子类注册为 pytest fixture
 - **@actions_class**: 自动将 AppActions 子类注册为 pytest fixture
+- **@service_client**: 自动将独立服务客户端注册为 pytest fixture（v4.2.0）
 - **load_api_fixtures()**: 自动加载所有 API fixtures
 - **load_actions_fixtures()**: 自动加载所有 Actions fixtures
+- **load_service_fixtures()**: 自动加载所有服务客户端 fixtures（v4.2.0）
 
 ### 通用装饰器（Core Decorators）
 
@@ -270,15 +272,71 @@ def test_order_flow(login_actions, order_actions):
     assert order_id is not None
 ```
 
-### 与 @api_class 的对比
+### 与 @api_class / @service_client 的对比
 
-| 特性 | @api_class | @actions_class |
-|------|-----------|----------------|
-| 基类 | `BaseAPI` | `AppActions` |
-| 默认 scope | `session` | `function` |
-| 配置字段 | `test.apis_package` | `test.actions_package` |
-| 目录约定 | `apis/` | `actions/` |
-| 自动依赖 | `http_client` | `page`, `browser_manager` |
+| 特性 | @api_class | @actions_class | @service_client |
+|------|-----------|----------------|----------------|
+| 基类 | `BaseAPI` | `AppActions` | 无要求 |
+| 默认 scope | `session` | `function` | `session` |
+| 配置字段 | `test.apis_package` | `test.actions_package` | `base_url_config` |
+| 目录约定 | `apis/` | `actions/` | `apis/` 或自定义 |
+| 自动依赖 | `http_client` | `page`, `browser_manager` | 按 `__init__` 签名推断 |
+
+---
+
+## @service_client 装饰器
+
+> **引入版本**: v4.2.0
+> **适用场景**: 独立服务客户端（不同 base_url、不同认证方式）
+> **详细指南**: [service_client_guide.md](service_client_guide.md)
+
+### 基本用法
+
+`@service_client` 装饰器自动将任意类注册为 pytest fixture，无需继承 `BaseAPI`。适合调用独立外部服务。
+
+```python
+from df_test_framework import service_client
+
+@service_client("payment_client", base_url_config="business.payment_url")
+class PaymentClient:
+    def __init__(self, base_url: str, timeout: int = 30):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def charge(self, order_no: str, amount: float) -> dict:
+        import httpx
+        with httpx.Client(timeout=self.timeout) as client:
+            return client.post(f"{self.base_url}/charge", json={"orderNo": order_no, "amount": amount}).json()
+```
+
+### 自动依赖注入
+
+如果 `__init__` 参数名匹配已知 fixture（如 `redis_client`、`database`），框架会自动注入：
+
+```python
+@service_client("my_client", base_url_config="business.my_url")
+class MyClient:
+    def __init__(self, base_url: str, redis_client=None):
+        self.base_url = base_url
+        self.redis = redis_client  # 自动注入 redis_client fixture
+```
+
+### 自动加载
+
+```python
+# conftest.py
+from df_test_framework.testing.decorators import load_service_fixtures
+
+load_service_fixtures(globals(), services_package="my_project.apis")
+```
+
+### 在测试中使用
+
+```python
+def test_charge(payment_client):
+    result = payment_client.charge("ORD001", 99.9)
+    assert result["retCode"] == "0"
+```
 
 ---
 
@@ -611,6 +669,8 @@ def frequent_call():
 - [Fixtures 使用指南](fixtures_guide.md) - pytest fixtures 详细说明
 - [HTTP 客户端指南](http_client_guide.md) - BaseAPI 使用方法
 - [Web UI 测试指南](web-ui-testing.md) - AppActions 使用方法
+- [服务客户端指南](service_client_guide.md) - @service_client 详细使用方法
+- [工具函数指南](helpers_guide.md) - 哈希/加密/签名工具
 - [配置系统指南](config_guide.md) - 配置 apis_package 和 actions_package
 
 ---
@@ -624,8 +684,10 @@ def frequent_call():
 from df_test_framework.testing.decorators import (
     api_class,
     actions_class,
+    service_client,
     load_api_fixtures,
     load_actions_fixtures,
+    load_service_fixtures,
 )
 
 # 通用装饰器
@@ -665,4 +727,4 @@ myproject/
 
 ---
 
-**完成时间**: 2026-01-17
+**完成时间**: 2026-04-02