محتويات الدورة
Dart
الأساسيات: القيم والغياب والمجموعات والكائنات الصالحة
العقود: الأنماط والواجهات العامة والنتائج غير المتزامنة
التكامل: الأهداف والموارد والتحقق والأدلة

Dart / التكامل: الأهداف والموارد والتحقق والأدلة / الدرس 17

تحويل JSON المفكوك إلى نماذج محلية متحققة

افصل الفك وفحص البنية والتحقق الدلالي واختيار الحقول صراحة والرفض الآمن للبيانات غير الموثوقة.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى
في هذه الصفحة

أهداف الدرس

  • اشرح لماذا لا يثبت JSON الصحيح والوصول الديناميكي للخريطة طلبا موثوقا.
  • تحقق من كل حقل مطلوب واحفظ سياسة مقصودة للتطبيع والمجهول والقبول الجزئي.

يثبت الفك الصياغة لا عقد التطبيق

تحول jsonDecode النص إلى قيم Dart كالخرائط والقوائم والنصوص والأعداد والمنطقي وnull. قد تكون القيمة المفكوكة ذات شكل علوي خاطئ أو حقول غير مقبولة. عاملها مدخلا غير موثوق ولا تنشر الوصول الديناميكي في منطق المجال. افصل JSON المشوه من الخطأ البنيوي ورفض العمل إذا احتاج المستدعي أسبابا مختلفة. لا يثبت String وجود المعرف أو ملكيته، ولا يثبت int وقوع العدد ضمن النطاق المسموح.

ابن كائنا موثوقا بعد اكتمال الفحوص المطلوبة

يقبل المتحقق قيمة Object? عند الحد ويفحص الخريطة وأنواع الحقول صراحة. يحذف مسافات المعرف ويسمح بعدد من واحد إلى ألف كسياسة مختبر افتراضية لا حد خدمة عام. تختصر النتيجة الخالية المثال؛ وقد تحتاج API أسبابا منظمة للغياب والنوع والنطاق. يُوثق الصنف للفحوص المعروضة فقط، ولا يفوض المعرف أو يثبت الدوام. لا تعمم التحقق الضيق إلى ضمان أمان أو حجز كامل.

dart تحقق صريح من الشكل والنوع والنطاق
import 'dart:convert';
class BatchRequest {
  final String id;
  final int count;
  BatchRequest(this.id, this.count);
}
BatchRequest? validateRequest(Object? value) {
  if (value is! Map<String, dynamic>) return null;
  final id = value['id'];
  final count = value['count'];
  if (id is! String || count is! int) return null;
  final normalized = id.trim();
  if (normalized.isEmpty || count < 1 || count > 1000) return null;
  return BatchRequest(normalized, count);
}
void main() {
  final Object? value = jsonDecode('{"id":" B-2 ","count":3}');
  final request = validateRequest(value);
  print(request == null ? 'invalid' : '${request.id}:${request.count}');
  print(validateRequest(<String, Object?>{'id': 'B-3', 'count': '3'}) == null);
}
الناتج المتوقع
B-2:3
true

المخرج المتوقع B-2:3 ثم true. يُرفض العدد النصي ولا يحلل ضمنيا. يستخدم المصدر JSON ثابتا وكائنات محلية ولم يُنفذ.

أظهر قواعد التطبيع والحقول المجهولة

قد يناسب حذف المسافات رمزا يدخله إنسان، لا كل رمز موقع أو معرف بروتوكول. قرّر تجاهل الحقول الزائدة أو رفضها أو حفظها في مساحة امتداد محدودة. وقد تحتاج الأسماء المكررة معالجة قبل اختزال النص إلى خريطة مفكوكة عادية. وقد تختلف سياسة حقل null عن حقل غائب. تنتمي الاختيارات لعقد البيانات العام. لا تحذف عناصر خاطئة من قائمة ثم تعلن نجاحا كاملا، إلا إذا كان القبول الجزئي سلوك المنتج المعلن.

رمّز عقد مخرج صريحا بدلا من الكائن كله

