Что такое 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.