ربط فلاتر بالخادم باستخدام Dio: النماذج والأخطاء والبنية النظيفة

كل تطبيق حقيقي يتواصل مع واجهة API. يوضح هذا الدليل كيف ترسل الطلبات باستخدام Dio، وتحوّل الاستجابات إلى نماذج Dart، وتعالج الأخطاء بشكل صحيح، وتُبقي شيفرة الشبكة في طبقة نظيفة.

3 دقيقة قراءة55 مشاهدة
ربط فلاتر بالخادم باستخدام Dio: النماذج والأخطاء والبنية النظيفة

يتواصل كل تطبيق حقيقي تقريبًا مع خادم. يمكن لفلاتر استخدام حزمة http، لكن Dio يضيف المعترضات (interceptors) وإلغاء الطلبات وتقدّم الرفع، وهو أكثر انتشارًا في المشاريع الجادة.

#الإعداد

أنشئ نسخة Dio مشتركة واحدة وأعطها الإعدادات الأساسية مرة واحدة:

final dio = Dio(BaseOptions(
  baseUrl: 'https://api.example.com/api/v1',
  connectTimeout: const Duration(seconds: 10),
  receiveTimeout: const Duration(seconds: 20),
  headers: {'Accept': 'application/json'},
));

#النماذج

حوّل استجابة JSON إلى صنف Dart حتى تعمل بقية شيفرتك مع كائنات محدّدة النوع، لا مع Map خام:

class Course {
  final String id;
  final String name;
  final int price;
  const Course({required this.id, required this.name, required this.price});

  factory Course.fromJson(Map<String, dynamic> json) => Course(
        id: json['id'] as String,
        name: json['name'] as String,
        price: json['price'] as int,
      );
}

#طبقة المستودع (Repository)

لا يجب أن تستدعي العناصر Dio مباشرة. أنشئ صنفًا وسيطًا:

class CourseRepository {
  CourseRepository(this._dio);
  final Dio _dio;

  Future<List<Course>> fetchCourses() async {
    final response = await _dio.get('/courses');
    return (response.data as List)
        .map((e) => Course.fromJson(e as Map<String, dynamic>))
        .toList();
  }
}

إذا تغيّر عنوان الواجهة أو صيغتها يومًا ما، يتغيّر هذا الصنف وحده.

#معالجة الأخطاء

أخطاء الشبكة أنواع: لا اتصال، أو انتهاء المهلة، أو استجابة خطأ من الخادم. حوّلها كلها إلى رسالة واحدة مفهومة:

String friendlyMessage(Object error) {
  if (error is DioException) {
    switch (error.type) {
      case DioExceptionType.connectionTimeout:
      case DioExceptionType.receiveTimeout:
        return 'The server did not respond. Please try again.';
      case DioExceptionType.connectionError:
        return 'Check your internet connection.';
      default:
        final data = error.response?.data;
        if (data is Map && data['message'] is String) return data['message'];
    }
  }
  return 'Something went wrong.';
}

#المعترضات للأعمال المتكررة

كل ما يجب أن يحدث مع كل طلب (مثل إضافة ترويسة المصادقة أو التسجيل) مكانه معترض:

dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) {
    final token = tokenStore.read();
    if (token != null) options.headers['Authorization'] = 'Bearer $token';
    handler.next(options);
  },
));

احفظ القيم الحساسة مثل الرموز (tokens) في flutter_secure_storage، لا في SharedPreferences.

#نصائح أخيرة

  • عند عرض البيانات عالج دائمًا ثلاث حالات: التحميل والنجاح والخطأ.
  • خطّط للتقسيم إلى صفحات (pagination) من البداية للقوائم الكبيرة.
  • عندما يغادر المستخدم شاشة، ألغِ الطلبات الجارية باستخدام CancelToken.

بهذه البنية، يمسّ تغيير الخادم أو إضافة نقطة نهاية جديدة ملفًا واحدًا فقط.

هل تحتاج إلى تطبيق أو موقع؟

يبني فريق فست فلاتر تطبيقات أندرويد وiOS والويب وسطح المكتب والمواقع بفلاتر: تقدير فوري بالدولار، ودفع على مراحل، والشيفرة المصدرية كاملة.