Nodejs Best Practices

Node.js 最佳实践

> 面向 2025 的 Node.js 开发原则与决策方法。 > 学习如何思考，不要只记代码套路。

---

[WARN] 本技能使用方式

本技能教授的是决策原则，不是固定代码模板。

• 需求不明确时，先向用户确认偏好
• 根据上下文（Context）选择框架与模式
• 不要每次都默认同一套方案

---

1. 框架选型（2025）

决策树

你要构建什么？
|
+-- Edge/Serverless（边缘/无服务器，Cloudflare、Vercel）
|   +-- Hono（零依赖、冷启动极快）
|
+-- 高性能 API
|   +-- Fastify（通常比 Express 快 2-3 倍）
|
+-- 企业协作/团队熟悉度优先
|   +-- NestJS（结构化、DI、装饰器）
|
+-- 传统/稳定/生态最大化
|   +-- Express（成熟、middleware 最多）
|
+-- 前后端一体
    +-- Next.js API Routes 或 tRPC

对比原则

| 维度 | Hono | Fastify | Express | |------|------|---------|---------| | 适用场景 | Edge、serverless | 性能优先 | 传统、学习 | | 冷启动 | 最快 | 快 | 中等 | | 生态 | 成长中 | 较好 | 最大 | | TypeScript | 原生支持 | 优秀 | 良好 | | 学习曲线 | 低 | 中 | 低 |

选型前必须询问：

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

---

2. 运行时考量（2025）

原生 TypeScript

Node.js 22+: --experimental-strip-types
+-- 可直接运行 .ts 文件
+-- 简单项目可免构建步骤
+-- 适用：脚本、简单 API

模块系统决策

ESM（import/export）
+-- 现代标准
+-- 更好的 tree-shaking
+-- 异步模块加载
+-- 适用：新项目

CommonJS（require）
+-- 遗留兼容性更好
+-- 对部分 npm 包支持更成熟
+-- 适用：既有代码库、特定边界场景

Runtime 选择

| Runtime | 适用场景 | |---------|----------| | Node.js | 通用场景、生态最大 | | Bun | 性能优先、内置 bundler | | Deno | 安全优先、内置 TypeScript |

---

3. 架构原则

分层结构概念

请求流（Request Flow）:
|
+-- Controller/Route 层
|   +-- 处理 HTTP 细节
|   +-- 在边界做输入校验
|   +-- 调用 service 层
|
+-- Service 层
|   +-- 承载业务逻辑
|   +-- 与框架解耦
|   +-- 调用 repository 层
|
+-- Repository 层
    +-- 仅处理数据访问
    +-- 数据库查询
    +-- ORM 交互

为什么重要

• 可测性（Testability）： 可独立 mock 每一层
• 灵活性（Flexibility）： 更换数据库不影响业务层
• 清晰性（Clarity）： 每层职责单一

何时简化

• 小型脚本 -> 单文件可接受
• 原型验证 -> 可降低结构复杂度
• 始终追问：“这个项目会继续增长吗？”

---

4. 错误处理原则

集中式错误处理

Pattern:
+-- 定义自定义错误类
+-- 各层都可 throw
+-- 在顶层统一 catch（middleware）
+-- 输出一致的响应格式

错误响应哲学

Client gets:
+-- 合理的 HTTP 状态码
+-- 可程序化处理的错误码
+-- 对用户友好的提示
+-- 不暴露内部细节（安全要求）

Logs get:
+-- 完整堆栈信息
+-- 请求上下文
+-- 用户 ID（如适用）
+-- 时间戳

状态码选择

| 场景 | 状态码 | 说明 | |------|--------|------| | Bad input | 400 | 客户端输入无效 | | No auth | 401 | 缺少或无效凭据 | | No permission | 403 | 已认证但无权限 | | Not found | 404 | 资源不存在 | | Conflict | 409 | 重复或状态冲突 | | Validation | 422 | schema 合法但业务规则失败 | | Server error | 500 | 服务端责任，完整记录日志 |

---

5. 异步模式原则

各模式使用时机

| 模式 | 适用场景 | |------|----------| | async/await | 串行异步操作 | | Promise.all | 可并行且互不依赖 | | Promise.allSettled | 并行且允许部分失败 | | Promise.race | 超时控制或“先返回者胜出” |

