nodejs-performance

Node.js 性能优化

使用此工作流，将 Node.js 性能／资源调查转化为安全、易于审查的 PR。

目标

• 优先缩短执行时间：在不改变预期行为的前提下，降低 p50/p95/p99 延迟并提高吞吐量。
• 在有助于缩短执行时间的前提下，降低 CPU、内存、事件循环延迟、I/O 压力或锁竞争。
• 提交小型、独立且效果可衡量的改动。

操作规则

• 每个 PR 只处理一项优化。
• 始终优先选择预期影响最大的任务。
• 更改之前，先确认并尊重有意为之的行为。
• 在高频路径中优先采用低风险改动。
• 优先处理请求／作业执行路径，而非启动／引导阶段的微优化，除非启动过程在大规模场景下属于关键路径。
• 提供证据：针对性测试和优化前后的基准测试。

影响优先的选择方式

编码之前，使用以下公式为候选项排序：

priority = (frequency x blast_radius x expected_gain) / (risk x effort)

每个因素按 1-5 评分：

• frequency：该路径在生产环境中的运行频率。
• blast_radius：受影响的请求／作业／用户数量。
• expected_gain：预计的延迟／资源改善幅度。
• risk：行为回归的概率。
• effort：工程投入时间和改动范围。

选择排名最高的候选项，然后通过基线测量进行验证。

如果两个候选项的得分相近，选择端到端执行时间影响更明确的那个。

优先优化的目标

从每个请求／作业／任务都会运行的代码入手：

• 请求／作业包装器和中间件。
• 重试／超时／断路器代码。
• 连接池（DB/Redis/HTTP）和套接字复用。
• 流／管道转换和缓冲。
• 序列化／反序列化热点路径（JSON、解析器、架构验证）。
• 队列消费者、调度器和工作进程分派。
• 事件监听器的注册／移除生命周期及清理逻辑。

除非生产环境性能分析结果表明有充分理由，否则降低以下内容的优先级：

• 一次性启动／引导代码。
• 极少使用的管理／调试专用流程。
• 不在稳态关键路径上的拆卸流程。

常见的热点路径问题

• 每次调用都重新计算不变值。
• 反复解析代码／AST。
• 多个异步查询返回相同的值。
• 常见解析场景中，每次调用都分配开销较大的对象。
• 在拆卸／关闭／释放流程中进行不必要的等待。
• 对占主导地位的输入形态缺少快速路径。
• 依赖项降级时，重试没有上限或出现重试风暴。
• 并发过高，导致内存激增或下游过载。
• 即使日志／遥测／指标功能已禁用，仍执行相关格式化工作。

执行工作流

1. 选择一个候选项

• 对候选项排序，并选择优先级最高的项。
• 用一句话说明问题。
• 说明预期影响（CPU、延迟、内存、事件循环延迟、I/O、竞争）。

2. 证明它是热点

• 添加有针对性的微基准或场景基准。
• 编辑前记录基线数据。
• 如果目标是缩短执行时间，优先选择包含真实请求／任务流程的场景基准。
• 对于资源问题，记录进程指标（rss、heap、FD 数量、事件循环延迟）。

3. 设计最小化修复方案

• 保持默认行为兼容。
• 为边缘情况添加回退路径。
• 避免在同一个 PR 中进行大范围重构。

4. 实施

• 尽可能用最小补丁消除重复工作。
• 除非确有必要，否则保持接口稳定。

5. 测试

• 为新行为和回归添加／调整有针对性的测试。
• 运行相关软件包的测试（默认不只运行整个 monorepo 的测试）。
• 如果问题只在负载下出现，则添加并发／降级测试。

6. 再次运行基准测试

• 使用相同参数重新运行相同基准。
• 报告绝对和相对变化。
• 优先报告延迟变化（p50/p95/p99、吞吐量），再报告适用的资源变化。

7. 准备 PR

• 分支命名：codex/perf-<area>-<change>。
• 提交消息：perf(<package>): <what changed>。
• 包含风险说明和回滚简便性说明。

8. 迭代

• 等待评审，然后再着手下一个独立改进。

基准测试指南

• 缩小基准测试范围，以隔离单项改动。
• 使用预热迭代。
• 测量以下两类：
• micro：操作级开销。
• scenario：请求／任务流程、并发，以及依赖项降级情况。
• 对于缩短执行时间的工作，以场景数据作为决策依据；微基准数据作为辅助证据。
• 始终打印：
• 总耗时
• 单次操作耗时
• 适用时的 p50/p95/p99 延迟
• 加速比
• 迭代次数和工作负载特征
• 适用时的资源计数器（rss、heap、句柄、事件循环延迟）

资源耗尽检查清单

• 在每个边界（入口、队列、下游客户端）限制并发。
• 确保超时和取消能够端到端传递。
• 确保重试有次数上限并加入抖动。
• 确认始终会清理监听器／计时器／间隔定时器。
• 确认在成功和错误路径中都会关闭／销毁流。
• 确认对象缓存具有大小／TTL 控制。

CI／不稳定测试处理

• 如果只在 CI 中出现故障，则在测试中添加临时诊断数据。
• 只有在资源竞争是原因时，才串行运行受影响的不稳定测试。
• 将确定性改进保留在测试代码中，除非生产代码确有需要。

输出模板

对于每个 PR，报告：

1. 要修复的问题。
2. 该问题在负载下为何重要。
3. 变更的代码位置。
4. 运行的测试及结果。
5. 基准测试前后数据（优先报告执行指标：p50/p95/p99 和吞吐量）。
6. 风险评估。
7. 下一个待优化候选项。