Axios: ce este, cereri HTTP și elementele de bază ale lucrului cu API

Ce este Axios?

Axios este o bibliotecă JavaScript destinată executării cererilor HTTP din browser și din mediul Node.js. Este construită pe baza XMLHttpRequest în browser și a modulului http în Node.js, oferind o interfață unică pentru ambele platforme.

Principalul avantaj al Axios față de fetch nativ este procesarea automată JSON, suportul pentru interceptoare și lucrul mai convenabil cu erorile. Spre deosebire de fetch, Axios nu necesită două apeluri .then pentru a obține corpul JSON al răspunsului și aruncă automat o excepție la erorile HTTP (4xx, 5xx).

Biblioteca suportă toate metodele HTTP principale: GET, POST, PUT, DELETE, PATCH și HEAD. Poate fi utilizată atât în proiecte simple, cât și în aplicații corporative mari cu sute de mii de cereri zilnice.

Caracteristici cheie ale Axios

• Promise API — toate operațiile returnează Promise, simplificând codul asincron
• Suport TypeScript — tipizare completă pentru toate metodele și configurațiile
• Interceptoare — middleware pentru procesarea cererilor și răspunsurilor
• Transformare — conversia automată a datelor la intrare și ieșire

Arhitectura Axios și principiul de funcționare

Arhitectura Axios se bazează pe conceptul de adaptoare (adapters). Biblioteca abstractizează stratul de transport: în browser se utilizează XMLHttpRequest, în Node.js — modulul http sau https. Acest lucru permite o interfață unică indiferent de mediul de execuție.

Fiecare cerere trece printr-un lanț de interceptoare (interceptors) care pot modifica configurația cererii sau răspunsului. După interceptoare, cererea este transmisă adaptorului care execută apelul HTTP real. Răspunsul trece apoi prin interceptoarele de răspuns înainte de a ajunge în codul aplicației.

Ciclul de viață al cererii Axios

1. Crearea configurației — metodă, URL, anteturi, corpul cererii
2. Interceptor de cerere — modificarea configurației, adăugarea tokenurilor
3. Apel HTTP — execuția prin adaptorul browserului sau Node.js
4. Interceptor de răspuns — transformarea răspunsului, gestionarea erorilor
5. Returnarea rezultatului — Promise este rezolvat cu date sau respins

Principalele capacități ale Axios

Axios include numeroase capacități încorporate care îl fac o alegere convenabilă pentru lucrul cu HTTP în aplicațiile mobile și web. Să examinăm cele mai importante dintre ele.

Transformarea automată a datelor

La trimiterea unei cereri, Axios convertește automat obiectul JavaScript într-un șir JSON folosind JSON.stringify. La primirea răspunsului, biblioteca parsează JSON-ul înapoi într-un obiect. Acest lucru eliberează programatorul de serializarea și deserializarea manuală a datelor.

Protecția împotriva CSRF

În mediul browserului, Axios adaugă automat anteturile XSRF-TOKEN din cookie, protejând aplicația împotriva falsificării cererilor între site-uri. Pentru aceasta, este suficient să configurați serverul să trimită tokenul într-un cookie cu numele XSRF-TOKEN.

Timeout și anularea cererilor

Biblioteca suportă setarea unui timeout prin parametrul timeout și anularea cererii prin AbortController. Acest lucru este deosebit de important în aplicațiile mobile cu conexiune instabilă, unde cererile blocate consumă baterie și trafic.

Instalarea și configurarea Axios

Instalarea Axios se efectuează prin orice manager de pachete. Biblioteca este disponibilă în registrul npm și poate fi conectată atât în Node.js, cât și în proiecte browser. Pentru TypeScript, tipurile sunt incluse în pachetul principal, nu sunt necesare dependențe suplimentare.

După instalare, puteți crea o instanță cu configurație de bază: URL de bază, timeout implicit, anteturi comune. Acest lucru permite evitarea repetării acelorași parametri în fiecare cerere și gestionarea centralizată a setărilor clientului HTTP.

