TypeScript Web API: تحقيق سلامة نوع البيانات (Type Safety) في Fetch API لتطبيقات قوية

في تطوير الويب الحديث، يعد جلب البيانات من واجهات برمجة التطبيقات (APIs) مهمة أساسية. في حين أن Fetch API الأصلية في JavaScript توفر طريقة مريحة لإجراء طلبات الشبكة، إلا أنها تفتقر إلى سلامة نوع البيانات المتأصلة. يمكن أن يؤدي هذا إلى أخطاء وقت التشغيل ويجعل من الصعب صيانة التطبيقات المعقدة. تقدم TypeScript، بقدراتها على الكتابة الثابتة، حلاً قويًا لمعالجة هذه المشكلة. يستكشف هذا الدليل الشامل كيفية تطبيق سلامة نوع البيانات مع Fetch API في TypeScript، مما يؤدي إلى إنشاء تطبيقات ويب أكثر قوة وقابلية للصيانة.

لماذا تهم سلامة نوع البيانات (Type Safety) مع Fetch API

قبل الغوص في تفاصيل التنفيذ، دعنا نفهم سبب أهمية سلامة نوع البيانات عند العمل مع Fetch API:

• تقليل أخطاء وقت التشغيل: تساعد الكتابة الثابتة في TypeScript على اكتشاف الأخطاء أثناء التطوير، مما يمنع مشكلات وقت التشغيل غير المتوقعة الناتجة عن أنواع البيانات غير الصحيحة.
• تحسين سهولة صيانة الكود: تجعل تعليقات نوع البيانات الكود أسهل في الفهم والصيانة، خاصة في المشاريع الكبيرة التي تضم العديد من المطورين.
• تجربة مطور محسنة: توفر IDEs إكمالًا تلقائيًا أفضل، وإبراز الأخطاء، وقدرات إعادة التنسيق عندما تتوفر معلومات النوع.
• التحقق من صحة البيانات: تمكنك سلامة نوع البيانات من التحقق من صحة بنية وأنواع البيانات المستلمة من واجهات برمجة التطبيقات، مما يضمن سلامة البيانات.

الاستخدام الأساسي لـ Fetch API مع TypeScript

لنبدأ بمثال أساسي على استخدام Fetch API في TypeScript بدون سلامة نوع البيانات:

            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); // Potential runtime error if 'name' doesn't exist
  });

            

              
                Copy
              
            
          

في هذا المثال، تقوم الدالة `fetchData` بجلب البيانات من عنوان URL المحدد وتحليل الاستجابة كـ JSON. ومع ذلك، فإن نوع المتغير `data` هو ضمنيًا `any`، مما يعني أن TypeScript لن يوفر أي فحص للنوع. إذا لم تحتوي استجابة API على الخاصية `name`، فسوف يطرح الكود خطأ وقت التشغيل.

تنفيذ سلامة نوع البيانات (Type Safety) باستخدام الواجهات

الطريقة الأكثر شيوعًا لإضافة سلامة نوع البيانات إلى استدعاءات Fetch API في TypeScript هي تحديد واجهات تمثل بنية البيانات المتوقعة.

تحديد الواجهات

لنفترض أننا نجلب قائمة بالمستخدمين من واجهة برمجة تطبيقات تُرجع البيانات بالتنسيق التالي:

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

            

              
                Copy
              
            
          

يمكننا تحديد واجهة لتمثيل هيكل البيانات هذا:

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

            

              
                Copy
              
            
          

استخدام الواجهات مع Fetch API

