Tüübikindlad API-kutsed TypeScriptiga: põhjalik juhend

Kaasaegses veebiarenduses on API-dega suhtlemine põhiülesanne. TypeScript pakub oma võimsa tüübisüsteemiga olulist eelist rakenduste usaldusväärsuse ja hooldatavuse tagamisel, võimaldades tüübikindlaid API-kutseid. Selles juhendis uurime, kuidas TypeScripti funktsioone kasutada robustsete ja vigadeta API-interaktsioonide loomiseks, hõlmates parimaid praktikaid, edasijõudnud tehnikaid ja reaalseid näiteid.

Miks on tüübikindlus API-kutsete puhul oluline

API-dega töötades tegelete sisuliselt välisest allikast pärinevate andmetega. Need andmed ei pruugi alati olla oodatud vormingus, mis põhjustab käitusaegseid vigu ja ootamatut käitumist. Tüübikindlus pakub olulist kaitsekihti, kontrollides, kas saadud andmed vastavad eelnevalt määratletud struktuurile, püüdes potentsiaalsed probleemid kinni juba arendusprotsessi varases staadiumis.

• Vähem käitusaegseid vigu: Tüübikontroll kompileerimise ajal aitab tuvastada ja parandada tüübiga seotud vigu enne nende jõudmist tootmiskeskkonda.
• Parem koodi hooldatavus: Selged tüübimääratlused muudavad teie koodi lihtsamini mõistetavaks ja muudetavaks, vähendades vigade tekkimise riski refaktoreerimise käigus.
• Parem koodi loetavus: Tüübiannotatsioonid pakuvad väärtuslikku dokumentatsiooni, muutes arendajatel oodatavate andmestruktuuride mõistmise lihtsamaks.
• Parem arendajakogemus: IDE tugi tüübikontrollile ja automaatsele täiendamisele parandab oluliselt arendajakogemust ja vähendab vigade tekkimise tõenäosust.

TypeScripti projekti seadistamine

Enne API-kutsetesse sukeldumist veenduge, et teil on TypeScripti projekt seadistatud. Kui alustate nullist, saate uue projekti lähtestada kasutades:

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

See loob `tsconfig.json` faili TypeScripti kompilaatori vaikesuvanditega. Saate neid suvandeid kohandada vastavalt oma projekti vajadustele. Näiteks võite soovida rangema tüübikontrolli jaoks lubada range režiimi:

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

API vastuste tüüpide defineerimine

Esimene samm tüübikindlate API-kutsete saavutamiseks on defineerida TypeScripti tüübid, mis esindavad andmete struktuuri, mida te API-lt ootate. Tavaliselt tehakse seda `interface` või `type` deklaratsioonide abil.

Liideste (Interfaces) kasutamine

Liidesed on võimas viis objekti kuju defineerimiseks. Näiteks kui hangite API-lt kasutajate nimekirja, võiksite defineerida sellise liidese:

interface User {
  id: number;
  name: string;
  email: string;
  address?: string; // Valikuline omadus
  phone?: string; // Valikuline omadus
  website?: string; // Valikuline omadus
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
}

`?` omaduse nime järel näitab, et omadus on valikuline. See on kasulik API vastuste käsitlemisel, kus teatud väljad võivad puududa.

Tüüpide (Types) kasutamine

Tüübid on sarnased liidestele, kuid pakuvad rohkem paindlikkust, sealhulgas võimalust defineerida unioon- ja risttüüpe. Sama tulemuse, mis ülaltoodud liidesega, saate saavutada tüübi abil:

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

Lihtsate objektistruktuuride puhul on liidesed ja tüübid sageli omavahel asendatavad. Tüübid muutuvad aga võimsamaks keerukamate stsenaariumide käsitlemisel.

API-kutsete tegemine Axiosiga

Axios on populaarne HTTP-klient API-päringute tegemiseks JavaScriptis ja TypeScriptis. See pakub puhast ja intuitiivset API-d, mis teeb erinevate HTTP-meetodite, päringupäiste ja vastuseandmete käsitlemise lihtsaks.

Axiose paigaldamine

npm install axios

Tüübikindla API-kutse tegemine

Tüübikindla API-kutse tegemiseks Axiosiga saate kasutada `axios.get` meetodit ja määrata oodatava vastuse tüübi geneeriliste tüüpide abil:

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('Viga kasutajate hankimisel:', error);
    throw error;
  }
}

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

Selles näites ütleb `axios.get('...')` TypeScriptile, et vastuse andmed on oodatavasti `User` objektide massiiv. See võimaldab TypeScriptil pakkuda tüübikontrolli ja automaatset täiendamist vastuse andmetega töötamisel.

Erinevate HTTP-meetodite käsitlemine

