استخدام حِزم Flutter SDK التي تم إنشاؤها

تتيح لك حِزم تطوير البرامج (SDK) من جهة العميل Firebase SQL Connect إرسال طلبات البحث والتعديلات من جهة الخادم مباشرةً من تطبيق Firebase. ويمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة من جهة العميل بالتزامن مع تصميم المخططات وطلبات البحث والتعديلات التي تنشرها في خدمة SQL Connect. بعد ذلك، يمكنك دمج طرق من حزمة تطوير البرامج هذه في منطق برنامجك.

كما ذكرنا في موضع آخر، من المهم الإشارة إلى أنّ SQL Connect طلبات البحث وعمليات التعديل لا يتم إرسالها من خلال رمز العميل وتنفيذها على الخادم. في المقابل، عند نشر عمليات SQL Connect، يتم تخزينها على الخادم، مثل "وظائف السحابة الإلكترونية". وهذا يعني أنّه عليك نشر التغييرات المقابلة من جهة العميل لتجنُّب إيقاف المستخدمين الحاليين (على سبيل المثال، في إصدارات التطبيق القديمة).

لهذا السبب، يوفّر لك SQL Connect بيئة تطوير وأدوات تتيح لك إنشاء نماذج أولية للمخططات والطلبات وعمليات التعديل التي يتم نشرها على الخادم. تنشئ أيضًا حِزم SDK من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.

بعد تكرار التحديثات على الخدمة وتطبيقات العميل، يصبح كلا التحديثَين على جهة الخادم والعميل جاهزًا للنشر.

ما هي خطوات سير عمل تطوير العملاء؟

إذا اتّبعت الخطوات الواردة في البدء، فقد تعرّفت على سير عملية التطوير بشكل عام في SQL Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً حول إنشاء حِزم تطوير البرامج (SDK) في Flutter من المخطط الخاص بك والتعامل مع طلبات البحث وعمليات التغيير من جهة العميل.

باختصار، لاستخدام حِزم تطوير البرامج (SDK) التي تم إنشاؤها في Flutter في تطبيقات العميل، عليك اتّباع خطوات المتطلبات الأساسية التالية:

1. أضِف Firebase إلى تطبيق Flutter.
2. ثبِّت أداة سطر الأوامر (CLI) الخاصة بـ flutterfire dart pub global activate flutterfire_cli.
3. تشغيل flutterfire configure

بعد ذلك:

1. طوِّر مخطّط تطبيقك.

2. إعداد إنشاء حزمة تطوير البرامج (SDK):

   • باستخدام الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق في إضافة SQL Connect VS Code
   • من خلال تعديل connector.yaml

3. تهيئة رمز العميل واستيراد المكتبات

4. تنفيذ طلبات البحث وعمليات التعديل

5. إعداد SQL Connect واستخدامه وتكرار العملية.

إنشاء حزمة تطوير البرامج (SDK) في Flutter

استخدِم واجهة سطر الأوامر Firebase لإعداد حِزم تطوير البرامج (SDK) التي تم إنشاؤها SQL Connect في تطبيقاتك. يجب أن يرصد الأمر init جميع التطبيقات في المجلد الحالي وأن يثبّت حِزم SDK التي تم إنشاؤها تلقائيًا.

firebase init dataconnect:sdk

تعديل حِزم SDK أثناء إنشاء النماذج الأولية

إذا كانت لديك إضافة SQL Connect VS Code مثبَّتة، ستحرص دائمًا على أن تكون حِزم SDK التي تم إنشاؤها محدّثة.

إذا كنت لا تستخدم إضافة SQL Connect VS Code، يمكنك استخدام Firebase CLI لإبقاء حِزم SDK التي تم إنشاؤها محدّثة.

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK في مسارات الإنشاء

يمكنك استخدام Firebase CLI لإنشاء حِزم تطوير البرامج (SDK) الخاصة بـ SQL Connect في عمليات إنشاء CI/CD.

firebase dataconnect:sdk:generate

إعداد رمز العميل

تهيئة تطبيق SQL Connect

أولاً، عليك إعداد تطبيقك باستخدام تعليمات الإعداد العادية في Firebase.

بعد ذلك، ثبِّت المكوّن الإضافي SQL Connect:

flutter pub add firebase_data_connect

إعداد SQL Connect Flutter SDK

