re:re:actable
Урок 022 минуты чтения

Что такое async_hooks, AsyncResource и context loss?

На этой странице
Кратко

async_hooks - низкоуровневый API Node.js для отслеживания async resources. В обычном backend-е чаще используют AsyncLocalStorage, но AsyncResource полезен, когда нужно вручную сохранить context в callback/event/worker интеграции.

Вопрос

Что такое async_hooks, AsyncResource и потеря контекста?

Что такое async resource?

Async resource - объект или операция, через которую Node.js продолжает выполнение позже:

  • promise;
  • timer;
  • TCP callback;
  • file system callback;
  • HTTP request;
  • custom callback.

Node.js связывает эти операции в async graph, чтобы tooling и context tracking понимали причинность.

Когда нужен AsyncResource?

Если библиотека вызывает callback вне привычной async цепочки, context может потеряться.

Пример wrapper-а:

import { AsyncResource } from 'node:async_hooks';
 
function callLater(callback) {
  const resource = new AsyncResource('custom-callback');
 
  setTimeout(() => {
    resource.runInAsyncScope(callback);
    resource.emitDestroy();
  }, 10);
}

runInAsyncScope() запускает callback так, чтобы Node.js видел правильную async связь.

Основные методы AsyncResource

МетодЗачем нужен
new AsyncResource(type)создает ресурс с понятным типом
runInAsyncScope(fn, thisArg, ...args)запускает callback внутри async resource
bind(fn)возвращает function, привязанную к resource
emitDestroy()сообщает, что resource завершен
asyncId()id ресурса
triggerAsyncId()id ресурса, который создал текущий

Почему не писать все на raw async_hooks?

Raw hooks очень мощные, но:

  • легко получить overhead;
  • легко сломать логирование рекурсией;
  • API низкоуровневый;
  • чаще нужен tooling, а не бизнес-код.

Для request context выбирай AsyncLocalStorage.

Типичный production case

Worker pool:

request context -> queue task -> worker callback -> log with same requestId

Если callback возвращается через custom emitter, AsyncResource помогает сохранить context.

Что важно помнить

  • Низкоуровневый API async_hooks не рекомендуется для прикладного кода — используйте AsyncLocalStorage.
  • Контекст может теряться в callback-библиотеках с собственными пулами и очередями.
  • AsyncResource.bind() привязывает функцию к текущему асинхронному контексту.
  • Проверяйте сохранение контекста тестами, если пишете библиотеку.

Мини-шпаргалка

  • AsyncLocalStorage - основной API для request context.
  • AsyncResource - ручная интеграция custom async boundaries.
  • async_hooks - низкоуровневая база для diagnostics tooling.
  • Context loss обычно лечат bind(), snapshot() или AsyncResource.

Документация

Node.js: Asynchronous context tracking, Node.js: Async hooks.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам