Użyj wygenerowanych internetowych pakietów SDK

Firebase Data Connect pakiety SDK klienta umożliwiają wywoływanie zapytań i mutacji po stronie serwera bezpośrednio z aplikacji w Firebase. Niestandardowy pakiet SDK klienta generujesz równolegle z projektowaniem schematów, zapytań i mutacji, które wdrażasz w usłudze Data Connect. Następnie zintegruj metody z tego pakietu SDK z logiką klienta.

Jak już wspominaliśmy, warto pamiętać, że Data Connect zapytania i mutacje nie są przesyłane przez kod klienta i wykonywane na serwerze. Zamiast tego po wdrożeniu operacje Data Connect są przechowywane na serwerze, tak jak Cloud Functions. Oznacza to, że musisz wdrożyć odpowiednie zmiany po stronie klienta, aby uniknąć problemów u dotychczasowych użytkowników (np. w starszych wersjach aplikacji).

Dlatego Data Connect udostępnia środowisko programistyczne i narzędzia, które umożliwiają tworzenie prototypów schematów, zapytań i mutacji wdrażanych na serwerze. Podczas tworzenia prototypu automatycznie generuje też pakiety SDK po stronie klienta.

Gdy wprowadzisz aktualizacje usługi i aplikacji klienckich, zarówno aktualizacje po stronie serwera, jak i po stronie klienta będą gotowe do wdrożenia.

Jak wygląda proces tworzenia aplikacji klienckiej?

Jeśli postępujesz zgodnie z instrukcjami w sekcji Pierwsze kroki, poznasz ogólny proces tworzenia aplikacji Data Connect. W tym przewodniku znajdziesz bardziej szczegółowe informacje o generowaniu internetowych pakietów SDK na podstawie schematu oraz o pracy z zapytaniami i mutacjami klienta.

Podsumowując, aby używać wygenerowanych pakietów Web SDK w aplikacjach klienckich, musisz wykonać te czynności wstępne:

1. Dodaj Firebase do aplikacji internetowej.

Następnie:

1. Opracuj schemat aplikacji.
2. Zainicjuj kod klienta za pomocą pakietu JavaScript SDK lub bibliotek React albo Angular.
3. W przypadku Reacta i Angulara zainstaluj pakiety Tanstack Query.

4. Skonfiguruj generowanie pakietu SDK:

   • Za pomocą przycisku Dodaj pakiet SDK do aplikacji w rozszerzeniu Data Connect VS Code
   • Aktualizując connector.yaml w przypadku pakietu JavaScript SDK lub React albo Angular.

5. Importuj biblioteki i wygenerowany kod za pomocą pakietu JavaScript SDK lub React albo Angular.

6. Zaimplementuj wywołania zapytań i mutacji za pomocą pakietu JavaScript SDK, React lub Angular.

7. Przeprowadź test, konfigurując Data Connect emulator za pomocą pakietu JavaScript SDK, React lub Angular.

Implementowanie kodu klienta za pomocą pakietu SDK Firebase JavaScript

W tej sekcji znajdziesz informacje o tym, jak implementować klientów za pomocą pakietu SDK Firebase JavaScript.

Jeśli używasz Reacta lub Angulara, zapoznaj się z alternatywnymi instrukcjami konfiguracji i linkami do dodatkowej dokumentacji na temat generowania pakietów SDK Data Connect dla platform.

Inicjowanie aplikacji

Najpierw zainicjuj aplikację za pomocą standardowej sekwencji Firebase.

initializeApp({...});

Instalowanie wygenerowanego pakietu JavaScript SDK

Użyj interfejsu wiersza poleceń Firebase, aby skonfigurować w aplikacjach wygenerowane pakiety SDK Data Connect. Polecenie init powinno wykryć wszystkie aplikacje w bieżącym folderze i automatycznie zainstalować wygenerowane pakiety SDK.

firebase init dataconnect:sdk

Połącz aplikację z usługą Data Connect.

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

Aktualizowanie pakietów SDK podczas tworzenia prototypu

Jeśli masz zainstalowane rozszerzenie Data Connect VS Code, będzie ono zawsze aktualizować wygenerowane pakiety SDK.

Jeśli nie używasz rozszerzenia Data Connect VS Code, możesz użyć wiersza poleceń Firebase, aby aktualizować wygenerowane pakiety SDK.

firebase dataconnect:sdk:generate --watch

Generowanie pakietów SDK w potokach kompilacji

Za pomocą wiersza poleceń Firebase możesz generować Data Connect pakiety SDK w procesach kompilacji CI/CD.

firebase dataconnect:sdk:generate

Importowanie bibliotek

Do zainicjowania kodu klienta potrzebne są 2 zestawy importów: ogólne importyData Connect i konkretne, wygenerowane importy pakietu SDK.

