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

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

@@ -5,6 +5,70 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.3.1] - 2026-04-16
+
+### 🔧 改进
+
+- **HTTP 方法 `@overload` 类型重载** (`BaseAPI` / `AsyncBaseAPI`): `get/post/put/delete/patch` 新增两组 `@overload`，当 `model=type[T]` 时推断返回 `T`，当 `model=None` 时推断返回 `dict[str, Any]`，消除调用处的手动类型转换
+
+---
+
+## [4.3.0] - 2026-04-16
+
+### ✨ 新增功能
+
+- 🗄️ **多数据库方言支持** (`infrastructure/config/schema`): `DatabaseConfig` 新增 `dialect` 字段，通过 host/port/name/user/password 可自动组装非 MySQL 数据库的连接字符串，无需手动拼写完整 URL
+  - `dialect: "mysql"`（默认，兼容现有配置）→ `mysql+pymysql://...?charset=utf8mb4`
+  - `dialect: "mssql"` → `mssql+pyodbc://...?driver=ODBC+Driver+18...`，配合新增的 `driver`（ODBC 驱动名）和 `trust_server_certificate`（默认 True）字段
+  - `dialect: "postgresql"` → `postgresql+psycopg2://...`
+  - `dialect: "sqlite"` → `sqlite:///name`
+- 🔄 **MSSQL 异步驱动映射** (`infrastructure/config/schema`): `resolved_async_connection_string()` 新增 `mssql+pyodbc → mssql+aioodbc` 映射
+- 📦 **`database-mssql` 可选依赖组**: 新增 `pyodbc>=5.1.0`（同步）和 `aioodbc>=0.5.0`（异步）
+  ```bash
+  uv sync --extra database-mssql
+  ```
+
+- 🐰 **RabbitMQ / Kafka 环境配置支持** (`infrastructure/config/schema`, `testing/fixtures/message_queue`):
+  新增 `RabbitMQSettingsConfig` 和 `KafkaSettingsConfig`，`FrameworkSettings` 增加 `rabbitmq:` / `kafka:` 可选字段（`default=None`，不配则透明，不污染非 MQ 项目）。`rabbitmq_config` / `kafka_config` fixtures 优先从 settings 读取，未配置时回退 localhost 默认值（向后兼容）
+
+### 📝 配置示例（MSSQL）
+
+```yaml
+# config/environments/test.yaml
+db:
+  dialect: mssql
+  host: 10.0.0.1
+  port: 1433
+  name: mydb
+  user: sa
+  # password 建议放 config/secrets/.env.local: DB__PASSWORD=...
+  pool_size: 5
+  pool_recycle: 1800
+  # driver: "ODBC Driver 17 for SQL Server"  # 默认 18，如需 17 在此覆盖
+  # trust_server_certificate: true           # 默认 true，生产环境可设 false
+```
+
+### 📝 配置示例（RabbitMQ / Kafka）
+
+```yaml
+# config/environments/test.yaml
+rabbitmq:
+  host: mq.test.example.com
+  port: 5672
+  username: admin
+  # password 放 .env.local: RABBITMQ__PASSWORD=...
+
+kafka:
+  bootstrap_servers:
+    - broker1.test.example.com:9092
+  # security_protocol: SASL_PLAINTEXT  # 需要认证时配置
+  # sasl_mechanism: PLAIN
+  # sasl_username: user
+  # sasl_password 放 .env.local: KAFKA__SASL_PASSWORD=...
+```
+
+---
+
 ## [4.2.2] - 2026-04-15
 
 ### 🔧 修复

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.2.2
+Version: 4.3.1
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework
@@ -75,6 +75,9 @@ Provides-Extra: database-async
 Requires-Dist: aiomysql>=0.2.0; extra == 'database-async'
 Requires-Dist: aiosqlite>=0.20.0; extra == 'database-async'
 Requires-Dist: asyncpg>=0.29.0; extra == 'database-async'
+Provides-Extra: database-mssql
+Requires-Dist: aioodbc>=0.5.0; extra == 'database-mssql'
+Requires-Dist: pyodbc>=5.1.0; extra == 'database-mssql'
 Provides-Extra: kafka
 Requires-Dist: confluent-kafka>=2.12.0; extra == 'kafka'
 Provides-Extra: mq

