Firebase SQL Connect کیت‌های توسعه نرم‌افزار کارخواه به شما امکان می‌دهند پرسمان‌ها و تغییرات سمت سرور را مستقیماً از برنامه Firebase فراخوانی کنید. شما یک کیت توسعه نرم‌افزار کارخواه سفارشی را به‌طور موازی با طراحی طرح‌واره‌ها، پرسمان‌ها، و تغییراتی که در سرویس SQL Connect خود مستقر می‌کنید، تولید می‌کنید. سپس، روش‌های این کیت توسعه نرم‌افزار را در منطق کارخواه خود ادغام می‌کنید.
همان‌طور که در جای دیگری اشاره کردیم، مهم است توجه داشته باشید که SQL Connect پرس‌وجوها و جهش‌ها توسط کد کارخواه ارسال نمی‌شوند و در سرور اجرا می‌شوند. درعوض، هنگام پیاده‌سازی، عملیات SQL Connect مانند Cloud Functions در سرور ذخیره می‌شود. این یعنی باید تغییرات مربوطه را در سمت کارخواه اعمال کنید تا از ایجاد مشکل برای کاربران فعلی (مثلاً در نسخه‌های قدیمی‌تر برنامه) جلوگیری شود.
به همین دلیل، SQL Connect محیط توسعه نرم‌افزار و ابزارهایی را در اختیارتان قرار می‌دهد که به شما امکان می‌دهد نمونه اولیه طرح‌واره‌ها، پُرسمان‌ها، و جهش‌های مستقرشده در سرور را بسازید. همچنین، درحالی‌که نمونه اولیه می‌سازید، کیت‌های توسعه نرم‌افزار سمت کارخواه را به‌طور خودکار تولید می‌کند.
وقتی به‌روزرسانی‌های سرویس و برنامه‌های مشتری را تکرار کردید، به‌روزرسانی‌های سمت سرور و مشتری آماده استقرار هستند.
گردش کار توسعه کارخواه چیست؟
اگر شروع به کار را دنبال کرده باشید، با جریان کلی توسعه برای SQL Connect آشنا شده‌اید. در این راهنما، اطلاعات دقیق‌تری درباره تولید کیت‌های توسعه نرم‌افزار Flutter از طرح‌واره‌تان و کار با پُرسمان‌ها و جهش‌های کارخواه پیدا خواهید کرد.
به‌طور خلاصه، برای استفاده از کیت‌های توسعه نرم‌افزار Flutter تولیدشده در برنامه‌های کارخواه، باید این مراحل پیش‌نیاز را دنبال کنید:
- Firebase را به برنامه Flutter خود اضافه کنید.
- flutterfire CLI
dart pub global activate flutterfire_cliرا نصب کنید. -
flutterfire configureرا اجرا کنید.
سپس:
- طرح‌واره برنامه‌تان را توسعه دهید.
راه‌اندازی تولید کیت توسعه نرم‌افزار:
- با دکمه افزودن کیت توسعه نرم‌افزار به برنامه در افزونه SQL Connect VS Code ما
- با به‌روزرسانی
connector.yaml.
کد کارخواه را مقداردهی اولیه کنید و کتابخانه‌ها را وارد کنید.
فراخوانی‌های پُرسمان‌ها و جهش‌ها را پیاده‌سازی کنید.
شبیه‌ساز SQL Connect را راه‌اندازی و استفاده کنید و تکرار کنید.
تولید کیت توسعه نرم‌افزار Flutter
از Firebase CLI برای راه‌اندازی کیت‌های توسعه نرم‌افزار تولیدشده SQL Connect در برنامه‌هایتان استفاده کنید.
فرمان init باید همه برنامه‌های موجود در پوشه فعلی را شناسایی کند و
کیت‌های توسعه نرم‌افزار تولیدشده را به‌طور خودکار نصب کند.
firebase init dataconnect:sdk
به‌روزرسانی کیت‌های توسعه نرم‌افزار درحین نمونه‌سازی
اگر افزونه SQL Connect VS Code را نصب کرده باشید، همیشه کیت‌های توسعه نرم‌افزار تولیدشده را به‌روز نگه می‌دارد.
اگر از افزونه SQL Connect VS Code استفاده نمی‌کنید، می‌توانید از واسط خط فرمان Firebase برای به‌روز نگه داشتن کیت‌های توسعه نرم‌افزار تولیدشده استفاده کنید.
firebase dataconnect:sdk:generate --watchتولید کیت‌های توسعه نرم‌افزار در خطوط لوله ساخت
می‌توانید از واسط خط فرمان Firebase برای تولید کیت‌های توسعه نرم‌افزار SQL Connect در فرایندهای ساخت CI/CD استفاده کنید.
firebase dataconnect:sdk:generateراه‌اندازی کد مشتری
راه‌اندازی برنامه SQL Connect
ابتدا، برنامه‌تان را بااستفاده از دستورالعمل‌های راه‌اندازی استاندارد Firebase مقداردهی اولیه کنید.
سپس، افزایه SQL Connect را نصب کنید:
flutter pub add firebase_data_connectمقداردهی اولیه کیت توسعه نرم‌افزار Flutter SQL Connect
نمونه SQL Connect خود را بااستفاده از اطلاعاتی که برای راه‌اندازی SQL Connect استفاده کردید مقداردهی اولیه کنید. این اطلاعات را در صفحه پایگاه‌های داده و فضای ذخیره‌سازی > اتصال SQL در کنسول Firebase پیدا کنید.
وارد کردن کتابخانه‌ها
دو مجموعه واردات برای مقداردهی اولیه کد مشتری شما لازم است، واردات عمومی SQL Connect و واردات خاص و تولیدشده کیت توسعه نرم‌افزار.
// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';
// generated queries and mutations from SDK
import 'generated/movies.dart';
استفاده از پُرسمان‌ها در سمت کارخواه
کد تولیدشده ازقبل با «ارجاع‌های پُرسمان» ازپیش تعریف‌شده ارائه می‌شود. تنها کاری که باید انجام دهید این است که execute را وارد کنید و روی آن‌ها فراخوانی کنید.
import 'generated/movies.dart';
await MoviesConnector.instance.listMovies().execute();
فراخوانی روش‌های پرسمان کیت توسعه نرم‌افزار
در اینجا مثالی از نحوه استفاده از این توابع میان‌بر کنش آورده شده است:
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 اختیاری است، بنابراین باید آن را در تابع سازنده ارائه دهید.
await MoviesConnector.instance.createMovie( title: 'Empire Strikes Back', releaseYear: 1980, genre: 'Sci-Fi').rating(5).execute();
مشترک شدن در تغییرات
دریافت به‌روزرسانی‌های هم‌زمان از SQL Connect را ببینید.
مدیریت تغییرات در فیلدهای شمارشی
طرح‌واره برنامه می‌تواند حاوی شمارش‌ها باشد، که پرس‌وجوهای GraphQL شما می‌توانند به آن دسترسی داشته باشند.
با تغییر طراحی برنامه، می‌توانید مقادیر پشتیبانی‌شده شمارشی جدیدی اضافه کنید. برای مثال،
تصور کنید که بعداً در چرخه حیات برنامه‌تان تصمیم می‌گیرید مقدار
FULLSCREEN را به شمارش AspectRatio اضافه کنید.
در گردش کار SQL Connect، می‌توانید از ابزار توسعه محلی برای به‌روزرسانی پُرسمان‌ها و کیت‌های توسعه نرم‌افزار استفاده کنید.
اما قبل‌از اینکه نسخه به‌روزشده‌ای از کلاینت‌هایتان را منتشر کنید، کلاینت‌های مستقرشده قدیمی‌تر ممکن است خراب شوند.
نمونه پیاده‌سازی انعطاف‌پذیر
کیت توسعه نرم‌افزار تولیدشده، رسیدگی به مقادیر ناشناخته را اجباری می‌کند. یعنی کد کارخواه باید
شیء 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 فعال کنید. وقتی این ویژگی فعال باشد،
کیت‌های توسعه نرم‌افزار مشتری تولیدشده پاسخ‌های پُرسمان را به‌طور محلی ذخیره می‌کنند، که می‌تواند
تعداد درخواست‌های پایگاه داده‌ای را که برنامه‌تان ایجاد می‌کند کاهش دهد و بخش‌های وابسته به پایگاه داده برنامه‌تان را قادر می‌سازد تا درصورت قطع شدن شبکه کار کنند.
برای فعال کردن ذخیره‌سازی موقت سمت کارخواه، پیکربندی ذخیره‌سازی موقت کارخواه را به پیکربندی متصل‌کننده‌تان اضافه کنید:
generate:
javascriptSdk:
outputDir: ../dart/
package: "dataconnect_generated"
clientCache:
maxAge: 5s
storage: memory
این پیکربندی دو پارامتر دارد که هر دو اختیاری هستند:
maxAge: حداکثر سن پاسخ ذخیره‌شده در حافظه نهان قبل‌از اینکه کیت توسعه نرم‌افزار مشتری مقادیر جدید را واکشی کند. مثال: «0»، «30s»، «1h30m».مقدار پیش‌فرض برای
maxAge،0است، یعنی پاسخ‌ها ذخیره موقت می‌شوند، اما کیت توسعه نرم‌افزار کارخواه همیشه مقادیر جدید را واکشی می‌کند. مقادیر ذخیره‌شده در حافظه نهان فقط زمانی استفاده می‌شود کهCACHE_ONLYبرایexecute()مشخص شده باشد و نتیجه اولیه ازsubscribe()برگردانده شده باشد.storage: کیت توسعه نرم‌افزار کارخواه را می‌توان به‌گونه‌ای پیکربندی کرد که پاسخ‌ها را درpersistentیا درmemoryذخیره کند. نتایج ذخیره‌شده در حافظه نهانpersistentدرصورت بازراه‌اندازی برنامه باقی می‌ماند. هنگام هدف‌یابی Android یا iOS، پیش‌فرضpersistentاست. هنگام هدف‌یابی مرورگرهای وب، فقط فضای ذخیره‌سازیmemoryپشتیبانی می‌شود.
پس‌از به‌روزرسانی پیکربندی ذخیره‌سازی موقت اتصال‌دهنده، کیت‌های توسعه نرم‌افزار کارخواه را بازتولید کنید و برنامه‌تان را بازسازی کنید. پس‌از انجام این کار، 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
مشتریان را برای استفاده از شبیه‌ساز محلی آماده کنید
می‌توانید از شبیه‌ساز SQL Connect، چه ازطریق افزونه SQL 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
سرور SQL Connect انواع داده‌های رایج GraphQL را نشان می‌دهد. این موارد در کیت توسعه نرم‌افزار به‌صورت زیر نشان داده می‌شوند.
| SQL Connect نوع | Dart |
|---|---|
| مُهر زمان | firebase_data_connect.Timestamp |
| عدد صحیح (۳۲ بیتی) | توپ‌ربایی |
| تاریخ | DateTime |
| شناسه منحصربه‌فرد جهانی | رشته |
| Int64 | توپ‌ربایی |
| شناور | دو نفره |
| بولی | بولی |
| همه | firebase_data_connect.AnyValue |