Usa gli SDK web generati

Gli SDK client Firebase Data Connect ti consentono di chiamare le query e le mutazioni lato server direttamente da un'app Firebase. Generi un SDK client personalizzato in parallelo alla progettazione degli schemi, delle query e delle mutazioni che implementi nel tuo servizio Data Connect. Poi, integra i metodi di questo SDK nella logica del client.

Come abbiamo già detto, è importante notare che Data Connect le query e le mutazioni non vengono inviate dal codice client ed eseguite sul server. Al contrario, una volta eseguito il deployment, le operazioni Data Connect vengono archiviate sul server come Cloud Functions. Ciò significa che devi implementare le modifiche lato client corrispondenti per evitare di interrompere l'esperienza degli utenti esistenti (ad esempio, nelle versioni precedenti dell'app).

Per questo motivo, Data Connect ti fornisce un ambiente di sviluppo e strumenti che ti consentono di prototipare schemi, query e mutazioni implementati sul server. Inoltre, genera automaticamente gli SDK lato client durante la prototipazione.

Una volta completati gli aggiornamenti iterativi del servizio e delle app client, gli aggiornamenti lato server e lato client sono pronti per il deployment.

Qual è il flusso di lavoro di sviluppo del client?

Se hai seguito la guida Inizia, hai appreso il flusso di sviluppo complessivo per Data Connect. In questa guida troverai informazioni più dettagliate sulla generazione di SDK web dallo schema e sull'utilizzo di query e mutazioni client.

Per riassumere, per utilizzare gli SDK web generati nelle tue app client, segui questi passaggi preliminari:

1. Aggiungi Firebase alla tua app web.

Quindi:

1. Sviluppa lo schema dell'app.
2. Inizializza il codice client con l'SDK JavaScript o con le librerie React o Angular.
3. Per React e Angular, installa i pacchetti Tanstack Query.

4. Configura la generazione dell'SDK:

   • Con il pulsante Aggiungi SDK all'app nella nostra estensione Data Connect VS Code
   • Aggiornando connector.yaml per l'SDK JavaScript o React o Angular.

5. Importa librerie e codice generato con l'SDK JavaScript o React o Angular.

6. Implementa le chiamate a query e mutazioni con l'SDK JavaScript, o React o Angular.

7. Esegui il test configurando l'emulatore Data Connect con l'SDK JavaScript o React o Angular.

Implementa il codice client con l'SDK Firebase JavaScript

Questa sezione illustra come implementare i client utilizzando l'SDK Firebase JavaScript.

Se utilizzi React o Angular, consulta le istruzioni di configurazione alternative e i link alla documentazione aggiuntiva sulla generazione di SDK Data Connect per i framework.

Inizializzare l'app

Innanzitutto, inizializza l'app utilizzando la sequenza Firebase standard.

initializeApp({...});

Genera l'SDK JavaScript

Come per la maggior parte dei progetti Firebase, il lavoro sul codice client Firebase Data Connect si svolge in una directory di progetto locale. Sia l'estensione VS Code Data Connect sia la CLI Firebase sono strumenti locali importanti per generare e gestire il codice client.

Le opzioni di generazione dell'SDK sono associate a diverse voci nel file dataconnect.yaml generato durante l'inizializzazione del progetto.

Inizializza la generazione dell'SDK

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

outputDir specifica la posizione in cui deve essere generato l'output dell'SDK.

package specifica il nome del pacchetto.

packageJsonDir specifica dove installare il pacchetto.

In questo caso, installa firebase@latest per assicurarti che questa dipendenza peer sia soddisfatta.

Inizializza l'SDK JavaScript

Inizializza l'istanza Data Connect utilizzando le informazioni che hai utilizzato per configurare Data Connect (tutte disponibili nella scheda Data Connect della console Firebase).

L'oggetto ConnectorConfig

L'SDK richiede un oggetto di configurazione del connettore.

Questo oggetto viene generato automaticamente da serviceId e location in dataconnect.yaml e connectorId in connector.yaml.

Importare librerie

Per inizializzare il codice client sono necessari due set di importazioni: le importazioni generali Data Connect e le importazioni specifiche dell'SDK generate.

Prendi nota dell'oggetto ConnectorConfig incluso nelle importazioni generali.

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

Utilizzare le query dell'SDK JavaScript

Il codice generato includerà già i riferimenti alle query predefiniti. Tutto ciò che devi fare è importare ed eseguire la chiamata.

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

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

Metodi di query dell'SDK di chiamata

Ecco un esempio di utilizzo di queste funzioni di scorciatoia per le azioni:

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

Iscriviti alle modifiche