Zwróć uwagę na obiekt ConnectorConfig uwzględniony w ogólnych importach.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@dataconnect/generated';

Używanie zapytań z pakietu JavaScript SDK

Wygenerowany kod będzie już zawierać wstępnie zdefiniowane odwołania do zapytań. Wystarczy je zaimportować i wywołać.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

Wywoływanie metod zapytań pakietu SDK

Oto przykład użycia tych funkcji skrótów do działań:

import { listMovies } from '@dataconnect/generated';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
  listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

Subskrybowanie zmian

Możesz zasubskrybować zmiany (które będą aktualizowane za każdym razem, gdy wykonasz zapytanie).

const listRef = listAllMoviesRef();

// subscribe will immediately invoke the query if no execute was called on it previously.
subscribe(listRef, ({ data }) => {
 updateUIWithMovies(data.movies);
});

await createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi", rating: 5 });\
await listMovies(); // will update the subscription above`

Obsługa zmian w polach wyliczeniowych

Schemat aplikacji może zawierać wyliczenia, do których można uzyskać dostęp za pomocą zapytań GraphQL.

W miarę zmian w projekcie aplikacji możesz dodawać nowe obsługiwane wartości wyliczeniowe. Załóżmy na przykład, że w późniejszym okresie cyklu życia aplikacji zdecydujesz się dodać wartość FULLSCREEN do wyliczenia AspectRatio.

W przypadku Data Connect możesz używać lokalnych narzędzi programistycznych do aktualizowania zapytań i pakietów SDK.

Zanim jednak udostępnisz zaktualizowaną wersję klientów, starsi wdrożeni klienci mogą przestać działać.

Przykład odpornej implementacji

Zawsze dodawaj gałąź default do instrukcji switch w przypadku wartości typu wyliczeniowego lub gałąź else do bloku if/else if porównującego wartości typu wyliczeniowego. Nie jest to wymuszane przez język JavaScript/TypeScript, ale jest to sposób na zwiększenie niezawodności kodu klienta w przypadku dodania nowych wartości wyliczeniowych.

const queryResult = await getOldestMovie();

if (queryResult.data) {
  // we can use a switch statement's "default" case to check for unexpected values
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
      case AspectRatio.ANAMORPHIC:
        console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
        break;
      default:
        // the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
        // it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
        console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
        break;
  }

  // alternatively, we can check to see if the returned enum value is a known value
  if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
    console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
  }
} else {
  console.log("no movies found!");
}

Używanie mutacji z pakietu JavaScript SDK

Mutacje są dostępne w taki sam sposób jak zapytania.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

Połącz się z emulatorem Data Connect

Opcjonalnie możesz połączyć się z emulatorem, wywołując funkcję connectDataConnectEmulator, a następnie przekazując instancję Data Connect w ten sposób:

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

Aby przełączyć się na zasoby produkcyjne, zakomentuj wiersze służące do łączenia się z emulatorem.

Implementowanie kodu klienta dla platform React i Angular

Firebase Data Connect udostępnia wygenerowany pakiet SDK z hakami dla Reacta i Angulara, korzystając z bibliotek dostępnych u naszych partnerów z Invertase, TanStack Query Firebase.

Ta biblioteka zawiera zestaw hooków, które znacznie ułatwiają obsługę zadań asynchronicznych w Firebase w aplikacjach.

Inicjowanie aplikacji

Najpierw, tak jak w przypadku każdej aplikacji internetowej Firebase, zainicjuj aplikację za pomocą standardowej sekwencji Firebase.

initializeApp({...});

Instalowanie pakietów TanStack Query Firebase

zainstalować pakiety TanStack Query w projekcie;

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

ng add @angular/fire

Generowanie pakietu SDK React lub Angular

Podobnie jak w przypadku standardowego pakietu SDK do klienta internetowego, o czym pisaliśmy wcześniej, narzędzia Firebase automatycznie generują pakiety SDK na podstawie schematu i operacji.

Jeśli dopiero co dodano do projektu React lub Angular, ponownie uruchom polecenie firebase init dataconnect:sdk, aby ponownie skonfigurować wygenerowane pakiety SDK i uwzględnić dodatkowe powiązania z platformą.

Importowanie bibliotek

Aby zainicjować kod klienta React lub Angular, potrzebujesz 4 zestawów importów: ogólnych importów Data Connect, ogólnych importów TanStack oraz importów specyficznych dla wygenerowanych pakietów SDK w JS i React.

Zwróć uwagę na typ ConnectorConfig uwzględniony w ogólnych importach.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/react";

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@dataconnect/generated/angular";

Używanie zapytań i mutacji w kliencie React lub Angular

Po zakończeniu konfiguracji możesz włączyć metody z wygenerowanego pakietu SDK.

W poniższym fragmencie kodu zwróć uwagę na metodę z prefiksem use useListAllMovies dla Reacta i metodę z prefiksem inject injectListAllMovies dla Angulara, które pochodzą z wygenerowanego pakietu SDK.

