nodejs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<EXTREMELY-IMPORTANT> This skill is a routing shell over the Node.js/Bun reference set.

Non-negotiable rules:

Read
```
references/stack.md
```
first to determine the runtime (Node.js or Bun), framework, and locked decisions.
Then load only the references needed for the actual task.
TypeScript strict mode — no
```
any
```
, no implicit returns, no unchecked index access.
All async functions must handle errors — no unhandled promise rejections. Use try/catch or
```
.catch()
```
at every boundary.
Input validation at system boundaries — Zod schemas on every external input (request bodies, query params, env vars, CLI args). Never trust
```
req.body
```
.
Structured logging via pino — no
```
console.log
```
in production code. JSON to stdout, parsed by log aggregators.
Graceful shutdown — handle SIGTERM/SIGINT, drain connections, finish in-flight work, close DB pools.
No secrets in code or logs — env vars validated at startup, never logged, never in error responses.

</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT> 本技能是基于 Node.js/Bun 参考集的路由外壳。

不可违背的规则：

首先阅读
```
references/stack.md
```
以确定运行时（Node.js 或 Bun）、框架及已锁定的决策。
仅加载实际任务所需的参考内容。
TypeScript 严格模式 — 禁止使用
```
any
```
、禁止隐式返回、禁止未检查的索引访问。
所有异步函数必须处理错误 — 禁止未处理的 Promise 拒绝。在每个边界使用 try/catch 或
```
.catch()
```
。
系统边界处的输入校验 — 对所有外部输入（请求体、查询参数、环境变量、CLI 参数）使用 Zod 模式。绝不信任
```
req.body
```
。
通过 pino 实现结构化日志 — 生产代码中禁止使用
```
console.log
```
。输出 JSON 到标准输出，由日志聚合器解析。
优雅停机 — 处理 SIGTERM/SIGINT 信号，排空连接，完成正在进行的工作，关闭数据库连接池。
代码或日志中不得包含密钥 — 环境变量在启动时校验，绝不记录，绝不包含在错误响应中。

</EXTREMELY-IMPORTANT>

nodejs

Inputs

输入

```
$request
```
: The backend task, subsystem, bug, or feature being worked on

```
$request
```
: 后端任务、子系统、Bug 或待开发功能

Goal

目标

Route Node.js/Bun backend work through the project's conventions so implementation follows the established patterns for server architecture, data access, error handling, and deployment.

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

Step 0: Read the stack contract

步骤 0：阅读栈合约

Always start with:

```
references/stack.md
```

That establishes: runtime (Node.js or Bun), framework (Express/Fastify/Hono/none), ORM, test runner, package manager, and locked dependency choices.

bun.lockb

bunfig.toml

exists, the runtime is Bun — also load

references/bun-runtime.md

for native API differences.

Success criteria: The project's runtime, framework, and toolchain choices are explicit before implementation starts.

始终从以下内容开始：

```
references/stack.md
```

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

如果存在

bun.lockb

或

bunfig.toml

，则运行时为 Bun — 同时加载

references/bun-runtime.md

了解原生 API 的差异。

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

Step 1: Load only the relevant references

步骤 1：仅加载相关参考内容

Use the routing table to pick reference files. Do not bulk-load the full reference tree.

Task	Read
Runtime, TypeScript, package manager, locked deps	`references/stack.md`
Folder conventions, entry points, monorepo layout	`references/project-structure.md`
Express/Fastify/Hono patterns, middleware, routing	`references/http-server.md`
REST conventions, versioning, pagination, error responses	`references/api-design.md`
Zod/AJV input validation, DTO patterns	`references/validation.md`
Prisma/Drizzle/Knex, migrations, connection pooling	`references/database.md`
JWT, sessions, OAuth2, RBAC, middleware guards	`references/auth.md`
Error classes, async error boundaries, HTTP error responses	`references/error-handling.md`
pino structured logging, request correlation, log levels	`references/logging.md`
vitest/jest/bun test, supertest, test factories, coverage	`references/testing.md`
Promises, streams, worker threads, AbortController, shutdown	`references/async-patterns.md`
helmet, CORS, rate limiting, input sanitization, dep audit	`references/security.md`
Redis, in-memory caching, cache invalidation patterns	`references/caching.md`
BullMQ, job patterns, retry strategies, dead-letter queues	`references/queues-jobs.md`
Env validation, dotenv, config modules, secrets management	`references/config.md`
OpenTelemetry, health checks, metrics, distributed tracing	`references/observability.md`
Multi-stage Dockerfile, .dockerignore, prod vs dev images	`references/docker.md`
ws/Socket.io, connection lifecycle, scaling, rooms	`references/websockets.md`
commander/yargs, argument parsing, exit codes, stdin/stdout	`references/cli.md`
Bun-native APIs, bun test, bun build, Bun.serve, Bun.$	`references/bun-runtime.md`

