Axios: mi ez, HTTP-kérések és az API-val való munka alapjai

Mi az Axios?

Az Axios egy JavaScript könyvtár HTTP-kérések végrehajtására a böngészőből és a Node.js környezetből. A böngészőben a XMLHttpRequest-re, a Node.js-ben pedig a http modulra épül, egységes API-t biztosítva mindkét platformhoz.

Az Axios fő előnye a natív fetch-hez képest az automatikus JSON-feldolgozás, az elfogók támogatása és a kényelmesebb hibakezelés. A fetch-tel ellentétben az Axios nem igényel két .then hívást a válasz JSON törzsének lekéréséhez, és automatikusan kivételt dob HTTP-hibák (4xx, 5xx) esetén.

A könyvtár támogatja az összes fő HTTP-metódust: GET, POST, PUT, DELETE, PATCH és HEAD. Használható mind egyszerű projektekben, mind nagy vállalati alkalmazásokban napi százezer kéréssel.

Az Axios legfontosabb jellemzői

• Promise API — minden művelet Promise-t ad vissza, leegyszerűsítve az aszinkron kódot
• TypeScript támogatás — teljes típusozás az összes metódushoz és konfigurációhoz
• Elfogók — middleware a kérések és válaszok feldolgozásához
• Transzformáció — az adatok automatikus konvertálása bemeneten és kimeneten

Az Axios architektúrája és működési elve

Az Axios architektúrája az adapterek (adapters) koncepcióján alapul. A könyvtár elvonatkoztatja a szállítási réteget: a böngészőben XMLHttpRequest, a Node.js-ben a http vagy https modul használatos. Ez egységes interfészt tesz lehetővé a végrehajtási környezettől függetlenül.

Minden kérés áthalad az elfogók (interceptors) láncán, amelyek módosíthatják a kérés vagy válasz konfigurációját. Az elfogók után a kérés továbbításra kerül az adapterhez, amely elvégzi a tényleges HTTP-hívást. A válasz ezután áthalad a válasz-elfogókon, mielőtt elérné az alkalmazás kódját.

Az Axios kérés életciklusa

1. Konfiguráció létrehozása — metódus, URL, fejlécek, kérés törzse
2. Kérés elfogó — konfiguráció módosítása, tokenek hozzáadása
3. HTTP-hívás — végrehajtás a böngésző vagy Node.js adapteren keresztül
4. Válasz elfogó — válasz transzformációja, hibakezelés
5. Eredmény visszaadása — a Promise feloldásra kerül adatokkal vagy elutasításra

Az Axios fő képességei

Az Axios számos beépített képességet tartalmaz, amelyek kényelmes választássá teszik a HTTP-vel való munkához mobil és webes alkalmazásokban. Tekintsük át a legfontosabbakat.

Automatikus adat-transzformáció

Kérés küldésekor az Axios automatikusan JSON stringgé alakítja a JavaScript objektumot a JSON.stringify segítségével. Válasz fogadásakor a könyvtár visszaparse-olja a JSON-t objektummá. Ez megszabadítja a fejlesztőt az adatok kézi szerializációjától és deszerializációjától.

CSRF védelem

A böngésző környezetben az Axios automatikusan hozzáadja a XSRF-TOKEN fejléceket a sütiből, megvédve az alkalmazást a webhelyek közötti kérés hamisítástól. Ehhez elegendő a szervert úgy konfigurálni, hogy XSRF-TOKEN nevű sütiben küldje a tokent.

Időtúllépés és kérések megszakítása

A könyvtár támogatja az időtúllépés beállítását a timeout paraméteren keresztül és a kérés megszakítását AbortController segítségével. Ez különösen fontos az instabil kapcsolattal rendelkező mobilalkalmazásokban, ahol a beragadt kérések akkumulátort és adatforgalmat fogyasztanak.

Az Axios telepítése és konfigurálása

Az Axios telepítése bármely csomagkezelőn keresztül történik. A könyvtár elérhető az npm regiszterben, és csatlakoztatható mind Node.js-ben, mind böngésző projektekben. TypeScripthez a típusok a fő csomagban találhatók, nincs szükség további függőségekre.

Telepítés után létrehozható egy példány alapkonfigurációval: alap URL, alapértelmezett időtúllépés, közös fejlécek. Ez lehetővé teszi, hogy ne ismételje meg ugyanazokat a paramétereket minden kérésben, és központilag kezelje a HTTP-kliens beállításait.