Event Loop 认知

I/O-bound（异步有帮助）:
+-- 数据库查询
+-- HTTP 请求
+-- 文件系统
+-- 网络操作

CPU-bound（异步无帮助）:
+-- 加密计算
+-- 图像处理
+-- 复杂计算
+-- -> 使用 worker threads 或外部任务卸载

避免阻塞 Event Loop

• 生产环境避免使用同步方法（如 fs.readFileSync）
• CPU 密集任务必须卸载
• 大数据处理优先使用 streaming

---

6. 校验原则

在边界做校验

校验位置：
+-- API 入口（request body/params）
+-- 数据库操作之前
+-- 外部数据（API 响应、文件上传）
+-- 环境变量（启动时）

校验库选型

| 库 | 适用场景 | |----|----------| | Zod | TypeScript 优先、类型推断友好 | | Valibot | 包体积更小（tree-shakeable） | | ArkType | 性能敏感场景 | | Yup | 既有 React Form 生态 |

校验哲学

• Fail fast：尽早校验、尽早失败
• Be specific：错误信息必须明确
• Don't trust：即使“内部数据”也不能默认可信

---

7. 安全原则

安全检查清单（不是代码模板）

• [ ] Input validation（输入校验）：所有输入已校验
• [ ] Parameterized queries（参数化查询）：SQL 禁止字符串拼接
• [ ] Password hashing（密码哈希）：使用 bcrypt 或 argon2
• [ ] JWT verification（JWT 校验）：必须校验签名与过期时间
• [ ] Rate limiting（限流）：具备防滥用机制
• [ ] Security headers（安全响应头）：使用 Helmet.js 或同等方案
• [ ] HTTPS：生产环境全链路启用
• [ ] CORS：配置正确
• [ ] Secrets（密钥）：仅使用环境变量管理
• [ ] Dependencies（依赖）：定期审计

安全思维

Trust nothing（默认不信任）:
+-- Query params（查询参数）-> 校验
+-- Request body（请求体）-> 校验
+-- Headers（请求头）-> 校验
+-- Cookies -> 校验
+-- File uploads（文件上传）-> 扫描
+-- External APIs（外部 API）-> 校验响应

---

8. 测试原则

测试策略选择

| 类型 | 目的 | 工具 | |------|------|------| | Unit（单元测试） | 业务逻辑 | node:test, Vitest | | Integration（集成测试） | API 端点 | Supertest | | E2E（端到端） | 完整流程 | Playwright |

测试优先级

1. 关键路径：鉴权、支付、核心业务
2. 边界场景：空输入、边界值
3. 错误处理：失败时系统如何表现
4. 不值得测：框架内部代码、过于简单的 getter

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

node --test src/**/*.test.ts
+-- 无需额外依赖
+-- 覆盖率报告可用
+-- 支持 watch mode（监听模式）

---

10. 需要避免的反模式

[FAIL] 不要这样做：

• 新 Edge 项目默认用 Express（优先考虑 Hono）
• 在生产代码中使用同步方法
• 在 controller 中堆业务逻辑
• 跳过输入校验
• 硬编码 secrets
• 不校验就信任外部数据
• 用 CPU 重任务阻塞 event loop（事件循环）

[OK] 推荐做法：

• 基于上下文选择框架
• 需求不清晰先询问用户偏好
• 可增长项目采用分层架构
• 对所有输入做校验
• secrets 使用环境变量管理
• 优化前先做 profile（性能分析）

---

11. 决策检查清单

开始实现前：

• [ ] 是否询问了用户的技术栈偏好？
• [ ] 是否为当前上下文选了合适框架？（而非默认）
• [ ] 是否考虑了部署目标？
• [ ] 是否规划了错误处理策略？
• [ ] 是否识别了校验边界点？
• [ ] 是否评估了安全要求？

---

> 牢记： Node.js 最佳实践的核心是“决策能力”，不是“背模板”。每个项目都应基于其真实需求重新判断。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MisonL
• Source: MisonL/Ling
• License: MIT
• Homepage: https://www.npmjs.com/package/@mison/ling

Install and usage instructions live in the source repository linked above.