Axios: какво е, HTTP заявки и основи на работа с API

Какво е Axios?

Axios е JavaScript библиотека за изпълнение на HTTP заявки от браузър и среда Node.js. Изградена е върху XMLHttpRequest в браузъра и модула http в Node.js, предоставяйки единен API за двете платформи.

Основното предимство на Axios пред native fetch е автоматичната обработка на JSON, поддръжката на прихващачи и по-удобната работа с грешки. За разлика от fetch, Axios не изисква две извиквания на .then за получаване на JSON тялото на отговора и автоматично хвърля изключение при HTTP грешки (4xx, 5xx).

Библиотеката поддържа всички основни HTTP методи: GET, POST, PUT, DELETE, PATCH и HEAD. Може да се използва както в прости проекти, така и в големи корпоративни приложения със стотици хиляди заявки дневно.

Ключови характеристики на Axios

• Promise API — всички операции връщат Promise, опростявайки асинхронния код
• Поддръжка на TypeScript — пълно типизиране за всички методи и конфигурации
• Прихващачи — middleware за обработка на заявки и отговори
• Трансформация — автоматично преобразуване на данни на входа и изхода

Архитектура на Axios и принцип на работа

Архитектурата на Axios се основава на концепцията за адаптери (adapters). Библиотеката абстрахира транспортния слой: в браузъра се използва XMLHttpRequest, в Node.js — модул http или https. Това позволява единен интерфейс независимо от средата на изпълнение.

Всяка заявка преминава през верига от прихващачи (interceptors), които могат да модифицират конфигурацията на заявката или отговора. След прихващачите заявката се предава на адаптера, който изпълнява реалното HTTP извикване. Отговорът след това преминава през прихващачите на отговора, преди да достигне до кода на приложението.

Жизнен цикъл на заявка в Axios

1. Създаване на конфигурация — метод, URL, заглавки, тяло на заявката
2. Прихващач на заявка — модификация на конфигурация, добавяне на токени
3. HTTP извикване — изпълнение чрез адаптер на браузър или Node.js
4. Прихващач на отговор — трансформация на отговор, обработка на грешки
5. Връщане на резултат — Promise се разрешава с данни или се отхвърля

Основни възможности на Axios

Axios включва множество вградени възможности, които го правят удобен избор за работа с HTTP в мобилни и уеб приложения. Нека разгледаме най-важните от тях.

Автоматична трансформация на данни

При изпращане на заявка Axios автоматично преобразува JavaScript обект в JSON низ чрез JSON.stringify. При получаване на отговор библиотеката парсира JSON обратно в обект. Това освобождава разработчика от ръчна сериализация и десериализация на данни.

Защита от CSRF

В браузърна среда Axios автоматично добавя заглавки XSRF-TOKEN от бисквитката, защитавайки приложението от междусайтово подправяне на заявки. За целта е достатъчно да конфигурирате сървъра да изпраща токен в бисквитка с име XSRF-TOKEN.

Таймаут и отмяна на заявки

Библиотеката поддържа задаване на таймаут чрез параметъра timeout и отмяна на заявка чрез AbortController. Това е особено важно в мобилни приложения с нестабилна връзка, където закъснелите заявки консумират батерия и трафик.

Инсталация и настройка на Axios

Инсталацията на Axios се извършва чрез всеки мениджър на пакети. Библиотеката е достъпна в npm регистъра и може да бъде свързана както в Node.js, така и в браузърни проекти. За TypeScript типовете са включени в основния пакет, не са необходими допълнителни зависимости.

След инсталация можете да създадете инстанция с основна конфигурация: основен URL, таймаут по подразбиране, общи заглавки. Това позволява да не повтаряте едни и същи параметри във всяка заявка и централизирано да управлявате настройките на HTTP клиента.

# Инсталация чрез npm
npm install axios

# Инсталация чрез yarn
yarn add axios

# Инсталация чрез pnpm
pnpm add axios

Създаване на инстанция с конфигурация