{df_test_framework-4.2.2 → df_test_framework-4.3.1}/docs/guides/config_guide.md

@@ -1,6 +1,6 @@
 # 配置系统使用指南
 
-> **最后更新**: 2026-01-17
+> **最后更新**: 2026-04-16
 > **适用版本**: v3.35.0+（YAML 分层配置）
 
 DF Test Framework 提供完整的多环境配置支持，包括 YAML 分层配置、深度合并、`_extends` 继承、统一配置访问等功能。
@@ -574,10 +574,12 @@ jobs:
 | `env` | str | 环境名称 |
 | `debug` | bool | 调试模式 |
 | `http` | HTTPConfig | HTTP 客户端配置 |
-| `db` | DatabaseConfig | 数据库配置 |
-| `redis` | RedisConfig | Redis 配置 |
-| `storage` | StorageConfig | 存储配置 |
-| `test` | TestConfig | 测试执行配置 |
+| `db` | DatabaseConfig \| None | 数据库配置（未配置时为 None） |
+| `redis` | RedisConfig \| None | Redis 配置（未配置时为 None） |
+| `rabbitmq` | RabbitMQSettingsConfig \| None | RabbitMQ 连接配置（v4.3.0，可选） |
+| `kafka` | KafkaSettingsConfig \| None | Kafka 连接配置（v4.3.0，可选） |
+| `storage` | StorageConfig \| None | 存储配置 |
+| `test` | TestExecutionConfig | 测试执行配置 |
 | `logging` | LoggingConfig | 日志配置 |
 | `observability` | ObservabilityConfig | 可观测性配置 |
 
@@ -594,12 +596,45 @@ jobs:
 
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `host` | str | "localhost" | 数据库主机 |
-| `port` | int | 3306 | 端口 |
-| `database` | str | "" | 数据库名 |
-| `username` | str | "" | 用户名 |
-| `password` | str | "" | 密码 |
-| `charset` | str | "utf8mb4" | 字符集 |
+| `connection_string` | str \| None | None | 完整连接字符串（优先级最高，设置后其他字段忽略） |
+| `dialect` | str \| None | None | 数据库方言：`mysql`（默认）、`mssql`、`postgresql`、`sqlite`（v4.3.0） |
+| `host` | str \| None | None | 数据库主机 |
+| `port` | int \| None | None | 端口 |
+| `name` | str \| None | None | 数据库名 |
+| `user` | str \| None | None | 用户名 |
+| `password` | SecretStr \| None | None | 密码 |
+| `charset` | str | "utf8mb4" | 字符集（MySQL 专用） |
+| `driver` | str \| None | None | ODBC 驱动名（MSSQL 专用，默认 "ODBC Driver 18 for SQL Server"）（v4.3.0） |
+| `trust_server_certificate` | bool | True | TrustServerCertificate（MSSQL 专用）（v4.3.0） |
+
+> **MySQL**：`dialect` 可省略（默认）。**MSSQL** 需系统安装 ODBC Driver 且 `uv sync --extra database-mssql`。
+
+### RabbitMQSettingsConfig 字段（v4.3.0）
+
+配置在 `rabbitmq:` 块下（不配置时字段为 None，不影响不使用 MQ 的项目）：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `host` | str | "localhost" | RabbitMQ 服务器地址 |
+| `port` | int | 5672 | 端口 |
+| `virtual_host` | str | "/" | 虚拟主机 |
+| `username` | str | "guest" | 用户名 |
+| `password` | SecretStr \| None | None | 密码 |
+| `heartbeat` | int | 600 | 心跳间隔（秒） |
+| `connection_attempts` | int | 3 | 最大连接重试次数 |
+| `retry_delay` | float | 2.0 | 重试间隔（秒） |
+
+### KafkaSettingsConfig 字段（v4.3.0）
+
+配置在 `kafka:` 块下：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `bootstrap_servers` | list[str] | ["localhost:9092"] | Broker 地址列表（也接受逗号分隔字符串） |
+| `security_protocol` | str | "PLAINTEXT" | 安全协议（PLAINTEXT / SASL_PLAINTEXT / SASL_SSL / SSL） |
+| `sasl_mechanism` | str \| None | None | SASL 机制（PLAIN / SCRAM-SHA-256 等） |
+| `sasl_username` | str \| None | None | SASL 用户名 |
+| `sasl_password` | SecretStr \| None | None | SASL 密码 |
 
 ---
 

