Sử dụng các SDK Flutter đã tạo

SDK ứng dụng Firebase SQL Connect cho phép bạn gọi các truy vấn và đột biến phía máy chủ ngay từ một ứng dụng Firebase. Bạn tạo một SDK ứng dụng tuỳ chỉnh song song khi thiết kế giản đồ, truy vấn và đột biến mà bạn triển khai cho dịch vụ SQL Connect của mình. Sau đó, bạn tích hợp các phương thức từ SDK này vào logic ứng dụng.

Như chúng tôi đã đề cập ở phần khác, điều quan trọng cần lưu ý là SQL Connect mã ứng dụng khách không gửi truy vấn và đột biến, đồng thời không 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 gián đoạn người dùng hiện tại (ví dụ: trên các phiên bản ứng dụng cũ).

Đó 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ụ, giúp bạn tạo nguyên mẫu cho 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à phía máy khách đều sẵn sàng để triển khai.

Quy trình phát triển ứng dụng là gì?

Nếu đã làm theo hướng dẫ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ề cách tạo SDK Flutter từ giản đồ và làm việc với các truy vấn và đột biến của ứng dụng.

Tóm lại, để sử dụng SDK Flutter được tạo trong ứng dụng khách, bạn cần làm theo các bước tiên quyết sau:

1. Thêm Firebase vào ứng dụng Flutter.
2. Cài đặt flutterfire CLI dart pub global activate flutterfire_cli.
3. Chạy flutterfire configure.

Sau đó:

1. Phát triển giản đồ ứng dụng.

2. Thiết lập tính năng 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.

3. Khởi động mã ứng dụng khách và nhập thư viện.

4. Triển khai lệnh gọi đến truy vấn và thay đổi.

5. 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 CLI Firebase để thiết lập 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 SDK đã tạo.

firebase init dataconnect:sdk

Cập nhật SDK trong khi tạo bản minh hoạ

Nếu bạn đã cài đặt tiện ích SQL Connect VS Code, thì 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ể dùng Giao diện dòng lệnh (CLI) của Firebase để luôn cập nhật các SDK được tạo.

firebase dataconnect:sdk:generate --watch

Tạo SDK trong quy trình xây dựng

Bạn có thể sử dụng Giao diện dòng lệnh (CLI) của Firebase để tạo SDK SQL Connect trong quy trình xây dựng CI/CD.

firebase dataconnect:sdk:generate

Thiết lập mã ứng dụng khách

Khởi chạy ứng dụng SQL Connect

Trước tiên, hãy khởi chạy ứng dụng của bạn 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_connect

Khởi chạy SDK SQL Connect Flutter

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 (Cơ sở dữ liệu và bộ nhớ) > SQL Connect (Kết nối SQL) của bảng điều khiển Firebase.

Nhập thư viện

Có hai nhóm lệnh nhập cần thiết để khởi động mã ứng dụng, lệnh nhập chung SQL Connect và lệnh nhập SDK cụ thể, được 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 máy khách

Mã được 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 thành phần đó.

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

Gọi phương thức truy vấn SDK

Dưới đây là ví dụ về cách sử dụng các hàm phím tắt 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, Flutter SDK sẽ hiển thị một phương thức trình tạo và phải được đặt 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 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 về cá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ê

Giản đồ của ứng dụng có thể chứa các kiểu liệt kê mà truy vấn GraphQL của bạn 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ợ mới cho enum. 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 làm việc SQL Connect, bạn có thể sử dụng công cụ cho nhà 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, các ứng dụng cũ đã triển khai có thể bị hỏng.

Ví dụ về cách triển khai linh hoạt

SDK được tạo sẽ buộc xử lý các giá trị không xác định. Tức là mã ứng dụng khách phải huỷ 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ó tính năng lưu vào bộ nhớ đệm phía máy khách (không bắt buộc) mà bạn có thể bật bằng cách chỉnh sửa tệp connector.yaml. Khi bạn bật tính năng này, SDK ứng dụng được tạo sẽ lưu phản hồi truy vấn vào bộ nhớ đệm cục bộ. Việc 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 đưa ra 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 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:
  javascriptSdk:
    outputDir: ../dart/
    package: "dataconnect_generated"
    clientCache:
      maxAge: 5s
      storage: memory

Cấu hình này có hai 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 tìm nạp các giá trị mới. Ví dụ: "0", "30s", "1h30m".

  Giá trị mặc định cho maxAge là 0, nghĩa là các phản hồi được lưu vào bộ nhớ đệm, nhưng SDK ứng dụng 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 khi CACHE_ONLY được chỉ định cho execute() 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 để lưu phản hồi vào bộ nhớ đệm trong bộ nhớ persistent hoặc trong memory. Kết quả được lưu vào bộ nhớ đệm trong bộ nhớ persistent sẽ được giữ lạ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 mới được hỗ trợ.

Sau khi bạn 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 SDK ứng dụng và tạo lại ứng dụng. Sau khi bạn thực hiện việc này, execute() và subscribe() sẽ lưu phản hồi vào bộ nhớ đệm 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. Việc này thường diễn ra tự động mà không cần bạ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 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ơn maxAge, 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ách PREFER_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ủ (SERVER_ONLY) mà không cần điều kiện.

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);
  

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);
  

• Khi bạn gọi subscribe(), hàm này sẽ luôn trả về ngay nội dung đã lưu vào bộ nhớ đệm (nếu có), bất kể chế độ cài đặt maxAge. Các lệnh gọi tiếp theo đến execute() sẽ thông báo cho trình nghe theo maxAge đã định cấu hình.

Sử dụng đột biến ở phía máy 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

Thiết lập ứ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, thông qua tiện ích SQL Connect VS Code hoặc qua CLI.

Việc đo lường ứ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 chính thức, hãy đánh dấu là nội dung 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 Dart SDK

Máy chủ SQL Connect đại diện cho các loại dữ liệu GraphQL phổ biến. Các trạng thái này được biểu thị trong SDK như sau.