حوّل JSON إلى class بلغة Dart!

أدخل JSON لتوليد كود class بلغة Dart بما في ذلك الكائنات المتداخلة! يدعم Flutter, fromJson, toJson.
JSON
النتيجة
 

حوّل JSON إلى class بلغة Dart!

حوّل JSON إلى أصناف Dart فيها factory باسم fromJson ودالة toJson. الكود Dart عادي دون أي حزم توليد كود، فلا توجد خطوة build_runner.

يناسب تطبيقات Flutter التي تمرّر استجابات Map<String, dynamic> الخام من http أو dio إلى الـ widgets وتريد أصناف نماذج حقيقية بدلًا منها، أو المشاريع الصغيرة التي تحتاج إلى تسلسل يعمل قبل اعتماد json_serializable.

طريقة الاستخدام

  1. الصق JSON المراد تحويله.
  2. أدخل اسم الصنف على المستوى الأعلى في اسم النوع (مثلًا Store).
  3. الصق الناتج في ملف تحت lib/models/؛ ولا حاجة لأي استيراد.
  4. أنشئ الكائنات بـ Store.fromJson(jsonDecode(response.body) as Map<String, dynamic>) وأرسلها بـ jsonEncode(store.toJson()).

مثال

المدخلات (JSON)
{
  "storeId": 77,
  "storeName": "Mapo Kimbap",
  "isOpen": true,
  "rating": 4.7,
  "menuItems": [
    { "name": "Tuna Kimbap", "price": 4500, "soldOut": false },
    { "name": "Ramyeon", "price": 5000, "soldOut": true, "spicy": 2 }
  ]
}
المخرجات (Dart)
class Store {
  final int storeId;
  final String storeName;
  final bool isOpen;
  final double rating;
  final List<MenuItem> menuItems;

  Store({
    required this.storeId,
    required this.storeName,
    required this.isOpen,
    required this.rating,
    required this.menuItems,
  });

  factory Store.fromJson(Map<String, dynamic> json) => Store(
        storeId: json['storeId'] as int,
        storeName: json['storeName'] as String,
        isOpen: json['isOpen'] as bool,
        rating: (json['rating'] as num).toDouble(),
        menuItems: (json['menuItems'] as List<dynamic>).map((e) => MenuItem.fromJson(e as Map<String, dynamic>)).toList(),
      );

  Map<String, dynamic> toJson() => {
        'storeId': storeId,
        'storeName': storeName,
        'isOpen': isOpen,
        'rating': rating,
        'menuItems': menuItems.map((e) => e.toJson()).toList(),
      };
}

class MenuItem {
  final String name;
  final int price;
  final bool soldOut;
  final int? spicy;

  MenuItem({
    required this.name,
    required this.price,
    required this.soldOut,
    this.spicy,
  });

  factory MenuItem.fromJson(Map<String, dynamic> json) => MenuItem(
        name: json['name'] as String,
        price: json['price'] as int,
        soldOut: json['soldOut'] as bool,
        spicy: json['spicy'] as int?,
      );

  Map<String, dynamic> toJson() => {
        'name': name,
        'price': price,
        'soldOut': soldOut,
        'spicy': spicy,
      };
}

عناصر المصفوفة menuItems تصبح صنف MenuItem، وتُحوَّل داخل fromJson بـ .map(...).toList(). يُقرأ rating بالشكل (json['rating'] as num).toDouble() فتبقى القيمة الصحيحة آمنة، وspicy، الموجود في بعض عناصر القائمة فقط، يكون int? دون required في الـ constructor.

الميزات المدعومة

  • كل الحقول final؛ والـ constructors تستخدم معاملات مسمّاة ({required this.x}).
  • factory X.fromJson(Map<String, dynamic> json) وMap<String, dynamic> toJson() مكتوبتان يدويًا دون الاعتماد على أي حزمة.
  • الكائنات المتداخلة ومصفوفات الكائنات تستدعي fromJson / toJson الخاصتين بالصنف الفرعي.
  • تُقرأ حقول double عبر (as num).toDouble()، فلا يرمي عدد صحيح في JSON مثل 4 خطأ تحويل نوع.
  • الحقول الغائبة في بعض العناصر أو التي تحوي null تصبح قابلة لـ null (int?) وتمرّر null كما هي في fromJson.
  • القيم مختلطة الأنواع تكون dynamic؛ والكلمات المحجوزة في Dart مثل class أو is تحصل على شرطة سفلية في آخرها.
  • المصفوفة على المستوى الأعلى تُنتج typedef Root = List<RootItem>;.

حالات الاستخدام

نماذج API لشاشات Flutter

تمرير Map عبر FutureBuilder أو حالة Riverpod/Bloc يُخفي الأخطاء الإملائية في المفاتيح حتى وقت التشغيل. مع الأصناف المولَّدة تحصل على الإكمال التلقائي وفحص الأنواع في store.menuItems.first.price.

التخزين المؤقت المحلي

خزّن jsonEncode(store.toJson()) في shared_preferences أو في ملف واستعده بـ fromJson عند بدء التشغيل لتحصل على cache في بضعة أسطر.

مسودة قبل json_serializable

ثبّت قائمة الحقول وأنواعها أولًا؛ ومع نمو المشروع أضف @JsonSerializable() إلى الحقول نفسها وانتقل إلى توليد الكود.

ملاحظات وقيود

  • تُستنتج الأنواع بمحلّل JSON الخاص بالمتصفح، الذي يقرأ 5000.0 كعدد صحيح 5000. أما jsonDecode في Dart فيُبقي 5000.0 من نوع double، فيرمي as int خطأً. غيّر حقول الأسعار أو الإحداثيات التي قد تحمل فاصلة عشرية إلى double.
  • يكتب toJson الحقول القابلة لـ null حتى لو كانت null ('spicy': null). إن كان خادمك يرفض المفاتيح ذات القيمة null، فاستبعدها شرطيًا.
  • تبقى سلاسل التاريخ String؛ حوّلها بنفسك بـ DateTime.parse(json['createdAt'] as String).
  • لا يُولَّد copyWith ولا ==/hashCode ولا toString. فكّر في freezed أو equatable إن احتجت إليها.
  • حقول dynamic تحمل القيم دون فحص؛ استبدلها ما إن تعرف النوع الحقيقي.

الأسئلة الشائعة

هل يمكنه توليد كود json_serializable أو freezed؟

الناتج fromJson/toJson بأسلوب الكتابة اليدوية دون حزم. خذ تعريفات الحقول، وأضف @JsonSerializable() وpart 'store.g.dart';، وشغّل dart run build_runner build للانتقال إلى توليد الكود.

يظهر لي الخطأ type 'int' is not a subtype of type 'double'.

يحدث ذلك حين يحوّل الكود النوع بـ as double وتكون قيمة JSON عددًا صحيحًا. حقول double المولَّدة تستخدم (as num).toDouble() لتجنّبه؛ طبّق النمط نفسه على أي حقل عدّلته يدويًا.

كيف أفك ترميز استجابة على شكل قائمة ([ {...}, {...} ])؟

المصفوفة على المستوى الأعلى تُنتج typedef وصنفًا للعنصر. استدعِ fromJson لكل عنصر: (jsonDecode(body) as List<dynamic>).map((e) => RootItem.fromJson(e as Map<String, dynamic>)).toList().

هل يعمل في المشاريع القديمة دون null safety؟

يستخدم الناتج صيغة sound null safety (int?، required) المتوفرة منذ Dart 2.12. المشاريع السابقة لـ null safety تحتاج إلى حذف ? وrequired لتُترجَم.