Асинхронные циклы в JavaScript: как избежать ловушек и выбрать правильную стратегию

Опубликовано:
Запускаете три независимых API-запроса в цикле, а они выполняются друг за другом, заставляя пользователя ждать втрое дольше. Или получаете массив `[Promise, Promise, Promise]` вместо ожидаемых данных. Всё дело в том, как вы используете `await`, `map` и `forEach`.

Проблема не в асинхронности, а в том, как управляем ею внутри циклов. В этой статье разберём, почему интуитивное использование await в forEach, map и for...of приводит к сбоям, и систематизируем все доступные стратегии: от Promise.all() для скорости до управляемого параллелизма с помощью p-limit. Вы не только исправите код, но и поймёте, почему одно решение работает, а другое нет.

К концу статьи у вас будет чёткий алгоритм выбора под любую задачу и готовые шаблоны кода.

Почему циклы ведут себя не так, как ожидаем

Корень всех проблем — в несоответствии ментальной модели. Мы думаем: вызвать асинхронную функцию для каждого элемента. JavaScript же выполняет инструкции ровно так, как написали. Давайте разберём три классических заблуждения.

Антипаттерн 1: for...of с await — невидимая последовательность

Ловушка for...of в связке с await — это создание неявной последовательности. Цикл выглядит и читается как синхронный, но его поведение для асинхронных операций часто не соответствует ожиданиям разработчика, который хочет просто обработать массив данных.

// ВАЖНО: Код должен выполняться внутри async-функции
const users = [1, 2, 3];
for (const id of users) {
  const user = await fetchUser(id); // На каждой итерации выполнение асинхронной функции приостанавливается
                                    // на ключевом слове await, и цикл не переходит к следующей итерации,
                                    // пока текущий промис не разрешится.
  console.log(user);
}

Ключевое слово await приостанавливает выполнение текущей асинхронной функции. На каждой итерации цикл буквально ждёт завершения fetchUser(id), прежде чем перейти к следующему id. Это приводит к последовательному выполнению. Если один запрос длится 100 мс, три запроса займут ~300 мс, хотя их можно было запустить параллельно.

Когда это не ошибка? Используйте этот подход осознанно, только когда операции зависимы друг от друга (например, для создания id=2 нужен результат от id=1) или когда вы намеренно ограничиваете нагрузку на внешний сервис. Во всех остальных случаях это неоптимально.

Антипаттерн 2: map() с async — промисы вместо данных

Распространённая ошибка — ожидание, что map() «подождёт» результаты асинхронных операций. На самом деле map — синхронный метод: он последовательно, в том же потоке, вызывает переданную функцию для каждого элемента и немедленно возвращает новый массив. Если переданная функция — async, она возвращает промис, поэтому результатом map будет массив промисов, а не значений.

const users = [1, 2, 3];
const results = users.map(async (id) => {
  const user = await fetchUser(id);
  return user; // Возвращается Promise, а не данные пользователя
});
console.log(results); // Вывод: [Promise {<pending>}, Promise {<pending>}, Promise {<pending>}]
// Это НЕ массив пользователей. Это массив незавершённых обещаний.

Здесь map синхронно обходит массив users и для каждого id выполняет переданную async-функцию. Как и ожидалось, results содержит три объекта Promise в состоянии «ожидание». Сам map не обладает механизмом для их автоматического разрешения.

Правильная ментальная модель: Array.prototype.map() предназначен для синхронных преобразований. Для асинхронных операций он выступает лишь как генератор массива промисов. Чтобы получить реальные данные, этот массив нужно передать в Promise.all() или подобную функцию.

Антипаттерн 3: forEach с async — потеря контроля над выполнением

Самая распространённая ошибка с серьёзными последствиями — использование async-функции в качестве колбэка для forEach. В отличие от map, forEach не только не ждёт промисов, но и полностью игнорирует возвращаемые значения. Это превращает асинхронные операции в «неуправляемые операции» — мы их запускаем, но не можем поймать результаты или ошибки в нужный момент.

const users = [1, 2, 3];
users.forEach(async (id) => {
  const user = await fetchUser(id);
  console.log(user); // Вывод будет в порядке 1, 2, 3, НО...
});
console.log('Цикл "завершился"'); // Это сообщение появится ПЕРВЫМ

Метод forEach синхронно вызывает переданную async-функцию для каждого элемента и немедленно завершает свою работу, не дожидаясь разрешения промисов, которые эти функции возвращают. Все созданные асинхронные операции продолжают выполняться «в фоне».

