قم بالترقية من واجهة برمجة التطبيقات ذات مساحة الاسم إلى واجهة برمجة التطبيقات المعيارية

يجب أن تفكر التطبيقات التي تستخدم حاليًا أي واجهة برمجة تطبيقات ويب Firebase Web ، بدءًا من المكتبات compat حتى الإصدار 8 أو ما قبله ، في الترحيل إلى واجهة برمجة التطبيقات المعيارية باستخدام الإرشادات الواردة في هذا الدليل.

يفترض هذا الدليل أنك على دراية بواجهة برمجة التطبيقات ذات مساحة الاسم وأنك ستستفيد من حزمة الوحدات النمطية مثل webpack أو Rollup للترقية والتطوير المستمر للتطبيقات المعيارية.

يوصى بشدة باستخدام أداة تجميع الوحدات في بيئة التطوير الخاصة بك. إذا لم تستخدم واحدًا ، فلن تتمكن من الاستفادة من المزايا الرئيسية لواجهة برمجة التطبيقات المعيارية في تقليل حجم التطبيق. ستحتاج إلى npm أو الغزل لتثبيت SDK.

ستعتمد خطوات الترقية في هذا الدليل على تطبيق ويب وهمي يستخدم مصادقة وحزم SDK لـ Cloud Firestore. من خلال العمل من خلال الأمثلة ، يمكنك إتقان المفاهيم والخطوات العملية المطلوبة لترقية جميع مجموعات Firebase Web SDK المدعومة.

حول المكتبات ذات مساحات الأسماء ( compat )

يتوفر نوعان من المكتبات لـ Firebase Web SDK:

• معياري - سطح API جديد مصمم لتسهيل اهتزاز الشجرة (إزالة الكود غير المستخدم) لجعل تطبيق الويب الخاص بك صغيرًا وسريعًا قدر الإمكان.
• Namespaced ( compat ) - سطح واجهة برمجة تطبيقات مألوف متوافق تمامًا مع الإصدارات السابقة من SDK ، مما يسمح لك بالترقية دون تغيير رمز Firebase بالكامل مرة واحدة. تتمتع مكتبات Compat بمزايا حجم أو أداء قليلة أو معدومة مقارنة بنظيراتها من مساحات الأسماء.

يفترض هذا الدليل أنك ستستفيد من المكتبات المتوافقة لتسهيل الترقية. تتيح لك هذه المكتبات الاستمرار في استخدام التعليمات البرمجية ذات مساحة الاسم جنبًا إلى جنب مع التعليمات البرمجية المعاد تصميمها لواجهة برمجة التطبيقات المعيارية. هذا يعني أنه يمكنك ترجمة تطبيقك وتصحيحه بسهولة أكبر أثناء عملك خلال عملية الترقية.

بالنسبة للتطبيقات ذات التعرض الضئيل جدًا لـ Firebase Web SDK - على سبيل المثال ، تطبيق يقوم بإجراء مكالمة بسيطة فقط إلى واجهات برمجة تطبيقات المصادقة - قد يكون من العملي إعادة هيكلة التعليمات البرمجية القديمة ذات مساحة الاسم دون استخدام المكتبات المتوافقة. إذا كنت تقوم بترقية مثل هذا التطبيق ، فيمكنك اتباع التعليمات الواردة في هذا الدليل لـ "API المعياري" دون استخدام المكتبات المتوافقة.

حول عملية الترقية

يتم تحديد نطاق كل خطوة من خطوات عملية الترقية بحيث يمكنك الانتهاء من تحرير المصدر لتطبيقك ثم تجميعه وتشغيله دون انقطاع. باختصار ، إليك ما ستفعله لترقية أحد التطبيقات:

1. أضف المكتبات المعيارية والمكتبات المتوافقة إلى تطبيقك.
2. قم بتحديث بيانات الاستيراد في التعليمات البرمجية الخاصة بك إلى التوافق.
3. كود Refactor لمنتج واحد (على سبيل المثال ، المصادقة) إلى النمط المعياري.
4. اختياري: في هذه المرحلة ، قم بإزالة مكتبة توافق المصادقة ورمز التوافق للمصادقة من أجل تحقيق فائدة حجم التطبيق للمصادقة قبل المتابعة.
5. وظائف Refactor لكل منتج (على سبيل المثال ، Cloud Firestore ، FCM ، إلخ) إلى النمط المعياري ، والتجميع والاختبار حتى تكتمل جميع المناطق.
6. تحديث كود التهيئة إلى النمط المعياري.
7. قم بإزالة جميع بيانات التوافق المتبقية ورمز التوافق من تطبيقك.

احصل على أحدث إصدار من SDK

للبدء ، احصل على المكتبات المعيارية والمكتبات المتوافقة باستخدام npm:

npm i firebase@9.22.1

# OR

yarn add firebase@9.22.1

تحديث الواردات إلى مواطن

من أجل الحفاظ على عمل التعليمات البرمجية الخاصة بك بعد تحديث التبعيات الخاصة بك ، قم بتغيير بيانات الاستيراد الخاصة بك لاستخدام الإصدار "المتوافق" لكل عملية استيراد. على سبيل المثال:

قبل: الإصدار 8 أو أقدم

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

بعد: المواطن

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

Refactor إلى النمط المعياري

بينما تستند واجهات برمجة التطبيقات ذات مساحة الاسم إلى مساحة اسم متسلسلة بالنقاط ونمط خدمة ، فإن النهج المعياري يعني أن التعليمات البرمجية الخاصة بك سيتم تنظيمها بشكل أساسي حول الوظائف . في واجهة برمجة التطبيقات المعيارية ، لا تُرجع حزمة firebase/app والحزم الأخرى تصديرًا شاملاً يحتوي على جميع الطرق من الحزمة. بدلاً من ذلك ، تقوم الحزم بتصدير الوظائف الفردية.

