# perf_api_test

**Repository Path**: YunAbove/perf_api_test

## Basic Information

- **Project Name**: perf_api_test
- **Description**: 一个专注于性能测试的API工具库，提供高效、易用的接口测试方案，支持多种测试场景和性能分析，助力开发者快速定位和优化系统性能问题。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DOSS 性能测试框架

基于 Python 的 API 性能测试工具,采用模块化设计,支持快速/基准/压力/边界/稳定性多种测试模式,以及可扩展的接口适配器架构。

## 主要特性

- **多模式测试**:快速测试、基准测试、压力测试(多种负载模型)、边界测试、稳定性测试
- **模块化架构**:核心引擎、接口适配器、配置管理、报告生成相互独立,职责清晰
- **可扩展接口层**:统一 `BaseAdapter` 抽象,支持 HTTP / gRPC / WebSocket 等自定义适配器
- **完整指标体系**:响应时间、成功率、吞吐量、TP50/TP90/TP95/TP99、内存监控、性能趋势与瓶颈识别
- **多格式报告**:Markdown / Word / HTML / PDF 四种格式,支持 DeepSeek AI 辅助分析
- **配置灵活**:支持配置文件、环境变量或 CLI 参数动态调整

## 项目结构

```
perf_api_test/
├── adapters/               # 接口适配层
│   ├── base.py             # BaseAdapter 抽象基类(适配器契约)
│   └── http.py             # HTTP 适配器(GET/POST/PUT/DELETE)
├── config/                 # 配置管理
│   ├── default_config.py   # 默认配置(测试/HTTP/报告/监控/AI/日志/阈值)
│   ├── config_manager.py   # 配置加载、合并、覆盖与健康检查
│   ├── api_config.py       # 被测 API 接口配置(端点/参数/边界值)
│   └── test_config.json    # 测试参数配置(示例)
├── core/                   # 核心引擎
│   ├── test_executor.py    # 测试执行引擎(并发控制 + 任务调度 + 负载模型)
│   ├── data_collector.py   # 数据收集与统计
│   ├── metrics.py          # 性能指标采集(请求 + 系统资源)
│   ├── ai_analyzer.py      # DeepSeek AI 分析
│   ├── resource_monitor.py # 独立资源监控组件
│   ├── error_handler.py    # 错误分类、统计与告警
│   ├── data_manager.py     # 测试数据模板与版本管理
│   ├── user_config.py      # 用户配置与参数化(版本控制/敏感信息保护)
│   └── report_generator.py # 报告生成兼容层(委托 report/ 包)
├── report/                 # 报告子系统
│   ├── compiler.py         # 报告数据编译器(ReportData,消除渲染器重复计算)
│   ├── renderer.py         # 渲染器基类
│   ├── markdown_renderer.py
│   ├── word_renderer.py
│   ├── html_renderer.py
│   └── pdf_renderer.py     # PDF 渲染(HTML 渲染 + weasyprint 转换)
├── utils/                  # 通用工具
│   ├── logger.py           # 日志(文件轮转 + 控制台双通道)
│   ├── data_generator.py   # 测试数据生成器
│   ├── result_analyzer.py  # 结果统计分析
│   └── memory_monitor.py   # 内存监控兼容层
├── tests/                  # 业务测试场景类(TestScenarios,被 CLI 引用,非 pytest 用例)
├── examples/               # 使用示例
├── main.py                 # 主入口(等价 cli.py)
├── cli.py                  # 命令行工具
├── setup.py                # 安装脚本
├── requirements.txt        # 依赖清单
└── pytest.ini              # pytest 配置(testpaths = 根目录测试脚本)
```

## 安装

```bash
pip install -r requirements.txt
```

## 快速开始

### 1. 配置环境变量

```bash
cp .env.example .env
```

### 2. 运行测试