{df_test_framework-4.2.2 → df_test_framework-4.3.1}/docs/guides/database_guide.md

@@ -1,7 +1,7 @@
 # 数据库访问指南
 
-> **最后更新**: 2026-01-16
-> **适用版本**: v2.0.0+（同步），v4.0.0+（异步推荐）
+> **最后更新**: 2026-04-16
+> **适用版本**: v2.0.0+（同步），v4.0.0+（异步推荐），v4.3.0+（多方言支持）
 
 ---
 
@@ -21,25 +21,63 @@ DF Test Framework 提供完整的数据库访问能力，支持同步和异步
 | 数据库 | 同步驱动 | 异步驱动 | 推荐版本 |
 |--------|---------|---------|---------|
 | **MySQL** | pymysql | aiomysql | 5.7+ |
+| **MSSQL** | pyodbc | aioodbc | SQL Server 2017+ |
 | **PostgreSQL** | psycopg2 | asyncpg | 12+ |
 | **SQLite** | sqlite3 | aiosqlite | 3.35+ |
 
+MSSQL 需安装额外依赖（系统也需安装 ODBC Driver）：
+
+```bash
+uv sync --extra database-mssql
+# 或
+pip install 'df-test-framework[database-mssql]'
+```
+
 ---
 
 ## 快速开始
 
 ### 1. 配置数据库
 
+**YAML 配置（推荐，v3.35.0+）**
+
+```yaml
+# config/environments/test.yaml
+
+# MySQL（默认，dialect 可省略）
+db:
+  host: db.example.com
+  port: 3306
+  name: test_db
+  user: root
+  # password 建议放 config/secrets/.env.local: DB__PASSWORD=...
+
+# MSSQL（v4.3.0+）
+db:
+  dialect: mssql
+  host: mssql.example.com
+  port: 1433
+  name: test_db
+  user: sa
+  # driver: "ODBC Driver 18 for SQL Server"  # 可选，默认即此值
+  # trust_server_certificate: true            # 默认 true
+
+# PostgreSQL（v4.3.0+）
+db:
+  dialect: postgresql
+  host: pg.example.com
+  port: 5432
+  name: test_db
+  user: postgres
+```
+
+**直接指定连接字符串（所有版本，优先级最高）**
+
 ```yaml
-# .env 或 configs/config.yaml
-DB__HOST=localhost
-DB__PORT=3306
-DB__NAME=test_db
-DB__USER=root
-DB__PASSWORD=password
-
-# 连接字符串方式
-DB__CONNECTION_STRING=mysql+pymysql://root:password@localhost:3306/test_db
+db:
+  connection_string: "mysql+pymysql://root:password@localhost:3306/test_db"
+  # 或 MSSQL 完整 connection string:
+  # connection_string: "mssql+pyodbc://sa:pass@host:1433/db?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
 ```
 
 ### 2. 选择合适的客户端
@@ -549,9 +587,10 @@ async def test_with_fixture(async_database):
 DB__CONNECTION_STRING=mysql+pymysql://user:pass@localhost/test_db
 
 # 框架自动转换：
-# mysql+pymysql → mysql+aiomysql ✅
+# mysql+pymysql    → mysql+aiomysql    ✅
+# mssql+pyodbc     → mssql+aioodbc     ✅ (v4.3.0+)
 # postgresql+psycopg2 → postgresql+asyncpg ✅
