|
|
---
|
|
|
applyTo: "**/Benchmark/**"
|
|
|
---
|
|
|
|
|
|
# 性能测试指令
|
|
|
|
|
|
适用于性能测试、压力测试、基准测试、BenchmarkDotNet 相关任务。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 项目结构
|
|
|
|
|
|
- 基准测试统一放在 `Benchmark/` 项目，按主题分子目录（如 `PacketBenchmarks/`、`CacheBenchmarks/`）
|
|
|
- 入口 `Program.cs` 使用 `BenchmarkSwitcher` 模式，**不要修改**
|
|
|
- TFM 使用最新稳定版，`<LangVersion>latest</LangVersion>`
|
|
|
|
|
|
## 2. 代码规范
|
|
|
|
|
|
遵循主指令全部编码规范（类型名用 `String`/`Int32` 等、file-scoped namespace），另有以下补充：
|
|
|
|
|
|
- **命名空间**：`Benchmark.{主题}Benchmarks`
|
|
|
- **类名**：`{被测类型}Benchmark` 或 `{被测主题}Benchmark`
|
|
|
- **必须标注** `[MemoryDiagnoser]` 和 `[SimpleJob]`（需调整迭代次数时用 `[SimpleJob(iterationCount: N)]`）
|
|
|
- **方法描述**：`[Benchmark(Description = "中文描述")]`，方便报告阅读
|
|
|
- **参数化**：用 `[Params]` 或 `[ParamsSource]` 控制数据规模
|
|
|
- **初始化 / 清理**：分别放 `[GlobalSetup]` 和 `[GlobalCleanup]`
|
|
|
- **分组**：同类测试用 `#region` 分组
|
|
|
- **多线程并发**：动态线程数包含 CPU 核心数，推荐模板：
|
|
|
|
|
|
```csharp
|
|
|
public static IEnumerable<Int32> ThreadCounts
|
|
|
{
|
|
|
get
|
|
|
{
|
|
|
var cores = Environment.ProcessorCount;
|
|
|
var set = new SortedSet<Int32> { 1, 4, 8, 32 };
|
|
|
set.Add(cores);
|
|
|
return set;
|
|
|
}
|
|
|
}
|
|
|
|
|
|
[ParamsSource(nameof(ThreadCounts))]
|
|
|
public Int32 ThreadCount { get; set; }
|
|
|
```
|
|
|
|
|
|
## 3. 运行要求
|
|
|
|
|
|
- 必须以 **Release 模式**运行，获取有代表性的峰值数据
|
|
|
- 运行全部：`dotnet run -c Release`
|
|
|
- 运行指定类：`dotnet run -c Release -- --filter *ClassName*`
|
|
|
- ❌ 禁止在 Debug 模式下采集数据写入报告
|
|
|
|
|
|
## 4. 测试维度
|
|
|
|
|
|
- **并发维度**：单线程 + 多线程（多线程含与当前 CPU 核心数相同的并发数）
|
|
|
- **操作维度**：单一操作 + 批量操作
|
|
|
|
|
|
## 5. 常见错误
|
|
|
|
|
|
- ❌ 在 `[Benchmark]` 方法内做初始化（应放 `[GlobalSetup]`）
|
|
|
- ❌ 忽略返回值导致 JIT 死码消除（确保返回或赋值给字段）
|
|
|
- ❌ 手动 `Stopwatch` 计时（BDN 自动处理）
|
|
|
- ❌ `using` 的 `Dispose` 开销混入测量（仅在测试 Dispose 本身时才包含）
|
|
|
|
|
|
## 6. 报告存放
|
|
|
|
|
|
`Doc/Benchmark/{测试主题}性能测试.md`（UTF-8 无 BOM）
|
|
|
|
|
|
## 7. 报告结构（顺序固定，精简为主）
|
|
|
|
|
|
1. **性能概览**（一句话用途 + 核心结论，3~5 条要点，每条一句话）
|
|
|
2. **测试环境**（CPU / OS / Runtime，代码块 3~4 行即可）
|
|
|
3. **测试结果**（BDN 原始表格，保留 Mean / Error / StdDev / Allocated）
|
|
|
4. **结果分析**（见下方约束）
|
|
|
5. **瓶颈与优化建议**（见第 8 节，仅列有数据支撑的瓶颈）
|
|
|
|
|
|
### 7.1 结果分析约束
|
|
|
|
|
|
结果分析是对 BDN 数据的**提炼**，不是重新排列。遵循以下规则：
|
|
|
|
|
|
- **禁止重复制表**：不要把 BDN 数据换个单位（如 ops/s）再列一张完整表格；如需标注业务指标，在正文中用"XXX 操作约 N M ops/s"一笔带过
|
|
|
- **对比用文字而非新表**：横向/纵向对比直接写结论（"ArrayPacket 构造比 OwnerPacket 快 ~670x，Slice 零分配"），不为每个对比维度单独建表
|
|
|
- **仅在对比维度 ≥3 且差异显著时**才建一张对比表，且最多一张
|
|
|
- **总量控制**：结果分析文字不超过 BDN 原始表格总行数的 1/3
|
|
|
|
|
|
### 7.2 篇幅控制
|
|
|
|
|
|
- 分析 + 瓶颈部分的文字行数 ≤ 数据表格行数（含表头）
|
|
|
- 无需为每个数字都单独解读；读者能从原表看出的趋势不必复述
|
|
|
|
|
|
## 8. 瓶颈与优化建议规范
|
|
|
|
|
|
### 8.1 撰写原则
|
|
|
|
|
|
- **数据驱动**：所有结论必须有 BDN 实测数据支撑，**禁止无数据臆测**，没有 profiler 数据时不编造 ns 级拆解
|
|
|
- **量化表达**：用"快 X 倍"、"省 Y%"、"降 Z B/op"，避免"显著""明显"等模糊词
|
|
|
- **可操作**：指明具体修改位置和方案，不泛泛建议
|
|
|
- **宁少勿凑**：只列真正有影响的瓶颈（通常 1~3 个），不为凑数列 P3 级微小问题
|
|
|
|
|
|
### 8.2 瓶颈表格（唯一模板，合并展示）
|
|
|
|
|
|
用一张表汇总，不再拆分多张表：
|
|
|
|
|
|
```markdown
|
|
|
| 优先级 | 瓶颈 | 现象（实测数据） | 优化方向 | 预期收益 |
|
|
|
|--------|------|----------------|---------|---------|
|
|
|
| P0 | {名称} | {BDN 数据描述} | {方案} | {速度/内存预估} |
|
|
|
| P1 | {名称} | {BDN 数据描述} | {方案} | {速度/内存预估} |
|
|
|
```
|
|
|
|
|
|
- **P0**：影响核心吞吐或 >30% 性能损失，必须优化
|
|
|
- **P1**：影响扩展性或有明显内存压力，建议优化
|
|
|
- **P2**：次要瓶颈，可选优化（仅在确有数据支撑时列出）
|
|
|
- 同级按影响程度降序；无明显瓶颈时写"未发现显著瓶颈"即可
|
|
|
|
|
|
### 8.3 补充说明（可选）
|
|
|
|
|
|
表格之后可对 P0/P1 瓶颈各写 2~3 句补充根因和方案细节，**不要求也不鼓励**对每个瓶颈展开长篇分析。
|