Axios toetab erinevaid HTTP-meetodeid, sealhulgas `GET`, `POST`, `PUT`, `DELETE` ja `PATCH`. Erinevat tüüpi API-päringute tegemiseks saate kasutada vastavaid meetodeid. Näiteks uue kasutaja loomiseks võite kasutada `axios.post` meetodit:

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('Viga kasutaja loomisel:', 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('Loodud kasutaja:', user);
});

Selles näites loob `Omit` tüübi, mis on sama mis `User`, kuid ilma `id` omaduseta. See on kasulik, kuna `id` genereerib tavaliselt server uue kasutaja loomisel.

Fetch API kasutamine

Fetch API on sisseehitatud JavaScripti API HTTP-päringute tegemiseks. Kuigi see on elementaarsem kui Axios, saab seda samuti kasutada koos TypeScriptiga, et saavutada tüübikindlaid API-kutseid. Võite seda eelistada, et vältida sõltuvuse lisamist, kui see sobib teie vajadustega.

Tüübikindla API-kutse tegemine Fetchiga

Tüübikindla API-kutse tegemiseks Fetchiga saate kasutada `fetch` funktsiooni ja seejärel parsida vastuse JSON-iks, määrates oodatava vastuse tüübi:

async function fetchUsers(): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
    if (!response.ok) {
      throw new Error(`HTTP viga! staatus: ${response.status}`);
    }
    const data: User[] = await response.json();
    return data;
  } catch (error) {
    console.error('Viga kasutajate hankimisel:', error);
    throw error;
  }
}

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

Selles näites ütleb `const data: User[] = await response.json();` TypeScriptile, et vastuse andmeid tuleks käsitleda kui `User` objektide massiivi. See võimaldab TypeScriptil teostada tüübikontrolli ja automaatset täiendamist.

Erinevate HTTP-meetodite käsitlemine Fetchiga

