از API فضای نامی به API مدولار ارتقا دهید

برنامه‌هایی که درحال‌حاضر از هر فضای نامی Firebase Web API استفاده می‌کنند، از کتابخانه‌های compat تا نسخه 8 یا قبل‌تر، باید با استفاده از دستورالعمل‌های این راهنما، به API مدولار مهاجرت کنند.

این راهنما فرض می کند که شما با API فضای نام آشنا هستید و از یک بسته ماژول مانند بسته وب یا Rollup برای ارتقاء و توسعه مداوم برنامه ماژولار استفاده خواهید کرد.

استفاده از باندلر ماژول در محیط توسعه خود به شدت توصیه می شود. اگر از یکی استفاده نکنید، نمی‌توانید از مزایای اصلی API ماژولار در کاهش اندازه برنامه استفاده کنید. برای نصب SDK به npm یا نخ نیاز دارید.

مراحل ارتقا در این راهنما حول یک برنامه وب خیالی است که از Authentication و Cloud Firestore SDK استفاده می کند. با کار کردن بر روی مثال‌ها، می‌توانید بر مفاهیم و مراحل عملی مورد نیاز برای ارتقاء همه SDK‌های Web Firebase پشتیبانی شده تسلط پیدا کنید.

درباره کتابخانه‌های فضای نام ( compat ).

دو نوع کتابخانه برای Firebase Web SDK وجود دارد:

• مدولار - یک سطح API جدید که برای تسهیل تکان دادن درخت (حذف کدهای استفاده نشده) طراحی شده است تا برنامه وب شما تا حد امکان کوچک و سریع باشد.
• Namespaced ( compat ) - یک سطح API آشنا که کاملاً با نسخه‌های قبلی SDK سازگار است و به شما امکان می‌دهد بدون تغییر همه کدهای Firebase به طور همزمان، آن را ارتقا دهید. کتابخانه های Compat نسبت به همتایان خود در فضای نام دارای مزیت های کمی یا بدون مزیت های عملکردی هستند.

این راهنما فرض می کند که شما از کتابخانه های سازگار برای تسهیل ارتقای خود استفاده خواهید کرد. این کتابخانه ها به شما این امکان را می دهند که به استفاده از کدهای فضای نامی در کنار کدهای بازسازی شده برای API مدولار ادامه دهید. این بدان معناست که شما می توانید برنامه خود را با سهولت بیشتری کامپایل و اشکال زدایی کنید، همانطور که در فرآیند ارتقا کار می کنید.

برای برنامه‌هایی که قرار گرفتن در معرض بسیار کمی با Firebase Web SDK دارند - برای مثال، برنامه‌ای که فقط یک تماس ساده با APIهای Authentication برقرار می‌کند - ممکن است بدون استفاده از کتابخانه‌های سازگار، کدهای فضای نام قدیمی‌تر را تغییر دهیم. اگر چنین برنامه‌ای را ارتقا می‌دهید، می‌توانید دستورالعمل‌های این راهنما را برای «API مدولار» بدون استفاده از کتابخانه‌های compat دنبال کنید.

درباره روند ارتقا

هر مرحله از فرآیند ارتقا به گونه ای است که می توانید ویرایش منبع برنامه خود را به پایان برسانید و سپس آن را بدون شکستگی کامپایل و اجرا کنید. به طور خلاصه، در اینجا کاری که برای ارتقاء یک برنامه انجام خواهید داد:

1. کتابخانه های مدولار و کتابخانه های سازگار را به برنامه خود اضافه کنید.
2. عبارت های واردات را در کد خود به روز کنید تا با هم سازگار شوند.
3. کد Refactor برای یک محصول واحد (به عنوان مثال، Authentication ) به سبک مدولار.
4. اختیاری: در این مرحله، کتابخانه Compat Authentication و کد سازگار برای Authentication را حذف کنید تا قبل از ادامه، از مزیت اندازه برنامه برای Authentication استفاده کنید.
5. توابع Refactor برای هر محصول (به عنوان مثال، Cloud Firestore ، FCM ، و غیره) به سبک مدولار، کامپایل و آزمایش تا زمانی که همه مناطق کامل شوند.
6. کد اولیه را به سبک مدولار به روز کنید.
7. تمام عبارات compat و کد سازگار باقیمانده را از برنامه خود حذف کنید.

