nodejs-best-practices

Node.js 最佳实践

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

何时使用

在做出 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

为什么这很重要：

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

何时简化：

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

---

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-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

---

9. 要避免的反模式

❌ 不要：

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

✅ 要：

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

---

10. 决策清单

在实现之前：

• 询问过用户的技术栈偏好吗？
• 针对此上下文选择了框架吗？（不只是默认选择）
• 考虑过部署目标吗？
• 规划过错误处理策略吗？
• 确定过验证点吗？
• 考虑过安全需求吗？

---

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

限制

• 仅当任务明确符合上述范围时才使用此技能。
• 不要将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。