Typsäkra API-anrop med TypeScript: En omfattande guide

I modern webbutveckling är interaktion med API:er en grundläggande uppgift. TypeScript, med sitt kraftfulla typsystem, erbjuder en betydande fördel när det gäller att säkerställa tillförlitligheten och underhållbarheten hos dina applikationer genom att möjliggöra typsäkra API-anrop. Den här guiden kommer att utforska hur du utnyttjar TypeScript:s funktioner för att bygga robusta och felfria API-interaktioner, och täcker bästa praxis, avancerade tekniker och verkliga exempel.

Varför typsäkerhet är viktigt för API-anrop

När du arbetar med API:er hanterar du i huvudsak data som kommer från en extern källa. Denna data kanske inte alltid är i det format du förväntar dig, vilket leder till runtime-fel och oväntat beteende. Typsäkerhet ger ett avgörande skyddslager genom att verifiera att den data du tar emot överensstämmer med en fördefinierad struktur, och fångar upp potentiella problem tidigt i utvecklingsprocessen.

• Minskade Runtime-fel: Typkontroll vid kompileringstid hjälper till att identifiera och åtgärda typrelaterade fel innan de når produktion.
• Förbättrad Kodunderhållbarhet: Tydliga typdefinitioner gör din kod lättare att förstå och modifiera, vilket minskar risken för att introducera buggar under refaktorisering.
• Förbättrad Kodläsbarhet: Typannotationer ger värdefull dokumentation, vilket gör det lättare för utvecklare att förstå de förväntade datastrukturerna.
• Bättre Utvecklarupplevelse: IDE-stöd för typkontroll och autokomplettering förbättrar utvecklarupplevelsen avsevärt och minskar sannolikheten för fel.

Konfigurera ditt TypeScript-projekt

Innan du dyker ner i API-anrop, se till att du har ett TypeScript-projekt konfigurerat. Om du börjar från början kan du initiera ett nytt projekt med:

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

Detta kommer att skapa en `tsconfig.json`-fil med standard TypeScript-kompilatoralternativ. Du kan anpassa dessa alternativ för att passa ditt projekts behov. Du kanske till exempel vill aktivera strikt läge för striktare typkontroll:

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

Definiera Typer för API-svar

Det första steget för att uppnå typsäkra API-anrop är att definiera TypeScript-typer som representerar strukturen på den data du förväntar dig att ta emot från API:et. Detta görs vanligtvis med `interface`- eller `type`-deklarationer.

Använda Gränssnitt

Gränssnitt är ett kraftfullt sätt att definiera formen på ett objekt. Om du till exempel hämtar en lista med användare från ett API kan du definiera ett gränssnitt som detta:

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

`?` efter ett egenskapsnamn indikerar att egenskapen är valfri. Detta är användbart för att hantera API-svar där vissa fält kan saknas.

Använda Typer

Typer liknar gränssnitt men erbjuder mer flexibilitet, inklusive möjligheten att definiera unionstyper och snittstyper. Du kan uppnå samma resultat som gränssnittet ovan med en typ:

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

För enkla objektstrukturer är gränssnitt och typer ofta utbytbara. Typer blir dock mer kraftfulla när man hanterar mer komplexa scenarier.

Göra API-anrop med Axios

Axios är en populär HTTP-klient för att göra API-förfrågningar i JavaScript och TypeScript. Det ger ett rent och intuitivt API, vilket gör det enkelt att hantera olika HTTP-metoder, begäranshuvuden och svarsdata.

Installera Axios

npm install axios

Göra ett Typsäkert API-anrop

För att göra ett typsäkert API-anrop med Axios kan du använda metoden `axios.get` och ange den förväntade svarstypen med hjälp av generiska typer:

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('Fel vid hämtning av användare:', error);
    throw error;
  }
}

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

I detta exempel säger `axios.get('...')` till TypeScript att svarsdatan förväntas vara en array av `User`-objekt. Detta tillåter TypeScript att tillhandahålla typkontroll och autokomplettering när du arbetar med svarsdatan.

Hantera Olika HTTP-metoder

