Usa gli SDK Flutter 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, su 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 Flutter dal tuo schema e sull'utilizzo di query e mutazioni client.

In sintesi, per utilizzare gli SDK Flutter generati nelle tue app client, devi seguire questi passaggi preliminari:

1. Aggiungi Firebase alla tua app Flutter.
2. Installa l'interfaccia a riga di comando FlutterFire dart pub global activate flutterfire_cli.
3. Esegui flutterfire configure.

Quindi:

1. Sviluppa lo schema dell'app.

2. Configura la generazione dell'SDK:

   • Con il pulsante Aggiungi SDK all'app nell'estensione SQL Connect per VS Code
   • Aggiornando il tuo connector.yaml.

3. Inizializza il codice client e importa le librerie.

4. Implementa le chiamate alle query e alle mutazioni.

5. Configura e utilizza l'emulatore SQL Connect ed esegui l'iterazione.

Genera l'SDK Flutter

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

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

Configura il codice client

Inizializza l'app SQL Connect

Innanzitutto, inizializza l'app seguendo le istruzioni di configurazione standard di Firebase.

Poi, installa il plug-in SQL Connect:

flutter pub add firebase_data_connect

Inizializza l'SDK Flutter SQL Connect

Inizializza l'istanza SQL Connect utilizzando le informazioni che hai utilizzato per configurare SQL Connect. Trova queste informazioni nella pagina Database e spazio di archiviazione > SQL Connect della console Firebase.

Importa le librerie

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

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

Utilizza le query sul lato client

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

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

Chiama i metodi di query dell'SDK

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

import 'generated/movies.dart';

function onBtnClick() {
  // This will call the generated Dart from the CLI and then make an HTTP request to the server.
  MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}

Campi facoltativi

Alcune query potrebbero avere campi facoltativi. In questi casi, l'SDK Flutter espone un metodo builder e dovrà essere impostato separatamente.

Ad esempio, il campo rating è facoltativo quando chiami createMovie, quindi devi fornirlo nella funzione builder.

await MoviesConnector.instance.createMovie( title: 'Empire Strikes Back', releaseYear: 1980, genre: 'Sci-Fi').rating(5).execute();

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

L'SDK generato forza la gestione dei valori sconosciuti. Ciò significa che il codice client deve eseguire l'unwrapping dell'oggetto EnumValue in Known o Unknown.

final result = await MoviesConnector.instance.listMovies().execute();

if (result.data != null && result.data!.isNotEmpty) {
  handleEnumValue(result.data![0].aspectratio);
}

void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
  if (aspectValue.value != null) {
    switch(aspectValue.value!) {
      case AspectRatio.ACADEMY:
        print('This movie is in Academy aspect');
        break;
      case AspectRatio.WIDESCREEN:
        print('This movie is in Widescreen aspect');
        break;
      case AspectRatio.ANAMORPHIC:
        print('This movie is in Anamorphic aspect');
        break;
      case AspectRatio.IMAX:
        print('This movie is in IMAX aspect');
    }
  } else {
    print('Unknown aspect ratio detected: ${aspectValue.stringValue}');
  }
}

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à è abilitata, 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 attivare la memorizzazione nella cache lato client, aggiungi una configurazione di memorizzazione nella cache del client alla configurazione del connettore:

generate:
  javascriptSdk:
    outputDir: ../dart/
    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 è impostato su execute() 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 persistent verranno mantenuti anche dopo il riavvio dell'app. Se il targeting è Android o iOS, il valore predefinito è persistent. Quando il target sono i browser 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, execute() 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 execute() è 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 execute() di fornire solo valori memorizzati nella cache (CACHE_ONLY) o di recuperare incondizionatamente nuovi valori dal server (SERVER_ONLY).

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);
  

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);
  

• Quando chiami subscribe(), i contenuti memorizzati nella cache, se presenti, vengono sempre restituiti immediatamente, indipendentemente dall'impostazione maxAge. Le chiamate successive a execute() invieranno notifiche ai listener in base alla configurazione di maxAge.

Utilizza le mutazioni sul lato client

Le mutazioni sono accessibili allo stesso modo delle query.

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

Crea prototipi e testa le tue app Flutter

Strumenta i client per utilizzare un emulatore locale

Puoi utilizzare l'emulatore SQL Connect, dall'estensione VS Code di SQL Connect o dalla CLI.

La strumentazione dell'app per la connessione all'emulatore è la stessa per entrambi gli scenari.

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';

MoviesConnector.instance.dataConnect
          .useDataConnectEmulator('127.0.0.1', 9399);

// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();

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

Tipi di dati nell'SDK Dart

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