-# sqlite → sqlite+aiosqlite ✅
+# sqlite           → sqlite+aiosqlite  ✅
 ```
 
 ### 迁移指南
@@ -1263,9 +1302,10 @@ class UserRepository(BaseRepository):
 DB__CONNECTION_STRING=mysql+pymysql://user:pass@localhost/test_db
 
 # 框架自动检测并转换
-# mysql+pymysql → mysql+aiomysql ✅
+# mysql+pymysql       → mysql+aiomysql    ✅
+# mssql+pyodbc        → mssql+aioodbc     ✅ (v4.3.0+)
 # postgresql+psycopg2 → postgresql+asyncpg ✅
-# sqlite → sqlite+aiosqlite ✅
+# sqlite              → sqlite+aiosqlite  ✅
 ```
 
 ### Q5: 如何处理复杂查询？

{df_test_framework-4.2.2 → df_test_framework-4.3.1}/docs/guides/message_queue.md

@@ -1,7 +1,7 @@
 # 消息队列使用指南
 
-> **最后更新**: 2026-01-16
-> **适用版本**: v3.9.0+
+> **最后更新**: 2026-04-16
+> **适用版本**: v3.9.0+，v4.3.0+（YAML 环境配置支持）
 > **支持的消息队列**: Kafka + RabbitMQ + RocketMQ
 
 ## 概述
@@ -223,14 +223,35 @@ client.delete_topic("old-topic")
 
 ### 在测试中使用
 
-使用pytest fixtures:
+**Step 1：YAML 环境配置（v4.3.0+，推荐）**
+
+在 `config/environments/test.yaml` 中配置 Kafka 连接参数，框架会自动读取：
+
+```yaml
+# config/environments/test.yaml
+kafka:
+  bootstrap_servers:
+    - broker1.example.com:9092
+    - broker2.example.com:9092
+  # SASL 认证（可选）
+  # security_protocol: SASL_SSL
+  # sasl_mechanism: PLAIN
+  # sasl_username: user
+  # sasl_password 建议放 config/secrets/.env.local: KAFKA__SASL_PASSWORD=...
+```
+
+**Step 2：conftest.py 导入 fixtures**
 
 ```python
 # conftest.py
 from df_test_framework.testing.fixtures.message_queue import (
     kafka_client, kafka_config
 )
+```
 
+**Step 3：在测试中使用**
+
+```python
 # test_kafka.py
 def test_send_and_consume(kafka_client):
     # 发送消息
@@ -250,6 +271,21 @@ def test_send_and_consume(kafka_client):
     assert messages[0] == test_message
 ```
 
+**高级：完全覆盖 kafka_config（自定义行为参数）**
+
+```python
+# conftest.py
+import pytest
+from df_test_framework.capabilities.messengers.queue.kafka import KafkaConfig, KafkaProducerConfig
+
+@pytest.fixture(scope="session")
+def kafka_config():
+    return KafkaConfig(
+        bootstrap_servers=["kafka.example.com:9092"],
+        producer=KafkaProducerConfig(compression_type="gzip"),
+    )
+```
+
 ---
 
 ## 🐰 RabbitMQ客户端
@@ -470,14 +506,32 @@ client.delete_queue("temp-messages")
 
 ### 在测试中使用
 
-使用pytest fixtures:
+**Step 1：YAML 环境配置（v4.3.0+，推荐）**
+
+在 `config/environments/test.yaml` 中配置 RabbitMQ 连接参数，框架会自动读取：
+
+```yaml
+# config/environments/test.yaml
+rabbitmq:
+  host: mq.example.com
+  port: 5672
+  virtual_host: /
+  username: admin
+  # password 建议放 config/secrets/.env.local: RABBITMQ__PASSWORD=...
+```
+
+**Step 2：conftest.py 导入 fixtures**
 
 ```python
 # conftest.py
 from df_test_framework.testing.fixtures.message_queue import (
     rabbitmq_client, rabbitmq_config
 )
+```
+
+**Step 3：在测试中使用**
 
+```python
 # test_rabbitmq.py
 def test_fanout_exchange(rabbitmq_client):
     # 声明fanout exchange和多个队列
@@ -504,6 +558,28 @@ def test_fanout_exchange(rabbitmq_client):
     rabbitmq_client.delete_exchange("broadcast")
 ```
 
