کیتهای توسعه نرمافزار (SDK) کلاینت Firebase Data Connect به شما امکان میدهند کوئریها و جهشهای سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. شما همزمان با طراحی طرحوارهها، کوئریها و جهشهایی که در سرویس Data Connect خود پیادهسازی میکنید، یک SDK کلاینت سفارشی ایجاد میکنید. سپس، متدهای این SDK را در منطق کلاینت خود ادغام میکنید.
همانطور که در جای دیگری اشاره کردیم، توجه به این نکته مهم است که کوئریها و جهشهای Data Connect توسط کد کلاینت ارسال و روی سرور اجرا نمیشوند. در عوض، هنگام استقرار، عملیات Data Connect مانند توابع ابری روی سرور ذخیره میشوند. این بدان معناست که برای جلوگیری از اختلال در عملکرد کاربران موجود (به عنوان مثال، در نسخههای قدیمیتر برنامه)، باید تغییرات مربوطه در سمت کلاینت را اعمال کنید.
به همین دلیل است که Data Connect یک محیط توسعهدهنده و ابزار در اختیار شما قرار میدهد که به شما امکان میدهد طرحها، کوئریها و جهشهای مستقر در سرور خود را نمونهسازی کنید. همچنین، همزمان با نمونهسازی شما، SDKهای سمت کلاینت را به طور خودکار تولید میکند.
وقتی بهروزرسانیهای مکرر را برای سرویس و برنامههای کلاینت خود انجام دادید، بهروزرسانیهای سمت سرور و کلاینت آمادهی استقرار هستند.
گردش کار توسعه کلاینت چیست؟
اگر بخش « شروع به کار» را دنبال کرده باشید، با جریان کلی توسعه برای Data Connect آشنا شدهاید. در این راهنما، اطلاعات دقیقتری در مورد تولید SDKهای فلاتر از طرحواره خود و کار با کوئریها و جهشهای کلاینت پیدا خواهید کرد.
به طور خلاصه، برای استفاده از SDK های تولید شده Flutter در برنامههای کلاینت خود، این مراحل پیشنیاز را دنبال خواهید کرد:
- فایربیس را به برنامه فلاتر خود اضافه کنید.
- دستور
dart pub global activate flutterfire_cliبرای خط فرمان flutterfire نصب کنید. - دستور
flutterfire configureاجرا کنید.
سپس:
- طرحواره برنامه خود را توسعه دهید.
تنظیم تولید SDK:
- با دکمهی «افزودن SDK به برنامه» در افزونهی Data Connect VS Code ما
- با بهروزرسانی
connector.yamlخود .
کد کلاینت خود را مقداردهی اولیه کنید و کتابخانهها را وارد کنید .
فراخوانیهای کوئریها و جهشها را پیادهسازی کنید.
شبیهساز 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}");
}
}
فعال کردن حافظه پنهان سمت کلاینت
Data Connect یک ویژگی ذخیرهسازی (caching) اختیاری در سمت کلاینت دارد که میتوانید با ویرایش فایل connector.yaml آن را فعال کنید. وقتی این ویژگی فعال باشد، SDK های کلاینت تولید شده، پاسخهای کوئری را به صورت محلی ذخیره میکنند که میتواند تعداد درخواستهای پایگاه دادهای که برنامه شما ایجاد میکند را کاهش دهد و بخشهای وابسته به پایگاه داده برنامه شما را قادر سازد تا در صورت قطع دسترسی به شبکه، کار کنند.
برای فعال کردن ذخیرهسازی سمت کلاینت، پیکربندی ذخیرهسازی سمت کلاینت را به پیکربندی کانکتور خود اضافه کنید:
generate:
javascriptSdk:
outputDir: ../dart/
package: "dataconnect_generated"
clientCache:
maxAge: 5s
storage: memory
این پیکربندی دو پارامتر دارد که هر دو اختیاری هستند:
maxAge: حداکثر سنی که یک پاسخ ذخیره شده میتواند داشته باشد قبل از اینکه SDK کلاینت مقادیر جدید را دریافت کند. مثالها: "0"، "30s"، "1h30m".مقدار پیشفرض برای
maxAgeبرابر0است، به این معنی که پاسخها ذخیره میشوند، اما SDK کلاینت همیشه مقادیر تازه را دریافت میکند. مقادیر ذخیره شده فقط زمانی استفاده میشوند کهCACHE_ONLYبرایexecute()و نتیجه اولیه برگردانده شده ازsubscribe()مشخص شده باشد.storage: SDK کلاینت را میتوان طوری پیکربندی کرد که پاسخها را در حافظهpersistentیا درmemoryپنهان کند. نتایج ذخیره شده در حافظهpersistentدر طول راهاندازی مجدد برنامه پایدار خواهند ماند. هنگام هدف قرار دادن اندروید یا 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()بر اساسmaxAgeپیکربندی شده به شنوندگان اطلاع میدهد.
استفاده از جهشها در سمت کلاینت
جهشها به همان روشی که پرسوجوها قابل دسترسی هستند، قابل دسترسی هستند.
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 به شرح زیر نمایش داده شدهاند.
| نوع Data Connect | دارت |
|---|---|
| مهر زمانی | firebase_data_connect.Timestamp |
| عدد صحیح (۳۲ بیتی) | عدد صحیح |
| تاریخ | تاریخ و زمان |
| شناسه کاربری | رشته |
| بینرشتهای64 | عدد صحیح |
| شناور | دو برابر |
| بولی | بول |
| هر | firebase_data_connect.AnyValue |