Axios stöder olika HTTP-metoder, inklusive `GET`, `POST`, `PUT`, `DELETE` och `PATCH`. Du kan använda motsvarande metoder för att göra olika typer av API-förfrågningar. För att till exempel skapa en ny användare kan du använda metoden `axios.post`:

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('Fel vid skapande av användare:', 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('Skapad användare:', user);
});

I detta exempel skapar `Omit` en typ som är samma som `User` men utan egenskapen `id`. Detta är användbart eftersom `id` vanligtvis genereras av servern när en ny användare skapas.

Använda Fetch API

Fetch API är ett inbyggt JavaScript API för att göra HTTP-förfrågningar. Även om det är mer grundläggande än Axios kan det också användas med TypeScript för att uppnå typsäkra API-anrop. Du kanske föredrar det för att undvika att lägga till ett beroende om det passar dina behov.

Göra ett Typsäkert API-anrop med Fetch

För att göra ett typsäkert API-anrop med Fetch kan du använda funktionen `fetch` och sedan parsa svaret som JSON, och ange den förväntade svarstypen:

async function fetchUsers(): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data: User[] = await response.json();
    return data;
  } catch (error) {
    console.error('Fel vid hämtning av användare:', error);
    throw error;
  }
}

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

I detta exempel säger `const data: User[] = await response.json();` till TypeScript att svarsdatan ska behandlas som en array av `User`-objekt. Detta tillåter TypeScript att utföra typkontroll och autokomplettering.

Hantera Olika HTTP-metoder med Fetch

