用途
本技能面向 Node.js 开发中的原则与决策训练,目标是帮助开发者“学会思考”,而不是背诵固定的代码模式。技能明确要求:当用户偏好不清晰时要主动询问,依据具体上下文选择框架和模式,不应每次都默认同一套方案。
主要能力
框架选择(2025)
技能提供一个按构建场景分支的决策树:
- 边缘/无服务器(Cloudflare、Vercel):Hono(零依赖、冷启动极快)
- 高性能 API:Fastify(比 Express 快 2-3 倍)
- 企业/团队熟悉度:NestJS(结构化、依赖注入、装饰器)
- 遗留/稳定/最大生态:Express(成熟、中间件最多)
- 前后端全栈:Next.js API Routes 或 tRPC
对比维度包括适用场景、冷启动、生态、TypeScript 支持与学习曲线。选择前建议自问:部署目标是什么、冷启动是否关键、团队是否有既有经验、是否有遗留代码需要维护。
运行时与模块系统
- Node.js 22+ 的
--experimental-strip-types可直接运行 .ts 文件,简单项目可省去构建步骤,适用于脚本和简单 API。 - 模块系统:ESM 是现代标准,具备更好的 tree-shaking 与异步模块加载,适用于新项目;CommonJS 用于遗留兼容与部分 npm 包支持场景。
- 运行时选择:Node.js 通用且生态最大;Bun 侧重性能与内置打包器;Deno 侧重安全与内置 TypeScript。
架构原则
采用分层结构:控制器/路由层处理 HTTP 细节并在边界做输入校验;服务层承载与框架无关的业务逻辑;仓储层只负责数据访问、数据库查询与 ORM 交互。其价值在于可测试性(可独立模拟各层)、灵活性(换数据库不影响业务逻辑)和职责清晰。小型脚本可单文件,原型可减少结构,但要先问“它会不会长大”。
错误处理
集中式错误处理模式:定义自定义错误类,从任意层抛出,在顶层中间件捕获并输出一致格式。客户端只得到合适的 HTTP 状态码、便于程序处理的错误码和友好信息,不暴露内部细节;日志则记录完整堆栈、请求上下文、用户 ID 和时间戳。技能还给出 400、401、403、404、409、422、500 等状态码的选择场景。
异步模式
- async/await:顺序异步操作
- Promise.all:并行独立操作
- Promise.allSettled:允许部分失败的并行
- Promise.race:超时或首个响应胜出
技能强调事件循环意识:I/O 密集(数据库、HTTP、文件系统、网络)适合异步;CPU 密集(加密、图像处理、复杂计算)异步无效,应使用 worker threads 或外移处理。生产中不要使用同步方法,CPU 密集工作要外移,大数据使用流式处理。
输入校验
在边界校验:API 入口、数据库操作前、外部数据(API 响应、文件上传)、环境变量(启动时)。库选择:Zod 适合 TypeScript 优先与类型推断,Valibot 体积更小可 tree-shake,ArkType 面向性能关键场景,Yup 适合已有 React Form 使用。原则是快速失败、信息明确、不信任任何数据。
安全清单
输入校验、参数化查询(禁止 SQL 字符串拼接)、bcrypt 或 argon2 密码哈希、JWT 验证签名与过期、限流、安全响应头(Helmet.js 等)、生产环境 HTTPS、正确配置 CORS、密钥仅用环境变量、依赖定期审计。对查询参数、请求体、响应头、Cookie、文件上传、外部 API 响应均保持不信任。
测试策略
单元测试(node:test、Vitest)覆盖业务逻辑;集成测试(Supertest)覆盖 API 端点;E2E(Playwright)覆盖完整流程。优先测试关键路径(认证、支付、核心业务)、边界情况与错误处理;框架代码和简单 getter 不值得测试。Node.js 22+ 可用 node --test src/**/*.test.ts 内置测试运行器,无需外部依赖。
反模式与决策清单
应避免:新边缘项目用 Express、生产代码用同步方法、业务逻辑放进控制器、跳过输入校验、硬编码密钥、不校验外部数据、CPU 工作阻塞事件循环。实施前应确认:是否询问过技术栈偏好、是否为当前上下文选框架、是否考虑部署目标、是否规划错误处理、是否识别校验点、是否考虑安全需求。
使用方式
资料未提供具体的安装命令、调用方式或运行步骤,暂未提供。
适用场景
适合需要为 Node.js 新项目做技术选型、设计分层架构、规范错误处理与校验、制定安全与测试策略的开发者或团队,也适合用于代码评审时对照反模式与决策清单。
限制
该技能强调原则与决策,不提供可直接复制的完整代码;文中提及的性能倍数、冷启动快慢等对比属于资料原文表述,未提供独立基准数据。具体安装与集成方式资料未提供。