node-best-practices

适用场景

每当你处理 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。

分析缓慢路径：在真实负载下复现 → 使用 --cpu-prof 捕获 CPU 性能分析文件 → 找出热点函数 → 检查流背压或不必要的序列化 → 使用基准测试验证改进。请参阅 rules/profiling.md 和 rules/performance.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/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 - Node.js 中的 TypeScript 配置和类型剥离