ใช้ Flutter SDK ที่สร้างขึ้น

SDK ของไคลเอ็นต์ Firebase SQL Connect ช่วยให้คุณเรียกใช้การค้นหาและการเปลี่ยนแปลงฝั่งเซิร์ฟเวอร์ได้โดยตรงจากแอป Firebase คุณสร้าง SDK ของไคลเอ็นต์ที่กำหนดเองควบคู่ไปกับการออกแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่ติดตั้งใช้งานในบริการ SQL Connect จากนั้นคุณจะผสานรวมเมธอดจาก SDK นี้เข้ากับตรรกะไคลเอ็นต์

ดังที่เราได้กล่าวไว้ในที่อื่น สิ่งสำคัญที่ควรทราบคือSQL Connect โค้ดฝั่งไคลเอ็นต์ไม่ได้ส่งการค้นหาและการเปลี่ยนแปลง และไม่ได้ดำเนินการบนเซิร์ฟเวอร์ แต่เมื่อติดตั้งใช้งาน ระบบจะจัดเก็บการดำเนินการ SQL Connect ไว้ในเซิร์ฟเวอร์ เช่น Cloud Functions ซึ่งหมายความว่าคุณต้องติดตั้งใช้งานการเปลี่ยนแปลงฝั่งไคลเอ็นต์ที่เกี่ยวข้องเพื่อหลีกเลี่ยงไม่ให้ผู้ใช้เดิมได้รับผลกระทบ (เช่น ในแอปเวอร์ชันเก่า)

ด้วยเหตุนี้ SQL Connect จึงมีสภาพแวดล้อมในการพัฒนาซอฟต์แวร์และเครื่องมือที่ช่วยให้คุณสร้างต้นแบบสคีมา คำค้นหา และการเปลี่ยนแปลงที่ติดตั้งใช้งานบนเซิร์ฟเวอร์ได้ นอกจากนี้ยังสร้าง SDK ฝั่งไคลเอ็นต์โดยอัตโนมัติขณะที่คุณสร้างต้นแบบ

เมื่อคุณอัปเดตบริการและแอปไคลเอ็นต์ซ้ำแล้ว การอัปเดตทั้งฝั่งเซิร์ฟเวอร์และฝั่งไคลเอ็นต์ก็พร้อมที่จะทำให้ใช้งานได้

เวิร์กโฟลว์การพัฒนาไคลเอ็นต์คืออะไร

หากทำตามขั้นตอนในเริ่มต้นใช้งาน คุณจะเห็นขั้นตอนการพัฒนาโดยรวมสำหรับ SQL Connect ในคู่มือนี้ คุณจะพบข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับการสร้าง Flutter SDK จากสคีมาและการทำงานกับคำค้นหาและการเปลี่ยนแปลงของไคลเอ็นต์

โดยสรุปแล้ว หากต้องการใช้ Flutter SDK ที่สร้างขึ้นในแอปไคลเอ็นต์ คุณจะต้องทำตามขั้นตอนเบื้องต้นต่อไปนี้

1. เพิ่ม Firebase ลงในแอป Flutter
2. ติดตั้ง flutterfire CLI dart pub global activate flutterfire_cli
3. วิ่ง flutterfire configure

จากนั้นให้ทำดังนี้

1. พัฒนาสคีมาแอป

2. ตั้งค่าการสร้าง SDK โดยทำดังนี้

   • ใช้ปุ่มเพิ่ม SDK ลงในแอปในส่วนขยาย VS Code ของ SQL Connect
   • อัปเดต connector.yaml

3. เริ่มต้นโค้ดไคลเอ็นต์และนำเข้าไลบรารี

4. ใช้การเรียกใช้การค้นหาและการเปลี่ยนแปลง

5. ตั้งค่าและใช้โปรแกรมจำลอง SQL Connect และทำซ้ำ

สร้าง Flutter SDK

ใช้ Firebase CLI เพื่อตั้งค่า SDK ที่สร้างโดย SQL Connect ในแอป คำสั่ง init ควรตรวจหาแอปทั้งหมดในโฟลเดอร์ปัจจุบันและติดตั้ง SDK ที่สร้างขึ้นโดยอัตโนมัติ

firebase init dataconnect:sdk

อัปเดต SDK ขณะสร้างต้นแบบ

หากคุณติดตั้งส่วนขยาย SQL Connect VS Code ไว้ ส่วนขยายนี้จะอัปเดต SDK ที่สร้างขึ้นให้เป็นเวอร์ชันล่าสุดเสมอ

หากไม่ได้ใช้ส่วนขยาย SQL Connect VS Code คุณสามารถใช้ Firebase CLI เพื่ออัปเดต SDK ที่สร้างขึ้นให้เป็นปัจจุบันอยู่เสมอ

firebase dataconnect:sdk:generate --watch

สร้าง SDK ในไปป์ไลน์บิลด์

