Axios → fetch у Node.js: як не пропустити зміну помилок і таймаутів

Зелені тести можуть приховати зміну поведінки

У pull request усе виглядає просто: видалено пакет Axios, змінено кілька викликів, тести пройшли. Але після розгортання зовнішній сервіс повертає 500, а застосунок більше не потрапляє у звичну гілку обробки помилки. Запит технічно завершився, проте його результат витлумачено інакше.

Саме так механічна заміна імпорту перетворюється на нічний сигнал тривоги. Команда має цілком нормальну мету — зменшити кількість залежностей і використовувати вбудований API Node.js. Та користувачі не повинні перевіряти сумісність замість розробників.

Під час такої зміни мігрує не лише синтаксис. Мігрує поведінковий контракт: які статуси вважаються помилками, коли запит припиняється, як читається тіло та які дані потрапляють у журнали й трасування.

Спочатку знайдіть приховану роботу Axios

Пошукайте не лише axios.get і axios.post. Перевірте axios.create, глобальні defaults, перехоплювачі, власні обгортки та модулі з назвами на кшталт apiClient або httpService.

Для кожного маршруту запишіть базову адресу, заголовки авторизації, параметри, формат тіла, таймаут, повторні запити та очікувану форму відповіді. Окремо позначте validateStatus, proxy, httpsAgent, responseType і обробку перенаправлень. Якщо ці правила не видно в місці виклику, їх міг додавати спільний перехоплювач.

Критерій переходу далі простий: команда може показати шлях запиту від бізнес-коду до мережі й назвати політики, які застосовуються на цьому шляху.

Зафіксуйте сумісність до переписування

Офіційний матеріал Node.js звертає увагу на ключову різницю: Axios типово відхиляє проміс для статусів поза успішним діапазоном, а fetch повертає звичайний Response. Для 404 або 500 треба явно перевіряти response.ok чи response.status.

Ділянка	Що перевірити
Статуси	Які коди стають помилками та які поля має помилка
Тіло	Коли читати JSON, текст або потік; що робити з порожнім чи пошкодженим JSON
Таймаут	Який AbortSignal припиняє запит і як відрізнити таймаут від ручного скасування
Redirect	Чи дозволені переходи та що стається з чутливими заголовками
Proxy і TLS	Як маршрут і сертифікати налаштовані саме у ваших версіях Node.js
Streaming	Чи готовий код працювати з потоками fetch без буферизації всього тіла

Налаштування Axios не слід переносити за схожою назвою. Наприклад, httpsAgent не є готовою конфігурацією для fetch. Перевіряйте задокументований спосіб для своєї версії Node.js і реального мережевого маршруту.

Зробіть тонкий адаптер, а не копію Axios

У fetch немає API перехоплювачів Axios. Повторювані правила авторизації, журналювання, tracing і класифікації помилок краще зібрати у власному адаптері:

async function fetchJson(url, options = {}) {
  const response = await fetch(url, options);
  const text = await response.text();
  const data = text ? JSON.parse(text) : null;

  if (!response.ok) {
    const error = new Error(`HTTP ${response.status}`);
    error.status = response.status;
    error.body = data;
    throw error;
  }

  return { status: response.status, headers: response.headers, data };
}

const result = await fetchJson(url, {
  signal: AbortSignal.timeout(5_000)
});

Це лише початкова форма: політику для порожнього тіла, пошкодженого JSON і таймауту має визначити команда. Не намагайтеся відтворити весь Axios. І не додавайте автоматичний повтор кожного запиту: повторення POST може дублювати дію на сервері.

Перевіряйте обидва клієнти одним контрактом

Створіть спільний інтерфейс send(request) і запустіть однакові контрактні тести для Axios та нового адаптера. Локальний сервер або керований mock-сервіс має повертати 200, 404, 500, повільну відповідь, порожнє тіло, пошкоджений JSON, redirect і передчасний розрив з’єднання.

Перевіряйте не лише результат. Підтвердьте наявність заголовків авторизації та tracing, форму помилки, причину скасування й відсутність небезпечних повторів. Proxy, TLS і великі потоки додатково тестуйте в середовищі з реальною мережевою конфігурацією.

Вмикайте зміну так, щоб її можна було зупинити

Спочатку переведіть один безпечний зовнішній маршрут або малу частку трафіку. Порівнюйте частоту 4xx/5xx, таймаутів, скасувань і помилок розбору тіла, а також затримку на високих процентилях. Журнали старого й нового шляху повинні мати однакові ідентифікатори запиту.

Збережіть конфігураційний перемикач для швидкого відкату. Не надсилайте «тіньові» копії запитів із побічними ефектами лише заради порівняння. Умови зупинки — наприклад, зростання таймаутів або втрата трас — погодьте до розгортання, а не після першого збою.

Оберіть варіант за ризиком, а не за модою

Мігруйте зараз, якщо використання Axios централізоване, контракт описаний, а мережеві сценарії перевірені. Спочатку ізолюйте Axios за адаптером, якщо виклики й перехоплювачі розкидані по кодовій базі. Залиште його, якщо складні proxy, TLS або streaming-сценарії вже надійні, а користь від заміни не покриває вартість перевірки.

Хороший результат — не видалений пакет сам по собі. Це передбачувана поведінка HTTP-запитів і відкат, який команда справді може виконати.

Джерела

• Migrating from Axios to Fetch — Node.js
• Node.js Blog feed