# Infomankit 性能测评方案

## 📋 概述

本测评方案针对 **infomankit v0.3.9** 进行全面的性能测试，涵盖 Web 服务、数据库操作、缓存系统、消息队列等核心组件的性能指标。

### 测试目标
- 评估 FastAPI 应用的请求处理能力（QPS、延迟）
- 对比 Tortoise ORM 与 SQLAlchemy 2.0 的性能差异
- 测试 Redis 缓存的命中率和响应时间
- 评估 NATS 消息队列的吞吐量
- 分析系统资源占用（CPU、内存、I/O）
- 提供性能优化建议

### 测试环境要求
- Python 3.11+
- Docker & Docker Compose（用于启动依赖服务）
- 至少 4GB RAM
- 稳定的网络环境

---

## 🎯 测试范围

### 1. Web 服务性能测试
- **HTTP 基准测试**：基础端点（健康检查、监控）
- **并发测试**：模拟不同并发级别（10/50/100/500/1000）
- **响应时间分析**：P50/P95/P99 延迟
- **吞吐量测试**：最大 QPS（每秒请求数）

### 2. 数据库性能测试
- **ORM 对比测试**
  - Tortoise ORM vs SQLAlchemy 2.0
  - CRUD 操作性能（Create/Read/Update/Delete）
  - 批量操作性能（bulk insert/update）
  - 复杂查询性能（JOIN/聚合/分页）
- **连接池性能**
  - 不同连接池大小的影响
  - 连接获取延迟
- **数据库引擎对比**
  - SQLite（本地测试）
  - MySQL（生产环境）
  - PostgreSQL（生产环境）

### 3. 缓存系统测试
- **Redis 性能**
  - 读写延迟
  - 缓存装饰器开销
  - 缓存命中率
  - 不同数据结构的性能（String/Hash/List）
- **内存缓存对比**
  - Redis vs 本地缓存装饰器

### 4. 消息队列测试
- **NATS 性能**
  - 消息发布延迟
  - 消息消费吞吐量
  - 消息路由开销
  - 不同消息大小的影响

### 5. 向量数据库测试（可选）
- **Qdrant 性能**
  - 向量插入速度
  - 相似度搜索延迟
  - 批量操作性能

### 6. 系统资源监控
- CPU 使用率
- 内存占用
- 网络 I/O
- 磁盘 I/O
- GC（垃圾回收）影响

---

## 🛠️ 测试工具

### 主要工具
- **wrk2**: HTTP 基准测试（支持精确 RPS 控制）
- **Locust**: 分布式负载测试和场景模拟
- **pytest-benchmark**: Python 代码基准测试
- **py-spy**: Python 性能分析工具
- **memory_profiler**: 内存分析
- **Prometheus + Grafana**: 实时监控和可视化

### 工具安装
```bash
# HTTP 测试工具
brew install wrk  # macOS
# sudo apt install wrk  # Linux

# Python 测试工具
pip install locust pytest-benchmark py-spy memory-profiler
pip install prometheus-client grafana-client

# Docker 环境
docker-compose up -d  # 启动 MySQL/Redis/NATS/Qdrant
```

---

## 📊 测试指标定义

### 1. 响应时间指标
- **平均延迟（Avg Latency）**: 所有请求的平均响应时间
- **P50 延迟（Median）**: 50% 请求的响应时间
- **P95 延迟**: 95% 请求的响应时间（关注长尾）
- **P99 延迟**: 99% 请求的响应时间
- **最大延迟（Max Latency）**: 最慢请求的响应时间

### 2. 吞吐量指标
- **QPS（Queries Per Second）**: 每秒处理的请求数
- **RPS（Requests Per Second）**: 与 QPS 相同
- **TPS（Transactions Per Second）**: 每秒事务数（用于数据库）

### 3. 资源指标
- **CPU 使用率**: 0-100%
- **内存占用**: MB/GB
- **网络带宽**: Mbps
- **连接数**: 并发连接数

