node-best-practiceslisted

# Node.js 最佳实践 ## 何时用 - 写新的 Node.js HTTP 服务、CLI 工具或后台任务时。 - 处理异步流程、设计中间件错误处理时。 - 引入新依赖或做安全加固时。 - Review 代码，发现有混用回调、漏 `await`、阻塞事件循环或配置硬编码时。 - 上线前做安全自查时。 ## 核心规则 ### 1. 全程 `async`/`await` + `try/catch`；不混用回调，不漏 `await` 导致竞态 **规则：** 所有异步操作统一用 `async`/`await`；禁止在 async 函数中混写 callback 风格；每个 `await` 表达式都必须被 `try/catch` 覆盖或由调用链上的统一错误处理捕获；`await` 不能遗漏——没有 `await` 的 Promise 是悬空的。 **为什么：** AI 生成 Node.js 代码时最常见的错误：`router.get('/user', async (req, res) => { const user = getUser(req.params.id); res.json(user); })`——忘记 `await`，`user` 是一个 Promise 对象而非数据，`res.json` 把 Promise 序列化成 `{}`，请求返回空对象。这类 bug 在简单场景下测试不出来，到了有延迟的生产环境才暴露，且错误信息毫无指向性。 **怎么做：** - 接收到 callback 风格 API（如旧版 `fs`）→ 用 `util.promisify` 包一层，再 `await`。 - 并行等多个无依赖的 Promise → `await Promise.all([...])` 而非串行多个 `await`。 - `async` 函数内若有 `setTimeout`/`setInterval` 回调，注意内部异常不会自动冒泡，需显式 `try/catch`。 --- ### 2. 不阻塞事件循环；CPU 密集任务用 Worker/队列 **规则：** 事件循环线程禁止执行耗时超过几毫秒的 CPU 密集操作（JSON 解析大文件、加密运算、图像处理、复杂正则）；此类任务交给 `worker_threads`、独立进程或异步任务队列（BullMQ、Celery 等）处理。 **为什么：** Node.js 是单线程事件循环，一个同步计算如果耗时 200ms，这 200ms 内所有其他请求都被冻结。AI 常把 `JSON.parse(fs.readFileSync('huge.json'))` 或同步加密写在请求处理函数里——在压测前完全看不出问题，一旦数据量上去，P99 延迟暴涨，整个服务响应停滞。这是 Node.js 最致命的性能陷阱之一。 **怎么做：** - 大文件解析 → 用流式读取（`fs.createReadStream` + `JSONStream`）或 `Worker`。 - CPU 密集计算（哈希、压缩、图像缩放）→ `worker_threads` 或独立微服务。 - 怀疑阻塞 → 用 `clinic.js` 或 `--prof` 火焰图定位，不凭感觉优化。 --- ### 3. 错误统一处理（中间件）；未捕获 rejection 要监听并优雅处理 **规则：** Express/Koa 等框架中必须注册全局错误处理中间件（四参数 `(err, req, res, next)`），所有路由的异步