import { useListAllMovies } from '@dataconnect/generated/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
  const queryClient = new QueryClient();
  return <QueryClientProvider client={queryClient}>
    <MyComponent />
  </QueryClientProvider>
}

import { injectAllMovies, connectorConfig } from '@dataconnect/generated/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

Używanie zapytań z automatycznym ponownym wczytywaniem w React i Angular

Możesz skonfigurować zapytania tak, aby automatycznie przeładowywały się po zmianie danych.

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause Tanstack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

Połącz się z emulatorem Data Connect

Opcjonalnie możesz połączyć się z emulatorem, wywołując funkcję connectDataConnectEmulator, a następnie przekazując do wygenerowanego haka instancję Data Connect, np. tak:

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListAllMovies } from '@dataconnect/generated/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

Aby przełączyć się na zasoby produkcyjne, zakomentuj wiersze służące do łączenia się z emulatorem.

Włączanie zapisywania w pamięci podręcznej po stronie klienta

Data Connect ma opcjonalną funkcję buforowania po stronie klienta, którą możesz włączyć, edytując plik connector.yaml. Gdy ta funkcja jest włączona, wygenerowane pakiety SDK do klienta lokalnie buforują odpowiedzi na zapytania, co może zmniejszyć liczbę żądań bazy danych wysyłanych przez aplikację i umożliwić działanie części aplikacji zależnych od bazy danych w przypadku przerw w dostępie do sieci.

Aby włączyć buforowanie po stronie klienta, dodaj konfigurację buforowania po stronie klienta do konfiguracji łącznika:

generate:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory

Ta konfiguracja ma 2 parametry, które są opcjonalne:

• maxAge: maksymalny wiek buforowanej odpowiedzi, po którym pakiet SDK klienta pobiera nowe wartości. Przykłady: „0”, „30s”, „1h30m”.

  Domyślna wartość parametru maxAge to 0, co oznacza, że odpowiedzi są buforowane, ale pakiet SDK klienta zawsze pobiera nowe wartości. Wartości z pamięci podręcznej będą używane tylko wtedy, gdy parametr CACHE_ONLY ma wartość executeQuery(), a początkowy wynik został zwrócony przez subscribe().

• storage: Pakiet SDK klienta można skonfigurować tak, aby buforował odpowiedzi w pamięci persistent lub w memory. Wyniki zapisane w pamięci podręcznej persistent będą dostępne po ponownym uruchomieniu aplikacji. W pakietach SDK na potrzeby internetu obsługiwany jest tylko rodzaj pamięci memory.

Po zaktualizowaniu konfiguracji buforowania oprogramowania sprzęgającego wygeneruj ponownie pakiety SDK klienta i przebuduj aplikację. Gdy to zrobisz, executeQuery() i subscribe() będą buforować odpowiedzi i używać wartości z pamięci podręcznej zgodnie ze skonfigurowanymi zasadami. Zwykle odbywa się to automatycznie, bez żadnych dodatkowych działań z Twojej strony. Pamiętaj jednak o tych kwestiach:

• Domyślne działanie funkcji executeQuery() jest opisane powyżej: jeśli wynik jest zapisany w pamięci podręcznej dla zapytania, a wartość w pamięci podręcznej nie jest starsza niż maxAge, użyj wartości z pamięci podręcznej. To domyślne działanie jest nazywane zasadą PREFER_CACHE.

  Możesz też określić, że poszczególne wywołania funkcji executeQuery() mają zwracać tylko wartości z pamięci podręcznej (CACHE_ONLY) lub bezwarunkowo pobierać nowe wartości z serwera (SERVER_ONLY).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• Gdy wywołasz funkcję subscribe(), zawsze natychmiast zwróci ona buforowaną treść, jeśli istnieje, niezależnie od ustawienia maxAge. Kolejne wywołania funkcji executeQuery() będą powiadamiać słuchaczy zgodnie ze skonfigurowanym maxAge.

Typy danych w pakiecie SDK

Data Connect serwer reprezentuje typowe typy danych GraphQL. W pakiecie SDK są one reprezentowane w ten sposób:

Aktualizowanie pakietów SDK podczas tworzenia prototypu

Jeśli masz zainstalowane rozszerzenie Data Connect VS Code, będzie ono zawsze aktualizować wygenerowane pakiety SDK.

Jeśli nie używasz rozszerzenia Data Connect VS Code, możesz użyć wiersza poleceń Firebase, aby aktualizować wygenerowane pakiety SDK.

firebase dataconnect:sdk:generate --watch

Generowanie pakietów SDK w potokach kompilacji

Za pomocą wiersza poleceń Firebase możesz generować Data Connect pakiety SDK w procesach kompilacji CI/CD.

firebase dataconnect:sdk:generate