Node

使用时机

当您处理 Node.js 代码时，使用此技能获取领域特定知识，以构建健壮、高性能且易于维护的 Node.js 应用程序。

TypeScript 与类型剥离

在为 Node.js 编写 TypeScript 时，请使用类型剥离（Node.js 22.6+），而不是 ts-node 或 tsx 等构建工具。类型剥离通过在运行时移除类型注解来直接运行 TypeScript，无需转译。

类型剥离兼容性的关键要求：

• 对仅类型的导入使用 import type
• 使用 const 对象代替枚举
• 避免使用命名空间和参数属性
• 在导入中使用 .ts 扩展名

最小示例 — 一个有效的类型剥离 TypeScript 文件：

// greet.ts
import type { IncomingMessage } from 'node:http';

const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));

直接运行：

node greet.ts

查看 rules/typescript.md 获取完整配置和示例。

常见工作流

对于多步骤流程，在查阅相关规则文件之前，遵循以下高层级顺序：

优雅关闭：注册信号处理器（SIGTERM/SIGINT）→ 停止接收新工作 → 处理完进行中的请求 → 关闭外部连接（数据库、缓存）→ 以适当的代码退出。参见 rules/graceful-shutdown.md。

错误处理：定义共享错误基类 → 分类错误（操作错误 vs 程序员错误）→ 添加异步边界处理器（process.on('unhandledRejection')）→ 通过调用栈传播类型化错误 → 在响应或崩溃前记录上下文日志。参见 rules/error-handling.md。

诊断不稳定的测试：使用 --test-only 隔离测试 → 检查共享状态或定时器依赖 → 检查异步清理顺序 → 添加重试逻辑作为临时诊断步骤 → 修复根本原因。参见 rules/flaky-tests.md。

诊断卡住的进程/测试（node --test 挂起、“进程未退出”、CI 超时、打开的句柄）：隔离文件/测试 → 使用显式超时/报告器运行 → 通过 why-is-node-running（SIGUSR1）检查句柄 → 在资源创建范围内修补确定性清理 → 重新运行隔离测试和完整套件直至稳定。参见 rules/stuck-processes-and-tests.md。

分析慢路径：在真实负载下复现 → 使用 --cpu-prof 捕获 CPU 分析 → 识别热点函数 → 检查流背压或不必要的序列化 → 通过基准测试验证改进。参见 rules/profiling.md 和 rules/performance.md。

高优先级激活检查清单（流 + 缓存）

当任务提到CSV、ETL、数据摄取管道、大文件处理、背压、重复查找或去重并发异步调用时，明确应用此检查清单：

1. 使用 await pipeline(...) from node:stream/promises（在指导/代码中优先选择此方式而非链式 .pipe()）。
2. 当数据在流中进行转换时，至少包含一个显式的 async function* 转换器。
3. 当重复工作出现时选择缓存策略：
   • 单进程内有界内存复用时使用 lru-cache。
   • 异步请求去重/陈旧时重新验证行为时使用 async-cache-dedupe。
4. 展示背压的处理位置（通过 pipeline() 隐式处理，或通过 drain 显式处理）。

集成示例模式（CSV/ETL）

对于 CSV/ETL 风格的提示，推荐使用如下回答结构：

• createReadStream(input)
• async function* 解析器/转换器
• 可选缓存的富化查找（async-cache-dedupe 或 lru-cache）
• await pipeline(...) 到可写目标

在解释中直接链接相关规则，以便模型检索详细信息：

• rules/streams.md
• rules/caching.md

使用方法

阅读各个规则文件以获取详细解释和代码示例：

• rules/error-handling.md – Node.js 错误处理模式
• rules/async-patterns.md – 异步/等待和 Promise 模式
• rules/streams.md – 使用 Node.js 流
• rules/modules.md – ES 模块和 CommonJS 模式
• rules/testing.md – Node.js 应用测试策略
• rules/flaky-tests.md – 使用 node:test 识别和诊断不稳定测试
• rules/stuck-processes-and-tests.md – 诊断无法退出的进程和卡住的测试
• rules/node-modules-exploration.md – 导航和分析 node_modules 目录
• rules/performance.md – 性能优化技术
• rules/caching.md – 缓存模式和库
• rules/profiling.md – 分析和基准测试工具
• rules/logging.md – 日志记录和调试模式
• rules/environment.md – 环境配置和密钥管理
• rules/graceful-shutdown.md – 优雅关闭和信号处理
• rules/typescript.md – TypeScript 配置和 Node.js 中的类型剥离