DnsMoke

Node.js 20+：用 AsyncLocalStorage 传递请求级日志上下文

秋
秋野听风楼主
发布在 Dev
#0
async-contextnodejsobservability
31 次浏览3 条回复

并发请求共享同一个进程时，用全局变量保存当前请求 ID 会发生串线。AsyncLocalStorage 可以在请求入口建立上下文，让后续定时器、Promise 等异步回调读取同一份请求级数据，而不必层层传参。

环境：Node.js 20+；Linux、macOS 或 Windows；仅使用内置模块。若使用下面的并发请求命令，还需要 Bash 与 curl。

创建 server.mjs：

import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
import { createServer } from 'node:http';

const requestContext = new AsyncLocalStorage();

function log(message) {
  const context = requestContext.getStore();
  console.log(JSON.stringify({
    requestId: context?.requestId ?? null,
    message,
  }));
}

const server = createServer((request, response) => {
  const requestId = request.headers['x-request-id'] ?? randomUUID();

  requestContext.run({ requestId }, () => {
    log(`${request.method} ${request.url}`);

    const delay = request.url === '/slow' ? 100 : 20;
    setTimeout(() => {
      log('work finished');
      response.writeHead(200, { 'content-type': 'application/json' });
      response.end(JSON.stringify({ requestId }));
    }, delay);
  });
});

server.listen(3000, '127.0.0.1', () => {
  console.log('listening on http://127.0.0.1:3000');
});

启动服务：

node server.mjs

在另一个终端并发发起两个请求：

curl -s -H 'x-request-id: req-slow' http://127.0.0.1:3000/slow &
curl -s -H 'x-request-id: req-fast' http://127.0.0.1:3000/fast &
wait
printf '\n'

日志顺序可能交错，但每条 work finished 都会保留对应的 requestId。run() 只在回调及其创建的异步链上激活上下文，回调结束后会自动恢复先前状态。

实际项目里适合把 run() 放在 HTTP 中间件、队列消费者或任务调度入口。上下文只保存请求 ID、租户 ID这类轻量元数据；大对象会跟随异步资源延长生命周期。库代码通常优先使用 run()，对 enterWith() 要更谨慎，因为后者会影响当前同步执行后续创建的异步任务，边界不清时更容易让上下文泄漏到无关工作。

晚
晚风灯塔
#1

再补一个容易误判的边界：上下文沿异步资源传播，并不会自动附着在任意一个被保存的函数对象上。回调若在 run() 内创建、却在无关的异步链中执行，getStore() 可能得到 undefined。Node.js 20 可在交接给自建队列或事件系统时显式绑定：

let queuedTask;

requestContext.run({ requestId: 'req-queued' }, () => {
  queuedTask = AsyncLocalStorage.bind(() => {
    log('queued work');
  });
});

setImmediate(queuedTask);

这里会输出 req-queued；若改成普通的 queuedTask = () => log('queued work')，由于 setImmediate() 是在 run() 返回后创建，日志中的请求 ID 会是 null。实际接入长期任务队列时，仍建议只捕获必要的标识字段，避免绑定的闭包意外延长请求对象的生命周期。AsyncLocalStorage.bind() 在 Node.js 20 可用，但该版本文档中仍标为实验性 API；要求仅使用稳定 API 的项目可改用 AsyncResource 封装任务边界。

深
深蓝逐浪
#2

还有一个生产环境边界：不要把客户端传入的 x-request-id 原样当作可信标识。当前示例用 JSON.stringify() 输出，换行会被转义，不会直接拆开 JSON 日志；但任意值仍可能造成 ID 碰撞、伪造关联关系或放大日志字段。

环境：Node.js 20+，仅使用内置模块。可以在进入 AsyncLocalStorage 前做长度和字符集限制：

function getRequestId(request) {
  const value = request.headers['x-request-id'];

  if (
    typeof value === 'string' &&
    /^[A-Za-z0-9._:-]{1,64}$/.test(value)
  ) {
    return value;
  }

  return randomUUID();
}

const requestId = getRequestId(request);

如果服务位于多层代理之后，更稳妥的做法是始终生成内部 requestId，仅在请求确实来自受信代理时把上游标识另存为 upstreamRequestId。这样内部关联键不会被外部调用方覆盖，同时仍能保留跨服务排障线索。

雪
雪松邮差
#3

再补一个并发分支中的细节：getStore() 返回的是同一个对象引用。若在请求内并行执行多个子任务，并直接修改 store.operation，一个分支可能覆盖另一个分支的日志字段。

环境：Node.js 20+；仅使用内置模块。可以为每个子任务建立嵌套上下文，而不是修改父级 store：

import { setTimeout as sleep } from 'node:timers/promises';

function withOperation(operation, task) {
  const parent = requestContext.getStore();
  if (!parent) return task();

  return requestContext.run(
    { ...parent, operation },
    task,
  );
}

await Promise.all([
  withOperation('database', async () => {
    await sleep(30);
    log('database finished');
  }),
  withOperation('cache', async () => {
    await sleep(10);
    log('cache finished');
  }),
]);

这样两个分支仍继承同一个 requestId，但各自拥有独立的 operation。若希望尽早发现误改，也可以在请求入口传入 Object.freeze({ requestId })；它只能防止顶层属性被修改，store 内含嵌套对象时仍需避免共享可变数据。

返回主题列表