שדרוג מ-API במרחב שמות לאפליקציה מודולרית

אם אתם משתמשים באפליקציות עם ממשק API של Firebase לאינטרנט שמבוסס על מרחב שמות, החל מספריות compat ועד לגרסה 8 או גרסאות קודמות, כדאי לכם לעבור ל-modular API לפי ההוראות שבמדריך הזה.

המדריך הזה מניח שאתם מכירים את ה-API של מרחב השמות, ושתשתמשו בכלי לאריזת מודולים כמו webpack או Rollup כדי לשדרג ולפתח אפליקציות מודולריות באופן שוטף.

מומלץ מאוד להשתמש בכלי לאריזת מודולים בסביבת הפיתוח. אם לא תשתמשו בכלי כזה, לא תוכלו ליהנות מהיתרונות העיקריים של ה-API המודולרי בהקטנת גודל האפליקציה. כדי להתקין את ה-SDK, צריך את npm או את yarn.

השלבים לשדרוג במדריך הזה מבוססים על אפליקציית אינטרנט דמיונית שמשתמשת בערכות ה-SDK של Authentication ו-Cloud Firestore. הדוגמאות האלה יעזרו לכם להבין את המושגים ואת השלבים המעשיים שצריך לבצע כדי לשדרג את כל ערכות ה-SDK הנתמכות של Firebase לאינטרנט.

מידע על הספריות של מרחב השמות (compat)

יש שני סוגים של ספריות זמינות ל-SDK של Firebase לאינטרנט:

  • מודולרי – ממשק API חדש שנועד לאפשר tree-shaking (הסרה של קוד שלא בשימוש) כדי להקטין את אפליקציית האינטרנט ולהאיץ אותה ככל האפשר.
  • מרחב שמות (compat) – ממשק API מוכר שתואם באופן מלא לגרסאות הקודמות של ה-SDK, ומאפשר לשדרג בלי לשנות את כל קוד Firebase בבת אחת. לספריות תאימות יש יתרונות קטנים, אם בכלל, מבחינת גודל או ביצועים בהשוואה לספריות המקבילות שלהן במרחב השמות.

המדריך הזה מבוסס על ההנחה שתשתמשו בספריות התאימות כדי לבצע את השדרוג. הספריות האלה מאפשרות לכם להמשיך להשתמש בקוד עם מרחב שמות לצד קוד שעבר refactoring ל-modular API. זה אומר שתוכלו לקמפל את האפליקציה ולנפות בה באגים בקלות רבה יותר במהלך תהליך השדרוג.

באפליקציות עם חשיפה קטנה מאוד ל-Firebase Web SDK – לדוגמה, אפליקציה שמבצעת רק קריאה פשוטה לממשקי ה-API של Authentication – יכול להיות שיהיה מעשי לשנות את הקוד הישן של מרחב השמות בלי להשתמש בספריות התאימות. אם אתם משדרגים אפליקציה כזו, אתם יכולים לפעול לפי ההוראות במדריך הזה ל-modular API בלי להשתמש בספריות התאימות.

מידע על תהליך השדרוג

