nodejs-best-practices

Node.js Best Practices - Node.js 开发决策原则与实践指南

技能概述

Node.js Best Practices 是一个专注于 Node.js 开发决策原则的智能技能，帮助开发者根据具体场景选择合适的框架、架构模式和编程实践，强调培养决策思维而非机械套用代码模板。

适用场景

1. 新项目技术选型

当你开始一个新的 Node.js 项目时，这个技能可以帮助你根据部署目标（边缘计算/Serverless、传统服务器）、性能要求、团队技术栈等因素，在 Hono、Fastify、Express、NestJS 等框架中做出最合适的选择。

2. 项目架构设计与重构

对于需要设计分层架构、规划错误处理策略、建立验证规范的项目，这个技能提供清晰的架构原则和设计模式，帮助你构建可测试、可维护、可扩展的代码结构。

3. 代码质量与安全审查

当你需要审查现有代码的安全性、异步模式使用、错误处理规范性时，这个技能可以指出常见反模式，提供基于 2025 年最新标准的改进建议。

核心功能

框架选择决策树

提供基于项目特征的框架选择指南，包括边缘计算场景推荐 Hono、高性能 API 推荐 Fastify、企业级项目推荐 NestJS、遗留系统维护使用 Express 等明确建议，并附带选择问题清单帮助你做出决策。

架构与异步模式指导

涵盖分层架构设计原则（Controller-Service-Repository）、异步模式选择（async/await、Promise.all、Promise.allSettled 等）、事件循环阻塞避免策略、CPU 密集型任务处理方案，帮助开发者编写高性能、非阻塞的代码。

安全与验证最佳实践

提供完整的安全检查清单（输入验证、参数化查询、密码哈希、JWT 验证、限流、安全头配置等）和验证库选择指南（Zod、Valibot、ArkType、Yup 的使用场景），帮助构建安全可靠的 Node.js 应用。

常见问题

Node.js 项目应该选择哪个框架？

没有万能的最佳框架。根据部署目标选择：边缘/Serverless 用 Hono（冷启动最快）；追求性能用 Fastify（比 Express 快 2-3 倍）；企业级项目用 NestJS（结构化、依赖注入）；维护遗留代码用 Express（生态最成熟）。需要结合团队经验、项目规模和性能要求综合决策。

Node.js ESM 和 CommonJS 有什么区别？

ESM (import/export) 是现代标准，支持更好的 tree-shaking 和异步模块加载，推荐用于新项目。CommonJS (require) 是遗留格式，拥有更好的 npm 包兼容性，适用于现有代码库维护。Node.js 22+ 支持直接运行 TypeScript 文件，简化了开发流程。

Node.js 错误处理最佳实践是什么？

采用集中式错误处理：创建自定义错误类，在任何层抛出错误，在顶层中间件统一捕获。客户端返回适当的 HTTP 状态码和用户友好消息，日志中记录完整堆栈跟踪和请求上下文。根据错误类型使用 400/401/403/404/409/422/500 等精确的状态码。