ابدأ مثيل SQL Connect باستخدام المعلومات التي استخدمتها لإعداد SQL Connect. يمكنك العثور على هذه المعلومات في صفحة قواعد البيانات ومساحة التخزين > SQL Connect في وحدة تحكّم Firebase.

استيراد المكتبات

هناك مجموعتان من عمليات الاستيراد مطلوبة لإعداد رمز العميل، وهما عمليات الاستيراد العامةSQL Connect وعمليات الاستيراد الخاصة بحزمة تطوير البرامج (SDK) التي تم إنشاؤها.

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

استخدام طلبات البحث من جهة العميل

سيتضمّن الرمز الذي تم إنشاؤه مراجع طلبات بحث محدّدة مسبقًا. كل ما عليك فعله هو استيرادها واستدعاء execute عليها.

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

استدعاء طُرق طلبات البحث في حزمة تطوير البرامج (SDK)

إليك مثال على استخدام دوال اختصارات الإجراءات هذه:

import 'generated/movies.dart';

function onBtnClick() {
  // This will call the generated Dart from the CLI and then make an HTTP request to the server.
  MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}

الحقول الاختيارية

قد تتضمّن بعض طلبات البحث حقولاً اختيارية. في هذه الحالات، تعرض حزمة تطوير البرامج (SDK) الخاصة بـ Flutter طريقة إنشاء، ويجب ضبطها بشكل منفصل.

على سبيل المثال، الحقل rating اختياري عند استدعاء createMovie، لذا عليك توفيره في دالة الإنشاء.

await MoviesConnector.instance.createMovie( title: 'Empire Strikes Back', releaseYear: 1980, genre: 'Sci-Fi').rating(5).execute();

الاشتراك في خدمة تلقّي إشعارات بالتغييرات

راجِع تلقّي إشعارات في الوقت الفعلي من SQL Connect.

التعامل مع التغييرات في حقول التعداد

يمكن أن يحتوي مخطط التطبيق على تعدادات، ويمكن الوصول إليها من خلال طلبات بحث GraphQL.

عندما يتغيّر تصميم التطبيق، يمكنك إضافة قيم جديدة متوافقة مع التعداد. على سبيل المثال، لنفترض أنّك قرّرت في وقت لاحق من دورة حياة تطبيقك إضافة القيمة FULLSCREEN إلى تعداد AspectRatio.

في سير عمل SQL Connect، يمكنك استخدام أدوات التطوير المحلية لتعديل الاستعلامات وحِزم SDK.

ومع ذلك، قبل طرح إصدار محدَّث من برامج العميل، قد تتعطّل برامج العميل القديمة التي تم نشرها.

مثال على عملية تنفيذ مرنة

تفرض حزمة SDK التي تم إنشاؤها معالجة القيم غير المعروفة. أي أنّ رمز العميل يجب أن يفكّ غلاف العنصر EnumValue إلى Known أو Unknown.

final result = await MoviesConnector.instance.listMovies().execute();

if (result.data != null && result.data!.isNotEmpty) {
  handleEnumValue(result.data![0].aspectratio);
}

void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
  if (aspectValue.value != null) {
    switch(aspectValue.value!) {
      case AspectRatio.ACADEMY:
        print('This movie is in Academy aspect');
        break;
      case AspectRatio.WIDESCREEN:
        print('This movie is in Widescreen aspect');
        break;
      case AspectRatio.ANAMORPHIC:
        print('This movie is in Anamorphic aspect');
        break;
      case AspectRatio.IMAX:
        print('This movie is in IMAX aspect');
    }
  } else {
    print('Unknown aspect ratio detected: ${aspectValue.stringValue}');
  }
}

تفعيل التخزين المؤقت من جهة العميل

يتضمّن SQL Connect ميزة اختيارية للتخزين المؤقت من جهة العميل، ويمكنك تفعيلها من خلال تعديل ملف connector.yaml. عند تفعيل هذه الميزة، ستخزّن حِزم تطوير البرامج (SDK) للعميل التي تم إنشاؤها ردود طلبات البحث مؤقتًا على الجهاز، ما قد يقلّل عدد طلبات قاعدة البيانات التي يرسلها تطبيقك ويتيح لأجزاء تطبيقك التي تعتمد على قاعدة البيانات العمل عند انقطاع الاتصال بالشبكة.

