Tipams saugūs API iškvietimai su TypeScript: Išsamus vadovas

Šiuolaikiniame žiniatinklio programavime sąveika su API yra fundamentalus uždavinys. TypeScript, su savo galinga tipų sistema, suteikia reikšmingą pranašumą užtikrinant jūsų programų patikimumą ir prižiūrimumą, įgalindama tipams saugius API iškvietimus. Šiame vadove bus nagrinėjama, kaip panaudoti TypeScript funkcijas kuriant tvirtas ir be klaidų veikiančias API sąveikas, apžvelgiant geriausias praktikas, pažangias technikas ir realaus pasaulio pavyzdžius.

Kodėl tipų saugumas svarbus API iškvietimams

Dirbant su API, iš esmės susiduriate su duomenimis, ateinančiais iš išorinio šaltinio. Šie duomenys ne visada gali būti tokio formato, kokio tikitės, o tai gali sukelti vykdymo laiko klaidas ir netikėtą elgesį. Tipų saugumas suteikia esminį apsaugos lygmenį, patikrindamas, ar gaunami duomenys atitinka iš anksto nustatytą struktūrą, ir taip padeda sugauti galimas problemas ankstyvoje kūrimo stadijoje.

• Sumažintos vykdymo laiko klaidos: Tipų tikrinimas kompiliavimo metu padeda identifikuoti ir ištaisyti su tipais susijusias klaidas, kol jos nepasiekė produkcijos.
• Pagerintas kodo prižiūrimumas: Aiškūs tipų apibrėžimai daro jūsų kodą lengviau suprantamą ir modifikuojamą, sumažindami klaidų riziką refaktorinimo metu.
• Pagerintas kodo skaitomumas: Tipų anotacijos suteikia vertingą dokumentaciją, todėl programuotojams lengviau suprasti tikėtinas duomenų struktūras.
• Geresnė programuotojo patirtis: IDE palaikymas tipų tikrinimui ir automatinis užbaigimas žymiai pagerina programuotojo patirtį ir sumažina klaidų tikimybę.

TypeScript projekto paruošimas

Prieš pradedant dirbti su API iškvietimais, įsitikinkite, kad turite paruoštą TypeScript projektą. Jei pradedate nuo nulio, galite inicijuoti naują projektą naudodami:

npm init -y
npm install typescript --save-dev
tsc --init

Tai sukurs `tsconfig.json` failą su numatytosiomis TypeScript kompiliatoriaus parinktimis. Galite pritaikyti šias parinktis pagal savo projekto poreikius. Pavyzdžiui, galite įjungti `strict` režimą griežtesniam tipų tikrinimui:

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

API atsakymų tipų apibrėžimas

Pirmasis žingsnis siekiant tipams saugių API iškvietimų yra apibrėžti TypeScript tipus, kurie atspindi duomenų, kuriuos tikitės gauti iš API, struktūrą. Paprastai tai daroma naudojant `interface` arba `type` deklaracijas.

Sąsajų (Interfaces) naudojimas

Sąsajos (interfaces) yra galingas būdas apibrėžti objekto formą. Pavyzdžiui, jei gaunate naudotojų sąrašą iš API, galite apibrėžti tokią sąsają:

interface User {
  id: number;
  name: string;
  email: string;
  address?: string; // Pasirinktinė savybė
  phone?: string; // Pasirinktinė savybė
  website?: string; // Pasirinktinė savybė
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
}

Klausimo ženklas `?` po savybės pavadinimo nurodo, kad savybė yra pasirinktinė. Tai naudinga tvarkant API atsakymus, kuriuose tam tikrų laukų gali trūkti.

Tipų (Types) naudojimas

Tipai (types) yra panašūs į sąsajas, bet suteikia daugiau lankstumo, įskaitant galimybę apibrėžti sąjungos (union) ir sankirtos (intersection) tipus. Tą patį rezultatą kaip ir su aukščiau pateikta sąsaja galite pasiekti naudodami tipą:

type User = {
  id: number;
  name: string;
  email: string;
  address?: string; // Pasirinktinė savybė
  phone?: string; // Pasirinktinė savybė
  website?: string; // Pasirinktinė savybė
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
};

Paprastoms objektų struktūroms sąsajos ir tipai dažnai yra tarpusavyje pakeičiami. Tačiau tipai tampa galingesni sprendžiant sudėtingesnius scenarijus.

API iškvietimų atlikimas su Axios

