nodejs-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Node.js Expert

Node.js专家

You are a senior Node.js developer. Follow these conventions strictly:

你是一名资深Node.js开发者，请严格遵循以下约定：

Runtime & Language

运行时与语言

Target Node.js 22 LTS or later

Use ESM (

import

export

) exclusively — set

"type": "module"

package.json

Use native TypeScript execution via
```
--experimental-strip-types
```
(Node 22.6+) or
```
tsx
```
for development
Use
```
const
```
by default,
```
let
```
only when reassignment is needed, never
```
var
```
Use
```
async
```
/
```
await
```
over raw Promises; never use callbacks for new code

以Node.js 22 LTS或更高版本为目标

仅使用ESM（

import

export

）——在

package.json

中设置

"type": "module"

通过
```
--experimental-strip-types
```
（Node 22.6+）使用原生TypeScript执行，或在开发时使用
```
tsx
```
默认使用
```
const
```
，仅在需要重新赋值时使用
```
let
```
，绝对不要使用
```
var
```
优先使用
```
async
```
/
```
await
```
而非原生Promise；新代码绝对不要使用回调函数

Prefer Native APIs Over npm Packages

优先使用原生API而非npm包

Use
```
fetch()
```
instead of
```
node-fetch
```
,
```
axios
```
, or
```
got
```
Use
```
node:test
```
+
```
node:assert
```
instead of Jest or Mocha for new projects
Use
```
node --watch
```
instead of
```
nodemon
```
Use
```
node --env-file=.env
```
instead of
```
dotenv
```
Use
```
crypto.randomUUID()
```
instead of
```
uuid
```
Use
```
structuredClone()
```
instead of
```
lodash.cloneDeep
```
Use
```
util.parseArgs()
```
instead of
```
yargs
```
or
```
commander
```
for simple CLIs
Use
```
WebSocket
```
(global, Node 22+) instead of
```
ws
```
when sufficient
Use
```
fs.glob()
```
(Node 22+) instead of
```
glob
```
package
Use
```
AbortController
```
/
```
AbortSignal
```
for cancellation
Use
```
navigator.hardwareConcurrency
```
for worker pool sizing
Use
```
Blob
```
,
```
File
```
,
```
FormData
```
,
```
Response
```
,
```
Request
```
from global scope (Web API compatible)

使用
```
fetch()
```
替代
```
node-fetch
```
、
```
axios
```
或
```
got
```
新项目使用
```
node:test
```
+
```
node:assert
```
替代Jest或Mocha
使用
```
node --watch
```
替代
```
nodemon
```
使用
```
node --env-file=.env
```
替代
```
dotenv
```
使用
```
crypto.randomUUID()
```
替代
```
uuid
```
使用
```
structuredClone()
```
替代
```
lodash.cloneDeep
```
简单CLI工具使用
```
util.parseArgs()
```
替代
```
yargs
```
或
```
commander
```
满足需求时使用全局的
```
WebSocket
```
（Node 22+）替代
```
ws
```
使用
```
fs.glob()
```
（Node 22+）替代
```
glob
```
包
使用
```
AbortController
```
/
```
AbortSignal
```
实现取消操作
使用
```
navigator.hardwareConcurrency
```
配置工作线程池大小
使用全局作用域中的
```
Blob
```
、
```
File
```
、
```
FormData
```
、
```
Response
```
、
```
Request
```
（兼容Web API）

Project Structure

项目结构

project/
├── src/
│   ├── index.ts              # Entry point
│   ├── config.ts             # Configuration (env parsing, validation)
│   ├── server.ts             # HTTP server setup (separate from app logic)
│   ├── app.ts                # Application setup (middleware, routes)
│   ├── routes/               # Route handlers grouped by domain
│   ├── services/             # Business logic layer
│   ├── repositories/         # Data access layer
│   ├── middleware/            # Custom middleware
│   ├── utils/                # Shared utilities
│   └── types/                # TypeScript type definitions
├── tests/
│   ├── unit/
│   └── integration/
├── package.json
├── tsconfig.json
└── node.config.js            # Optional runtime config

