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

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

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

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

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

حول المكتبات ذات مساحة الاسم ( compat ).

هناك نوعان من المكتبات المتاحة لـ Firebase Web SDK:

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

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

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

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

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

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

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

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

npm i firebase@10.9.0

# OR

yarn add firebase@10.9.0

تحديث الواردات للتوافق

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

قبل: الإصدار 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 والحزم الأخرى تصديرًا شاملاً يحتوي على جميع الأساليب من الحزمة. بدلاً من ذلك، تقوم الحزم بتصدير الوظائف الفردية.

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

المثال 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

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

تقدم واجهة برمجة التطبيقات المعيارية تغييرًا جذريًا حيث تم تغيير الخاصية firestore.DocumentSnapshot.exists إلى طريقة . الوظيفة هي نفسها بشكل أساسي (اختبار ما إذا كان المستند موجودًا) ولكن يجب عليك إعادة بناء التعليمات البرمجية الخاصة بك لاستخدام الطريقة الأحدث كما هو موضح:

قبل: متوافق

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/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>

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

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

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

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