Урок 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.
Документация
Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.