Препоръчително е да създавате отделна инстанция Axios за всяка API услуга. Това позволява задаване на основен URL, стандартни заглавки и таймаут, които ще се прилагат към всички заявки на тази инстанция без повторение във всяко извикване.

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.example.com/v1',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

Примери за код с Axios

Примери за заявки показват основните модели на използване на Axios. Всички примери използват синтаксис async/await, който прави асинхронния код по-четим в сравнение с .then() вериги.

GET заявка с параметри

За получаване на данни от сървъра се използва методът axios.get. Параметрите на заявката се предават чрез обекта params, който автоматично се преобразува в query-string. Отговорът съдържа данни в полето data, статус в status и заглавки в headers.

interface User {
  id: number;
  name: string;
  email: string;
}

async function getUsers() {
  try {
    const response = await api.get<User[]>('/users', {
      params: { page: 1, limit: 10 }
    });
    return response.data;
  } catch (error) {
    console.error('Грешка при зареждане на потребители', error);
    throw error;
  }
}

POST заявка с тяло

За изпращане на данни към сървъра се използва axios.post. Вторият аргумент е обект с данни, който Axios автоматично сериализира в JSON. Типът съдържание Content-Type по подразбиране се задава на application/json.

interface CreateUserDto {
  name: string;
  email: string;
  role: string;
}

async function createUser(data: CreateUserDto) {
  const response = await api.post<User>('/users', data);
  return response.data;
}

Прихващачи (Interceptors)

Прихващачите са middleware функции, които се изпълняват за всяка заявка или отговор. Те позволяват добавяне на токени за авторизация, регистриране на заявки, централизирана обработка на грешки. Прихващачът на заявка добавя заглавка Authorization с токен, извлечен от хранилището.

// Прихващач на заявка — добавя токен за авторизация
api.interceptors.request.use(
  (config) => {
    const token = getToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Прихващач на отговор — обработва 401 грешки
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

Обработка на грешки в Axios

Обработката на грешки в Axios се основава на механизма за изключения. За разлика от fetch, Axios автоматично улавя HTTP грешките (4xx, 5xx) и ги предава на catch блока. Обектът на грешка съдържа информация за отговора на сървъра, заявката и контекста на изпълнение.

Важно е да се разграничат три типа грешки: грешка в отговора на сървъра (response), грешка в заявката (request) и грешка в конфигурацията (config). Първата възниква при успешно HTTP извикване с код за грешка, втората — при липса на отговор от сървъра, третата — при неправилна конфигурация на заявката.

import axios, { AxiosError } from 'axios';

async function safeRequest() {
  try {
    return await api.get('/data');
  } catch (error) {
    if (error instanceof AxiosError) {
      if (error.response) {
        console.warn('Грешка в отговора', error.response.status);
      } else if (error.request) {
        console.warn('Няма отговор от сървъра');
      } else {
        console.warn('Грешка в конфигурацията');
      }
    }
  }
}

Сравнение на Axios с Fetch API

Сравнението на Axios с native Fetch API помага да се разбере кога всяка технология е подходяща. Fetch е вграден в браузъра API, който не изисква инсталация. Axios е библиотека на трета страна с допълнителни възможности. За прости заявки fetch е достатъчен, за сложни приложения с прихващачи и централизирана обработка на грешки Axios е по-удобен.

Fetch не счита HTTP грешките (4xx, 5xx) за изключения — трябва да проверите response.ok. Fetch изисква две извиквания на .then() за получаване на JSON: response.json() след това връща Promise с данни. Axios прави това автоматично. Fetch не поддържа прогрес на качване на файлове без допълнителен polyfill. Axios има вградени onUploadProgress и onDownloadProgress.

В Node.js Fetch е достъпен от версия 18 като експериментална функция, докато Axios работи стабилно от Node.js 10. За проекти, поддържащи по-стари версии на Node.js, изборът е очевиден в полза на Axios. За съвременни браузърни проекти без сложна обработка на заявки fetch може да бъде достатъчен.