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 (benchmark the actual 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
最适合	Edge、无服务器	性能	遗留项目、学习
冷启动	最快	快	一般
生态系统	不断发展	良好	最大
TypeScript	原生支持	出色	良好
学习曲线	低	中	低

要提出的选择问题：

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

---

2. 运行时注意事项（2025 年）

原生 TypeScript

Node.js TypeScript support depends on the exact runtime version and syntax; verify the installed release before using type stripping
├── 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-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 22+）

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

---

9. 应避免的反模式

❌ 不要：

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

✅ 应当：

• 根据具体情况选择框架
• 不确定时询问用户的偏好
• 对不断发展的项目采用分层架构
• 验证所有输入
• 使用环境变量存放机密信息
• 优化前先进行性能分析

---

10. 决策检查清单

实施前：

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

---

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

局限性

• 框架比较属于定性评估，且受版本和工作负载影响。示例不构成基准测试证据。对底层 I/O 使用明确的取消机制和截止时间，并从诊断上下文中删去机密信息和个人身份信息。
• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请暂停并请求澄清。