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

Как использовать AsyncLocalStorage для request context?

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

AsyncLocalStorage из node:async_hooks хранит request-scoped данные через цепочки async/await, callbacks и promises. В backend это используют для request id, tenant id, user id, logger context и tracing.

Вопрос

Как использовать AsyncLocalStorage для хранения контекста запроса?

Зачем нужен request context?

Без context приходится прокидывать requestId через все функции:

await userService.findById(id, {
  requestId,
});

В большом backend-е это быстро загрязняет сигнатуры. AsyncLocalStorage позволяет сохранить context один раз в начале request и читать его глубже.

Минимальный пример

import http from 'node:http';
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
 
const requestContext = new AsyncLocalStorage();
 
function getContext() {
  return requestContext.getStore();
}
 
function log(message) {
  const context = getContext();
 
  console.log(JSON.stringify({
    requestId: context?.requestId,
    message,
  }));
}
 
http.createServer((req, res) => {
  requestContext.run({
    requestId: randomUUID(),
  }, async () => {
    log('request started');
 
    await new Promise((resolve) => setTimeout(resolve, 10));
 
    log('request finished');
    res.end('ok');
  });
}).listen(3000);

Какие методы важно знать?

МетодЧто делает
run(store, callback)создает context на время callback и async-операций внутри
getStore()возвращает текущий store или undefined
enterWith(store)входит в context для текущего sync execution, использовать осторожно
exit(callback)выполняет callback вне текущего context
disable()отключает storage, нужно для cleanup самого instance
AsyncLocalStorage.bind(fn)привязывает function к текущему context
AsyncLocalStorage.snapshot()захватывает текущий context и возвращает runner

Что хранить в context?

Хорошо:

  • requestId;
  • userId;
  • tenantId;
  • traceId;
  • logger;
  • startedAt;
  • permissions.

Плохо:

  • большие объекты;
  • request body целиком;
  • secrets;
  • mutable shared state;
  • database connection на request без причины.

Где context может потеряться?

Редко, но бывает:

  • custom callback API;
  • старые native addons;
  • ручные event emitters;
  • worker threads;
  • чужие библиотеки, которые ломают async boundary.

Для таких случаев используют AsyncResource, bind() или явное прокидывание context.

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

  • AsyncLocalStorage хранит данные, доступные во всей асинхронной цепочке запроса.
  • Типичное применение — requestId в логах и трейсах без передачи через все функции.
  • Контекст задается через als.run(store, fn), читается через als.getStore().
  • Не храните там большие объекты и не используйте как замену явным параметрам бизнес-логики.

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

  • AsyncLocalStorage - request-scoped storage.
  • В web backend обычно начинай с run() в middleware.
  • getStore() читает context глубже в коде.
  • Не клади в context тяжелые и sensitive данные.
  • Для логов, tracing и tenant-aware операций это один из самых полезных современных Node API.

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

Node.js: AsyncLocalStorage.

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

Поиск

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