Ling: Skill for Claude Code

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（如适用）
+-- 时间戳

状态码选择