nodejs-best-practices

Node.js 最佳实践

2025 年 Node.js 开发的原则与决策。 学会思考，而不是背诵代码模式。

---

⚠️ 如何使用本技能

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

• 情况不明时，先询问用户的偏好
• 根据上下文选择框架/模式
• 不要每次都默认采用同一套方案

---

1. 框架选择（2025）

决策树

What are you building?
│
├── Edge/Serverless (Cloudflare, Vercel)
│   └── Hono (zero-dependency, ultra-fast cold starts)
│
├── High Performance API
│   └── Fastify (2-3x faster than Express)
│
├── 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. 运行时考量（2025）

原生 TypeScript

Node.js 22+: --experimental-strip-types
├── Run .ts files directly
├── No build step needed for simple projects
└── 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

为什么这很重要：

• 可测试性：可独立 mock 各层
• 灵活性：更换数据库而不触及业务逻辑
• 清晰性：每一层只承担单一职责

何时简化：

• 小型脚本 → 单文件即可
• 原型 → 结构可以更少
• 始终自问：“它会变大吗？”

---

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	Schema 有效但业务规则不通过
服务器错误	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-shake）
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
E2E	完整流程	Playwright

要测试什么（优先级）

1. 关键路径：认证、支付、核心业务
2. 边界情况：空输入、边界值
3. 错误处理：失败时会发生什么？
4. 不值得测试：框架代码、简单的 getter

内置测试运行器（Node.js 22+）

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

---

10. 应避免的反模式

❌ 不要：

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

✅ 要：

• 根据上下文选择框架
• 不明确时询问用户的偏好
• 对不断增长的项目使用分层架构
• 验证所有输入
• 使用环境变量存储密钥
• 优化前先进行性能分析

---

11. 决策清单

在实现之前：

• 询问了用户的栈偏好吗？
• 为当前上下文选择了框架吗？（而不只是默认值）
• 考虑了部署目标吗？
• 规划了错误处理策略吗？
• 确定了验证点吗？
• 考虑了安全要求吗？

---

记住：Node.js 最佳实践关乎决策，而非死记硬背模式。每个项目都应根据其需求进行全新的考量。