TypeScripti veebi-API: Päringute tüübikindluse saavutamine vastupidavates rakendustes

Kaasaegses veebiarenduses on andmete toomine API-dest põhiülesanne. Kuigi JavaScripti natiivne Fetch API pakub mugavat viisi võrgupäringute tegemiseks, puudub sellel omane tüübikindlus. See võib viia käitusaja vigadeni ja muuta keerukate rakenduste hooldamise keeruliseks. TypeScript oma staatilise tüüpimise võimalustega pakub võimsat lahendust selle probleemi lahendamiseks. See põhjalik juhend uurib, kuidas rakendada Fetch API-ga tüübikindlust TypeScriptis, luues vastupidavamaid ja hooldatavamaid veebirakendusi.

Miks on tüübikindlus Fetch API puhul oluline

Enne rakendusdetailidesse süvenemist mõistame, miks on tüübikindlus Fetch API-ga töötamisel kriitilise tähtsusega:

• Vähendatud käitusaja vead: TypeScripti staatiline tüüpimine aitab vigu arenduse ajal tabada, vältides ootamatuid käitusaja probleeme, mis on põhjustatud valedest andmetüüpidest.
• Parem koodi hooldatavus: Tüübi annotatsioonid muudavad koodi lihtsamini mõistetavaks ja hooldatavaks, eriti suurtes projektides, kus on mitu arendajat.
• Parem arendajakogemus: IDE-d pakuvad paremat automaatset täitmist, vigade esiletõstmist ja refaktoriseerimisvõimalusi, kui tüübiteave on saadaval.
• Andmete valideerimine: Tüübikindlus võimaldab valideerida API-dest saadud andmete struktuuri ja tüüpe, tagades andmete terviklikkuse.

Fetch API põhikäitlus TypeScriptiga

Alustame lihtsa näitega Fetch API kasutamisest TypeScriptis ilma tüübikindluseta:

            async function fetchData(url: string) {
  const response = await fetch(url);
  const data = await response.json();
  return data;
}

fetchData('https://api.example.com/users')
  .then(data => {
    console.log(data.name); // Võimalik käitusaja viga, kui 'name' puudub
  });

            

              
                Copy
              
            
          

Selles näites toob funktsioon `fetchData` andmeid antud URL-ilt ja parandab vastuse JSON-ina. Kuid muutuja `data` tüüp on implitsiitselt `any`, mis tähendab, et TypeScript ei paku mingit tüübikontrolli. Kui API vastus ei sisalda omadust `name`, viskab kood käitusaja vea.

Tüübi ohutuse rakendamine liidestega

Kõige levinum viis Fetch API päringutele tüübikindluse lisamiseks TypeScriptis on liideste defineerimine, mis esindavad oodatavate andmete struktuuri.

Liideste defineerimine

Oletame, et me toome kasutajate loendi API-st, mis tagastab andmed järgmises vormingus:

            [
  {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane.smith@example.com"
  }
]

            

              
                Copy
              
            
          

Saame defineerida liidese, et esindada seda andmestruktuuri:

            interface User {
  id: number;
  name: string;
  email: string;
}

            

              
                Copy
              
            
          

Liideste kasutamine Fetch API-ga

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  const data = await response.json();
  return data as User[];
}

fetchData('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name); // Tüübikindel juurdepääs omadusele 'name'
    });
  });

            

              
                Copy
              
            
          

Selles uuendatud näites oleme lisanud funktsioonile `fetchData` tüübi annotatsiooni, täpsustades, et see tagastab `Promise`'i, mis lahendub `User` objektide massiiviks (`Promise

Oluline märkus: Kuigi märksõna `as` teeb tüübikinnituse, ei tee see käitusaja valideerimist. See ütleb kompilaatorile, mida oodata, kuid see ei taga, et andmed tegelikult vastavad kinnitatud tüübile. Siin tulevad appi teegid nagu `io-ts` või `zod` käitusaja valideerimiseks, nagu me hiljem arutame.

Genericsi kasutamine korduvkasutatavate päringufunktsioonide jaoks

Korduvkasutatavamate päringufunktsioonide loomiseks saame kasutada genericit. Generics võimaldavad meil defineerida funktsiooni, mis saab töötada erinevate andmetüüpidega, ilma et peaks iga tüübi jaoks eraldi funktsioone kirjutama.

Üldise päringufunktsiooni defineerimine

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data: T = await response.json();
  return data;
}

            

              
                Copy
              
            
          

Selles näites oleme defineerinud üldise `fetchData` funktsiooni, mis võtab tüüpparameetri `T`. Funktsioon tagastab `Promise`'i, mis lahendub tüübi `T` väärtuseks. Lisasime ka veakäsitluse, et kontrollida, kas vastus oli edukas.