+**高级：完全覆盖 rabbitmq_config（自定义 consume/publish 行为参数）**
+
+```python
+# conftest.py
+import pytest
+from pydantic import SecretStr
+from df_test_framework.capabilities.messengers.queue.rabbitmq import (
+    RabbitMQConfig, RabbitMQConnectionConfig, RabbitMQConsumeConfig
+)
+
+@pytest.fixture(scope="session")
+def rabbitmq_config():
+    return RabbitMQConfig(
+        connection=RabbitMQConnectionConfig(
+            host="mq.example.com",
+            username="admin",
+            password=SecretStr("secret"),
+        ),
+        consume=RabbitMQConsumeConfig(prefetch_count=10),
+    )
+```
+
 ---
 
 ## 📋 测试场景示例

df_test_framework-4.3.1/docs/releases/v4.3.0.md

@@ -0,0 +1,179 @@
+# v4.3.0 发布说明
+
+**发布日期**: 2026-04-16
+**类型**: 次版本（Minor Release）
+**主题**: 多数据库方言支持 + 消息队列环境配置
+
+---
+
+## 概述
+
+v4.3.0 解决了两个长期痛点：
+
+1. **多方言数据库接入**：`DatabaseConfig` 新增 `dialect` 字段，MSSQL / PostgreSQL / SQLite 项目无需手写完整连接字符串，框架自动组装。
+2. **消息队列环境切换**：RabbitMQ / Kafka 连接参数现在可写入 YAML 环境配置，`rabbitmq_config` / `kafka_config` fixtures 自动读取，与 `db`、`redis` 的使用模式完全对齐。
+
+**向后兼容**：所有变更均为新增字段/行为，现有配置无需修改。
+
+---
+
+## 新增功能
+
+### 1. DatabaseConfig 多方言支持
+
+**影响文件**: `src/df_test_framework/infrastructure/config/schema.py`
+
+新增 `dialect` 字段，支持四种方言自动组装连接字符串：
+
+| dialect | 同步驱动 | 异步驱动 | 说明 |
+|---------|---------|---------|------|
+| `mysql`（默认） | `mysql+pymysql` | `mysql+aiomysql` | 兼容现有配置，dialect 可省略 |
+| `mssql` | `mssql+pyodbc` | `mssql+aioodbc` | 需安装 ODBC Driver + `database-mssql` 额外依赖 |
+| `postgresql` | `postgresql+psycopg2` | `postgresql+asyncpg` | |
+| `sqlite` | `sqlite` | `sqlite+aiosqlite` | |
+
+**MSSQL 专属字段**:
+- `driver`: ODBC 驱动名，默认 `"ODBC Driver 18 for SQL Server"`
+- `trust_server_certificate`: 默认 `True`，测试环境自签名证书免配置
+
+`resolved_async_connection_string()` 新增 `mssql+pyodbc → mssql+aioodbc` 映射，异步场景同样支持。
+
+**YAML 配置示例**:
+
+```yaml
+# MySQL（默认，dialect 可省略）
+db:
+  host: db.example.com
+  port: 3306
+  name: test_db
+  user: root
+
+# MSSQL
+db:
+  dialect: mssql
+  host: mssql.example.com
+  port: 1433
+  name: test_db
+  user: sa
+  # driver: "ODBC Driver 18 for SQL Server"  # 可选，默认即此值
+  # trust_server_certificate: true            # 默认 true
+
+# PostgreSQL
+db:
+  dialect: postgresql
+  host: pg.example.com
+  port: 5432
+  name: test_db
+  user: postgres
+```
+
+### 2. database-mssql 可选依赖组
+
+**影响文件**: `pyproject.toml`、`cli/templates/project/pyproject_toml.py`
+
+```bash
+uv sync --extra database-mssql
+# 包含: pyodbc>=5.1.0（同步）+ aioodbc>=0.5.0（异步）
+```
+
+系统还需安装 ODBC Driver 17 或 18 for SQL Server。
+
+### 3. RabbitMQSettingsConfig / KafkaSettingsConfig
+
+**影响文件**: `src/df_test_framework/infrastructure/config/schema.py`、`infrastructure/config/__init__.py`
+
+新增两个配置模型，集成进 `FrameworkSettings`（默认 `None`，不使用 MQ 的项目完全透明）：
+
+```python
+class FrameworkSettings(BaseSettings):
+    rabbitmq: RabbitMQSettingsConfig | None = None  # v4.3.0
+    kafka: KafkaSettingsConfig | None = None         # v4.3.0
+```
+
+**RabbitMQSettingsConfig 字段**:
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `host` | `"localhost"` | 服务器地址 |
+| `port` | `5672` | 端口 |
+| `virtual_host` | `"/"` | 虚拟主机 |
+| `username` | `"guest"` | 用户名 |
+| `password` | `None` | 建议通过 `RABBITMQ__PASSWORD` 环境变量注入 |
+| `heartbeat` | `600` | 心跳间隔（秒） |
+| `connection_attempts` | `3` | 最大重试次数 |
+| `retry_delay` | `2` | 重试间隔（秒） |
+
+**KafkaSettingsConfig 字段**:
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `bootstrap_servers` | `["localhost:9092"]` | Broker 地址列表，也接受逗号分隔字符串 |
+| `security_protocol` | `"PLAINTEXT"` | 安全协议 |
+| `sasl_mechanism` | `None` | SASL 机制 |
+| `sasl_username` | `None` | SASL 用户名 |
+| `sasl_password` | `None` | 建议通过 `KAFKA__SASL_PASSWORD` 环境变量注入 |
+
+### 4. message_queue fixtures 环境配置感知
+
+**影响文件**: `src/df_test_framework/testing/fixtures/message_queue.py`
+
+`rabbitmq_config` / `kafka_config` fixtures 新增从 `FrameworkSettings` 读取连接配置的逻辑，优先级如下：
+
+1. conftest.py 中用户自定义的 `rabbitmq_config` / `kafka_config` fixture（完全覆盖）
+2. `config/environments/*.yaml` 的 `rabbitmq:` / `kafka:` 配置段（自动读取）
+3. localhost 默认值（向后兼容）
+
+与 `db_config` / `redis_config` fixtures 的设计模式完全一致。
+
+**YAML 配置示例**:
+
+```yaml
+# config/environments/test.yaml
+rabbitmq:
+  host: mq.test.example.com
+  port: 5672
+  username: admin
+  # password 放 config/secrets/.env.local: RABBITMQ__PASSWORD=...
+
+kafka:
+  bootstrap_servers:
+    - broker1.test.example.com:9092
+  # security_protocol: SASL_PLAINTEXT
+  # sasl_mechanism: PLAIN
+  # sasl_username: user
+  # sasl_password 放 config/secrets/.env.local: KAFKA__SASL_PASSWORD=...
+```
+
+### 5. 脚手架模板更新
+
+**影响文件**: `cli/templates/generators/env_files.py`、`cli/templates/project/enhanced_gitignore.py`
+
+- `config/base.yaml` 模板新增 MSSQL / PostgreSQL 配置示例注释
+- `config/base.yaml` 模板新增 RabbitMQ / Kafka 配置示例注释
+- `.gitignore` 模板新增 `!config/secrets/.env.local.example` 白名单（保留示例文件）
+
+---
+
+## 迁移指南
+
+### 现有 MySQL 项目：无需修改
+
+`dialect` 字段默认为 `None`，框架回退到 MySQL 行为，完全兼容。
+
+### 现有 MQ 测试项目：无需修改
+
+`rabbitmq:` / `kafka:` 字段默认为 `None`，fixtures 回退到 localhost 默认值，行为与 v4.2.x 完全一致。
+
+### 切换到 MSSQL
+
+1. 安装 ODBC Driver（[微软官方文档](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)）
+2. 安装额外依赖：`uv sync --extra database-mssql`
+3. 修改 YAML 配置添加 `dialect: mssql`
+
+---
+
+## 相关文档
+
+- [配置系统使用指南](../guides/config_guide.md) - FrameworkSettings 字段说明
+- [数据库访问指南](../guides/database_guide.md) - 多方言配置示例
+- [消息队列使用指南](../guides/message_queue.md) - YAML 环境配置用法

