الترقية من واجهة برمجة التطبيقات التي تتضمّن مساحة الاسم إلى واجهة برمجة التطبيقات modular API

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

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

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

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

لمحة عن مكتبات مساحات الاسم (compat)

يتوفّر نوعان من المكتبات لحزمة تطوير البرامج (SDK) على الويب لمنصة Firebase:

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

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

بالنسبة إلى التطبيقات التي لديها عدد محدود جدًا من المستخدمين لحزمة تطوير البرامج (SDK) على الويب لمنصة Firebase، مثل هو تطبيق يتيح طلب وصول بسيط إلى واجهات برمجة تطبيقات Authentication، وقد يكون عملية إعادة ضبط التعليمات البرمجية القديمة ذات مساحات الاسم دون استخدام مكتبات التوافق. في حال ترقية هذا التطبيق، يمكنك اتّباع التعليمات الواردة في هذا الدليل. عن "واجهة برمجة التطبيقات modular API" دون استخدام مكتبات التوافق.

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

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

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

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

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

npm i firebase@10.13.1

# OR

yarn add firebase@10.13.1

تعديل عمليات الاستيراد إلى متوافق

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

قبل: الإصدار 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';

إعادة التنفيذ باستخدام النمط النمطي

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

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

المثال 1: إعادة ضبط بنية دالة Authentication

قبل: التوافق

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

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 في مثال سابق. لاحظ كيف لتشكيل استعلام مختلف تمامًا في واجهة برمجة التطبيقات 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

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

قبل:compat

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

بعد: الوحدات النمطية

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

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

يسمح لك استخدام مكتبات التوافق أثناء الترقية بمواصلة استخدام مساحة الاسم بجانب رمز تمت إعادة هيكلته في modular API. هذا يعني أنه يمكنك الاحتفاظ رمز مساحة الاسم الحالي لـ Cloud Firestore أثناء إعادة ضبط Authentication أو أي رمز آخر لحزمة تطوير البرامج (SDK) لمنصة Firebase بالنمط النمطي، وستستمر في تجميع تطبيقك بنجاح باستخدام الرمزين الأنماط. وينطبق الأمر نفسه على رمز واجهة برمجة التطبيقات المقسّمة إلى عدة مساحات داخل منتج مثل كـ 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 */ });

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

للتعرّف على مزايا الحجم التي توفّرها واجهة برمجة التطبيقات modular API، يجب اتّباع الخطوات التالية: وتحويل جميع الاستدعاءات إلى نمط الوحدات الموضحة أعلاه وإزالة جميع import "firebase/compat/* عبارة من الرمز الخاص بك. عند الانتهاء، هناك يجب ألا يكون هناك المزيد من الإشارات إلى مساحة الاسم العامة firebase.* أو أي في نمط واجهة برمجة التطبيقات ذي مساحة الاسم.

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

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

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

تستخدم مكتبة التوافق كودًا نموذجيًا خفيفًا توفير واجهة برمجة التطبيقات نفسها المستخدَمة في واجهة برمجة التطبيقات التي تتضمّن مساحة الاسم فهذا يعني أنه يمكنك يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات namespaced API ومقتطفات الرمز المُصنَّفة ضمن مساحة الاسم للحصول على التفاصيل. هذه الطريقة ليست يُنصح باستخدامه على المدى الطويل، ولكن كبداية للترقية إلى الإصدار التجريبي المكتبة.

مزايا وقيود حزمة تطوير البرامج (SDK) النموذجية

تتميّز حزمة تطوير البرامج (SDK) المؤلفة من وحدات بالكامل بهذه المزايا مقارنةً بالإصدارات السابقة:

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