Firebase SQL Connect کیتهای توسعه نرمافزار کارخواه به شما امکان میدهند پرسمانها و جهشهای سمت سرور را مستقیماً از برنامه Firebase فراخوانی کنید. شما یک کیت توسعه نرمافزار کارخواه سفارشی را بهطور موازی با طراحی طرحوارهها، پرسمانها، و جهشهایی که در سرویس SQL Connect خود مستقر میکنید، تولید میکنید. سپس، روشهای این کیت توسعه نرمافزار را در منطق کارخواه خود ادغام میکنید.
همانطور که در جای دیگری اشاره کردیم، مهم است توجه داشته باشید که SQL Connect پرسوجوها و جهشها توسط کد کارخواه ارسال نمیشوند و در سرور اجرا نمیشوند. درعوض، هنگام استقرار، عملیات SQL Connect مانند Cloud Functions در سرور ذخیره میشود. این یعنی باید تغییرات مربوطه را در سمت کارخواه اعمال کنید تا از ایجاد مشکل برای کاربران فعلی (مثلاً در نسخههای قدیمیتر برنامه) جلوگیری شود.
به همین دلیل، SQL Connect محیط توسعه نرمافزار و ابزارهایی را دراختیارتان قرار میدهد که به شما امکان میدهد نمونههای اولیه طرحوارهها، پُرسمانها، و جهشهای مستقرشده در سرور را بسازید. همچنین کیتهای توسعه نرمافزار سمت کارخواه را بهطور خودکار درحین نمونهسازی شما تولید میکند.
وقتی بهروزرسانیهای سرویس و برنامههای کارخواه را تکرار کردید، بهروزرسانیهای سمت سرور و سمت کارخواه آماده استقرار هستند.
گردش کار توسعه کارخواه چیست؟
اگر شروع به کار را دنبال کرده باشید، با جریان کلی توسعه برای SQL Connect آشنا شدهاید. در این راهنما، اطلاعات دقیقتری درباره تولید کیتهای توسعه نرمافزار وب از طرحوارهتان و کار با پُرسمانها و جهشهای کارخواه پیدا خواهید کرد.
بهطور خلاصه، برای استفاده از کیتهای توسعه نرمافزار وب تولیدشده در برنامههای مشتری، این مراحل پیشنیاز را دنبال خواهید کرد:
- Firebase را به برنامه وب خود اضافه کنید.
سپس:
- طرحواره برنامهتان را توسعه دهید.
- کد مشتریتان را با کیت توسعه نرمافزار جاوا اسکریپت مقداردهی اولیه کنید.
- راهاندازی تولید کیت توسعه نرمافزار:
- با دکمه افزودن کیت توسعه نرمافزار به برنامه در افزونه SQL Connect VS Code.
- با بهروزرسانی
connector.yamlبرای کیت توسعه نرمافزار جاوا اسکریپت.
- کتابخانهها و کد تولیدشده را با کیت توسعه نرمافزار جاوا اسکریپت وارد کنید.
- فراخوانیهای پُرسمانها و جهشها را با کیت توسعه نرمافزار جاوا اسکریپت پیادهسازی کنید.
- با راهاندازی شبیهساز SQL Connect با کیت توسعه نرمافزار جاوا اسکریپت، آزمایش کنید.
پیادهسازی کد کارخواه با کیت توسعه نرمافزار Firebase JavaScript
این بخش نحوه پیادهسازی مشتریان بااستفاده از کیت توسعه نرمافزار Firebase JavaScript را پوشش میدهد.
اگر از React یا Angular استفاده میکنید، دستورالعملهای راهاندازی جایگزین و پیوندهای اسناد تکمیلی درباره تولید SQL Connect کیتهای توسعه نرمافزار برای چارچوبها را ببینید.
مقداردهی اولیه برنامه
ابتدا، برنامهتان را بااستفاده از توالی استاندارد Firebase مقداردهی اولیه کنید.
initializeApp({...});
کیت توسعه نرمافزار جاوا اسکریپت تولیدشده را نصب کنید
از Firebase CLI برای راهاندازی کیتهای توسعه نرمافزار تولیدشده SQL Connect در برنامههایتان استفاده کنید.
فرمان init باید همه برنامههای موجود در پوشه فعلی را شناسایی کند و
کیتهای توسعه نرمافزار تولیدشده را بهطور خودکار نصب کند.
firebase init dataconnect:sdk
برنامهتان را به سرویس SQL Connect متصل کنید.
import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);
بهروزرسانی کیتهای توسعه نرمافزار درحین نمونهسازی اولیه
اگر افزونه 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 و واردات خاص و تولیدشده «کیت توسعه نرمافزار».
به شیء ConnectorConfig که در واردات عمومی گنجانده شده است توجه کنید.
// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';
// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@dataconnect/generated';
استفاده از پُرسمانهای کیت توسعه نرمافزار جاوا اسکریپت
کد تولیدشده ازقبل با «مرجعهای پُرسمان» ازپیش تعریفشده ارائه میشود. تنها کاری که باید انجام دهید این است که آنها را وارد کنید و execute را روی آنها فراخوانی کنید.
import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';
const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);
فراخوانی روشهای پُرسمان کیت توسعه نرمافزار
در اینجا مثالی از نحوه استفاده از این توابع میانبر کنش آورده شده است:
import { listMovies } from '@dataconnect/generated';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}
مشترک شدن در تغییرات
دریافت بهروزرسانیهای همزمان از SQL Connect را ببینید.
مدیریت تغییرات در فیلدهای شمارشی
طرحواره برنامه میتواند حاوی شمارشها باشد، که پرسوجوهای GraphQL شما میتوانند به آنها دسترسی داشته باشند.
با تغییر طراحی برنامه، میتوانید مقادیر پشتیبانیشده enum جدیدی اضافه کنید. برای مثال،
تصور کنید که بعداً در چرخه حیات برنامهتان تصمیم میگیرید مقدار
FULLSCREEN را به شمارش AspectRatio اضافه کنید.
در گردش کار SQL Connect، میتوانید از ابزار توسعه محلی برای بهروزرسانی پُرسمانها و کیتهای توسعه نرمافزار استفاده کنید.
بااینحال، قبلاز اینکه نسخه بهروزشدهای از کلاینتهایتان را منتشر کنید، کلاینتهای قدیمیتر مستقرشده ممکن است خراب شوند.
نمونه پیادهسازی انعطافپذیر
همیشه یک شاخه default به عبارت switch روی مقادیر enum اضافه کنید، یا
یک شاخه else به بلوک if/else if که با مقادیر enum مقایسه میشود اضافه کنید.
این مورد توسط زبان جاوا اسکریپت/ تایپ اسکریپت اعمال نمیشود، اما راهی برای
مستحکم کردن کد کارخواه درصورت اضافه شدن مقادیر شمارشی جدید است.
const queryResult = await getOldestMovie();
if (queryResult.data) {
// we can use a switch statement's "default" case to check for unexpected values
const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
switch (oldestMovieAspectRatio) {
case AspectRatio.ACADEMY:
case AspectRatio.WIDESCREEN:
case AspectRatio.ANAMORPHIC:
console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
break;
default:
// the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
// it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
break;
}
// alternatively, we can check to see if the returned enum value is a known value
if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
}
} else {
console.log("no movies found!");
}
استفاده از جهشها از کیت توسعه نرمافزار جاوا اسکریپت
جهشها به همان روش پُرسمانها قابلدسترسی هستند.
import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';
const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));
اتصال به شبیهساز SQL Connect
درصورت تمایل، میتوانید با فراخوانی
connectDataConnectEmulator و سپس ارسال نمونه
SQL Connect به شبیهساز متصل شوید،
به این صورت:
import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`
// Make calls from your app
برای رفتن به منابع تولید، خطوط مربوط به اتصال به شبیهساز را بهصورت نظر درآورید.
فعال کردن ذخیرهسازی موقت سمت کارخواه
SQL Connect دارای ویژگی اختیاری ذخیره مؤقت سمت کارخواه است که میتوانید آن را با ویرایش فایل connector.yaml فعال کنید. وقتی این ویژگی فعال باشد،
کیتهای توسعه نرمافزار مشتری تولیدشده پاسخهای پُرسمان را بهطور محلی در حافظه نهان ذخیره میکنند که میتواند
تعداد درخواستهای پایگاه دادهای را که برنامهتان ایجاد میکند کاهش دهد و بخشهای وابسته به پایگاه داده برنامهتان را قادر میسازد
وقتی دسترسی به شبکه قطع میشود کار کنند.
برای فعال کردن ذخیرهسازی موقت سمت کارخواه، پیکربندی ذخیرهسازی موقت کارخواه را به پیکربندی متصلکنندهتان اضافه کنید:
generate:
javascriptSdk:
outputDir: ../web/
package: "@dataconnect/generated"
clientCache:
maxAge: 5s
storage: memory
این پیکربندی دو پارامتر دارد که هر دو اختیاری هستند:
maxAge: حداکثر سن پاسخ ذخیرهشده در حافظه نهان قبلاز اینکه کیت توسعه نرمافزار کارخواه مقادیر جدید را واکشی کند. مثال: «0»، «30s»، «1h30m».مقدار پیشفرض برای
maxAge،0است، یعنی پاسخها در حافظه نهان ذخیره میشوند، اما کیت توسعه نرمافزار کارخواه همیشه مقادیر جدید را واکشی میکند. مقادیر ذخیرهشده در حافظه نهان فقط زمانی استفاده میشود کهCACHE_ONLYبرایexecuteQuery()مشخص شده باشد و نتیجه اولیه ازsubscribe()برگردانده شده باشد.storage: کیت توسعه نرمافزار کارخواه را میتوان بهگونهای پیکربندی کرد که پاسخها را درpersistentیا درmemoryذخیره کند. نتایج ذخیرهشده در حافظه نهانpersistentدرصورت بازراهاندازی برنامه باقی میمانند. در کیتهای توسعه نرمافزار وب، فقط فضای ذخیرهسازیmemoryپشتیبانی میشود.
پساز بهروزرسانی پیکربندی ذخیرهسازی موقت اتصالدهنده، کیتهای توسعه نرمافزار کارخواه را بازتولید کنید و برنامهتان را بازسازی کنید. پساز انجام این کار، executeQuery() و subscribe() پاسخها را ذخیره موقت میکنند و از مقادیر ذخیرهشده موقت طبق خطمشیای که پیکربندی کردهاید استفاده میکنند. این
معمولاً بهطور خودکار و بدون هیچ اقدام اضافی ازجانب شما اتفاق میافتد؛
بااینحال، به موارد زیر توجه کنید:
رفتار پیشفرض
executeQuery()همانطور است که در بالا شرح داده شد: اگر نتیجهای برای پُرسمانی ذخیره شده باشد و مقدار ذخیرهشده قدیمیتر ازmaxAgeنباشد، از مقدار ذخیرهشده استفاده میشود. این رفتار پیشفرض خطمشیPREFER_CACHEنامیده میشود.همچنین میتوانید برای فراخوانیهای تکی
executeQuery()مشخص کنید که یا فقط مقادیر ذخیرهشده در حافظه نهان (CACHE_ONLY) را ارائه دهد یا بدون قیدوشرط مقادیر جدید را از سرور (SERVER_ONLY) واکشی کند.await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);وقتی
subscribe()را فراخوانی میکنید، همیشه بلافاصله محتوای ذخیرهشده در حافظه نهان را (درصورت وجود) برمیگرداند، صرفنظر از تنظیمmaxAge. فراخوانیهای بعدی بهexecuteQuery()به شنوندگان طبقmaxAgeپیکربندیشده اطلاع میدهد.
انواع داده در کیت توسعه نرمافزار
سرور SQL Connect انواع دادههای رایج GraphQL را نشان میدهد. این موارد در کیت توسعه نرمافزار بهصورت زیر نشان داده میشوند.
| نوع SQL Connect | TypeScript |
|---|---|
| مُهر زمان | رشته |
| تاریخ | رشته |
| شناسه منحصربهفرد جهانی | رشته |
| Int64 | رشته |
| دونفره | شماره |
| شناور | شماره |
تولید کیتهای توسعه نرمافزار React و Angular با TanStack
Firebase SQL Connect یک کیت توسعه نرمافزار تولیدشده با قلابهایی برای React و Angular بااستفاده از کتابخانههای دردسترس از شرکای ما در Invertase، TanStack Query Firebase ارائه میدهد.
این کتابخانه مجموعهای از قلابها را ارائه میدهد که مدیریت کارهای ناهمگام با Firebase را در برنامههایتان بسیار آسان میکند.
TanStack با پیادهسازی خودش از ذخیرهسازی موقت سمت کارخواه و اشتراکهای همزمان ارائه میشود که میتواند درکنار پشتیبانی همزمان داخلی SQL Connect کار کند، اما فقط با کمی دشواری. توصیه میکنیم از اتصالهای مبتنی بر TanStack یا پشتیبانی همزمان داخلی SQL Connect استفاده کنید، اما نه از هردو.
توجه داشته باشید که پیادهسازی همزمان خود SQL Connect نسبتبه اتصالهای TanStack مزایایی دارد:
- ذخیرهسازی نرمالشده در حافظه نهان: SQL Connect ذخیرهسازی نرمالشده در حافظه نهان را پیادهسازی میکند، که درمقایسه با ذخیرهسازی در حافظه نهان در سطح پُرسمان، سازگاری دادهها و همچنین کارایی حافظه و شبکه را بهبود میبخشد. با ذخیرهسازی نرمالشده، اگر موجودیتی در یک بخش از برنامه شما بهروز شود، در بخشهای دیگری که از آن موجودیت استفاده میکنند نیز بهروز خواهد شد.
- باطل کردن از راه دور: SQL Connect میتواند موجودیتهای ذخیرهشده در حافظه نهان را از راه دور در همه دستگاههای مشترکشده باطل کند.
مقداردهی اولیه برنامه
ابتدا، مانند هر برنامه وب Firebase، برنامهتان را بااستفاده از توالی استاندارد Firebase مقداردهی اولیه کنید.
initializeApp({...});
بستههای TanStack Query Firebase را نصب کنید
بستههای TanStack Query را در پروژهتان نصب کنید.
واکنش نشان دادن
npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0
Angular
ng add @angular/fire
تولید کیت توسعه نرمافزار React یا Angular
همانطور که پیشتر توضیح داده شد، مانند کیت توسعه نرمافزار وب استاندارد، ابزار Firebase تولید خودکار کیتهای توسعه نرمافزار را براساس طرحواره و عملیات شما مدیریت میکند.
اگر بهتازگی React یا Angular را به پروژهتان اضافه کردهاید، firebase init dataconnect:sdk را دوباره اجرا کنید تا کیتهای توسعه نرمافزار تولیدشده را دوباره پیکربندی کنید تا شامل اتصالهای چارچوب اضافی شود.
وارد کردن کتابخانهها
برای مقداردهی اولیه کد کارخواه React یا Angular، چهار مجموعه واردات لازم است: واردات عمومی SQL Connect، واردات عمومی TanStack، و واردات خاص برای کیتهای توسعه نرمافزار تولیدشده JS و React.
به نوع ConnectorConfig موجود در واردات کلی توجه کنید.
واکنش نشان دادن
// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';
// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';
// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/react";
Angular
// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';
// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';
// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@dataconnect/generated/angular";
از پُرسمانها و جهشها در کلاینت React یا Angular خود استفاده کنید
پساز تکمیل راهاندازی، میتوانید روشهای کیت توسعه نرمافزار تولیدشده را ادغام کنید.
در قطعه کد زیر، به روش useListAllMovies با پیشوند use برای React و روش injectListAllMovies با پیشوند inject برای Angular توجه کنید که هر دو از کیت توسعه نرمافزار تولیدشده هستند.
واکنش نشان دادن
همه این عملیاتها در کیت توسعه نرمافزار تولیدشده، هم پُرسمانها و هم جهشها، اتصالات TanStackQuery را فراخوانی میکنند:
- پرسوجوها قلاب TanStack
useDataConnectQueryرا فراخوانی میکنند و برمیگردانند - فراخوانی Mutations و برگرداندن قلاب
useDataConnectMutationTanStack
import { useListAllMovies } from '@dataconnect/generated/react';
function MyComponent() {
const { isLoading, data, error } = useListAllMovies();
if(isLoading) {
return <div>Loading...</div>
}
if(error) {
return <div> An Error Occurred: {error} </div>
}
}
// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';
function App() {
const queryClient = new QueryClient();
return <QueryClientProvider client={queryClient}>
<MyComponent />
</QueryClientProvider>
}
Angular
import { injectAllMovies, connectorConfig } from '@dataconnect/generated/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
...
provideTanStackQuery(queryClient),
provideDataConnect(() => {
const dc = getDataConnect(connectorConfig);
return dc;
})
]
استفاده از پُرسمانهای بار کردن مجدد خودکار با React و Angular
میتوانید پُرسمانها را بهگونهای پیکربندی کنید که هنگام تغییر دادهها بهطور خودکار بازبارگیری شوند.
واکنش نشان دادن
export class MovieListComponent {
movies = useListAllMovies();
}
export class AddPostComponent {
const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
addMovie() {
// The following will automatically cause TanStack to reload its listAllMovies query
mutation.mutate({ title: 'The Matrix });
}
}
Angular
// class
export class MovieListComponent {
movies = injectListAllMovies();
}
// template
@if (movies.isPending()) {
Loading...
}
@if (movies.error()) {
An error has occurred: {{ movies.error() }}
}
@if (movies.data(); as data) {
@for (movie of data.movies; track movie.id) {
<mat-card appearance="outlined">
<mat-card-content>{{movie.description}}</mat-card-content>
</mat-card>
} @empty {
<h2>No items!</h2>
}
}
اتصال به شبیهساز SQL Connect
درصورت تمایل، میتوانید با فراخوانی
connectDataConnectEmulator و سپس ارسال نمونه SQL Connect
به قلاب تولیدشدهتان، به شبیهساز متصل شوید، مانند این:
واکنش نشان دادن
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListAllMovies } from '@dataconnect/generated/react';
const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);
class AppComponent() {
...
const { isLoading, data, error } = useListAllMovies(dc);
...
}
Angular
// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);
return dc;
}),
برای رفتن به منابع تولید، خطوط مربوط به اتصال به شبیهساز را بهصورت نظر درآورید.
بهروزرسانی کیتهای توسعه نرمافزار درحین نمونهسازی اولیه
اگر افزونه SQL Connect VS Code را نصب کرده باشید، همیشه کیتهای توسعه نرمافزار تولیدشده را بهروز نگه میدارد.
اگر از افزونه SQL Connect VS Code استفاده نمیکنید، میتوانید از واسط خط فرمان Firebase برای بهروز نگه داشتن کیتهای توسعه نرمافزار تولیدشده استفاده کنید.
firebase dataconnect:sdk:generate --watchتولید کیتهای توسعه نرمافزار در خطوط لوله ساخت
میتوانید از واسط خط فرمان Firebase برای تولید کیتهای توسعه نرمافزار SQL Connect در فرایندهای ساخت CI/CD استفاده کنید.
firebase dataconnect:sdk:generate