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 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 Connectzapytania i mutacje nie są przesyłane przez kod klienta i nie są 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 zapoznasz się z sekcją 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.

Możesz nauczyć się tworzenia aplikacji klienckich, korzystając z repozytorium aplikacji szybkiego startu, i zbudować w pełni funkcjonalną aplikację Data Connect, postępując zgodnie z naszymi ćwiczeniami z programowania dotyczącymi internetu.

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 SDK JavaScript 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 naszym rozszerzeniu Data Connect do VS Code
   • Aktualizując connector.yaml w przypadku pakietu SDK JavaScript lub React albo Angular.

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

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

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

Implementowanie kodu klienta za pomocą pakietu SDK Firebase JavaScript

W tej sekcji znajdziesz informacje o tym, jak wdrażać 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ę, korzystając z standardowej sekwencji Firebase.

initializeApp({...});

Generowanie pakietu JavaScript SDK

Podobnie jak w przypadku większości projektów Firebase, praca nad Firebase Data Connectkodem klienta odbywa się w lokalnym katalogu projektu. Zarówno rozszerzenie Data Connect VS Code, jak i Firebase CLI to ważne lokalne narzędzia do generowania kodu klienta i zarządzania nim.

Opcje generowania pakietu SDK są powiązane z kilkoma wpisami w dataconnect.yamlpliku wygenerowanym podczas inicjowania projektu.

Inicjowanie generowania pakietu SDK

W connector.yaml dodaj outputDir, package i (w przypadku pakietu SDK na potrzeby internetu) packageJsonDir.

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

outputDir określa miejsce, w którym ma zostać wygenerowany pakiet SDK.

package określa nazwę pakietu.

packageJsonDir określa miejsce instalacji pakietu.

Uwaga: podczas generowania dodajemy "firebase": "^10.14.0" jako peerDependency. W zależności od menedżera zależności (np. pnpm) te zależności mogą nie zostać zainstalowane automatycznie.

W takim przypadku zainstaluj firebase@latest, aby spełnić to wymaganie.

Inicjowanie pakietu JavaScript SDK

Zainicjuj instancję Data Connect, używając informacji, które zostały użyte do skonfigurowania funkcji Data Connect (wszystkie są dostępne w konsoli Firebase na karcie Data Connect).

Obiekt ConnectorConfig

Pakiet SDK wymaga obiektu konfiguracji łącznika.

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

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

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ć funkcję execute.

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ótów do działań:

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`

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 '@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 connectDataConnectEmulator i przekazując instancję Data Connect, jak w tym przykładzie:

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, zakomentuj wiersze służące do łączenia się z emulatorem.

Uwaga: wywołanie getDataConnect jest wymagane tylko wtedy, gdy chcesz połączyć się z emulatorem Data Connect. W przeciwnym razie wygenerowany pakiet SDK automatycznie utworzy instancję obiektu DataConnect.

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ę asynchronicznych zadań 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;

Dodaj reakcję

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

Angular

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 Twojego schematu i operacji.

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

Dodaj reakcję

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

Angular

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

Importowanie bibliotek

Do zainicjowania kodu klienta React lub Angular potrzebne są 4 zestawy importów: ogólne importy Data Connect, ogólne importy TanStack oraz importy specyficzne dla wygenerowanych pakietów SDK w JS i React.

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

Dodaj reakcję

// 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";

Angular

// 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";

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 useuseListAllMovies w przypadku Reacta i metodę z prefiksem injectinjectListAllMovies w przypadku Angulara. Obie pochodzą z wygenerowanego pakietu SDK.

Dodaj reakcję

Wszystkie operacje w wygenerowanym pakiecie SDK, zarówno zapytania, jak i mutacje, wywołują powiązania TanStack Query:

• Wysyła zapytania i zwraca hooka TanStack useDataConnectQuery.
• Wywołania mutacji i zwracanie haczyka TanStack useDataConnectMutation

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

Angular

Uwaga: ng add @angular/fire zrobi to za Ciebie automatycznie, ale jeśli chcesz skonfigurować to ustawienie ręcznie, możesz to zrobić za pomocą tego kodu:

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;
  })
]

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.

Dodaj reakcję

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

Angular

// 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, jak w tym przykładzie:

Dodaj reakcję

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);
  ...
}

Angular

// 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.

Uwaga: wywołanie getDataConnect jest wymagane tylko wtedy, gdy chcesz połączyć się z emulatorem Data Connect. W przeciwnym razie wygenerowany pakiet SDK automatycznie utworzy instancję obiektu DataConnect.

Typy danych w pakiecie SDK

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

Typ połączenia danych	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 instalowania pakietu SDK, wygenerowany pakiet SDK musi być zapisany w katalogu na tym samym poziomie co ścieżka node_modules lub w katalogu podrzędnym, który ma dostęp do node_modules.

Innymi słowy, wygenerowany pakiet SDK musi mieć dostęp do modułu węzła firebase, aby działać prawidłowo.

Jeśli na przykład plik node_modules znajduje się w folderze my-app/, katalog wyjściowy powinien mieć nazwę my-app/js-email-generated, aby plik js-email-generated mógł importować 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 monorepo, w którym moduły są hostowane w katalogu głównym, możesz umieścić katalog wyjściowy w dowolnym folderze w monorepo.

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

Uwaga: możesz podać bezwzględną ścieżkę do katalogów, jeśli projekt jest skonfigurowany w oddzielnej strukturze katalogów.

Aktualizowanie pakietów SDK podczas tworzenia prototypu

Jeśli tworzysz interaktywny prototyp za pomocą rozszerzenia Data Connect VS Code i jego Data Connect emulatora, pliki źródłowe pakietu SDK są automatycznie generowane i aktualizowane podczas modyfikowania plików .gql definiujących schematy, zapytania i mutacje. Może to być przydatna funkcja w przypadku procesów roboczych z szybkim ponownym wczytywaniem.

W innych przypadkach, jeśli używasz Data Connectemulatora z Firebase interfejsu CLI, możesz ustawić obserwowanie .gql aktualizacji, a także automatycznie aktualizować źródła pakietu SDK.

Możesz też użyć interfejsu wiersza poleceń, aby ponownie wygenerować pakiety SDK za każdym razem, gdy zmienią się 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 przeprowadzenia aktualizacji zbiorczej.

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