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

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

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

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

אחרי שחוזרים על תהליך העדכון של השירות ושל אפליקציות הלקוח, העדכונים בצד השרת ובצד הלקוח מוכנים לפריסה.

מהו תהליך העבודה לפיתוח לקוחות?

אם פעלתם לפי השלבים במאמר תחילת העבודה, קיבלתם הסבר על תהליך הפיתוח הכולל של SQL Connect. במדריך הזה מופיע מידע מפורט יותר על יצירת ערכות Flutter SDK מהסכימה שלכם ועל עבודה עם שאילתות ומוטציות של לקוחות.

לסיכום, כדי להשתמש בערכות Flutter SDK שנוצרו באפליקציות הלקוח, צריך לבצע את השלבים המקדימים הבאים:

1. מוסיפים את Firebase לאפליקציית Flutter.
2. מתקינים את flutterfire CLI dart pub global activate flutterfire_cli.
3. מריצים את flutterfire configure.

לאחר מכן:

1. פיתוח סכימת האפליקציה.

2. מגדירים יצירת SDK:

   • באמצעות הלחצן Add SDK to app (הוספת SDK לאפליקציה) בתוסף SQL Connect ל-VS Code
   • עדכון connector.yaml.

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

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

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

יצירת Flutter SDK

משתמשים ב-Firebase CLI כדי להגדיר ערכות 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 כדי ליצור SQL Connect SDK בתהליכי בנייה של 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();
}

שדות אופציונליים

יכול להיות שלחלק מהשאילתות יש שדות אופציונליים. במקרים כאלה, Flutter SDK חושף שיטת builder, ויהיה צורך להגדיר אותה בנפרד.

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

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

הרשמה לקבלת עדכונים על שינויים

אתם יכולים להירשם לעדכונים (כך שהנתונים יתעדכנו בכל פעם שתריצו שאילתה).

QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();

// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
  updateUIWithMovies(data.movies);
});

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`

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

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

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