Korzystanie z wygenerowanych pakietów Flutter SDK

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

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

Dlatego SQL Connect udostępnia środowisko programistyczne i narzędzia, które umożliwiają prototypowanie schematów, zapytań i mutacji wdrożonych na serwerze. Automatycznie generuje też pakiety SDK po stronie klienta podczas prototypowania.

Gdy wprowadzisz zmiany w usłudze i aplikacjach klienckich, aktualizacje po stronie serwera i klienta będą gotowe do wdrożenia.

Jak wygląda proces programowania klienta?

Jeśli postępujesz zgodnie z instrukcjami z sekcji Pierwsze kroki, znasz już ogólny proces tworzenia aplikacji na platformę SQL Connect. W tym przewodniku znajdziesz bardziej szczegółowe informacje o generowaniu pakietów SDK Fluttera na podstawie schematu oraz o pracy z zapytaniami i mutacjami klienta.

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

1. Dodaj Firebase do aplikacji we Flutterze.
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 connector.yaml.

3. Zainicjuj kod klienta i zaimportuj biblioteki.

4. Zaimplementuj wywołania zapytań i mutacji.

5. Skonfiguruj emulator SQL Connect i używaj go, a następnie powtarzaj te czynności.

Generowanie pakietu SDK Flutter

Użyj interfejsu wiersza poleceń Firebase, aby skonfigurować w aplikacjach pakiety SDK wygenerowane przez 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 prototypowania

Jeśli masz zainstalowane rozszerzenie SQL Connect VS Code, wygenerowane pakiety SDK będą zawsze aktualne.

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

firebase dataconnect:sdk:generate --watch

Generowanie pakietów SDK w potokach kompilacji

Możesz używać interfejsu wiersza poleceń Firebase do generowania pakietów SDK SQL Connect w procesach kompilacji CI/CD.

firebase dataconnect:sdk:generate

Konfigurowanie kodu klienta

Inicjowanie aplikacji SQL Connect

Najpierw zainicjuj aplikację, korzystając ze standardowych instrukcji konfiguracji Firebase.

Następnie zainstaluj wtyczkę SQL Connect:

flutter pub add firebase_data_connect

Inicjowanie pakietu SDK SQL Connect Flutter

Zainicjuj instancję SQL Connect, używając informacji, które zostały użyte do skonfigurowania SQL Connect. Te informacje znajdziesz na stronie Databases & Storage (Bazy danych i miejsce na dane) > SQL Connect w konsoli Firebase.

Importowanie bibliotek

Do zainicjowania kodu klienta potrzebne są 2 zestawy importów: ogólne importy SQL Connect i importy wygenerowane przez pakiet 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ć wstępnie zdefiniowane odwołania do zapytań. Wystarczy, że zaimportujesz i wywołasz na nich execute.

import 'generated/movies.dart';

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

Wywoływanie metod zapytania pakietu SDK

Oto przykład użycia tych funkcji skrótów 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ą zawierać pola opcjonalne. W takich przypadkach pakiet SDK Flutter udostępnia metodę kreatora, którą trzeba ustawić osobno.

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

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

Subskrybowanie zmian

Zobacz Otrzymywanie aktualizacji w czasie rzeczywistym od 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 typu wyliczeniowego. Wyobraź sobie na przykład, że na późniejszym etapie cyklu życia aplikacji postanawiasz dodać wartość FULLSCREEN do typu wyliczeniowego AspectRatio.

W przepływie pracy SQL Connect możesz używać lokalnych narzędzi dla programistów do aktualizowania zapytań i pakietów SDK.

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

Przykładowa odporna implementacja

Wygenerowany pakiet SDK wymusza obsługę nieznanych wartości. Oznacza to, że kod klienta musi rozpakować obiekt EnumValue do 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łącz buforowanie po stronie klienta

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

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

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

Ta konfiguracja ma 2 parametry, które są opcjonalne:

• maxAge: maksymalny wiek odpowiedzi z pamięci podręcznej, zanim pakiet SDK klienta pobierze nowe wartości. Przykłady: „0”, „30s”, „1h30m”.

  Domyślna wartość parametru maxAge to 0, co oznacza, że odpowiedzi są przechowywane w pamięci podręcznej, ale pakiet SDK klienta zawsze pobiera nowe wartości. Wartości z pamięci podręcznej będą używane tylko wtedy, gdy parametr CACHE_ONLY ma wartość execute() i zwrócony zostanie początkowy wynik z subscribe().

• storage: pakiet SDK klienta można skonfigurować tak, aby zapisywał odpowiedzi w pamięci podręcznej w persistent lub memory. Wyniki zapisane w pamięci podręcznej w pamięci persistent będą zachowywane po ponownym uruchomieniu aplikacji. W przypadku kierowania na Androida lub iOS domyślna wartość to persistent. W przypadku kierowania na przeglądarki obsługiwane jest tylko miejsce na dane memory.

Po zaktualizowaniu konfiguracji buforowania oprogramowania sprzęgającego wygeneruj ponownie pakiety SDK klienta i przebuduj aplikację. Gdy to zrobisz, execute() i subscribe() będą buforować odpowiedzi i używać buforowanych wartości zgodnie ze skonfigurowaną zasadą. Zwykle dzieje się to automatycznie, bez konieczności wykonywania dodatkowych czynności. Pamiętaj jednak o tych kwestiach:

• Domyślne działanie execute() jest opisane powyżej: jeśli wynik zapytania jest przechowywany w pamięci podręcznej, a wartość w pamięci podręcznej nie jest starsza niż maxAge, używana jest wartość z pamięci podręcznej. To działanie domyślne jest nazywane zasadą PREFER_CACHE.

  Możesz też określić, czy poszczególne wywołania execute() mają wyświetlać tylko wartości z pamięci podręcznej (CACHE_ONLY) czy bezwarunkowo pobierać nowe wartości z serwera (SERVER_ONLY).

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

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

• Gdy wywołasz funkcję subscribe(), zawsze natychmiast zwróci ona zapisaną w pamięci podręcznej treść (jeśli istnieje), niezależnie od ustawienia maxAge. Kolejne wywołania metody execute() będą powiadamiać detektory zgodnie ze skonfigurowanym parametrem 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();

Prototypowanie i testowanie aplikacji Flutter

Instrumentowanie klientów pod kątem korzystania z lokalnego emulatora

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

Instrumentacja aplikacji w celu połączenia z emulatorem jest taka sama 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, zmień w komentarz wiersze dotyczące połączenia z emulatorem.

Typy danych w pakiecie SDK Dart

Serwer SQL Connect reprezentuje typowe typy danych GraphQL. W pakiecie SDK są one reprezentowane w następujący sposób: