SDK ứng dụng 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 ứng dụng 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 ứng dụng 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ã ứng dụng khách gửi và 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 và công cụ dành cho nhà phát triển, 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 khách, cả bản cập nhật ở phía máy chủ và ứng dụng khách đều sẵn sàng triển khai.
Quy trình phát triển ứng dụng khách là gì?
Nếu bạn đã làm theo phần Bắt đầu, bạn đã đượ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 Flutter từ lược đồ và làm việc với các truy vấn và đột biến của ứng dụng khách.
Tóm lại, để sử dụng SDK Flutter đã tạo trong ứng dụng 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 Flutter.
- Cài đặt CLI flutterfire
dart pub global activate flutterfire_cli. - Chạy
flutterfire configure.
Sau đó:
- Phát triển lược đồ ứng dụng.
Thiết lập quá trình tạo SDK:
- Bằng 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 Flutter
Sử dụng Firebase CLI để thiết lập các SDK do SQL Connect tạo trong ứng dụng.
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 quy trình xây dựng CI/CD.
firebase dataconnect:sdk:generateThiết lập mã ứng dụng khách
Khởi động ứng dụng SQL Connect
Trước tiên, hãy khởi động ứng dụng bằng cách làm theo hướng dẫn thiết lập Firebase tiêu chuẩn.
Sau đó, hãy cài đặt trình bổ trợ SQL Connect:
flutter pub add firebase_data_connectKhởi động SDK Flutter 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ập các thư viện
Bạn cần nhập 2 nhóm để khởi động mã ứng dụng khách, nhóm nhập chung SQL Connect và nhóm nhập SDK cụ thể đã tạo.
// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';
// generated queries and mutations from SDK
import 'generated/movies.dart';
Sử dụng truy vấn ở phía ứng dụng khách
Mã đã tạo sẽ đi kèm với các Tham chiếu truy vấn được xác định trước. Bạn chỉ cần nhập và gọi execute trên các tham chiếu đó.
import 'generated/movies.dart';
await MoviesConnector.instance.listMovies().execute();
Gọi các phương thức truy vấn SDK
Dưới đây là ví dụ về cách sử dụng các hàm lối tắt cho thao tác này:
import 'generated/movies.dart';
function onBtnClick() {
// This will call the generated Dart from the CLI and then make an HTTP request to the server.
MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}
Trường tuỳ chọn
Một số truy vấn có thể có các trường tuỳ chọn. Trong những trường hợp này, SDK Flutter sẽ hiển thị một phương thức trình tạo và bạn sẽ phải thiết lập riêng.
Ví dụ: trường rating là không bắt buộc khi gọi createMovie, vì vậy, bạn cần cung cấp trường này trong hàm trình tạo.
await MoviesConnector.instance.createMovie( title: 'Empire Strikes Back', releaseYear: 1980, genre: 'Sci-Fi').rating(5).execute();
Đă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ế ứng dụng thay đổi, bạn có thể thêm các giá trị được hỗ trợ cho enum mới. Ví dụ: giả sử sau này trong vòng đời của ứng dụng, bạn quyết định thêm giá trị FULLSCREEN vào enum 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 ứng dụng khách, các ứng dụng khách đã triển khai trước đó có thể bị hỏng.
Ví dụ về cách triển khai linh hoạt
SDK đã tạo sẽ buộc bạn phải xử lý các giá trị không xác định. Tức là mã ứng dụng khách phải mở gói đối tượng EnumValue thành Known hoặc Unknown.
final result = await MoviesConnector.instance.listMovies().execute();
if (result.data != null && result.data!.isNotEmpty) {
handleEnumValue(result.data![0].aspectratio);
}
void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
if (aspectValue.value != null) {
switch(aspectValue.value!) {
case AspectRatio.ACADEMY:
print('This movie is in Academy aspect');
break;
case AspectRatio.WIDESCREEN:
print('This movie is in Widescreen aspect');
break;
case AspectRatio.ANAMORPHIC:
print('This movie is in Anamorphic aspect');
break;
case AspectRatio.IMAX:
print('This movie is in IMAX aspect');
}
} else {
print('Unknown aspect ratio detected: ${aspectValue.stringValue}');
}
}
Bật tính năng lưu vào bộ nhớ đệm ở phía máy khách
SQL Connect có một 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 ứng dụng 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ể làm 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ông có mạng.
Để 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:
javascriptSdk:
outputDir: ../dart/
package: "dataconnect_generated"
clientCache:
maxAge: 5s
storage: memory
Cấu hình này có 2 tham số, cả hai đều không bắt buộc:
maxAge: Thời gian tối đa mà một phản hồi được lưu vào bộ nhớ đệm có thể tồn tại trước khi SDK ứng dụng 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 ứng dụng 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()và kết quả ban đầu được trả về từsubscribe().storage: Bạn có thể định cấu hình SDK ứng dụng khách để lưu vào bộ nhớ đệm các phản hồi trong bộ nhớpersistenthoặc trongmemory. Các 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. Khi nhắm đến Android hoặc iOS, giá trị mặc định làpersistent. Khi nhắm đến trình duyệt web, chỉ bộ nhớmemoryđược hỗ trợ.
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 ứng dụng 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() và subscribe() 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 các giá trị mới từ máy chủ một cách vô điều kiện (SERVER_ONLY).await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);Khi bạn gọi
subscribe(), lệnh này sẽ luôn trả về ngay nội dung được lưu vào bộ nhớ đệm (nếu có), bất kể chế độ cài đặtmaxAge. Các lệnh gọi tiếp theo đếnexecute()sẽ thông báo cho trình nghe theomaxAgeđã định cấu hình.
Sử dụng đột biến ở phía ứng dụng khách
Bạn có thể truy cập vào các đột biến theo cách tương tự như truy vấn.
await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
Tạo nguyên mẫu và kiểm thử ứng dụng Flutter
Gắn mã theo dõi ứng dụng khách để 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 lập ứng dụng để kết nối với trình mô phỏng là giống nhau cho cả hai trường hợp.
import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';
MoviesConnector.instance.dataConnect
.useDataConnectEmulator('127.0.0.1', 9399);
// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();
Để chuyển sang tài nguyên sản xuất, hãy nhận xét các dòng để kết nối với trình mô phỏng.
Các loại dữ liệu trong SDK Dart
Máy chủ SQL Connect đại diện cho các loại dữ liệu GraphQL phổ biến. Các loại dữ liệu này được biểu thị trong SDK như sau.
| SQL Connect Loại | Dart |
|---|---|
| Dấu thời gian | firebase_data_connect.Timestamp |
| Int (32 bit) | int |
| Ngày | DateTime |
| Mã nhận dạng duy nhất (UUID) | chuỗi |
| Int64 | int |
| Nổi | hai nét |
| Boolean | bool |
| Bất kỳ | firebase_data_connect.AnyValue |