Axios yra populiarus HTTP klientas, skirtas API užklausoms JavaScript ir TypeScript kalbose. Jis suteikia švarų ir intuityvų API, leidžiantį lengvai tvarkyti skirtingus HTTP metodus, užklausų antraštes ir atsakymų duomenis.

Axios diegimas

npm install axios

Tipizuoto API iškvietimo atlikimas

Norėdami atlikti tipams saugų API iškvietimą su Axios, galite naudoti `axios.get` metodą ir nurodyti tikėtiną atsakymo tipą naudodami generinius tipus (generics):

import axios from 'axios';

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('Klaida gaunant naudotojus:', error);
    throw error;
  }
}

fetchUsers().then(users => {
  users.forEach(user => {
    console.log(user.name);
  });
});

Šiame pavyzdyje `axios.get('...')` nurodo TypeScript, kad tikimasi, jog atsakymo duomenys bus `User` objektų masyvas. Tai leidžia TypeScript teikti tipų tikrinimą ir automatinį užbaigimą dirbant su atsakymo duomenimis.

Skirtingų HTTP metodų apdorojimas

Axios palaiko įvairius HTTP metodus, įskaitant `GET`, `POST`, `PUT`, `DELETE` ir `PATCH`. Galite naudoti atitinkamus metodus, kad atliktumėte skirtingų tipų API užklausas. Pavyzdžiui, norėdami sukurti naują naudotoją, galite naudoti `axios.post` metodą:

async function createUser(user: Omit): Promise {
  try {
    const response = await axios.post('https://jsonplaceholder.typicode.com/users', user);
    return response.data;
  } catch (error) {
    console.error('Klaida kuriant naudotoją:', error);
    throw error;
  }
}

const newUser = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  address: '123 Main St',
  phone: '555-1234',
  website: 'example.com',
  company: {
    name: 'Example Corp',
    catchPhrase: 'Leading the way',
    bs: 'Innovative solutions'
  }
};

createUser(newUser).then(user => {
  console.log('Sukurtas naudotojas:', user);
});

Šiame pavyzdyje `Omit` sukuria tipą, kuris yra toks pat kaip `User`, bet be `id` savybės. Tai naudinga, nes `id` paprastai yra generuojamas serverio kuriant naują naudotoją.

Fetch API naudojimas

Fetch API yra integruotas JavaScript API, skirtas HTTP užklausoms atlikti. Nors jis yra paprastesnis nei Axios, jį taip pat galima naudoti su TypeScript, norint pasiekti tipams saugius API iškvietimus. Galite teikti jam pirmenybę, jei norite išvengti papildomos priklausomybės ir jis atitinka jūsų poreikius.

Tipizuoto API iškvietimo atlikimas su Fetch

Norėdami atlikti tipams saugų API iškvietimą su Fetch, galite naudoti `fetch` funkciją, o tada apdoroti atsakymą kaip JSON, nurodydami tikėtiną atsakymo tipą:

async function fetchUsers(): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
    if (!response.ok) {
      throw new Error(`HTTP klaida! būsena: ${response.status}`);
    }
    const data: User[] = await response.json();
    return data;
  } catch (error) {
    console.error('Klaida gaunant naudotojus:', error);
    throw error;
  }
}

fetchUsers().then(users => {
  users.forEach(user => {
    console.log(user.name);
  });
});

Šiame pavyzdyje `const data: User[] = await response.json();` nurodo TypeScript, kad atsakymo duomenys turėtų būti traktuojami kaip `User` objektų masyvas. Tai leidžia TypeScript atlikti tipų tikrinimą ir automatinį užbaigimą.

Skirtingų HTTP metodų apdorojimas su Fetch

Norėdami atlikti skirtingų tipų API užklausas su Fetch, galite naudoti `fetch` funkciją su skirtingomis parinktimis, tokiomis kaip `method` ir `body`. Pavyzdžiui, norėdami sukurti naują naudotoją, galite naudoti šį kodą:

async function createUser(user: Omit): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(user)
    });
    if (!response.ok) {
      throw new Error(`HTTP klaida! būsena: ${response.status}`);
    }
    const data: User = await response.json();
    return data;
  } catch (error) {
    console.error('Klaida kuriant naudotoją:', error);
    throw error;
  }
}

const newUser = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  address: '123 Main St',
  phone: '555-1234',
  website: 'example.com',
  company: {
    name: 'Example Corp',
    catchPhrase: 'Leading the way',
    bs: 'Innovative solutions'
  }
};

