# JS-Benchmark 性能测试工具需求文档

## 1. 项目概述

### 1.1 项目目标
创建一个声明式的接口性能测试工具，使用JavaScript配置，基于RxJS实现，提供简单易用的性能测试能力。

### 1.2 技术选型
- **运行时**: Bun
- **语言**: TypeScript
- **核心库**: RxJS (处理异步流和并发控制)
- **HTTP客户端**: Axios
- **命令行工具**: Commander.js

## 2. 功能需求

### 2.1 核心功能

#### 2.1.1 测试配置
- 支持JavaScript配置文件（ES模块）
- 组级配置管理（HTTP配置、执行模式、并发数等）
- 接口级测试配置（请求方法、URL、权重等）
- 权重分配：0-100，总和必须=100

#### 2.1.2 执行模式
- **并行执行**: 组内所有接口同时启动
- **串行执行**: 组内接口按顺序执行
- 支持组间延迟配置
- 通过数组复用实现分阶段测试

#### 2.1.3 测试策略
- **按次数测试**: 指定总请求数
- **按时间测试**: 指定测试时长
- 两种策略互斥，不能同时设置

#### 2.1.4 并发控制
- 组级并发控制
- 接口级并发控制
- Artillery风格：始终保持指定并发数进行中

### 2.2 必要功能

#### 2.2.1 实时监控
- 每个请求都显示进度
- 实时统计更新（成功率、响应时间、每秒请求数）
- 实时错误信息显示

#### 2.2.2 报告生成
- 控制台完整报告
- 分组统计报告
- 性能指标分析（P50、P90、P95、P99）

#### 2.2.3 错误处理
- 超时检测（基于`expectMaxResponseTime`）
- 响应过慢判断
- 错误分类统计
- **策略**: 不恢复，只记录，继续测试

#### 2.2.4 配置验证
- 运行时验证权重总和
- 运行时验证必要参数
- 配置错误时立即停止

### 2.3 可选功能

#### 2.3.1 数据收集
- 请求大小统计
- 响应大小统计
- 详细错误信息记录

#### 2.3.2 性能指标
- 响应时间分布
- 错误率分析
- 吞吐量统计

## 3. 非功能需求

### 3.1 性能要求
- 控制台输出不影响测试性能
- 支持高并发测试（100+并发）
- 内存使用友好，流式处理

### 3.2 易用性
- 一个命令启动：`js-benchmark config.js`
- 默认实时监控和报告生成
- 配置文件简单直观

### 3.3 可扩展性
- 模块化设计
- 函数式编程风格
- 易于添加新的执行模式

## 4. 用户使用场景

### 4.1 配置文件编写
```typescript
// simple-test.js
export default {
  groups: [
    {
      name: "用户接口",
      http: { baseUrl: "https://api.example.com" },
      executionMode: 'parallel',
      concurrent: 10,
      requests: 1000,
      tests: [
        { name: "登录", weight: 60, request: { method: "POST", url: "/auth/login" } },
        { name: "注册", weight: 40, request: { method: "POST", url: "/auth/register" } }
      ]
    }
  ]
};
```

### 4.2 测试启动
```bash
js-benchmark simple-test.js
```

### 4.3 测试过程
- 启动时显示配置摘要
- 运行中实时显示进度和统计
- 完成后显示完整报告

## 5. 技术架构

### 5.1 核心模块
- **配置管理**: 配置文件加载和验证
- **测试引擎**: RxJS流式处理，并发控制
- **请求执行**: HTTP请求发送和结果收集
- **统计计算**: 实时统计和指标计算
- **进度监控**: 实时进度显示和报告生成

### 5.2 数据流
1. 配置文件 → 配置验证
2. 配置 → 请求流生成
3. 请求流 → 并发控制
4. 结果流 → 实时统计
5. 统计结果 → 进度显示和报告

### 5.3 关键算法
- **权重分配**: 两轮分配算法，处理舍入误差
- **并发控制**: RxJS mergeMap + concatMap
- **统计计算**: 流式统计，实时更新

## 6. 输出格式

### 6.1 启动信息
```
🚀 开始性能测试...
📋 测试组: 1个
🎯 总请求数: 1000个
⚡ 并发数: 10个
```

### 6.2 实时进度
```
📊 进度: 1.0% (10/1000)
📊 进度: 2.0% (20/1000)
⚡ 成功率: 100.0%
📈 平均响应时间: 156ms
🚀 每秒请求数: 10.2/s
```

### 6.3 最终报告
```
🎉 测试完成!
⏱️  总耗时: 125s
📈 总请求: 1000
✅ 成功: 985
❌ 失败: 15

📊 用户接口组
   - 登录接口: 600次, 成功率98.3%, 平均156ms
   - 注册接口: 400次, 成功率97.5%, 平均234ms

📊 性能分析
   - P50: 120ms
   - P90: 280ms  
   - P95: 450ms
   - P99: 800ms
```

## 7. 开发优先级

### 7.1 第一阶段（核心功能）
- 基础配置管理
- HTTP请求执行
- 并发控制
- 基础统计

### 7.2 第二阶段（必要功能）
- 实时监控
- 报告生成
- 错误处理
- 配置验证

### 7.3 第三阶段（优化完善）
- 性能优化
- 错误分类
- 指标完善
- 文档完善

## 8. 验收标准

### 8.1 功能验收
- 支持并行和串行执行
- 权重分配准确
- 并发控制有效
- 实时监控正常
- 报告生成完整

### 8.2 性能验收
- 支持100+并发
- 控制台输出不影响性能
- 内存使用合理

### 8.3 易用性验收
- 配置文件简单
- 一个命令启动
- 输出信息清晰
- 错误信息明确