Это приводит к двум проблемам:

  1. Невозможность синхронизироваться с завершением операций. Код после цикла выполняется сразу, и вы не можете узнать, когда все асинхронные операции внутри forEach завершились, чтобы продолжить работу с их результатами.
  2. Невозможность централизованно обработать ошибки без дополнительных механизмов.

Чем это опасно: Этот паттерн создаёт иллюзию работы, но на деле лишает контроля над выполнением. Вы не можете обработать ошибки, дождаться завершения всех операций или гарантировать порядок. В Node.js необработанные отклонения промисов (unhandled rejections) по умолчанию приводят к завершению процесса, что может вызвать аварийную остановку приложения. Это делает такой код особенно рискованным.

Каждая из этих ошибок возникает из-за неправильного управления временем выполнения и зависимостями. Для решения этих задач в JavaScript предусмотрены точные инструменты для каждой ситуации — от полного параллелизма до строгой последовательности. Давайте разберём их по порядку.

Стратегии: Выбираем инструмент под задачу

Разобравшись с типичными ошибками, можем перейти к эффективным решениям. Ключ к написанию надёжного асинхронного кода — осознанный выбор стратегии. Для этого нужно ответить на два вопроса:

  1. Зависимы ли операции друг от друга? (Нужен ли порядок?)
  2. Как мы хотим обрабатывать возможные ошибки?

Разные комбинации ответов приводят к разным инструментам. Начнём с самого популярного — Promise.all().

Стратегия 1: Promise.all() — скорость для независимых операций

Используйте Promise.all(), когда нужно максимально быстро выполнить набор независимых задач и вы готовы обработать ситуацию «всё или ничего».

Как это работает: Promise.all() принимает итерируемую коллекцию промисов (чаще всего — массив) и возвращает один новый промис. Этот новый промис будет удовлетворён (fulfilled) только тогда, когда успешно завершатся все переданные промисы. Его результатом будет массив результатов в строго том же порядке, в котором промисы были переданы в массив, независимо от того, в каком порядке они завершились. Если же хотя бы один из промисов будет отклонён (rejected), то и весь Promise.all() немедленно завершится с этой ошибкой.

// Правильное использование map с Promise.all
const users = [1, 2, 3];
const fetchUserPromises = users.map(id => fetchUser(id)); // map создаёт массив промисов

const results = await Promise.all(fetchUserPromises); // Ждём завершения ВСЕХ промисов
console.log(results); // Вывод: [{id: 1, ...}, {id: 2, ...}, {id: 3, ...}] - реальные данные!

Когда выбирать Promise.all():

Стратегия 2: Promise.allSettled() — полный контроль и отказоустойчивость

Используйте Promise.allSettled(), когда важно получить итог по каждой операции, независимо от того, завершилась она успешно или с ошибкой. Это ваш инструмент для сквозной аналитики, массовых операций с частичными сбоями или когда нужно выполнить максимально возможное количество задач.

Как это работает: В отличие от Promise.all(), Promise.allSettled() ждёт завершения всех переданных промисов — как успешных, так и неудачных. Возвращаемый промис никогда не будет отклонён. Вместо этого его результатом станет массив объектов специального формата, описывающих судьбу каждого исходного промиса.

const results = await Promise.allSettled(
  users.map(id => fetchUser(id))
);

// Структура результата для каждого промиса:
// { status: 'fulfilled', value: <результат> }  - если успех
// { status: 'rejected', reason: <ошибка> }     - если ошибка

results.forEach((result, index) => {
  if (result.status === 'fulfilled') {
    console.log(`✅ Пользователь ${index + 1}:`, result.value);
  } else {
    console.error(`❌ Ошибка для ${index + 1}:`, result.reason.message);
    // Можно добавить логику повторной попытки, подставить значение по умолчанию и т.д.
  }
});

Ключевое преимущество: Вы получаете полную картину выполнения пакета операций. Это позволяет принимать гибкие решения: логировать ошибки, отправлять уведомления, подставлять значения по умолчанию для неудачных элементов и при этом успешно обрабатывать корректные данные.

Когда выбирать Promise.allSettled():

Стратегия 3: for...of с await — осознанная последовательность

Интересно, что тот же самый паттерн, который был нашим первым антипаттерном, становится мощным и правильным решением, когда последовательное выполнение — это осознанное требование, а не случайный побочный эффект.

Тот же самый синтаксис (for...of + await) не является ошибкой сам по себе — ошибка возникает, когда его применяют в неподходящем контексте. В сценариях, где важна последовательность, этот паттерн — не только допустим, но и предпочтителен.

Используйте for...of с await, когда порядок операций критичен или когда вам нужно жёстко ограничить нагрузку (например, на внешний API или базу данных) самым простым способом.

