Usa gli SDK web generati

Gli SDK client Firebase SQL Connect ti consentono di chiamare le query e le mutazioni lato server direttamente da un'app Firebase. Generi un SDK client personalizzato in parallelo mentre progetti gli schemi, le query e le mutazioni di cui esegui il deployment nel tuo servizio SQL Connect. Poi, integra i metodi di questo SDK nella logica del client.

Come abbiamo già accennato, è importante notare che le query e le mutazioni di SQL Connect non vengono inviate dal codice client ed eseguite sul server. Invece, quando viene eseguito il deployment, le operazioni SQL 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).

Ecco perché SQL Connect ti fornisce un ambiente di sviluppo e strumenti che ti consentono di creare prototipi di schemi, query e mutazioni di cui è stato eseguito il deployment sul server. Inoltre, genera automaticamente gli SDK lato client durante la prototipazione.

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

Qual è il flusso di lavoro per lo sviluppo del client?

Se hai seguito la guida introduttiva, hai conosciuto il flusso di sviluppo generale per SQL Connect. In questa guida troverai informazioni più dettagliate sulla generazione di SDK web dal tuo schema e sull'utilizzo di query e mutazioni client.

Puoi imparare lo sviluppo client con un repository di app di avvio rapido e creare un'app SQL Connect completa seguendo il nostro codelab per il web.

In sintesi, per utilizzare gli SDK web generati nelle tue app client, devi seguire 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.
3. Configura la generazione dell'SDK:
   • Con il pulsante Aggiungi SDK all'app nell'estensione VS Code di SQL Connect.
   • Aggiornando connector.yaml per l'SDK JavaScript.
4. Importa le librerie e il codice generato con l'SDK JavaScript.
5. Implementa le chiamate a query e mutazioni con l'SDK JavaScript.
6. Esegui un test configurando l'emulatore SQL Connect con l'SDK JavaScript.

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 SQL Connect per i framework.

Inizializza l'app

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

initializeApp({...});

Installa l'SDK JavaScript generato

Utilizza l'interfaccia a riga di comando Firebase per configurare gli SDK generati da SQL Connect 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 la tua app al servizio SQL 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);

Aggiorna gli SDK durante la prototipazione

Se hai installato l'estensione VS Code di SQL Connect, gli SDK generati verranno sempre mantenuti aggiornati.

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

firebase dataconnect:sdk:generate --watch

Genera SDK nelle pipeline di build

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

firebase dataconnect:sdk:generate

Importa le librerie

Per inizializzare il codice client sono necessari due set di importazioni: importazioni generali di SQL Connect e importazioni SDK specifiche generate.

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

Nota: gli SDK client JavaScript generati utilizzano gli stessi nomi per le interfacce e le operazioni degli SDK Admin Node.js generati. Assicurati di importare la libreria corretta per la tua piattaforma. Se devi utilizzare entrambe le librerie nello stesso file, utilizza un alias di importazione o un'importazione con spazio dei nomi per una o entrambe le librerie.

import { listMovies as adminListMovies } from '@dataconnect/admin-generated';
Oppure:
import * as Admin from '@dataconnect/admin-generated';

Utilizza le query dell'SDK JavaScript

Il codice generato includerà già i riferimenti alle query predefiniti. Tutto ciò che devi fare è importarli e chiamare execute.

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

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

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

Iscriviti alle modifiche

Consulta Ricevi aggiornamenti in tempo reale da SQL Connect.

Gestisci le modifiche ai campi di enumerazione

Lo schema di un'app può contenere enumerazioni, a cui possono accedere le tue query GraphQL.

Man mano che il design di un'app cambia, puoi aggiungere nuovi valori supportati per l'enum. Ad esempio, immagina che in un secondo momento del ciclo di vita della tua applicazione decidi di aggiungere un valore FULLSCREEN all'enum AspectRatio.

Nel workflow di SQL Connect, puoi utilizzare gli strumenti per sviluppatori 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 in precedenza potrebbero non funzionare.

Esempio di implementazione resiliente

Aggiungi sempre un ramo default a un'istruzione switch sui valori enum o 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 il codice client efficace 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!");
}

Utilizza le mutazioni dell'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' }));

Connettiti all'emulatore SQL Connect

Facoltativamente, puoi connetterti all'emulatore chiamando connectDataConnectEmulator e poi passando l'istanza SQL Connect, in questo modo:

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, commenta le righe per la connessione all'emulatore.

Nota: la chiamata a getDataConnect è necessaria solo se vuoi connetterti all'emulatore SQL Connect. In caso contrario, l'SDK generato creerà automaticamente un'istanza dell'oggetto DataConnect per te.