```bash
# 快速测试(5 并发,5 分钟)
python main.py run quick --concurrency 5 --duration 300

# 基准测试(每接口 10 次迭代)
python main.py run baseline

# 压力测试(逐步增加并发,支持负载模型)
python main.py run stress --concurrency-levels 5,10,15,20 --load-model ramp_up

# 边界测试(自动取 api_config.py 中各接口的边界参数)
python main.py run boundary

# 指定接口(注意:--endpoints 为空格分隔的多值参数)
python main.py run quick --endpoints /v2/account/media/listVo /v2/account/business/listVo

# 也可用 CLI 入口,二者等价
python cli.py run quick --concurrency 5 --duration 300
```

### 3. 查看报告

测试完成后,报告与结果文件默认输出到 `reports/` 目录(见下文「报告」)。

## 配置

### 环境变量

敏感信息(API Token、AI 密钥等)**不提交到仓库**,通过 `.env` 文件提供(已 gitignore)。

完整变量清单见 `.env.example`,常用配置:

| 变量 | 必填 | 说明 |
|---|---|---|
| `HTTP_BASE_URL` | 是 | 被测 API 服务地址 |
| `API_TOKEN` / `HTTP_AUTH_TOKEN` | 是 | 接口认证 Token |
| `DEEPSEEK_API_KEY` | 按需 | 报告 AI 分析功能密钥 |
| `DEEPSEEK_BASE_URL` | 否 | DeepSeek API 基础地址(默认 `https://api.deepseek.com/v1`) |
| `SECRET_KEY` | 否 | 加密签名密钥 |
| `TEST_CONCURRENCY` / `TEST_DURATION` | 否 | 默认并发数 / 测试时长(秒) |
| `HTTP_TIMEOUT` / `TEST_TIMEOUT` | 否 | HTTP 超时 / 测试超时(秒) |
| `TEST_ENVIRONMENT` | 否 | 环境名(决定 `.env.<环境>` 与环境特定配置文件) |

> 不配置必填项会导致运行时报错,属预期行为(安全设计:拒绝无凭据运行)。

### 配置优先级

`DEFAULT_CONFIG` < 环境特定配置文件 < `.env.<环境>` < 环境变量 < 显式指定的配置文件,高优先级逐层覆盖低优先级。

### 命令参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--base-url` | API 基础地址 | `https://api.example.com` |
| `--headers` | 请求头(JSON 格式) | `'{"Authorization":"Bearer xxx"}'` |
| `--endpoints` | 接口路径,空格分隔多值 | `/api/a /api/b` |
| `--payloads` | 请求体列表(JSON 格式) | `'{"pageNum":1}'` |
| `--concurrency` | 并发线程数(默认 5) | `5` |
| `--duration` | 测试持续时间,秒(默认 30) | `300` |
| `--iterations` | 基准测试迭代次数(默认 10) | `10` |
| `--concurrency-levels` | 压力测试多级并发,逗号分隔 | `10,20,30` |
| `--load-model` | 负载模型:constant / ramp_up / spike / random | `ramp_up` |
| `--user-behavior` | 用户行为配置(JSON 格式) | `'{"think_time":1}'` |
| `--boundary-params` | 边界参数,分号分隔的 JSON | `'{"page":0};{"page":-1}'` |
| `--report-dir` | 报告输出目录(默认 `reports`) | `reports` |

## 架构

| 模块 | 职责 |
|------|------|
| `adapters/` | 接口适配层:`BaseAdapter` 定义契约,`HTTPAdapter` 实现 HTTP 请求与 Token 失效识别 |
| `config/` | 配置管理:默认配置、接口配置、多源配置加载与合并 |
| `core/` | 核心引擎:测试执行、数据收集、指标采集、AI 分析、资源监控、错误处理、数据管理 |
| `report/` | 报告子系统:数据编译(compiler)与格式渲染(renderer)分离,消除重复计算 |
| `utils/` | 通用工具:日志、数据生成、结果分析、内存监控兼容层 |
| `tests/` | 业务测试场景类(被 CLI 引用) |

核心数据流:`cli.py` → `tests/TestScenarios`(调用 `core/TestExecutor` 并发执行)→ `core/MetricsCollector` 采集指标 → `report/compiler` 编译为 `ReportData` → 各渲染器输出报告。

