Tipdroši API izsaukumi ar TypeScript: Visaptverošs ceļvedis

Mūsdienu tīmekļa izstrādē mijiedarbība ar API ir pamatuzdevums. TypeScript ar savu jaudīgo tipu sistēmu piedāvā būtisku priekšrocību, nodrošinot jūsu lietojumprogrammu uzticamību un uzturamību, ļaujot veikt tipdrošus API izsaukumus. Šajā ceļvedī tiks apskatīts, kā izmantot TypeScript funkcijas, lai izveidotu stabilu un bezkļūdu API mijiedarbību, aptverot labākās prakses, progresīvas metodes un reālus piemērus.

Kāpēc tipu drošība ir svarīga API izsaukumiem

Strādājot ar API, jūs būtībā strādājat ar datiem, kas nāk no ārēja avota. Šie dati ne vienmēr var būt tādā formātā, kādu jūs sagaidāt, kas var novest pie izpildlaika kļūdām un neparedzētas uzvedības. Tipu drošība nodrošina kritisku aizsardzības slāni, pārbaudot, vai saņemtie dati atbilst iepriekš definētai struktūrai, tādējādi atklājot potenciālās problēmas jau agrīnā izstrādes posmā.

• Samazinātas izpildlaika kļūdas: Tipu pārbaude kompilēšanas laikā palīdz identificēt un labot ar tipiem saistītas kļūdas, pirms tās nonāk produkcijā.
• Uzlabota koda uzturamība: Skaidras tipu definīcijas padara jūsu kodu vieglāk saprotamu un modificējamu, samazinot risku ieviest kļūdas refaktorēšanas laikā.
• Uzlabota koda lasāmība: Tipu anotācijas nodrošina vērtīgu dokumentāciju, padarot izstrādātājiem vieglāk saprotamas sagaidāmās datu struktūras.
• Labāka izstrādātāja pieredze: IDE atbalsts tipu pārbaudei un automātiskajai pabeigšanai ievērojami uzlabo izstrādātāja pieredzi un samazina kļūdu iespējamību.

TypeScript projekta iestatīšana

Pirms iedziļināties API izsaukumos, pārliecinieties, ka jums ir iestatīts TypeScript projekts. Ja sākat no nulles, varat inicializēt jaunu projektu, izmantojot:

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

Tas izveidos `tsconfig.json` failu ar noklusējuma TypeScript kompilatora opcijām. Jūs varat pielāgot šīs opcijas atbilstoši sava projekta vajadzībām. Piemēram, jūs varētu vēlēties ieslēgt stingro režīmu (strict mode) stingrākai tipu pārbaudei:

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

API atbilžu tipu definēšana

Pirmais solis ceļā uz tipdrošiem API izsaukumiem ir definēt TypeScript tipus, kas attēlo datu struktūru, kuru jūs sagaidāt saņemt no API. To parasti veic, izmantojot `interface` vai `type` deklarācijas.

Saskarņu (Interfaces) izmantošana

Saskarnes ir spēcīgs veids, kā definēt objekta formu. Piemēram, ja jūs ielādējat lietotāju sarakstu no API, jūs varētu definēt šādu saskarni:

interface User {
  id: number;
  name: string;
  email: string;
  address?: string; // Neobligāta īpašība
  phone?: string; // Neobligāta īpašība
  website?: string; // Neobligāta īpašība
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
}

Jautājuma zīme `?` aiz īpašības nosaukuma norāda, ka īpašība ir neobligāta. Tas ir noderīgi, apstrādājot API atbildes, kurās daži lauki var trūkt.

Tipu (Types) izmantošana

Tipi ir līdzīgi saskarnēm, bet piedāvā lielāku elastību, ieskaitot iespēju definēt apvienojuma (union) un šķēluma (intersection) tipus. Jūs varat sasniegt tādu pašu rezultātu kā ar iepriekšējo saskarni, izmantojot tipu:

