Приложениям, которые в настоящее время используют любой веб-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», не используя библиотеки совместимости.
О процессе обновления
Каждый шаг процесса обновления ограничен таким образом, чтобы вы могли завершить редактирование исходного кода для своего приложения, а затем скомпилировать и запустить его без поломок. Итак, вот что вы будете делать, чтобы обновить приложение:
- Добавьте модульные библиотеки и совместимые библиотеки в свое приложение.
- Обновите операторы импорта в своем коде, чтобы они соответствовали.
- Рефакторинг кода отдельного продукта (например, Аутентификация) на модульный стиль.
- Необязательно: на этом этапе удалите библиотеку совместимости проверки подлинности и код совместимости для проверки подлинности, чтобы реализовать преимущество размера приложения для проверки подлинности, прежде чем продолжить.
- Рефакторинг функций для каждого продукта (например, Cloud Firestore, FCM и т. д.) в модульном стиле, компиляция и тестирование, пока все области не будут завершены.
- Обновите код инициализации до модульного стиля.
- Удалите все оставшиеся операторы совместимости и код совместимости из своего приложения.
Получить последнюю версию 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 с пространством имен — нет.