Firebase SQL Connect pakiety SDK klienta umożliwiają wywoływanie zapytań i mutacji po stronie serwera bezpośrednio z aplikacji w Firebase. Niestandardowy pakiet SDK klienta generujesz równolegle z projektowaniem 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 już wspominaliśmy, warto 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 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ą tworzenie prototypów schematów, zapytań i mutacji wdrażanych na serwerze. Podczas tworzenia prototypu automatycznie generuje też pakiety SDK po stronie klienta.
Gdy wprowadzisz 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 postępowałeś(-aś) zgodnie z instrukcjami w sekcji Pierwsze kroki, poznałeś(-aś) ogólny proces tworzenia aplikacji SQL Connect. W tym przewodniku znajdziesz bardziej szczegółowe informacje o generowaniu pakietów SDK w Swift z Twojego schematu oraz o pracy z zapytaniami i mutacjami klienta.
Podsumowując, aby używać wygenerowanych pakietów Swift SDK w aplikacjach klienckich, musisz wykonać te czynności wstępne:
- Dodaj Firebase do aplikacji na iOS.
Aby użyć 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 pakiet
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
connector.yaml,
Skonfiguruj i używaj SQL Connect emulatora oraz iteruj.
Generowanie pakietu SDK w Swift
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 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ć SQL Connect pakiety SDK w procesach kompilacji CI/CD.
firebase dataconnect:sdk:generateZainicjuj SQL Connect pakiet iOS SDK.
Zainicjuj instancję SQL Connect, używając informacji, których użyto do skonfigurowania SQL Connect (wszystkie są dostępne na karcie Firebase konsoliSQL Connect).
Pobieranie instancji oprogramowania sprzęgającego
Kod złącza zostanie wygenerowany przez emulator SQL Connect. Jeśli nazwa łącznika to movies, a pakiet to movies, zgodnie z informacjami podanymi w pliku connector.yaml, pobierz obiekt łącznika, wywołując:
let connector = DataConnect.moviesConnector
Implementowanie zapytań i mutacji
Za pomocą obiektu łącznika 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
}
}
Następnie możesz 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żyj odwołania do zapytania. Wszystkie odwołania do zapytań są wydawcami Observable. W zależności od skonfigurowanego wydawcy (patrz connector.yaml)) obsługują oni makro @Observable (iOS 17+) lub implementują protokół ObservableObject. Jeśli nie określisz tu żadnej wartości, zostanie użyte ustawienie domyślne, czyli makro @Observable obsługiwane w iOS 17 lub nowszym.
W widoku SwiftUI możesz powiązać wyniki zapytania za pomocą opublikowanej zmiennej dataodwołania do zapytania i wywołać metodę execute() zapytania, aby zaktualizować dane. Zmienna data będzie pasować do kształtu danych zdefiniowanego w definicji zapytania GQL.
Wszystkie pobrane wyniki są zgodne z protokołem Decodable. Jeśli w zapytaniu 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")
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 okresie cyklu życia aplikacji zdecydujesz się dodać wartość FULLSCREEN do wyliczenia AspectRatio.
W przypadku SQL Connect możesz używać lokalnych narzędzi programistycznych do aktualizowania zapytań i pakietów SDK.
Jednak przed udostępnieniem zaktualizowanej wersji klientów starsze wdrożone klienty mogą przestać działać.
Przykład odpornej implementacji
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 zapisywania w pamięci podręcznej 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 do klienta lokalnie buforują 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 w przypadku przerw w dostępie do sieci.
Aby włączyć buforowanie po stronie klienta, dodaj konfigurację buforowania po stronie klienta do konfiguracji łącznika:
generate:
swiftSdk:
outputDir: "../ios"
package: "FirebaseDataConnectGenerated"
clientCache:
maxAge: 5s
storage: persistent
Ta konfiguracja ma 2 parametry, które są opcjonalne:
maxAge: maksymalny wiek buforowanej odpowiedzi, po którym pakiet SDK klienta pobiera nowe wartości. Przykłady: „0”, „30s”, „1h30m”.Domyślna wartość parametru
maxAgeto0, co oznacza, że odpowiedzi są przechowywane w pamięci podręcznej, ale pakiet SDK klienta zawsze pobiera nowe wartości. Wartości buforowane będą używane tylko wtedy, gdy parametrCACHE_ONLYma wartośćexecute().storage: Pakiet SDK klienta można skonfigurować tak, aby buforował odpowiedzi w pamięcipersistentlub wmemory. Wyniki zapisane w pamięci podręcznejpersistentbędą dostępne po ponownym uruchomieniu aplikacji. W pakietach SDK na iOS domyślna wartość topersistent.
Po zaktualizowaniu konfiguracji buforowania oprogramowania sprzęgającego wygeneruj ponownie pakiety SDK klienta i przebuduj aplikację. Gdy to zrobisz, execute()
będzie buforować odpowiedzi i używać wartości z pamięci podręcznej zgodnie ze skonfigurowanymi zasadami. Zwykle odbywa się to automatycznie, bez żadnych dodatkowych działań z Twojej strony. Pamiętaj jednak o tych kwestiach:
Domyślne działanie funkcji
execute()jest opisane powyżej: jeśli wynik jest zapisany w pamięci podręcznej dla zapytania, a wartość w pamięci podręcznej nie jest starsza niżmaxAge, użyj wartości z pamięci podręcznej. To domyślne działanie jest nazywane zasadąPREFER_CACHE.Możesz też określić, że poszczególne wywołania funkcji
execute()mają zwracać tylko wartości z pamięci podręcznej (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
Instrumentowanie klientów do korzystania z lokalnego emulatora
Możesz używać SQL Connect emulatora w rozszerzeniu SQL Connect do VS Code lub w interfejsie wiersza poleceń.
Instrumentowanie aplikacji w celu połączenia z emulatorem jest takie samo w obu scenariuszach.
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
SQL Connect serwer reprezentuje standardowe i niestandardowe typy danych GraphQL. W pakiecie SDK są one reprezentowane 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