Node.js AsyncLocalStorage 解决了什么问题？

简化版

AsyncLocalStorage 用来在异步调用链中保存和读取上下文，比如请求 ID、用户信息、租户信息和链路追踪字段。它解决的是异步回调跨层传参麻烦的问题，但要注意上下文边界、内存泄漏和异步资源兼容性。

详细版

在 Node.js 服务里，一个请求会经过路由、中间件、数据库、RPC、日志等很多层。如果每层都手动传 requestId，代码会很吵。 AsyncLocalStorage 可以为一次异步调用链创建上下文，后续深层函数都能读取。

import { AsyncLocalStorage } from 'node:async_hooks'

const als = new AsyncLocalStorage<{ traceId: string }>()

app.use((req, res, next) => {
  als.run({ traceId: req.headers['x-trace-id'] as string }, next)
})

function log(message: string) {
  console.log(als.getStore()?.traceId, message)
}

它常用于日志串联和请求级上下文，不适合存放大对象或长期状态。

完整版教学

一、异步上下文难在调用栈会断

同步代码里，函数 A 调 B，B 调 C，参数可以沿调用栈一路传。 Node.js 服务大量依赖异步 I/O，一个请求进入后可能经历 Promise、定时器、数据库回调和网络回调。这时普通调用栈已经断开，想在任意深层函数拿到请求信息就麻烦了。

HTTP 请求
-> middleware 设置 traceId
-> await service()
-> await db.query()
-> logger.log()

logger 希望知道当前 traceId

如果每个函数都加一个 ctx 参数，10 层调用就要传 10 次。上下文参数会污染业务函数签名。 AsyncLocalStorage 的目标就是把“请求级上下文”从业务参数里拿出来。

二、AsyncLocalStorage 基于异步资源传播上下文

AsyncLocalStorage 来自 async_hooks 能力。你用 run(store, callback) 建立一个上下文，callback 内部创建的异步任务会继承这个上下文。后续通过 getStore() 就能读取当前上下文。

const storage = new AsyncLocalStorage<{ requestId: string }>()

storage.run({ requestId: 'req-1001' }, async () => {
  await Promise.resolve()
  console.log(storage.getStore()?.requestId) // req-1001
})

API	作用	常见注意点
`run(store, cb)`	创建上下文并执行回调	最常用
`getStore()`	读取当前上下文	没有上下文时返回 undefined
`enterWith(store)`	进入上下文	更容易污染后续流程
`disable()`	禁用实例	通常很少直接用

一个请求里可能打 30 条日志。如果每条日志都能自动带上同一个 requestId，排查问题会轻松很多。

三、它最常见的价值是日志和链路追踪

线上排障时，单条日志价值有限。你更需要把一次请求的所有日志串起来。 AsyncLocalStorage 可以让日志函数不用显式传参，也能拿到 traceId。

function info(msg: string, extra = {}) {
  const ctx = storage.getStore()
  console.log(JSON.stringify({
    level: 'info',
    traceId: ctx?.traceId,
    msg,
    ...extra
  }))
}

traceId=abc
├─ 收到请求
├─ 查询用户
├─ 调用支付服务
└─ 返回响应

假设系统每分钟 5000 个请求，没有 traceId 的日志就像一锅粥。有了请求级上下文，按 traceId 过滤就能看到完整路径。

四、它不是全局变量的安全替代品

AsyncLocalStorage 很像“异步调用链上的局部变量”，但不能把它当数据库或缓存。不要往上下文里塞大对象、连接对象、响应对象等长期引用。请求结束后上下文应自然释放，引用过大可能增加内存压力。

// 推荐：小而稳定的上下文字段
{ traceId, userId, tenantId }

// 谨慎：大对象或可变对象
{ req, res, hugePayload, dbConnection }

如果每个请求上下文多保存 200 KB，对 1000 个并发请求就是约 200 MB 引用压力。上下文应该短小，只放真正需要跨层读取的标识信息。

五、第三方库和异步边界要验证

现代 Promise、定时器、HTTP 等场景通常能正确传播上下文。但某些旧库、原生扩展或特殊异步封装可能破坏上下文链。如果发现日志里的 traceId 偶尔丢失，要检查异步资源边界。

正常传播:
run -> Promise -> await -> logger

可能异常:
run -> 非标准回调封装 -> logger 读不到 store

工程里最好写集成测试覆盖关键链路。例如 HTTP 请求进入、经过数据库和消息发送后，日志里仍能带上同一个 traceId。

六、和显式 ctx 参数并不是非此即彼

请求上下文适合横切关注点，比如日志、链路、租户。业务核心参数仍应显式传递。如果函数逻辑必须依赖 userId 做业务判断，显式参数通常更清楚。

记忆钩子：AsyncLocalStorage 适合“到处都要知道但不想层层传”的请求上下文。

面试回答时不要只说 API。要说明它解决异步调用链上下文传播，并补上内存、边界和日志追踪场景。

七、常见误区与追问

误区：AsyncLocalStorage 就是普通全局变量。 它是按异步调用链隔离的上下文，不同请求应读取到不同 store。
误区：上下文里可以随便放大对象。 大对象会延长引用链，增加内存压力，应只放 traceId、userId 等小字段。
误区：所有第三方库都会完美传播上下文。 特殊异步封装或旧库可能丢上下文，需要压测和集成验证。
追问：它常用于什么场景？ 日志 traceId、链路追踪、租户信息、请求级用户信息。
追问：为什么不用层层传 ctx？ 层层传参显式但侵入业务签名，横切字段会让函数参数变得嘈杂。
追问：没有上下文时 getStore 返回什么？ 返回 undefined，日志函数要做好兜底。

八、加强记忆

这题按“请求级上下文”记。Node 异步链路长，手动传 traceId 很烦；AsyncLocalStorage.run 建上下文，getStore 深层读取。它适合日志追踪这类横切字段，不适合大对象和长期状态。

简化版

详细版