Асинхронность в Node.js
Сервер получает запрос, и почти всё, что происходит дальше, асинхронно: чтение из базы, вызов внешнего API, запись в файл, ожидание очереди. Синтаксис здесь не главное — главное поведение под нагрузкой: сколько операций сервис запускает одновременно, что происходит при частичном отказе и как ошибка одного запроса не уносит процесс целиком. Разберём стандартную библиотеку, ловушки промисов и инструменты, превращающие async/await в управляемый серверный код.
Содержание
- Почему серверная асинхронность — не про синтаксис
- Error-first колбэки и util.promisify
- Промисы в стандартной библиотеке
- Последовательно и параллельно
- Promise.all и частичное падение
- Ограничение параллелизма
- Необработанные ошибки
- Отмена через AbortSignal
- AsyncLocalStorage: контекст запроса
- Отличия от браузерной асинхронности
- Эксперименты
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Почему серверная асинхронность — не про синтаксис
Node обслуживает тысячи соединений одним потоком: пока один запрос ждёт базу, другой читает body, третий отправляет ответ. Асинхронность здесь — способ не блокировать event loop, а не украшение кода. Поэтому у любого асинхронного участка есть три прикладных вопроса: сколько операций стартует одновременно, что делать, если одна из них упала, и как остановить работу, когда она больше не нужна.
Семантика промисов и микрозадач разобрана в статье «Асинхронность: Promise, async/await», порядок очередей — в статье «Event Loop в Node.js». Здесь речь о том, что эти правила означают для сервиса: про лимиты, ошибки процесса и контекст запроса.
Error-first колбэки и util.promisify
Почти всё старое API Node построено на одном контракте: последний аргумент функции — колбэк, первый аргумент колбэка — ошибка.
readFile('config.json', 'utf8', (err, text) => {
if (err) return onError(err);
console.log(text.length);
});
util.promisify превращает такую функцию в возвращающую промис, если контракт соблюдён:
import { promisify } from 'node:util';
import { readFile } from 'node:fs';
const readFileAsync = promisify(readFile);
const text = await readFileAsync('config.json', 'utf8');
Ограничения контракта проявляются сразу, как только колбэк возвращает больше одного значения:
child_process.execвызываетcallback(err, stdout, stderr), иpromisifyпо умолчанию оставил бы толькоstdout. У встроенной функции для этого уже есть своя реализацияpromisify.custom, возвращающая{ stdout, stderr };- библиотека может нарушать контракт: бросать синхронно, вызывать колбэк дважды или отвечать то синхронно, то асинхронно. Промис оградит от двойного вызова, но не исправит саму функцию.
Если у функции свой результат, обёртку задают явно через символ promisify.custom:
import { promisify } from 'node:util';
function getOrder(id, callback) {
db.query('SELECT * FROM orders WHERE id = $1', [id], (err, rows) => {
if (err) return callback(err);
callback(null, rows[0], rows.length);
});
}
getOrder[promisify.custom] = (id) =>
new Promise((resolve, reject) => {
getOrder(id, (err, order, total) =>
err ? reject(err) : resolve({ order, total }));
});
const getOrderAsync = promisify(getOrder);
const { order, total } = await getOrderAsync(42);
Зачем это нужно, если новый код пишут на промисах: драйверы баз, старые SDK и часть crypto до сих пор на колбэках, а смешивание двух стилей в одном обработчике — источник ошибок. Рабочее правило: обернуть один раз на границе и дальше работать только на промисах. Для стандартной библиотеки обёртки уже есть — об этом следующий раздел.
Промисы в стандартной библиотеке
Три модуля закрывают почти все задачи без сторонних пакетов:
import { readFile, writeFile } from 'node:fs/promises';
import { setTimeout as sleep } from 'node:timers/promises';
import { pipeline } from 'node:stream/promises';
node:timers/promises стоит отдельного упоминания, потому что самодельная обёртка над таймером встречается в каждом проекте и почти всегда с изъяном:
// так пишут часто, но так нельзя отменить и легко потерять управление
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
Встроенный вариант принимает AbortSignal:
await sleep(1000, undefined, { signal });
Ещё два инструмента, которые избавляют от ручных промисов:
Promise.withResolvers()(Node 22+) возвращает{ promise, resolve, reject }, если промис действительно нужно создать вручную — например, чтобы связать колбэк-API с внешним кодом;events.once(emitter, 'event')возвращает промис, который резолвится на следующем событии. Это удобно дляawait once(server, 'listening')в тестах и при старте.
Общее правило: чем меньше промисов, созданных вручную через new Promise, тем меньше шансов потерять ошибку. Всё, у чего есть готовая промис-версия, берут из node:* или из обёртки, а не собирают заново.
Последовательно и параллельно
Разница в стоимости здесь буквальная. Последовательные вызовы складывают задержки, параллельные берут максимум:
// последовательно: 50 мс + 80 мс = 130 мс
const user = await getUser(id);
const orders = await getOrders(user.id);
// параллельно: максимум из двух задержек
const [user, orders] = await Promise.all([getUser(id), getOrders(id)]);
Ждать по очереди имеет смысл только в двух случаях: следующий вызов зависит от результата предыдущего или вы сознательно ограничиваете нагрузку. Если зависимости по данным нет, await в цикле — почти всегда ошибка:
const results = [];
for (const id of ids) {
results.push(await fetchUser(id)); // 100 запросов × 50 мс = 5 секунд
}
Тот же код параллельно выполнялся бы за время одного запроса — но именно такие циклы чаще всего и превращают «параллельно» в проблему: наивная замена на Promise.all(ids.map(fetchUser)) запускает сразу все сто операций. Как найти середину — в разделе про ограничение параллелизма.
Promise.all и частичное падение
Promise.all отклоняется на первой ошибке: остальные промисы продолжают выполняться, потому что отмены в промисах нет. Побочные эффекты — запись в базу, отправка письма, списание средств — уже произошли, а результаты потеряны. Так рождается классический баг batch-обработки: часть пачки сохранена, часть нет, клиент получил 500 и не знает, что повторять.
// при ошибке одного запроса ответ 500, но два других уже выполнились
await Promise.all([
saveItem(a),
saveItem(b), // упал
saveItem(c), // всё равно запишется
]);
| Метод | Поведение | Когда брать |
|---|---|---|
Promise.all | ждёт все, отклоняется на первой ошибке | операции должны пройти целиком |
Promise.allSettled | ждёт все, никогда не отклоняется, возвращает статусы | частичный успех — норма |
Promise.any | резолвится первым успешным, при полном провале — AggregateError | несколько зеркал или источников |
Promise.race | завершается первым, успешным или нет | таймаут поверх операции |
Для «частичный успех — норма» берут allSettled и разбирают результат:
const results = await Promise.allSettled(ids.map(saveItem));
const failed = results
.map((r, i) => (r.status === 'rejected' ? { id: ids[i], reason: r.reason } : null))
.filter(Boolean);
logger.warn({ failed }, 'часть пачки не сохранилась');
Три детали, которые делают эту схему рабочей:
- Индекс — единственная связь с входом.
allSettledвозвращает массив в порядке исходных промисов, но не сами значения; соответствие восстанавливают по позиции. allSettledне отменяет соседей. Медленная операция всё равно доработает, и её побочный эффект случится.- Повтор должен быть безопасным. Раз задача могла выполниться частично, повторный вызов не должен дублировать запись — это называется идемпотентностью и разбирается в статье «Таймауты, ретраи и graceful shutdown».
Если операция должна пройти строго целиком, Promise.all недостаточно: нужна транзакция или компенсация, потому что откатить уже выполненные шаги промисы не умеют.
Ограничение параллелизма
Promise.all по тысяче элементов честно запускает тысячу операций. Дальше работает не ваш код, а чужие лимиты: пул соединений базы на десять, rate limit внешнего API, память под ответы. В итоге девятьсот девяносто запросов сидят в очереди, превышают дедлайн и падают по таймауту — при том, что сервер формально «работает параллельно».
Ограничитель — это пул воркеров фиксированного размера:
async function mapLimit(items, limit, fn) {
const results = new Array(items.length);
let next = 0;
async function worker() {
while (next < items.length) {
const index = next++;
results[index] = await fn(items[index], index);
}
}
await Promise.all(
Array.from({ length: Math.min(limit, items.length) }, worker),
);
return results;
}
const users = await mapLimit(ids, 10, fetchUser);
Здесь одновременно работает не больше limit вызовов, а порядок результатов сохраняется за счёт индексов. Один нюанс: если fn бросает, воркер завершится, Promise.all отклонится, но остальные воркеры продолжат работу — то же fail-fast поведение, что и выше. Чтобы получить полный отчёт, ошибку ловят внутри воркера и возвращают результат со статусом.
В проде этот код обычно не пишут руками: берут p-limit или fastq и держат лимит рядом с конфигом. Отдельно стоит помнить, что лимит параллелизма в коде и размер пула соединений — разные вещи: пул ограничивает число соединений с базой, но не число ожидающих запросов в памяти процесса.
Необработанные ошибки
Главный вопрос серверной асинхронности: куда попадает ошибка, которую никто не ждал.
Внутри async-функции throw создаёт отклонённый промис. Если его никто не ожидает, возникает unhandledRejection. С Node 15 поведение по умолчанию — падение процесса с ненулевым кодом, и это осознанное решение: необработанный reject означает, что о состоянии приложения ничего не известно.
uncaughtException — другой случай: синхронный throw, который никто не перехватил на пути. Он рождается в колбэке таймера, в обработчике события, в process.nextTick, то есть вне цепочки промисов:
setTimeout(() => {
throw new Error('boom'); // uncaughtException, промис здесь ни при чём
}, 0);
Похожая ловушка поджидает в самодельных обёртках: throw в теле executor’а new Promise промис отклоняет, а throw в колбэке, вызванном внутри executor’а, — нет. Именно поэтому ручные промисы над колбэк-API так легко «теряют» ошибки.
Почему после uncaughtException нельзя продолжать работу:
- стек раскручен, но состояние неизвестно: транзакция могла остаться открытой, ответ — недописанным, счётчик — недосчитанным;
- ошибка с высокой вероятностью повторится на следующем таком же запросе;
- процесс может продолжать работать и молча портить данные, что хуже падения.
Правильная реакция — залогировать контекст и завершиться, оставив рестарт оркестратору:
import { logger } from './logger.js';
import { shutdown } from './shutdown.js';
process.on('unhandledRejection', (reason) => {
logger.fatal({ err: reason }, 'unhandled rejection');
shutdown(1); // graceful shutdown, затем выход с кодом 1
});
process.on('uncaughtException', (err) => {
logger.fatal({ err }, 'uncaught exception');
shutdown(1);
});
Ключевая деталь: установка обработчика заменяет поведение по умолчанию. Пока слушателя нет, Node падает сам; как только вы добавили process.on('unhandledRejection'), падение отключено, и завершать процесс обязан обработчик. Обработчик «просто для логов» без shutdown — распространённая ошибка, из-за которой сервис живёт в повреждённом состоянии. Если нужны только логи и дефолтный краш, есть process.on('uncaughtExceptionMonitor') — он не перехватывает поведение.
И обратное правило: ожидаемые ошибки — не исключения процесса, а часть ответа. Ошибка валидации, отсутствующая запись, отказ внешнего API обрабатываются try/catch в контроллере и единым error middleware; как это устроено — в статье «Express и middleware».
Отмена через AbortSignal
Клиент закрыл вкладку или оборвал соединение, а сервер всё ещё считает запрос к базе и держит соединение из пула. Работа, результат которой никто не увидит, — это чистая потеря пропускной способности. Стандартный способ её остановить — AbortController и его AbortSignal.
import { setTimeout as sleep } from 'node:timers/promises';
const controller = new AbortController();
res.on('close', () => {
if (!res.writableEnded) controller.abort(); // клиент ушёл, не дождавшись
});
try {
const user = await fetchUser(id, { signal: controller.signal });
await sleep(200, undefined, { signal: controller.signal });
res.json(user);
} catch (err) {
if (err.name === 'AbortError') return; // отмена — не ошибка сервиса
throw err;
}
Сигнал понимают fetch, fs.promises.*, timers/promises, stream.pipeline и часть сторонних клиентов. У драйверов SQL сигнала обычно нет: там отмену ограничивают statement_timeout и проверкой signal.aborted перед записью результата.
Два сигнала часто объединяют — отмену клиентом и страховку по времени:
const signal = AbortSignal.any([
controller.signal,
AbortSignal.timeout(5_000), // страховочный дедлайн
]);
Виды ошибок при этом различаются: AbortError приходит от controller.abort(), TimeoutError — от AbortSignal.timeout(), а AbortSignal.any пробрасывает причину того сигнала, который сработал первым. Для API это разные ответы: отменённый клиентом запрос не логируется как ошибка, а истёкший дедлайн — инцидент.
Главное ограничение: отмена работает только там, где сигнал проброшен. Если функция принимает id, но не принимает signal, прервать её извне нельзя. Поэтому сигнал — часть контракта асинхронной функции, как логгер или контекст запроса.
И второе: abort() не останавливает выполнение мгновенно и не откатывает сделанное. Операция может завершиться в момент отмены, поэтому перед побочным эффектом проверяют signal.aborted, а результат отменённой операции игнорируют.
AsyncLocalStorage: контекст запроса
Request-id нужен в каждом логе, но протаскивать его параметром через десять функций — шум, который к тому же забывают добавить в новую ветку кода. AsyncLocalStorage из node:async_hooks хранит контекст, привязанный к цепочке асинхронных вызовов.
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
const requestContext = new AsyncLocalStorage();
app.use((req, res, next) => {
const store = { requestId: req.headers['x-request-id'] ?? randomUUID() };
requestContext.run(store, next);
});
// логгер сам достаёт контекст, обработчикам его передавать не нужно
function log(level, message, extra = {}) {
const store = requestContext.getStore();
logger[level]({ ...extra, requestId: store?.requestId }, message);
}
Контекст переживает await, таймеры и колбэки ввода-вывода, потому что все они создаются внутри run. Всё, что стартовало до входа в run или после его завершения, контекста не видит.
Разница между двумя методами принципиальна:
run(store, fn)привязывает контекст к вызовуfnи его асинхронным потомкам — безопасный вариант для middleware;enterWith(store)меняет контекст текущего исполнения и сохраняется до конца синхронной цепочки. В обработчике запроса это почти всегда утечка: следующий запрос, попавший в тот же стек, увидит чужой request-id.
Ограничения, о которых спрашивают:
- в
worker_threadsконтекст не переносится — там своя память и свои async-ресурсы; async_hooksне бесплатны: на очень высоком RPS накладные расходы заметны, хотя обычно ими пренебрегают;- контекст не заменяет явные параметры в сервисном слое: для тестов и переиспользования
requestIdлучше принимать аргументом, аAsyncLocalStorageдержать для логов и трейсинга на границе.
Кроме request-id так же переносят пользователя, tenant, клиент транзакции и текущий span трассировки. Как это складывается в сквозной лог и метрики — в статье «Логирование и наблюдаемость».
Отличия от браузерной асинхронности
Синтаксис и семантика микрозадач совпадают, а последствия ошибок — нет.
| Аспект | Браузер | Node.js |
|---|---|---|
| Необработанный reject | событие unhandledrejection на window, страница живёт | падение процесса (Node 15+) |
Необработанный throw | window.onerror, страница продолжает работу | uncaughtException, состояние процесса неизвестно |
| Отмена | AbortController + fetch | тот же AbortController, плюс fs, стримы, таймеры |
| Контекст | один пользователь, контекст — глобальное состояние | тысячи параллельных запросов, нужен AsyncLocalStorage |
| Время жизни | вкладка закрывается пользователем | процесс завершается, когда event loop пуст |
| Зависимости | сеть и DOM | сеть, база, файлы, очередь, другие сервисы |
В браузере цена необработанной ошибки — сломанный интерфейс у одного пользователя, и часто достаточно показать сообщение. На сервере та же ошибка роняет процесс, который обслуживал тысячи запросов, поэтому обработка строже: нет сценария «просто вывести в консоль и поехать дальше».
Ещё одно следствие — отмена. В браузере запрос отменяется вместе с компонентом или навигацией; на сервере отмену нужно провести по всей цепочке вложенных вызовов, иначе работа продолжится после ухода клиента.
Эксперименты
Три коротких запуска, которые показывают разницу между «код работает» и «код ведёт себя предсказуемо».
1. Fail-fast и осиротевшие операции
const delay = (ms, name) => new Promise((resolve) => {
setTimeout(() => {
console.log(`завершился ${name}`);
resolve(name);
}, ms);
});
try {
await Promise.all([
delay(100, 'a'),
Promise.reject(new Error('boom')),
delay(300, 'c'),
]);
} catch (err) {
console.log(`all упал: ${err.message}`);
}
// all упал: boom
// завершился c ← через 300 мс, хотя результат уже никому не нужен
Promise.all вернул управление сразу, но третья операция доработала. Если внутри была запись в базу, она произошла.
2. Обработчик, который отключил защиту
process.on('uncaughtException', (err) => {
console.log('перехвачено:', err.message);
});
setTimeout(() => {
throw new Error('boom');
console.log('эта строка не выполнится');
}, 0);
// перехвачено: boom
Процесс не упал, но код после throw в том же колбэке пропущен. Без обработчика тот же файл завершился бы с кодом 1 — это и есть поведение, которое обработчик отключил.
3. Контекст через await
import { AsyncLocalStorage } from 'node:async_hooks';
const als = new AsyncLocalStorage();
als.run({ requestId: 'r-1' }, async () => {
await new Promise((resolve) => setTimeout(resolve, 100));
console.log(als.getStore()); // { requestId: 'r-1' }
});
als.run({ requestId: 'r-2' }, async () => {
await new Promise((resolve) => setTimeout(resolve, 50));
console.log(als.getStore()); // { requestId: 'r-2' }
});
setTimeout(() => console.log(als.getStore()), 150); // undefined
Два параллельных контекста не смешиваются, а код, запущенный вне run, контекста не видит — именно это ломается при использовании enterWith.
Ключевые тезисы для интервью
- Асинхронность в Node — это бюджет одновременных операций, а не синтаксис: каждый незавершённый
awaitдержит соединение или поток пула, поэтому число параллельных операций ограничивают явно, а не надеются наPromise.all. - Error-first колбэки остаются в драйверах и старых SDK;
promisify(при необходимости черезpromisify.custom) сводит их к промисам один раз на границе, дальше два стиля не смешивают. Promise.allпадает на первой ошибке, но остальные операции не отменяются и оставляют побочные эффекты; частичный успех требуетallSettledи идемпотентного повтора.unhandledRejectionиuncaughtExceptionозначают неизвестное состояние процесса: безопасно только залогировать контекст, начать graceful shutdown и уступить рестарт оркестратору.- Обработчик этих событий заменяет дефолтное падение Node, поэтому если он установлен, завершение процесса должно быть в нём;
uncaughtExceptionMonitorоставляет поведение по умолчанию. AbortSignal— часть контракта асинхронной функции: отмена работает только там, куда сигнал проброшен, аAbortErrorиTimeoutErrorразличают уход клиента и истёкший дедлайн, а не откатывают уже сделанное.AsyncLocalStorageпереносит контекст черезawaitи колбэки, но не вworker_threads; в middleware нуженrun, аenterWithпротекает между запросами.
Заключение
Асинхронный код на сервере оценивают не по красоте цепочки, а по предсказуемости под нагрузкой. Промисы дают композицию, async/await — читаемость, но ни то, ни другое не отвечает на три вопроса: сколько операций запущено одновременно, что произошло при частичном отказе и как остановить бесполезную работу. Ответы — ограниченный параллелизм, allSettled вместе с идемпотентностью и AbortSignal, проброшенный до конца цепочки. Ошибки уровня процесса лечатся не try/catch, а логом, graceful shutdown и рестартом, а контекст запроса переносится AsyncLocalStorage, а не десятком параметров. Дальше эти инструменты применяются к событиям и потокам данных: там те же правила работают уже на уровне подписок и backpressure.
Полезные ссылки
- util.promisify — контракт,
promisify.custom, ограничения - Process events: unhandledRejection — режимы
--unhandled-rejectionsи поведение по умолчанию - AsyncLocalStorage —
run,enterWith,getStore - AbortSignal —
abort,timeout,any,reason - timers/promises — промис-таймеры и
signal - Асинхронность: Promise, async/await — базовая семантика промисов в языке