คุณใช้ Firebase CLI เพื่อสร้าง SDK ของ SQL Connect ในกระบวนการบิลด์ CI/CD ได้

firebase dataconnect:sdk:generate

ตั้งค่ารหัสไคลเอ็นต์

เริ่มต้นแอป SQL Connect

ก่อนอื่น ให้เริ่มต้นแอปโดยใช้วิธีการตั้งค่า Firebase มาตรฐาน

จากนั้นติดตั้งปลั๊กอิน SQL Connect โดยทำดังนี้

flutter pub add firebase_data_connect

เริ่มต้นใช้งาน SQL Connect Flutter SDK

เริ่มต้นอินสแตนซ์ SQL Connect โดยใช้ข้อมูลที่คุณใช้ตั้งค่า SQL Connect ดูข้อมูลนี้ได้ในหน้าฐานข้อมูลและพื้นที่เก็บข้อมูล > SQL Connect ของคอนโซล Firebase

นำเข้าไลบรารี

คุณต้องนำเข้า 2 ชุดเพื่อเริ่มต้นโค้ดไคลเอ็นต์ ได้แก่ การนำเข้า SQL Connect ทั่วไปและการนำเข้า SDK ที่สร้างขึ้นโดยเฉพาะ

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

ใช้การค้นหาฝั่งไคลเอ็นต์

โค้ดที่สร้างขึ้นจะมาพร้อมกับ Query Ref ที่กำหนดไว้ล่วงหน้าอยู่แล้ว คุณเพียงต้องนำเข้าและเรียกใช้ execute ในเมธอดเหล่านั้น

import 'generated/movies.dart';

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

เรียกใช้เมธอดการค้นหา SDK

ตัวอย่างการใช้ฟังก์ชันทางลัดการดำเนินการมีดังนี้

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();
}

ฟิลด์ที่ไม่บังคับ

การค้นหาบางรายการอาจมีช่องที่ไม่บังคับ ในกรณีเหล่านี้ Flutter SDK จะแสดงเมธอด Builder และจะต้องตั้งค่าแยกต่างหาก

เช่น ช่อง rating จะระบุหรือไม่ก็ได้เมื่อเรียกใช้ createMovie ดังนั้นคุณจึงต้องระบุช่องดังกล่าวในฟังก์ชัน Builder

await MoviesConnector.instance.createMovie( title: 'Empire Strikes Back', releaseYear: 1980, genre: 'Sci-Fi').rating(5).execute();

ติดตามการเปลี่ยนแปลง

ดูหัวข้อรับข้อมูลอัปเดตแบบเรียลไทม์จาก SQL Connect

จัดการการเปลี่ยนแปลงในช่องการแจงนับ

สคีมาของแอปสามารถมีการแจงนับ ซึ่งเข้าถึงได้โดยการค้นหา GraphQL

เมื่อการออกแบบของแอปเปลี่ยนไป คุณอาจเพิ่มค่าที่รองรับ enum ใหม่ ตัวอย่างเช่น สมมติว่าในวงจรของแอปพลิเคชันในภายหลัง คุณตัดสินใจเพิ่มค่า FULLSCREEN ลงใน enum AspectRatio

ในเวิร์กโฟลว์ SQL Connect คุณสามารถใช้เครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ในเครื่องเพื่ออัปเดตการค้นหาและ SDK

อย่างไรก็ตาม ก่อนที่คุณจะเผยแพร่ไคลเอ็นต์เวอร์ชันอัปเดต ไคลเอ็นต์เวอร์ชันเก่าที่ติดตั้งใช้งานอาจใช้งานไม่ได้

ตัวอย่างการใช้งานที่ยืดหยุ่น

SDK ที่สร้างขึ้นจะบังคับให้จัดการค่าที่ไม่รู้จัก กล่าวคือ โค้ดไคลเอ็นต์ต้องแยกออบเจ็กต์ EnumValue ออกเป็น Known หรือ 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}');
  }
}

เปิดใช้การแคชฝั่งไคลเอ็นต์

SQL Connect มีฟีเจอร์การแคชฝั่งไคลเอ็นต์ที่ไม่บังคับ ซึ่งคุณเปิดใช้ได้โดยแก้ไขไฟล์ connector.yaml เมื่อเปิดใช้ฟีเจอร์นี้ SDK ไคลเอ็นต์ที่สร้างขึ้นจะแคชการตอบกลับการค้นหาไว้ในเครื่อง ซึ่งจะช่วยลดจำนวนคำขอฐานข้อมูลที่แอปสร้างขึ้น และช่วยให้ส่วนที่ขึ้นอยู่กับฐานข้อมูลของแอปทำงานได้เมื่อความพร้อมใช้งานของเครือข่ายถูกขัดจังหวะ

หากต้องการเปิดใช้การแคชฝั่งไคลเอ็นต์ ให้เพิ่มการกำหนดค่าการแคชของไคลเอ็นต์ลงในการกำหนดค่าเครื่องมือเชื่อมต่อ โดยทำดังนี้

