Переход с API с пространством имен на модульный API

Приложениям, которые в настоящее время используют любой веб-API Firebase с пространством имен, от compat библиотек до версии 8 или более ранней, следует рассмотреть возможность перехода на модульный API, следуя инструкциям в этом руководстве.

В этом руководстве предполагается, что вы знакомы с API с пространством имен и воспользуетесь преимуществами сборщика модулей, такого как webpack или Rollup , для обновления и постоянной разработки модульных приложений.

Настоятельно рекомендуется использовать сборщик модулей в вашей среде разработки. Если вы его не используете, вы не сможете воспользоваться основными преимуществами модульного API в уменьшенном размере приложения. Вам понадобится npm или yarn для установки SDK.

Шаги по обновлению в этом руководстве будут основаны на воображаемом веб-приложении, которое использует SDK аутентификации и Cloud Firestore. Работая с примерами, вы сможете освоить концепции и практические шаги, необходимые для обновления всех поддерживаемых Firebase Web SDK.

О библиотеках с пространством имен ( compat )

Для Firebase Web SDK доступно два типа библиотек:

  • Modular — новая поверхность API, предназначенная для облегчения встряхивания дерева (удаления неиспользуемого кода), чтобы сделать ваше веб-приложение как можно меньше и быстрее.
  • Пространство имен ( compat ) — знакомая поверхность API, полностью совместимая с более ранними версиями SDK, позволяющая выполнять обновление без одновременного изменения всего кода Firebase. Библиотеки совместимости практически не имеют преимуществ по размеру или производительности по сравнению с их аналогами в пространстве имен.

В этом руководстве предполагается, что вы воспользуетесь преимуществами библиотек совместимости для облегчения обновления. Эти библиотеки позволяют продолжать использовать код с пространством имен наряду с кодом, реорганизованным для модульного API. Это означает, что вам будет проще компилировать и отлаживать приложение в процессе обновления.

Для приложений с очень небольшим воздействием Firebase Web SDK — например, приложение, которое делает только простой вызов API-интерфейсов аутентификации — может оказаться практичным рефакторинг старого кода с пространством имен без использования библиотек совместимости. Если вы обновляете такое приложение, вы можете следовать инструкциям в этом руководстве для «модульного API», не используя библиотеки совместимости.

О процессе обновления

Каждый шаг процесса обновления ограничен таким образом, чтобы вы могли завершить редактирование исходного кода для своего приложения, а затем скомпилировать и запустить его без поломок. Итак, вот что вы будете делать, чтобы обновить приложение:

  1. Добавьте модульные библиотеки и совместимые библиотеки в свое приложение.
  2. Обновите операторы импорта в своем коде, чтобы они соответствовали.
  3. Рефакторинг кода отдельного продукта (например, Аутентификация) на модульный стиль.
  4. Необязательно: на этом этапе удалите библиотеку совместимости проверки подлинности и код совместимости для проверки подлинности, чтобы реализовать преимущество размера приложения для проверки подлинности, прежде чем продолжить.
  5. Рефакторинг функций для каждого продукта (например, Cloud Firestore, FCM и т. д.) в модульном стиле, компиляция и тестирование, пока все области не будут завершены.
  6. Обновите код инициализации до модульного стиля.
  7. Удалите все оставшиеся операторы совместимости и код совместимости из своего приложения.

Получить последнюю версию SDK

Для начала получите модульные библиотеки и библиотеки совместимости с помощью npm:

npm i firebase@10.3.1

# OR

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

Рефакторинг в модульный стиль

В то время как API-интерфейсы с пространством имен основаны на точечной цепочке пространства имен и шаблоне службы, модульный подход означает, что ваш код будет организован главным образом вокруг функций . В модульном API пакет firebase/app и другие пакеты не возвращают полный экспорт, содержащий все методы из пакета. Вместо этого пакеты экспортируют отдельные функции.

В модульном API услуги передаются в качестве первого аргумента, а затем функция использует сведения о службе для выполнения остальных функций. Давайте рассмотрим, как это работает, на двух примерах, которые рефакторят вызовы API аутентификации и 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 , как это было бы в 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 пользователем.

До: совместимость

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 было изменено на метод . Функциональность по существу такая же (проверка существования документа), но вы должны реорганизовать свой код, чтобы использовать более новый метод, как показано ниже:

До: совместимость

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

После: модульный

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

Пример 3: сочетание стилей кода с пространством имен и модульным стилем

Использование совместимых библиотек во время обновления позволяет продолжать использовать код с пространством имен наряду с кодом, реорганизованным для модульного API. Это означает, что вы можете сохранить существующий код с пространством имен для Cloud Firestore во время рефакторинга аутентификации или другого кода SDK Firebase в модульный стиль и при этом успешно скомпилировать свое приложение с обоими стилями кода. То же самое верно для пространства имен и модульного кода 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() инициализирует глобальное состояние как для совместимого, так и для модульного API, тогда как модульная функция initializeApp() инициализирует только состояние для модульного.

До: совместимость

import firebase from "firebase/compat/app"

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

После: модульный

import { initializeApp } from "firebase/app"

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

Удалить код совместимости

Чтобы реализовать преимущества модульного API по размеру, вам следует в конечном итоге преобразовать все вызовы в модульный стиль, показанный выше, и удалить из кода все операторы import "firebase/compat/* . Когда вы закончите, ссылок больше не должно быть. в глобальное пространство имен firebase.* или любой другой код в стиле API с пространством имен.

Использование библиотеки совместимости из окна

Модульный API оптимизирован для работы с модулями, а не с объектом window браузера. Предыдущие версии библиотеки позволяли загружать и управлять Firebase с помощью пространства имен window.firebase . Это не рекомендуется в дальнейшем, поскольку это не позволяет исключить неиспользуемый код. Однако совместимая версия JavaScript SDK работает с window для разработчиков, которые предпочитают не сразу начинать путь модульного обновления.

<script src="https://www.gstatic.com/firebasejs/10.3.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.3.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.3.1/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, что позволяет использовать методы «дрожания дерева», когда вы импортируете только те артефакты, которые нужны вашему приложению. В зависимости от вашего приложения встряхивание дерева с модульным SDK может привести к уменьшению килобайт на 80 % по сравнению с сопоставимым приложением, созданным с использованием API с пространством имен.
  • Модульный SDK будет по-прежнему извлекать выгоду из постоянного развития функций, а API с пространством имен — нет.