Przejście z interfejsu API z nazwą przestrzeni nazw na aplikację modułową

Aplikacje korzystające z dowolnego interfejsu Firebase Web API w przestrzeni nazw, z bibliotek compat wstecznie do wersji 8 lub starszej, powinny rozważyć migrację do Modular API zgodnie z instrukcjami w tym przewodniku.

Ten przewodnik zakłada że znasz Namespaced API i że do uaktualnienia oraz dalszego tworzenia aplikacji modułowych będziesz używać usługi tworzenia pakietów modułów, takiej jak webpack lub Rollup.

Zdecydowanie zalecamy używanie usługi tworzenia pakietów modułów w środowisku programistycznym. Jeśli nie będziesz jej używać, nie będziesz mieć możliwości korzystania z głównych zalet modułowego interfejsu API, czyli mniejszego rozmiaru aplikacji. Do zainstalowania pakietu SDK będziesz potrzebować npm lub yarn.

Kroki uaktualnienia opisane w tym przewodniku będą oparte na fikcyjnej aplikacji internetowej, która korzysta z pakietów SDK Authentication i Cloud Firestore. Dzięki pracy z przykładami możesz opanować koncepcje i praktyczne kroki wymagane do uaktualnienia wszystkich obsługiwanych pakietów Firebase Web SDK.

Informacje o bibliotekach w przestrzeni nazw (compat)

Dostępne są 2 typy bibliotek dla pakietu Firebase Web SDK:

• Modułowe – nowy interfejs API zaprojektowany tak, aby ułatwić usuwanie nieużywanego kodu (tree-shaking) i sprawić, że aplikacja internetowa będzie jak najmniejsza i najszybsza.
• W przestrzeni nazw (compat) – znany interfejs API, który jest w pełni zgodny z wcześniejszymi wersjami pakietu SDK, co pozwala na uaktualnienie bez konieczności jednoczesnej zmiany całego kodu Firebase. Biblioteki Compat nie mają żadnych lub prawie żadnych zalet w zakresie rozmiaru i wydajności w porównaniu z ich odpowiednikami w przestrzeni nazw.

Ten przewodnik zakłada, że do ułatwienia uaktualnienia będziesz używać bibliotek Compat. Te biblioteki umożliwiają dalsze używanie kodu w przestrzeni nazw obok kodu refaktoryzowanego pod kątem Modular API. Oznacza to, że podczas procesu uaktualniania możesz łatwiej kompilować i debugować aplikację.

Pamiętaj: biblioteki Compat są rozwiązaniem tymczasowym, które zostanie całkowicie usunięte w przyszłej głównej wersji pakietu SDK (np. w wersji 10 lub 11). Twoim ostatecznym celem jest usunięcie kodu Compat i pozostawienie w aplikacji tylko kodu w stylu modułowym.

W przypadku aplikacji, które w niewielkim stopniu korzystają z pakietu Firebase Web SDK (np. aplikacji, która wykonuje tylko proste wywołanie interfejsów Authentication API), refaktoryzacja starszego kodu w przestrzeni nazw bez użycia bibliotek Compat może być praktyczna. Jeśli uaktualniasz taką aplikację, możesz postępować zgodnie z instrukcjami w tym przewodniku dotyczącymi „Modular API” bez użycia bibliotek Compat.

Informacje o procesie uaktualniania

Każdy etap procesu uaktualniania jest tak skonstruowany, aby można było zakończyć edytowanie kodu źródłowego aplikacji, a następnie skompilować i uruchomić ją bez żadnych problemów. Podsumowując, aby uaktualnić aplikację, wykonaj te czynności:

1. Dodaj do aplikacji biblioteki modułowe i biblioteki Compat.
2. Zaktualizuj instrukcje importu w kodzie do Compat.
3. Refaktoryzuj kod jednego produktu (np. Authentication) do stylu modułowego.
4. Opcjonalnie: w tym momencie usuń bibliotekę Authentication Compat i kod Compat dla Authentication, aby przed kontynuowaniem skorzystać z zalet mniejszego rozmiaru aplikacji w przypadku Authentication.
5. Refaktoryzuj funkcje każdego produktu (np. Cloud Firestore, FCM, itp.) do stylu modułowego, kompilując i testując, aż wszystkie obszary zostaną ukończone.
6. Zaktualizuj kod inicjujący do stylu modułowego.
7. Usuń z aplikacji wszystkie pozostałe instrukcje Compat i kod Compat.

