از Flutter SDK های تولید شده استفاده کنید

کیت‌های توسعه نرم‌افزار (SDK) کلاینت Firebase Data Connect به شما امکان می‌دهند کوئری‌ها و جهش‌های سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. شما همزمان با طراحی طرحواره‌ها، کوئری‌ها و جهش‌هایی که در سرویس Data Connect خود پیاده‌سازی می‌کنید، یک SDK کلاینت سفارشی ایجاد می‌کنید. سپس، متدهای این SDK را در منطق کلاینت خود ادغام می‌کنید.

همانطور که در جای دیگری اشاره کردیم، توجه به این نکته مهم است که کوئری‌ها و جهش‌های Data Connect توسط کد کلاینت ارسال و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، عملیات Data Connect مانند توابع ابری روی سرور ذخیره می‌شوند. این بدان معناست که برای جلوگیری از اختلال در عملکرد کاربران موجود (به عنوان مثال، در نسخه‌های قدیمی‌تر برنامه)، باید تغییرات مربوطه در سمت کلاینت را اعمال کنید.

به همین دلیل است که Data Connect یک محیط توسعه‌دهنده و ابزار در اختیار شما قرار می‌دهد که به شما امکان می‌دهد طرح‌ها، کوئری‌ها و جهش‌های مستقر در سرور خود را نمونه‌سازی کنید. همچنین، همزمان با نمونه‌سازی شما، SDKهای سمت کلاینت را به طور خودکار تولید می‌کند.

وقتی به‌روزرسانی‌های مکرر را برای سرویس و برنامه‌های کلاینت خود انجام دادید، به‌روزرسانی‌های سمت سرور و کلاینت آماده‌ی استقرار هستند.

گردش کار توسعه کلاینت چیست؟

اگر بخش « شروع به کار» را دنبال کرده باشید، با جریان کلی توسعه برای Data Connect آشنا شده‌اید. در این راهنما، اطلاعات دقیق‌تری در مورد تولید SDKهای فلاتر از طرحواره خود و کار با کوئری‌ها و جهش‌های کلاینت پیدا خواهید کرد.

به طور خلاصه، برای استفاده از SDK های تولید شده Flutter در برنامه‌های کلاینت خود، این مراحل پیش‌نیاز را دنبال خواهید کرد:

  1. فایربیس را به برنامه فلاتر خود اضافه کنید.
  2. dart pub global activate flutterfire_cli برای خط فرمان flutterfire نصب کنید.
  3. flutterfire configure اجرا کنید.

سپس:

  1. طرحواره برنامه خود را توسعه دهید.

  2. تنظیم تولید SDK:

  3. کد کلاینت خود را مقداردهی اولیه کنید و کتابخانه‌ها را وارد کنید .

  4. فراخوانی‌های کوئری‌ها و جهش‌ها را پیاده‌سازی کنید.

  5. شبیه‌ساز Data Connect را راه‌اندازی و استفاده کنید و مراحل را تکرار کنید.

SDK فلاتر خود را ایجاد کنید

از رابط خط فرمان Firebase CLI) برای تنظیم SDK های تولید شده توسط Data Connect در برنامه‌های خود استفاده کنید. دستور init باید تمام برنامه‌های موجود در پوشه فعلی را شناسایی کرده و SDK های تولید شده را به طور خودکار نصب کند.

firebase init dataconnect:sdk
به‌روزرسانی SDKها هنگام نمونه‌سازی اولیه

اگر افزونه‌ی Data Connect VS Code را نصب کرده باشید، این افزونه همیشه SDKهای تولید شده را به‌روز نگه می‌دارد.

اگر از افزونه Data Connect VS Code استفاده نمی‌کنید، می‌توانید از Firebase CLI برای به‌روز نگه داشتن SDKهای تولید شده استفاده کنید.

firebase dataconnect:sdk:generate --watch
 تولید SDK در خطوط لوله ساخت

شما می‌توانید از Firebase CLI برای تولید SDK های Data Connect در فرآیندهای ساخت CI/CD استفاده کنید.

firebase dataconnect:sdk:generate
 تنظیم کد کلاینت برنامه Data Connect خود را مقداردهی اولیه کنید

ابتدا، برنامه خود را با استفاده از دستورالعمل‌های استاندارد راه‌اندازی Firebase راه‌اندازی کنید.

سپس، افزونه Data Connect را نصب کنید:

flutter pub add firebase_data_connect
 مقداردهی اولیه Data Connect Flutter SDK

نمونه Data Connect خود را با استفاده از اطلاعاتی که برای راه‌اندازی Data Connect استفاده کرده‌اید (همه در تب Data Connect کنسول Firebase موجود است) مقداردهی اولیه کنید.

کتابخانه‌ها را وارد کنید

برای مقداردهی اولیه کد کلاینت، دو مجموعه از ایمپورت‌ها مورد نیاز است، ایمپورت‌های عمومی Data 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 یک متد سازنده ارائه می‌دهد و باید جداگانه تنظیم شود.

برای مثال، فیلد rating هنگام فراخوانی createMovie اختیاری است، بنابراین باید آن را در تابع builder ارائه دهید.

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi"}).rating(5).execute();
اشتراک در تغییرات

شما می‌توانید در تغییرات مشترک شوید (که هر زمان که یک پرس‌وجو را اجرا کنید، به‌روزرسانی می‌شوند).

QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();

// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
  updateUIWithMovies(data.movies);
});

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`
مدیریت تغییرات در فیلدهای شمارشی

طرحواره یک برنامه می‌تواند شامل شمارشگرها باشد که می‌توانند توسط کوئری‌های GraphQL شما قابل دسترسی باشند.

با تغییر طراحی یک برنامه، ممکن است مقادیر جدیدی که توسط enum پشتیبانی می‌شوند را اضافه کنید. برای مثال، تصور کنید که بعداً در چرخه حیات برنامه خود تصمیم می‌گیرید یک مقدار FULLSCREEN به enum مربوط به AspectRatio اضافه کنید.

در گردش کار Data 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}");
  }
}
استفاده از جهش‌ها در سمت کلاینت

جهش‌ها به همان روشی که پرس‌وجوها قابل دسترسی هستند، قابل دسترسی هستند. 

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
نمونه اولیه برنامه‌های Flutter خود را بسازید و آزمایش کنید کلاینت‌های Instrument برای استفاده از یک شبیه‌ساز محلی

شما می‌توانید از شبیه‌ساز Data Connect ، چه از طریق افزونه Data Connect VS Code و چه از طریق رابط خط فرمان (CLI)، استفاده کنید.

آماده‌سازی برنامه برای اتصال به شبیه‌ساز برای هر دو سناریو یکسان است. 

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

سرور Data Connect انواع داده رایج GraphQL را نشان می‌دهد. این انواع داده در SDK به شرح زیر نمایش داده شده‌اند.

نوع اتصال داده دارت
مهر زمانی firebase_data_connect.Timestamp
عدد صحیح (۳۲ بیتی) عدد صحیح
تاریخ تاریخ و زمان
شناسه کاربری رشته
بین‌رشته‌ای64 عدد صحیح
شناور دو برابر
بولی بول
هر firebase_data_connect.AnyValue