## 添加新接口

在 `config/api_config.py` 的 `API_CONFIG` 中添加接口配置即可,框架会自动纳入测试:

```python
API_CONFIG = {
    "new_interface": {
        "endpoint": "/v2/path/to/interface",
        "method": "POST",
        "payload": {"key": "value"},
        "boundary_params": [
            {"key": "edge_case_1"},
            {"key": "edge_case_2"}
        ],
        "description": "接口描述"
    }
}
```

## 自定义适配器

继承 `BaseAdapter` 并实现 `send_request`、`get_name`、`get_supported_methods`:

```python
from adapters.base import BaseAdapter

class GRPCAdapter(BaseAdapter):
    def send_request(self, endpoint, data=None, **kwargs):
        # gRPC 请求逻辑
        return {"success": True, "elapsed": 0.1, ...}

    def get_name(self):
        return "gRPC"

    def get_supported_methods(self):
        return ["UNARY", "STREAM"]
```

## 性能指标

| 指标 | 说明 | 单位 |
|------|------|------|
| 总请求数 / 成功率 | 请求总量与成功率 | 个 / % |
| 平均 / 最大 / 最小响应时间 | 响应时间统计 | 秒 |
| TP50 / TP90 / TP95 / TP99 | 分位数响应时间 | 秒 |
| 吞吐量 | 每秒处理请求数 | req/s |
| 状态码分布 | 各 HTTP 状态码统计 | 个 |
| 内存使用 | 系统/进程内存监控与泄漏预警 | MB |
| 性能趋势 | 响应时间随时间变化趋势 | - |
| 瓶颈识别 | 响应时间 / 错误率 / 资源 / 吞吐量阈值告警 | - |

## 报告

报告与原始结果默认输出到 `reports/` 目录(`--report-dir` 可改):

- `test_report_<时间戳>.md` — Markdown 格式(CLI 默认生成)
- `test_report_<时间戳>.docx` — Word 格式(CLI 默认生成)
- HTML / PDF 格式可通过 `ReportGenerator.generate_html_report()` / `generate_pdf_report()` 生成(PDF 需安装 `weasyprint`)
- `test_results_<时间戳>.json` — 原始测试结果

启用 AI 分析需配置 `DEEPSEEK_API_KEY` 环境变量。

## 测试

`tests/` 包提供业务场景类(TestScenarios),真正的测试脚本在仓库根目录,已通过 `pytest.ini` 的 `testpaths` 指向:

```bash
python -m pytest                     # 运行全部测试
python -m pytest test_framework.py -v

python test_system.py                # 冒烟测试(依赖外部服务 httpbin.org,离线环境会失败)
```

## 技术栈

| 技术 | 用途 |
|------|------|
| Python 3.8+ | 开发语言 |
| requests | HTTP 请求 |
| psutil | 系统资源监控 |
| python-docx | Word 报告生成 |
| python-dotenv | 环境变量加载(可选) |
| weasyprint | PDF 报告生成(可选) |
| DeepSeek | AI 结果分析(可选) |

## 注意事项

- `.codegraph/` 和 `.workbuddy/` 是本地工具目录,已加入 `.gitignore`
- 敏感配置(Token、API Key)通过 `.env` 设置,不提交到仓库
- 压力测试建议从低并发逐步增加,避免对目标系统造成影响
- `templates/` 目录由报告生成器自动创建,为保留参数预留,当前未使用模板

## 版本历史

- **v1.0.0**:初始版本,核心测试引擎 + HTTP 适配器 + Markdown/Word 报告
- **v1.1.0**:新增压力测试/边界测试模式;内存监控;数据收集器重构
- **v1.2.0**:报告生成器重构(消除 1000+ 行重复代码);异常处理优化;CodeGraph 集成

## 相关项目

- [DOSS 接口自动化测试框架](https://gitee.com/YunAbove/api_test)
- [智能测试用例生成器](https://gitee.com/YunAbove/ai-agent)