df_test_framework-4.3.1/docs/releases/v4.3.1.md

@@ -0,0 +1,49 @@
+# v4.3.1 发布说明
+
+**发布日期**: 2026-04-16
+**类型**: 补丁版本（Patch Release）
+**主题**: HTTP 方法 @overload 类型重载
+
+---
+
+## 概述
+
+v4.3.1 为 `BaseAPI` 和 `AsyncBaseAPI` 的所有 HTTP 方法（`get / post / put / delete / patch`）补充了 `@overload` 类型重载，提升 IDE 类型推断精度，无任何运行时行为变更。
+
+**向后兼容**：纯类型签名改进，无 API 变更。
+
+---
+
+## 改进内容
+
+### `@overload` 类型重载 - `BaseAPI` / `AsyncBaseAPI`
+
+**影响文件**:
+- `src/df_test_framework/capabilities/clients/http/rest/httpx/base_api.py`
+- `src/df_test_framework/capabilities/clients/http/rest/httpx/async_base_api.py`
+
+为每个 HTTP 方法新增两组 `@overload`：
+
+| 调用签名 | 返回类型 |
+|---------|---------|
+| `model: type[T]` | `T` |
+| `model: None`（默认） | `dict[str, Any]` |
+
+**效果**：调用方无需手动强制类型转换，IDE/mypy 可直接推断出正确类型。
+
+```python
+# 之前：返回类型为 T | dict[str, Any]，需要手动 cast
+user = api.get("/users/1", model=UserModel)  # 类型: UserModel | dict
+
+# 之后：精准推断
+user = api.get("/users/1", model=UserModel)  # 类型: UserModel
+data = api.get("/users/1")                   # 类型: dict[str, Any]
+```
+
+涵盖方法：`get`、`post`、`put`、`delete`、`patch`（同步 + 异步各 5 个，共 10 个方法）。
+
+---
+
+## 升级指引
+
+直接升级，无需修改任何代码。

