معالجة أخطاء API في Flutter تبدأ بالتفريق بين نجاح النقل وصحة البيانات ونجاح العملية المطلوبة. HTTP 200 قد يحتوي رسالة رفض من التطبيق، وانقطاع الشبكة يختلف عن 401 أو استجابة JSON غير متوافقة. المثال القديم ذو statusCode ثابت لا يجري اتصالًا حقيقيًا؛ هنا نستخدم نتيجة Dart واضحة تُحيط بطلب فعلي أو طلب وهمي قابل للاختبار.
نتيجة للنجاح والفشل دون اعتماد إضافي
تدعم Dart الحديثة sealed classes، لذلك يمكن التعبير عن النتيجة دون ربط الدرس بإصدار حزمة Either معين. يحتفظ ApiFailure برمز HTTP عند وجوده وعلامة للإلغاء، بينما يحمل ApiSuccess البيانات ذات النوع المتوقع. لا تُعِد Unit إذا كان المستدعي يحتاج نموذجًا فعليًا من الخادم.
import 'package:dio/dio.dart';
sealed class ApiResult<T> {}
final class ApiSuccess<T> extends ApiResult<T> {
ApiSuccess(this.value);
final T value;
}
final class ApiFailure<T> extends ApiResult<T> {
ApiFailure(this.message, {this.statusCode, this.cancelled = false});
final String message;
final int? statusCode;
final bool cancelled;
}
Future<ApiResult<T>> runApi<T>(Future<T> Function() request) async {
try {
return ApiSuccess(await request());
} on DioException catch (e) {
if (CancelToken.isCancel(e)) {
return ApiFailure('Request cancelled', cancelled: true);
}
return ApiFailure(e.response == null ? 'Connection failed' : 'Request rejected',
statusCode: e.response?.statusCode);
} on FormatException {
return ApiFailure('Invalid response format');
}
}
كيف تستخدم runApi؟
مرر دالة تعيد Future، مثل repository.search، ثم افحص النتيجة باستخدام switch أو is. في حالة النجاح اعرض البيانات، وفي حالة الفشل اعرض رسالة آمنة وخيار إعادة المحاولة. الإلغاء الناتج عن كتابة المستخدم كلمة بحث جديدة لا يحتاج عادةً رسالة خطأ مرئية؛ فهو جزء من سير العمل المقصود.
لا تخلط الأخطاء المتوقعة بأخطاء البرمجة
تلتقط الدالة DioException وFormatException فقط. لا تحول كل خطأ برمجي إلى «الإنترنت غير متصل»؛ فقد يكون السبب خطأ في تحويل الحقول أو الوصول لفهرس خارج القائمة. في المقابل لا تعرض stack trace أو جسم استجابة يحتوي بيانات حساسة للمستخدم. سجّل تفاصيل تشخيصية منقحة وفق حاجتك.
الإعادة والمصادقة
إعادة GET بعد انقطاع عابر تختلف عن إعادة POST لعملية دفع أو إنشاء طلب. لا تكرر الكتابة تلقائيًا دون دعم idempotency أو عقد واضح من الخادم. عند 401 تحقق من انتهاء الجلسة وفق سياسة المصادقة، ولا تعرض بيانات كاش لحساب آخر. عند 429 راعِ سياسة الخدمة وحدود المعدل بدل إطلاق محاولات متسارعة.
خطة اختبار واقعية
اختبر نجاح الطلب، وHTTP 500 و401، ومهلة زمنية، وإلغاء، وJSON ببنية غير صحيحة، ونتيجة صحيحة لكن فارغة. تأكد أن حالة loading تنتهي في كل مسار، وأن زر إعادة المحاولة لا يشغّل طلبات متداخلة. رسائل الاختبار في الكود إنجليزية للتوضيح ويمكن تعريبها في طبقة العرض دون تغيير بنية النتيجة.
مراجع التنفيذ
لإكمال هذا الجزء، انتقل إلى Repository Pattern في Flutter لتنظيم API باستخدام Dio، ثم طبّق الربط الذي يناسب بنية مشروعك.