لتفعيل التخزين المؤقت من جهة العميل، أضِف إعدادات التخزين المؤقت من جهة العميل إلى إعدادات الموصل:

generate:
  javascriptSdk:
    outputDir: ../dart/
    package: "dataconnect_generated"
    clientCache:
      maxAge: 5s
      storage: memory

يتضمّن هذا الإعداد مَعلمتَين، وكلاهما اختياري:

• ‫maxAge: الحد الأقصى لعمر الرد المخزّن مؤقتًا قبل أن تجلب حزمة تطوير البرامج (SDK) الخاصة بالعميل قيمًا جديدة. أمثلة: "0" أو "30 ثانية" أو "ساعة و30 دقيقة".

  القيمة التلقائية لـ maxAge هي 0، ما يعني أنّه يتم تخزين الردود مؤقتًا، ولكن ستجلب حزمة تطوير البرامج (SDK) للعميل دائمًا قيمًا جديدة. لن يتم استخدام القيم المخزّنة مؤقتًا إلا عندما يتم ضبط CACHE_ONLY على execute() وعرض النتيجة الأولية من subscribe().

• ‫storage: يمكن ضبط حزمة SDK الخاصة بالعميل لتخزين الردود مؤقتًا إما في مساحة التخزين persistent أو في memory. ستبقى النتائج المخزّنة مؤقتًا في مساحة تخزين persistent متاحة عند إعادة تشغيل التطبيق. عند استهداف نظام التشغيل Android أو iOS، تكون القيمة التلقائية هي persistent. عند استهداف متصفّحات الويب، لا يتوفّر سوى مساحة تخزين memory.

بعد تعديل إعدادات التخزين المؤقت للموصل، أعِد إنشاء حِزم تطوير البرامج (SDK) الخاصة بالعميل وأعِد إنشاء تطبيقك. بعد الانتهاء من ذلك، سيخزّن execute() وsubscribe() الردود مؤقتًا ويستخدمان القيم المخزّنة مؤقتًا وفقًا للسياسة التي أعددتها. يحدث ذلك تلقائيًا بشكل عام، بدون أي خطوات إضافية من جانبك، ولكن يُرجى ملاحظة ما يلي:

• يكون السلوك التلقائي لـ execute() كما هو موضّح أعلاه: إذا تم تخزين نتيجة طلب البحث مؤقتًا وكانت القيمة المخزَّنة مؤقتًا ليست أقدم من maxAge، يتم استخدام القيمة المخزَّنة مؤقتًا. يُطلق على هذا السلوك التلقائي اسم سياسة PREFER_CACHE.

  يمكنك أيضًا تحديد ما إذا كان سيتم عرض القيم المخزّنة مؤقتًا فقط (CACHE_ONLY) أو جلب قيم جديدة من الخادم بدون شروط (SERVER_ONLY) عند استدعاء execute() بشكل فردي.

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);
  

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);
  

• عند الاتصال بـ subscribe()، سيتم دائمًا عرض المحتوى المخزّن مؤقتًا على الفور إذا كان متاحًا، بغض النظر عن إعداد maxAge. ستؤدي المكالمات اللاحقة إلى الرقم execute() إلى إرسال إشعارات إلى المستمعين وفقًا maxAge الذي تم ضبطه.

استخدام عمليات التغيير من جهة العميل

يمكن الوصول إلى عمليات التغيير بالطريقة نفسها التي يتم بها الوصول إلى طلبات البحث.

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

إنشاء نماذج أولية لتطبيقات Flutter واختبارها

تجهيز العملاء لاستخدام محاكي محلي

يمكنك استخدام محاكي SQL Connect، سواء من إضافة SQL Connect VS Code أو من واجهة سطر الأوامر.

تكون عملية إعداد التطبيق للاتصال بالمحاكي هي نفسها في كلتا الحالتين.

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';

MoviesConnector.instance.dataConnect
          .useDataConnectEmulator('127.0.0.1', 9399);

// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();

للتبديل إلى موارد الإنتاج، علِّق على الأسطر التي تربطك بالمحاكي.

أنواع البيانات في حزمة تطوير البرامج (SDK) للغة Dart

يمثّل خادم SQL Connect أنواع بيانات GraphQL الشائعة. ويتم تمثيلها في حزمة SDK على النحو التالي.