För att göra olika typer av API-förfrågningar med Fetch kan du använda funktionen `fetch` med olika alternativ, till exempel alternativen `method` och `body`. För att till exempel skapa en ny användare kan du använda följande 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 error! status: ${response.status}`);
    }
    const data: User = await response.json();
    return data;
  } catch (error) {
    console.error('Fel vid skapande av användare:', 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('Skapad användare:', user);
});

Hantera API-fel

Felhantering är en kritisk aspekt av API-anrop. API:er kan misslyckas av många anledningar, inklusive problem med nätverksanslutning, serverfel och ogiltiga förfrågningar. Det är viktigt att hantera dessa fel på ett smidigt sätt för att förhindra att din applikation kraschar eller visar oväntat beteende.

Använda Try-Catch-block

Det vanligaste sättet att hantera fel i asynkron kod är att använda try-catch-block. Detta gör att du kan fånga upp alla undantag som kastas under API-anropet och hantera dem på lämpligt sätt.

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('Fel vid hämtning av användare:', error);
    // Hantera felet, t.ex. visa ett felmeddelande för användaren
    throw error; // Kasta om felet för att tillåta anropande kod att hantera det också
  }
}

Hantera Specifika Felkoder

API:er returnerar ofta specifika felkoder för att indikera vilken typ av fel som har inträffat. Du kan använda dessa felkoder för att ge mer specifik felhantering. Du kanske till exempel vill visa ett annat felmeddelande för ett 404 Not Found-fel än för ett 500 Internal Server Error.

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(`Användare med ID ${id} hittades inte.`);
      return null; // Eller kasta ett anpassat fel
    } else {
      console.error('Fel vid hämtning av användare:', error);
      throw error;
    }
  }
}

fetchUser(123).then(user => {
  if (user) {
    console.log('Användare:', user);
  } else {
    console.log('Användare hittades inte.');
  }
});

Skapa Anpassade Feltyper

För mer komplexa felhanteringsscenarier kan du skapa anpassade feltyper för att representera olika typer av API-fel. Detta gör att du kan ge mer strukturerad felinformation och hantera fel mer effektivt.

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, `Användare med ID ${id} hittades inte.`);
    } else {
      console.error('Fel vid hämtning av användare:', error);
      throw new ApiError(500, 'Internt serverfel'); //Eller någon annan lämplig statuskod
    }
  }
}

fetchUser(123).catch(error => {
  if (error instanceof ApiError) {
    console.error(`API-fel: ${error.statusCode} - ${error.message}`);
  } else {
    console.error('Ett oväntat fel inträffade:', error);
  }
});

Datavalidering

Även med TypeScript:s typsystem är det avgörande att validera den data du tar emot från API:er vid runtime. API:er kan ändra sin svarsstruktur utan förvarning, och dina TypeScript-typer kanske inte alltid är perfekt synkroniserade med API:ets faktiska svar.

Använda Zod för Runtime-validering

Zod är ett populärt TypeScript-bibliotek för runtime-datavalidering. Det låter dig definiera scheman som beskriver den förväntade strukturen på din data och sedan validera datan mot dessa scheman vid runtime.

Installera Zod

npm install zod

Validera API-svar med Zod

För att validera API-svar med Zod kan du definiera ett Zod-schema som motsvarar din TypeScript-typ och sedan använda metoden `parse` för att validera datan.

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('Fel vid hämtning av användare:', error);
    throw error;
  }
}

I detta exempel validerar `z.array(userSchema).parse(response.data)` att svarsdatan är en array av objekt som överensstämmer med `userSchema`. Om datan inte överensstämmer med schemat kommer Zod att kasta ett fel, som du sedan kan hantera på lämpligt sätt.

Avancerade Tekniker

Använda Generiska Typer för Återanvändbara API-funktioner

Generiska typer låter dig skriva återanvändbara API-funktioner som kan hantera olika typer av data. Du kan till exempel skapa en generisk funktion `fetchData` som kan hämta data från vilken API-slutpunkt som helst och returnera den med rätt typ.

async function fetchData(url: string): Promise {
  try {
    const response = await axios.get(url);
    return response.data;
  } catch (error) {
    console.error(`Fel vid hämtning av data från ${url}:`, error);
    throw error;
  }
}

// Användning
fetchData('https://jsonplaceholder.typicode.com/users').then(users => {
  console.log('Användare:', users);
});

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

Använda Interceptorer för Global Felhantering

Axios tillhandahåller interceptorer som låter dig fånga upp förfrågningar och svar innan de hanteras av din kod. Du kan använda interceptorer för att implementera global felhantering, till exempel logga fel eller visa felmeddelanden för användaren.

axios.interceptors.response.use(
  (response) => response,
  (error) => {
    console.error('Global felhanterare:', error);
    // Visa ett felmeddelande för användaren
    return Promise.reject(error);
  }
);

Använda Miljövariabler för API-URL:er

För att undvika att hårdkoda API-URL:er i din kod kan du använda miljövariabler för att lagra URL:erna. Detta gör det lättare att konfigurera din applikation för olika miljöer, till exempel utveckling, staging och produktion.

Exempel med hjälp av filen `.env` och paketet `dotenv`.

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

// Installera dotenv
npm install dotenv

// Importera och konfigurera dotenv
import * as dotenv from 'dotenv'
dotenv.config()

const apiUrl = process.env.API_URL || 'http://localhost:3000'; // ange ett standardvärde

async function fetchData(endpoint: string): Promise {
  try {
    const response = await axios.get(`${apiUrl}/${endpoint}`);
    return response.data;
  } catch (error) {
    console.error(`Fel vid hämtning av data från ${apiUrl}/${endpoint}:`, error);
    throw error;
  }
}

Slutsats

Typsäkra API-anrop är avgörande för att bygga robusta, underhållbara och felfria webbapplikationer. TypeScript tillhandahåller kraftfulla funktioner som gör att du kan definiera typer för API-svar, validera data vid runtime och hantera fel på ett smidigt sätt. Genom att följa de bästa praxis och tekniker som beskrivs i den här guiden kan du avsevärt förbättra kvaliteten och tillförlitligheten hos dina API-interaktioner.

Genom att använda TypeScript och bibliotek som Axios och Zod kan du säkerställa att dina API-anrop är typsäkra, din data valideras och dina fel hanteras smidigt. Detta kommer att leda till mer robusta och underhållbara applikationer.

Kom ihåg att alltid validera din data vid runtime, även med TypeScript:s typsystem. API:er kan ändras, och dina typer kanske inte alltid är perfekt synkroniserade med API:ets faktiska svar. Genom att validera din data vid runtime kan du fånga upp potentiella problem innan de orsakar problem i din applikation.

Lycka till med kodningen!