Puoi iscriverti alle modifiche (che verranno aggiornate ogni volta che esegui una query).

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`

Gestire le modifiche ai campi di enumerazione

Lo schema di un'app può contenere enumerazioni, a cui è possibile accedere tramite le query GraphQL.

Man mano che il design di un'app cambia, puoi aggiungere nuovi valori enum supportati. Ad esempio, immagina che più avanti nel ciclo di vita della tua applicazione decidi di aggiungere un valore FULLSCREEN all'enumerazione AspectRatio.

Nel flusso di lavoro Data Connect, puoi utilizzare gli strumenti di sviluppo locali per aggiornare le query e gli SDK.

Tuttavia, prima di rilasciare una versione aggiornata dei client, i client meno recenti potrebbero non funzionare.

Esempio di implementazione resiliente

Aggiungi sempre un ramo default a un'istruzione switch rispetto ai valori enum oppure un ramo else a un blocco if/else if che esegue il confronto con i valori enum. Questo non è imposto dal linguaggio JavaScript/TypeScript, ma è il modo per rendere robusto il codice client nel caso in cui vengano aggiunti nuovi valori enum.

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

Utilizzare le mutazioni dell'SDK JavaScript

Le mutazioni sono accessibili allo stesso modo delle query.

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

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

Connettersi all'emulatore Data Connect

Se vuoi, puoi connetterti all'emulatore chiamando connectDataConnectEmulator e poi passando l'istanza Data Connect, come segue:

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

Per passare alle risorse di produzione, commenta le righe per la connessione all'emulatore.

Implementare il codice client per React e Angular

Firebase Data Connect fornisce un SDK generato con hook per React e Angular utilizzando le librerie disponibili presso i nostri partner di Invertase, TanStack Query Firebase.

Questa libreria fornisce un insieme di hook che semplificano notevolmente la gestione delle attività asincrone con Firebase nelle tue applicazioni.

Inizializzare l'app

Innanzitutto, come per qualsiasi app web Firebase, inizializza l'app utilizzando la sequenza Firebase standard.

initializeApp({...});

Installa i pacchetti Firebase di TanStack Query

installa i pacchetti per TanStack Query nel tuo progetto.

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

Genera l'SDK React o Angular

Come per l'SDK web standard, come descritto in precedenza, gli strumenti Firebase gestiscono la generazione automatica degli SDK in base allo schema e alle operazioni.

Per generare un SDK React per il tuo progetto, aggiungi una chiave react al file di configurazione 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: "../../"

Importare librerie

Per inizializzare il codice client React o Angular sono necessari quattro set di importazioni: importazioni Data Connect generali, importazioni TanStack generali e importazioni specifiche per gli SDK generati per JS e React.

Tieni presente il tipo ConnectorConfig incluso nelle importazioni generali.

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

Utilizzare query e mutazioni nel client React o Angular

Una volta completata la configurazione, puoi incorporare i metodi dell'SDK generato.

Nello snippet seguente, nota il metodo con prefisso use useListAllMovies per React e il metodo con prefisso inject injectListAllMovies per Angular, entrambi provenienti dall'SDK generato.

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

Utilizzare le query di ricaricamento automatico con React e Angular

Puoi configurare le query in modo che vengano ricaricate automaticamente quando i dati cambiano.

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

Connettersi all'emulatore Data Connect

(Facoltativo) Puoi connetterti all'emulatore chiamando connectDataConnectEmulator e poi passando l'istanza Data Connect all'hook generato, come segue:

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

Per passare alle risorse di produzione, commenta le righe per la connessione all'emulatore.

Tipi di dati nell'SDK

Il server Data Connect rappresenta i tipi di dati GraphQL comuni. Questi sono rappresentati nell'SDK nel seguente modo.

Considerazioni speciali per la generazione dell'SDK

Configura i percorsi relativi a node_modules

Per l'SDK JavaScript, poiché Data Connect utilizza npm link per installare l'SDK, l'SDK generato deve essere inviato a una directory allo stesso livello del percorso node_modules o in una directory secondaria che possa accedere a node_modules.

In altre parole, l'SDK generato deve avere accesso al modulo del nodo firebase per funzionare correttamente.

Ad esempio, se hai node_modules in my-app/, la directory di output deve essere my-app/js-email-generated in modo che js-email-generated possa importare dalla cartella principale 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"

In alternativa, se hai un monorepo in cui i moduli sono ospitati nella root, puoi inserire la directory di output in qualsiasi cartella del 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

Aggiornare gli SDK durante la prototipazione

Se prototipi in modo interattivo con l'estensione VS Code Data Connect e il relativo emulatore Data Connect, i file di origine dell'SDK vengono generati e aggiornati automaticamente mentre modifichi i file .gql che definiscono schemi, query e mutazioni. Può essere una funzionalità utile nei flussi di lavoro di ricaricamento a caldo.

In alternativa, puoi utilizzare la CLI per rigenerare gli SDK ogni volta che vengono modificati i file .gql:

firebase dataconnect:sdk:generate --watch

Generare SDK per l'integrazione e per le release di produzione

In alcuni scenari, ad esempio la preparazione delle origini del progetto da inviare per i test CI, puoi chiamare la CLI Firebase per un aggiornamento batch.

In questi casi, utilizza firebase dataconnect:sdk:generate.