Как это работает: Цикл for...of гарантирует, что каждая следующая итерация начнётся только после полного завершения (включая асинхронную часть) предыдущей. Это делает его идеальным для сценариев, где следующий запрос зависит от результата предыдущего.

// Пример 1: Последовательная обработка, где данные зависят друг от друга
const transactionIds = [101, 102, 103];
const results = [];

for (const id of transactionIds) {
  // Следующий шаг требует данных от предыдущего
  const data = await processTransaction(id);
  const validatedData = await validateStep(data); // Ждём валидации
  results.push(validatedData);
}
console.log('Все транзакции обработаны по порядку:', results);

// Пример 2: Простое и эффективное ограничение нагрузки (rate limiting)
const apiEndpoints = [...];
for (const endpoint of apiEndpoints) {
  await callExternalApi(endpoint); // Гарантирует, что следующий вызов будет только после завершения текущего
  // Этим мы предотвращаем DDoS или превышение лимита запросов (RPM) на стороннем сервисе
}

Когда выбирать for...of с await:

Стратегия 4: Управляемый параллелизм — баланс между скоростью и контролем

Иногда нужна «золотая середина»: запустить задачи параллельно для скорости, но ограничить количество одновременных операций, чтобы не перегрузить ресурсы (свои или внешнего API). Нативное API промисов не предоставляет такой функции, но её легко добавить с помощью библиотек, например, p-limit.

Используйте управляемый параллелизм, когда нужна высокая производительность, но есть жёсткие лимиты на одновременные подключения или нагрузку.

Как это работает: Библиотека создаёт «ограничитель« (limiter), который контролирует очередь промисов. Вы оборачиваете асинхронные функции в ограничитель, и он гарантирует, что одновременно будут выполняться не более указанного числа задач.

// Установка: npm install p-limit
import pLimit from 'p-limit';

const limit = pLimit(2); // Не более 2 промисов одновременно
const users = [1, 2, 3, 4, 5];

// Создаём массив "ограниченных" промисов
const limitedTasks = users.map(id =>
  limit(() => fetchUser(id)) // Ограничитель управляет выполнением этой функции
);

// Запускаем все задачи. Одновременно будут работать максимум 2 из них.
const results = await Promise.all(limitedTasks);
console.log(results); // Все 5 пользователей, полученные партиями по 2

Что происходит под капотом:

  1. Вы создаёте очередь с лимитом N.
  2. При создании задачи (limit(() => ...)) она попадает в очередь.
  3. Ограничитель автоматически запускает следующую задачу из очереди, как только завершается одна из N активных.
  4. Promise.all() ждёт завершения всей очереди.

Когда выбирать управляемый параллелизм:

Альтернатива без зависимостей: Для простых случаев можно реализовать базовое ограничение с помощью счётчика и очереди вручную, но p-limit предлагает отлаженное и эффективное решение.

Чтобы сохранить контроль над ошибками при использовании p-limit, оберните задачи в try/catch или используйте Promise.allSettled() вместо Promise.all(). Это особенно важно, если вы не хотите, чтобы одна ошибка прервала выполнение всех остальных задач.

Шпаргалка: таблица стратегий и готовые шаблоны

Теперь, когда все стратегии разобраны, давайте сведём их в одну схему для быстрого принятия решений и предложим готовые к использованию шаблоны кода.

Сравнение стратегий

Используйте эту таблицу как шпаргалку для быстрого принятия решений. Определите приоритеты задачи и выберите подходящую стратегию:

СтратегияКогда использоватьМодель выполненияОбработка ошибок
Promise.all()Независимые задачи, «всё или ничего»Параллельная (все операции запускаются одновременно)Прерывает выполнение при первой ошибке
Promise.allSettled()Отказоустойчивость, анализ всех результатовПараллельная (аналогично Promise.all, но с другой обработкой результатов)Сохраняет все ошибки, продолжает выполнение
for...of с awaitЗависимые задачи, порядок, rate limitingПоследовательная (операции выполняются строго одна за другой)Ошибка останавливает текущую итерацию, но цикл можно обернуть в try/catch
Управляемый параллелизмБаланс скорости и нагрузкиОграниченно-параллельная (операции выполняются параллельными "пакетами")Зависит от обёртки (обычно как Promise.all или Promise.allSettled)

Как пользоваться таблицей:

  1. Определите зависимость операций. Если операции зависимы или важен порядок — вам подходит Последовательная модель. Если операции независимы — выбирайте между Параллельной и Ограниченно-параллельной моделями.
  2. Определите приоритеты задачи — что важнее: скорость, надёжность или порядок?
  3. Проверьте ограничения — есть ли лимиты на одновременные запросы?
  4. Выберите подходящую строку — каждая стратегия решает конкретный класс задач.