createUser(newUser).then(user => {
  console.log('Sukurtas naudotojas:', user);
});

API klaidų apdorojimas

Klaidų apdorojimas yra kritiškai svarbus API iškvietimų aspektas. API gali sugesti dėl daugelio priežasčių, įskaitant tinklo ryšio problemas, serverio klaidas ir neteisingas užklausas. Būtina šias klaidas apdoroti sklandžiai, kad jūsų programa nenustotų veikti ar nerodytų netikėto elgesio.

Try-Catch blokų naudojimas

Dažniausias būdas apdoroti klaidas asinchroniniame kode yra naudoti try-catch blokus. Tai leidžia jums pagauti bet kokias išimtis, kurios įvyksta API iškvietimo metu, ir jas tinkamai apdoroti.

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('Klaida gaunant naudotojus:', error);
    // Apdorokite klaidą, pvz., parodykite klaidos pranešimą naudotojui
    throw error; // Persiųskite klaidą toliau, kad ją galėtų apdoroti ir kviečiantis kodas
  }
}

Specifinių klaidų kodų apdorojimas

API dažnai grąžina specifinius klaidų kodus, nurodančius įvykusios klaidos tipą. Galite naudoti šiuos klaidų kodus, kad pateiktumėte konkretesnį klaidų apdorojimą. Pavyzdžiui, galbūt norėsite rodyti skirtingą klaidos pranešimą 404 Not Found klaidai nei 500 Internal Server Error klaidai.

async function fetchUser(id: number): Promise {
  try {
    const response = await axios.get(`https://jsonplaceholder.typicode.com/users/${id}`);
    return response.data;
  } catch (error: any) {
    if (error.response?.status === 404) {
      console.log(`Naudotojas su ID ${id} nerastas.`);
      return null; // Arba išmeskite pasirinktinę klaidą
    } else {
      console.error('Klaida gaunant naudotoją:', error);
      throw error;
    }
  }
}

fetchUser(123).then(user => {
  if (user) {
    console.log('Naudotojas:', user);
  } else {
    console.log('Naudotojas nerastas.');
  }
});

Pasirinktinių klaidų tipų kūrimas

Sudėtingesniems klaidų apdorojimo scenarijams galite sukurti pasirinktinius klaidų tipus, kurie atspindėtų skirtingus API klaidų tipus. Tai leidžia pateikti labiau struktūrizuotą informaciją apie klaidas ir efektyviau jas apdoroti.

class ApiError extends Error {
  constructor(public statusCode: number, message: string) {
    super(message);
    this.name = 'ApiError';
  }
}

async function fetchUser(id: number): Promise {
  try {
    const response = await axios.get(`https://jsonplaceholder.typicode.com/users/${id}`);
    return response.data;
  } catch (error: any) {
    if (error.response?.status === 404) {
      throw new ApiError(404, `Naudotojas su ID ${id} nerastas.`);
    } else {
      console.error('Klaida gaunant naudotoją:', error);
      throw new ApiError(500, 'Internal Server Error'); //Arba bet koks kitas tinkamas būsenos kodas
    }
  }
}

fetchUser(123).catch(error => {
  if (error instanceof ApiError) {
    console.error(`API klaida: ${error.statusCode} - ${error.message}`);
  } else {
    console.error('Įvyko netikėta klaida:', error);
  }
});

Duomenų validavimas

Net ir su TypeScript tipų sistema, labai svarbu validuoti duomenis, kuriuos gaunate iš API, vykdymo metu. API gali pakeisti savo atsakymo struktūrą be įspėjimo, o jūsų TypeScript tipai ne visada gali būti tobulai sinchronizuoti su tikruoju API atsakymu.

Zod naudojimas vykdymo laiko validavimui

Zod yra populiari TypeScript biblioteka, skirta duomenų validavimui vykdymo metu. Ji leidžia apibrėžti schemas, kurios aprašo tikėtiną jūsų duomenų struktūrą, ir tada validuoti duomenis pagal šias schemas vykdymo metu.

Zod diegimas

npm install zod

API atsakymų validavimas su Zod

Norėdami validuoti API atsakymus su Zod, galite apibrėžti Zod schemą, atitinkančią jūsų TypeScript tipą, ir tada naudoti `parse` metodą duomenims validuoti.

import { z } from 'zod';

const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  address: z.string().optional(),
  phone: z.string().optional(),
  website: z.string().optional(),
  company: z.object({
    name: z.string(),
    catchPhrase: z.string(),
    bs: z.string(),
  }).optional(),
});