Erinevat tüüpi API-päringute tegemiseks Fetchiga saate kasutada `fetch` funktsiooni erinevate valikutega, nagu `method` ja `body` valikud. Näiteks uue kasutaja loomiseks võiksuite kasutada järgmist koodi:

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 viga! staatus: ${response.status}`);
    }
    const data: User = await response.json();
    return data;
  } catch (error) {
    console.error('Viga kasutaja loomisel:', 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('Loodud kasutaja:', user);
});

API vigade käsitlemine

Vigade käsitlemine on API-kutsete kriitiline aspekt. API-d võivad ebaõnnestuda mitmel põhjusel, sealhulgas võrguühenduse probleemid, serveri vead ja kehtetud päringud. On oluline neid vigu sujuvalt käsitleda, et vältida rakenduse krahhi või ootamatu käitumise kuvamist.

Try-Catch plokkide kasutamine

Kõige levinum viis vigade käsitlemiseks asünkroonses koodis on kasutada try-catch plokke. See võimaldab teil püüda kinni kõik erandid, mis API-kutse ajal visatakse, ja neid asjakohaselt käsitleda.

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('Viga kasutajate hankimisel:', error);
    // Käsitle viga, nt kuva kasutajale veateade
    throw error; // Viska viga uuesti, et ka kutsuv kood saaks seda käsitleda
  }
}

Spetsiifiliste veakoodide käsitlemine

API-d tagastavad sageli spetsiifilisi veakoode, et näidata toimunud vea tüüpi. Saate neid veakoode kasutada spetsiifilisema veakäsitluse pakkumiseks. Näiteks võiksite 404 Not Found vea puhul kuvada teistsuguse veateate kui 500 Internal Server Error vea puhul.

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(`Kasutajat ID-ga ${id} ei leitud.`);
      return null; // Või viska kohandatud viga
    } else {
      console.error('Viga kasutaja hankimisel:', error);
      throw error;
    }
  }
}

fetchUser(123).then(user => {
  if (user) {
    console.log('Kasutaja:', user);
  } else {
    console.log('Kasutajat ei leitud.');
  }
});

Kohandatud veatüüpide loomine

Keerukamate veakäsitlusstsenaariumide jaoks saate luua kohandatud veatüüpe, et esindada erinevaid API-vigade tüüpe. See võimaldab teil pakkuda struktureeritumat veateavet ja vigu tõhusamalt käsitleda.

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, `Kasutajat ID-ga ${id} ei leitud.`);
    } else {
      console.error('Viga kasutaja hankimisel:', error);
      throw new ApiError(500, 'Internal Server Error'); //Või mis tahes muu sobiv staatuskood
    }
  }
}

fetchUser(123).catch(error => {
  if (error instanceof ApiError) {
    console.error(`API viga: ${error.statusCode} - ${error.message}`);
  } else {
    console.error('Ilmnes ootamatu viga:', error);
  }
});

Andmete valideerimine

Isegi TypeScripti tüübisüsteemi olemasolul on ülioluline valideerida andmeid, mida te API-delt käitusajal saate. API-d võivad oma vastuse struktuuri etteteatamata muuta ja teie TypeScripti tüübid ei pruugi alati olla täiuslikus sünkroonis API tegeliku vastusega.

Zodi kasutamine käitusaegseks valideerimiseks

Zod on populaarne TypeScripti teek käitusaegseks andmete valideerimiseks. See võimaldab teil defineerida skeeme, mis kirjeldavad teie andmete oodatavat struktuuri, ja seejärel valideerida andmeid nende skeemide vastu käitusajal.

Zodi paigaldamine

npm install zod

API vastuste valideerimine Zodiga

API vastuste valideerimiseks Zodiga saate defineerida Zodi skeemi, mis vastab teie TypeScripti tüübile, ja seejärel kasutada `parse` meetodit andmete valideerimiseks.

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('Viga kasutajate hankimisel:', error);
    throw error;
  }
}

Selles näites valideerib `z.array(userSchema).parse(response.data)`, et vastuse andmed on objektide massiiv, mis vastab `userSchema`-le. Kui andmed ei vasta skeemile, viskab Zod vea, mida saate seejärel asjakohaselt käsitleda.

Edasijõudnud tehnikad

Geneeriliste tüüpide kasutamine korduvkasutatavate API-funktsioonide jaoks

Geneerilised tüübid võimaldavad teil kirjutada korduvkasutatavaid API-funktsioone, mis saavad hakkama erinevat tüüpi andmetega. Näiteks saate luua geneerilise `fetchData` funktsiooni, mis suudab hankida andmeid mis tahes API otspunktist ja tagastada need õige tüübiga.

async function fetchData(url: string): Promise {
  try {
    const response = await axios.get(url);
    return response.data;
  } catch (error) {
    console.error(`Viga andmete hankimisel asukohast ${url}:`, error);
    throw error;
  }
}

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

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

Interceptor'ite kasutamine globaalseks veahalduseks

Axios pakub interceptor'eid, mis võimaldavad teil päringuid ja vastuseid enne nende käsitlemist teie koodi poolt kinni püüda. Saate kasutada interceptor'eid globaalse veahalduse rakendamiseks, näiteks vigade logimiseks või kasutajale veateadete kuvamiseks.

axios.interceptors.response.use(
  (response) => response,
  (error) => {
    console.error('Globaalne veahaldur:', error);
    // Kuva kasutajale veateade
    return Promise.reject(error);
  }
);

Keskkonnamuutujate kasutamine API URL-ide jaoks

Et vältida API URL-ide kõvakodeerimist oma koodi, saate kasutada keskkonnamuutujaid URL-ide salvestamiseks. See muudab teie rakenduse konfigureerimise erinevate keskkondade jaoks, nagu arendus, testimine ja tootmine, lihtsamaks.

Näide, kasutades `.env` faili ja `dotenv` paketti.

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

// Paigalda dotenv
npm install dotenv

// Impordi ja konfigureeri dotenv
import * as dotenv from 'dotenv'
dotenv.config()

const apiUrl = process.env.API_URL || 'http://localhost:3000'; // paku vaikeväärtus

async function fetchData(endpoint: string): Promise {
  try {
    const response = await axios.get(`${apiUrl}/${endpoint}`);
    return response.data;
  } catch (error) {
    console.error(`Viga andmete hankimisel asukohast ${apiUrl}/${endpoint}:`, error);
    throw error;
  }
}

Kokkuvõte

Tüübikindlad API-kutsed on olulised robustsete, hooldatavate ja vigadeta veebirakenduste loomiseks. TypeScript pakub võimsaid funktsioone, mis võimaldavad teil defineerida API vastuste tüüpe, valideerida andmeid käitusajal ja käsitleda vigu sujuvalt. Järgides selles juhendis toodud parimaid praktikaid ja tehnikaid, saate oluliselt parandada oma API-interaktsioonide kvaliteeti ja usaldusväärsust.

Kasutades TypeScripti ja teeke nagu Axios ja Zod, saate tagada, et teie API-kutsed on tüübikindlad, teie andmed on valideeritud ja teie vead on sujuvalt käsitletud. See viib robustsemate ja hooldatavamate rakendusteni.

Pidage meeles, et peate oma andmeid alati käitusajal valideerima, isegi TypeScripti tüübisüsteemi olemasolul. API-d võivad muutuda ja teie tüübid ei pruugi alati olla täiuslikus sünkroonis API tegeliku vastusega. Andmete valideerimisega käitusajal saate potentsiaalsed probleemid kinni püüda enne, kui need teie rakenduses probleeme tekitavad.

Head kodeerimist!