Pobierz najnowszą wersję pakietu SDK

Aby rozpocząć, pobierz biblioteki modułowe i biblioteki Compat za pomocą npm:

npm i firebase@12.12.0

# OR

yarn add firebase@12.12.0

Zaktualizuj importy do Compat

Aby kod działał po zaktualizowaniu zależności, zmień instrukcje importu tak, aby używały wersji „compat” każdego importu. Przykład:

Wcześniej: wersja 8 lub starsza

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

Potem: Compat

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

Refaktoryzuj do stylu modułowego

Interfejsy API w przestrzeni nazw są oparte na wzorcu przestrzeni nazw i usługi połączonych kropkami, natomiast podejście modułowe oznacza, że kod będzie zorganizowany głównie wokół funkcji. W modułowym interfejsie API pakiet firebase/app i inne pakiety nie zwracają kompleksowego eksportu, który zawiera wszystkie metody z pakietu. Zamiast tego pakiety eksportują poszczególne funkcje.

W Modular API usługi są przekazywane jako pierwszy argument, a funkcja używa szczegółów usługi do wykonania pozostałych czynności. Zobaczmy, jak to działa na 2 przykładach, które refaktoryzują wywołania interfejsów Authentication i Cloud Firestore API.

Przykład 1. Refaktoryzacja funkcji Authentication

Wcześniej: Compat

Kod Compat jest identyczny z kodem w przestrzeni nazw, ale importy uległy zmianie.

import firebase from "firebase/compat/app";
import "firebase/compat/auth";

const auth = firebase.auth();
auth.onAut>hStateChanged(user = { 
  // Check for user status
});

Potem: modułowy

Funkcja getAuth przyjmuje firebaseApp jako pierwszy parametr. Funkcja onAuthStateChanged nie jest połączona z instancją auth, jak w przypadku Namespaced API. Jest to funkcja wolna, która przyjmuje auth jako pierwszy parametr.

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

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

Zaktualizuj obsługę metody Auth getRedirectResult

Uwaga: jeśli Twoja aplikacja używa metody Auth getRedirectResult, musisz wprowadzić zmiany opisane w tej sekcji. Nieprzeprowadzenie refaktoryzacji kodu może spowodować nieprzewidywalne działanie aplikacji.

Modular API wprowadza zmianę powodującą niezgodność wsteczną w getRedirectResult. Gdy nie jest wywoływana żadna operacja przekierowania, Modular API zwraca wartość null w przeciwieństwie do Namespaced API, który zwracał UserCredential z użytkownikiem null.

Wcześniej: Compat

const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
  return null;
}
return result;

Potem: modułowy

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;

Przykład 2. Refaktoryzacja funkcji Cloud Firestore

Wcześniej: Compat

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 snaps>hots
            console.log(doc.id, " = ", do>c.data());
        });
    })
    .catch((error) = {
        console.log("Error getting documents: ", error);
    });

Potem: modułowy

Funkcja getFirestore przyjmuje firebaseApp jako pierwszy parametr, który został zwrócony przez initializeApp w poprzednim przykładzie. Zwróć uwagę, jak bardzo różni się kod tworzący zapytanie w Modular API. Nie ma łańcuchów, a metody takie jak query czy where są teraz udostępniane jako funkcje wolne.

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 g>etDocs(q);
querySnapshot.forEach((doc) = {
  // doc.data() is never undefined for query> doc snapshots
  console.log(doc.id, " = ", doc.data());
});

Zaktualizuj odwołania do Firestore DocumentSnapshot.exists

Uwaga: jeśli Twoja aplikacja używa właściwości DocumentSnapshot.exists, musisz przeprowadzić aktualizację opisaną w tej sekcji. Nieprzeprowadzenie refaktoryzacji kodu może spowodować nieprzewidywalne działanie aplikacji.

Modular API wprowadza zmianę powodującą niezgodność wsteczną, w której właściwość firestore.DocumentSnapshot.exists została zmieniona na metodę. Funkcja jest zasadniczo taka sama (sprawdzanie, czy dokument istnieje), ale musisz refaktoryzować kod, aby używać nowszej metody, jak pokazano poniżej:

Wcześniej:Compat

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

Potem: modułowy

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

Przykład 3. Łączenie stylów kodu w przestrzeni nazw i modułowego

