SDK máy khách Firebase SQL Connect cho phép bạn gọi các truy vấn và đột biến phía máy chủ trực tiếp từ một ứng dụng Firebase. Bạn tạo một SDK máy khách tuỳ chỉnh song song khi thiết kế các lược đồ, truy vấn và đột biến mà bạn triển khai cho dịch vụ SQL Connect. Sau đó, bạn tích hợp các phương thức từ SDK này vào logic máy khách.
Như chúng tôi đã đề cập ở nơi khác, bạn cần lưu ý rằng SQL Connect các truy vấn và đột biến không được mã máy khách gửi và không được thực thi trên máy chủ. Thay vào đó, khi được triển khai, các thao tác SQL Connect sẽ được lưu trữ trên máy chủ như Cloud Functions. Điều này có nghĩa là bạn cần triển khai các thay đổi tương ứng ở phía máy khách để tránh làm hỏng người dùng hiện tại (ví dụ: trên các phiên bản ứng dụng cũ hơn).
Đó là lý do SQL Connect cung cấp cho bạn một môi trường phát triển và công cụ cho phép bạn tạo nguyên mẫu các lược đồ, truy vấn và đột biến được triển khai trên máy chủ. Công cụ này cũng tự động tạo SDK phía máy khách trong khi bạn tạo nguyên mẫu.
Khi bạn đã lặp lại các bản cập nhật cho dịch vụ và ứng dụng máy khách, cả bản cập nhật phía máy chủ và phía máy khách đều đã sẵn sàng để triển khai.
Quy trình phát triển máy khách là gì?
Nếu bạn đã làm theo phần Bắt đầu, bạn sẽ được giới thiệu về quy trình phát triển tổng thể cho SQL Connect. Trong hướng dẫn này, bạn sẽ tìm thấy thông tin chi tiết hơn về việc tạo SDK Swift từ lược đồ và làm việc với các truy vấn và đột biến của máy khách.
Tóm lại, để sử dụng các SDK Swift đã tạo trong ứng dụng máy khách, bạn sẽ làm theo các bước tiên quyết sau:
- Thêm Firebase vào ứng dụng iOS.
Để sử dụng SDK đã tạo, hãy định cấu hình SDK đó làm phần phụ thuộc trong Xcode.
Trong thanh điều hướng trên cùng của Xcode, hãy chọn File > Add Package Dependencies > Add Local (Tệp > Thêm phần phụ thuộc gói > Thêm cục bộ) rồi chọn thư mục chứa
Package.swiftđã tạo.
Sau đó:
- Phát triển lược đồ ứng dụng.
Thiết lập quá trình tạo SDK:
- Với nút Add SDK to app (Thêm SDK vào ứng dụng) trong tiện ích SQL Connect VS Code
- Bằng cách cập nhật
connector.yaml
Thiết lập và sử dụng trình mô phỏng SQL Connect rồi lặp lại.
Tạo SDK Swift
Sử dụng Firebase CLI để thiết lập các SDK do SQL Connect tạo trong ứng dụng của bạn.
Lệnh init sẽ phát hiện tất cả ứng dụng trong thư mục hiện tại và tự động cài đặt các SDK đã tạo.
firebase init dataconnect:sdk
Cập nhật SDK trong khi tạo nguyên mẫu
Nếu bạn đã cài đặt tiện ích SQL Connect VS Code, tiện ích này sẽ luôn cập nhật các SDK đã tạo.
Nếu không sử dụng tiện ích SQL Connect VS Code, bạn có thể sử dụng Firebase CLI để cập nhật các SDK đã tạo.
firebase dataconnect:sdk:generate --watchTạo SDK trong quy trình xây dựng
Bạn có thể sử dụng Firebase CLI để tạo SQL Connect SDK trong các quy trình xây dựng CI/CD.
firebase dataconnect:sdk:generateKhởi động SDK iOS SQL Connect
Khởi động thực thể SQL Connect bằng thông tin bạn đã dùng để thiết lập SQL Connect. Tìm thông tin này trong trang Databases & Storage > SQL Connect của bảng điều khiển Firebase.
Nhận thực thể trình kết nối
Mã cho trình kết nối của bạn sẽ được trình mô phỏng
SQL Connect tạo. Nếu tên trình kết nối của bạn là movies và gói là movies, như được chỉ định trong connector.yaml, thì hãy truy xuất đối tượng trình kết nối bằng cách gọi:
let connector = DataConnect.moviesConnector
Triển khai các truy vấn và đột biến
Với đối tượng trình kết nối, bạn có thể chạy các truy vấn và đột biến như được xác định trong mã nguồn GraphQL. Giả sử trình kết nối của bạn đã xác định các thao tác sau:
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
}
}
Sau đó, bạn có thể tạo một bộ phim như sau:
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)")
Để truy xuất một bộ phim, bạn sẽ sử dụng tham chiếu truy vấn. Tất cả tham chiếu truy vấn đều là nhà xuất bản có thể quan sát được. Tuỳ thuộc vào nhà xuất bản đã định cấu hình (xem connector.yaml),
các nhà xuất bản này sẽ hỗ trợ macro @Observable (iOS 17 trở lên) hoặc triển khai giao thức
ObservableObject. Giá trị mặc định (nếu không có giá trị nào được chỉ định) là macro @Observable được hỗ trợ trên iOS 17 trở lên.
Trong chế độ xem SwiftUI, bạn có thể liên kết kết quả truy vấn bằng cách sử dụng biến data đã xuất bản của tham chiếu truy vấn và gọi phương thức execute() của truy vấn để cập nhật dữ liệu. Biến data sẽ khớp với hình dạng của dữ liệu đã được xác định trong định nghĩa truy vấn GQL.
Tất cả kết quả đã truy xuất đều tuân thủ giao thức Decodable. Nếu bạn đã đưa khoá chính của đối tượng vào lượt tìm nạp GQL, thì các đối tượng cũng sẽ Identifiable, cho phép bạn sử dụng các đối tượng này trong trình vòng lặp.
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()
}
}
Các truy vấn cũng hỗ trợ thực thi một lần.
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
Đăng ký nhận thông báo khi có thay đổi
Xem bài viết Nhận thông tin cập nhật theo thời gian thực từ SQL Connect.
Xử lý các thay đổi đối với trường liệt kê
Lược đồ của ứng dụng có thể chứa các giá trị liệt kê, mà truy vấn GraphQL có thể truy cập.
Khi thiết kế của ứng dụng thay đổi, bạn có thể thêm các giá trị được hỗ trợ cho giá trị liệt kê mới. Ví dụ: hãy tưởng tượng rằng sau này trong vòng đời của ứng dụng, bạn quyết định thêm giá trị FULLSCREEN vào giá trị liệt kê AspectRatio.
Trong quy trình SQL Connect, bạn có thể sử dụng công cụ phát triển cục bộ để cập nhật các truy vấn và SDK.
Tuy nhiên, trước khi bạn phát hành phiên bản cập nhật của máy khách, các máy khách đã triển khai cũ có thể bị hỏng.
Ví dụ về cách triển khai linh hoạt
SDK đã tạo buộc phải xử lý các giá trị không xác định vì các giá trị liệt kê đã tạo chứa giá trị _UNKNOWN và Swift thực thi các câu lệnh chuyển đổi toàn diện.
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
}
Bật tính năng lưu vào bộ nhớ đệm phía máy khách
SQL Connect có tính năng lưu vào bộ nhớ đệm phía máy khách không bắt buộc. Bạn
có thể bật tính năng này bằng cách chỉnh sửa tệp connector.yaml Khi tính năng này được bật, các SDK máy khách đã tạo sẽ lưu vào bộ nhớ đệm cục bộ các phản hồi truy vấn. Điều này có thể giảm số lượng yêu cầu cơ sở dữ liệu mà ứng dụng của bạn thực hiện và cho phép các phần phụ thuộc vào cơ sở dữ liệu của ứng dụng hoạt động khi khả năng kết nối mạng bị gián đoạn.
Để bật tính năng lưu vào bộ nhớ đệm phía máy khách, hãy thêm cấu hình lưu vào bộ nhớ đệm phía máy khách vào cấu hình trình kết nối:
generate:
swiftSdk:
outputDir: "../ios"
package: "FirebaseDataConnectGenerated"
clientCache:
maxAge: 5s
storage: persistent
Cấu hình này có 2 tham số, cả hai đều không bắt buộc:
maxAge: Tuổi tối đa mà phản hồi được lưu vào bộ nhớ đệm có thể có trước khi SDK máy khách tìm nạp các giá trị mới. Ví dụ: "0", "30s", "1h30m".Giá trị mặc định cho
maxAgelà0. Điều này có nghĩa là các phản hồi được lưu vào bộ nhớ đệm, nhưng SDK máy khách sẽ luôn tìm nạp các giá trị mới. Các giá trị được lưu vào bộ nhớ đệm sẽ chỉ được sử dụng khiCACHE_ONLYđược chỉ định choexecute().storage: Bạn có thể định cấu hình SDK máy khách để lưu vào bộ nhớ đệm các phản hồi trong bộ nhớpersistenthoặc trongmemory. Kết quả được lưu vào bộ nhớ đệm trong bộ nhớpersistentsẽ tồn tại trong các lần khởi động lại ứng dụng. Trong SDK iOS, giá trị mặc định làpersistent.
Sau khi cập nhật cấu hình lưu vào bộ nhớ đệm của trình kết nối, hãy tạo lại các SDK
máy khách và xây dựng lại ứng dụng. Sau khi bạn thực hiện việc này, execute()
sẽ lưu vào bộ nhớ đệm các
phản hồi và sử dụng các giá trị được lưu vào bộ nhớ đệm theo chính sách mà bạn đã định cấu hình. Quá trình này thường diễn ra tự động mà bạn không cần thực hiện thêm bước nào. Tuy nhiên, hãy lưu ý những điều sau:
Hành vi mặc định của
execute()như mô tả ở trên: nếu một kết quả được lưu vào bộ nhớ đệm cho một truy vấn và giá trị được lưu vào bộ nhớ đệm không cũ hơnmaxAge, thì hãy sử dụng giá trị được lưu vào bộ nhớ đệm. Hành vi mặc định này được gọi là chính sáchPREFER_CACHE.Bạn cũng có thể chỉ định cho từng lệnh gọi
execute()để chỉ phân phát các giá trị được lưu vào bộ nhớ đệm (CACHE_ONLY) hoặc để tìm nạp vô điều kiện các giá trị mới từ máy chủ (SERVER_ONLY).try await execute(fetchPolicy: .cacheOnly)try await execute(fetchPolicy: .serverOnly)Tạo nguyên mẫu và kiểm thử ứng dụng iOS
Gắn mã theo dõi ứng dụng để sử dụng trình mô phỏng cục bộ
Bạn có thể sử dụng trình mô phỏng SQL Connect, cho dù là từ tiện ích SQL Connect VS Code hay từ CLI.
Việc thiết bị ứng dụng để kết nối với trình mô phỏng là giống nhau đối với cả hai trường hợp.
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 appCác loại dữ liệu trong SDK SQL Connect
Máy chủ SQL Connect đại diện cho các loại dữ liệu GraphQL phổ biến và tuỳ chỉnh. Các loại dữ liệu này được biểu thị trong SDK như sau.
SQL Connect Loại Swift Chuỗi Chuỗi Int Int Nổi Giường đôi Boolean Bool mã nhận dạng duy nhất (UUID) mã nhận dạng duy nhất (UUID) Ngày FirebaseDataConnect.LocalDate Dấu thời gian FirebaseCore.Timestamp Int64 Int64 Bất kỳ FirebaseDataConnect.AnyValue