Użyj wygenerowanych internetowych pakietów SDK

Pakiety SDK klienta Firebase Data Connect umożliwiają wywoływanie zapytań i mutacji po stronie serwera bezpośrednio z aplikacji 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 integrujesz metody z tego pakietu SDK z logiką klienta.

Jak już wspomnieliśmy, Data Connectzapytania i mutacje nie są przesyłane przez kod klienta ani wykonywane na serwerze. Zamiast tego po wdrożeniu operacje Data Connect są przechowywane na serwerze, podobnie jak w przypadku Cloud Functions. Oznacza to, że musisz wdrożyć odpowiednie zmiany po stronie klienta, aby nie zakłócać działania aplikacji 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 wdrożonych na serwerze. Podczas tworzenia prototypu automatycznie generuje też zestawy SDK po stronie klienta.

Gdy wprowadzisz aktualizacje w aplikacjach usługi i klienta, będzie można wdrożyć aktualizacje zarówno po stronie serwera, jak i po stronie klienta.

Zaimplementuj kod klienta za pomocą pakietu SDK Firebase JavaScript

W tej sekcji znajdziesz informacje o wdrażaniu klientów za pomocą pakietu SDK Firebase JavaScript.

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

Inicjowanie aplikacji

Najpierw zainicjuj aplikację za pomocą standardowej sekwencji Firebase.

initializeApp({...});

Generowanie pakietu JavaScript SDK

Podobnie jak w przypadku większości projektów Firebase, praca nad kodem klienta Firebase Data Connect odbywa się w lokalnym katalogu projektu. Zarówno rozszerzenie Data Connect w VS Code, jak i narzędzie wiersza poleceń Firebase są ważnymi lokalnymi narzędziami do generowania kodu klienta i zarządzania nim.

Opcje generowania pakietu SDK są powiązane z kilkoma wpisami w pliku dataconnect.yaml, który został wygenerowany podczas inicjowania projektu.

Inicjowanie generowania pakietu SDK

W konfiguracji connector.yaml dodaj swoje outputDir, package i (w przypadku pakietu SDK na potrzeby internetu) packageJsonDir. 
generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir określa, gdzie ma zostać wygenerowany pakiet SDK.

package określa nazwę pakietu.

packageJsonDir określa, gdzie zainstalować pakiet.

W takim przypadku zainstaluj firebase@latest, aby spełnić tę zależność od peera.

Inicjowanie pakietu JavaScript SDK

Zainicjuj instancję Data Connect, korzystając z informacji użytych do skonfigurowania usługi Data Connect (wszystkie dostępne w konsoli Firebase na karcie Data Connect).

Obiekt ConnectorConfig

Pakiet SDK wymaga obiektu konfiguracji łącznika.

Ten obiekt jest automatycznie generowany na podstawie elementów serviceId i location w dataconnect.yaml oraz elementu connectorId w connector.yaml.

Importowanie bibliotek

Do zainicjowania kodu klienta potrzebne są 2 zbiory importów: ogólne importy Data Connect i specyficzne, wygenerowane importy pakietu SDK.

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

// 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 '@myorg/myconnector';

Korzystanie z zapytań z pakietu JavaScript SDK

Wygenerowany kod będzie już zawierać wstępnie zdefiniowane odwołania do zapytania. Wystarczy je zaimportować i wykonać.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

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ótu działania:

