# 性能基准测试

## 输入要求

1. **目标代码路径**（必填）：被测函数/模块/脚本
2. **性能指标**（必填）：耗时 / 内存 / 吞吐量 / QPS / 启动时间，至少其一
3. **阈值**（可选）：目标上限，如"单次调用 < 200ms"；不提供则仅输出基准数据
4. **对比基线**（可选）：优化前的基准数据，用于 A/B 对比

## 执行流程

### 第一步：识别性能触发面

扫描代码，定位性能关键路径：

- 循环体内重计算（正则编译、字符串拼接、重复 I/O）
- 批量操作（大批次读文件、批量 SQL、批量网络请求）
- 数据结构选择（list vs set vs dict 查重、字符串拼接 vs join）
- 缓存缺失（重复调用同一开销大的函数 / 重复查询同一数据）
- 数据库查询（N+1、缺索引、全表扫描 — 发现后跳转 `mysql-database`）

#### 自动化扫描档位

当用户提供文件或目录路径时，先执行可复现的静态扫描，再进入人工分析；当用户只粘贴代码片段且没有可访问路径时，跳过工具扫描并明确标注"仅基于片段审查"。

| 扫描档位 | 触发条件 | 扫描范围 | 输出要求 |
| - | - | - | - |
| 快速扫描 | 单个文件、单个函数、短代码片段 | 当前文件或片段中的循环、I/O、SQL、缓存 | 输出命中位置和疑似反模式 |
| 深度扫描 | 目录、模块、项目级性能排查 | 入口、循环、数据库访问、网络调用、缓存、异步任务 | 输出扫描摘要、热点候选和后续验证路径 |

推荐扫描模式：

| 扫描项 | 参考模式 | 风险 |
| - | - | - |
| 循环内数据库调用 | `for` / `foreach` / `while` 附近出现 `query` / `select` / `find` / `where` | N+1 查询 |
| 循环内外部请求 | 循环附近出现 `fetch` / `axios` / `requests` / `http` / `RestTemplate` | N+1 API 调用 |
| 同步阻塞 I/O | `readFileSync` / `writeFileSync` / 同步文件读写 / 高并发路径阻塞调用 | 阻塞 I/O |
| 无上限数据拉取 | `.all()` / `findAll()` / `SELECT *` / 无 `LIMIT` 的列表查询 | 内存和响应时间失控 |
| 缓存无界增长 | 全局 Map/dict/Object/静态集合持续写入且无 TTL/容量限制 | 内存泄漏 |
| 索引失效 | `DATE(column)` / `LIKE '%xxx'` / 字段隐式类型转换 | 慢查询 |

扫描结果只能作为嫌疑点；交付结论必须继续通过 benchmark、profile、EXPLAIN、日志或人工复核验证。

#### 分层分析深度

根据问题规模选择分析层级，避免简单问题过度分析，也避免复杂问题只给浅层建议：

| 层级 | 触发条件 | 分析内容 | 输出形态 |
| - | - | - | - |
| L0 轻量分析 | 单条 SQL、单个函数、少于 30 行的小片段 | 直接复杂度、明显 I/O、单点风险 | 简短结论 + 1 到 3 个建议 |
| L1 标准分析 | 多函数、循环 + DB、常规重构、30 到 200 行代码 | 复杂度、I/O、边界条件、数据量影响 | 热点表格 + 修复方案 |
| L2 深度分析 | 多文件、架构级优化、线上瓶颈、超过 200 行或涉及并发 | L1 全部 + 并发、内存、缓存、扩展性、回滚风险 | 分阶段诊断和验证计划 |

#### 硬性性能反模式

| 反模式 | 典型信号 | 严重度 | 最小修复方向 |
| - | - | - | - |
| N+1 查询 | 循环内数据库查询或外部 API 调用 | 严重 | 批量查询、预加载、JOIN、聚合、一次性拉取后内存分组 |
| 同步阻塞 I/O | 高并发请求路径内同步文件、网络或重 CPU 操作 | 严重 | 异步化、后台任务、连接池、队列、流式处理 |
| 内存泄漏风险 | 无界缓存、监听器未清理、静态集合持续增长 | 高 | TTL、容量限制、LRU、生命周期清理 |
| 无上限数据拉取 | 列表查询无分页、无最大 limit、全表拉取 | 高 | 强制分页、游标、批处理、最大 page size |

### 第二步：选择优化策略

识别反模式后，按问题性质选择策略；没有实测基线时只能描述"预期收益"或"假设收益"，不得声称已提升。

| 策略 | 适用场景 | 风险控制 |
| - | - | - |
| 缓存优先 | 高频读取、变更不频繁、可接受短暂不一致 | 明确 TTL、失效时机、穿透/击穿/雪崩防护 |
| 异步处理 | 耗时超过用户等待阈值的非核心副作用 | 明确幂等、重试、死信、失败告警和最终一致性 |
| 索引优化 | WHERE/JOIN/ORDER BY 慢查询 | 必须提供 EXPLAIN，评估写入成本和回滚方案 |

优化建议输出需包含：问题位置、当前路径、方案、预期收益依据、验证命令、回滚方式。

### 第三步：选用测量工具

按语言和场景选择：

