如何在NodeJS中实现请求作用域日志？Winston元数据异常解决

问题背景 #

使用Winston以JSON格式记录日志到Graylog，需要包含以下请求元数据：

method: request.method,
request_uri: request.url,
request_ip: request.ip,
user_agent: request.headers['user-agent'],
referrer: request.headers['referrer'] || request.headers['referer'],
x_forwarded_for: request.headers['x-forwarded-for'],

尝试通过Express中间件将元数据注入Winston的defaultMeta，但出现元数据与请求不匹配的问题，经排查是request对象的上下文关联错误导致。

当前代码的核心问题 #

你提供的中间件存在两个致命问题：

1. 每次请求创建新Winston实例：不仅浪费资源，还会导致全局覆盖的console方法被后续请求的logger替换，日志元数据出现串位。
2. 静态defaultMeta无法动态更新：defaultMeta是创建logger时的固定值，无法随每个请求的request信息动态变化，即使每个请求新建logger，全局console的覆盖也会让日志和请求上下文脱节。

优化方案 #

方案1：全局单例Logger + AsyncLocalStorage追踪请求上下文 #

利用Node.js内置的AsyncLocalStorage实现请求上下文的隔离，确保每个请求的元数据能正确绑定到对应的日志。

步骤1：创建全局单例Logger

// src/utils/logger.ts
import * as winston from 'winston'
import { AsyncLocalStorage } from 'async_hooks'

// 初始化请求上下文存储
const asyncLocalStorage = new AsyncLocalStorage<Record<string, any>>()

// 全局单例Logger
export const logger = winston.createLogger({
  defaultMeta: { service: 'Front API' },
  level: 'http',
  format: winston.format.combine(
    // 动态注入请求元数据
    winston.format((info) => {
      const requestMeta = asyncLocalStorage.getStore()
      if (requestMeta) info.metadata = requestMeta
      return info
    })(),
    winston.format.errors({ stack: true }),
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [new winston.transports.Console()]
})

步骤2：编写Logger中间件

// src/middlewares/logger.middleware.ts
import { NextFunction, Request, Response } from 'express'
import { logger } from '../utils/logger'
import { AsyncLocalStorage } from 'async_hooks'

const asyncLocalStorage = new AsyncLocalStorage<Record<string, any>>()

export function loggerMiddleware(req: Request, res: Response, next: NextFunction) {
  // 收集当前请求的元数据
  const requestMeta = {
    method: req.method,
    request_uri: req.url,
    request_ip: req.ip,
    user_agent: req.headers['user-agent'],
    referrer: req.headers['referrer'] || req.headers['referer'],
    x_forwarded_for: req.headers['x-forwarded-for']
  }

  // 将元数据存入请求上下文
  asyncLocalStorage.enterWith(requestMeta)

  // 重写console方法（可选，若业务代码依赖console）
  const bindConsole = (level: string) => (...args: any[]) => {
    try {
      logger[level](args.join(' '))
    } catch (e) {
      logger[level](...args)
    }
  }

  console.http = bindConsole('http')
  console.log = bindConsole('info')
  console.info = bindConsole('info')
  console.warn = bindConsole('warn')
  console.error = bindConsole('error')
  console.debug = bindConsole('debug')

  next()
}

步骤3：在Express中使用中间件

// src/app.ts
import express from 'express'
import { loggerMiddleware } from './middlewares/logger.middleware'

const app = express()

// 全局注册Logger中间件（需在路由之前）
app.use(loggerMiddleware)

// 业务路由
app.get('/api/test', (req, res) => {
  // 直接调用logger或console，自动携带请求元数据
  logger.info('Test API accessed')
  console.log('Console log with request meta')
  res.send('OK')
})

app.listen(3000)

方案2：手动传入请求元数据（更轻量） #

如果不想使用AsyncLocalStorage，可以在日志时手动传入请求元数据，适合小型项目：

步骤1：全局Logger

// src/utils/logger.ts
import * as winston from 'winston'

export const logger = winston.createLogger({
  defaultMeta: { service: 'Front API' },
  level: 'http',
  format: winston.format.combine(
    winston.format.errors({ stack: true }),
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [new winston.transports.Console()]
})

// 封装带请求元数据的日志方法
export const logWithReq = (req: Request, level: string, message: string) => {
  const meta = {
    method: req.method,
    request_uri: req.url,
    request_ip: req.ip,
    user_agent: req.headers['user-agent'],
    referrer: req.headers['referrer'] || req.headers['referer'],
    x_forwarded_for: req.headers['x-forwarded-for']
  }
  logger.log(level, message, { metadata: meta })
}

步骤2：业务代码中使用

// src/routes/test.ts
import { Request, Response } from 'express'
import { logWithReq } from '../utils/logger'

export const testRoute = (req: Request, res: Response) => {
  logWithReq(req, 'info', 'Test API accessed')
  res.send('OK')
}

关键优化点 #

• 全局单例Logger：避免重复初始化，提升性能，减少实例冲突。
• 请求上下文隔离：用AsyncLocalStorage确保并发请求的元数据不会串位，彻底解决日志与请求不匹配的问题。
• 避免全局污染：推荐直接调用封装的日志方法，而非覆盖全局console；若必须覆盖，结合上下文隔离确保正确性。

内容的提问来源于stack exchange，提问作者Tomasz Szymanek