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）→ 停止接受新任务 → 排空正在处理的请求 → 关闭外部连接（DB、缓存）→ 使用适当的代码退出。请参阅 rules/graceful-shutdown.md。

错误处理：定义共享错误基类 → 对错误进行分类（操作错误与程序员错误）→ 添加异步边界处理程序（process.on('unhandledRejection')）→ 在调用栈中传递类型化错误 → 在响应或崩溃前记录带有上下文的日志。请参阅 rules/error-handling.md。

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

诊断卡住的进程/测试（node --test 挂起、“process did not exit”、CI 超时、句柄未关闭）：隔离文件/测试 → 使用显式超时/报告器运行 → 通过 why-is-node-running（SIGUSR1）检查句柄 → 在创建资源的作用域中进行确定性清理 → 重新运行隔离测试和完整测试套件，直至稳定。请参阅 rules/stuck-processes-and-tests.md。

分析缓慢的执行路径：在真实负载下重现 → 使用 --cpu-prof 捕获 CPU 性能分析文件 → 找出热点函数 → 检查流背压或不必要的序列化 → 使用基准测试验证改进。请参阅 rules/profiling.md 和 rules/performance.md。

高优先级启用清单（流 + 缓存）

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

1. 使用 node:stream/promises 中的 await pipeline(...)（在指导或代码中优先使用此方式，而不是链式调用 .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 - Async/await 和 Promise 模式
• rules/streams.md - 使用 Node.js 流
• rules/modules.md - ES Modules 和 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 中的类型剥离