### 4. 成功率指标
- **成功率**: 成功请求占比（目标 > 99.9%）
- **错误率**: 4xx/5xx 错误占比
- **超时率**: 超时请求占比

---

## 🧪 测试场景设计

### 场景 1: 健康检查端点基准测试
**目的**: 评估最简单端点的极限性能
```bash
# 1 分钟，1000 并发，目标 10000 RPS
wrk -t12 -c1000 -d60s -R10000 --latency http://localhost:8000/api/health
```

### 场景 2: CRUD 操作性能测试
**目的**: 对比 Tortoise 和 SQLAlchemy 的 CRUD 性能
- 单条插入 x 10000
- 批量插入 x 1000（每批 100 条）
- 条件查询 x 10000
- 分页查询 x 1000
- 更新操作 x 10000
- 删除操作 x 10000

### 场景 3: 带缓存的 API 测试
**目的**: 测试 Redis 缓存对性能的提升
- 冷启动（无缓存）
- 热数据（100% 缓存命中）
- 混合场景（80% 命中率）

### 场景 4: 复杂业务场景
**目的**: 模拟真实业务负载
- 用户注册 + 登录流程
- 数据查询 + 缓存 + 日志
- 消息发布 + 消费

### 场景 5: 压力测试
**目的**: 找到系统瓶颈
- 逐步增加并发（10/50/100/500/1000/2000）
- 持续时间：每级别 5 分钟
- 记录性能拐点

---

## 📁 目录结构

```
plan/performance/
├── README.md                          # 本文件
├── docker-compose.yml                 # 测试环境依赖服务
├── config/
│   ├── .env.test                      # 测试环境配置
│   └── locust.conf                    # Locust 配置
├── scripts/
│   ├── benchmark_web.sh               # Web 性能测试脚本
│   ├── benchmark_orm.py               # ORM 性能对比脚本
│   ├── benchmark_cache.py             # 缓存性能测试脚本
│   ├── benchmark_mq.py                # 消息队列测试脚本
│   └── monitor.sh                     # 系统监控脚本
├── locustfiles/
│   ├── web_load_test.py               # Web 负载测试
│   ├── crud_load_test.py              # CRUD 负载测试
│   └── complex_scenario.py            # 复杂场景测试
├── results/
│   └── .gitkeep                       # 测试结果存放目录
└── report_template.md                 # 测试报告模板
```

---

## 🚀 快速开始

### 1. 环境准备
```bash
cd plan/performance

# 启动依赖服务
docker-compose up -d

# 安装测试依赖
pip install -e ".[test,full-pro]"

# 配置测试环境变量
cp config/.env.test ../../.env.test
export ENV=test
```

### 2. 运行基准测试
```bash
# Web 基准测试（5 分钟）
./scripts/benchmark_web.sh

# ORM 性能对比
python scripts/benchmark_orm.py

# 缓存性能测试
python scripts/benchmark_cache.py
```

### 3. 运行负载测试
```bash
# 启动测试应用
infoman-serve run main:app

# 运行 Locust（Web UI）
locust -f locustfiles/web_load_test.py --host=http://localhost:8000

# 或命令行模式
locust -f locustfiles/web_load_test.py \
  --host=http://localhost:8000 \
  --users 100 \
  --spawn-rate 10 \
  --run-time 5m \
  --headless
```

### 4. 生成报告
```bash
# 合并测试结果
python scripts/generate_report.py --output results/performance_report.html

# 查看报告
open results/performance_report.html
```

---

## 📈 性能基准（参考值）

以下为预期性能基准（需实际测试验证）：

