用途:这是一份 Node.js 开发决策指南,目标是教人“思考”而非记忆固定代码模式。它要求在不明确时先询问用户偏好,依据上下文选择框架与模式,避免每次都套用同一方案。
主要能力:
- 框架选型决策树:边缘/无服务器(Cloudflare、Vercel)选 Hono;高性能 API 选 Fastify;企业级与团队熟悉度选 NestJS;遗留/稳定/生态最大选 Express;全栈配前端选 Next.js API Routes 或 tRPC。并给出 Hono、Fastify、Express 在冷启动、生态、TypeScript、学习曲线上的对比原则,以及应提问的选型问题(部署目标、冷启动是否关键、团队经验、是否有遗留代码)。
- 运行时考量:Node.js 22+ 可用 --experimental-strip-types 直接运行 .ts;模块系统上 ESM 用于新项目,CommonJS 用于既有代码库;运行时可选 Node.js(通用、生态最大)、Bun(性能、内置打包器)、Deno(安全优先、内置 TypeScript)。
- 架构原则:控制器/路由层负责 HTTP 与边界校验,服务层承载与框架无关的业务逻辑,仓储层只做数据访问;分层带来可测试性、可替换性与职责清晰,小脚本或原型可简化,但要先问“它会长大吗”。
- 错误处理:自定义错误类、任意层抛出、顶层中间件捕获并统一响应;客户端只得到合适状态码、错误码与友好信息,不暴露内部细节;日志保留完整堆栈、请求上下文、用户 ID 与时间戳。并列出 400/401/403/404/409/422/500 的适用情形。
- 异步模式:async/await 用于顺序操作,Promise.all 用于并行独立操作,Promise.allSettled 用于允许部分失败,Promise.race 用于超时或首个响应;区分 I/O 密集与 CPU 密集,后者应使用 worker 线程或卸载;生产环境避免同步方法,大流量数据用流式处理。
- 校验:在 API 入口、数据库操作前、外部数据与环境变量启动时校验;库可选 Zod、Valibot、ArkType、Yup;原则是快速失败、信息明确、不信任任何数据。
- 安全清单:输入校验、参数化查询、bcrypt 或 argon2 哈希密码、验证 JWT 签名与过期、限流、安全响应头(Helmet.js 或等价物)、生产全站 HTTPS、正确配置 CORS、密钥仅用环境变量、定期审计依赖。
- 测试:单元测试用 node:test 或 Vitest,集成测试用 Supertest,端到端用 Playwright;优先测关键路径、边界情况与错误处理,不必测框架代码和琐碎 getter;Node.js 22+ 可用 node --test src/**/*.test.ts。
- 反模式与决策清单:不要在新边缘项目用 Express、生产用同步方法、把业务逻辑放进控制器、跳过校验、硬编码密钥、不校验外部数据、用 CPU 工作阻塞事件循环;实现前应确认技术栈偏好、按当前上下文选框架、考虑部署目标、规划错误处理、识别校验点与安全需求。
限制:资料未提供具体安装命令、版本兼容细节、性能基准数据、收费或平台信息,也未给出完整代码示例;实际采用时需结合项目情况自行判断。