nodejs

此技能是 Node.js/Bun 参考资料集的路由外壳。

不可妥协的规则：

1. 首先阅读 references/stack.md，以确定运行时（Node.js 或 Bun）、框架和已锁定的决策。
2. 然后仅加载实际任务所需的参考资料。
3. TypeScript 严格模式——不得使用 any，不得隐式返回，不得未经检查就访问索引。
4. 所有异步函数都必须处理错误——不得出现未处理的 Promise 拒绝。在每个边界处使用 try/catch 或 .catch()。
5. 在系统边界处验证输入——对每个外部输入（请求体、查询参数、环境变量、CLI 参数）使用 Zod schema。绝不信任 req.body。
6. 使用 pino 进行结构化日志记录——生产代码中不得使用 console.log。以 JSON 格式输出到 stdout，由日志聚合器解析。
7. 优雅关闭——处理 SIGTERM/SIGINT，排空连接，完成正在执行的工作，并关闭数据库连接池。
8. 代码或日志中不得包含机密信息——启动时验证环境变量；绝不记录这些变量，也绝不将其包含在错误响应中。

nodejs

输入

• $request：正在处理的后端任务、子系统、错误或功能

目标

按照项目约定处理 Node.js/Bun 后端工作，确保实现遵循既定的服务器架构、数据访问、错误处理和部署模式。

步骤 0：阅读技术栈约定

始终从以下文件开始：

• references/stack.md

该文件会说明：运行时（Node.js 或 Bun）、框架（Express/Fastify/Hono/无）、ORM、测试运行器、包管理器和已锁定的依赖选择。

如果存在 bun.lockb 或 bunfig.toml，则运行时为 Bun——还需加载 references/bun-runtime.md，了解原生 API 的差异。

成功标准：开始实现前，项目的运行时、框架和工具链选择均已明确。

步骤 1：仅加载相关参考资料

使用路由表选择参考文件。不要一次性加载整套参考资料。

任务	阅读
运行时、TypeScript、包管理器、已锁定的依赖	references/stack.md
文件夹约定、入口点、monorepo 布局	references/project-structure.md
Express/Fastify/Hono 模式、中间件、路由	references/http-server.md
REST 约定、版本控制、分页、错误响应	references/api-design.md
Zod/AJV 输入验证、DTO 模式	references/validation.md
Prisma/Drizzle/Knex、迁移、连接池	references/database.md
JWT、会话、OAuth2、RBAC、中间件防护	references/auth.md
错误类、异步错误边界、HTTP 错误响应	references/error-handling.md
pino 结构化日志记录、请求关联、日志级别	references/logging.md
vitest/jest/bun test、supertest、测试工厂、覆盖率	references/testing.md
Promise、流、工作线程、AbortController、关闭	references/async-patterns.md
helmet、CORS、速率限制、输入清理、依赖审计	references/security.md
Redis、内存缓存、缓存失效模式	references/caching.md
BullMQ、作业模式、重试策略、死信队列	references/queues-jobs.md
环境变量验证、dotenv、配置模块、机密管理	references/config.md
OpenTelemetry、健康检查、指标、分布式追踪	references/observability.md
多阶段 Dockerfile、.dockerignore、生产与开发镜像	references/docker.md
ws/Socket.io、连接生命周期、扩展、房间	references/websockets.md
commander/yargs、参数解析、退出码、stdin/stdout	references/cli.md
Bun 原生 API、bun test、bun build、Bun.serve、Bun.$	references/bun-runtime.md

多个任务？阅读多个文件。参考资料均可独立使用。

成功标准：仅采用与任务相关的后端约定。

第 2 步：使用核心后端防护措施实现

持续遵循以下规则：

• TypeScript 严格模式，并启用 noUncheckedIndexedAccess
• 在边界处验证所有外部输入（Zod 架构）
• 错误必须有类型、经过捕获，并以结构化 HTTP 响应返回
• 通过 pino 子日志记录器记录日志，并使用请求关联 ID
• 通过项目的 ORM／查询构建器访问数据库，而非使用原始 SQL 字符串
• 在原子性至关重要时，将变更包装在事务中
• 优雅关闭：SIGTERM 处理程序排空服务器、关闭连接池并干净退出
• 在启动时验证环境变量——缺少必需配置时立即失败
• 不使用 any，除非在注释中说明理由，否则不使用 as 类型断言
• 如果使用 Bun 运行时：优先使用 Bun.serve()、Bun.file()、bun test，而非 Node.js 对应项

成功标准：更改符合项目的后端架构，而非通用默认做法。

第 3 步：验证受影响范围

使用范围最窄的相关验证方式：

• 单元测试（vitest run、jest 或 bun test）
• 使用 supertest 或实际 HTTP 调用进行集成测试
• 类型检查（tsc --noEmit）
• 代码检查（eslint .）
• 如果使用 Docker：构建镜像并验证其可以启动

成功标准：更改涉及的后端范围仍可构建、通过类型检查和测试。

防护措施

• 不要将整本 Node.js 手册内联到 SKILL.md 中。
• 不要跳过 references/stack.md。
• 不要在生产代码中使用 console.log——请使用 pino。
• 不要绕过 API 边界处的输入验证。
• 不要留下未处理的 Promise 拒绝。
• 不要硬编码密钥、端口或特定环境的值。
• 不要添加 disable-model-invocation；这是一个普通的领域技能。

何时加载参考资料

• references/stack.md 始终加载。

• references/bun-runtime.md 当项目使用 Bun 时加载（通过 bun.lockb 或 bunfig.toml 检测）。

• 然后仅加载 references/ 下与任务相关的文件

输出约定

报告：

1. 加载了哪些参考资料
2. 选择了哪种架构模式
3. 所做的更改
4. 运行的验证