# Instalare prin npm
npm install axios

# Instalare prin yarn
yarn add axios

# Instalare prin pnpm
pnpm add axios

Crearea unei instanțe cu configurație

Se recomandă crearea unei instanțe separate Axios pentru fiecare serviciu API. Acest lucru permite setarea URL-ului de bază, anteturilor standard și timeout-ului care se vor aplica tuturor cererilor acestei instanțe fără repetare în fiecare apel.

import axios from 'axios';

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

Exemple de cod cu Axios

Exemple de cereri arată principalele modele de utilizare a Axios. Toate exemplele folosesc sintaxa async/await care face codul asincron mai lizibil în comparație cu lanțurile .then().

Cerere GET cu parametri

Pentru obținerea datelor de la server se utilizează metoda axios.get. Parametrii cererii se transmit prin obiectul params, care este convertit automat în query-string. Răspunsul conține datele în câmpul data, statusul în status și anteturile în 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('Eroare la încărcarea utilizatorilor', error);
    throw error;
  }
}

Cerere POST cu corp

Pentru trimiterea datelor la server se utilizează axios.post. Al doilea argument este un obiect cu date pe care Axios le serializează automat în JSON. Tipul de conținut Content-Type este setat implicit la 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;
}

Interceptoare (Interceptors)

Interceptoarele sunt funcții middleware care se execută pentru fiecare cerere sau răspuns. Ele permit adăugarea tokenurilor de autorizare, logarea cererilor, gestionarea centralizată a erorilor. Interceptorul de cerere adaugă antetul Authorization cu tokenul extras din stocare.

// Interceptor de cerere — adaugă tokenul de autorizare
api.interceptors.request.use(
  (config) => {
    const token = getToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Interceptor de răspuns — gestionează erorile 401
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

Gestionarea erorilor în Axios

Gestionarea erorilor în Axios se bazează pe mecanismul excepțiilor. Spre deosebire de fetch, Axios interceptează automat erorile HTTP (4xx, 5xx) și le transmite în blocul catch. Obiectul eroare conține informații despre răspunsul serverului, cerere și contextul de execuție.

Este important să distingem trei tipuri de erori: eroare de răspuns a serverului (response), eroare de cerere (request) și eroare de configurare (config). Prima apare la executarea cu succes a apelului HTTP cu un cod de eroare, a doua — la lipsa răspunsului de la server, a treia — la configurarea incorectă a cererii.

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('Eroare de răspuns', error.response.status);
      } else if (error.request) {
        console.warn('Nu există răspuns de la server');
      } else {
        console.warn('Eroare de configurare');
      }
    }
  }
}

Compararea Axios cu Fetch API

Compararea Axios cu Fetch API nativ ajută la înțelegerea când fiecare tehnologie este potrivită. Fetch este un API încorporat în browser care nu necesită instalare. Axios este o bibliotecă terță cu capacități suplimentare. Pentru cereri simple, fetch este suficient, pentru aplicații complexe cu interceptoare și gestionare centralizată a erorilor, Axios este mai convenabil.

Fetch nu consideră erorile HTTP (4xx, 5xx) excepții — trebuie verificat response.ok. Fetch necesită două apeluri .then() pentru a obține JSON: response.json() apoi returnează Promise cu datele. Axios face acest lucru automat. Fetch nu suportă progresul încărcării fișierelor fără polyfill suplimentar. Axios are onUploadProgress și onDownloadProgress încorporate.

În Node.js, Fetch este disponibil de la versiunea 18 ca funcție experimentală, iar Axios funcționează stabil începând cu Node.js 10. Pentru proiectele care suportă versiuni vechi de Node.js, alegerea este evidentă în favoarea Axios. Pentru proiectele browser moderne fără procesare complexă a cererilor, fetch poate fi suficient.