SDK klien Firebase SQL Connect memungkinkan Anda memanggil kueri dan mutasi sisi server langsung dari aplikasi Firebase. Anda membuat SDK klien kustom secara paralel saat mendesain skema, kueri dan mutasi yang Anda deploy ke layanan SQL Connect. Kemudian, Anda mengintegrasikan metode dari SDK ini ke dalam logika klien.
Seperti yang telah kami sebutkan di tempat lain, penting untuk diperhatikan bahwa SQL Connect kueri dan mutasi tidak dikirimkan oleh kode klien dan dijalankan di server. Sebagai gantinya, saat di-deploy, SQL Connect operasi disimpan di server seperti Cloud Functions. Artinya, Anda perlu men-deploy perubahan sisi klien yang sesuai untuk menghindari gangguan pada pengguna yang ada (misalnya, pada versi aplikasi yang lebih lama).
Itulah sebabnya SQL Connect menyediakan lingkungan dan alat pengembangan yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy server. SQL Connect juga membuat SDK sisi klien secara otomatis, saat Anda membuat prototipe.
Setelah Anda melakukan iterasi pembaruan pada aplikasi layanan dan klien, pembaruan sisi server dan klien siap di-deploy.
Apa yang dimaksud dengan alur kerja pengembangan klien?
Jika Anda mengikuti Memulai, Anda akan diperkenalkan dengan alur pengembangan keseluruhan untuk SQL Connect. Dalam panduan ini, Anda akan menemukan informasi yang lebih mendetail tentang pembuatan Swift SDK dari skema dan penggunaan kueri dan mutasi klien.
Singkatnya, untuk menggunakan Swift SDK yang dibuat di aplikasi klien, Anda harus mengikuti langkah-langkah prasyarat berikut:
- Tambahkan Firebase ke aplikasi iOS Anda.
Untuk menggunakan SDK yang dibuat, konfigurasikan sebagai dependensi di Xcode.
Di menu navigasi atas Xcode, pilih File > Add Package Dependencies > Add Local, lalu pilih folder yang berisi
Package.swiftyang dibuat.
Kemudian:
- Kembangkan skema aplikasi Anda.
Siapkan pembuatan SDK:
- Dengan tombol Add SDK to app di ekstensi SQL Connect VS Code
- Dengan memperbarui
connector.yaml
Siapkan dan gunakan emulator SQL Connect dan lakukan iterasi.
Buat Swift SDK
Gunakan Firebase CLI untuk menyiapkan SDK yang dibuat SQL Connect di aplikasi Anda.
Perintah init akan mendeteksi semua aplikasi di folder saat ini dan menginstal SDK yang dibuat secara otomatis.
firebase init dataconnect:sdk
Memperbarui SDK saat membuat prototipe
Jika Anda telah menginstal ekstensi SQL Connect VS Code, ekstensi tersebut akan selalu memperbarui SDK yang dibuat.
Jika tidak menggunakan ekstensi SQL Connect VS Code, Anda dapat menggunakan Firebase CLI untuk memperbarui SDK yang dibuat.
firebase dataconnect:sdk:generate --watchMembuat SDK dalam pipeline build
Anda dapat menggunakan Firebase CLI untuk membuat SQL Connect SDK dalam proses build CI/CD.
firebase dataconnect:sdk:generateMenginisialisasi SQL Connect iOS SDK
Inisialisasi instance SQL Connect menggunakan informasi yang Anda gunakan untuk menyiapkan SQL Connect. Temukan informasi ini di Databases & Storage > SQL Connect page of the Firebase console.
Mendapatkan instance konektor
Kode untuk konektor Anda akan dibuat oleh the
SQL Connect emulator. Jika nama konektor Anda adalah movies dan paketnya adalah movies, seperti yang ditentukan dalam connector.yaml, ambil objek konektor dengan memanggil:
let connector = DataConnect.moviesConnector
Menerapkan kueri dan mutasi
Dengan objek konektor, Anda dapat menjalankan kueri dan mutasi seperti yang ditentukan dalam kode sumber GraphQL. Misalkan konektor Anda memiliki operasi berikut yang ditentukan:
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
}
}
Kemudian, Anda dapat membuat film sebagai berikut:
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)")
Untuk mengambil film, Anda akan menggunakan referensi kueri. Semua referensi kueri adalah penayang yang Dapat Diamati. Bergantung pada penayang yang dikonfigurasi (lihat connector.yaml),
penayang tersebut mendukung makro @Observable (iOS 17+) atau menerapkan protokol
ObservableObject. Jika tidak ada yang ditentukan, nilai defaultnya adalah makro @Observable yang didukung di iOS 17+.
Dalam tampilan SwiftUI, Anda dapat mengikat hasil kueri menggunakan variabel data yang dipublikasikan dari referensi kueri dan memanggil metode execute() kueri untuk memperbarui data. Variabel data akan cocok dengan bentuk data yang ditentukan dalam definisi kueri GQL Anda.
Semua hasil yang diambil mematuhi protokol Decodable. Jika Anda menyertakan kunci utama objek dalam pengambilan GQL, objek juga Identifiable, sehingga Anda dapat menggunakannya dalam iterator.
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()
}
}
Kueri juga mendukung eksekusi satu kali.
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
Berlangganan perubahan
Lihat Mendapatkan update real-time dari SQL Connect.
Menangani perubahan pada kolom enumerasi
Skema aplikasi dapat berisi enumerasi, yang dapat diakses oleh kueri GraphQL Anda.
Saat desain aplikasi berubah, Anda dapat menambahkan nilai yang didukung enum baru. Misalnya, bayangkan bahwa nanti dalam siklus proses aplikasi, Anda memutuskan untuk menambahkan nilai FULLSCREEN ke enum AspectRatio.
Dalam alur kerja SQL Connect, Anda dapat menggunakan alat pengembangan lokal untuk memperbarui kueri dan SDK.
Namun, sebelum Anda merilis versi klien yang diperbarui, klien yang di-deploy sebelumnya mungkin akan rusak.
Contoh penerapan yang tangguh
SDK yang dibuat memaksa penanganan nilai yang tidak diketahui karena enum yang dibuat berisi nilai _UNKNOWN, dan Swift menerapkan pernyataan switch yang lengkap.
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
}
Mengaktifkan caching sisi klien
SQL Connect memiliki fitur caching sisi klien opsional, yang Anda
dapat aktifkan dengan mengedit file connector.yaml. Jika fitur ini diaktifkan, SDK klien yang dibuat akan menyimpan respons kueri secara lokal, yang dapat mengurangi jumlah permintaan database yang dibuat aplikasi Anda dan memungkinkan bagian aplikasi yang bergantung pada database berfungsi saat ketersediaan jaringan terganggu.
Untuk mengaktifkan caching sisi klien, tambahkan konfigurasi caching klien ke konfigurasi konektor Anda:
generate:
swiftSdk:
outputDir: "../ios"
package: "FirebaseDataConnectGenerated"
clientCache:
maxAge: 5s
storage: persistent
Konfigurasi ini memiliki dua parameter, keduanya opsional:
maxAge: Usia maksimum respons yang di-cache sebelum SDK klien mengambil nilai baru. Contoh: "0", "30s", "1h30m".Nilai default untuk
maxAgeadalah0, yang berarti respons di-cache, tetapi SDK klien akan selalu mengambil nilai baru. Nilai yang di-cache hanya akan digunakan jikaCACHE_ONLYditentukan keexecute().storage: SDK klien dapat dikonfigurasi untuk menyimpan respons dalam cache di penyimpananpersistentatau dimemory. Hasil yang di-cache di penyimpananpersistentakan tetap ada saat aplikasi dimulai ulang. Di iOS SDK, nilai defaultnya adalahpersistent.
Setelah memperbarui konfigurasi caching konektor, buat ulang SDK klien
dan bangun kembali aplikasi Anda. Setelah melakukannya, execute()
akan menyimpan respons
dalam cache dan menggunakan nilai yang di-cache sesuai dengan kebijakan yang Anda konfigurasi. Hal ini umumnya terjadi secara otomatis, tanpa langkah tambahan dari Anda. Namun, perhatikan hal berikut:
Perilaku default
execute()adalah seperti yang dijelaskan di atas: jika hasil di-cache untuk kueri dan nilai yang di-cache tidak lebih lama darimaxAge, gunakan nilai yang di-cache. Perilaku default ini disebut kebijakanPREFER_CACHE.Anda juga dapat menentukan pemanggilan individual
execute()untuk hanya menayangkan nilai yang di-cache (CACHE_ONLY) atau untuk mengambil nilai baru dari server tanpa syarat (SERVER_ONLY).try await execute(fetchPolicy: .cacheOnly)try await execute(fetchPolicy: .serverOnly)Membuat prototipe dan menguji aplikasi iOS
Menginstrumentasi klien untuk menggunakan emulator lokal
Anda dapat menggunakan emulator SQL Connect, baik dari ekstensi SQL Connect VS Code maupun dari CLI.
Menginstrumentasi aplikasi untuk terhubung ke emulator sama untuk kedua skenario.
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 appJenis data di SQL Connect SDK
Server SQL Connect mewakili jenis data GraphQL umum dan kustom. Jenis data ini direpresentasikan dalam SDK sebagai berikut.
SQL Connect Jenis Swift String String Int Int Float Double Boolean Bool UUID UUID Date FirebaseDataConnect.LocalDate Timestamp FirebaseCore.Timestamp Int64 Int64 Any FirebaseDataConnect.AnyValue