Użyj wygenerowanych pakietów SDK na iOS

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

Jak już wspominaliśmy, warto pamiętać, że Data Connect zapytania i mutacje nie są przesyłane przez kod klienta i wykonywane na serwerze. Zamiast tego po wdrożeniu operacje Data 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 Data 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, zarówno aktualizacje po stronie serwera, jak i po stronie klienta będą gotowe do wdrożenia.

Jak wygląda proces tworzenia aplikacji klienckiej?

Jeśli postępujesz zgodnie z instrukcjami w sekcji Pierwsze kroki, poznasz ogólny proces tworzenia aplikacji Data Connect. W tym przewodniku znajdziesz bardziej szczegółowe informacje o generowaniu pakietów Swift SDK na podstawie 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:

1. Dodaj Firebase do aplikacji na iOS.

2. 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:

1. Opracuj schemat aplikacji.

2. Skonfiguruj generowanie pakietu SDK:

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

3. Zainicjuj kod klienta i zaimportuj biblioteki.

4. Wdróż wywołania zapytań i mutacji.

5. Skonfiguruj i używaj Data Connect emulatora i wprowadzaj zmiany.

Generowanie pakietu SDK w Swift

Podobnie jak w przypadku większości projektów Firebase, praca nad Firebase Data Connectkodem klienta odbywa się w lokalnym katalogu projektu. Zarówno rozszerzenie Data Connect VS Code, jak i Firebase CLI to ważne lokalne narzędzia do generowania kodu klienta i zarządzania nim.

Opcje generowania pakietu SDK są powiązane z kilkoma wpisami w dataconnect.yamlpliku wygenerowanym podczas inicjowania projektu.

Inicjowanie generowania pakietu SDK

connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir określa miejsce, w którym ma zostać wygenerowany pakiet SDK. Jeśli nie zostanie określony, jako domyślny katalog wyjściowy zostanie użyty folder łącznika.

package określa nazwę pakietu, który zostanie wygenerowany. Generator utworzy folder o nazwie pakietu, który będzie zawierać plik Package.swift i wygenerowany kod.

observablePublisher (opcjonalny) określa wydawcę Observable, który ma być używany w odwołaniach do zapytań. Możliwe wartości to observableMacro (iOS 17 lub nowszy) i observableObject (wersja starsza niż iOS 17). Jeśli nie podasz żadnej wartości, domyślną wartością będzie observableMacro.

Aktualizowanie pakietów SDK podczas tworzenia prototypu

Jeśli tworzysz interaktywny prototyp za pomocą rozszerzenia Data Connect VS Code i jego Data Connect emulatora, pliki źródłowe pakietu SDK są automatycznie generowane i aktualizowane podczas modyfikowania plików .gql definiujących schematy, zapytania i mutacje. Może to być przydatna funkcja w przypadku procesów roboczych z szybkim ponownym wczytywaniem.

Możesz też użyć interfejsu wiersza poleceń, aby ponownie wygenerować pakiety SDK za każdym razem, gdy zmienią się pliki .gql:

firebase dataconnect:sdk:generate --watch

Generowanie pakietów SDK na potrzeby integracji i wersji produkcyjnych

W niektórych przypadkach, np. podczas przygotowywania źródeł projektu do przesłania na potrzeby testów CI, możesz wywołać interfejs wiersza poleceń Firebase w celu przeprowadzenia aktualizacji zbiorczej.

W takich przypadkach używaj firebase dataconnect:sdk:generate.

Zainicjuj Data Connect pakiet iOS SDK.

Zainicjuj instancję Data Connect, używając informacji, które zostały użyte do skonfigurowania funkcji Data Connect (wszystkie są dostępne w konsoli Firebase na karcie Data Connect).

Pobieranie instancji oprogramowania sprzęgającego

Kod złącza zostanie wygenerowany przez emulator Data Connect. Jeśli nazwa łącznika to movies, a pakiet to movies, jak określono w 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ą one makro @Observable (iOS 17+) lub protokół ObservableObject. Jeśli nie określisz tu żadnej wartości, zostanie użyty domyślny makro @Observable obsługiwany 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, że w późniejszym okresie istnienia aplikacji zdecydujesz się dodać wartość FULLSCREEN do wyliczenia AspectRatio.

W przypadku przepływu pracy Data Connect możesz używać lokalnych narzędzi programistycznych do aktualizowania zapytań i pakietów SDK.

Zanim jednak udostępnisz zaktualizowaną wersję klientów, starsi wdrożeni klienci 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
}

Tworzenie prototypu i testowanie aplikacji na iOS

Konfigurowanie klientów do korzystania z lokalnego emulatora

Możesz użyć Data Connect emulatora, korzystając z rozszerzenia Data Connect VS Code lub interfejsu CLI.

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 app

Typy danych w pakietach SDK Data Connect

Data Connect serwer reprezentuje standardowe i niestandardowe typy danych GraphQL. W pakiecie SDK są one reprezentowane w ten sposób: