Навигация

Асинхронность в Node.js

Сервер получает запрос, и почти всё, что происходит дальше, асинхронно: чтение из базы, вызов внешнего API, запись в файл, ожидание очереди. Синтаксис здесь не главное — главное поведение под нагрузкой: сколько операций сервис запускает одновременно, что происходит при частичном отказе и как ошибка одного запроса не уносит процесс целиком. Разберём стандартную библиотеку, ловушки промисов и инструменты, превращающие async/await в управляемый серверный код.

Содержание

  1. Почему серверная асинхронность — не про синтаксис
  2. Error-first колбэки и util.promisify
  3. Промисы в стандартной библиотеке
  4. Последовательно и параллельно
  5. Promise.all и частичное падение
  6. Ограничение параллелизма
  7. Необработанные ошибки
  8. Отмена через AbortSignal
  9. AsyncLocalStorage: контекст запроса
  10. Отличия от браузерной асинхронности
  11. Эксперименты
  12. Ключевые тезисы для интервью
  13. Заключение
  14. Полезные ссылки

Почему серверная асинхронность — не про синтаксис

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+)
Необработанный throwwindow.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.

Полезные ссылки