שדרג מ-API עם רווח שמות ל-API המודולרי

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

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

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

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

על הספריות עם רווחי שמות ( compat ).

ישנם שני סוגים של ספריות זמינים עבור Firebase Web SDK:

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

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

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

לגבי תהליך השדרוג

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

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

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

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

npm i firebase@10.9.0

# OR

yarn add firebase@10.9.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';

Refactor לסגנון המודולרי

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

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

דוגמה 1: עיבוד מחדש של פונקציית אימות

לפני: compat

קוד ה-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 כפי שהיא תהיה ב-API עם רווח שמות; במקום זאת, זוהי פונקציה חינמית שלוקחת את auth כפרמטר הראשון שלה.

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

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

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

ה-API המודולרי מציג שינוי פורץ ב- getRedirectResult . כאשר לא נקראת פעולת הפניה מחדש, ה-API המודולרי מחזיר null בניגוד ל-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 בדוגמה קודמת. שימו לב כיצד הקוד ליצירת שאילתה שונה מאוד ב-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

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

לפני: compat

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

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

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

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

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

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

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

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

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

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

לפני: compat

import firebase from "firebase/compat/app"

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

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

import { initializeApp } from "firebase/app"

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

הסר את קוד הקומפט

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

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

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

<script src="https://www.gstatic.com/firebasejs/10.9.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.9.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.9.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 Module, המאפשר שיטות "טלטול עצים" שבהן אתה מייבא רק את החפצים שהאפליקציה שלך צריכה. בהתאם לאפליקציה שלך, רעד עצים עם ה-SDK המודולרי יכול לגרום ל-80% פחות קילובייט מאשר אפליקציה דומה שנבנתה באמצעות ה-API עם רווח שמות.
  • ה-SDK המודולרי ימשיך להפיק תועלת מפיתוח תכונות מתמשך, בעוד שה-API עם רווחי שמות לא.