TypeScript Web API: Mencapai Keamanan Tipe Fetch untuk Aplikasi yang Kuat

Dalam pengembangan web modern, pengambilan data dari API adalah tugas mendasar. Meskipun Fetch API bawaan di JavaScript menyediakan cara yang nyaman untuk melakukan permintaan jaringan, ia kekurangan keamanan tipe bawaan. Hal ini dapat menyebabkan kesalahan saat runtime dan membuatnya sulit untuk memelihara aplikasi yang kompleks. TypeScript, dengan kemampuan pengetikan statisnya, menawarkan solusi ampuh untuk mengatasi masalah ini. Panduan komprehensif ini mengeksplorasi cara mengimplementasikan keamanan tipe dengan Fetch API di TypeScript, menciptakan aplikasi web yang lebih kuat dan mudah dipelihara.

Mengapa Keamanan Tipe Penting dengan Fetch API

Sebelum menyelami detail implementasi, mari pahami mengapa keamanan tipe sangat penting saat bekerja dengan Fetch API:

• Mengurangi Kesalahan Runtime: Pengetikan statis TypeScript membantu menangkap kesalahan selama pengembangan, mencegah masalah runtime yang tidak terduga yang disebabkan oleh tipe data yang salah.
• Peningkatan Pemeliharaan Kode: Anotasi tipe membuat kode lebih mudah dipahami dan dipelihara, terutama dalam proyek besar dengan banyak pengembang.
• Peningkatan Pengalaman Pengembang: IDE menyediakan pelengkapan otomatis, penyorotan kesalahan, dan kemampuan refactoring yang lebih baik ketika informasi tipe tersedia.
• Validasi Data: Keamanan tipe memungkinkan Anda memvalidasi struktur dan tipe data yang diterima dari API, memastikan integritas data.

Penggunaan Fetch API Dasar dengan TypeScript

Mari kita mulai dengan contoh dasar penggunaan Fetch API di TypeScript tanpa keamanan tipe:

            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); // Potensi kesalahan runtime jika 'name' tidak ada
  });

            

              
                Copy
              
            
          

Dalam contoh ini, fungsi `fetchData` mengambil data dari URL yang diberikan dan mengurai respons sebagai JSON. Namun, tipe variabel `data` secara implisit adalah `any`, yang berarti TypeScript tidak akan memberikan pemeriksaan tipe apa pun. Jika respons API tidak berisi properti `name`, kode akan menimbulkan kesalahan runtime.

Mengimplementasikan Keamanan Tipe dengan Antarmuka

Cara paling umum untuk menambahkan keamanan tipe ke panggilan Fetch API di TypeScript adalah dengan mendefinisikan antarmuka yang mewakili struktur data yang diharapkan.

Mendefinisikan Antarmuka

Misalkan kita mengambil daftar pengguna dari API yang mengembalikan data dalam format berikut:

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

            

              
                Copy
              
            
          

Kita dapat mendefinisikan antarmuka untuk mewakili struktur data ini:

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

            

              
                Copy
              
            
          

Menggunakan Antarmuka dengan Fetch API

Sekarang, kita dapat memperbarui fungsi `fetchData` untuk menggunakan antarmuka `User`:

            async function fetchData(url: string): Promise<User[]> {
  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); // Akses properti 'name' yang aman tipe
    });
  });

            

              
                Copy
              
            
          

Dalam contoh yang diperbarui ini, kita telah menambahkan anotasi tipe ke fungsi `fetchData`, menentukan bahwa fungsi tersebut mengembalikan `Promise` yang diselesaikan menjadi larik objek `User` (`Promise<User[]>`). Kita juga menggunakan penegasan tipe (`as User[]`) untuk memberi tahu TypeScript bahwa data yang dikembalikan oleh `response.json()` adalah larik objek `User`. Ini membantu TypeScript memahami struktur data dan memberikan pemeriksaan tipe.

Catatan Penting: Meskipun kata kunci `as` melakukan penegasan tipe, ia tidak melakukan validasi saat runtime. Ini memberi tahu kompiler apa yang diharapkan, tetapi tidak menjamin bahwa data tersebut benar-benar cocok dengan tipe yang ditegaskan. Di sinilah pustaka seperti `io-ts` atau `zod` berguna untuk validasi runtime, seperti yang akan kita bahas nanti.

Memanfaatkan Generik untuk Fungsi Fetch yang Dapat Digunakan Kembali

Untuk membuat fungsi fetch yang lebih dapat digunakan kembali, kita dapat menggunakan generik. Generik memungkinkan kita mendefinisikan fungsi yang dapat bekerja dengan tipe data yang berbeda tanpa harus menulis fungsi terpisah untuk setiap tipe.