Multiple tasks? Read multiple files. The references are self-contained.

Success criteria: Only the task-relevant backend conventions are in play.

使用路由表选择参考文件。不要批量加载完整的参考树。

任务	阅读内容
运行时、TypeScript、包管理器、已锁定依赖	`references/stack.md`
文件夹规范、入口点、单仓库布局	`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、速率限制、输入 sanitization、依赖审计	`references/security.md`
Redis、内存缓存、缓存失效模式	`references/caching.md`
BullMQ、任务模式、重试策略、死信队列	`references/queues-jobs.md`
环境变量校验、dotenv、配置模块、密钥管理	`references/config.md`
OpenTelemetry、健康检查、指标、分布式追踪	`references/observability.md`
多阶段 Dockerfile、.dockerignore、生产 vs 开发镜像	`references/docker.md`
ws/Socket.io、连接生命周期、扩容、房间	`references/websockets.md`
commander/yargs、参数解析、退出码、标准输入/输出	`references/cli.md`
Bun 原生 API、bun test、bun build、Bun.serve、Bun.$	`references/bun-runtime.md`

多个任务？阅读多个文件。参考内容是独立的。

成功标准：仅应用与任务相关的后端规范。

Step 2: Implement with the core backend guardrails

步骤 2：遵循核心后端约束实现

Keep these rules active:

TypeScript strict mode with
```
noUncheckedIndexedAccess
```
all external input validated at the boundary (Zod schemas)
errors are typed, caught, and returned as structured HTTP responses
logging via pino child loggers with request correlation IDs
database access through the project's ORM/query builder, not raw SQL strings
mutations wrapped in transactions where atomicity matters
graceful shutdown: SIGTERM handler drains server, closes pools, exits cleanly
env vars validated at startup — fail fast on missing required config
no
```
any
```
, no
```
as
```
type assertions unless justified with a comment
if Bun runtime: prefer
```
Bun.serve()
```
,
```
Bun.file()
```
,
```
bun test
```
over Node.js equivalents

Success criteria: The change matches the project's backend architecture instead of generic defaults.

始终遵守以下规则：

启用
```
noUncheckedIndexedAccess
```
的 TypeScript 严格模式
所有外部输入在边界处校验（使用 Zod 模式）
错误被类型化、捕获并作为结构化 HTTP 响应返回
通过带有请求关联 ID 的 pino 子记录器记录日志
通过项目的 ORM/查询构建器访问数据库，不使用原始 SQL 字符串
在需要原子性的场景下，将变更包裹在事务中
优雅停机：SIGTERM 处理器排空服务器、关闭连接池、干净退出
环境变量在启动时校验 — 缺少必要配置时快速失败
禁止使用
```
any
```
，除非有注释说明理由，否则禁止使用
```
as
```
类型断言
如果是 Bun 运行时：优先使用
```
Bun.serve()
```
、
```
Bun.file()
```
、
```
bun test
```
而非 Node.js 等效 API

成功标准：变更符合项目后端架构，而非通用默认值。

Step 3: Verify the affected surface

步骤 3：验证受影响的范围

Use the narrowest relevant verification:

unit tests (
```
vitest run
```
,
```
jest
```
, or
```
bun test
```
)
integration tests with supertest or actual HTTP calls
type checking (
```
tsc --noEmit
```
)
linting (
```
eslint .
```
)
if Docker: build the image and verify it starts

Success criteria: The changed backend surface still builds, type-checks, and passes tests.

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

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

成功标准：变更后的后端代码仍可构建、通过类型检查并通过测试。

Guardrails

约束

Do not inline the whole Node.js handbook in
```
SKILL.md
```
.
Do not skip
```
references/stack.md
```
.
Do not use
```
console.log
```
in production code — use pino.
Do not bypass input validation at API boundaries.
Do not leave unhandled promise rejections.
Do not hardcode secrets, ports, or environment-specific values.
Do not add
```
disable-model-invocation
```
; this is a normal domain skill.

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

When To Load References

何时加载参考内容

```
references/stack.md
```
Always.

references/bun-runtime.md

When the project uses Bun (detected via

bun.lockb

bunfig.toml

then only the task-relevant files under
```
references/
```

```
references/stack.md
```
始终加载。
```
references/bun-runtime.md
```
当项目使用 Bun 时（通过
```
bun.lockb
```
或
```
bunfig.toml
```
检测）。
然后仅加载
```
references/
```
下与任务相关的文件

Output Contract

输出约定

Report:

which references were loaded
the architecture pattern chosen
the change made
the verification run

报告：

加载了哪些参考内容
选择的架构模式
做出的变更
执行的验证