Üldise päringufunktsiooni kasutamine

            interface Post {
  id: number;
  title: string;
  body: string;
  userId: number;
}

fetchData('https://jsonplaceholder.typicode.com/posts/1')
  .then(post => {
    console.log(post.title); // Tüübikindel juurdepääs omadusele 'title'
  })
  .catch(error => {
      console.error("Viga postituse toomisel:", error);
  });

fetchData('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.email);
    });
  })
  .catch(error => {
      console.error("Viga kasutajate toomisel:", error);
  });

            

              
                Copy
              
            
          

Selles näites kasutame üldist `fetchData` funktsiooni nii ühe `Post` kui ka `User` objektide massiivi toomiseks. TypeScript tuletab automaatselt õige tüübi vastavalt meie antud tüüpparameetrile.

Vigade ja olekukoodide käsitlemine

Fetch API-ga töötades on vigade ja olekukoodide käsitlemine ülioluline. Saame lisada oma `fetchData` funktsioonile veakäsitluse, et kontrollida HTTP-vigu ja vajadusel viga visata.

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data: T = await response.json();
  return data;
}

            

              
                Copy
              
            
          

Selles uuendatud näites kontrollime `response.ok` omadust, mis näitab, kas vastuse olekukood on vahemikus 200-299. Kui vastus ei ole OK, viskame vea koos olekukoodiga.

Käitusaja andmete valideerimine `io-ts` või `zod` abil

Nagu varem mainitud, ei tee TypeScripti tüübikinnitused (`as`) käitusaja valideerimist. Et tagada, et API-st saadud andmed vastavad tegelikult oodatud tüübile, saame kasutada teeke nagu `io-ts` või `zod`.

`io-ts` kasutamine

`io-ts` on teek käitusaja tüüpide defineerimiseks ja andmete valideerimiseks nende tüüpide vastu.

            import * as t from 'io-ts'
import { PathReporter } from 'io-ts/PathReporter'

const UserType = t.type({
  id: t.number,
  name: t.string,
  email: t.string
})

type User = t.TypeOf

async function fetchDataAndValidate(url: string): Promise {
  const response = await fetch(url)
  const data = await response.json()

  const decodedData = t.array(UserType).decode(data)

  if (decodedData._tag === 'Left') {
    const errors = PathReporter.report(decodedData)
    throw new Error(`Valideerimisvead: ${errors.join('\n')}`)
  }

  return decodedData.right
}


fetchDataAndValidate('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name);
    });
  })
  .catch(error => {
    console.error('Viga kasutajate toomisel ja valideerimisel:', error);
  });

            

              
                Copy
              
            
          

Selles näites defineerime `UserType`'i kasutades `io-ts`'i, mis vastab meie `User` liidesele. Seejärel kasutame `decode` meetodit API-st saadud andmete valideerimiseks. Kui valideerimine ebaõnnestub, viskame vea koos valideerimisvigadega.

`zod` kasutamine

`zod` on teine populaarne teek skeemide deklareerimiseks ja valideerimiseks.

            import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer;

async function fetchDataAndValidate(url: string): Promise {
  const response = await fetch(url);
  const data = await response.json();

  const parsedData = z.array(UserSchema).safeParse(data);

  if (!parsedData.success) {
    throw new Error(`Valideerimisvead: ${parsedData.error.message}`);
  }

  return parsedData.data;
}


fetchDataAndValidate('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name);
    });
  })
  .catch(error => {
    console.error('Viga kasutajate toomisel ja valideerimisel:', error);
  });

            

              
                Copy
              
            
          

Selles näites defineerime `UserSchema` kasutades `zod`'i, mis vastab meie `User` liidesele. Seejärel kasutame `safeParse` meetodit API-st saadud andmete valideerimiseks. Kui valideerimine ebaõnnestub, viskame vea koos valideerimisvigadega.

Nii `io-ts` kui ka `zod` pakuvad võimsat viisi tagamaks, et API-dest saadud andmed vastavad käitusajal oodatud tüübile.

Integreerimine populaarsete raamistutega (React, Angular, Vue.js)

Tüübiturvalisi Fetch API päringuid saab hõlpsasti integreerida populaarsete JavaScripti raamistutega nagu React, Angular ja Vue.js.

Reacti näide

            import React, { useState, useEffect } from 'react';

interface User {
  id: number;
  name: string;
  email: string;
}

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchUsers() {
      try {
        const response = await fetch('https://api.example.com/users');
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data: User[] = await response.json();
        setUsers(data);
      } catch (error: any) {
        setError(error.message);
      } finally {
        setLoading(false);
      }
    }

    fetchUsers();
  }, []);

  if (loading) {
    return 
Laadimine...
;
  }

  if (error) {
    return 
Viga: {error}
;
  }

  return (
    

      {users.map(user => (
        
{user.name}
      ))}
    
  );
}

