R_D_Demo/WpfNodeTest/.github/instructions/benchmark.instructions.md

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 核心数，推荐模板：

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 瓶颈表格（唯一模板，合并展示）

用一张表汇总，不再拆分多张表：

| 优先级 | 瓶颈 | 现象（实测数据） | 优化方向 | 预期收益 |
|--------|------|----------------|---------|---------|
| P0 | {名称} | {BDN 数据描述} | {方案} | {速度/内存预估} |
| P1 | {名称} | {BDN 数据描述} | {方案} | {速度/内存预估} |

• P0：影响核心吞吐或 >30% 性能损失，必须优化
• P1：影响扩展性或有明显内存压力，建议优化
• P2：次要瓶颈，可选优化（仅在确有数据支撑时列出）
• 同级按影响程度降序；无明显瓶颈时写"未发现显著瓶颈"即可

8.3 补充说明（可选）

表格之后可对 P0/P1 瓶颈各写 2~3 句补充根因和方案细节，不要求也不鼓励对每个瓶颈展开长篇分析。