כל שלב בתהליך השדרוג מוגדר כך שתוכלו לסיים את עריכת המקור של האפליקציה, ואז לקמפל ולהריץ אותה בלי תקלות. לסיכום, כדי לשדרג אפליקציה:

  1. מוסיפים לאפליקציה את הספריות המודולריות ואת ספריות התאימות.
  2. מעדכנים את הצהרות הייבוא בקוד ל-compat.
  3. משכתבים את הקוד של מוצר אחד (לדוגמה, Authentication) לסגנון מודולרי.
  4. אופציונלי: בשלב הזה, מסירים את ספריית התאימות של Authentication ואת קוד התאימות של Authentication כדי ליהנות מהיתרון של גודל האפליקציה ב-Authentication לפני שממשיכים.
  5. משכתבים את הפונקציות של כל מוצר (לדוגמה, Cloud Firestore, FCM וכו') לסגנון מודולרי, מקמפלים ובודקים עד שכל האזורים מוכנים.
  6. מעדכנים את קוד האתחול לסגנון המודולרי.
  7. מסירים מהאפליקציה את כל הצהרות התאימות וקוד התאימות שנותרו.

הורדת הגרסה העדכנית של ה-SDK

כדי להתחיל, צריך להוריד את הספריות המודולריות ואת ספריות התאימות באמצעות npm:

npm i firebase@13.2.0

# OR

yarn add firebase@13.2.0

עדכון הייבוא לתאימות

כדי שהקוד ימשיך לפעול אחרי עדכון יחסי התלות, צריך לשנות את הצהרות הייבוא כך שישתמשו בגרסת ה-compat של כל ייבוא. לדוגמה:

לפני: גרסה 8 או גרסאות קודמות

import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';

אחרי: compat

// compat packages are API compatible with namespaced code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';

לארגן את הקוד מחדש לסגנון מודולרי

ממשקי ה-API של מרחב השמות מבוססים על תבנית של שירות ומרחב שמות עם שרשור נקודות, אבל הגישה המודולרית מאפשרת לארגן את הקוד בעיקר סביב פונקציות. ב-modular API, החבילה firebase/app וחבילות אחרות לא מחזירות ייצוא מקיף שמכיל את כל השיטות מהחבילה. במקום זאת, החבילות מייצאות פונקציות נפרדות.

ב-modular API, השירותים מועברים כארגומנט הראשון, ואז הפונקציה משתמשת בפרטי השירות כדי לבצע את השאר. נבחן איך זה עובד בשתי דוגמאות שמשנות את הקוד של הקריאות לממשקי ה-API של Authentication ו-Cloud Firestore.

דוגמה 1: שכתוב של פונקציית Authentication

לפני: compat

קוד התאימות זהה לקוד של מרחב השמות, אבל הייבוא השתנה.

import firebase from "firebase/compat/app";
import "firebase/compat/auth";

const auth = firebase.auth();
auth.onAuthStateChanged(user => { 
  // Check for user status
});

אחרי: מודולרי

הפונקציה getAuth מקבלת את firebaseApp בתור הפרמטר הראשון שלה. הפונקציה onAuthStateChanged לא משורשרת מהמופע של auth כמו ב-namespaced API, אלא היא פונקציה חופשית שמקבלת את auth כפרמטר הראשון שלה.

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

עדכון הטיפול בשיטת האימות getRedirectResult

ה-modular API מציג שינוי תוכנה שעלול לגרום לכשל ב-getRedirectResult. כשלא מתבצעת קריאה לפעולת הפניה אוטומטית, ה-modular API מחזיר null, בניגוד ל-namespaced API, שהחזיר UserCredential עם משתמש null.

לפני: compat

const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
  return null;
}
return result;

אחרי: מודולרי

const result = await getRedirectResult(auth);
// Provider of the access token could be Facebook, Github, etc.
if (result === null || provider.credentialFromResult(result) === null) {
  return null;
}
return result;

דוגמה 2: ארגון קוד מחדש של פונקציית Cloud Firestore

לפני: compat

import "firebase/compat/firestore"

const db = firebase.firestore();
db.collection("cities").where("capital", "==", true)
    .get()
    .then((querySnapshot) => {
        querySnapshot.forEach((doc) => {
            // doc.data() is never undefined for query doc snapshots
            console.log(doc.id, " => ", doc.data());
        });
    })
    .catch((error) => {
        console.log("Error getting documents: ", error);
    });

אחרי: מודולרי

הפונקציה getFirestore מקבלת את firebaseApp כפרמטר הראשון שלה, שהוחזר מ-initializeApp בדוגמה קודמת. שימו לב שהקוד ליצירת שאילתה שונה מאוד ב-modular API. אין שרשור, ושיטות כמו query או where חשופות עכשיו כפונקציות חופשיות.

import { getFirestore, collection, query, where, getDocs } from "firebase/firestore";

const db = getFirestore(firebaseApp);

const q = query(collection(db, "cities"), where("capital", "==", true));

const querySnapshot = await getDocs(q);
querySnapshot.forEach((doc) => {
  // doc.data() is never undefined for query doc snapshots
  console.log(doc.id, " => ", doc.data());
});

עדכון ההפניות ל-Firestore DocumentSnapshot.exists