### Web 服务
| 指标 | 目标值 | 说明 |
|------|--------|------|
| 健康检查 QPS | > 5000 | 无数据库操作 |
| 简单查询 QPS | > 1000 | 单表查询 + 缓存 |
| 复杂查询 QPS | > 100 | 多表 JOIN + 聚合 |
| P95 延迟 | < 100ms | 95% 请求在 100ms 内完成 |
| P99 延迟 | < 500ms | 99% 请求在 500ms 内完成 |

### 数据库（ORM）
| 操作 | Tortoise ORM | SQLAlchemy 2.0 | 说明 |
|------|--------------|----------------|------|
| 单条插入 | ~2ms | ~1.5ms | 预期 SA 快 20-30% |
| 批量插入（100 条） | ~50ms | ~30ms | SA 批量优化更好 |
| 简单查询 | ~1ms | ~0.8ms | SA 编译查询更快 |
| 复杂查询 | ~10ms | ~7ms | SA 查询优化更强 |

### 缓存
| 操作 | 延迟 | 吞吐量 |
|------|------|--------|
| Redis GET | < 1ms | > 10000 ops/s |
| Redis SET | < 2ms | > 8000 ops/s |
| 本地缓存 GET | < 0.1ms | > 100000 ops/s |

### 消息队列（NATS）
| 操作 | 延迟 | 吞吐量 |
|------|------|--------|
| 发布消息 | < 1ms | > 5000 msg/s |
| 消费消息 | < 5ms | > 3000 msg/s |

---

## 🎯 测试通过标准

### 功能测试
- ✅ 所有 API 端点响应正常（HTTP 200）
- ✅ 数据库 CRUD 操作无错误
- ✅ 缓存命中率符合预期
- ✅ 消息队列无消息丢失

### 性能测试
- ✅ QPS 达到预期目标值的 80% 以上
- ✅ P95 延迟低于目标值
- ✅ 错误率 < 0.1%
- ✅ 资源占用合理（CPU < 80%，内存 < 2GB）

### 稳定性测试
- ✅ 持续运行 1 小时无崩溃
- ✅ 内存无明显泄漏（增长 < 10%）
- ✅ 连接池正常回收

---

## 📝 测试报告模板

完整的测试报告应包含：

1. **执行摘要**
   - 测试日期和版本
   - 测试环境描述
   - 主要发现和建议

2. **测试结果**
   - 各场景的性能数据
   - 性能对比图表
   - 瓶颈分析

3. **性能分析**
   - CPU/内存占用分析
   - 热点函数识别（py-spy flamegraph）
   - 数据库查询分析

4. **优化建议**
   - 短期优化（Quick wins）
   - 长期优化（架构改进）
   - 配置调优建议

5. **附录**
   - 完整测试数据
   - 监控截图
   - 日志样例

参考模板：[report_template.md](./report_template.md)

---

## 🔧 常见问题

### Q1: 测试时出现连接超时？
A: 检查 Docker 服务是否正常运行，调整连接池配置。

### Q2: ORM 性能测试结果不稳定？
A: 运行多次取平均值，确保数据库预热（warm-up）。

### Q3: 如何模拟真实用户行为？
A: 使用 Locust 自定义用户行为脚本，添加思考时间（wait_time）。

### Q4: 如何分析性能瓶颈？
A: 使用 py-spy 生成火焰图，结合 Prometheus 监控分析。

---

## 📚 参考资料

- [FastAPI Performance Tips](https://fastapi.tiangolo.com/deployment/concepts/)
- [SQLAlchemy Performance Guide](https://docs.sqlalchemy.org/en/20/faq/performance.html)
- [Locust Documentation](https://docs.locust.io/)
- [wrk Benchmarking Tool](https://github.com/wg/wrk)
- [py-spy Profiler](https://github.com/benfred/py-spy)

---

## 📧 联系方式

如有问题或建议，请联系：
- Email: louishwh@gmail.com
- GitHub Issues: https://github.com/infoman-lib/infoman-pykit/issues

---

**最后更新**: 2026-01-07
**版本**: v1.0.0
**维护者**: Infoman Team
