# APIForge **Repository Path**: aidenhgl/apiforge ## Basic Information - **Project Name**: APIForge - **Description**: 一个全面的API测试框架，支持REST和gRPC API测试以及数据mock，提供强大的测试功能和灵活的扩展机制 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-17 - **Last Updated**: 2025-12-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # APIForge APIForge是一个全面的API测试框架，支持REST和gRPC API测试，提供强大的测试功能和灵活的扩展机制。 ## SDK 特性 - ✅ **流式 API** - 直观的链式调用语法 - ✅ **异步支持** - 高性能并发测试 - ✅ **批量测试** - 并行执行多个测试 - ✅ **完整类型提示** - 更好的 IDE 支持 - ✅ **向后兼容** - 与现有 CLI 完全兼容 ### 💡 为什么选择 APIForge SDK？ - 🔄 **双重接口**：既支持 CLI 命令行，也提供编程式 SDK - 🚀 **现代 Python**：流式 API、异步支持、完整类型提示 - 🔧 **易于集成**：完美集成到现有 Python 项目和 CI/CD 流程 - 🛡️ **生产就绪**：内置错误处理、重试机制、性能优化 - 📊 **完整报告**：支持多种格式的详细测试报告 ### 🚀 快速开始 ```bash # 安装 SDK pip install apiforge ``` ```python # 基础测试 from apiforge import APITestSDK sdk = APITestSDK() result = sdk.quick_test("GET", "https://jsonplaceholder.typicode.com/users") print(f"测试状态: {result.status}") # 流式 API - 构建复杂测试 result = (sdk.test() .get("/users/1") .expect_status(200) .expect_json_path("$.id", 1) .run()) # 批量测试 requests = [ {"method": "GET", "url": "/users"}, {"method": "GET", "url": "/posts"} ] results = sdk.batch_test(requests) stats = sdk.get_statistics(results) print(f"通过率: {stats['pass_rate']:.1f}%") # 异步高性能测试 async with AsyncAPITestSDK() as async_sdk: results = await async_sdk.abatch_test(requests, max_workers=10) ``` ### 📚 完整文档 - 📖 [SDK 使用指南](SDK_README.md) - 快速上手 - 🔧 [API 参考文档](docs/api_reference.md) - 完整 API 参考 - 💡 [最佳实践](docs/best_practices.md) - 专业技巧 - ❓ [常见问题](docs/faq.md) - 问题解答 - 🧪 [Mock 数据生成](docs/mock_data.md) - 仅生成数据/文件（Mocker） - 🚀 [高级示例](examples/advanced_examples.py) - 实战案例 --- ## 🎯 SDK 核心功能 ### 🔄 双重接口设计 APIForge 提供了 CLI 和 SDK 两种使用方式，满足不同场景需求： ```bash # CLI 方式 - 适合快速测试和 CI/CD api-test run --test-case user_api.yaml # SDK 方式 - 适合编程集成和复杂逻辑 from apiforge import APITestSDK sdk = APITestSDK() result = sdk.run_test_case("user_api.yaml") ``` ### 🌟 主要功能对比 | 功能 | CLI | SDK | | ---------- | --- | --- | | 快速测试 | ✅ | ✅ | | 流式 API | ❌ | ✅ | | 异步支持 | ❌ | ✅ | | 编程集成 | ❌ | ✅ | | 自定义逻辑 | ❌ | ✅ | | CI/CD 集成 | ✅ | ✅ | | 配置管理 | ✅ | ✅ | | 报告生成 | ✅ | ✅ | ### 💼 典型使用场景 #### 1. 单元测试集成 ```python import unittest from apiforge import APITestSDK class APITestCase(unittest.TestCase): def setUp(self): self.sdk = APITestSDK().with_base_url("https://api.example.com") def test_user_api(self): result = (self.sdk.test() .get("/users/1") .expect_status(200) .run()) self.assertEqual(result.status, "passed") ``` #### 2. 性能测试 ```python async def load_test(): async with AsyncAPITestSDK() as sdk: # 1000 个并发请求 requests = [{"method": "GET", "url": "/api/data"}] * 1000 results = await sdk.abatch_test(requests, max_workers=50) stats = sdk.get_statistics(results) print(f"平均响应时间: {stats['avg_execution_time']:.2f}ms") print(f"成功率: {stats['pass_rate']:.1f}%") ``` #### 3. 数据驱动测试 ```python def test_data_driven(): sdk = APITestSDK() # 测试数据 test_data = [ {"user_id": 1, "expected_name": "Leanne Graham"}, {"user_id": 2, "expected_name": "Ervin Howell"} ] for data in test_data: result = (sdk.test() .get(f"/users/{data['user_id']}") .expect_status(200) .expect_json_path("$.name", data['expected_name']) .run()) assert result.status == "passed" ``` --- ## 项目简介 APIForge旨在简化API测试流程，提高测试效率和质量。它提供了一套完整的工具链，从测试用例编写、执行到报告生成，帮助开发者和测试人员快速构建和运行API测试。 ### 主要用途 - 自动化REST API测试 - gRPC API测试，支持所有流类型 - API功能验证和回归测试 - 性能测试和负载测试 - API文档验证 ### 设计理念 - **模块化设计**：核心功能与扩展功能分离，便于维护和扩展 - **易扩展性**：支持插件系统，允许自定义功能 - **多协议支持**：同时支持REST和gRPC协议 - **强大的报告功能**：提供详细的测试报告和可视化 - **并行执行**：支持多线程和分布式测试运行 ## 主要特性 - **RESTful API测试**：完整支持HTTP方法（GET, POST, PUT, DELETE等） - **gRPC测试**：支持所有gRPC流类型（单请求-单响应、客户端流、服务器流、双向流） - **DataWeaver Mock数据引擎集成**：内置强大的数据生成和管理功能 - **可扩展插件系统**：支持自定义插件开发和安装 - **多种认证机制**：支持API密钥、OAuth2.0、JWT、基本认证等 - **全面的报告功能**：支持HTML、JSON、XML等多种报告格式 - **并行测试执行**：提高测试效率，节省时间 - **灵活的配置管理**：支持环境变量、配置文件、命令行参数 - **断言库**：内置丰富的断言方法，支持JSON Schema验证 - **CI/CD集成**：易于与持续集成/持续部署系统集成 ## 安装指南 ### 系统要求 - Python 3.8+ - pip 20.0+（推荐） - 支持的操作系统：Windows, macOS, Linux ### 安装方式 #### 使用pip安装 ```bash pip install apiforge ``` #### 从源码安装 ```bash # 克隆仓库 git clone https://github.com/your-org/api-test-framework.git cd api-test-framework # 安装依赖 pip install -r requirements/base.txt # 安装开发依赖（可选） pip install -r requirements/dev.txt # 安装框架 pip install -e . ``` ### 依赖管理 APIForge使用分层依赖管理： - `requirements/base.txt`：核心依赖 - `requirements/dev.txt`：开发依赖 - `requirements/docs.txt`：文档依赖 ## 快速开始 ### 基本配置 创建一个简单的配置文件 `config.yaml`： ```yaml environments: default: base_url: "https://api.example.com" headers: Content-Type: "application/json" auth: type: "api_key" api_key: "your-api-key" header_name: "X-API-Key" ``` ### 编写第一个测试用例 创建测试用例文件 `tests/test_example.py`： ```python from api_forge import TestCase, TestSuite class TestExampleAPI(TestCase): def test_get_users(self): """测试获取用户列表""" response = self.client.get("/users") self.assertStatus(response, 200) self.assertJsonSchema(response, "user_list_schema.json") def test_create_user(self): """测试创建新用户""" payload = { "name": "Test User", "email": "test@example.com" } response = self.client.post("/users", json=payload) self.assertStatus(response, 201) self.assertJsonKey(response, "id") # 创建测试套件 test_suite = TestSuite("Example API Tests") test_suite.add_test_case(TestExampleAPI) ``` ### 运行测试 ```bash # 运行所有测试 api-test run # 运行特定测试套件 api-test run --suite "Example API Tests" # 运行特定测试用例 api-test run --test "TestExampleAPI.test_get_users" # 指定配置文件 api-test run --config config.yaml ``` ### 查看报告 测试运行完成后，报告将生成在 `reports` 目录中。你可以通过浏览器打开 HTML 报告： ```bash open reports/latest/report.html ``` ## 核心概念 ### 测试用例（TestCase） 测试用例是APIForge的基本测试单元，代表单个测试场景。每个测试用例类继承自 `TestCase`，并包含多个测试方法。 ### 测试套件（TestSuite） 测试套件是测试用例的集合，用于组织和管理相关的测试用例。一个测试套件可以包含多个测试用例类。 ### 测试运行器（TestRunner） 测试运行器负责执行测试用例，管理测试执行流程，并收集测试结果。 ### 配置管理（ConfigManager） 配置管理器负责加载和管理测试配置，支持多种配置源和环境切换。 ### 报告生成器（ReportGenerator） 报告生成器负责将测试结果转换为可读的报告，支持多种报告格式。 ## 项目架构 APIForge采用模块化、分层架构设计，具有良好的扩展性和灵活性。框架核心专注于提供基础能力，功能扩展通过插件系统实现，支持REST和gRPC等多种协议。 ### 架构概览 APIForge采用模块化架构设计，主要分为两个独立但协作的核心模块： 1. **测试框架模块** (`test_framework/`)：专注于API测试执行 - 核心测试能力：配置管理、插件管理、测试执行、报告生成 - 协议处理：REST和gRPC协议支持 - 测试插件：验证器、断言等测试相关功能 - 对外接口：`APITester`类提供测试框架API 2. **Mock数据引擎模块** (`mock_engine/`)：专注于数据生成 - 数据生成器：文本、图像、音频、视频等多种类型 - 生成策略：多种数据生成策略和算法 - Mock工具：数据验证、格式化等辅助工具 - 对外接口：通过 `Mocker`类提供Mock数据API 3. **统一对外层** (`api_forge/`)：提供统一的用户接口 - 测试API：`from api_forge import APITester` - Mock API：`from api_forge import Mocker` - SDK接口：完整的Python SDK ### 核心组件 #### APITestFramework（主框架） `APITestFramework` 是框架的核心协调者，负责初始化和管理所有组件，提供统一的测试执行入口。 **主要功能**： - 初始化框架组件 - 加载和管理配置 - 协调测试执行流程 - 生成测试报告 - 管理插件生命周期 **代码位置**：`src/test_framework/core/framework.py` #### ConfigManager（配置管理） `ConfigManager` 负责加载、解析和管理测试配置，支持多种配置源和环境切换。 **主要功能**： - 加载配置文件（YAML/JSON） - 支持环境变量覆盖 - 管理多环境配置 - 配置验证和合并 **代码位置**：`src/test_framework/core/config_manager.py` #### PluginManager（插件管理） `PluginManager` 负责插件的加载、初始化和管理，提供插件扩展机制。 **主要功能**： - 加载内置和第三方插件 - 插件生命周期管理 - 提供插件调用接口 - 支持插件优先级配置 **代码位置**：`src/test_framework/core/plugin_manager.py` #### TestRunner（测试执行） `TestRunner` 负责执行测试用例，管理测试执行流程，支持顺序和并行执行。 **主要功能**： - 测试用例执行 - 支持顺序和并行执行 - 测试超时和重试机制 - 执行结果收集 **代码位置**：`src/test_framework/core/test_runner.py` #### ReportGenerator（报告生成） `ReportGenerator` 负责将测试结果转换为各种格式的报告。 **主要功能**： - 支持HTML、JSON、XML等多种报告格式 - 测试结果统计和分析 - 报告模板管理 - 报告输出和存储 **代码位置**：`src/test_framework/core/report_generator.py` #### MockEngine（Mock数据引擎） `MockEngine` 是内置的Mock数据生成引擎，提供各种类型的测试数据生成能力。 **主要功能**： - 支持文本、图像、音频、视频等多种数据类型 - 提供多种数据生成策略 - 支持批量异步数据生成 - 内置数据验证和格式化 **代码位置**：`src/mock_engine/mock_engine.py` ### 模块关系 APIForge采用双模块架构，测试框架和Mock引擎独立但协作： ``` ┌─────────────────┐ │ api_forge/ │ │ (统一对外接口) │ └─────────┬───────┘ │ ┌─────────┴───────┐ │ │ ┌───────▼────────┐ ┌──────▼──────────┐ │ test_framework/ │ │ mock_engine/ │ │ (测试框架模块) │ │ (Mock数据引擎) │ └─────────────────┘ └─────────────────┘ │ │ ┌───────────┼───────────┐ │ │ │ │ │ ┌───────▼────┐ ┌───▼────┐ ┌───▼────┐ │ │ConfigManager│ │Plugin │ │Test │ │ │ │ │Manager │ │Runner │ │ └─────────────┘ └────────┘ └────────┘ │ │ │ │ │ └───────────┼───────────┘ │ │ │ ┌───────▼───────┐ │ │ ReportGenerator│ │ └─────────────────┘ │ │ ┌─────────────▼──────────┐ │ MockEngine │ │ (数据生成核心) │ └─────────────────────────┘ ``` ### 数据流 #### 测试执行数据流 1. 用户编写测试用例和测试套件 2. 框架加载配置和插件 3. 测试运行器执行测试用例 4. 收集测试结果 5. 报告生成器生成报告 6. 输出报告到指定位置 #### 配置数据流 1. 加载基础配置文件 2. 应用环境变量覆盖 3. 加载插件配置 4. 合并和验证配置 5. 分发配置到各个组件 #### 报告生成数据流 1. 收集测试结果数据 2. 解析和统计结果 3. 应用报告模板 4. 生成指定格式的报告 5. 输出报告文件 ### 代码结构 APIForge采用清晰的模块化代码结构，便于维护和扩展： ``` src/ ├── __init__.py # 框架入口和导出 ├── cli/ # 命令行接口 │ └── main.py # CLI主程序 ├── test_framework/ # 测试框架模块 │ ├── core/ # 测试核心组件 │ │ ├── config_manager.py # 配置管理 │ │ ├── data_manager.py # 数据管理 │ │ ├── framework.py # 主框架 │ │ ├── plugin_manager.py # 插件管理 │ │ ├── report_generator.py # 报告生成 │ │ └── test_runner.py # 测试执行 │ ├── models/ # 测试数据模型 │ │ ├── test_case.py # 测试用例模型 │ │ ├── test_result.py # 测试结果模型 │ │ ├── test_suite.py # 测试套件模型 │ │ └── validation_result.py # 验证结果模型 │ ├── protocols/ # 协议处理 │ │ ├── grpc_handler.py # gRPC协议处理 │ │ └── rest_handler.py # REST协议处理 │ ├── plugins/ # 测试插件 │ │ └── validators/ # 验证器插件 │ └── logger.py # 日志工具 ├── mock_engine/ # Mock数据引擎模块 │ ├── mock_engine.py # 主引擎 │ ├── core/ # Mock核心 │ │ ├── base.py # 基础类 │ │ └── manager.py # 管理器 │ ├── generators/ # 数据生成器 │ │ ├── text/ # 文本生成 │ │ ├── image/ # 图像生成 │ │ ├── audio/ # 音频生成 │ │ └── video/ # 视频生成 │ ├── strategies/ # 生成策略 │ └── utils/ # Mock工具 └── sdk/ # Python SDK ├── client.py # 同步客户端 ├── async_client.py # 异步客户端 ├── builders.py # 测试构建器 ├── exceptions.py # 异常定义 └── utils.py # SDK工具 ``` ### 扩展机制 #### 插件系统设计 APIForge的插件系统采用基于接口的设计，支持多种类型的插件： - **数据生成插件**：如DataWeaver，用于生成测试数据 - **断言插件**：提供各种断言方法 - **报告插件**：支持不同格式的报告生成 - **协议插件**：支持扩展新的协议处理 - **认证插件**：提供各种认证机制 #### 协议扩展机制 框架支持通过插件扩展新的协议处理，只需实现协议处理接口： ```python class ProtocolHandler: def validate_test_case(self, test_case): # 验证测试用例 pass def execute_test(self, test_case): # 执行测试 pass ``` #### 自定义报告生成 用户可以通过实现报告生成器接口，扩展新的报告格式： ```python class CustomReporter: def generate_report(self, results, format, output_path): # 生成自定义格式报告 pass ``` ## 使用示例 ### REST API测试示例 ```python from api_forge import TestCase, TestSuite class TestRESTAPI(TestCase): def test_get_resource(self): """测试获取单个资源""" response = self.client.get("/resources/123") self.assertStatus(response, 200) self.assertJsonKey(response, "name") self.assertJsonValue(response, "status", "active") def test_update_resource(self): """测试更新资源""" payload = { "name": "Updated Resource", "status": "inactive" } response = self.client.put("/resources/123", json=payload) self.assertStatus(response, 200) self.assertJsonValue(response, "name", "Updated Resource") # 创建并运行测试套件 suite = TestSuite("REST API Tests") suite.add_test_case(TestRESTAPI) ``` ### 仅生成 Mock 数据（不运行测试） 当你只想获取 Mock 数据（例如枚举值），而不想执行 HTTP/gRPC 请求与报告生成时，可以使用 `Mocker`（属于 `api_forge` SDK 的一部分）： ```python from api_forge import Mocker # 1) 枚举：随机从 choices 中取值 with Mocker(strict=True) as mocker: values = mocker.enum(["small", "medium", "large"], count=10) print(values[:3]) # 2) 自定义 schema：直接生成并返回 Python 数据 schema = {"type": "enum", "enum": ["A", "B", "C"]} values = Mocker(strict=True).generate(schema, count=5) # 3) 文本落盘：写入 .txt（每行一个值） texts = Mocker(strict=True).generate({"type": "string"}, count=10, save_path="out/texts.txt") # 4) 多媒体：生成文件并返回文件信息（文件落盘到 output_dir） schema = {"type": "image", "strategy": "placeholder", "params": {"width": 800, "height": 600}} files = Mocker(strict=True, output_dir="./test_data").generate(schema, count=2) print(files[0]["file_path"]) ``` 说明： - `output_dir`：用于图片/音频/视频等“文件型 Mock”生成的落盘目录（默认 `./test_data`）。 - `save_path`：把生成结果导出为文件（支持 `.jsonl/.json/.yaml/.txt`，按后缀自动选择）。 - `strict=True`：任何生成/保存错误都会抛异常（强制失败）。 - 对多媒体通常不需要 `save_path`；文件本体会在 `output_dir` 下生成（如 `./test_data/image/`）。 ### gRPC测试示例 ```python from api_forge import TestCase, TestSuite from proto import helloworld_pb2, helloworld_pb2_grpc class TestGRPCAPI(TestCase): def test_grpc_hello_world(self): """测试gRPC HelloWorld服务""" # 初始化gRPC客户端 stub = helloworld_pb2_grpc.GreeterStub(self.grpc_channel) # 发送请求 response = stub.SayHello(helloworld_pb2.HelloRequest(name="World")) # 断言结果 self.assertEqual(response.message, "Hello, World!") # 创建并运行测试套件 suite = TestSuite("gRPC API Tests") suite.add_test_case(TestGRPCAPI) ``` ### 高级功能示例 ```python from api_forge import TestCase, TestSuite class TestAdvancedFeatures(TestCase): def test_with_data_driven(self): """数据驱动测试示例""" test_data = [ ("user1", 200), ("user2", 200), ("invalid_user", 404) ] for username, expected_status in test_data: with self.subTest(username=username): response = self.client.get(f"/users/{username}") self.assertStatus(response, expected_status) def test_with_setup_teardown(self): """测试前置和后置操作""" # 测试前置操作在setUp方法中实现 # 测试后置操作在tearDown方法中实现 response = self.client.get("/resources") self.assertStatus(response, 200) # 创建并运行测试套件 suite = TestSuite("Advanced Features Tests") suite.add_test_case(TestAdvancedFeatures) ``` ## 配置说明 ### 配置文件格式 APIForge支持YAML和JSON格式的配置文件。默认配置文件名为 `config.yaml`，位于项目根目录。 ### 环境配置 ```yaml environments: dev: base_url: "https://dev-api.example.com" headers: Content-Type: "application/json" prod: base_url: "https://api.example.com" headers: Content-Type: "application/json" X-Environment: "production" ``` ### 认证配置 ```yaml auth: type: "oauth2" grant_type: "client_credentials" client_id: "your-client-id" client_secret: "your-client-secret" token_url: "https://auth.example.com/token" scope: "read write" ``` ### gRPC配置 ```yaml grpc: host: "grpc.example.com" port: 50051 secure: true ca_cert: "path/to/ca.crt" client_cert: "path/to/client.crt" client_key: "path/to/client.key" ``` ## 插件系统 ### 内置插件 - **assertions**：提供丰富的断言方法 - **reporters**：提供多种报告格式 - **dataweaver**：集成DataWeaver数据引擎 - **auth**：提供多种认证机制 ### 开发自定义插件 ```python from api_forge import Plugin class CustomPlugin(Plugin): def __init__(self): super().__init__(name="custom", version="1.0.0") def on_test_start(self, test_case): """测试开始时执行""" self.logger.info(f"Starting test: {test_case.name}") def on_test_end(self, test_case, result): """测试结束时执行""" self.logger.info(f"Test {test_case.name} completed with result: {result.status}") # 注册插件 plugin_manager.register_plugin(CustomPlugin()) ``` ### 插件安装与管理 ```bash # 安装插件 api-test plugin install plugin-name # 列出已安装插件 api-test plugin list # 卸载插件 api-test plugin uninstall plugin-name ``` ## 报告生成 ### 报告类型 - **HTML报告**：交互式HTML报告，包含测试结果、统计信息、请求/响应详情 - **JSON报告**：结构化JSON格式，便于后续处理和分析 - **XML报告**：JUnit兼容的XML格式，便于CI/CD系统集成 ### 报告配置 ```yaml report: format: "html" # html, json, xml output_dir: "reports" generate_summary: true include_request: true include_response: true include_headers: true ``` ### 报告查看 HTML报告可以直接在浏览器中打开，包含丰富的交互功能： - 测试结果统计 - 测试用例详情 - 请求/响应查看 - 测试时间线 - 失败原因分析 ## 贡献指南 ### 开发环境设置 1. 克隆仓库： ```bash git clone https://github.com/your-org/api-test-framework.git cd api-test-framework ``` 2. 创建虚拟环境： ```bash python -m venv venv source venv/bin/activate # macOS/Linux # 或 venv\Scripts\activate # Windows ``` 3. 安装开发依赖： ```bash pip install -r requirements/dev.txt ``` 4. 安装pre-commit钩子： ```bash pre-commit install ``` ### 代码风格 - 遵循PEP 8编码规范 - 使用black进行代码格式化 - 使用flake8进行代码检查 - 使用mypy进行类型检查 ### 测试要求 - 所有新功能必须包含单元测试 - 测试覆盖率要求不低于80% - 确保所有现有测试通过 ## 许可证信息 APIForge采用MIT许可证，详情请见LICENSE文件。 ### 免责声明 本软件按"原样"提供，不附带任何明示或暗示的保证，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对因使用本软件而产生的任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权诉讼或其他诉讼中。 ## 致谢 感谢所有为APIForge项目做出贡献的开发者和测试人员！ --- **APIForge** - 让API测试更简单、更高效！