AsyncLocalStorage 是解决 Node.js 跨中间件传递请求 ID 的核心方案，它为每个请求提供独立上下文容器，确保异步操作中 ID 不丢失、不污染、不手动传。
在大型 Node.js 项目中，跨中间件传递请求 ID 的核心难点不是“怎么生成 ID”，而是“如何让 ID 不丢失、不污染、不手动传”。AsyncLocalStorage 正是为解决这个问题而生——它让每个请求拥有自己独立的上下文容器，所有由该请求触发的异步操作（无论嵌套多深、经过多少 Promise 或 setTimeout）都能自动读取同一份数据。
为什么不能靠中间件挂载 req 属性？
Express/Koa 的 req 对象只在当前中间件链中可用。一旦进入数据库查询、日志写入、微服务调用等异步环节，req 就无法自然延续。常见错误方式包括：
- 用全局变量存
currentRequestId→ 并发请求互相覆盖 - 层层手动透传
requestId参数 → Controller → Service → Repository 每层都要改，耦合高、易遗漏 - 依赖闭包捕获 → 无法跨模块复用，测试困难，内存泄漏风险高
标准接入流程（以 Express 为例）
只需三步，即可让整个请求生命周期内任意位置安全获取 requestId：
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
-
初始化存储实例：在应用启动时创建单例
AsyncLocalStorage -
入口拦截注入：在首个中间件中调用
asyncLocalStorage.run({ requestId }, next)，包裹后续全部逻辑 -
任意位置消费：在日志函数、DB 工具、API 客户端里直接调用
asyncLocalStorage.getStore()?.requestId
示例日志封装：
const { AsyncLocalStorage } = require('node:async_hooks');const asyncLocalStorage = new AsyncLocalStorage();
function log(msg) {
const ctx = asyncLocalStorage.getStore();
console.log(`[${ctx?.requestId || 'N/A'}] ${msg}`);
}
与日志系统深度集成的关键细节
单纯存 ID 不够，要让它真正“自动生效”：
- 替换默认
console.log或封装winston.info()，内部统一读取getStore() - 在数据库连接池的 query hook 中注入
ctx.requestId，让慢查询日志自带追踪标识 - 对外 HTTP 请求头自动添加
X-Request-ID，下游服务也能延续上下文（需对方支持） - 避免在
run()外部调用getStore()，返回undefined是正常行为，不是 bug
常见陷阱与规避方式
AsyncLocalStorage 表现稳定，但实际落地时容易踩坑：
-
未 await 异步操作就退出上下文：比如在
run()内部调用了setTimeout或未 await 的 Promise，但回调执行时上下文已销毁 → 解决方法：确保所有异步逻辑都在run()包裹的 callback 内发起，或使用enterWith()显式恢复 -
Worker 线程或子进程不共享上下文：AsyncLocalStorage 仅限当前线程，跨线程需手动序列化/反序列化上下文并重新
run() -
错误地复用 store 对象：不要把
getStore()返回的对象缓存或修改，它是只读快照；如需扩展字段，应在run()时传入新对象