Mendefinisikan Fungsi Fetch Generik

            async function fetchData<T>(url: string): Promise<T> {
  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
              
            
          

Dalam contoh ini, kita telah mendefinisikan fungsi `fetchData` generik yang menerima parameter tipe `T`. Fungsi tersebut mengembalikan `Promise` yang diselesaikan menjadi nilai bertipe `T`. Kita juga menambahkan penanganan kesalahan untuk memeriksa apakah respons berhasil.

Menggunakan Fungsi Fetch Generik

Sekarang, kita dapat menggunakan fungsi `fetchData` generik dengan antarmuka yang berbeda:

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

fetchData<Post>('https://jsonplaceholder.typicode.com/posts/1')
  .then(post => {
    console.log(post.title); // Akses properti 'title' yang aman tipe
  })
  .catch(error => {
      console.error("Error fetching post:", error);
  });

fetchData<User[]>('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.email);
    });
  })
  .catch(error => {
      console.error("Error fetching users:", error);
  });

            

              
                Copy
              
            
          

Dalam contoh ini, kita menggunakan fungsi `fetchData` generik untuk mengambil baik satu `Post` maupun larik objek `User`. TypeScript akan secara otomatis menyimpulkan tipe yang benar berdasarkan parameter tipe yang kita berikan.

Menangani Kesalahan dan Kode Status