{df_test_framework-4.2.2 → df_test_framework-4.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "df-test-framework"
-version = "4.2.2"
+version = "4.3.1"
 description = "基于交互模式的现代化测试自动化框架，支持多种测试场景"
 authors = [{name = "DF QA Team", email = "qa@example.com"}]
 readme = "README_PYPI.md"
@@ -75,6 +75,10 @@ database-async = [
     "asyncpg>=0.29.0",      # PostgreSQL 异步驱动
     "aiosqlite>=0.20.0",    # SQLite 异步驱动
 ]
+database-mssql = [
+    "pyodbc>=5.1.0",       # MSSQL 同步驱动（mssql+pyodbc）
+    "aioodbc>=0.5.0",      # MSSQL 异步驱动（mssql+aioodbc，可选）
+]
 kafka = [
     "confluent-kafka>=2.12.0",  # Kafka客户端 - 最新版本，提供 Windows 预编译 wheel
 ]

{df_test_framework-4.2.2 → df_test_framework-4.3.1}/src/df_test_framework/__init__.py

@@ -1,8 +1,12 @@
 """
-DF 测试自动化框架 v4.2.2
+DF 测试自动化框架 v4.3.1
 
 企业级测试平台架构升级，基于五层架构 + 事件驱动 + 可观测性。
 
+v4.3.1 核心特性 - HTTP 方法 @overload 类型重载:
+- 🔧 `BaseAPI` / `AsyncBaseAPI` 的 get/post/put/delete/patch 方法新增 `@overload`
+- ✅ IDE 精准类型推断：`model=SomeModel` → 返回 `SomeModel`，`model=None` → 返回 `dict[str, Any]`
+
 v4.2.2 核心特性 - 依赖升级 + 脚手架模板修复:
 - 🔧 升级依赖后枚举类统一改用 `StrEnum`（原 `str, Enum` 写法）
 - 🐛 修复脚手架模板中 `{{}}` 残留导致生成文件含错误字典字面量
@@ -156,7 +160,7 @@ v3.18.1 特性:
 - 🔄 Unit of Work 模式支持（v3.7）
 """
 
-__version__ = "4.2.1"
+__version__ = "4.3.1"
 __author__ = "DF QA Team"
 
 # ==============================================================================