في API المعياري ، يتم تمرير الخدمات كوسيطة أولى ، ثم تستخدم الوظيفة تفاصيل الخدمة للقيام بالباقي. دعنا نفحص كيفية عمل هذا في مثالين يستدعيان المصادقة و Cloud Firestore APIs.

مثال 1: إعادة هيكلة دالة المصادقة

قبل: المواطن

رمز التوافق مطابق للرمز الذي يحتوي على مساحة الاسم ، ولكن تم تغيير عمليات الاستيراد.

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 كما هو الحال في واجهة برمجة التطبيقات ذات مساحة الاسم ؛ بدلاً من ذلك ، إنها وظيفة مجانية تأخذ auth كأول معلمة لها.

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

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

تحديث معالجة أسلوب المصادقة getRedirectResult

تقدم API المعيارية تغييرًا فاصلًا في getRedirectResult . عندما لا يتم استدعاء أي عملية إعادة توجيه ، تقوم API المعيارية بإرجاع null على عكس واجهة برمجة التطبيقات ذات مساحة الاسم ، والتي أعادت UserCredential مع مستخدم 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 إلى طريقة . الوظيفة هي نفسها بشكل أساسي (اختبار ما إذا كان المستند موجودًا) ولكن يجب إعادة تشكيل التعليمات البرمجية الخاصة بك لاستخدام طريقة v9 كما هو موضح:

قبل: المواطن

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

بعد: وحدات

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

مثال 3: الجمع بين أنماط التعليمات البرمجية المعيارية ومساحات الأسماء

يتيح لك استخدام المكتبات المتوافقة أثناء الترقية الاستمرار في استخدام التعليمات البرمجية ذات مساحة الاسم جنبًا إلى جنب مع التعليمات البرمجية المعاد تشكيلها لواجهة برمجة التطبيقات المعيارية. هذا يعني أنه يمكنك الاحتفاظ بالشفرة الموجودة في مساحة الاسم لـ Cloud Firestore أثناء إعادة بناء المصادقة أو رمز Firebase SDK الآخر إلى النمط المعياري ، ولا يزال بإمكانك تجميع تطبيقك بنجاح باستخدام كلا نمطي الكود. وينطبق الشيء نفسه على كود 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() يهيئ الحالة العالمية لكل من واجهات برمجة التطبيقات المتوافقة والوحدات النمطية ، في حين أن وظيفة initializeApp() تهيئ الحالة المعيارية فقط.

قبل: المواطن

import firebase from "firebase/compat/app"

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

بعد: وحدات

import { initializeApp } from "firebase/app"

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

إزالة رمز التوافق

لإدراك فوائد الحجم لواجهة برمجة التطبيقات المعيارية ، يجب عليك في النهاية تحويل جميع الاستدعاءات إلى النمط المعياري الموضح أعلاه وإزالة جميع عبارات import "firebase/compat/* من التعليمات البرمجية. عند الانتهاء ، يجب ألا يكون هناك المزيد من المراجع إلى firebase.* مساحة الاسم العالمية أو أي رمز آخر في نمط واجهة برمجة التطبيقات.

استخدام المكتبة المتوافقة من النافذة

تم تحسين واجهة برمجة التطبيقات المعيارية للعمل مع الوحدات بدلاً من كائن window المتصفح. سمحت الإصدارات السابقة من المكتبة بتحميل Firebase وإدارته باستخدام مساحة الاسم window.firebase . لا يُنصح بهذا من الآن فصاعدًا لأنه لا يسمح بإزالة التعليمات البرمجية غير المستخدمة. ومع ذلك ، فإن الإصدار المتوافق من JavaScript SDK يعمل مع window للمطورين الذين يفضلون عدم بدء مسار الترقية المعياري على الفور.

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

تستخدم مكتبة التوافق كودًا معياريًا تحت الغطاء وتوفر لها نفس واجهة برمجة التطبيقات مثل واجهة برمجة التطبيقات ذات مساحة الاسم ؛ هذا يعني أنه يمكنك الرجوع إلى مرجع واجهة برمجة التطبيقات ذات مساحة الاسم ومقتطفات التعليمات البرمجية الخاصة بمساحة الاسم للحصول على التفاصيل. لا يُنصح باستخدام هذه الطريقة على المدى الطويل ، ولكن كبداية للترقية إلى المكتبة المعيارية بالكامل.

فوائد وقيود SDK المعيارية

تتميز SDK المعيارية بالكامل بهذه المزايا مقارنة بالإصدارات السابقة:

• تتيح SDK المعيارية تقليل حجم التطبيق بشكل كبير. وهي تعتمد تنسيق وحدة JavaScript الحديثة ، مما يسمح بممارسات "اهتزاز الشجرة" التي لا تستورد فيها سوى العناصر التي يحتاجها تطبيقك. اعتمادًا على التطبيق الخاص بك ، يمكن أن يؤدي اهتزاز الشجرة باستخدام SDK المعياري إلى تقليل كيلوبايتات أقل بنسبة 80٪ من تطبيق مشابه تم إنشاؤه باستخدام واجهة برمجة التطبيقات ذات مساحة الاسم.
• سيستمر SDK المعياري في الاستفادة من التطوير المستمر للميزات ، في حين أن واجهة برمجة التطبيقات ذات مساحة الاسم لن تفعل ذلك.