# Telepítés npm-en keresztül
npm install axios

# Telepítés yarn-on keresztül
yarn add axios

# Telepítés pnpm-en keresztül
pnpm add axios

Példány létrehozása konfigurációval

Ajánlott külön Axios példányt létrehozni minden API szolgáltatáshoz. Ez lehetővé teszi az alap URL, a standard fejlécek és az időtúllépés beállítását, amelyek a példány összes kérésére vonatkoznak anélkül, hogy minden hívásban meg kellene ismételni.

import axios from 'axios';

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

Kódpéldák Axios-szal

Kéréspéldák bemutatják az Axios fő használati mintáit. Minden példa az async/await szintaxist használja, amely olvashatóbbá teszi az aszinkron kódot a .then() láncokhoz képest.

GET kérés paraméterekkel

Adatok lekéréséhez a szerverről az axios.get metódus használatos. A kérés paraméterei a params objektumon keresztül kerülnek átadásra, amely automatikusan query-stringé alakul. A válasz a data mezőben tartalmazza az adatokat, a status mezőben az állapotot és a headers mezőben a fejléceket.

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('Hiba a felhasználók betöltésekor', error);
    throw error;
  }
}

POST kérés törzzsel

Adatok szerverre küldéséhez az axios.post használatos. A második argumentum egy adatokat tartalmazó objektum, amelyet az Axios automatikusan JSON-ba szerializál. A Content-Type alapértelmezés szerint application/json-ra van állítva.

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

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

Elfogók (Interceptors)

Az elfogók olyan middleware függvények, amelyek minden kéréshez vagy válaszhoz végrehajtódnak. Lehetővé teszik hitelesítési tokenek hozzáadását, kérések naplózását, központi hibakezelést. A kérés elfogó hozzáadja az Authorization fejlécet a tárolóból vett tokennel.

// Kérés elfogó — hitelesítési tokent ad hozzá
api.interceptors.request.use(
  (config) => {
    const token = getToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Válasz elfogó — kezeli a 401-es hibákat
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

Hibakezelés az Axios-ban

A hibakezelés az Axios-ban a kivételmechanizmusra épül. A fetch-tel ellentétben az Axios automatikusan elkapja a HTTP-hibákat (4xx, 5xx), és továbbítja a catch blokkba. A hibaobjektum információkat tartalmaz a szerver válaszáról, a kérésről és a végrehajtási kontextusról.

Fontos megkülönböztetni háromféle hibát: szerver válaszhiba (response), kéréshiba (request) és konfigurációs hiba (config). Az első sikeres HTTP-hívás esetén keletkezik hibakóddal, a második — amikor nincs válasz a szervertől, a harmadik — a kérés hibás konfigurációja esetén.

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('Válasz hiba', error.response.status);
      } else if (error.request) {
        console.warn('Nincs válasz a szervertől');
      } else {
        console.warn('Konfigurációs hiba');
      }
    }
  }
}

Az Axios összehasonlítása a Fetch API-val

Az Axios összehasonlítása a natív Fetch API-val segít megérteni, mikor melyik technológia megfelelő. A Fetch egy beépített böngésző API, amely nem igényel telepítést. Az Axios egy harmadik féltől származó könyvtár további képességekkel. Egyszerű kérésekhez a fetch elegendő, összetett alkalmazásokhoz elfogókkal és központi hibakezeléssel az Axios kényelmesebb.

A Fetch nem tekinti a HTTP-hibákat (4xx, 5xx) kivételeknek — ellenőrizni kell a response.ok-t. A Fetch két .then() hívást igényel a JSON lekéréséhez: a response.json() ezután Promise-t ad vissza az adatokkal. Az Axios ezt automatikusan teszi. A Fetch nem támogatja a fájlfeltöltés előrehaladását további polyfill nélkül. Az Axios beépített onUploadProgress és onDownloadProgress funkciókkal rendelkezik.

A Node.js-ben a Fetch a 18-as verziótól érhető el kísérleti funkcióként, míg az Axios a Node.js 10-től kezdve stabilan működik. A régebbi Node.js verziókat támogató projektek esetében a választás egyértelműen az Axios javára szól. A modern böngésző projektekhez összetett kérésfeldolgozás nélkül a fetch is elegendő lehet.