تحويل JSON إلى Model في Flutter يحمي الواجهة من الاعتماد على خرائط غير مقيدة. Null Safety لا تتحقق تلقائيًا من البيانات القادمة من الشبكة؛ الحقل قد يكون غائبًا أو من نوع مختلف. لذلك نتحقق في factory قبل إنشاء النموذج بدل استخدام late ثم انتظار انهيار عند عرض الشاشة.
نموذج Article مع فحص الأنواع
في الملف التالي يشترط Article عنوانًا نصيًا غير فارغ، ويقبل غياب الصورة أو عنوانًا غير صالح لها باستخدام null. تحتفظ parseArticles بمسؤولية فحص الغلاف والقائمة. لا تحوّل كل قيمة ناقصة إلى صفر أو نص فارغ إذا كان ذلك يخفي خللًا في عقد الخادم.
import 'package:dio/dio.dart';
class Article {
const Article(this.title, this.imageUrl);
final String title;
final String? imageUrl;
factory Article.fromJson(Map<String, dynamic> json) {
final rawTitle = json['title'];
if (rawTitle is! String || rawTitle.trim().isEmpty) {
throw const FormatException('Missing article title');
}
final rawImage = json['urlToImage'];
final uri = rawImage is String ? Uri.tryParse(rawImage) : null;
return Article(rawTitle, uri != null && uri.scheme == 'https' && uri.host.isNotEmpty
? uri.toString() : null);
}
}
List<Article> parseArticles(Object? body) {
if (body is! Map<String, dynamic> || body['articles'] is! List) {
throw const FormatException('Invalid articles response');
}
return (body['articles'] as List).map((row) {
if (row is! Map<String, dynamic>) {
throw const FormatException('Invalid article row');
}
return Article.fromJson(row);
}).toList(growable: false);
}
class NewsRepository {
NewsRepository(this.dio);
final Dio dio;
// The backend owns provider credentials and returns {"articles": [...]}.
Future<List<Article>> search(String query, {CancelToken? cancelToken}) async {
final response = await dio.get<Object?>('/news',
queryParameters: {'q': query}, cancelToken: cancelToken);
return parseArticles(response.data);
}
}
Dio createApiClient(String baseUrl) => Dio(BaseOptions(
baseUrl: baseUrl,
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 15),
));
الغياب يختلف عن عدم التوافق
صورة غير موجودة حالة شائعة يمكن عرض بديل لها، لكن articles من نوع نص بدل قائمة قد يعني استجابة خطأ أو تغييرًا في الخدمة. اختر سياستك لكل حقل؛ ليس هناك سبب واحد لجعل كل الحقول nullable أو كل الحقول late. عند الحاجة إلى رقم قد يأتي نصيًا، حدد تحويلًا مقصودًا واختبره بدل cast أعمى.
ربط النموذج بتسجيل الدخول
إذا كنت تبني LoginModel، افصل بيانات العرض عن رمز الجلسة. لا تطبع data.token في Cubit أو listener. تحقق من نجاح العملية حسب عقد الخادم ومن وجود الرمز قبل الحفظ، ثم أرسله إلى خدمة التخزين الآمن. نجاح تحويل JSON وحده لا يمنح المستخدم صلاحية أو يثبت أن الجلسة صالحة.
اختبار التحويل قبل الواجهة
اختبر حقولًا صحيحة ومفقودة وnull ونوعًا خاطئًا ونصًا عربيًا ورابط صورة غير آمن. النموذج لا يحتاج شبكة لاختبار معظم هذه الحالات؛ مرر خرائط ثابتة إلى factory. بعد ذلك استخدم ListView بعدد العناصر الفعلي، واعرض خطأ تحويل واضحًا بدل مؤشر تحميل مستمر. التفاصيل الخاصة بإرسال الطلب توجد في درس Dio، حتى لا يكرر هذا المقال كود الاتصال.
مراجع التنفيذ
لإكمال هذا الجزء، انتقل إلى Repository Pattern في Flutter لتنظيم API باستخدام Dio، ثم طبّق الربط الذي يناسب بنية مشروعك.