الآن، يمكننا تحديث الدالة `fetchData` لاستخدام الواجهة `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); // Type-safe access to 'name' property
    });
  });

            

              
                Copy
              
            
          

في هذا المثال المحدث، أضفنا تعليقًا على النوع إلى الدالة `fetchData`، مع تحديد أنها تُرجع `Promise` يتم تقييمها إلى مصفوفة من كائنات `User` (`Promise<User[]>`). نستخدم أيضًا تأكيد النوع (`as User[]`) لإخبار TypeScript بأن البيانات التي تم إرجاعها بواسطة `response.json()` هي مصفوفة من كائنات `User`. يساعد هذا TypeScript على فهم هيكل البيانات وتوفير فحص النوع.

ملاحظة مهمة: بينما تقوم الكلمة الأساسية `as` بتنفيذ تأكيد النوع، إلا أنها لا تنفذ التحقق من صحة وقت التشغيل. إنها تخبر المحول البرمجي بما هو متوقع، لكنها لا تضمن أن البيانات تتطابق بالفعل مع النوع المؤكد. هنا تأتي مكتبات مثل `io-ts` أو `zod` مفيدة للتحقق من صحة وقت التشغيل، كما سنناقش لاحقًا.

الاستفادة من Generics لوظائف Fetch قابلة لإعادة الاستخدام

لإنشاء المزيد من وظائف الجلب القابلة لإعادة الاستخدام، يمكننا استخدام generics. تسمح لنا Generics بتعريف دالة يمكنها العمل مع أنواع بيانات مختلفة دون الحاجة إلى كتابة دوال منفصلة لكل نوع.

تحديد دالة Fetch عامة

            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
              
            
          

في هذا المثال، حددنا دالة `fetchData` عامة تأخذ معلمة نوع `T`. ترجع الدالة `Promise` التي يتم تقييمها إلى قيمة من النوع `T`. أضفنا أيضًا معالجة الأخطاء للتحقق مما إذا كانت الاستجابة ناجحة.

استخدام الدالة Fetch العامة

الآن، يمكننا استخدام دالة `fetchData` العامة مع واجهات مختلفة:

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

fetchData<Post>('https://jsonplaceholder.typicode.com/posts/1')
  .then(post => {
    console.log(post.title); // Type-safe access to 'title' property
  })
  .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
              
            
          

في هذا المثال، نستخدم الدالة `fetchData` العامة لجلب كل من `Post` واحد ومصفوفة من كائنات `User`. سيستنتج TypeScript تلقائيًا النوع الصحيح بناءً على معلمة النوع التي نقدمها.

التعامل مع الأخطاء ورموز الحالة

من الضروري التعامل مع الأخطاء ورموز الحالة عند العمل مع Fetch API. يمكننا إضافة معالجة الأخطاء إلى الدالة `fetchData` الخاصة بنا للتحقق من وجود أخطاء HTTP وطرح خطأ إذا لزم الأمر.

            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
              
            
          

في هذا المثال المحدث، نتحقق من الخاصية `response.ok`، والتي تشير إلى ما إذا كان رمز حالة الاستجابة في النطاق من 200 إلى 299. إذا لم تكن الاستجابة على ما يرام، فإننا نطرح خطأ مع رمز الحالة.

التحقق من صحة البيانات وقت التشغيل باستخدام `io-ts` أو `zod`

كما ذكرنا سابقًا، لا تنفذ تأكيدات نوع TypeScript (`as`) التحقق من صحة وقت التشغيل. للتأكد من أن البيانات المستلمة من API تتطابق بالفعل مع النوع المتوقع، يمكننا استخدام مكتبات مثل `io-ts` أو `zod`.

باستخدام `io-ts`

`io-ts` هي مكتبة لتعريف أنواع وقت التشغيل والتحقق من صحة البيانات مقابل هذه الأنواع.

            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
              
            
          

في هذا المثال، نحدد `UserType` باستخدام `io-ts` الذي يتوافق مع واجهة `User` الخاصة بنا. ثم نستخدم طريقة `decode` للتحقق من صحة البيانات المستلمة من API. إذا فشل التحقق من الصحة، فإننا نطرح خطأ مع أخطاء التحقق من الصحة.

باستخدام `zod`

`zod` هي مكتبة أخرى شائعة لإعلان المخطط والتحقق من الصحة.

            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
              
            
          

في هذا المثال، نحدد `UserSchema` باستخدام `zod` الذي يتوافق مع واجهة `User` الخاصة بنا. ثم نستخدم طريقة `safeParse` للتحقق من صحة البيانات المستلمة من API. إذا فشل التحقق من الصحة، فإننا نطرح خطأ مع أخطاء التحقق من الصحة.

يوفر كل من `io-ts` و `zod` طريقة فعالة لضمان تطابق البيانات المستلمة من واجهات برمجة التطبيقات (APIs) مع النوع المتوقع في وقت التشغيل.

التكامل مع الأطر الشائعة (React، Angular، Vue.js)

يمكن دمج استدعاءات Fetch API الآمنة من النوع بسهولة مع أطر JavaScript الشائعة مثل React و Angular و Vue.js.

مثال 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
              
            
          

في مثال React هذا، نستخدم الخطاف `useState` لإدارة حالة مصفوفة `users`. نستخدم أيضًا الخطاف `useEffect` لجلب المستخدمين من API عند تحميل المكون. أضفنا تعليقات نوع إلى حالة `users` والمتغير `data` لضمان سلامة النوع.

مثال 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
              
            
          

في مثال Angular هذا، نستخدم خدمة `HttpClient` لإجراء استدعاء API. نحدد نوع الاستجابة كـ `User[]` باستخدام generics، مما يضمن سلامة النوع.

مثال 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
              
            
          

في مثال Vue.js هذا، نستخدم الدالة `ref` لإنشاء مصفوفة `users` تفاعلية. نستخدم الخطاف lifecycle `onMounted` لجلب المستخدمين من API عند تحميل المكون. أضفنا تعليقات نوع إلى مرجع `users` والمتغير `data` لضمان سلامة النوع.

أفضل الممارسات لاستدعاءات Fetch API الآمنة من النوع

فيما يلي بعض أفضل الممارسات التي يجب اتباعها عند تنفيذ استدعاءات Fetch API الآمنة من النوع في TypeScript:

• تحديد الواجهات: قم دائمًا بتعريف الواجهات التي تمثل بنية البيانات المتوقعة.
• استخدام Generics: استخدم generics لإنشاء وظائف جلب قابلة لإعادة الاستخدام يمكنها العمل مع أنواع بيانات مختلفة.
• التعامل مع الأخطاء: قم بتنفيذ معالجة الأخطاء للتحقق من وجود أخطاء HTTP وطرح الأخطاء إذا لزم الأمر.
• التحقق من صحة البيانات: استخدم مكتبات مثل `io-ts` أو `zod` للتحقق من صحة البيانات المستلمة من واجهات برمجة التطبيقات (APIs) في وقت التشغيل.
• اكتب أنواع حالتك: عند التكامل مع أطر العمل مثل React و Angular و Vue.js، اكتب متغيرات حالتك واستجابات API.
• مركزية تكوين API: قم بإنشاء موقع مركزي لعنوان URL الأساسي لواجهة برمجة التطبيقات (API) وأي رؤوس أو معلمات شائعة. هذا يسهل صيانة وتحديث تكوين واجهة برمجة التطبيقات (API) الخاصة بك. ضع في اعتبارك استخدام متغيرات البيئة لبيئات مختلفة (التطوير، التدريج، الإنتاج).
• استخدم مكتبة عميل API (اختياري): ضع في اعتبارك استخدام مكتبة عميل API مثل Axios أو عميل تم إنشاؤه من مواصفات OpenAPI/Swagger. غالبًا ما توفر هذه المكتبات ميزات أمان نوع مضمنة ويمكنها تبسيط تفاعلات API الخاصة بك.

الخلاصة

يعد تطبيق سلامة نوع البيانات (Type Safety) مع Fetch API في TypeScript أمرًا ضروريًا لبناء تطبيقات ويب قوية وقابلة للصيانة. من خلال تعريف الواجهات، واستخدام generics، والتعامل مع الأخطاء، والتحقق من صحة البيانات في وقت التشغيل، يمكنك تقليل أخطاء وقت التشغيل بشكل كبير وتحسين تجربة المطور الإجمالية. يوفر هذا الدليل نظرة عامة شاملة حول كيفية تحقيق سلامة نوع البيانات مع Fetch API، إلى جانب الأمثلة العملية وأفضل الممارسات. باتباع هذه الإرشادات، يمكنك إنشاء تطبيقات ويب أكثر موثوقية وقابلية للتطوير ويسهل فهمها وصيانتها.

الاستكشاف الإضافي

• OpenAPI/Swagger Code Generation: استكشف الأدوات التي تنشئ تلقائيًا عملاء TypeScript API من مواصفات OpenAPI/Swagger. يمكن أن يؤدي هذا إلى تبسيط تكامل API وضمان سلامة النوع بشكل كبير. تشمل الأمثلة: `openapi-typescript` و `swagger-codegen`.
• GraphQL مع TypeScript: ضع في اعتبارك استخدام GraphQL مع TypeScript. يوفر مخطط GraphQL المكتوب بقوة سلامة نوع بيانات (Type Safety) ممتازة ويزيل الإفراط في جلب البيانات.
• اختبار سلامة النوع: اكتب اختبارات الوحدة للتحقق من أن استدعاءات API الخاصة بك تُرجع بيانات من النوع المتوقع. يساعد هذا على ضمان عمل آليات سلامة النوع بشكل صحيح.