Большинство современных веб-приложений постоянно взаимодействуют с сервером. JavaScript Fetch API — это стандартный способ сделать это, он встроен в браузеры, а также в Node.js 18 и более поздних версий, поэтому устанавливать нечего.

Базовое использование занимает две строки, однако многие руководства останавливаются на этом и опускают ту часть, которая вызывает реальные ошибки: обработку сбоев. Мы протестировали примеры в этом руководстве на небольшом локальном сервере Node.js 24, и показанный результат получен в результате этого запуска. example.com в коде обозначает ваш собственный API. Если обещания для вас новы, начните с объяснения обещаний JavaScript.

Что такое API-интерфейс Fetch?

Fetch — это основанный на обещаниях интерфейс для выполнения HTTP-запросов. Он заменил старый метод, управляемый обратными вызовами XMLHttpRequest, и теперь многие проекты используют его вместо добавления библиотеки для простых вызовов.

GET-запрос

Fetch по умолчанию выполняет запрос GET. Есть два шага, и каждый из них требует await: сначала приходят заголовки ответа, а затем вы читаете тело.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

Эти два шага существуют, потому что тело может быть большим и приходить позже заголовков. В скрипте браузера для верхнего уровня await нужен модуль, поэтому вы обычно помещаете его в функцию async. См. наше руководство по асинхронности/ожиданию JavaScript.

Объект ответа

Прежде чем читать тело, вы можете проверить ответ:

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

Тело можно прочитать только один раз. Вызов json() во второй раз в нашем тесте не удался:

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

Если вам нужно прочитать его дважды, сначала вызовите response.clone().

Большой сюрприз: ошибка 404 не выдает

Это самое главное в этой статье. Мы запросили пользователя, которого не существует:

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

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

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

Ознакомьтесь с нашей шпаргалкой по кодам статуса HTTP, чтобы узнать, что означает каждый код.

Многоразовый помощник

Не повторяйте эту проверку везде. Оберните его один раз:

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

Теперь ошибки HTTP и сетевые ошибки оказываются в одном и том же catch. Эту небольшую функцию стоит иметь в каждом проекте. Реальная версия также может считывать сообщение об ошибке из тела ответа и обрабатывать ответ 204 No Content, в котором нет JSON для анализа.

POST-данные в формате JSON

Передайте объект параметров в качестве второго аргумента. Для JSON вам необходимо сделать две вещи самостоятельно: преобразовать данные в строку и установить заголовок.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

Наш тестовый сервер вернул полученный тип контента, подтвердив получение заголовка. Забывание этого заголовка является распространенной причиной запутанных ошибок сервера, поскольку многие платформы анализируют JSON только тогда, когда он объявлен. Чтобы загрузить форму или файлы, передайте объект FormData в качестве тела и не устанавливайте Content-Type, поскольку браузеру необходимо самому добавить граничное значение.

Другие методы и варианты

Выбираете между REST и другими стилями API? Наше сравнение REST и GraphQL показывает, насколько fetch подходит для каждого из них.

Строки запроса

Не создавайте строки запроса путем объединения текста, поскольку специальные символы разрушают их. URLSearchParams обрабатывает кодировку за вас:

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

Сервер получил red shoes правильно, место было восстановлено.

Тайм-ауты и отмена

Fetch будет долго ждать на медленном сервере, если вы не укажете иное. AbortSignal.timeout() устанавливает предел. Конечная точка нашего теста заняла две секунды при пределе в 200 миллисекунд:

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

Для отмены вручную, например, когда пользователь покидает страницу или вводит новый поисковый запрос, используйте AbortController:

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

Чтобы выполнить несколько запросов одновременно, используйте Promise.all, что намного быстрее, чем ожидать их по одному:

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

Всякий вид неудачи

Вот как выглядел каждый сбой в нашем тесте, а также как их отличить:

Последний ряд часто встречается в производстве. Прокси-сервер, возвращающий код 502, часто отправляет страницу с ошибкой HTML. Мы воспроизвели это, и res.json() бросил SyntaxError. Проверка response.ok перед анализом означает, что вы сообщаете о реальной проблеме, а не о запутанной ошибке анализа.

CORS и учетные данные

В браузере запрос от одного источника к другому регулируется CORS, правилами совместного использования ресурсов между источниками. Если вы видите ошибку с упоминанием Access-Control-Allow-Origin, исправление принадлежит серверу, который должен разрешить ваш сайт. В вашем JavaScript сбой отображается только как общий TypeError, поэтому посмотрите на консоль браузера, чтобы узнать истинную причину. Node.js не применяет CORS, поэтому запрос, который работает в сценарии, все равно может завершиться неудачей в браузере.

По умолчанию браузеры не отправляют файлы cookie при запросах между источниками. Установите credentials: "include", если они вам нужны, и убедитесь, что сервер это разрешает. Никогда не помещайте секретные ключи API в JavaScript браузера, поскольку их может прочитать любой. Держите их на своем сервере.

Распространенные ошибки

• Не проверяется. response.ok. Ответы об ошибках рассматриваются как успешные.
• Забывание второго await. response.json() также возвращает обещание.
• Забывание JSON.stringify. Передача объекта по мере отправки тела [object Object].
• Настройка Content-Type с FormData. Это нарушает границу, поэтому оставьте это.
• Отсутствие тайм-аута. Зависший запрос может привести к тому, что счетчик страницы будет работать бесконечно.
• Разбор JSON на предмет пустого ответа. У 204 нет тела, и json() выдаст ошибку.

Итоги

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

Часто задаваемые вопросы

Продолжайте учиться