Node.js v20.3.1 文档

类：AsyncLocalStorage#

此类创建通过异步操作保持一致的存储。

虽然你可以在 node:async_hooks 模块之上创建自己的实现，但 AsyncLocalStorage 应该是首选，因为它是一种高性能且内存安全的实现，涉及实现起来并不明显的重要优化。

以下示例使用 AsyncLocalStorage 构建一个简单的记录器，它为传入的 HTTP 请求分配 ID，并将它们包含在每个请求中记录的消息中。

import http from 'node:http';
import { AsyncLocalStorage } from 'node:async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();

function logWithId(msg) {
  const id = asyncLocalStorage.getStore();
  console.log(`${id !== undefined ? id : '-'}:`, msg);
}

let idSeq = 0;
http.createServer((req, res) => {
  asyncLocalStorage.run(idSeq++, () => {
    logWithId('start');
    // Imagine any chain of async operations here
    setImmediate(() => {
      logWithId('finish');
      res.end();
    });
  });
}).listen(8080);

http.get('http://localhost:8080');
http.get('http://localhost:8080');
// Prints:
//   0: start
//   1: start
//   0: finish
//   1: finishconst http = require('node:http');
const { AsyncLocalStorage } = require('node:async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

function logWithId(msg) {
  const id = asyncLocalStorage.getStore();
  console.log(`${id !== undefined ? id : '-'}:`, msg);
}

let idSeq = 0;
http.createServer((req, res) => {
  asyncLocalStorage.run(idSeq++, () => {
    logWithId('start');
    // Imagine any chain of async operations here
    setImmediate(() => {
      logWithId('finish');
      res.end();
    });
  });
}).listen(8080);

http.get('http://localhost:8080');
http.get('http://localhost:8080');
// Prints:
//   0: start
//   1: start
//   0: finish
//   1: finish拷贝

AsyncLocalStorage 的每个实例都维护一个独立的存储上下文。 多个实例可以安全地同时存在，而不会有干扰彼此数据的风险。

new AsyncLocalStorage()#

创建 AsyncLocalStorage 的新实例。 Store 仅在 run() 调用内或 enterWith() 调用后提供。

静态方法：AsyncLocalStorage.bind(fn)#

• fn <Function> 绑定到当前执行上下文的函数。
• 返回： <Function> 在捕获的执行上下文中调用 fn 的新函数。

将给定函数绑定到当前执行上下文。

静态方法：AsyncLocalStorage.snapshot()#

• 返回： <Function> 带有签名 (fn: (...args) : R, ...args) : R 的新函数。

捕获当前执行上下文并返回一个接受函数作为参数的函数。 每当调用返回的函数时，它都会在捕获的上下文中调用传递给它的函数。

const asyncLocalStorage = new AsyncLocalStorage();
const runInAsyncScope = asyncLocalStorage.run(123, () => AsyncLocalStorage.snapshot());
const result = asyncLocalStorage.run(321, () => runInAsyncScope(() => asyncLocalStorage.getStore()));
console.log(result);  // returns 123 拷贝

AsyncLocalStorage.snapshot() 可以代替 AsyncResource 用于简单的异步上下文跟踪目的，例如：

class Foo {
  #runInAsyncScope = AsyncLocalStorage.snapshot();

  get() { return this.#runInAsyncScope(() => asyncLocalStorage.getStore()); }
}

const foo = asyncLocalStorage.run(123, () => new Foo());
console.log(asyncLocalStorage.run(321, () => foo.get())); // returns 123 拷贝

asyncLocalStorage.disable()#

禁用 AsyncLocalStorage 的实例。 对 asyncLocalStorage.getStore() 的所有后续调用都将返回 undefined，直到再次调用 asyncLocalStorage.run() 或 asyncLocalStorage.enterWith()。

调用 asyncLocalStorage.disable() 时，将退出所有当前链接到该实例的上下文。

在可以对 asyncLocalStorage 进行垃圾回收之前，需要调用 asyncLocalStorage.disable()。 这不适用于 asyncLocalStorage 提供的存储，因为这些对象与相应的异步资源一起被垃圾回收。

当 asyncLocalStorage 在当前进程中不再使用时使用此方法。

asyncLocalStorage.getStore()#

• 返回： <any>

返回当前商店。 如果在通过调用 asyncLocalStorage.run() 或 asyncLocalStorage.enterWith() 初始化的异步上下文之外调用，它将返回 undefined。

asyncLocalStorage.enterWith(store)#

• store <any>

转换为当前同步执行的剩余部分的上下文，然后通过任何后续异步调用持久保存存储。

示例：

const store = { id: 1 };
// Replaces previous store with the given store object
asyncLocalStorage.enterWith(store);
asyncLocalStorage.getStore(); // Returns the store object
someAsyncOperation(() => {
  asyncLocalStorage.getStore(); // Returns the same object
}); 拷贝

此转换将持续整个同步执行。 这意味着，例如，如果在事件处理程序中输入上下文，则后续事件处理程序也将在该上下文中运行，除非使用 AsyncResource 专门绑定到另一个上下文。 这就是为什么 run() 应该优于 enterWith() 的原因，除非有充分的理由使用后一种方法。

const store = { id: 1 };

emitter.on('my-event', () => {
  asyncLocalStorage.enterWith(store);
});
emitter.on('my-event', () => {
  asyncLocalStorage.getStore(); // Returns the same object
});

asyncLocalStorage.getStore(); // Returns undefined
emitter.emit('my-event');
asyncLocalStorage.getStore(); // Returns the same object 拷贝

asyncLocalStorage.run(store, callback[, ...args])#

• store <any>
• callback <Function>
• ...args <any>

在上下文中同步运行函数并返回其返回值。 在回调函数之外无法访问该商店。 在回调中创建的任何异步操作都可以访问该存储。

可选的 args 被传递给回调函数。

如果回调函数抛出错误，则 run() 也会抛出该错误。 堆栈跟踪不受此调用的影响，上下文已退出。

示例：

const store = { id: 2 };
try {
  asyncLocalStorage.run(store, () => {
    asyncLocalStorage.getStore(); // Returns the store object
    setTimeout(() => {
      asyncLocalStorage.getStore(); // Returns the store object
    }, 200);
    throw new Error();
  });
} catch (e) {
  asyncLocalStorage.getStore(); // Returns undefined
  // The error will be caught here
} 拷贝

asyncLocalStorage.exit(callback[, ...args])#

• callback <Function>
• ...args <any>

在上下文之外同步运行函数并返回其返回值。 该存储在回调函数或回调中创建的异步操作中不可访问。 在回调函数内完成的任何 getStore() 调用将始终返回 undefined。

可选的 args 被传递给回调函数。

如果回调函数抛出错误，则 exit() 也会抛出该错误。 堆栈跟踪不受此调用的影响，并且重新进入上下文。

示例：

// Within a call to run
try {
  asyncLocalStorage.getStore(); // Returns the store object or value
  asyncLocalStorage.exit(() => {
    asyncLocalStorage.getStore(); // Returns undefined
    throw new Error();
  });
} catch (e) {
  asyncLocalStorage.getStore(); // Returns the same object or value
  // The error will be caught here
} 拷贝

与 async/await 一起使用#

如果在异步函数中，只有一个 await 调用在上下文中运行，则应使用以下模式：

async function fn() {
  await asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('key', value);
    return foo(); // The return value of foo will be awaited
  });
} 拷贝

本例中 store 只在回调函数和 foo 调用的函数中可用。 在 run 之外，调用 getStore 将返回 undefined。

故障排除：上下文丢失#

在大多数情况下，AsyncLocalStorage 可以正常工作。 在极少数情况下，当前存储会在其中一个异步操作中丢失。

如果你的代码是基于回调的，则使用 util.promisify() 对其进行 promise 就足够了，因此它可以开始使用原生 promise。

如果你需要使用基于回调的 API，或者你的代码采用自定义的 thenable 实现，请使用 AsyncResource 类将异步操作与正确的执行上下文相关联。 通过在你怀疑导致上下文丢失的调用之后记录 asyncLocalStorage.getStore() 的内容，找到导致上下文丢失的函数调用。 当代码记录 undefined 时，调用的最后一个回调可能是上下文丢失的原因。