Używanie bibliotek Compat podczas uaktualniania umożliwia dalsze używanie kodu w przestrzeni nazw obok kodu refaktoryzowanego pod kątem Modular API. Oznacza to, że możesz zachować istniejący kod w przestrzeni nazw dla Cloud Firestore refaktoryzując Authentication lub innego pakietu Firebase SDK do stylu modułowego, i nadal kompilować aplikację z oboma stylami kodu. To samo dotyczy kodu Modular API w przestrzeni nazw i modułowego w obrębie produktu, takiego jak Cloud Firestore. Nowe i stare style kodu mogą współistnieć, o ile importujesz pakiety Compat:

import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'

const docRef = firebase.firestore().doc();
getDoc(docRef);

Pamiętaj, że chociaż aplikacja będzie się kompilować, nie uzyskasz korzyści z mniejszego rozmiaru aplikacji, dopóki całkowicie nie usuniesz z niej instrukcji i kodu Compat.

Zaktualizuj kod inicjujący

Zaktualizuj kod inicjujący aplikację, aby używać składni modułowej. Ważne jest , aby zaktualizować ten kod po zakończeniu refaktoryzacji całego kodu w aplikacji. Dzieje się tak, ponieważ firebase.initializeApp() inicjuje stan globalny zarówno dla interfejsów Compat, jak i modułowych, natomiast funkcja modułowa initializeApp() inicjuje tylko stan modułowy.

Wcześniej: Compat

import firebase from "firebase/compat/app"

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

Potem: modułowy

import { initializeApp } from "firebase/app"

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

Usuń kod Compat

Aby skorzystać z zalet Modular API w zakresie rozmiaru, musisz ostatecznie przekonwertować wszystkie wywołania do stylu modułowego pokazanego powyżej i usunąć z kodu wszystkie instrukcje import "firebase/compat/*. Po zakończeniu nie powinno być już żadnych odwołań do globalnej przestrzeni nazw firebase.* ani żadnego innego kodu w stylu Namespaced API.

Używanie biblioteki Compat z okna

Modułowy interfejs API jest zoptymalizowany do współpracy z modułami, a nie z obiektem window przeglądarki. Wcześniejsze wersje biblioteki umożliwiały wczytywanie i zarządzanie Firebase za pomocą przestrzeni nazw window.firebase. Nie zalecamy tego, ponieważ nie pozwala to na eliminowanie nieużywanego kodu. Jednak wersja Compat pakietu JavaScript SDK działa z window w przypadku deweloperów, którzy wolą nie rozpoczynać od razu ścieżki uaktualniania modułowego.

<script src="https://www.gstatic.com/firebasejs/12.12.0/firebase-app-compa><t.js&qu>o<t;/script
script src="https://www.gstatic.com/firebasejs/12.12.0/firebase-fires><tore-co>m<pat.js"/script
script src="https://www.gstatic.com/firebasejs/12.12.0></fireba>s<e-auth>-compat.js"/script
script
   const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
   const db = firebaseApp.firestore();
   con<st auth> = firebaseApp.auth();
/script

Biblioteka zgodności używa pod spodem kodu modułowego i udostępnia go za pomocą tego samego interfejsu API co Namespaced API. Oznacza to, że szczegóły znajdziesz w dokumentacji Namespaced API i fragmentach kodu Namespaced API. Ta metoda nie jest zalecana do długotrwałego użytku, ale może być dobrym początkiem uaktualnienia do w pełni modułowej biblioteki.

Zalety i ograniczenia modułowego pakietu SDK

W pełni modułowy pakiet SDK ma te zalety w porównaniu z wcześniejszymi wersjami:

• Modułowy pakiet SDK umożliwia znaczne zmniejszenie rozmiaru aplikacji. Przyjmuje nowoczesny format modułu JavaScript, co pozwala na stosowanie praktyk „usuwania nieużywanego kodu”, w których importujesz tylko te artefakty, których potrzebuje Twoja aplikacja. W zależności od aplikacji usuwanie nieużywanego kodu za pomocą modułowego pakietu SDK może zmniejszyć rozmiar aplikacji o 80% w porównaniu z podobną aplikacją utworzoną za pomocą Namespaced API.
• Modułowy pakiet SDK będzie nadal korzystać z rozwoju funkcji, natomiast Namespaced API nie będzie.