Korzystanie z wygenerowanych pakietów Flutter SDK

Firebase SQL Connect pakiety SDK klienta umożliwiają wywoływanie zapytań i mutacji po stronie serwera bezpośrednio z aplikacji w Firebase. Podczas projektowania schematów, zapytań i mutacji, które wdrażasz w usłudze SQL Connect równolegle generujesz niestandardowy pakiet SDK klienta. Następnie integrujesz metody z tego pakietu SDK z logiką klienta.

Jak wspomnieliśmy w innym miejscu, ważne jest, aby pamiętać, że SQL Connect zapytania i mutacje nie są przesyłane przez kod klienta i wykonywane na serwerze. Zamiast tego po wdrożeniu operacje SQL Connect są przechowywane na serwerze, tak jak funkcje Cloud Functions. Oznacza to, że musisz wdrożyć odpowiednie zmiany po stronie klienta, aby nie zakłócić działania aplikacji u dotychczasowych użytkowników (np. w starszych wersjach aplikacji).

Dlatego SQL Connect udostępnia środowisko programistyczne i narzędzia, które umożliwiają tworzenie prototypów schematów, zapytań i mutacji wdrożonych na serwerze. Podczas tworzenia prototypu automatycznie generuje też pakiety SDK po stronie klienta.

Gdy wprowadzisz iteracyjne aktualizacje usługi i aplikacji klienckich, aktualizacje po stronie serwera i po stronie klienta będą gotowe do wdrożenia.

Jak wygląda proces tworzenia aplikacji klienckiej?

Jeśli wykonasz czynności opisane w przewodniku Pierwsze kroki, poznasz ogólny proces tworzenia aplikacji w SQL Connect. W tym przewodniku znajdziesz bardziej szczegółowe informacje o generowaniu pakietów SDK Flutter na podstawie schematu oraz o pracy z zapytaniami i mutacjami klienta.

Podsumowując, aby używać wygenerowanych pakietów SDK Flutter w aplikacjach klienckich, musisz wykonać te czynności przygotowawcze:

1. Dodaj Firebase do aplikacji Flutter.
2. Zainstaluj interfejs wiersza poleceń flutterfire dart pub global activate flutterfire_cli.
3. Uruchom flutterfire configure.

Następnie:

1. Opracuj schemat aplikacji.

2. Skonfiguruj generowanie pakietu SDK:

   • Za pomocą przycisku Add SDK to app (Dodaj pakiet SDK do aplikacji) w rozszerzeniu SQL Connect VS Code.
   • Aktualizując plik connector.yaml.

3. Zainicjuj kod klienta i zaimportuj biblioteki.

4. Zaimplementuj wywołania zapytań i mutacji.

5. Skonfiguruj i użyj emulatora SQL Connect oraz przeprowadzaj iteracje.

Generowanie pakietu SDK Flutter

Użyj interfejsu wiersza poleceń Firebase, aby skonfigurować w aplikacjach wygenerowane pakiety SDK SQL Connect. Polecenie init powinno wykryć wszystkie aplikacje w bieżącym folderze i automatycznie zainstalować wygenerowane pakiety SDK.

firebase init dataconnect:sdk

Aktualizowanie pakietów SDK podczas tworzenia prototypu

Jeśli masz zainstalowane rozszerzenie SQL Connect VS Code, będzie ono zawsze aktualizować wygenerowane pakiety SDK.

Jeśli nie używasz rozszerzenia SQL Connect VS Code, możesz aktualizować wygenerowane pakiety SDK za pomocą wiersza poleceń Firebase.

firebase dataconnect:sdk:generate --watch

Generowanie pakietów SDK w potokach kompilacji

Za pomocą wiersza poleceń Firebase możesz generować pakiety SDK SQL Connect w procesach kompilacji CI/CD.

firebase dataconnect:sdk:generate

Konfigurowanie kodu klienta

Inicjowanie aplikacji SQL Connect

Najpierw zainicjuj aplikację, postępując zgodnie z e standardowymi instrukcjami konfiguracji Firebase.

Następnie zainstaluj wtyczkę SQL Connect:

flutter pub add firebase_data_connect

Inicjowanie pakicetu SDK FlutterSQL Connect

Zainicjuj instancję SQL Connect, używając informacji, których używasz do konfigurowania SQL Connect (wszystkie są dostępne na karcie SQL Connect w konsoli Firebase).

Importowanie bibliotek

Aby zainicjować kod klienta, musisz zaimportować 2 zestawy bibliotek – ogólne SQL Connect biblioteki oraz konkretne, wygenerowane biblioteki pakietu SDK.

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

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

Używanie zapytań po stronie klienta

Wygenerowany kod będzie już zawierać predefiniowane odwołania do zapytań. Wystarczy je zaimportować i wywołać na nich metodę execute.

import 'generated/movies.dart';

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

Wywoływanie metod zapytań pakietu SDK

Oto przykład użycia tych funkcji skrótów do działań:

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

Pola opcjonalne

Niektóre zapytania mogą mieć pola opcjonalne. W takich przypadkach pakiet SDK Flutter udostępnia metodę tworzenia, którą trzeba ustawić osobno.

