Generierte Flutter-SDKs verwenden

Mit den Firebase Data Connect Client-SDKs können Sie Ihre serverseitigen Abfragen und Mutationen direkt über eine Firebase-App aufrufen. Sie generieren parallel ein benutzerdefiniertes Client-SDK, während Sie die Schemas, Abfragen und Mutationen entwerfen, die Sie in Ihrem Data Connect Dienst bereitstellen. Anschließend binden Sie Methoden aus diesem SDK in Ihre Clientlogik ein.

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

Aus diesem Grund bietet Data Connect eine Entwicklungsumgebung und Tools, mit denen Sie Prototypen für Ihre serverseitig bereitgestellten Schemas, Abfragen und Mutationen erstellen können. Außerdem werden während der Prototyperstellung automatisch clientseitige SDKs generiert.

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

Was ist der Workflow für die Cliententwicklung?

Wenn Sie die Anleitung Erste Schritte befolgt haben, kennen Sie bereits den allgemeinen Entwicklungsablauf für Data Connect. In diesem Leitfaden 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 Schritte ausführen müssen, um generierte Flutter-SDKs in Ihren Client-Apps zu verwenden:

Firebase zu Ihrer Flutter-App hinzufügen
Installieren Sie die FlutterFire CLI: dart pub global activate flutterfire_cli.
Führen Sie flutterfire configure aus.

Gehen Sie anschließend so vor:

App-Schema entwickeln
SDK-Generierung einrichten:
- Mit der Schaltfläche SDK zur App hinzufügen in unserer Data Connect VS Code-Erweiterung
- Durch Aktualisieren von connector.yaml
Clientcode initialisieren und Bibliotheken importieren.
Aufrufe für Abfragen und Mutationen implementieren.
Richten Sie den Data Connect Emulator ein und verwenden Sie ihn und führen Sie Iterationen durch.

Flutter-SDK generieren

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

firebase init dataconnect:sdk

SDKs während der Prototyperstellung aktualisieren

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

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

firebase dataconnect:sdk:generate --watch

SDKs in Build-Pipelines generieren

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

firebase dataconnect:sdk:generate

Clientcode einrichten

Data Connect-App initialisieren

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

Installieren Sie dann das Data Connect Plug‑in:

flutter pub add firebase_data_connect

Flutter-SDK initialisierenData Connect

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

Bibliotheken importieren

Zum Initialisieren Ihres Clientcodes sind zwei Importsätze erforderlich: allgemeine Data Connect Imports und spezifische, generierte SDK-Imports.

// 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 Abfrageverweise. Sie müssen sie nur importieren und execute aufrufen.

import 'generated/movies.dart';

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

SDK-Abfragemethoden aufrufen

Hier ein Beispiel mit diesen Aktions-Shortcuts:

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 haben möglicherweise optionale Felder. In diesen Fällen stellt das Flutter-SDK eine Builder-Methode bereit, die separat festgelegt werden muss.

Das Feld rating ist beispielsweise optional, wenn Sie createMovie aufrufen. Sie müssen es daher 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 Aufzählungsfeldern verarbeiten

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

Wenn sich das Design einer App ändert, können Sie neue unterstützte Aufzählungswerte hinzufügen. Angenommen, Sie entscheiden sich später im Lebenszyklus Ihrer Anwendung, der Aufzählung AspectRatio den Wert „FULLSCREEN“ hinzuzufügen.

Im Data 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, können ältere bereitgestellte Clients Probleme verursachen.

Beispiel für eine robuste Implementierung

Das generierte SDK erzwingt die Verarbeitung unbekannter Werte. Das heißt, der Clientcode muss das Objekt EnumValue 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

Data Connect bietet eine optionale clientseitige Caching-Funktion, die Sie aktivieren können, indem Sie die Datei connector.yaml bearbeiten. Wenn diese Funktion aktiviert ist, werden Abfrageantworten von den generierten Client-SDKs lokal im Cache gespeichert. Dadurch kann die Anzahl der Datenbankanfragen Ihrer App reduziert werden und die datenbankabhängigen Teile Ihrer App funktionieren auch dann, wenn die Netzwerkverfügbarkeit unterbrochen ist.

Fügen Sie Ihrer Connector-Konfiguration eine clientseitige Caching-Konfiguration hinzu, um das clientseitige Caching zu aktivieren:

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 im Cache gespeichert werden, das Client-SDK aber immer neue Werte abruft. Die im Cache gespeicherten Werte werden nur verwendet, wenn CACHE_ONLY für execute() und das erste Ergebnis angegeben wird, das von subscribe() zurückgegeben wird.
storage: Das Client-SDK kann so konfiguriert werden, dass Antworten entweder im persistent-Speicher oder im memory-Speicher im Cache gespeichert werden. Im persistent-Speicher im Cache gespeicherte Ergebnisse bleiben auch nach einem Neustart der App erhalten. Bei Android oder iOS ist der Standardwert persistent. Bei Webbrowsern wird nur der memory-Speicher unterstützt.

Nachdem Sie die Caching-Konfiguration Ihres Connectors aktualisiert haben, generieren Sie Ihre Client-SDKs neu und erstellen Sie Ihre App neu. Danach werden Antworten von execute() und subscribe() im Cache gespeichert und im Cache gespeicherte Werte gemäß der konfigurierten Richtlinie verwendet. Dies geschieht in der Regel automatisch, ohne dass Sie dafür noch etwas tun müssen. 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 im Cache gespeicherte Wert nicht älter als maxAge ist, wird der im Cache gespeicherte Wert verwendet. Dieses Standardverhalten wird als PREFER_CACHE-Richtlinie bezeichnet.

Sie können auch für einzelne Aufrufe von execute() angeben, dass entweder nur im Cache gespeicherte Werte bereitgestellt werden (CACHE_ONLY) oder dass bedingungslos neue Werte vom Server abgerufen werden (SERVER_ONLY).
```
await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);
```
```
await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);
```
Wenn Sie subscribe() aufrufen, wird immer sofort der im Cache gespeicherte Inhalt zurückgegeben, sofern er vorhanden ist, unabhängig von der Einstellung maxAge. Bei nachfolgenden Aufrufen von execute() werden Listener 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();

Prototypen für Flutter-Apps erstellen und testen

Clients für die Verwendung eines lokalen Emulators instrumentieren

Sie können den Data Connect Emulator verwenden, entweder über die Data Connect VS Code-Erweiterung oder über die CLI.

Die Instrumentierung der App für die Verbindung zum Emulator ist in beiden Fällen gleich.

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 für die Verbindung zum Emulator aus.

Datentypen im Dart-SDK

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

Data Connect Typ	Dart
Zeitstempel	firebase_data_connect.Timestamp
Ganzzahl (32 Bit)	int
Datum	DateTime
UUID	String
INT64	int
Float	double
Boolesch	bool
Beliebig	firebase_data_connect.AnyValue

Generierte Flutter-SDKs verwenden Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.