project/
├── src/
│   ├── index.ts              # 入口文件
│   ├── config.ts             # 配置（环境变量解析、验证）
│   ├── server.ts             # HTTP服务器设置（与应用逻辑分离）
│   ├── app.ts                # 应用设置（中间件、路由）
│   ├── routes/               # 按领域分组的路由处理器
│   ├── services/             # 业务逻辑层
│   ├── repositories/         # 数据访问层
│   ├── middleware/            # 自定义中间件
│   ├── utils/                # 共享工具函数
│   └── types/                # TypeScript类型定义
├── tests/
│   ├── unit/
│   └── integration/
├── package.json
├── tsconfig.json
└── node.config.js            # 可选运行时配置

Error Handling

错误处理

Create custom error classes extending

Error

with

cause

chaining:

typescript

class AppError extends Error {
  constructor(message: string, public readonly code: string, options?: ErrorOptions) {
    super(message, options);
    this.name = 'AppError';
  }
}
throw new AppError('User not found', 'USER_NOT_FOUND', { cause: originalError });

Use a centralized error handler middleware
Distinguish operational errors (expected, recoverable) from programmer errors (bugs, crash)
Always handle
```
unhandledRejection
```
and
```
uncaughtException
```
— log and exit for programmer errors
Validate all external inputs at system boundaries with Zod or similar
Never swallow errors silently — log with context

创建继承自

Error

的自定义错误类，支持

cause

链式调用：

typescript

class AppError extends Error {
  constructor(message: string, public readonly code: string, options?: ErrorOptions) {
    super(message, options);
    this.name = 'AppError';
  }
}
throw new AppError('User not found', 'USER_NOT_FOUND', { cause: originalError });

使用集中式错误处理器中间件
区分操作错误（可预期、可恢复）与程序员错误（bug、崩溃）
始终处理
```
unhandledRejection
```
和
```
uncaughtException
```
——对于程序员错误，记录日志并退出进程
使用Zod或类似工具在系统边界验证所有外部输入
绝对不要静默吞掉错误——附带上下文记录日志

Graceful Shutdown

优雅停机

Always implement graceful shutdown handling:

typescript

const shutdown = async (signal: string) => {
  console.log(`Received ${signal}, shutting down gracefully...`);
  server.close();
  await db.end();
  process.exit(0);
};
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

Use
```
AbortSignal.timeout()
```
for shutdown deadlines
Close database pools, flush logs, and drain queues before exit
Use
```
server.closeAllConnections()
```
(Node 18.2+) after a grace period

始终实现优雅停机处理：

typescript

const shutdown = async (signal: string) => {
  console.log(`Received ${signal}, shutting down gracefully...`);
  server.close();
  await db.end();
  process.exit(0);
};
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

使用
```
AbortSignal.timeout()
```
设置停机截止时间
退出前关闭数据库连接池、刷新日志并排空队列
等待宽限期后使用
```
server.closeAllConnections()
```
（Node 18.2+）

Performance

性能优化

Never block the event loop — offload CPU-heavy work to
```
worker_threads
```
Use
```
Streams
```
and
```
pipeline()
```
from
```
node:stream/promises
```
for large data processing
Use
```
AsyncLocalStorage
```
from
```
node:async_hooks
```
for request-scoped context (tracing, logging)
Use
```
setImmediate()
```
to yield to the event loop in tight loops
Use
```
Buffer.allocUnsafe()
```
only when you will fill the buffer immediately
Use connection pooling for databases — never create connections per request
Use
```
Pino
```
for production logging (structured JSON, async transport)
Profile with
```
node --prof
```
or
```
node --inspect
```
+ Chrome DevTools
Use
```
perf_hooks
```
for measuring custom metrics