import { listMovies } from '@movie-app/movies';
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 subskrybować 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`

Korzystanie z mutacji z pakietu SDK JavaScript

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

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

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 i przekazując instancję Data Connect, na przykład w ten sposób:

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name

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

// Make calls from your app

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

Implementacja kodu klienta dla React

Firebase Data Connect udostępnia wygenerowany pakiet SDK z elementami wywołania dla Reacta, korzystając z biblioteki dostępnej u naszych partnerów z Invertase, TanStack Query Firebase.

Ta biblioteka zawiera zestaw funkcji, które znacznie ułatwiają obsługę zadań asynchronicznych za pomocą Firebase w Twoich 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 na Firebase

zainstaluj w projekcie pakiety TanStack Query;

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

Generowanie pakietu React SDK

Podobnie jak w przypadku standardowego pakietu SDK do klienta internetowego, o którym pisaliśmy wcześniej, narzędzia Firebase automatycznie generują pakiety SDK na podstawie Twojego schematu i działań.

Aby wygenerować pakiet SDK Reacta dla projektu, dodaj klucz react do pliku konfiguracyjnego connector.yaml.

generate:
  javascriptSdk:
    react: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

Importowanie bibliotek

Do zainicjowania kodu klienta React potrzebne są 4 zbiory importów: ogólne importy Data Connect, ogólne importy TanStack oraz konkretne importy pakietów SDK wygenerowanych za pomocą JS i React.

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

// 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 '@myorg/myconnector';

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

Korzystanie z zapytań i mutacji w kliencie React

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

W tym fragmencie kodu zwróć uwagę na metodę useListAllMovies z prefiksem use z wygenerowanego pakietu React SDK. Wszystkie takie operacje use w wygenerowanym pakiecie SDK, zarówno zapytania, jak i mutacje, wywołują powiązania zapytań TanStack:

import { useListAllMovies } from '@movies-app/movies/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>
}

Połącz się z emulatorem Data Connect

Opcjonalnie możesz połączyć się z emulatorem, wywołując funkcję connectDataConnectEmulator, a potem przekazując instancję Data Connect do wygenerowanego haka, na przykład w ten sposób:

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

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

function App() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

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

Typy danych w pakiecie SDK

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

Typ Data Connect TypeScript
Sygnatura czasowa ciąg znaków
Data ciąg znaków
UUID ciąg znaków
Int64 ciąg znaków
Podwójne Liczba
Liczba zmiennoprzecinkowa Liczba

Specjalne uwagi dotyczące generowania pakietu SDK

Konfigurowanie ścieżek względem node_modules

W przypadku pakietu SDK JavaScript, ponieważ Data Connect używa npm link do zainstalowania pakietu SDK, wygenerowany pakiet SDK musi zostać zapisany w katalogu na tym samym poziomie co ścieżka node_modules lub w katalogu podrzędnym, który może uzyskać dostęp do node_modules.

Inaczej mówiąc, aby wygenerowany pakiet SDK działał prawidłowo, musi mieć dostęp do węzła firebase.

Jeśli na przykład node_modules znajduje się w my-app/, katalog wyjściowy powinien mieć nazwę my-app/js-email-generated, aby js-email-generated mógł zaimportować dane z folderu nadrzędnego node_modules.

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

Jeśli masz repozytorium mono, w którym moduły są hostowane w katalogu głównym, możesz umieścić katalog wyjściowy w dowolnym folderze w tym repozytorium.

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

Aktualizowanie pakietów SDK podczas prototypowania

Jeśli prototypowanie odbywa się interaktywnie za pomocą rozszerzenia Data Connect w VS Code i jego emulatora Data Connect, podczas modyfikowania plików .gql definiujących schematy, zapytania i mutacje, pliki źródłowe pakietu SDK są automatycznie generowane i aktualizowane. Może to być przydatna funkcja w przypadku procesów (ponownego) wczytywania na gorąco.

W innych przypadkach, jeśli używasz emulatora Data Connect z poziomu wiersza poleceń Firebase, możesz skonfigurować monitorowanie aktualizacji .gql, a także automatycznie aktualizować źródła pakietu SDK.

Możesz też użyć interfejsu wiersza poleceń, aby wygenerować pakiety SDK za każdym razem, gdy zmienisz pliki .gql:

firebase dataconnect:sdk:generate --watch

Generowanie pakietów SDK na potrzeby integracji i wersji produkcyjnych

W niektórych przypadkach, np. podczas przygotowywania źródeł projektu do przesłania na potrzeby testów CI, możesz wywołać interfejs wiersza poleceń Firebase w celu aktualizacji zbiorczej.

W takich przypadkach użyj firebase dataconnect:sdk:generate.

Inne kwestie dotyczące innych platform

Angular

Podczas generowania kodu Angular CLI nie uwzględni nowych zmian z powodu kodu optymalizacji zależności. Aby to naprawić, musisz zmodyfikować angular.json.

  "projects": {
    "myproject": {
      "architect": {
        "serve:": {
          "prebundle": {
            "exclude": ["@movie-app/movies"]
          }
        }
      }
    }
  }