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 wdrażanych w usłudze równolegle generujesz niestandardowy pakiet SDK klienta. SQL Connect usługa. 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. Po wdrożeniu operacje SQL Connect są przechowywane na serwerze, tak jak Cloud Functions. Oznacza to, że musisz wdrożyć odpowiednie zmiany po stronie klienta, aby uniknąć problemów 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.
Jaki jest proces tworzenia aplikacji klienckiej?
Jeśli wykonasz czynności opisane w sekcji Pierwsze kroki, poznasz ogólny proces tworzenia aplikacji za pomocą SQL Connect. W tym przewodniku znajdziesz bardziej szczegółowe informacje o generowaniu pakietów SDK w języku Swift na podstawie schematu oraz o pracy z zapytaniami i mutacjami klienta.
Podsumowując, aby używać wygenerowanych pakietów SDK w języku Swift w aplikacjach klienckich, musisz wykonać te czynności przygotowawcze:
- Dodaj Firebase do aplikacji na iOS.
Aby używać wygenerowanego pakietu SDK, skonfiguruj go jako zależność w Xcode.
Na górnym pasku nawigacyjnym Xcode wybierz File > Add Package Dependencies > Add Local (Plik > Dodaj zależności pakietu > Dodaj lokalnie) i wybierz folder zawierający wygenerowany plik
Package.swift.
Następnie:
- Opracuj schemat aplikacji.
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
Skonfiguruj i używaj emulatora SQL Connect oraz wprowadzaj iteracyjne zmiany.
Generowanie pakietu SDK w języku Swift
Użyj interfejsu wiersza poleceń Firebase, aby skonfigurować wygenerowane pakiety SDK SQL Connect w aplikacjach.
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 użyć wiersza poleceń Firebase, aby aktualizować wygenerowane pakiety SDK.
firebase dataconnect:sdk:generate --watchGenerowanie 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:generateInicjowanie pakietu SDK na iOSSQL 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).
Pobieranie instancji oprogramowania sprzęgającego
Kod oprogramowania sprzęgającego zostanie wygenerowany przez emulator
SQL Connect. Jeśli nazwa oprogramowania sprzęgającego to movies, a pakiet to movies (zgodnie z ustawieniami w pliku connector.yaml), pobierz obiekt oprogramowania sprzęgającego, wywołując:
let connector = DataConnect.moviesConnector
Implementowanie zapytań i mutacji
Za pomocą obiektu oprogramowania sprzęgającego możesz uruchamiać zapytania i mutacje zdefiniowane w kodzie źródłowym GraphQL. Załóżmy, że oprogramowanie sprzęgające ma zdefiniowane te operacje:
mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
movie_insert(data: {
title: $title
releaseYear: $releaseYear
genre: $genre
rating: $rating
})
}
query getMovieByKey($key: Movie_Key!) {
movie(key: $key) { id title }
}
query listMoviesByGenre($genre: String!) {
movies(where: {genre: {eq: $genre}}) {
id
title
}
}
Możesz wtedy utworzyć film w ten sposób:
let mutationResult = try await connector.createMovieMutation.execute(
title: "Empire Strikes Back",
releaseYear: 1980,
genre: "Sci-Fi",
rating: 5)
print("Movie ID: \(mutationResult.data.movie_insert.id)")
Aby pobrać film, użyjesz odwołania do zapytania. Wszystkie odwołania do zapytań są wydawcami Observable. W zależności od skonfigurowanego wydawcy (patrz connector.yaml),
obsługują one makro @Observable (iOS 17+) lub implementują
ObservableObject protokół. Domyślnie, jeśli nie określono żadnego wydawcy, używane jest makro @Observable obsługiwane w iOS 17+.
W widoku SwiftUI możesz powiązać wyniki zapytania za pomocą opublikowanej zmiennej data odwołania do zapytania i wywołać metodę execute() zapytania, aby zaktualizować dane. Zmienna data będzie zgodna z kształtem danych zdefiniowanym w definicji zapytania GQL.
Wszystkie pobrane wyniki są zgodne z protokołem Decodable. Jeśli w pobieraniu GQL uwzględnisz klucz podstawowy obiektu, obiekty będą też Identifiable, co umożliwi Ci używanie ich w iteratorach.
struct ListMovieView: View {
@StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
var body: some View {
VStack {
Button {
Task {
do {
try await refresh()
} catch {
print("Failed to refresh: \(error)")
}
}
} label: {
Text("Refresh")
}
// use the query results in a view
ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
Text(movie.title)
}
}
}
@MainActor
func refresh() async throws {
_ = try await queryRef.execute()
}
}
Zapytania obsługują też jednorazowe wykonanie.
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
Subskrybowanie zmian
Zobacz 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. Załóżmy 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ć narzędzi do programowania lokalnego, aby aktualizować zapytania i pakiety SDK.
Zanim jednak opublikujesz zaktualizowaną wersję klientów, starsze wdrożone klienty mogą przestać działać.
Przykład implementacji odpornej na błędy
Wygenerowany pakiet SDK wymusza obsługę nieznanych wartości, ponieważ wygenerowane wyliczenia zawierają wartość _UNKNOWN, a Swift wymusza wyczerpujące instrukcje switch.
do {
let result = try await DataConnect.moviesConnector.listMovies.execute()
if let data = result.data {
for movie in data.movies {
switch movie.aspectratio {
case .ACADEMY: print("academy")
case .WIDESCREEN: print("widescreen")
case .ANAMORPHIC: print("anamorphic")
case ._UNKNOWN(let unknownAspect): print(unknownAspect)
}
}
}
} catch {
// handle error
}
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ę żądań bazy danych wysyłanych przez aplikację i umożliwić działanie części aplikacji zależnych od bazy danych, gdy połączenie sieciowe zostanie przerwane.
Aby włączyć buforowanie po stronie klienta, dodaj konfigurację buforowania klienta do konfiguracji oprogramowania sprzęgającego:
generate:
swiftSdk:
outputDir: "../ios"
package: "FirebaseDataConnectGenerated"
clientCache:
maxAge: 5s
storage: persistent
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ść
maxAgeto0, 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 przypadkuexecute()zostanie określona wartośćCACHE_ONLY.storage: pakiet SDK klienta można skonfigurować tak, aby buforował odpowiedzi w pamięcipersistentlubmemory. Wyniki buforowane w pamięcipersistentbędą przechowywane po ponownym uruchomieniu aplikacji. W pakietach SDK na iOS domyślnie używana jest pamięćpersistent.
Po zaktualizowaniu konfiguracji buforowania oprogramowania sprzęgającego wygeneruj ponownie pakiety SDK klienta
i ponownie skompiluj aplikację. Gdy to zrobisz, execute()
będzie 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
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
execute()mają używać tylko buforowanych wartości (CACHE_ONLY) lub bezwarunkowo pobierać nowe wartości z serwera (SERVER_ONLY).try await execute(fetchPolicy: .cacheOnly)try await execute(fetchPolicy: .serverOnly)Tworzenie prototypu i testowanie aplikacji na iOS
Konfigurowanie klientów do korzystania z emulatora lokalnego
Możesz używać emulatora SQL Connect w rozszerzeniu SQL Connect VS Code lub w interfejsie wiersza poleceń.
Konfigurowanie aplikacji do łączenia się z emulatorem jest takie samo w obu przypadkach.
let connector = DataConnect.moviesConnector // Connect to the emulator on "127.0.0.1:9399" connector.useEmulator() // (alternatively) if you're running your emulator on non-default port: connector.useEmulator(port: 9999) // Make calls from your appTypy danych w pakietach SDK SQL Connect
Serwer SQL Connect reprezentuje standardowe i niestandardowe typy danych GraphQL. Są one reprezentowane w pakiecie SDK w ten sposób.
SQL Connect Typ Swift Ciąg znaków Ciąg znaków Liczba całkowita Liczba całkowita Liczba zmiennoprzecinkowa Liczba zmiennoprzecinkowa Wartość logiczna Wartość logiczna UUID UUID Data FirebaseDataConnect.LocalDate Sygnatura czasowa FirebaseCore.Timestamp Int64 Int64 Dowolna FirebaseDataConnect.AnyValue