Быстрый выбор по сценариям:

Готовые шаблоны кода

💡 Быстрые шаблоны (разверните нужный):

📦 Шаблон 1: Пакетная обработка с ограничением и обработкой ошибок

Функция для безопасного выполнения большого количества задач с контролем нагрузки и логированием всех результатов.

import pLimit from 'p-limit';

/**
 * Выполняет массив асинхронных задач с ограничением на количество одновременных.
 * @param {Array<any>} items - Массив данных для обработки.
 * @param {Function} asyncTask - Асинхронная функция (item) => Promise.
 * @param {Object} options - Настройки: limit, continueOnError.
 * @param {number} [options.limit=3] - Максимальное количество одновременных задач.
 * @param {boolean} [options.continueOnError=false] - Продолжать при ошибках.
 * @returns {Promise<Array> | Promise<Array<{status: string, value?: any, reason?: any}>>}
 *   Если continueOnError=false: массив результатов (как Promise.all).
 *   Если continueOnError=true: массив объектов {status, value|reason} (как Promise.allSettled).
 */
async function processBatch(items, asyncTask, options = {}) {
  const { limit = 3, continueOnError = false } = options;
  const limiter = pLimit(limit);

  // Создаём промисы с ограничением
  const promises = items.map(item =>
    limiter(() => asyncTask(item))
  );

  // Выбираем стратегию в зависимости от флага
  if (continueOnError) {
    // Режим "продолжать при ошибках"
    const results = await Promise.allSettled(promises);

    // Опционально: логируем ошибки для отладки
    results.forEach((result, index) => {
      if (result.status === 'rejected') {
        console.warn(`Задача ${index} завершилась с ошибкой:`, result.reason);
      }
    });

    return results;
  } else {
    // Режим "всё или ничего"
    return await Promise.all(promises);
  }
}

// Пример: имитация работы с API
const mockFetchUser = (userId) => {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (userId === 3) {
        reject(new Error(`Пользователь ${userId} заблокирован`));
      } else {
        resolve({ id: userId, name: `User ${userId}` });
      }
    }, Math.random() * 500);
  });
};

// Пример работы с результатами
results.forEach((result, index) => {
  if (result.status === 'fulfilled') {
    console.log(`✅ Успех для пользователя ${result.value.id}:`, result.value.name);
  } else {
    console.log(`❌ Ошибка для элемента ${index}:`, result.reason.message);
  }
});

Иногда даже правильная стратегия требует дополнительной надёжности — например, повторных попыток при сбоях сети. Универсальная функция retry(), которую можно использовать внутри любого цикла.

🔄 Шаблон 2: Последовательное выполнение с повторными попытками

Идеально для неустойчивых операций (сеть, сторонние API), которые требуют гарантии выполнения.

/**
 * Выполняет асинхронную функцию с повторными попытками при ошибке.
 * @param {Function} asyncFn - Выполняемая асинхронная функция.
 * @param {number} maxRetries - Максимальное количество попыток (по умолчанию 3).
 * @param {number} delayMs - Задержка между попытками в мс (по умолчанию 1000).
 * @returns {Promise<any>} - Результат выполнения функции.
 */
async function retry(asyncFn, maxRetries = 3, delayMs = 1000) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await asyncFn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      console.warn(`Попытка ${attempt} не удалась. Повтор через ${delayMs}мс.`, error);
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }
}

/**
 * Пример использования retry с обработкой ошибок:
 */
try {
  const result = await retry(
    () => fetchDataFromUnstableAPI(),
    3,    // максимум 3 попытки
    1000  // задержка 1 секунда между попытками
  );
  console.log('Успех:', result);
} catch (error) {
  console.error('Не удалось после всех попыток:', error);
  // Здесь можно добавить fallback-логику
}

Заключение

Управление асинхронностью в циклах — это не поиск одного «правильного» способа, а осознанный выбор инструмента под конкретную задачу. Больше не нужно запоминать, что «forEach с await не работает» — вместо этого вы понимаете почему и знаете, чем его заменить.

Ключ к мастерству — в ответе на два простых вопроса: «Зависят ли операции?» и «Как обрабатывать ошибки?».

Перестаньте бороться с асинхронностью. Начните управлять ею, выбирая стратегию, соответствующую вашей цели. Скопируйте готовые шаблоны из статьи, чтобы применять эти принципы в коде уже сегодня.

Комментарии


Предыдущая Статья

React изменился, хуки тоже должны измениться

Следующая Статья

Ленивые итераторы в JavaScript: руководство с примерами