Abilita la memorizzazione nella cache lato client

SQL Connect ha una funzionalità di memorizzazione nella cache lato client facoltativa, che puoi attivare modificando il file connector.yaml. Quando questa funzionalità è attiva, gli SDK client generati memorizzano nella cache locale le risposte alle query, il che può ridurre il numero di richieste al database effettuate dalla tua app e consentire il funzionamento delle parti dell'app che dipendono dal database quando la disponibilità della rete viene interrotta.

Per abilitare la memorizzazione nella cache lato client, aggiungi una configurazione di memorizzazione nella cache del 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 che può avere una risposta memorizzata nella cache prima che l'SDK client recuperi i valori aggiornati. Esempi: "0", "30s", "1h30m".

  Il valore predefinito per 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 è specificato su executeQuery() e il risultato iniziale restituito da subscribe().

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

Dopo aver aggiornato la configurazione della memorizzazione nella cache del connettore, rigenera gli SDK client e ricrea 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, questo avviene automaticamente, senza ulteriori passaggi 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 è precedente a maxAge, utilizza il valore memorizzato nella cache. Questo comportamento predefinito è chiamato policy PREFER_CACHE.

  Puoi anche specificare per singole chiamate di executeQuery() di fornire solo valori memorizzati nella cache (CACHE_ONLY) o di recuperare incondizionatamente nuovi valori 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 notifiche ai listener in base alla configurazione di maxAge.

Tipi di dati nell'SDK

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

Tipo di SQL Connect	TypeScript
Timestamp	stringa
Data	stringa
UUID	stringa
Int64	stringa
Doppio	Numero
In virgola mobile	Numero

Genera SDK React e Angular con TanStack

Firebase SQL 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.

TanStack include la propria implementazione della memorizzazione nella cache lato client e delle sottoscrizioni in tempo reale, che possono funzionare insieme al supporto in tempo reale integrato di SQL Connect, ma solo con alcune difficoltà. Ti consigliamo di utilizzare le associazioni basate su TanStack o il supporto in tempo reale integrato di SQL Connect, ma non entrambi.

Tieni presente che l'implementazione in tempo reale di SQL Connect presenta alcuni vantaggi rispetto alle associazioni TanStack:

• Memorizzazione nella cache normalizzata: SQL Connect implementa la memorizzazione nella cache normalizzata, che migliora la coerenza dei dati, nonché l'efficienza della memoria e della rete rispetto alla memorizzazione nella cache a livello di query. Con la memorizzazione nella cache normalizzata, se un'entità viene aggiornata in un'area dell'app, verrà aggiornata anche in altre aree che utilizzano l'entità.
• Annullamento della convalida da remoto: SQL Connect può annullare la convalida da remoto delle entità memorizzate nella cache su tutti i dispositivi iscritti.

Inizializza l'app

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

initializeApp({...});

Installa i pacchetti Firebase TanStack Query

installa i pacchetti per TanStack Query nel tuo progetto.

React

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

Genera l'SDK React o Angular

Come per l'SDK web standard, come descritto in precedenza, gli strumenti di 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 le associazioni di framework aggiuntive.

Importa le librerie

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

Tieni presente il tipo ConnectorConfig incluso nelle importazioni generali.

React

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

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

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

Utilizza query e mutazioni nel tuo client React o Angular

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

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

React

Tutte queste operazioni nell'SDK generato, sia le query che le mutazioni, chiamano i binding TanStackQuery:

• Le query chiamano e restituiscono l'hook TanStack useDataConnectQuery
• Le mutazioni chiamano e restituiscono l'hook TanStack useDataConnectMutation

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

Angular

Nota: ng add @angular/fire eseguirà questa operazione automaticamente, ma se scegli di configurarla manualmente, puoi farlo con il seguente codice:

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

Utilizza le query di ricaricamento automatico con React e Angular

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

React

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

Connettiti all'emulatore SQL Connect

Facoltativamente, puoi connetterti all'emulatore chiamando connectDataConnectEmulator e poi passando l'istanza SQL Connect all'hook generato, in questo modo:

React

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

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

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

Nota: la chiamata a getDataConnect è necessaria solo se vuoi connetterti all'emulatore SQL Connect. In caso contrario, l'SDK generato creerà automaticamente un'istanza dell'oggetto DataConnect per te.

Aggiorna gli SDK durante la prototipazione

Se hai installato l'estensione VS Code di SQL Connect, gli SDK generati verranno sempre mantenuti aggiornati.

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

firebase dataconnect:sdk:generate --watch

Genera SDK nelle pipeline di build

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

firebase dataconnect:sdk:generate