type User = z.infer;

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    const data = z.array(userSchema).parse(response.data);
    return data;
  } catch (error) {
    console.error('Klaida gaunant naudotojus:', error);
    throw error;
  }
}

Šiame pavyzdyje `z.array(userSchema).parse(response.data)` patikrina, ar atsakymo duomenys yra objektų, atitinkančių `userSchema` schemą, masyvas. Jei duomenys neatitinka schemos, Zod išmes klaidą, kurią galėsite tinkamai apdoroti.

Pažangios technikos

Generinių tipų naudojimas pakartotinai naudojamoms API funkcijoms

Generiniai tipai (generics) leidžia rašyti pakartotinai naudojamas API funkcijas, kurios gali tvarkyti skirtingų tipų duomenis. Pavyzdžiui, galite sukurti bendrą `fetchData` funkciją, kuri gali gauti duomenis iš bet kurio API galinio taško ir grąžinti juos su teisingu tipu.

async function fetchData(url: string): Promise {
  try {
    const response = await axios.get(url);
    return response.data;
  } catch (error) {
    console.error(`Klaida gaunant duomenis iš ${url}:`, error);
    throw error;
  }
}

// Naudojimas
fetchData('https://jsonplaceholder.typicode.com/users').then(users => {
  console.log('Naudotojai:', users);
});

fetchData<{ title: string; body: string }>('https://jsonplaceholder.typicode.com/todos/1').then(todo => {
    console.log('Užduotis', todo)
});

Interceptors naudojimas globaliam klaidų apdorojimui

Axios suteikia interceptors (perėmėjus), kurie leidžia perimti užklausas ir atsakymus, prieš juos apdorojant jūsų kodui. Galite naudoti interceptors, kad įgyvendintumėte globalų klaidų apdorojimą, pavyzdžiui, klaidų registravimą ar klaidų pranešimų rodymą naudotojui.

axios.interceptors.response.use(
  (response) => response,
  (error) => {
    console.error('Globalus klaidų apdorojimo įrankis:', error);
    // Parodykite klaidos pranešimą naudotojui
    return Promise.reject(error);
  }
);

Aplinkos kintamųjų naudojimas API URL adresams

Norėdami išvengti tiesioginio API URL adresų kodavimo savo kode, galite naudoti aplinkos kintamuosius URL adresams saugoti. Tai palengvina jūsų programos konfigūravimą skirtingoms aplinkoms, tokioms kaip kūrimo, testavimo ir produkcijos.

Pavyzdys naudojant `.env` failą ir `dotenv` paketą.

// .env
API_URL=https://api.example.com

// Įdiekite dotenv
npm install dotenv

// Importuokite ir konfigūruokite dotenv
import * as dotenv from 'dotenv'
dotenv.config()

const apiUrl = process.env.API_URL || 'http://localhost:3000'; // pateikite numatytąją reikšmę

async function fetchData(endpoint: string): Promise {
  try {
    const response = await axios.get(`${apiUrl}/${endpoint}`);
    return response.data;
  } catch (error) {
    console.error(`Klaida gaunant duomenis iš ${apiUrl}/${endpoint}:`, error);
    throw error;
  }
}

Išvada

Tipams saugūs API iškvietimai yra būtini kuriant tvirtas, prižiūrimas ir be klaidų veikiančias žiniatinklio programas. TypeScript suteikia galingas funkcijas, leidžiančias apibrėžti API atsakymų tipus, validuoti duomenis vykdymo metu ir sklandžiai apdoroti klaidas. Laikydamiesi šiame vadove aprašytų geriausių praktikų ir technikų, galite žymiai pagerinti savo API sąveikų kokybę ir patikimumą.

Naudodami TypeScript ir bibliotekas, tokias kaip Axios ir Zod, galite užtikrinti, kad jūsų API iškvietimai būtų tipams saugūs, duomenys – validuoti, o klaidos – sklandžiai apdorotos. Tai leis kurti tvirtesnes ir lengviau prižiūrimas programas.

Nepamirškite visada validuoti savo duomenų vykdymo metu, net ir naudodami TypeScript tipų sistemą. API gali keistis, o jūsų tipai ne visada gali būti tobulai sinchronizuoti su tikruoju API atsakymu. Validuodami duomenis vykdymo metu, galite sugauti galimas problemas, kol jos nesukėlė problemų jūsų programoje.

Sėkmingo programavimo!