本文深入探讨如何在winston.js日志系统中通过自定义格式（format）实现日志信息的拦截与动态参数注入。通过创建自定义格式函数，开发者可以在日志被记录前，对日志对象（info）进行修改和扩展，例如注入关联id（correlationid）等上下文信息，从而极大地提升日志的可追溯性和分析能力，确保每条日志都承载了丰富的诊断数据。

理解winston.JS的日志格式机制

Winston.js是一个功能强大且高度可配置的node.js日志库。其核心特性之一是“格式”（Formats），它允许开发者在日志信息被传输到目标（如控制台、文件）之前，对其进行转换和处理。每个日志消息在Winston内部表示为一个包含至少level和message属性的info对象。通过自定义格式，我们可以在这个info对象上执行任意操作，包括添加、修改或删除属性。

当我们需要为每条日志注入特定的上下文信息，例如请求的关联ID（correlationId）、用户ID或会话ID时，自定义格式就成为了一个理想的解决方案。这种机制允许我们以非侵入式的方式，在不修改原有日志调用代码的前提下，统一增强日志内容。

实现自定义格式进行参数注入

要拦截Winston日志并注入自定义参数，我们需要创建一个返回格式函数的函数。这个格式函数会接收日志的info对象作为参数，并期望返回修改后的info对象。

以下是一个示例，展示如何注入一个假设的correlationId：

import winston from 'winston'; // 假设 correlator 是一个用于获取当前请求关联ID的库 // 例如：import correlator from 'express-correlation-id'; // 在实际应用中，你需要根据自己的上下文管理方案来实现 correlator.getId() const correlator = {   getId: () => 'req-1234567890' // 示例函数，实际应获取动态ID };  /**  * 创建一个Winston自定义格式，用于注入关联ID。  * @returns {winston.Format} 一个Winston格式函数。  */ export const correlationInjection = winston.format((info) => {   // 检查 info 对象是否已存在 correlationId，避免重复注入或覆盖   if (!info.correlationId) {     info.correlationId = correlator.getId();   }   return info; });

在这个correlationInjection格式中：

微信 WeLM

WeLM不是一个直接的对话机器人，而是一个补全用户输入信息的生成模型。

33

查看详情

1. winston.format() 是Winston提供的一个高阶函数，用于创建自定义格式。它接收一个转换函数作为参数。
2. 转换函数接收一个info对象。这个info对象包含了当前的日志级别、消息以及任何其他元数据。
3. info.correlationId = correlator.getId();：这是核心的注入逻辑。我们调用correlator.getId()来获取当前的关联ID，并将其作为新属性correlationId添加到info对象上。
4. return info;：修改后的info对象必须被返回，以便后续的格式或传输器能够处理它。

将自定义格式集成到Winston Logger中

创建了自定义格式之后，下一步是将其集成到Winston的日志器配置中。这通常通过winston.format.combine()函数实现，该函数允许你按顺序组合多个格式。

import winston from 'winston'; import { correlationInjection } from './correlationInjection.js'; // 导入上面定义的格式  // 配置Winston Logger const logger = winston.createLogger({   level: 'info', // 设置日志级别   format: winston.format.combine(     correlationInjection(), // 首先应用我们的自定义注入格式     winston.format.timestamp({ format: 'yyYY-MM-DD HH:mm:ss' }), // 添加时间戳     winston.format.errors({ stack: true }), // 捕获错误堆栈     winston.format.colorize(), // 为控制台输出着色     winston.format.printf(({ level, message, timestamp, correlationId, stack }) => {       // 在printf中，我们可以访问到注入的 correlationId       let logMessage = `${timestamp} [${level}]`;       if (correlationId) {         logMessage += ` [${correlationId}]`;       }       logMessage += `: ${message}`;       if (stack) {         logMessage += `n${stack}`;       }       return logMessage;     })   ),   transports: [     new winston.transports.Console() // 输出到控制台     // 也可以添加其他传输器，如文件传输     // new winston.transports.File({ filename: 'combined.log' })   ], });  // 示例日志输出 logger.info('这是一个普通的信息日志。'); logger.error(new Error('这是一个带有堆栈的错误日志。')); logger.debug('调试信息，仅在level为debug或更低时显示。');  // 模拟不同请求的关联ID（在实际应用中，correlator.getId()会动态变化） correlator.getId = () => 'req-abcdefg'; logger.info('这是另一个请求的日志。');

在上述配置中：

1. winston.format.combine(…)：用于将多个格式按顺序链式应用。
2. correlationInjection()：我们的自定义格式被放置在链的开头。这意味着它会在其他格式（如timestamp、errors、printf）处理info对象之前，先将correlationId注入进去。
3. winston.format.printf(…)：这是一个强大的格式，允许你完全自定义日志的最终输出字符串。在这里，我们修改了输出模板，使其能够包含correlationId。

注意事项与最佳实践

• 格式顺序至关重要：在winston.format.combine()中，格式的应用是严格按照从左到右的顺序进行的。如果你的自定义格式需要依赖其他格式生成的数据，或者其输出会被后续格式消费，则需要合理安排它们的顺序。例如，correlationInjection应该在printf之前，以便printf能访问到correlationId。
• 避免副作用：在自定义格式中，尽量只修改info对象本身，避免对全局状态或外部变量产生不必要的副作用，以保持代码的清晰和可维护性。
• 错误处理：如果你的注入逻辑可能抛出错误，考虑在自定义格式内部进行错误捕获，以防止日志系统崩溃。
• 性能考量：对于简单的属性注入，性能开销通常可以忽略不计。但如果你的自定义格式执行了复杂的计算或I/O操作，可能会影响日志记录的性能，此时应进行性能评估。
• correlator的实现：示例中的correlator.getId()是一个占位符。在真实的Web应用中，correlationId通常通过中间件在请求开始时生成并存储在AsyncLocalStorage或类似的机制中，以便在整个请求生命周期中都能访问到。

总结

通过Winston.js的自定义格式机制，我们可以优雅且高效地实现日志信息的拦截和参数注入。这种方法不仅使得日志内容更加丰富和具有上下文，极大地提升了日志的可追溯性和故障诊断效率，同时也保持了日志记录代码的整洁和解耦。掌握自定义格式的使用，是深入利用Winston.js强大功能的关键一步。