اختر حقول التمثيل الخارجي بدلا من تسلسل كل خاصية داخلية مريحة. ينشئ المثال خريطة عامة صغيرة ويحذف ملاحظة داخلية. هذا اختيار حقول لا تفويض أو سياسة خصوصية كاملة. استخدم jsonEncode لهروب النصوص الصحيح بدلا من تركيب JSON بالوصل. تظل الدقة العددية والقيم المدعومة معتمدتين على النموذج والهدف؛ فلا تفترض عودة عدد صحيح هائل مطابقا عبر كل مستهلك JavaScript. يهم ثبات المعنى بقدر صحة الصياغة.

dart تمثيل JSON مختار عمدا
import 'dart:convert';
void main() {
  final internal = <String, Object?>{
    'id': 'B-1',
    'count': 2,
    'internalNote': 'lab-only',
  };
  final publicValue = <String, Object?>{
    'id': internal['id'],
    'count': internal['count'],
  };
  print(jsonEncode(publicValue));
}
الناتج المتوقع
{"id":"B-1","count":2}

المخرج المتوقع {"id":"B-1","count":2}. يُحذف internalNote عمدا. لا تصل الشيفرة لبيانات أو خدمة خارجية ولم يُنفذ اختبار ترميز.

حد المدخل قبل الاعتماد على مفكك مريح

لا يفرض المفكك تلقائيا حدود حجم المنتج أو التعشيق أو طول القائمة أو المعالجة. طبق الحدود المناسبة عند الاستقبال ولا تسجل الحمولة المرفوضة كاملة. التقط FormatException ذات الصلة للصياغة دون إخفاء عيب تطبيق آخر. افحص الأشكال العليا الخاطئة والغياب وnull والقوائم المختلطة وحدود العدد والتطبيع في مشروع معزول متوافق. يمكن فحص أمثلة JSON كبيانات هنا، لكن فك Dart وترقية الأنواع وسلوك أعداد الهدف لم تُنفذ، وتظل المخرجات متوقعة بالتحليل.

الأخطاء الشائعة وإصلاحها

يُقبل JSON صحيح رغم خطأ أنواع الحقول.

لماذا يحدث؟
اختلط فك الصياغة بالتحقق من البنية والمجال.
كيف تصلحه؟
تحقق صراحة من الشكل العلوي وأنواع الحقول المطلوبة والنطاقات.
كيف تتجنب تكراره؟
أبق المفكوك غير موثوق حتى بناء نموذج متحقق.

يظهر حقل داخلي في الحمولة العامة.

لماذا يحدث؟
سلسل المرمز الحالة المريحة بدلا من عقد مخرج مختار.
كيف تصلحه؟
ابن تمثيلا صريحا بالحقول العامة المعلنة فقط.
كيف تتجنب تكراره؟
راجع التسلسل مع التفويض والسجلات وتقليل البيانات.

يتحول عدد غير صالح إلى صفر ويُعرض نجاحا.

لماذا يحدث؟
أخفى بديل الفرق بين البيانات المشوهة والقيمة المسموحة.
كيف تصلحه؟
أعد فشل تحقق صريحا أو نتائج جزئية منظمة.
كيف تتجنب تكراره؟
اشترط سياسة معلنة قبل دمج الخطأ بقيم افتراضية.

اختبر فهمك

1. هل ينبغي معاملة count: "3" تلقائيا مثل count: 3؟

اعرض الحل المشروح

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

2. لماذا لا يفوض التحقق من id وcount عملية دفعة حقيقية؟

اعرض الحل المشروح

يثبت البنية وقواعد القيم المعروضة فقط. تظل هوية الطرف وملكية المورد والفعل المسموح والحالة وقيد التزامن فحوصا منفصلة عند المالك المرجعي. قد يكون الطلب السليم ممنوعا أو قديما. لا تجعل منشئ DTO محليا بديلا عرضيا لتفويض المورد.

أهم ما تعلمته

  • الفك والتحقق والتفويض والتنفيذ حدود مختلفة.
  • تحفظ سياسات الحقول والرفض الصريحة المعنى عبر واجهات JSON.

المراجع الرسمية