שימוש בערכות Flutter SDK שנוצרו

ערכות ה-SDK של הלקוח ב-Firebase SQL Connect מאפשרות לבצע קריאות לשאילתות ולמוטציות בצד השרת ישירות מאפליקציית Firebase. אתם יוצרים ערכת SDK מותאמת אישית של הלקוח במקביל לתכנון הסכימות, השאילתות והמוטציות שאתם פורסים בשירות SQL Connect. לאחר מכן, משלבים שיטות מה-SDK הזה בלוגיקה של הלקוח.

כמו שציינו במקומות אחרים, חשוב לציין שSQL Connect שאילתות ומוטציות לא נשלחות על ידי קוד הלקוח ומבוצעות בשרת. במקום זאת, כשפורסים את SQL Connect, הפעולות נשמרות בשרת כמו פונקציות של Cloud Functions. זה אומר שצריך לפרוס שינויים תואמים בצד הלקוח כדי לא לפגוע במשתמשים קיימים (לדוגמה, בגרסאות ישנות יותר של האפליקציה).

לכן, 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:

   • באמצעות הלחצן Add SDK to app בתוסף SQL Connect VS Code שלנו
   • לעדכן את connector.yaml.

3. מאתחלים את קוד הלקוח ומייבאים ספריות.

4. מטמיעים קריאות לשאילתות ומוטציות.

5. מגדירים את האמולטור של SQL Connect ומשתמשים בו, וחוזרים על הפעולה.

יצירת Flutter SDK

משתמשים ב-CLI של 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 בצינורות עיבוד נתונים של גרסאות build

אתם יכולים להשתמש ב-Firebase CLI כדי ליצור ערכות SDK של SQL Connect בתהליכי build של 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. המידע הזה מופיע בדף Databases & Storage > 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 חושף שיטת builder, וצריך להגדיר אותה בנפרד.

לדוגמה, השדה rating הוא אופציונלי כשקוראים ל-createMovie, ולכן צריך לספק אותו בפונקציית ה-builder.

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

הרשמה לשינויים

איך מקבלים עדכונים בזמן אמת מ-SQL Connect

טיפול בשינויים בשדות של ספירה

סכימה של אפליקציה יכולה להכיל ספירות, שאפשר לגשת אליהן באמצעות שאילתות GraphQL.

אם העיצוב של האפליקציה משתנה, אתם יכולים להוסיף ערכים נתמכים חדשים של enum. לדוגמה, נניח שבשלב מאוחר יותר במחזור החיים של האפליקציה, אתם מחליטים להוסיף ערך FULLSCREEN ל-enum של 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",‏ "30s",‏ "1h30m".

  ערך ברירת המחדל של maxAge הוא 0, כלומר התשובות נשמרות במטמון, אבל ה-SDK של הלקוח תמיד יאחזר ערכים חדשים. המערכת תשתמש בערכים שנשמרו במטמון רק אם CACHE_ONLY צוין כ-execute() והתוצאה הראשונית הוחזרה מ-subscribe().

• ‫storage: אפשר להגדיר את ה-SDK של הלקוח לשמור תשובות במטמון באחסון של persistent או ב-memory. התוצאות שנשמרו במטמון באחסון של persistent יישארו גם אחרי הפעלה מחדש של האפליקציה. כשמטרגטים ל-Android או ל-iOS, ברירת המחדל היא persistent. כשמטרגטים דפדפני אינטרנט, יש תמיכה רק באחסון ב-memory.

אחרי שמעדכנים את הגדרות השמירה במטמון של המחבר, יוצרים מחדש את ערכות ה-SDK של הלקוח ובונים מחדש את האפליקציה. אחרי שעושים את זה, execute() ו-subscribe() ישמרו תשובות במטמון וישתמשו בערכים שנשמרו במטמון בהתאם למדיניות שהגדרתם. בדרך כלל זה קורה באופן אוטומטי, בלי שתצטרכו לבצע פעולות נוספות, אבל חשוב לשים לב לנקודות הבאות:

• התנהגות ברירת המחדל של execute() היא כמו שמתואר למעלה: אם תוצאה נשמרת במטמון עבור שאילתה והערך שנשמר במטמון לא ישן יותר מ-maxAge, אז משתמשים בערך שנשמר במטמון. פעולת ברירת המחדל הזו נקראת המדיניות PREFER_CACHE.

  אפשר גם לציין בקריאות ספציפיות ל-execute() אם להציג רק ערכים שנשמרו במטמון (CACHE_ONLY) או לאחזר ערכים חדשים מהשרת ללא תנאי (SERVER_ONLY).

  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 או מה-CLI.

הגדרת האפליקציה להתחברות לאמולטור זהה בשני התרחישים.

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();

כדי לעבור למשאבי ייצור, מסמנים כהערה את השורות להתחברות לאמולטור.

סוגי נתונים ב-Dart SDK

השרת SQL Connect מייצג סוגי נתונים נפוצים של GraphQL. הם מיוצגים ב-SDK באופן הבא.