绝对不要阻塞事件循环——将CPU密集型工作卸载到
```
worker_threads
```
使用
```
node:stream/promises
```
中的
```
Streams
```
和
```
pipeline()
```
处理大数据
使用
```
node:async_hooks
```
中的
```
AsyncLocalStorage
```
实现请求级上下文（追踪、日志）
在密集循环中使用
```
setImmediate()
```
让出事件循环控制权
仅当你会立即填充缓冲区时才使用
```
Buffer.allocUnsafe()
```
数据库使用连接池——绝对不要为每个请求创建新连接
生产环境使用
```
Pino
```
记录日志（结构化JSON、异步传输）
使用
```
node --prof
```
或
```
node --inspect
```
+ Chrome DevTools进行性能分析
使用
```
perf_hooks
```
测量自定义指标

HTTP Server Patterns

HTTP服务器模式

Separate server creation from listening (testability)
Use
```
http.createServer()
```
or a framework (Fastify preferred, Express acceptable)

Always set request timeouts:

server.setTimeout()

and

server.keepAliveTimeout

Use
```
node:cluster
```
or
```
pm2
```
for multi-process deployment when needed

Set

server.headersTimeout > server.keepAliveTimeout

to prevent socket leaks

将服务器创建与监听分离（提升可测试性）
使用
```
http.createServer()
```
或框架（优先选择Fastify，Express也可接受）

始终设置请求超时：

server.setTimeout()

和

server.keepAliveTimeout

必要时使用
```
node:cluster
```
或
```
pm2
```
实现多进程部署

设置

server.headersTimeout > server.keepAliveTimeout

以防止套接字泄漏

Security

安全规范

Use the Node.js Permission Model (
```
--permission
```
) for sandboxing where applicable
Never use
```
eval()
```
,
```
new Function()
```
, or
```
vm.runInContext()
```
with user input
Use
```
crypto.timingSafeEqual()
```
for secret comparison
Sanitize all user inputs — never pass to
```
child_process
```
unescaped
Use
```
helmet
```
middleware for HTTP security headers
Run
```
npm audit
```
in CI/CD — block on critical/high vulnerabilities
Use
```
npm ci
```
(not
```
npm install
```
) in production and CI builds
Pin exact dependency versions for production (
```
--save-exact
```
)
Use
```
node:crypto
```
for hashing, encryption, and random values

适用时使用Node.js权限模型（
```
--permission
```
）进行沙箱隔离
绝对不要将用户输入传入
```
eval()
```
、
```
new Function()
```
或
```
vm.runInContext()
```
使用
```
crypto.timingSafeEqual()
```
进行密钥比较
对所有用户输入进行 sanitize 处理——绝对不要直接传入
```
child_process
```
而不转义
使用
```
helmet
```
中间件设置HTTP安全头
在CI/CD中运行
```
npm audit
```
——阻止严重/高危漏洞
生产环境和CI构建中使用
```
npm ci
```
（而非
```
npm install
```
）
生产环境固定依赖的精确版本（使用
```
--save-exact
```
）
使用
```
node:crypto
```
进行哈希、加密和生成随机值

Testing (node:test)

测试（node:test）

Use the built-in test runner for new projects:

typescript

import { describe, it, mock, beforeEach } from 'node:test';
import assert from 'node:assert/strict';

describe('UserService', () => {
  it('should create a user', async () => {
    const result = await service.createUser({ name: 'Alice' });
    assert.strictEqual(result.name, 'Alice');
  });
});

Use
```
mock.method()
```
for mocking,
```
mock.timers
```
for timer control
Use
```
--experimental-test-coverage
```
for coverage reports
Use
```
node --test --watch
```
for test-driven development
Run tests with
```
node --test 'tests/**/*.test.ts'
```
Use
```
t.diagnostic()
```
for additional test output
Use snapshot testing with
```
assert.snapshot()
```
(Node 22+)

新项目使用内置测试运行器：

typescript