type User = {
  id: number;
  name: string;
  email: string;
  address?: string; // Neobligāta īpašība
  phone?: string; // Neobligāta īpašība
  website?: string; // Neobligāta īpašība
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
};

Vienkāršām objektu struktūrām saskarnes un tipi bieži ir savstarpēji aizvietojami. Tomēr tipi kļūst jaudīgāki, strādājot ar sarežģītākiem scenārijiem.

API izsaukumu veikšana ar Axios

Axios ir populārs HTTP klients API pieprasījumu veikšanai JavaScript un TypeScript. Tas nodrošina tīru un intuitīvu API, kas atvieglo dažādu HTTP metožu, pieprasījumu galveņu un atbildes datu apstrādi.

Axios instalēšana

npm install axios

Tipdroša API izsaukuma veikšana

Lai veiktu tipdrošu API izsaukumu ar Axios, varat izmantot `axios.get` metodi un norādīt sagaidāmo atbildes tipu, izmantojot ģenēriķus:

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('Kļūda, ielādējot lietotājus:', error);
    throw error;
  }
}

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

Šajā piemērā `axios.get('...')` norāda TypeScript, ka sagaidāms, ka atbildes dati būs `User` objektu masīvs. Tas ļauj TypeScript nodrošināt tipu pārbaudi un automātisko pabeigšanu, strādājot ar atbildes datiem.

Dažādu HTTP metožu apstrāde

Axios atbalsta dažādas HTTP metodes, ieskaitot `GET`, `POST`, `PUT`, `DELETE` un `PATCH`. Jūs varat izmantot atbilstošās metodes, lai veiktu dažāda veida API pieprasījumus. Piemēram, lai izveidotu jaunu lietotāju, jūs varētu izmantot `axios.post` metodi:

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('Kļūda, veidojot lietotāju:', 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('Izveidotais lietotājs:', user);
});

Šajā piemērā `Omit` izveido tipu, kas ir tāds pats kā `User`, bet bez `id` īpašības. Tas ir noderīgi, jo `id` parasti ģenerē serveris, veidojot jaunu lietotāju.

Fetch API izmantošana

Fetch API ir iebūvēta JavaScript API HTTP pieprasījumu veikšanai. Lai gan tā ir vienkāršāka nekā Axios, to var izmantot arī ar TypeScript, lai panāktu tipdrošus API izsaukumus. Jūs varētu dot priekšroku tai, lai izvairītos no papildu atkarības pievienošanas, ja tā atbilst jūsu vajadzībām.

Tipdroša API izsaukuma veikšana ar Fetch

Lai veiktu tipdrošu API izsaukumu ar Fetch, varat izmantot `fetch` funkciju un pēc tam parsēt atbildi kā JSON, norādot sagaidāmo atbildes tipu:

async function fetchUsers(): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
    if (!response.ok) {
      throw new Error(`HTTP kļūda! statuss: ${response.status}`);
    }
    const data: User[] = await response.json();
    return data;
  } catch (error) {
    console.error('Kļūda, ielādējot lietotājus:', error);
    throw error;
  }
}

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

Šajā piemērā `const data: User[] = await response.json();` norāda TypeScript, ka atbildes dati ir jāuzskata par `User` objektu masīvu. Tas ļauj TypeScript veikt tipu pārbaudi un automātisko pabeigšanu.

Dažādu HTTP metožu apstrāde ar Fetch

