Node.js 错误处理与日志工程：从异常到可观测

class AppError extends Error {
  constructor(statusCode, code, message, details) {
    super(message);
    this.statusCode = statusCode; // 400/401/403/404/500
    this.code = code;             // 业务错误码：USER_NOT_FOUND
    this.details = details;       // 额外上下文（可选）
    this.name = 'AppError';
    Error.captureStackTrace(this, this.constructor);
  }
}

throw new AppError(404, 'USER_NOT_FOUND', '用户不存在', { userId: 10086 });

function parseJSON(s) {
  try {
    return JSON.parse(s);
  } catch (e) {
    throw new AppError(400, 'BAD_JSON', 'JSON 格式错误', { input: s.slice(0, 100) });
  }
}

// async 函数里 await 的 reject 会进 try/catch
async function getUser(id) {
  try {
    const row = await db.find(id);
    if (!row) throw new AppError(404, 'USER_NOT_FOUND', '用户不存在');
    return row;
  } catch (e) {
    if (e instanceof AppError) throw e;   // 业务错误透传
    throw new AppError(500, 'DB_ERROR', '查询失败', { id }); // 基础设施错误包装
  }
}

// 未捕获的 Promise 异常
process.on('unhandledRejection', (reason) => {
  logger.error({ reason }, 'unhandled rejection');
  // 记录后决定：重试？重启？——至少不要静默
});

// 未捕获的同步异常
process.on('uncaughtException', (err) => {
  logger.fatal({ err }, 'uncaught exception');
  // 进程可能处于不安全状态：记录 + 优雅退出，由 PM2 拉起
  gracefulShutdown().finally(() => process.exit(1));
});

// 所有 throw 的异常最终汇到这里统一响应
app.use((err, req, res, next) => {
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      code: err.code,
      message: err.message,
      details: err.details,
      traceId: req.traceId,
    });
  }
  // 未知错误：记日志，返回统一 500（不泄露内部细节）
  logger.error({ err, url: req.url, traceId: req.traceId }, 'unhandled error');
  res.status(500).json({ code: 'INTERNAL_ERROR', message: '服务器内部错误', traceId: req.traceId });
});

// ✗ 路由里 await 抛错 → 直接未捕获，可能崩进程
app.get('/user/:id', async (req, res) => { throw new AppError(400, 'X', 'y'); });

// ✓ 包一层 wrapper，reject 转给 next
const wrap = (fn) => (req, res, next) => fn(req, res, next).catch(next);
app.get('/user/:id', wrap(async (req, res) => { ... }));

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const res = ctx.getResponse();
    if (exception instanceof AppError) {
      return res.status(exception.statusCode).json({ code: exception.code, message: exception.message });
    }
    return res.status(500).json({ code: 'INTERNAL_ERROR', message: '服务器内部错误' });
  }
}

{
  "code": "USER_NOT_FOUND",
  "message": "用户不存在",
  "traceId": "0a2b3c4d",
  "details": { "userId": 10086 }
}

export const ErrorCodes = {
  BAD_REQUEST: 400, USER_NOT_FOUND: 404, FORBIDDEN: 403,
  DB_ERROR: 500, TIMEOUT: 504, RATE_LIMITED: 429,
};

import pino from 'pino';
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  base: { app: 'order-service', env: process.env.NODE_ENV },
  // 生产直接 JSON，开发可配 pino-pretty
});

// 永远传对象，别字符串拼接（省序列化 + 字段可检索）
logger.info({ orderId, userId }, 'order created');
logger.error({ err, orderId }, 'create order failed');

// 入口中间件注入 traceId 到 request，并写入日志上下文
app.use((req, res, next) => {
  req.traceId = req.headers['x-trace-id'] || crypto.randomUUID();
  res.setHeader('x-trace-id', req.traceId);
  logger = logger.child({ traceId: req.traceId }); // Pino child 自动带上
  next();
});

Web 请求(带 traceId)
  → 网关/入口(生成 traceId，注入 header)
  → 服务A → 服务B（header 透传 x-trace-id）
  → DB / MQ（span 记录）
最终：一条 traceId 串起所有日志，日志平台按 traceId 检索即可还原完整调用链。

import * as Sentry from '@sentry/node';
Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 1.0 });

// 业务异常不要全上报（噪声），只上报"未知异常"
app.use((err, req, res, next) => {
  if (!(err instanceof AppError)) {
    Sentry.captureException(err, { extra: { url: req.url, traceId: req.traceId } });
  }
  next(err);
});