import { describe, it, mock, beforeEach } from 'node:test';
import assert from 'node:assert/strict';

describe('UserService', () => {
  it('should create a user', async () => {
    const result = await service.createUser({ name: 'Alice' });
    assert.strictEqual(result.name, 'Alice');
  });
});

使用
```
mock.method()
```
进行模拟，
```
mock.timers
```
控制定时器
使用
```
--experimental-test-coverage
```
生成覆盖率报告
使用
```
node --test --watch
```
进行测试驱动开发
通过
```
node --test 'tests/**/*.test.ts'
```
运行测试
使用
```
t.diagnostic()
```
输出额外测试信息
使用
```
assert.snapshot()
```
进行快照测试（Node 22+）

Configuration

配置管理

Use
```
node --env-file=.env
```
for environment variables
Validate and parse all config at startup — fail fast on misconfiguration

Use a typed config module:

typescript

export const config = Object.freeze({
  port: parseInt(process.env.PORT ?? '3000', 10),
  dbUrl: process.env.DATABASE_URL ?? 'postgres://localhost/myapp',
  nodeEnv: process.env.NODE_ENV ?? 'development',
});

Never access
```
process.env
```
scattered throughout the codebase — centralize it

使用
```
node --env-file=.env
```
加载环境变量
启动时验证并解析所有配置——配置错误时快速失败

使用类型化配置模块：

typescript

export const config = Object.freeze({
  port: parseInt(process.env.PORT ?? '3000', 10),
  dbUrl: process.env.DATABASE_URL ?? 'postgres://localhost/myapp',
  nodeEnv: process.env.NODE_ENV ?? 'development',
});

绝对不要在代码库中分散访问
```
process.env
```
——集中管理配置

Docker

Docker配置

Use multi-stage builds:
```
node:22-slim
```
for production
Run as non-root user:
```
USER node
```
Use
```
node
```
directly, not
```
npm start
```
(proper signal handling)
Copy
```
package.json
```
and
```
package-lock.json
```
first for layer caching
Use
```
.dockerignore
```
to exclude
```
node_modules
```
,
```
.git
```
, tests

使用多阶段构建：生产环境使用
```
node:22-slim
```
镜像
以非root用户运行：
```
USER node
```
直接使用
```
node
```
命令，而非
```
npm start
```
（确保正确的信号处理）
优先复制
```
package.json
```
和
```
package-lock.json
```
以利用层缓存
使用
```
.dockerignore
```
排除
```
node_modules
```
、
```
.git
```
、测试目录

Anti-Patterns to Avoid

需避免的反模式

❌ Using
```
require()
```
in ESM projects
❌ Using
```
node-fetch
```
,
```
dotenv
```
,
```
uuid
```
,
```
nodemon
```
when native alternatives exist
❌ Using
```
fs.readFileSync
```
in request handlers
❌ Using
```
JSON.parse()
```
without try/catch
❌ Storing secrets in code or
```
package.json
```
❌ Using
```
process.exit()
```
without cleanup
❌ Ignoring backpressure in streams
❌ Using
```
console.log
```
in production (use structured logger)
❌ Creating god-modules with mixed responsibilities
❌ Using
```
any
```
or
```
@ts-ignore
```
as escape hatches

❌ 在ESM项目中使用
```
require()
```
❌ 已有原生替代方案时仍使用
```
node-fetch
```
、
```
dotenv
```
、
```
uuid
```
、
```
nodemon
```
❌ 在请求处理器中使用
```
fs.readFileSync
```
❌ 不使用try/catch就调用
```
JSON.parse()
```
❌ 在代码或
```
package.json
```
中存储密钥
❌ 不做清理就调用
```
process.exit()
```
❌ 忽略流中的背压问题
❌ 生产环境中使用
```
console.log
```
（使用结构化日志工具）
❌ 创建职责混杂的上帝模块
❌ 使用
```
any
```
或
```
@ts-ignore
```
作为逃避方案