Usa gli SDK web generati

Firebase Data Connect SDK client 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 di cui esegui il deployment nel tuo Data Connect servizio. Poi, integri i metodi di questo SDK nella logica client.

Come abbiamo già detto, è importante notare che Data Connect query e mutazioni non vengono inviate dal codice client ed eseguite sul server. Quando viene eseguito il deployment, le operazioni Data Connect vengono archiviate su il server come Cloud Functions. Ciò significa che devi eseguire il deployment delle modifiche lato client corrispondenti per evitare di interrompere gli 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 creare prototipi di schemi, query e mutazioni di cui hai eseguito il deployment sul server. Genera anche automaticamente gli SDK lato client durante la creazione del prototipo.

Dopo aver eseguito l'iterazione degli aggiornamenti del servizio e delle app client, gli aggiornamenti lato server e lato client sono pronti per il deployment.

Che cos'è il flusso di lavoro di sviluppo client?

Se hai seguito la guida Inizia, hai scoperto 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 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 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 il tuo 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 i test configurando l'emulatore Data Connect con l' SDK JavaScript o React o Angular.

Implementare il codice client con l'SDK Firebase JavaScript

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

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

Inizializzare l'app

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

initializeApp({...});

Installare l'SDK JavaScript generato

Utilizza l'interfizza a riga di comando Firebase per configurare gli SDK Data Connect generati nelle tue app. Il comando init dovrebbe rilevare tutte le app nella cartella corrente e installare automaticamente gli SDK generati.

firebase init dataconnect:sdk

Collega l'app al servizio 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);

Aggiornare gli SDK durante la creazione del prototipo

Se hai installato l'estensione Data Connect VS Code, gli SDK generati saranno sempre aggiornati.

Se non utilizzi l'estensione Data Connect VS Code, puoi utilizzare l'interfaccia a riga di comando di Firebase per mantenere aggiornati gli SDK generati.

firebase dataconnect:sdk:generate --watch

Generare SDK nelle pipeline di build

Puoi utilizzare l'interfaccia a riga di comando di Firebase per generare Data Connect SDK nei processi di build CI/CD.

firebase dataconnect:sdk:generate

Importare le librerie

Sono necessari due set di importazioni per inizializzare il codice client: importazioni generali Data Connect e importazioni specifiche di SDK generati.

Tieni presente l'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 '@dataconnect/generated';

Utilizzare le query dall'SDK JavaScript

Il codice generato include già i riferimenti alle query predefiniti. Devi solo importarli e chiamare l'esecuzione.

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

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

Chiamare i metodi di query dell'SDK

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

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

Abbonarsi alle modifiche

Puoi abbonarti 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 supportati per l'enumerazione. Ad esempio, supponiamo che in un secondo momento nel ciclo di vita dell'applicazione tu decida 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 di cui è stato eseguito il deployment precedente potrebbero non funzionare.

Esempio di implementazione resiliente

Aggiungi sempre un ramo default a un'istuzione switch sui valori di enumerazione o un ramo else a un blocco if/else if rispetto ai valori di enumerazione. Questo non è applicato dal linguaggio JavaScript/TypeScript, ma è il modo per rendere robusto il codice client nel caso in cui vengano aggiunti nuovi valori di enumerazione.

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 dall'SDK JavaScript

Le mutazioni sono accessibili allo stesso modo delle query.

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

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'Data Connect istanza, come segue:

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

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

// Make calls from your app

Per passare alle risorse di produzione, inserisci come commento 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 dai 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({...});

Installare i pacchetti TanStack Query Firebase

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

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

Se hai appena aggiunto React o Angular al tuo progetto, esegui di nuovo firebase init dataconnect:sdk per riconfigurare gli SDK generati in modo da includere i binding del framework aggiuntivi.

Importare le librerie

Sono necessari quattro set di importazioni per inizializzare il codice client React o Angular: importazioni generali Data Connect, importazioni generali di TanStack, e importazioni specifiche per gli SDK generati 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 '@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";

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 dall'SDK generato.

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

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

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

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

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

Attivare la memorizzazione nella cache lato client

Data Connect ha una funzionalità di memorizzazione nella cache lato client facoltativa, che puoi attivare modificando il file connector.yaml. Quando questa funzionalità è attivata, gli SDK client generati memorizzano nella cache localmente le risposte alle query, il che può ridurre il numero di richieste di database effettuate dall'app e consente alle parti dell'app dipendenti dal database di funzionare quando la disponibilità della rete viene interrotta.

Per attivare la memorizzazione nella cache lato client, aggiungi una configurazione di memorizzazione nella cache client alla configurazione del connettore:

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

Questa configurazione ha due parametri, entrambi facoltativi:

• maxAge: l'età massima di una risposta memorizzata nella cache prima che l'SDK client recuperi i valori aggiornati. Esempi: "0", "30s", "1h30m".

  Il valore predefinito di maxAge è 0, il che significa che le risposte vengono memorizzate nella cache, ma l'SDK client recupererà sempre i valori aggiornati. I valori memorizzati nella cache verranno utilizzati solo quando CACHE_ONLY viene specificato in executeQuery() e il risultato iniziale restituito da subscribe().

• storage: l'SDK client può essere configurato per memorizzare nella cache le risposte in persistent storage o in memory. I risultati memorizzati nella cache in persistent storage verranno mantenuti dopo il riavvio dell'app. Negli SDK web è supportato solo memory storage.

Dopo aver aggiornato la configurazione della memorizzazione nella cache del connettore, rigenera gli SDK client e ricompila l'app. Una volta fatto, executeQuery() e subscribe() memorizzeranno nella cache le risposte e utilizzeranno i valori memorizzati nella cache in base alla policy configurata. In genere, questa operazione viene eseguita automaticamente, senza ulteriori interventi da parte tua. Tuttavia, tieni presente quanto segue:

• Il comportamento predefinito di executeQuery() è quello descritto sopra: se un risultato viene memorizzato nella cache per una query e il valore memorizzato nella cache non è più vecchio di maxAge, utilizza il valore memorizzato nella cache. Questo comportamento predefinito è chiamato policy PREFER_CACHE.

  Puoi anche specificare le singole chiamate a executeQuery() per pubblicare solo i valori memorizzati nella cache (CACHE_ONLY) o per recuperare incondizionatamente i valori aggiornati dal server (SERVER_ONLY).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• Quando chiami subscribe(), restituirà sempre immediatamente i contenuti memorizzati nella cache, se esistenti, indipendentemente dall'impostazione maxAge. Le chiamate successive a executeQuery() invieranno una notifica ai listener in base al valore maxAge configurato.

Tipi di dati nell'SDK

Il server Data Connect rappresenta i tipi di dati GraphQL comuni. Questi sono rappresentati nell'SDK come segue.

Aggiornare gli SDK durante la creazione del prototipo

Se hai installato l'estensione Data Connect VS Code, gli SDK generati saranno sempre aggiornati.

Se non utilizzi l'estensione Data Connect VS Code, puoi utilizzare l'interfaccia a riga di comando di Firebase per mantenere aggiornati gli SDK generati.

firebase dataconnect:sdk:generate --watch

Generare SDK nelle pipeline di build

Puoi utilizzare l'interfaccia a riga di comando di Firebase per generare Data Connect SDK nei processi di build CI/CD.

firebase dataconnect:sdk:generate