本教程详细介绍了如何在winston.js日志系统中拦截日志并注入自定义参数，例如为每条日志添加关联id。通过创建winston自定义格式（`winston.format`），我们可以访问并修改日志的`info`对象，从而在日志输出前动态添加所需数据，实现日志追踪和上下文关联，提升日志的可观测性。
在复杂的分布式系统中，日志的追踪和关联性变得尤为重要。当一个请求流经多个服务时，如果每条日志都能带上一个唯一的关联ID（Correlation ID），将极大方便问题的诊断和流程的追踪。Winston.js作为Node.js中流行的日志库，提供了强大的可扩展性，允许我们通过自定义格式（Formats）来拦截并修改日志内容，从而实现诸如注入关联ID这样的需求。
Winston.js格式化机制概述
Winston的核心功能之一是其灵活的格式化系统。日志在被传输到各种传输器（Transports，如控制台、文件、数据库等）之前，会经过一系列格式化处理。这些格式化器可以对日志的元数据进行操作，例如添加时间戳、颜色、JSON序列化等。
每个日志条目在Winston内部都表示为一个info对象，它至少包含level（日志级别，如'info'、'error'）和message（日志消息）。自定义格式函数接收这个info对象作为参数，并期望返回一个修改后的info对象。
实现自定义日志参数注入
要实现日志参数的注入，我们需要创建一个自定义的Winston格式函数。这个函数将拦截日志流，并在info对象中添加我们所需的参数。
1. 创建自定义格式函数
以下是一个用于注入关联ID的自定义格式函数示例：
import winston from 'winston';
// 假设 correlator 是一个用于获取当前请求关联ID的库或模块
// 例如：const correlator = require('express-winston-correlation-id');
// 或者自定义一个全局上下文管理器
const correlator = {
getId: () => {
// 实际应用中，这里会从请求上下文、异步本地存储（AsyncLocalStorage）等获取ID
// 示例中返回一个模拟ID
return Math.random().toString(36).substring(2, 15);
}
};
/**
* Winston自定义格式：注入关联ID到日志信息中。
* @param {object} info - Winston日志的info对象。
* @returns {object} - 包含关联ID的info对象。
*/
export const correlationInjection = winston.format(info => {
// 从 correlator 获取当前的关联ID
const correlationId = correlator.getId();
if (correlationId) {
// 将关联ID添加到info对象中
info.correlationId = correlationId;
}
// 必须返回修改后的info对象
return info;
});代码解析：
- winston.format(info => { ... }): 这是Winston提供的一个工厂函数，用于创建自定义格式。它接收一个函数作为参数，该函数会在每个日志条目被处理时执行。
- info: 这是当前日志条目的元数据对象。它包含了日志级别、消息以及任何其他通过logger.log()或logger.info()传递的额外数据。
- correlator.getId(): 这是一个占位符，代表你的应用程序中获取当前请求或操作关联ID的逻辑。在实际应用中，这可能是一个从AsyncLocalStorage、cls-hooked或其他上下文管理库中获取ID的方法。
- info.correlationId = correlationId;: 如果获取到了关联ID，我们将其作为correlationId属性添加到info对象中。
- return info;: 至关重要，自定义格式函数必须返回修改后的info对象，以便后续的格式化器和传输器能够处理它。
2. 集成到Winston日志器
创建了自定义格式后，我们需要将其添加到Winston日志器的format配置中。通常，我们会使用winston.format.combine()来组合多个格式。
import winston from 'winston';
import { correlationInjection } from './correlationInjection'; // 假设自定义格式在单独的文件中
// 创建一个Winston日志器实例
const logger = winston.createLogger({
level: 'info', // 设置日志级别
format: winston.format.combine(
correlationInjection(), // 首先应用我们的自定义注入格式
winston.format.timestamp(), // 添加时间戳
winston.format.json() // 将日志输出为JSON格式
// 还可以添加其他格式，例如 winston.format.colorize() 等
),
transports: [
new winston.transports.Console() // 输出到控制台
// new winston.transports.File({ filename: 'combined.log' }) // 输出到文件
]
});
// 示例日志输出
logger.info('这是一个普通的信息日志');
logger.error('发生了一个错误', { errorCode: 500 });
// 模拟不同的关联ID
correlator.getId = () => 'req-123';
logger.info('这是请求123的日志');
correlator.getId = () => 'req-456';
logger.warn('这是请求456的警告日志', { component: 'auth' });运行上述代码，你将在控制台看到类似以下的JSON格式输出：
{"level":"info","message":"这是一个普通的信息日志","timestamp":"2023-10-27T10:00:00.000Z","correlationId":"<随机生成的ID>"}
{"level":"error","message":"发生了一个错误","errorCode":500,"timestamp":"2023-10-27T10:00:00.000Z","correlationId":"<随机生成的ID>"}
{"level":"info","message":"这是请求123的日志","timestamp":"2023-10-27T10:00:00.000Z","correlationId":"req-123"}
{"level":"warn","message":"这是请求456的警告日志","component":"auth","timestamp":"2023-10-27T10:00:00.000Z","correlationId":"req-456"}可以看到，每条日志都被成功注入了correlationId。
注意事项与最佳实践
- 格式顺序的重要性： 在winston.format.combine()中，格式的顺序非常重要。通常，像correlationInjection这种需要修改info对象内容的格式应该放在其他处理格式（如timestamp()、json()）之前，以确保它们能处理到最新的info对象。
-
correlator.getId()的实现： 示例中的correlator.getId()是一个简化的模拟。在实际的Web应用中，你需要一个可靠的机制来在请求的整个生命周期中维护和获取关联ID。常用的方法包括：
- AsyncLocalStorage (Node.js 14+): Node.js原生的异步上下文管理API，非常适合在异步操作链中传递上下文数据。
- cls-hooked 或 continuation-local-storage： 社区提供的库，用于在早期Node.js版本中实现类似AsyncLocalStorage的功能。
- 请求头： 从传入的HTTP请求头中获取关联ID，并在响应中返回。
-
通用性： 这种注入参数的方法不限于关联ID。你可以注入任何你希望在每条日志中出现的上下文信息，例如：
- 请求的用户ID
- 请求的URL或路径
- 当前的服务版本
- 环境信息（开发、生产）
- 性能考虑： 自定义格式函数会在每次日志调用时执行。对于简单的属性添加，性能开销通常可以忽略不计。但如果你的格式函数执行了复杂的计算或I/O操作，可能会对日志性能产生影响。
- 错误处理： 在自定义格式函数中，如果获取关联ID的逻辑可能失败，应考虑添加错误处理，确保不会阻止日志的正常输出。
总结
通过Winston.js的自定义格式机制，我们可以优雅地拦截日志流并注入额外的上下文信息，如关联ID。这不仅提高了日志的可观测性和可追踪性，也使得复杂的分布式系统调试工作变得更加高效。掌握这一技巧，能让你更好地利用Winston.js来构建健壮且易于维护的日志系统。