Na przykład pole rating jest opcjonalne podczas wywoływania metody createMovie, więc musisz je podać w funkcji tworzenia.

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

Subskrybowanie zmian

Zapoznaj się z artykułem Otrzymywanie aktualizacji w czasie rzeczywistym z SQL Connect.

Obsługa zmian w polach wyliczeniowych

Schemat aplikacji może zawierać wyliczenia, do których można uzyskać dostęp za pomocą zapytań GraphQL.

W miarę zmian w projekcie aplikacji możesz dodawać nowe obsługiwane wartości wyliczeniowe. Wyobraź sobie na przykład, że w późniejszym etapie cyklu życia aplikacji zdecydujesz się dodać wartość FULLSCREEN do wyliczenia AspectRatio.

W procesie SQL Connect możesz używać lokalnych narzędzi programistycznych do aktualizowania zapytań i pakietów SDK.

Zanim jednak opublikujesz zaktualizowaną wersję klientów, starsze wdrożone klienty mogą przestać działać.

Przykład odpornej implementacji

Wygenerowany pakiet SDK wymusza obsługę nieznanych wartości. Oznacza to, że kod klienta musi rozpakować obiekt EnumValue do postaci Known lub 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}');
  }
}

Włączanie buforowania po stronie klienta

SQL Connect ma opcjonalną funkcję buforowania po stronie klienta, którą możesz włączyć, edytując plik connector.yaml. Gdy ta funkcja jest włączona, wygenerowane pakiety SDK klienta będą lokalnie buforować odpowiedzi na zapytania, co może zmniejszyć liczbę zapytań do bazy danych wysyłanych przez aplikację i umożliwić działanie części aplikacji zależnych od bazy danych w przypadku przerwy w dostępie do sieci.

Aby włączyć buforowanie po stronie klienta, dodaj konfigurację buforowania po stronie klienta do konfiguracji oprogramowania sprzęgającego:

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

Ta konfiguracja ma 2 parametry, oba opcjonalne:

• maxAge: maksymalny wiek buforowanej odpowiedzi, po którym pakiet SDK klienta pobierze nowe wartości. Przykłady: „0”, „30s”, „1h30m”.

  Domyślna wartość parametru maxAge to 0, co oznacza, że odpowiedzi są buforowane, ale pakiet SDK klienta zawsze będzie pobierać nowe wartości. Buforowane wartości będą używane tylko wtedy, gdy w przypadku metody execute() określono wartość CACHE_ONLY, a w przypadku metody subscribe() zwrócono wynik początkowy.

• storage: pakiet SDK klienta można skonfigurować tak, aby buforował odpowiedzi w pamięci persistent lub memory. Wyniki buforowane w pamięci persistent będą zachowywane po ponownym uruchomieniu aplikacji. W przypadku Androida i iOS domyślnie używana jest pamięć persistent. W przypadku przeglądarek obsługiwana jest tylko pamięć memory.

Po zaktualizowaniu konfiguracji buforowania oprogramowania sprzęgającego wygeneruj ponownie pakiety SDK klienta i ponownie skompiluj aplikację. Gdy to zrobisz, metody execute() i subscribe() będą buforować odpowiedzi i używać buforowanych wartości zgodnie ze skonfigurowanymi zasadami. Zwykle dzieje się to automatycznie, bez żadnych dodatkowych działań z Twojej strony. Pamiętaj jednak o tych kwestiach:

• Domyślne działanie metody execute() jest takie, jak opisano powyżej: jeśli wynik jest buforowany dla zapytania, a buforowana wartość nie jest starsza niż maxAge, użyj buforowanej wartości. To domyślne działanie jest nazywane zasadą PREFER_CACHE.

  Możesz też określić, że poszczególne wywołania metody execute() mają zwracać tylko buforowane wartości (CACHE_ONLY) lub bezwarunkowo pobierać nowe wartości z serwera (SERVER_ONLY).

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

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

• Gdy wywołasz metodę subscribe(), zawsze natychmiast zwróci ona buforowaną treść, jeśli taka istnieje, niezależnie od ustawienia maxAge. Kolejne wywołania metody execute() będą powiadamiać odbiorców zgodnie ze skonfigurowaną wartością maxAge.

Używanie mutacji po stronie klienta

Mutacje są dostępne w taki sam sposób jak zapytania.

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

Tworzenie prototypów i testowanie aplikacji Flutter

Konfigurowanie klientów do korzystania z lokalnego emulatora

Możesz używać emulatora SQL Connect z rozszerzenia SQL Connect VS Code lub z interfejsu wiersza poleceń.

Konfigurowanie aplikacji do łączenia się z emulatorem jest takie samo w obu przypadkach.

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

Aby przełączyć się na zasoby produkcyjne, zakomentuj wiersze służące do łączenia się z emulatorem.

Typy danych w pakiecie SDK Dart

Serwer SQL Connect reprezentuje typowe typy danych GraphQL. Są one reprezentowane w pakiecie SDK w ten sposób.