nodejs-best-practices

Node.js 最佳实践

现代 Node.js 开发的原则与决策方法。 学会思考，而不是死记代码模式。

---

⚠️ 如何使用此技能

此技能教授的是决策原则，而不是可直接复制的固定代码。

• 不清楚时，向用户询问偏好
• 根据上下文选择框架／模式
• 不要每次都默认采用同一种方案

---

1. 框架选择

决策树

What are you building?
│
├── Edge/Serverless (Cloudflare, Vercel)
│   └── Hono (zero-dependency, ultra-fast cold starts)
│
├── High Performance API
│   └── Fastify (~5x req/sec of Express in Fastify's own hello-world benchmark; benchmark your own workload)
│
├── Enterprise/Team familiarity
│   └── NestJS (structured, DI, decorators)
│
├── Legacy/Stable/Maximum ecosystem
│   └── Express (mature, most middleware)
│
└── Full-stack with frontend
    └── Next.js API Routes or tRPC

比较原则

因素	Hono	Fastify	Express
最适合	边缘计算、无服务器	性能	遗留项目、学习
冷启动	最快	快	中等
生态系统	正在发展	良好	最成熟
TypeScript	原生支持	出色	良好
学习曲线	低	中等	低

要询问的问题：

1. 部署目标是什么？
2. 冷启动时间是否至关重要？
3. 团队是否有相关经验？
4. 是否有需要维护的遗留代码？

---

2. 运行时考量

原生 TypeScript

Node.js 24+ (Active LTS): type-stripping ON by default
├── Run .ts files directly: node file.ts (no flag, stable since 24.12)
├── Erasable syntax only — enums, runtime namespaces, param properties error out
├── For those, use tsx (--experimental-transform-types was removed in Node 26)
└── Consider for: scripts, simple APIs

模块系统决策

ESM (import/export)
├── Modern standard
├── Better tree-shaking
├── Async module loading
└── Use for: new projects

CommonJS (require)
├── Legacy compatibility
├── More npm packages support
└── Use for: existing codebases, some edge cases

运行时选择

运行时	最适合
Node.js	通用场景、生态系统最庞大
Bun	性能、内置打包器
Deno	安全优先、内置 TypeScript

---

3. 架构原则

分层结构概念

Request Flow:
│
├── Controller/Route Layer
│   ├── Handles HTTP specifics
│   ├── Input validation at boundary
│   └── Calls service layer
│
├── Service Layer
│   ├── Business logic
│   ├── Framework-agnostic
│   └── Calls repository layer
│
└── Repository Layer
    ├── Data access only
    ├── Database queries
    └── ORM interactions

重要性：

• 可测试性：独立模拟各层
• 灵活性：无需改动业务逻辑即可替换数据库
• 清晰性：每层只负责一项职责

何时简化：

• 小型脚本 → 可以使用单个文件
• 原型 → 可以采用较少的结构
• 始终要问：“它会不断扩展吗？”

---

4. 错误处理原则

集中式错误处理

Pattern:
├── Create custom error classes
├── Throw from any layer
├── Catch at top level (middleware)
└── Format consistent response

错误响应理念

Client gets:
├── Appropriate HTTP status
├── Error code for programmatic handling
├── User-friendly message
└── NO internal details (security!)

Logs get:
├── Full stack trace
├── Request context
├── User ID (if applicable)
└── Timestamp

状态码选择

情况	状态码	适用场景
输入错误	400	客户端发送了无效数据
未认证	401	缺少凭据或凭据无效
无权限	403	认证有效，但不允许访问
未找到	404	资源不存在
冲突	409	重复或状态冲突
验证失败	422	架构有效，但业务规则未通过
服务器错误	500	我们的责任，记录所有信息

---

5. 异步模式原则

何时使用各模式

模式	使用场景
async/await	按顺序执行异步操作
Promise.all	并行执行相互独立的操作
Promise.allSettled	并行执行，且部分操作可能失败
Promise.race	超时或以最先返回的响应为准

了解事件循环

I/O-bound (async helps):
├── Database queries
├── HTTP requests
├── File system
└── Network operations

CPU-bound (async doesn't help):
├── Crypto operations
├── Image processing
├── Complex calculations
└── → Use worker threads or offload

避免阻塞事件循环

• 生产环境中绝不要使用同步方法（fs.readFileSync 等）
• 将 CPU 密集型工作转移到其他地方处理
• 大型数据使用流处理

---

6. 验证原则

在边界处进行验证

Where to validate:
├── API entry point (request body/params)
├── Before database operations
├── External data (API responses, file uploads)
└── Environment variables (startup)

验证库选择

库	最适合
Zod	优先支持 TypeScript、类型推断
Valibot	更小的打包体积（可进行 tree-shaking）
ArkType	对性能要求高的场景
Yup	已在使用 React Form 的项目

验证理念

• 尽早失败：尽早验证
• 明确具体：提供清晰的错误消息
• 不要轻信：即使是“内部”数据也要验证

---

7. 安全原则

安全检查清单（非代码）

• 输入验证：验证所有输入
• 参数化查询：SQL 不使用字符串拼接
• 密码哈希：使用 bcrypt 或 argon2
• JWT 验证：始终验证签名和有效期
• 速率限制：防止滥用
• 安全标头：使用 Helmet.js 或同类工具
• HTTPS：在生产环境中处处使用
• CORS：正确配置
• 密钥：仅使用环境变量
• 依赖项：定期审计

安全意识

Trust nothing:
├── Query params → validate
├── Request body → validate
├── Headers → verify
├── Cookies → validate
├── File uploads → scan
└── External APIs → validate response

---

8. 测试原则

测试策略选择

类型	用途	工具
单元测试	业务逻辑	node:test、Vitest
集成测试	API 端点	Supertest
端到端测试	完整流程	Playwright

测试内容（优先级）

1. 关键路径：身份验证、支付、核心业务
2. 边界情况：空输入、边界值
3. 错误处理：发生故障时会怎样？
4. 不值得测试的内容：框架代码、简单的 getter

内置测试运行器（自 Node.js 20 起稳定）

node --test src/**/*.test.ts
├── No external dependency
├── Good coverage reporting
└── Watch mode available

---

9. 应避免的反模式

❌ 不要：

• 在新的边缘项目中使用 Express（改用 Hono）
• 在生产代码中使用同步方法
• 将业务逻辑放在控制器中
• 跳过输入验证
• 硬编码机密信息
• 未经验证就信任外部数据
• 用 CPU 密集型任务阻塞事件循环

✅ 应当：

• 根据上下文选择框架
• 不确定时询问用户的偏好
• 在项目逐渐扩大时采用分层架构
• 验证所有输入
• 使用环境变量存储机密信息
• 优化前先进行性能分析

---

10. 决策清单

开始实施前：

• 是否询问了用户对技术栈的偏好？
• 是否根据当前上下文选择了框架？（而非仅采用默认选项）
• 是否考虑了部署目标？
• 是否规划了错误处理策略？
• 是否确定了验证点？
• 是否考虑了安全要求？

---

请记住：Node.js 最佳实践的核心是决策，而不是死记模式。每个项目都应根据自身需求重新考量。