nodejs-backend

Node.js 后端

实施前请先查证：对于特定框架的 API（Express 5、Fastify 5、Node.js 22+ 内置功能），编写代码前请查阅与当前版本匹配的官方文档。可用时优先使用 Context7（query-docs）。否则，请使用可用的网页工具查阅框架的官方文档，或查阅 Node.js 内置功能的 Node.js API 文档。训练数据可能滞后于当前版本。

工作规则

• 使用请求和第三方数据前先进行验证；明确指定响应序列化方式和错误封装。
• 添加弹性机制或回退方案时，保留调用方可见的契约和授权。
• 限制并发、设置超时，并避免阻塞生产请求路径。
• 解析或缓存复用客户端的结果前，先验证实际资源身份。
• 检查运行遥测和故障路径，而不只是成功返回码。

架构

src/
├── routes/          # HTTP: parse request, call service, format response
├── middleware/       # Auth, validation, rate limiting, logging
├── services/        # Business logic (no HTTP types)
├── repositories/    # Data access only (queries, ORM)
├── config/          # Env, DB pool, constants
└── types/           # Shared TypeScript interfaces

• 路由中绝不包含业务逻辑
• 服务中绝不导入 Request/Response
• 仓储中绝不抛出 HTTP 错误
• 依赖只能向内指向（整洁架构规则）：路由 -> 服务 -> 仓储。绝不可反向依赖。
• 对于脚本/原型：使用单个文件即可；先问自己“它会继续扩展吗？”

TypeScript 规则

• 类型专用导入使用 import type { }；可消除运行时开销
• 对象结构优先使用 interface（类型解析速度比交叉类型快 2-5 倍）
• 优先使用 unknown 而非 any；这会强制进行显式收窄
• 使用 z.infer<typeof Schema> 作为唯一事实来源；绝不重复定义类型和 schema
• 尽量减少 as 断言；改用类型守卫
• 为导出的函数添加显式返回类型（可加快声明文件生成）
• 对于无类型定义的包，在 types/ambient.d.ts 中使用 declare module 'pkg' { const v: unknown; export default v; }

原则

• 简洁优先：每项改动都应尽可能简单，将影响范围控制在最少代码内
• 只改必要的内容；避免引入无关改动
• 不要使用临时取巧的变通方案：如果修复方案感觉不妥，就退一步，采用整洁的解决方案
• 添加新的抽象前，先确认它至少会在 3 个地方出现；否则就直接内联
• 如果修复需要绕过 TypeScript（as any、对不可信数据使用非空断言、// @ts-ignore），应将其视为设计缺陷，并寻找类型安全的解决方案

验证

• tsc --noEmit 通过，且零错误
• npm test 通过，且零失败
• 新代码中没有绕过 TypeScript 的写法（as any、@ts-ignore）

参考资料

• TypeScript 配置：tsconfig、ESM、品牌类型、编译器性能
• 安全：JWT、密码哈希、速率限制、OWASP
• API 设计模式：分页、筛选、排序、弃用、幂等键声明与保留
• 数据库与生产环境：连接池、事务、Docker、日志记录

任务专用参考资料

实施或审查相应行为前，请阅读相关参考资料：

• 对于框架选择、输入验证、API 契约或错误处理：请参阅 api-boundaries.md。
• 对于并发、网络、启动、缓存、生命周期清理或遥测：请参阅 async-and-production.md。
• 对于 span 类型、HTTP 状态码到 span 状态的规则、采样位置、指标基数或遥测数据治理：请参阅 observability-tracing.md。

适用时，请查阅现有的专题参考资料：