Generierte Flutter-SDKs verwenden

Mit den Firebase SQL Connect-Client-SDKs können Sie Ihre serverseitigen Abfragen und Mutationen direkt über eine Firebase-App aufrufen. Sie generieren ein benutzerdefiniertes Client-SDK parallel zur Entwicklung der Schemas, Abfragen und Mutationen, die Sie für Ihren SQL Connect-Dienst bereitstellen. Anschließend binden Sie Methoden aus diesem SDK in Ihre Clientlogik ein.

Wie bereits erwähnt, ist es wichtig zu beachten, dass SQL Connect-Abfragen und ‑Mutationen nicht vom Clientcode gesendet und auf dem Server ausgeführt werden. Stattdessen werden SQL Connect-Vorgänge bei der Bereitstellung auf dem Server wie Cloud Functions gespeichert. Das bedeutet, dass Sie entsprechende clientseitige Änderungen bereitstellen müssen, um zu vermeiden, dass bestehende Nutzer (z. B. in älteren App-Versionen) beeinträchtigt werden.

SQL Connect bietet Ihnen daher eine Entwicklungsumgebung und Tools, mit denen Sie Prototypen für Ihre auf dem Server bereitgestellten Schemas, Abfragen und Mutationen erstellen können. Außerdem werden clientseitige SDKs automatisch generiert, während Sie Prototypen erstellen.

Nachdem Sie die Updates für Ihren Dienst und Ihre Client-Apps durchlaufen haben, können Sie sowohl serverseitige als auch clientseitige Updates bereitstellen.

Wie sieht der Workflow für die Cliententwicklung aus?

Wenn Sie dem Startleitfaden gefolgt sind, haben Sie den allgemeinen Entwicklungsablauf für SQL Connect kennengelernt. In dieser Anleitung finden Sie detailliertere Informationen zum Generieren von Flutter-SDKs aus Ihrem Schema und zum Arbeiten mit Clientabfragen und ‑Mutationen.

Zusammenfassend lässt sich sagen, dass Sie die folgenden Voraussetzungen erfüllen müssen, um generierte Flutter-SDKs in Ihren Client-Apps zu verwenden:

1. Fügen Sie Ihrer Flutter-App Firebase hinzu.
2. Installieren Sie die FlutterFire-Befehlszeile dart pub global activate flutterfire_cli.
3. Führen Sie flutterfire configure aus.

Gehen Sie anschließend so vor:

1. App-Schema entwickeln

2. SDK-Generierung einrichten:

   • Mit dem Button SDK zur App hinzufügen in unserer SQL Connect-VS Code-Erweiterung
   • Aktualisieren Sie Ihre connector.yaml.

3. Clientcode initialisieren und Bibliotheken importieren

4. Aufrufe für Abfragen und Mutationen implementieren

5. SQL Connect-Emulator einrichten und verwenden und iterieren.

Flutter SDK generieren

Verwenden Sie die Firebase-Befehlszeile, um SQL Connect-generierte SDKs in Ihren Apps einzurichten. Mit dem Befehl init sollten alle Apps im aktuellen Ordner erkannt und die generierten SDKs automatisch installiert werden.

firebase init dataconnect:sdk

SDKs während der Prototyperstellung aktualisieren

Wenn Sie die SQL Connect-VS Code-Erweiterung installiert haben, werden generierte SDKs immer auf dem neuesten Stand gehalten.

Wenn Sie die SQL Connect-VS Code-Erweiterung nicht verwenden, können Sie die generierten SDKs mit der Firebase-Befehlszeile auf dem neuesten Stand halten.

firebase dataconnect:sdk:generate --watch

SDKs in Build-Pipelines generieren

Sie können die Firebase CLI verwenden, um SQL Connect-SDKs in CI/CD-Build-Prozessen zu generieren.

firebase dataconnect:sdk:generate

Clientcode einrichten

SQL Connect-App initialisieren

Initialisieren Sie Ihre App zuerst gemäß der Standardanleitung für die Firebase-Einrichtung.

Installieren Sie dann das SQL Connect-Plug-in:

flutter pub add firebase_data_connect

SQL Connect Flutter SDK initialisieren

Initialisieren Sie Ihre SQL Connect-Instanz mit den Informationen, die Sie zum Einrichten von SQL Connect verwendet haben (alle auf dem Tab SQL Connect der Firebase-Konsole verfügbar).

Bibliotheken importieren

Es sind zwei Importsätze erforderlich, um Ihren Clientcode zu initialisieren: allgemeine SQL Connect-Importe und spezifische, generierte SDK-Importe.

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

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

Abfragen auf der Clientseite verwenden

Der generierte Code enthält bereits vordefinierte Query-Refs. Sie müssen sie nur importieren und execute aufrufen.

import 'generated/movies.dart';

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

SDK-Abfragemethoden aufrufen

Hier ein Beispiel für die Verwendung dieser Aktionskürzelfunktionen:

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

Optionale Felder

Einige Abfragen können optionale Felder enthalten. In diesen Fällen stellt das Flutter SDK eine Builder-Methode bereit, die separat festgelegt werden muss.

Das Feld rating ist beispielsweise optional, wenn createMovie aufgerufen wird. Sie müssen es also in der Builder-Funktion angeben.

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

Änderungen abonnieren