export default UserList;

            

              
                Copy
              
            
          

Selles Reacti näites kasutame `useState` hook'i `users` massiivi oleku haldamiseks. Kasutame ka `useEffect` hook'i kasutajate toomiseks API-st, kui komponent paigaldatakse. Oleme lisanud tüübi annotatsioonid `users` olekule ja `data` muutujale, et tagada tüübikindlus.

Angulari näide

            import { Component, OnInit } from '@angular/core';
import { HttpClient } from '@angular/common/http';

interface User {
  id: number;
  name: string;
  email: string;
}

@Component({
  selector: 'app-user-list',
  template: `
    

      
{{ user.name }}
    
  `,
  styleUrls: []
})
export class UserListComponent implements OnInit {
  users: User[] = [];

  constructor(private http: HttpClient) { }

  ngOnInit() {
    this.http.get('https://api.example.com/users')
      .subscribe(users => {
        this.users = users;
      });
  }
}

            

              
                Copy
              
            
          

Selles Angulari näites kasutame API-kõne tegemiseks `HttpClient` teenust. Määrame vastuse tüübi `User[]`-na, kasutades genericit, mis tagab tüübikindluse.

Vue.js näide

            



            

              
                Copy
              
            
          

Selles Vue.js näites kasutame `ref` funktsiooni reaktiivse `users` massiivi loomiseks. Kasutame `onMounted` elutsükli hook'i, et tuua API-st kasutajad, kui komponent paigaldatakse. Oleme lisanud tüübi annotatsioonid `users` ref'ile ja `data` muutujale, et tagada tüübikindlus.

Parimad tavad tüübikindlate Fetch API päringute jaoks

Siin on mõned parimad tavad, mida järgida tüübikindlate Fetch API päringute rakendamisel TypeScriptis:

• Defineerige liidesed: Defineerige alati liidesed, mis esindavad oodatavate andmete struktuuri.
• Kasutage genericit: Kasutage genericit korduvkasutatavate päringufunktsioonide loomiseks, mis saavad töötada erinevate andmetüüpidega.
• Käsitlege vigu: Rakendage veakäsitlust HTTP-vigade kontrollimiseks ja vajadusel vigade viskamiseks.
• Valideerige andmeid: Kasutage teeke nagu `io-ts` või `zod`, et valideerida API-dest saadud andmeid käitusajal.
• Tüübistage oma olek: Integreerimisel raamistutega nagu React, Angular ja Vue.js, tüübistage oma olekumuutujad ja API vastused.
• Tsentraliseerige API konfiguratsioon: Looge keskne koht oma API baas-URL-i ja kõikide ühiste päiste või parameetrite jaoks. See muudab API konfiguratsiooni hooldamise ja uuendamise lihtsamaks. Kaaluge keskkonnaparameetrite kasutamist erinevate keskkondade (arendus, testimine, tootmine) jaoks.
• Kasutage API klienditeeki (valikuline): Kaaluge API klienditeegi, näiteks Axios'i või OpenAPI/Swagger spetsifikatsioonist genereeritud kliendi kasutamist. Need teegid pakuvad sageli sisseehitatud tüübikindluse funktsioone ja võivad lihtsustada teie API interaktsioone.

Järeldus

Tüübikindluse rakendamine Fetch API-ga TypeScriptis on vastupidavate ja hooldatavate veebirakenduste loomisel hädavajalik. Liideste defineerimise, genericit kasutades, vigu käsitledes ja andmeid käitusajal valideerides saate oluliselt vähendada käitusaja vigu ja parandada üldist arendajakogemust. See juhend annab põhjaliku ülevaate sellest, kuidas saavutada tüübikindlus Fetch API-ga, koos praktiliste näidete ja parimate tavadega. Nende juhiste järgimisega saate luua usaldusväärsemaid ja skaleeritavamaid veebirakendusi, mida on lihtsam mõista ja hooldada.

Edasine uurimine

• OpenAPI/Swagger koodi genereerimine: Uurige tööriistu, mis genereerivad automaatselt TypeScripti API kliente OpenAPI/Swagger spetsifikatsioonidest. See võib oluliselt lihtsustada API integreerimist ja tagada tüübikindluse. Näited: `openapi-typescript` ja `swagger-codegen`.
• GraphQL koos TypeScriptiga: Kaaluge GraphQL-i kasutamist koos TypeScriptiga. GraphQL-i tugevalt tüübitud skeem pakub suurepärast tüübikindlust ja kõrvaldab andmete ülekäituse.
• Tüübikindluse testimine: Kirjutage ühiktestid, et kontrollida, kas teie API-kõned tagastavad oodatud tüüpi andmeid. See aitab tagada, et teie tüübikindluse mehhanismid töötavad õigesti.