Sangat penting untuk menangani kesalahan dan kode status saat bekerja dengan Fetch API. Kita dapat menambahkan penanganan kesalahan ke fungsi `fetchData` kita untuk memeriksa kesalahan HTTP dan menimbulkan kesalahan jika perlu.

            async function fetchData<T>(url: string): Promise<T> {
  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
              
            
          

Dalam contoh yang diperbarui ini, kita memeriksa properti `response.ok`, yang menunjukkan apakah kode status respons berada dalam rentang 200-299. Jika respons tidak OK, kita menimbulkan kesalahan dengan kode status.

Validasi Data Runtime dengan `io-ts` atau `zod`

Seperti yang disebutkan sebelumnya, penegasan tipe TypeScript (`as`) tidak melakukan validasi runtime. Untuk memastikan bahwa data yang diterima dari API benar-benar cocok dengan tipe yang diharapkan, kita dapat menggunakan pustaka seperti `io-ts` atau `zod`.

Menggunakan `io-ts`

`io-ts` adalah pustaka untuk mendefinisikan tipe runtime dan memvalidasi data terhadap tipe tersebut.

            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<typeof UserType>

async function fetchDataAndValidate(url: string): Promise<User[]> {
  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(`Validation errors: ${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('Error fetching and validating users:', error);
  });

            

              
                Copy
              
            
          

Dalam contoh ini, kita mendefinisikan `UserType` menggunakan `io-ts` yang sesuai dengan antarmuka `User` kita. Kita kemudian menggunakan metode `decode` untuk memvalidasi data yang diterima dari API. Jika validasi gagal, kita menimbulkan kesalahan dengan kesalahan validasi.

Menggunakan `zod`

`zod` adalah pustaka populer lainnya untuk deklarasi dan validasi skema.

            import { z } from 'zod';

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

type User = z.infer<typeof UserSchema>;

async function fetchDataAndValidate(url: string): Promise<User[]> {
  const response = await fetch(url);
  const data = await response.json();

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

  if (!parsedData.success) {
    throw new Error(`Validation errors: ${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('Error fetching and validating users:', error);
  });

            

              
                Copy
              
            
          

Dalam contoh ini, kita mendefinisikan `UserSchema` menggunakan `zod` yang sesuai dengan antarmuka `User` kita. Kita kemudian menggunakan metode `safeParse` untuk memvalidasi data yang diterima dari API. Jika validasi gagal, kita menimbulkan kesalahan dengan kesalahan validasi.

Baik `io-ts` maupun `zod` menyediakan cara ampuh untuk memastikan bahwa data yang diterima dari API cocok dengan tipe yang diharapkan saat runtime.

Integrasi dengan Framework Populer (React, Angular, Vue.js)

Panggilan Fetch API yang aman tipe dapat dengan mudah diintegrasikan dengan framework JavaScript populer seperti React, Angular, dan Vue.js.

Contoh React

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

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

function UserList() {
  const [users, setUsers] = useState<User[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(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 <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error}</p>;
  }

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

export default UserList;

            

              
                Copy
              
            
          

Dalam contoh React ini, kita menggunakan hook `useState` untuk mengelola status larik `users`. Kita juga menggunakan hook `useEffect` untuk mengambil pengguna dari API saat komponen dipasang. Kita telah menambahkan anotasi tipe ke status `users` dan variabel `data` untuk memastikan keamanan tipe.

Contoh Angular

            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: `
    <ul>
      <li *ngFor="let user of users">{{ user.name }}</li>
    </ul>
  `,
  styleUrls: []
})
export class UserListComponent implements OnInit {
  users: User[] = [];

  constructor(private http: HttpClient) { } 

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

            

              
                Copy
              
            
          

Dalam contoh Angular ini, kita menggunakan layanan `HttpClient` untuk melakukan panggilan API. Kita menentukan tipe respons sebagai `User[]` menggunakan generik, yang memastikan keamanan tipe.

Contoh Vue.js

            <template>
  <ul>
    <li v-for="user in users" :key="user.id">{{ user.name }}</li>
  </ul>
</template>

<script>
import { defineComponent, ref, onMounted } from 'vue'

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

export default defineComponent({
  setup() {
    const users = ref<User[]>([])

    onMounted(async () => {
      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()
        users.value = data
      } catch (error) {
        console.error('Error fetching users:', error)
      }
    })

    return {
      users
    }
  }
})
</script>

            

              
                Copy
              
            
          

Dalam contoh Vue.js ini, kita menggunakan fungsi `ref` untuk membuat larik `users` yang reaktif. Kita menggunakan hook siklus hidup `onMounted` untuk mengambil pengguna dari API saat komponen dipasang. Kita telah menambahkan anotasi tipe ke ref `users` dan variabel `data` untuk memastikan keamanan tipe.

Praktik Terbaik untuk Panggilan Fetch API yang Aman Tipe

Berikut adalah beberapa praktik terbaik yang perlu diikuti saat mengimplementasikan panggilan Fetch API yang aman tipe di TypeScript:

• Definisikan Antarmuka: Selalu definisikan antarmuka yang mewakili struktur data yang diharapkan.
• Gunakan Generik: Gunakan generik untuk membuat fungsi fetch yang dapat digunakan kembali yang dapat bekerja dengan tipe data yang berbeda.
• Tangani Kesalahan: Terapkan penanganan kesalahan untuk memeriksa kesalahan HTTP dan menimbulkan kesalahan jika perlu.
• Validasi Data: Gunakan pustaka seperti `io-ts` atau `zod` untuk memvalidasi data yang diterima dari API saat runtime.
• Ketik Status Anda: Saat berintegrasi dengan kerangka kerja seperti React, Angular, dan Vue.js, ketik variabel status dan respons API Anda.
• Pusatkan Konfigurasi API: Buat lokasi terpusat untuk URL dasar API Anda dan header atau parameter umum apa pun. Ini memudahkan pemeliharaan dan pembaruan konfigurasi API Anda. Pertimbangkan untuk menggunakan variabel lingkungan untuk lingkungan yang berbeda (pengembangan, staging, produksi).
• Gunakan Pustaka Klien API (Opsional): Pertimbangkan untuk menggunakan pustaka klien API seperti Axios atau klien yang dihasilkan dari spesifikasi OpenAPI/Swagger. Pustaka ini sering kali menyediakan fitur keamanan tipe bawaan dan dapat menyederhanakan interaksi API Anda.

Kesimpulan

Mengimplementasikan keamanan tipe dengan Fetch API di TypeScript sangat penting untuk membangun aplikasi web yang kuat dan mudah dipelihara. Dengan mendefinisikan antarmuka, menggunakan generik, menangani kesalahan, dan memvalidasi data saat runtime, Anda dapat secara signifikan mengurangi kesalahan runtime dan meningkatkan pengalaman pengembang secara keseluruhan. Panduan ini memberikan gambaran umum yang komprehensif tentang cara mencapai keamanan tipe dengan Fetch API, bersama dengan contoh praktis dan praktik terbaik. Dengan mengikuti panduan ini, Anda dapat membuat aplikasi web yang lebih andal dan terukur yang lebih mudah dipahami dan dipelihara.

Eksplorasi Lebih Lanjut

• Pembuatan Kode OpenAPI/Swagger: Jelajahi alat yang secara otomatis menghasilkan klien API TypeScript dari spesifikasi OpenAPI/Swagger. Ini dapat sangat menyederhanakan integrasi API dan memastikan keamanan tipe. Contohnya meliputi: `openapi-typescript` dan `swagger-codegen`.
• GraphQL dengan TypeScript: Pertimbangkan untuk menggunakan GraphQL dengan TypeScript. Skema yang diketik kuat GraphQL memberikan keamanan tipe yang sangat baik dan menghilangkan over-fetching data.
• Pengujian Keamanan Tipe: Tulis pengujian unit untuk memverifikasi bahwa panggilan API Anda mengembalikan data dengan tipe yang diharapkan. Ini membantu memastikan bahwa mekanisme keamanan tipe Anda berfungsi dengan benar.