# JMeter 性能测试方案

## 文件清单

| 文件 | 用途 |
|------|------|
| `billing_perf_test.jmx` | **账单专项测试**（验证本次优化效果，优先用这个） |
| `aigcspace_test_plan.jmx` | 全功能稳定性测试（登录/模型列表/余额/非流式对话） |
| `stress_ramp_test.jmx` | 阶梯压力测试（10→50→100→200 并发，找崩溃点） |
| `run_billing_test.sh` | 账单测试运行脚本 |
| `run_tests.sh` | 全功能测试运行脚本 |
| `user_data.csv` | 测试账号数据（需要手动填写） |

---

## 第一步：准备工作

### 1. 安装 JMeter

从 [jmeter.apache.org](https://jmeter.apache.org/download_jmeter.cgi) 下载 5.6.x，解压后把 `bin/` 加入 PATH。

验证安装：
```bash
jmeter --version
```

### 2. 填写测试账号

编辑 `docs/jmeter/user_data.csv`，把占位符换成真实账号：

```csv
username,password,encrypted
testuser1,明文密码,false
testuser2,明文密码,false
testuser3,明文密码,false
```

**注意**：
- `encrypted=false` 表示密码是明文，后端会直接验证
- 多填几个账号，并发时会轮流使用（CSV 循环读取）
- 账号需要有余额，否则流式对话会返回 402

### 3. 确认接口地址

默认目标地址是 `https://aigc-api.wangxunai.com`。如果要测本地或其他环境，运行时用 `-Jbase_url=` 覆盖。

---

## 第二步：验证优化效果（账单专项测试）

这是本次优化的核心测试，覆盖所有改动点：

| 场景 | 接口 | 验证的优化 |
|------|------|-----------|
| 场景1 | GET /api/billing/records | 14表串行 → 单表查询 |
| 场景2 | GET /api/billing/summary | 20+次聚合 → 4次SQL |
| 场景3 | GET /api/billing/balance | check_balance 减少一次查询 |
| 场景4 | GET /api/billing/consumption-logs | 分页查询效果 |
| 场景5 | POST /api/llm/chat (stream=true) | db连接提前关闭修复 |

### 运行方式

```bash
cd docs/jmeter

# 快速验证（20并发，5分钟）—— 日常验证用这个
bash run_billing_test.sh quick

# 完整测试（50并发，15分钟）—— 正式测试用这个
bash run_billing_test.sh full
```

也可以直接用 JMeter 命令行：

```bash
cd docs/jmeter

# 快速验证
jmeter -n \
  -t billing_perf_test.jmx \
  -Jbase_url=https://aigc-api.wangxunai.com \
  -Jthread_count=20 \
  -Jramp_up=30 \
  -Jduration=300 \
  -l results/billing_quick.jtl \
  -e -o results/billing_quick_report/
```

### 查看报告

```bash
# 打开 HTML 报告（Windows）
start results/billing_quick_report/index.html

# macOS
open results/billing_quick_report/index.html
```

---

## 第三步：优化前后对比测试

这是验证优化效果最直接的方式：

```bash
# 1. 切换到优化前的代码
git stash   # 或 git checkout <优化前的commit>

# 2. 重启后端服务

# 3. 跑一次测试，记录结果目录
bash run_billing_test.sh quick
# 记录：results/billing_quick_report_20250429_XXXXXX/

# 4. 切换回优化后的代码
git stash pop   # 或 git checkout main

# 5. 重启后端服务

# 6. 再跑一次
bash run_billing_test.sh quick
# 记录：results/billing_quick_report_20250429_YYYYYY/

# 7. 对比两次报告
```

查看对比说明：
```bash
bash run_billing_test.sh compare
```

### 重点关注指标

打开 HTML 报告后，在 **Statistics** 页面看这几列：

| 接口 | 优化前预期 | 优化后预期 | 关注列 |
|------|-----------|-----------|--------|
| GET /api/billing/records | P95 > 800ms | P95 < 200ms | 95th pct |
| GET /api/billing/summary | P95 > 500ms | P95 < 150ms | 95th pct |
| GET /api/billing/balance | P95 > 300ms | P95 < 150ms | 95th pct |
| POST /api/llm/chat(stream) | 错误率 > 0 | 错误率 = 0 | Error % |

---

## 第四步：稳定性测试（全功能）

验证系统在持续负载下不会出现内存泄漏、连接池耗尽等问题：

```bash
cd docs/jmeter

# 稳定性测试：20并发，30分钟
bash run_tests.sh stability

# 压力测试：100并发，10分钟
bash run_tests.sh stress

# 阶梯加压：10→50→100→200并发
bash run_tests.sh ramp
```

---

## 常见问题

### Q: 登录一直失败（断言报错）

检查 `user_data.csv` 里的账号密码是否正确，以及 `encrypted` 字段是否设为 `false`。

### Q: 流式对话返回 402

账号余额不足，充值后重试。

### Q: 报告里看不到 P95

JMeter 默认报告包含 P95，在 Statistics 页面的 `95th pct` 列。如果没有，检查 `-e -o` 参数是否正确传入。

### Q: 想在 GUI 模式下调试

```bash
jmeter -t billing_perf_test.jmx
```

在 GUI 里手动点 Run，先确认每个请求都能正常返回，再切命令行模式正式跑。

### Q: 想修改并发数或时长

命令行用 `-J` 参数覆盖：
```bash
jmeter -n -t billing_perf_test.jmx \
  -Jthread_count=50 \
  -Jduration=600 \
  ...
```

或者直接在 GUI 里修改 ThreadGroup 的 `Number of Threads` 和 `Duration`。