| 语言 | 工具 | 适用场景 |
| - | - | - |
| Python | `cProfile` / `timeit` / `pytest-benchmark` | 函数级耗时、逐行热点 |
| Node.js | `console.time` / `benchmark.js` / `clinic` | 火焰图、事件循环延迟 |
| Go | `go test -bench` / `pprof` | CPU/内存 profile |
| Java | JMH | 微基准测试 |
| PHP | `microtime()` / Xdebug profiler | 函数耗时 |

**首选策略**：若项目已有测试框架，优先用其内置 benchmark（如 pytest-benchmark、go test -bench），降低接入成本。

### 第四步：执行测量并采集数据

- 跑 3 次取中位数，标注冷/热启动差异
- 记录环境：CPU 型号/核心数、内存、OS、Python 版本
- 内存测试记录峰值 RSS（`tracemalloc` / `memory_profiler` / `process.memory_info()`）
- 输出原始数据 + 整理后表格

### 第五步：生成瓶颈报告

对超出阈值的热点逐条分析：

- 热点代码位置（文件:行号）
- 当前耗时 / 内存占用
- 根因分析（为什么慢）
- 优化建议（具体方案 + 预期收益）

### 第六步：优化前后对比（如有基线）

| 指标 | 优化前 | 优化后 | 提升 |
| - | - | - | - |
| 耗时 | X ms | Y ms | Z% |
| 内存 | X MB | Y MB | Z% |
| 调用次数 | X | Y | Z% |

### 第七步：记录到项目记忆

性能基准测试完成后，将以下内容沉淀到项目记忆（参见 `project-memory-management.md`）：

- **性能基线数据**：中位数/P95/P99/峰值内存，作为后续回归对比依据
- **热点位置与根因**：文件:行号 + 耗时占比 + 优化建议
- **优化前后对比**：提升幅度和验证证据
- **benchmark 脚本路径**：纳入测试套件持续运行
- **性能陷阱**：本轮发现的性能反模式（如 N+1 查询、O(n²) 循环、不必要的序列化）

## 输出格式

````
## 性能基准测试报告

**目标代码**：[函数/模块名]
**测试环境**：[OS / CPU / 内存 / Python 版本]

## 基准数据

| 指标 | 中位数 | P95 | P99 | 峰值内存 |
|------|--------|-----|-----|---------|
| [指标1] | [值] | [值] | [值] | [值] |

## 热点分析

| 位置 | 耗时占比 | 根因 | 优化建议 | 预期收益 |
|------|---------|------|---------|---------|
| [文件:行号] | X% | [原因] | [方案] | ~Y% |

## 优化前后对比（如有基线）

| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|

## 测试脚本

```[语言]
[可复现的 benchmark 代码]
````

## 质量标准

- 必须跑 3 次以上取中位数，单次结果不可作为结论
- 必须标注测试环境（硬件 + 软件版本），否则数据不可复现
- 热点分析必须有具体代码位置（文件:行号），不得只说"某个循环慢"
- 优化建议必须给出可操作的方案，不得只说"优化一下"
- 不得在无基线对比的情况下声称"显著提升"

## 失败回退机制

| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |
|------|---------|---------|---------|------------------|
| 第一步：识别触发面 | 代码量过大无法定位关键路径 | 按函数分批，标注"仅部分路径" | 1 | 缩小范围到用户指定的入口函数 |
| 第二步：选择优化策略 | 无实测基线或策略不明 | 先跑基线，标注"预期收益/假设收益" | 1 | 输出候选策略与权衡，由用户决策 |
| 第三步：选用测量工具 | 工具不可用或安装失败 | 降级到语言内置 time 打点 | 1 | 输出手动计时方案，标注精度受限 |
| 第四步：执行测量 | 环境差异导致数据波动 > 20% | 增加采样次数到 7 次，输出方差 | 2 | 标注"环境不稳定"，以区间范围呈现 |
| 第五步：生成瓶颈报告 | 热点根因无法在静态分析中确定 | 输出热点位置 + 耗时占比，标注"根因待确认" | 1 | 建议用户补充 profiler 火焰图 |
| 第六步：优化前后对比 | 无优化前基线 | 仅输出当前基准，标注"无基线对比" | — | 正常输出 |
| 第七步：记录到项目记忆 | 项目记忆系统不可用 | 输出性能基线数据到本地文件 | 1 | 标注"基线未沉淀"，提示用户手动保存 |

## 关联 reference

- **code-review**（代码审查）— 发现潜在性能问题后，用本技能定量验证
- **code-generation**（代码生成）— 生成代码后可用本技能跑基准测试验证性能
- **refactoring**（重构建议）— 重构前跑基线，重构后跑对比，量化重构收益
- **mysql-database**（MySQL数据库）— SQL 性能问题跳转 `mysql-database` 做 EXPLAIN / 索引分析
- **test-generation**（测试用例生成）— benchmark 脚本应纳入测试套件持续跑基准
- **software-project**（软件项目总控）— 软件项目上线前性能验收，提交基准数据作为交付物
- **website-project**（网站项目总控）— 网站项目的性能指标、部署前压测和上线后监控基准
- **project-memory-management**（项目记忆管理）— 记录性能基线数据，作为后续回归对比依据