Axios: co to jest, żądania HTTP i podstawy pracy z API

Czym jest Axios?

Axios to biblioteka JavaScript przeznaczona do wykonywania żądań HTTP z przeglądarki i środowiska Node.js. Jest zbudowana na bazie XMLHttpRequest w przeglądarce i modułu http w Node.js, udostępniając jednolity API dla obu platform.

Główną zaletą Axios w porównaniu z natywnym fetch jest automatyczna obsługa JSON, wsparcie dla przechwytywaczy i wygodniejsza praca z błędami. W przeciwieństwie do fetch, Axios nie wymaga dwóch wywołań .then do uzyskania treści JSON odpowiedzi i automatycznie zgłasza wyjątek przy błędach HTTP (4xx, 5xx).

Biblioteka obsługuje wszystkie główne metody HTTP: GET, POST, PUT, DELETE, PATCH i HEAD. Może być używana zarówno w prostych projektach, jak i w dużych aplikacjach korporacyjnych z setkami tysięcy żądań dziennie.

Kluczowe cechy Axios

• Promise API — wszystkie operacje zwracają Promise, co upraszcza kod asynchroniczny
• Obsługa TypeScript — pełna typizacja dla wszystkich metod i konfiguracji
• Interceptory — middleware do przetwarzania żądań i odpowiedzi
• Transformacja — automatyczne przekształcanie danych na wejściu i wyjściu

Architektura Axios i zasada działania

Architektura Axios opiera się na koncepcji adapterów (adapters). Biblioteka abstrahuje warstwę transportową: w przeglądarce używany jest XMLHttpRequest, w Node.js — moduł http lub https. Pozwala to na jednolity interfejs niezależnie od środowiska wykonawczego.

Każde żądanie przechodzi przez łańcuch przechwytywaczy (interceptors), które mogą modyfikować konfigurację żądania lub odpowiedzi. Po przechwytywaczach żądanie trafia do adaptera, który wykonuje rzeczywiste wywołanie HTTP. Odpowiedź następnie przechodzi przez interceptory odpowiedzi, zanim trafi do kodu aplikacji.

Cykl życia żądania Axios

1. Tworzenie konfiguracji — metoda, URL, nagłówki, treść żądania
2. Interceptor żądania — modyfikacja konfiguracji, dodawanie tokenów
3. Wywołanie HTTP — wykonanie przez adapter przeglądarki lub Node.js
4. Interceptor odpowiedzi — transformacja odpowiedzi, obsługa błędów
5. Zwrot wyniku — Promise jest rozwiązywany z danymi lub odrzucany

Główne możliwości Axios

Axios zawiera wiele wbudowanych funkcji, które czynią go wygodnym wyborem do pracy z HTTP w aplikacjach mobilnych i webowych. Omówmy najważniejsze z nich.

Automatyczna transformacja danych

Podczas wysyłania żądania Axios automatycznie przekształca obiekt JavaScript na ciąg JSON za pomocą JSON.stringify. Przy odbieraniu odpowiedzi biblioteka parsuje JSON z powrotem na obiekt. To zwalnia programistę z ręcznej serializacji i deserializacji danych.

Ochrona przed CSRF

W środowisku przeglądarki Axios automatycznie dodaje nagłówki XSRF-TOKEN z ciasteczka, chroniąc aplikację przed fałszowaniem żądań międzywitowych. W tym celu wystarczy skonfigurować serwer do przesyłania tokena w ciasteczku o nazwie XSRF-TOKEN.

Timeout i anulowanie żądań

Biblioteka obsługuje ustawienie timeoutu przez parametr timeout oraz anulowanie żądania przez AbortController. Jest to szczególnie ważne w aplikacjach mobilnych z niestabilnym połączeniem, gdzie zawieszone żądania pochłaniają baterię i transfer danych.

Instalacja i konfiguracja Axios

Instalacja Axios odbywa się za pomocą dowolnego menedżera pakietów. Biblioteka jest dostępna w rejestrze npm i może być podłączona zarówno w Node.js, jak i w projektach przeglądarkowych. Dla TypeScript typy są dołączone do głównego pakietu, nie są wymagane dodatkowe zależności.