ב-modular API יש שינוי תוכנה שעלול לגרום לכשל, שבו המאפיין firestore.DocumentSnapshot.exists השתנה לmethod. הפונקציונליות זהה במהותה (בדיקה אם מסמך קיים), אבל צריך לארגן את הקוד מחדש כדי להשתמש בשיטה החדשה יותר, כפי שמוצג:

Before:compat

if (snapshot.exists) {
  console.log("the document exists");
}

אחרי: מודולרי

if (snapshot.exists()) {
  console.log("the document exists");
}

דוגמה 3: שילוב של סגנונות קוד מודולריים ומרחבי שמות

השימוש בספריות התאימות במהלך השדרוג מאפשר לכם להמשיך להשתמש בקוד עם מרחב שמות לצד קוד שעבר refactoring ל-modular API. זה אומר שאתם יכולים להשאיר את הקוד הקיים של Cloud Firestore עם מרחב השמות, בזמן שאתם משנים את הקוד של Authentication או קוד אחר של Firebase SDK לסגנון המודולרי, ועדיין לקמפל את האפליקציה עם שני סגנונות הקוד. אותו הדבר נכון לגבי קוד API עם מרחב שמות וקוד API מודולרי בתוך מוצר כמו Cloud Firestore. סגנונות קוד חדשים וישנים יכולים להתקיים במקביל, כל עוד מייבאים את חבילות התאימות:

import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'

const docRef = firebase.firestore().doc();
getDoc(docRef);

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

עדכון קוד האתחול

מעדכנים את קוד האתחול של האפליקציה כך שישתמש בתחביר מודולרי. חשוב לעדכן את הקוד הזה אחרי שמסיימים לארגן את כל הקוד מחדש באפליקציה, כי firebase.initializeApp() מאתחל את המצב הגלובלי גם ל-API התואם וגם ל-modular API, ואילו הפונקציה המודולרית initializeApp() מאתחלת רק את המצב של ה-modular API.

לפני: compat

import firebase from "firebase/compat/app"

firebase.initializeApp({ /* config */ });

אחרי: מודולרי

import { initializeApp } from "firebase/app"

const firebaseApp = initializeApp({ /* config */ });

הסרת קוד תאימות

כדי ליהנות מהיתרונות של ה-API המודולרי מבחינת הגודל, בסופו של דבר צריך להמיר את כל הקריאות לסגנון המודולרי שמוצג למעלה ולהסיר את כל הצהרות ה-import "firebase/compat/* מהקוד. בסיום, לא אמורות להיות יותר הפניות למרחב השמות הגלובלי firebase.* או לכל קוד אחר בסגנון של namespaced API.

שימוש בספריית התאימות מהחלון

ה-API המודולרי מותאם לעבודה עם מודולים ולא עם האובייקט window של הדפדפן. בגרסאות קודמות של הספרייה אפשר היה לטעון את Firebase ולנהל אותו באמצעות מרחב השמות window.firebase. לא מומלץ להשתמש בשיטה הזו, כי היא לא מאפשרת להסיר קוד שלא בשימוש. עם זאת, גרסת התאימות של JavaScript SDK פועלת עם window למפתחים שמעדיפים לא להתחיל מיד את תהליך השדרוג המודולרי.

<script src="https://www.gstatic.com/firebasejs/13.2.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/13.2.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/13.2.0/firebase-auth-compat.js"></script>
<script>
   const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
   const db = firebaseApp.firestore();
   const auth = firebaseApp.auth();
</script>

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

היתרונות והמגבלות של ה-SDK המודולרי

ל-SDK המודולרי לחלוטין יש את היתרונות הבאים על פני גרסאות קודמות:

  • ה-SDK המודולרי מאפשר להקטין באופן משמעותי את גודל האפליקציה. הוא משתמש בפורמט המודול המודרני של JavaScript, שמאפשר שיטות של tree shaking שבהן מייבאים רק את פריטי המידע שדרושים לאפליקציה. בהתאם לאפליקציה, tree-shaking עם ה-SDK המודולרי יכול להביא לחיסכון של 80% בקילובייטים בהשוואה לאפליקציה דומה שנבנתה באמצעות namespaced API.
  • ערכת ה-SDK המודולרית תמשיך ליהנות מפיתוח תכונות שוטף, ואילו ה-namespaced API לא.