Node.js v18.7.0 文档

术语#

中英对照

异步的资源表示具有关联回调的对象。 此回调可能会被多次调用，比如 net.createServer() 中的 'connection' 事件、或者像 fs.open() 一样只调用一次。 资源也可以在调用回调之前关闭。 AsyncHook 没有明确区分这些不同的情况，而是将它们表示为抽象的概念，即资源。

概述#

中英对照

以下是公共 API 的简单概述。

async_hooks.createHook(callbacks)#

中英对照

为每个异步操作的不同生命周期事件注册要调用的函数。

异常处理#

中英对照

如果任何 AsyncHook 回调抛出，则应用程序将打印堆栈跟踪并退出。 退出路径确实遵循未捕获异常的路径，但所有 'uncaughtException' 监听器都被删除，从而强制进程退出。 除非应用程序使用 --abort-on-uncaught-exception 运行，否则仍将调用 'exit' 回调，在这种情况下，将打印堆栈跟踪并且应用程序退出，留下核心文件。

在 AsyncHook 回调中打印#

中英对照

因为打印到控制台是异步的操作，所以 console.log() 会导致 AsyncHook 回调被调用。 在 AsyncHook 回调函数中使用 console.log() 或类似的异步操作将导致无限递归。 当调试时，一个简单的解决方案是使用同步的日志记录操作，例如 fs.writeFileSync(file, msg, flag)。 这将打印到文件并且不会递归地调用 AsyncHook，因为它是同步的。

AsyncHook 类#

中英对照

AsyncHook 类公开了一个用于跟踪异步操作的生命周期事件的接口。

asyncHook.enable()#

中英对照

启用给定 AsyncHook 实例的回调。 如果没有提供回调，则启用是无操作的。

asyncHook.disable()#

中英对照

从要执行的 AsyncHook 回调全局池中禁用给定 AsyncHook 实例的回调。 一旦一个钩子被禁用，则它在启用之前不会被再次调用。

钩子回调#

中英对照

异步事件生命周期中的关键事件分为四个区域：实例化、回调调用前后、实例销毁时。

init(asyncId, type, triggerAsyncId, resource)#

中英对照

当构造有可能触发异步事件的类时调用。 这并不意味着实例必须在调用 destroy 之前调用 before/after，只是存在这种可能性。

type#

中英对照

type 是字符串，标识导致调用 init 的资源类型。 一般会对应资源的构造函数名。

triggerAsyncId#

中英对照

triggerAsyncId 是导致（或“触发”）新资源初始化并导致 init 调用的资源的 asyncId。 这与 async_hooks.executionAsyncId() 不同，async_hooks.executionAsyncId() 只显示何时创建资源，而 triggerAsyncId 显示创建资源的原因。

resource#

中英对照

resource 是一个对象，表示已初始化的实际异步资源。 这可能包含有用的信息，这些信息可能会根据 type 的值而有所不同。 例如，对于 GETADDRINFOREQWRAP 资源类型，resource 提供了在 net.Server.listen() 中查找主机 IP 地址时使用的主机名。 不支持访问此信息的 API，但使用 Embedder API，用户可以提供和记录自己的资源对象。 例如，这样的资源对象可能包含正在执行的 SQL 查询。

异步上下文的示例#

中英对照

以下是一个示例，其中包含有关 before 和 after 调用之间对 init 的调用的附加信息，特别是对 listen() 的回调将是什么样子。 输出格式稍微复杂一点，使调用上下文更容易看到。

before(asyncId)#

中英对照

当异步操作启动（如 TCP 服务器接收新连接）或完成（如将数据写入磁盘）时，会调用回调通知用户。 before 回调在所述回调执行之前被调用。 asyncId 是分配给即将执行回调的资源的唯一标识符。

after(asyncId)#

中英对照

在 before 中指定的回调完成后立即调用。

destroy(asyncId)#

中英对照

asyncId 对应的资源销毁后调用。 它也从嵌入器 API emitDestroy() 异步调用。

promiseResolve(asyncId)#

中英对照

当调用传给 Promise 构造函数的 resolve 函数时调用（直接或通过其他解决 promise 的方法）。

async_hooks.executionAsyncResource()#

中英对照

executionAsyncResource() 返回的资源对象通常是带有未记录 API 的内部 Node.js 句柄对象。 在对象上使用任何函数或属性都可能使您的应用程序崩溃，应该避免。

async_hooks.executionAsyncId()#

中英对照

executionAsyncId() 返回的 ID 与执行时机有关，与因果无关（被 triggerAsyncId() 涵盖）：

async_hooks.triggerAsyncId()#

中英对照

默认情况下，promise 上下文可能无法获得有效的 triggerAsyncId。 请参阅 promise 执行跟踪部分。

async_hooks.asyncWrapProviders#

中英对照

此特性禁止使用 process.binding('async_wrap').Providers。 参阅：DEP0111

Promise 执行跟踪#

中英对照

默认情况下，由于 V8 提供的 promise 自省 API 相对昂贵，因此不会为 promise 执行分配 asyncId。 这意味着默认情况下，使用 promise 或 async/await 的程序将无法正确执行并触发 promise 回调上下文的 id。

JavaScript 嵌入的接口#

中英对照

处理自己的异步资源执行 I/O、连接池或管理回调队列等任务的库开发者可以使用 AsyncResource JavaScript API 以便调用所有适当的回调。

AsyncResource 类#

中英对照

该类的文档已移至 AsyncResource。

AsyncLocalStorage 类#

中英对照

该类的文档已移至 AsyncLocalStorage。