generate:
  javascriptSdk:
    outputDir: ../dart/
    package: "dataconnect_generated"
    clientCache:
      maxAge: 5s
      storage: memory

การกำหนดค่านี้มีพารามิเตอร์ 2 รายการ ซึ่งไม่บังคับทั้งคู่ ได้แก่

• maxAge: อายุสูงสุดที่การตอบกลับที่แคชไว้สามารถมีได้ก่อนที่ SDK ของไคลเอ็นต์จะดึงค่าใหม่ ตัวอย่างเช่น "0", "30s", "1h30m"

  ค่าเริ่มต้นสำหรับ maxAge คือ 0 ซึ่งหมายความว่าระบบจะแคชการตอบกลับ แต่ SDK ของไคลเอ็นต์จะดึงข้อมูลค่าใหม่เสมอ ระบบจะใช้ค่าที่แคชไว้เมื่อมีการระบุ CACHE_ONLY เป็น execute() และผลลัพธ์เริ่มต้นที่แสดงผลจาก subscribe() เท่านั้น

• storage: คุณสามารถกำหนดค่า SDK ของไคลเอ็นต์ให้แคชการตอบกลับในพื้นที่เก็บข้อมูล persistent หรือใน memory ได้ ผลลัพธ์ที่แคชไว้ในพื้นที่เก็บข้อมูล persistent จะยังคงอยู่แม้จะรีสตาร์ทแอป เมื่อกำหนดเป้าหมายเป็น Android หรือ iOS ค่าเริ่มต้นจะเป็น persistent เมื่อกำหนดเป้าหมายเป็นเว็บเบราว์เซอร์ ระบบจะรองรับเฉพาะพื้นที่เก็บข้อมูล memory เท่านั้น

หลังจากอัปเดตการกำหนดค่าการแคชของเครื่องมือเชื่อมต่อแล้ว ให้สร้าง SDK ของไคลเอ็นต์ใหม่และสร้างแอปอีกครั้ง เมื่อดำเนินการเสร็จแล้ว execute() และ subscribe() จะแคชการตอบกลับและใช้ค่าที่แคชไว้ตามนโยบายที่คุณกำหนดค่าไว้ โดยทั่วไปแล้ว การดำเนินการนี้จะเกิดขึ้นโดยอัตโนมัติโดยที่คุณไม่ต้องดำเนินการใดๆ เพิ่มเติม แต่โปรดทราบข้อมูลต่อไปนี้

• ลักษณะการทำงานเริ่มต้นของ execute() เป็นไปตามที่อธิบายไว้ข้างต้น กล่าวคือ หากมีการแคชผลลัพธ์สำหรับคำค้นหาและค่าที่แคชไว้ไม่เก่ากว่า maxAge ระบบจะใช้ค่าที่แคชไว้ ลักษณะการทำงานเริ่มต้นนี้เรียกว่านโยบาย PREFER_CACHE

  นอกจากนี้ คุณยังระบุการเรียกใช้ execute() แต่ละครั้งให้แสดงเฉพาะค่าที่แคชไว้ (CACHE_ONLY) หรือดึงข้อมูลค่าใหม่จากเซิร์ฟเวอร์โดยไม่มีเงื่อนไข (SERVER_ONLY) ได้ด้วย

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

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

• เมื่อคุณเรียกใช้ subscribe() ระบบจะแสดงผลเนื้อหาที่แคชไว้ทันทีเสมอหากมี โดยไม่คำนึงถึงการตั้งค่า maxAge การเรียกใช้ execute() ในครั้งต่อๆ ไปจะแจ้งเตือน Listener ตาม maxAge ที่กำหนดค่าไว้

ใช้การกลายพันธุ์ในฝั่งไคลเอ็นต์

คุณเข้าถึงการกลายพันธุ์ได้ในลักษณะเดียวกับการค้นหา

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

สร้างต้นแบบและทดสอบแอป Flutter

เครื่องมือไคลเอ็นต์เพื่อใช้โปรแกรมจำลองในเครื่อง

คุณสามารถใช้โปรแกรมจำลอง SQL Connect ไม่ว่าจะจากส่วนขยาย SQL Connect VS Code หรือจาก CLI

การใช้เครื่องมือในแอปเพื่อเชื่อมต่อกับโปรแกรมจำลองจะเหมือนกันสำหรับทั้ง 2 สถานการณ์

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();

หากต้องการเปลี่ยนไปใช้ทรัพยากรเวอร์ชันที่ใช้งานจริง ให้ทำเครื่องหมายบรรทัดสำหรับการเชื่อมต่อกับโปรแกรมจำลองเป็นความคิดเห็น

ประเภทข้อมูลใน Dart SDK

เซิร์ฟเวอร์ SQL Connect แสดงประเภทข้อมูล GraphQL ทั่วไป ซึ่งจะแสดงใน SDK ดังนี้