Użyj wygenerowanych internetowych pakietów SDK

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

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.

Jaki jest proces tworzenia klienta?

Jeśli korzystasz z pomocy dla początkujących, zapoznałeś/zapoznałaś się z całym procesem tworzenia aplikacji Data Connect. W tym przewodniku znajdziesz szczegółowe informacje o generowaniu pakietów SDK na potrzeby sieci na podstawie schematu oraz o pracy z zapytaniami i mutacjami klienta.

Aby podsumować, aby używać wygenerowanych pakietów SDK dla sieci Web w aplikacjach klienckich, musisz wykonać te czynności wstępne:

1. Dodaj Firebase do aplikacji internetowej.

Następnie:

1. Utwórz schemat aplikacji.
2. Zainicjuj kod klienta za pomocą pakietu JavaScript SDK lub bibliotek React lub Angular.
3. W przypadku React i Angular zainstaluj pakiety zapytań Tanstack.

4. Konfigurowanie generowania pakietu SDK:

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

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

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

7. Przetestuj, konfigurując emulator Data Connect z pakietem SDK JavaScript lub React albo Angular.

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 lub Angular, zapoznaj się z alternatywnymi instrukcjami konfiguracji i linkami do dodatkowej dokumentacji na temat generowania pakietów SDK Data Connect dla frameworków.

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 wygenerowanym podczas inicjowania projektu.

Inicjowanie generowania pakietu SDK

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 Data Connect i konkretne, 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';

Używanie zapytań z pakietu JavaScript SDK

Wygenerowany kod będzie 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.

Wdrożenie kodu klienta w przypadku React i Angular

Firebase Data Connect udostępnia wygenerowany pakiet SDK z elementami wywołania dla React i Angular za pomocą bibliotek dostępnych u naszych partnerów z Invertase i 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

ng add @angular/fire

Generowanie pakietu SDK React lub Angular

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 React SDK dla projektu, dodaj klucz react do pliku konfiguracyjnego connector.yaml.

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

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

Importowanie bibliotek

Do zainicjowania kodu klienta w React lub Angular potrzebne są 4 zbiory importów: ogólne importy Data Connect, ogólne importy TanStack oraz specyficzne 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";

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

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

Korzystanie z zapytań i mutacji w kliencie React lub Angular

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

W tym fragmencie kodu zwróć uwagę na metodę useListAllMovies z prefiksem use w przypadku React i metodę injectListAllMovies z prefiksem inject w przypadku Angular, obie z wygenerowanego pakietu SDK.

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>
}

import { injectAllMovies, connectorConfig } from '@movies-app/movies/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;
  })
]

Automatyczne odświeżanie zapytań w React i Angular

Możesz skonfigurować zapytania tak, aby były automatycznie ponownie wczytywane 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 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);

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, 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:

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.

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, aby przeprowadzić aktualizację zbiorczą.

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