Po instalacji można utworzyć instancję z podstawową konfiguracją: podstawowy URL, domyślny timeout, wspólne nagłówki. Pozwala to nie powtarzać tych samych parametrów w każdym żądaniu i centralnie zarządzać ustawieniami klienta HTTP.

# Instalacja przez npm
npm install axios

# Instalacja przez yarn
yarn add axios

# Instalacja przez pnpm
pnpm add axios

Tworzenie instancji z konfiguracją

Zaleca się tworzenie osobnej instancji Axios dla każdego serwisu API. Pozwala to ustawić podstawowy URL, standardowe nagłówki i timeout, które będą stosowane do wszystkich żądań tej instancji bez powtarzania w każdym wywołaniu.

import axios from 'axios';

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

Przykłady kodu z Axios

Przykłady żądań pokazują główne wzorce użycia Axios. Wszystkie przykłady używają składni async/await, która czyni kod asynchroniczny bardziej czytelnym w porównaniu z łańcuchami .then().

Żądanie GET z parametrami

Do pobierania danych z serwera używana jest metoda axios.get. Parametry żądania są przekazywane przez obiekt params, który jest automatycznie przekształcany na query-string. Odpowiedź zawiera dane w polu data, status w status i nagłówki w 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('Błąd ładowania użytkowników', error);
    throw error;
  }
}

Żądanie POST z ciałem

Do wysyłania danych na serwer używana jest axios.post. Drugim argumentem przekazywany jest obiekt z danymi, który Axios automatycznie serializuje do JSON. Typ treści Content-Type domyślnie ustawiany jest na 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;
}

Przechwytywacze (Interceptors)

Interceptory to funkcje middleware, które są wykonywane dla każdego żądania lub odpowiedzi. Umożliwiają dodawanie tokenów autoryzacji, logowanie żądań, centralną obsługę błędów. Interceptor żądania dodaje nagłówek Authorization z tokenem pobranym z magazynu.

// Interceptor żądania — dodaje token autoryzacji
api.interceptors.request.use(
  (config) => {
    const token = getToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Interceptor odpowiedzi — obsługuje błędy 401
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

Obsługa błędów w Axios

Obsługa błędów w Axios opiera się na mechanizmie wyjątków. W przeciwieństwie do fetch, Axios automatycznie przechwytuje błędy HTTP (4xx, 5xx) i przekazuje je do bloku catch. Obiekt błędu zawiera informacje o odpowiedzi serwera, żądaniu i kontekście wykonania.

Ważne jest rozróżnienie trzech typów błędów: błąd odpowiedzi serwera (response), błąd żądania (request) i błąd konfiguracji (config). Pierwszy występuje przy pomyślnym wykonaniu wywołania HTTP z kodem błędu, drugi — przy braku odpowiedzi z serwera, trzeci — przy nieprawidłowej konfiguracji żądania.

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('Błąd odpowiedzi', error.response.status);
      } else if (error.request) {
        console.warn('Brak odpowiedzi z serwera');
      } else {
        console.warn('Błąd konfiguracji');
      }
    }
  }
}

Porównanie Axios z Fetch API

Porównanie Axios z natywnym Fetch API pomaga zrozumieć, kiedy każda technologia jest odpowiednia. Fetch to wbudowane w przeglądarkę API, które nie wymaga instalacji. Axios to biblioteka zewnętrzna z dodatkowymi funkcjami. Do prostych żądań wystarczy fetch, do złożonych aplikacji z przechwytywaczami i centralną obsługą błędów wygodniejszy jest Axios.

Fetch nie traktuje błędów HTTP (4xx, 5xx) jako wyjątków — należy sprawdzać response.ok. Fetch wymaga dwóch wywołań .then() do uzyskania JSON: response.json() następnie zwraca Promise z danymi. Axios robi to automatycznie. Fetch nie obsługuje postępu przesyłania plików bez dodatkowego polyfill. Axios ma wbudowane onUploadProgress i onDownloadProgress.

W Node.js Fetch jest dostępny od wersji 18 jako funkcja eksperymentalna, a Axios działa stabilnie od Node.js 10. Dla projektów wspierających starsze wersje Node.js wybór jest oczywisty na korzyść Axios. Dla nowoczesnych projektów przeglądarkowych bez złożonego przetwarzania żądań fetch może być wystarczający.