آخرین نسخه SDK را دریافت کنید

برای شروع، کتابخانه های مدولار و کتابخانه های سازگار را با استفاده از npm دریافت کنید:

npm i firebase@10.14.0

# OR

yarn add firebase@10.14.0

به روز رسانی واردات به compat

برای اینکه کد خود را پس از به‌روزرسانی وابستگی‌هایتان فعال نگه دارید، عبارت‌های واردات خود را برای استفاده از نسخه «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 ماژولار، سرویس ها به عنوان اولین آرگومان ارسال می شوند و سپس تابع از جزئیات سرویس برای انجام بقیه موارد استفاده می کند. بیایید بررسی کنیم که چگونه این کار در دو مثال انجام می شود که Refactor به 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 مانند API فضای نامی از نمونه auth زنجیر نشده است. در عوض، این یک تابع رایگان است که auth به عنوان اولین پارامتر خود می گیرد.

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

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

مدیریت به‌روزرسانی روش Auth getRedirectResult

API ماژولار یک تغییر قطعی را در getRedirectResult معرفی می کند. هنگامی که هیچ عملیات تغییر مسیری فراخوانی نمی شود، API ماژولار بر خلاف API با فضای نام، که یک UserCredential با یک کاربر null برمی گرداند null را برمی گرداند.

قبل از: همنشین

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

قبل از: همنشین

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 نگه دارید، در حالی که Authentication یا دیگر کدهای 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);

به خاطر داشته باشید که اگرچه برنامه شما کامپایل می شود، اما تا زمانی که دستورات سازگار و کد را به طور کامل از برنامه خود حذف نکنید، از مزایای اندازه برنامه کد ماژولار برخوردار نخواهید شد.

کد اولیه را به روز کنید

کد مقداردهی اولیه برنامه خود را برای استفاده از نحو مدولار به روز کنید. مهم است که این کد را پس از تکمیل مجدد تمام کدهای موجود در برنامه خود به روز کنید. این به این دلیل است که firebase.initializeApp() حالت جهانی را برای APIهای سازگار و مدولار مقداردهی می کند، در حالی که تابع ماژولار initializeApp() فقط حالت را برای ماژولار مقداردهی می کند.

قبل از: همنشین

import firebase from "firebase/compat/app"

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

بعد از: مدولار

import { initializeApp } from "firebase/app"

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

کد compat را حذف کنید

برای درک مزایای اندازه API ماژولار، در نهایت باید همه فراخوان‌ها را به سبک مدولار نشان داده شده در بالا تبدیل کنید و تمام عبارات import "firebase/compat/* را از کد خود حذف کنید. وقتی کارتان تمام شد، دیگر هیچ مرجعی وجود نخواهد داشت. به firebase.* فضای نام جهانی یا هر کد دیگری در سبک API فضای نامی.

استفاده از کتابخانه compat از پنجره

API ماژولار برای کار با ماژول ها به جای شی window مرورگر بهینه شده است. نسخه‌های قبلی کتابخانه بارگیری و مدیریت Firebase را با استفاده از فضای نام window.firebase مجاز می‌کرد. این کار در آینده توصیه نمی شود زیرا امکان حذف کدهای استفاده نشده را نمی دهد. با این حال، نسخه سازگار JavaScript SDK برای توسعه دهندگانی که ترجیح می دهند بلافاصله مسیر ارتقاء ماژولار را شروع نکنند، با window کار می کند.

<script src="https://www.gstatic.com/firebasejs/10.14.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.14.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.14.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 مدولار کاهش چشمگیر اندازه برنامه را امکان پذیر می کند. این فرمت ماژول جاوا اسکریپت مدرن را به کار می‌گیرد و به شیوه‌های "تکان دادن درخت" اجازه می‌دهد که در آن فقط مصنوعاتی را که برنامه‌تان نیاز دارد وارد کنید. بسته به برنامه شما، تکان دادن درخت با SDK ماژولار می تواند 80 درصد کیلوبایت کمتری نسبت به یک برنامه مشابه که با استفاده از API فضای نام ساخته شده است، داشته باشد.
• SDK مدولار همچنان از توسعه ویژگی‌های مداوم بهره می‌برد، در حالی که API فضای نامی این کار را نخواهد کرد.