Lai veiktu dažāda veida API pieprasījumus ar Fetch, varat izmantot `fetch` funkciju ar dažādām opcijām, piemēram, `method` un `body`. Piemēram, lai izveidotu jaunu lietotāju, jūs varētu izmantot šādu kodu:

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 kļūda! statuss: ${response.status}`);
    }
    const data: User = await response.json();
    return data;
  } catch (error) {
    console.error('Kļūda, veidojot lietotāju:', 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('Izveidotais lietotājs:', user);
});

API kļūdu apstrāde

Kļūdu apstrāde ir kritisks API izsaukumu aspekts. API var neizdoties daudzu iemeslu dēļ, tostarp tīkla savienojamības problēmu, servera kļūdu un nederīgu pieprasījumu dēļ. Ir būtiski šīs kļūdas apstrādāt eleganti, lai novērstu lietojumprogrammas avāriju vai neparedzētu uzvedību.

Try-Catch bloku izmantošana

Visizplatītākais veids, kā apstrādāt kļūdas asinhronā kodā, ir izmantot try-catch blokus. Tas ļauj jums notvert jebkurus izņēmumus, kas tiek izmesti API izsaukuma laikā, un atbilstoši tos apstrādāt.

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('Kļūda, ielādējot lietotājus:', error);
    // Apstrādājiet kļūdu, piemēram, parādot kļūdas ziņojumu lietotājam
    throw error; // Pārmetiet kļūdu tālāk, lai to varētu apstrādāt arī izsaucošais kods
  }
}

Specifisku kļūdu kodu apstrāde

API bieži atgriež specifiskus kļūdu kodus, lai norādītu notikušās kļūdas veidu. Jūs varat izmantot šos kļūdu kodus, lai nodrošinātu specifiskāku kļūdu apstrādi. Piemēram, jūs varētu vēlēties parādīt atšķirīgu kļūdas ziņojumu 404 Not Found kļūdai nekā 500 Internal Server Error kļūdai.

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(`Lietotājs ar ID ${id} nav atrasts.`);
      return null; // Vai izmest pielāgotu kļūdu
    } else {
      console.error('Kļūda, ielādējot lietotāju:', error);
      throw error;
    }
  }
}

fetchUser(123).then(user => {
  if (user) {
    console.log('Lietotājs:', user);
  } else {
    console.log('Lietotājs nav atrasts.');
  }
});

Pielāgotu kļūdu tipu izveide

Sarežģītākiem kļūdu apstrādes scenārijiem varat izveidot pielāgotus kļūdu tipus, lai attēlotu dažāda veida API kļūdas. Tas ļauj nodrošināt strukturētāku kļūdu informāciju un efektīvāk apstrādāt kļūdas.

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, `Lietotājs ar ID ${id} nav atrasts.`);
    } else {
      console.error('Kļūda, ielādējot lietotāju:', error);
      throw new ApiError(500, 'Iekšēja servera kļūda'); // Vai jebkurš cits piemērots statusa kods
    }
  }
}

fetchUser(123).catch(error => {
  if (error instanceof ApiError) {
    console.error(`API kļūda: ${error.statusCode} - ${error.message}`);
  } else {
    console.error('Notika neparedzēta kļūda:', error);
  }
});

Datu validācija

Pat ar TypeScript tipu sistēmu ir ļoti svarīgi validēt datus, ko saņemat no API, izpildlaikā. API var mainīt savu atbildes struktūru bez brīdinājuma, un jūsu TypeScript tipi ne vienmēr var būt perfekti sinhronizēti ar API faktisko atbildi.

Zod izmantošana izpildlaika validācijai

Zod ir populāra TypeScript bibliotēka izpildlaika datu validācijai. Tā ļauj definēt shēmas, kas apraksta jūsu datu sagaidāmo struktūru, un pēc tam validēt datus pret šīm shēmām izpildlaikā.

Zod instalēšana

npm install zod

API atbilžu validēšana ar Zod

Lai validētu API atbildes ar Zod, varat definēt Zod shēmu, kas atbilst jūsu TypeScript tipam, un pēc tam izmantot `parse` metodi datu validēšanai.

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('Kļūda, ielādējot lietotājus:', error);
    throw error;
  }
}

Šajā piemērā `z.array(userSchema).parse(response.data)` validē, ka atbildes dati ir objektu masīvs, kas atbilst `userSchema`. Ja dati neatbilst shēmai, Zod izmetīs kļūdu, kuru jūs varat atbilstoši apstrādāt.

Progresīvas metodes

Ģenēriķu (Generics) izmantošana atkārtoti lietojamām API funkcijām

Ģenēriķi ļauj rakstīt atkārtoti lietojamas API funkcijas, kas var apstrādāt dažāda veida datus. Piemēram, varat izveidot ģenērisku `fetchData` funkciju, kas var ielādēt datus no jebkura API galapunkta un atgriezt tos ar pareizo tipu.

async function fetchData(url: string): Promise {
  try {
    const response = await axios.get(url);
    return response.data;
  } catch (error) {
    console.error(`Kļūda, ielādējot datus no ${url}:`, error);
    throw error;
  }
}

// Usage
fetchData('https://jsonplaceholder.typicode.com/users').then(users => {
  console.log('Lietotāji:', users);
});

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

Pārtvērēju (Interceptors) izmantošana globālai kļūdu apstrādei

Axios nodrošina pārtvērējus, kas ļauj pārtvert pieprasījumus un atbildes, pirms tos apstrādā jūsu kods. Jūs varat izmantot pārtvērējus, lai ieviestu globālu kļūdu apstrādi, piemēram, reģistrējot kļūdas vai parādot kļūdu ziņojumus lietotājam.

axios.interceptors.response.use(
  (response) => response,
  (error) => {
    console.error('Globālais kļūdu apstrādātājs:', error);
    // Parādīt kļūdas ziņojumu lietotājam
    return Promise.reject(error);
  }
);

Vides mainīgo izmantošana API URL adresēm

Lai izvairītos no API URL adrešu iekodēšanas kodā, varat izmantot vides mainīgos, lai glabātu URL adreses. Tas atvieglo jūsu lietojumprogrammas konfigurēšanu dažādām vidēm, piemēram, izstrādes (development), sagatavošanas (staging) un produkcijas (production).

Piemērs, izmantojot `.env` failu un `dotenv` pakotni.

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

// Instalēt dotenv
npm install dotenv

// Importēt un konfigurēt dotenv
import * as dotenv from 'dotenv'
dotenv.config()

const apiUrl = process.env.API_URL || 'http://localhost:3000'; // norādiet noklusējuma vērtību

async function fetchData(endpoint: string): Promise {
  try {
    const response = await axios.get(`${apiUrl}/${endpoint}`);
    return response.data;
  } catch (error) {
    console.error(`Kļūda, ielādējot datus no ${apiUrl}/${endpoint}:`, error);
    throw error;
  }
}

Noslēgums

Tipdroši API izsaukumi ir būtiski, lai veidotu stabilas, uzturamas un bezkļūdu tīmekļa lietojumprogrammas. TypeScript nodrošina jaudīgas funkcijas, kas ļauj definēt tipus API atbildēm, validēt datus izpildlaikā un eleganti apstrādāt kļūdas. Ievērojot šajā ceļvedī izklāstītās labākās prakses un metodes, jūs varat ievērojami uzlabot savu API mijiedarbību kvalitāti un uzticamību.

Izmantojot TypeScript un tādas bibliotēkas kā Axios un Zod, jūs varat nodrošināt, ka jūsu API izsaukumi ir tipdroši, dati tiek validēti un kļūdas tiek apstrādātas eleganti. Tas novedīs pie stabilākām un uzturamākām lietojumprogrammām.

Atcerieties vienmēr validēt datus izpildlaikā, pat ar TypeScript tipu sistēmu. API var mainīties, un jūsu tipi ne vienmēr var būt perfekti sinhronizēti ar API faktisko atbildi. Validējot datus izpildlaikā, jūs varat atklāt potenciālās problēmas, pirms tās rada problēmas jūsu lietojumprogrammā.

Veiksmīgu kodēšanu!