使用AsyncLocalStorage可在Node.js中实现请求上下文跟踪，通过在中间件中调用asyncLocalStorage.run()为每个请求创建独立上下文，使后续异步操作能访问同一请求数据；结合日志系统可自动透传requestId等信息，实现全链路追踪与问题定位。
在Node.js中进行请求上下文跟踪，关键在于跨异步操作保持上下文一致性。虽然JavaScript的异步特性让传统同步跟踪方式失效，但通过利用 AsyncLocalStorage（Node.js 14+）这类异步钩子机制，可以实现安全、高效的请求级数据追踪。
什么是AsyncLocalStorage？
AsyncLocalStorage 是 Node.js 提供的一个类，用于在异步调用链中持久保存上下文数据。它基于异步_hooks 模块实现，能够在 Promise、setTimeout、事件循环等异步操作之间维持同一个逻辑请求上下文。
与 ThreadLocal 不同，Node.js 是单线程事件循环模型，因此 AsyncLocalStorage 跟踪的是“异步调用链”而非线程。每个请求进来时分配一个独立的上下文，后续所有由该请求触发的异步操作都能访问相同的上下文数据。
如何实现请求ID跟踪
最常见的使用场景是为每个HTTP请求生成唯一ID，并在整个处理链路中传递，便于日志关联和调试。
示例代码：
const { AsyncLocalStorage } = require('async_hooks');
const asyncLocalStorage = new AsyncLocalStorage();
function log(message) {
const store = asyncLocalStorage.getStore();
const requestId = store ? store.requestId : 'unknown';
console.log(`[${requestId}] ${message}`);
}
const express = require('express');
const app = express();
app.use((req, res, next) => {
const requestId = generateRequestId(); // 如：uuid 或 时间戳 + 随机数
asyncLocalStorage.run({ requestId }, () => {
log('Request started');
next();
});
});
app.get('/user', (req, res) => {
log('Fetching user data'); // 自动携带 requestId
setTimeout(() => {
log('User data fetched'); // 依然能访问 requestId
res.json({ id: 1, name: 'John' });
}, 100);
});
在这个例子中，asyncLocalStorage.run() 创建了一个带有初始存储对象的异步作用域。之后所有由该请求引发的异步操作（如 setTimeout、数据库查询、Promise.then）都能通过 getStore() 获取原始上下文。
结合日志系统做上下文透传
实际项目中，可将此机制集成到日志库中，自动注入请求ID、用户身份、接口路径等信息。
建议做法：
- 中间件中初始化上下文对象，包含 requestId、startTime、ip、url 等
- 封装统一的日志函数，自动读取当前上下文并格式化输出
- 在错误处理中间件中也能访问上下文，便于定位问题源头
- 调用下游服务时，可将 requestId 注入 header（如 X-Request-ID），实现全链路追踪
注意事项与限制
尽管 AsyncLocalStorage 很强大，但也需注意以下几点：
- 必须确保 asyncLocalStorage.run() 包裹了整个请求生命周期，否则后续操作无法访问上下文
- 不要在 run 回调外部引用 store 对象，因为其生命周期受异步链约束
- 避免在其中存储大量数据，影响内存和性能
- 某些库（如某些数据库驱动或任务队列）可能中断异步链，需手动绑定上下文
基本上就这些。只要合理使用 AsyncLocalStorage，在不侵入业务代码的前提下，就能实现轻量级的请求上下文跟踪，对排查问题和监控系统非常有帮助。