Sie können Änderungen abonnieren, die jedes Mal aktualisiert werden, wenn Sie eine Abfrage ausführen.

QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();

// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
  updateUIWithMovies(data.movies);
});

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`

Änderungen an Enumerationsfeldern verarbeiten

Das Schema einer App kann Aufzählungen enthalten, auf die über Ihre GraphQL-Abfragen zugegriffen werden kann.

Wenn sich das Design einer App ändert, können Sie neue unterstützte Enum-Werte hinzufügen. Angenommen, Sie entscheiden sich später im Lebenszyklus Ihrer Anwendung, der AspectRatio-Enumeration den Wert FULLSCREEN hinzuzufügen.

Im SQL Connect-Workflow können Sie lokale Entwicklungstools verwenden, um Ihre Abfragen und SDKs zu aktualisieren.

Bevor Sie jedoch eine aktualisierte Version Ihrer Clients veröffentlichen, kann es sein, dass ältere bereitgestellte Clients nicht mehr funktionieren.

Beispiel für eine robuste Implementierung

Das generierte SDK erzwingt die Verarbeitung unbekannter Werte. Das heißt, der Clientcode muss das EnumValue-Objekt in Known oder Unknown entpacken.

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

Clientseitiges Caching aktivieren

SQL Connect bietet eine optionale clientseitige Caching-Funktion, die Sie durch Bearbeiten der Datei connector.yaml aktivieren können. Wenn diese Funktion aktiviert ist, werden die generierten Client-SDKs Antwortdaten lokal im Cache speichern. Dadurch kann die Anzahl der Datenbankanfragen, die Ihre App stellt, reduziert werden. Außerdem können die datenbankabhängigen Teile Ihrer App auch dann funktionieren, wenn die Netzwerkverfügbarkeit unterbrochen wird.

Wenn Sie das clientseitige Caching aktivieren möchten, fügen Sie Ihrer Connector-Konfiguration eine Client-Caching-Konfiguration hinzu:

generate:
  javascriptSdk:
    outputDir: ../dart/
    package: "dataconnect_generated"
    clientCache:
      maxAge: 5s
      storage: memory

Diese Konfiguration hat zwei Parameter, die beide optional sind:

• maxAge: Das maximale Alter einer im Cache gespeicherten Antwort, bevor das Client-SDK neue Werte abruft. Beispiele: „0“, „30s“, „1h30m“

  Der Standardwert für maxAge ist 0. Das bedeutet, dass Antworten zwischengespeichert werden, das Client-SDK aber immer aktuelle Werte abruft. Die im Cache gespeicherten Werte werden nur verwendet, wenn CACHE_ONLY auf execute() gesetzt ist und das erste Ergebnis von subscribe() zurückgegeben wird.

• storage: Das Client-SDK kann so konfiguriert werden, dass Antworten entweder im persistent-Speicher oder in memory zwischengespeichert werden. Im persistent-Speicher zwischengespeicherte Ergebnisse bleiben auch nach einem Neustart der App erhalten. Bei Targeting auf Android oder iOS ist der Standardwert persistent. Beim Targeting auf Webbrowser wird nur memory-Speicher unterstützt.

Nachdem Sie die Caching-Konfiguration Ihres Connectors aktualisiert haben, müssen Sie Ihre Client-SDKs neu generieren und Ihre App neu erstellen. Danach werden mit execute() und subscribe() Antworten gemäß der von Ihnen konfigurierten Richtlinie im Cache gespeichert und es werden gecachte Werte verwendet. Das geschieht in der Regel automatisch, ohne dass Sie dafür noch etwas zu tun brauchen. Beachten Sie jedoch Folgendes:

• Das Standardverhalten von execute() ist wie oben beschrieben: Wenn ein Ergebnis für eine Abfrage im Cache gespeichert ist und der Cachewert nicht älter als maxAge ist, wird der Cachewert verwendet. Dieses Standardverhalten wird als PREFER_CACHE-Richtlinie bezeichnet.

  Sie können auch für einzelne Aufrufe von execute() angeben, ob nur Werte aus dem Cache bereitgestellt werden sollen (CACHE_ONLY) oder ob bedingungslos neue Werte vom Server abgerufen werden sollen (SERVER_ONLY).

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

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

• Wenn Sie subscribe() aufrufen, werden die im Cache gespeicherten Inhalte immer sofort zurückgegeben, sofern sie vorhanden sind, unabhängig von der Einstellung für maxAge. Bei nachfolgenden Anrufen an execute() werden Zuhörer gemäß der konfigurierten maxAge benachrichtigt.

Mutationen auf der Clientseite verwenden

Auf Mutationen kann auf dieselbe Weise wie auf Abfragen zugegriffen werden.

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

Flutter-Apps prototypisieren und testen

Clients für die Verwendung eines lokalen Emulators instrumentieren

Sie können den SQL Connect-Emulator entweder über die VS Code-Erweiterung „SQL Connect“ oder über die CLI verwenden.

Die Instrumentierung der App für die Verbindung zum Emulator ist in beiden Szenarien identisch.

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

Wenn Sie zu Produktionsressourcen wechseln möchten, kommentieren Sie die Zeilen aus, die für die Verbindung zum Emulator verwendet werden.

Datentypen im Dart-SDK

Der SQL Connect-Server stellt allgemeine GraphQL-Datentypen dar. Sie werden im SDK so dargestellt: