۱. قبل از شروع
استفاده از ابزارهای پسین بدون سرور مانند Cloud Firestore و Cloud Functions بسیار آسان است، اما آزمایش آنها میتواند دشوار باشد. «مجموعه شبیهساز محلی Firebase» به شما امکان میدهد نسخههای محلی این سرویسها را در ماشین توسعه نرمافزار خود اجرا کنید تا بتوانید برنامهتان را بهسرعت و بهطور ایمن توسعه دهید.
پیشنیازها
- ویرایشگر سادهای مثل Visual Studio Code، Atom، یا Sublime Text
- Node.js نسخه ۱۰.۰.۰ یا بالاتر (برای نصب Node.js، از nvm استفاده کنید، برای بررسی نسخه،
node --versionرا اجرا کنید) - جاوا ۷ یا بالاتر (برای نصب جاوا از این دستورالعملها استفاده کنید، برای بررسی نسخه،
java -versionرا اجرا کنید)
کارهایی که انجام خواهید داد
در این codelab، یک برنامه خرید آنلاین ساده را که توسط چندین سرویس Firebase پشتیبانی میشود، اجرا و اشکالزدایی خواهید کرد:
- Cloud Firestore: پایگاه داده NoSQL بدون سرور با قابلیت مقیاسپذیری جهانی و قابلیتهای همزمان.
- Cloud Functions: کد باطن بدون سرور که در پاسخ به رویدادها یا درخواستهای HTTP اجرا میشود.
- اصالتسنجی Firebase: سرویس اصالتسنجی مدیریتشدهای که با دیگر محصولات Firebase ادغام میشود.
- میزبانی Firebase: میزبانی سریع و ایمن برای برنامههای وب.
برای فعال کردن توسعه محلی، برنامه را به «مجموعه شبیهساز» متصل خواهید کرد.

همچنین با نحوه انجام کارهای زیر آشنا خواهید شد:
- نحوه اتصال برنامه به «مجموعه شبیهساز» و نحوه اتصال شبیهسازهای مختلف.
- نحوه عملکرد Firebase Security Rules و نحوه آزمایش Firestore Security Rules دربرابر شبیهساز محلی.
- نحوه نوشتن «تابع Firebase» که با رویدادهای Firestore راهاندازی میشود و نحوه نوشتن آزمایشهای ادغام که در «مجموعه شبیهساز» اجرا میشود.
۲. تنظیم کردن
دریافت کد منبع
در این codelab، با نسخهای از نمونه Fire Store شروع میکنید که تقریباً کامل است، بنابراین اولین کاری که باید انجام دهید شبیهسازی کد منبع است:
$ git clone https://github.com/firebase/emulators-codelab.git
سپس به دایرکتوری codelab بروید، جایی که برای بقیه این codelab کار خواهید کرد:
$ cd emulators-codelab/codelab-initial-state
اکنون وابستگیها را نصب کنید تا بتوانید کد را اجرا کنید. اگر اتصال اینترنت شما کند است، ممکن است یک یا دو دقیقه طول بکشد:
# Move into the functions directory
$ cd functions
# Install dependencies
$ npm install
# Move back into the previous directory
$ cd ../
دریافت واسط خط فرمان Firebase
«مجموعه شبیهساز» بخشی از «واسط خط فرمان Firebase» است که میتوان آن را با فرمان زیر در دستگاهتان نصب کرد:
$ npm install -g firebase-tools
سپس، مطمئن شوید که جدیدترین نسخه CLI را دارید. این codelab باید با نسخه ۹.۰.۰ یا بالاتر کار کند، اما نسخههای جدیدتر شامل رفع اشکالهای بیشتری هستند.
$ firebase --version 9.6.0
به پروژه Firebase خود متصل شوید
ایجاد پروژه Firebase
- بااستفاده از «حساب Google» خود به سیستم کنسول Firebase وارد شوید.
- برای ایجاد پروژه جدید، روی دکمه کلیک کنید و سپس نام پروژه را وارد کنید (برای مثال،
Emulators Codelab).
- روی ادامه کلیک کنید.
- اگر درخواست شد، شرایط Firebase را مرور و قبول کنید، سپس روی ادامه کلیک کنید.
- (اختیاری) «کمک هوش مصنوعی» را در کنسول Firebase (بهنام «Gemini در Firebase») فعال کنید.
- برای این codelab، به Google Analytics نیاز ندارید، بنابراین گزینه Google Analytics را خاموش کنید.
- روی ایجاد پروژه کلیک کنید، منتظر بمانید تا پروژهتان آماده شود، سپس روی ادامه دادن کلیک کنید.
کدتان را به پروژه Firebase متصل کنید
اکنون باید این کد را به پروژه Firebase شما متصل کنیم. ابتدا فرمان زیر را اجرا کنید تا به سیستم Firebase CLI وارد شوید:
$ firebase login
سپس فرمان زیر را برای ایجاد نام مستعار پروژه اجرا کنید. $YOUR_PROJECT_ID را با شناسه پروژه Firebase خودتان جایگزین کنید.
$ firebase use $YOUR_PROJECT_ID
اکنون آماده اجرای برنامه هستید!
۳. اجرای شبیهسازها
در این بخش، برنامه را بهصورت محلی اجرا خواهید کرد. این یعنی زمان راهاندازی «مجموعه شبیهساز» فرا رسیده است.
شروع کردن شبیهسازها
از داخل فهرست راهنمای منبع codelab، فرمان زیر را برای راهاندازی شبیهسازها اجرا کنید:
$ firebase emulators:start --import=./seed
باید خروجیای شبیه به این ببینید:
$ firebase emulators:start --import=./seed i emulators: Starting emulators: auth, functions, firestore, hosting ⚠ functions: The following emulators are not running, calls to these services from the Functions emulator will affect production: database, pubsub i firestore: Importing data from /Users/samstern/Projects/emulators-codelab/codelab-initial-state/seed/firestore_export/firestore_export.overall_export_metadata i firestore: Firestore Emulator logging to firestore-debug.log i hosting: Serving hosting files from: public ✔ hosting: Local server: http://127.0.0.1:5000 i ui: Emulator UI logging to ui-debug.log i functions: Watching "/Users/samstern/Projects/emulators-codelab/codelab-initial-state/functions" for Cloud Functions... ✔ functions[calculateCart]: firestore function initialized. ┌─────────────────────────────────────────────────────────────┐ │ ✔ All emulators ready! It is now safe to connect your app. │ │ i View Emulator UI at http://127.0.0.1:4000 │ └─────────────────────────────────────────────────────────────┘ ┌────────────────┬────────────────┬─────────────────────────────────┐ │ Emulator │ Host:Port │ View in Emulator UI │ ├────────────────┼────────────────┼─────────────────────────────────┤ │ Authentication │ 127.0.0.1:9099 │ http://127.0.0.1:4000/auth │ ├────────────────┼────────────────┼─────────────────────────────────┤ │ Functions │ 127.0.0.1:5001 │ http://127.0.0.1:4000/functions │ ├────────────────┼────────────────┼─────────────────────────────────┤ │ Firestore │ 127.0.0.1:8080 │ http://127.0.0.1:4000/firestore │ ├────────────────┼────────────────┼─────────────────────────────────┤ │ Hosting │ 127.0.0.1:5000 │ n/a │ └────────────────┴────────────────┴─────────────────────────────────┘ Emulator Hub running at 127.0.0.1:4400 Other reserved ports: 4500 Issues? Report them at https://github.com/firebase/firebase-tools/issues and attach the *-debug.log files.
وقتی پیام همه شبیهسازها شروع شدند را دیدید، برنامه آماده استفاده است.
متصل کردن برنامه وب به شبیهسازها
براساس جدول موجود در گزارشها، میتوانیم ببینیم که شبیهساز Cloud Firestore درحال گوش دادن به درگاه 8080 است و شبیهساز «اصالتسنجی» درحال گوش دادن به درگاه 9099 است.
┌────────────────┬────────────────┬─────────────────────────────────┐ │ Emulator │ Host:Port │ View in Emulator UI │ ├────────────────┼────────────────┼─────────────────────────────────┤ │ Authentication │ 127.0.0.1:9099 │ http://127.0.0.1:4000/auth │ ├────────────────┼────────────────┼─────────────────────────────────┤ │ Functions │ 127.0.0.1:5001 │ http://127.0.0.1:4000/functions │ ├────────────────┼────────────────┼─────────────────────────────────┤ │ Firestore │ 127.0.0.1:8080 │ http://127.0.0.1:4000/firestore │ ├────────────────┼────────────────┼─────────────────────────────────┤ │ Hosting │ 127.0.0.1:5000 │ n/a │ └────────────────┴────────────────┴─────────────────────────────────┘
بیایید کد پیشنمای شما را بهجای تولید، به شبیهساز متصل کنیم. فایل public/js/homepage.js را باز کنید و تابع onDocumentReady را پیدا کنید. میبینیم که کد به نمونههای استاندارد Firestore و Auth دسترسی دارد:
public/js/homepage.js
const auth = firebaseApp.auth();
const db = firebaseApp.firestore();
بیایید اشیاء db و auth را بهروز کنیم تا به شبیهسازهای محلی اشاره کنند:
public/js/homepage.js
const auth = firebaseApp.auth();
const db = firebaseApp.firestore();
// ADD THESE LINES
if (location.hostname === "127.0.0.1") {
console.log("127.0.0.1 detected!");
auth.useEmulator("http://127.0.0.1:9099");
db.useEmulator("127.0.0.1", 8080);
}
اکنون وقتی برنامه در دستگاه محلی شما اجرا میشود (که توسط شبیهساز «میزبانی» ارائه میشود)، سرویسگیرنده Firestore نیز بهجای پایگاه داده تولید، به شبیهساز محلی اشاره میکند.
باز کردن EmulatorUI
در مرورگر وب، به http://127.0.0.1:4000/ بروید. باید واسط کاربر «مجموعه شبیهساز» را ببینید.

برای دیدن واسط کاربر «شبیهساز Firestore» کلیک کنید. مجموعه items ازقبل حاوی داده است زیرا دادهها با پرچم --import وارد شدهاند.

۴. اجرای برنامه
باز کردن برنامه
در مرورگر وب، به http://127.0.0.1:5000 بروید و باید ببینید که Fire Store بهصورت محلی در دستگاهتان اجرا میشود!

استفاده از برنامه
کالایی را در صفحه اصلی انتخاب کنید و روی افزودن به سبد خرید کلیک کنید. متأسفانه با خطای زیر مواجه خواهید شد:

بیایید آن اشکال را برطرف کنیم! چون همه چیز در شبیهسازها اجرا میشود، میتوانیم آزمایش کنیم و نگران تأثیر گذاشتن بر دادههای واقعی نباشیم.
۵. اشکالزدایی برنامه
یافتن اشکال
بسیار خوب، بیایید در کنسول توسعهدهندگان Chrome نگاه کنیم. کلیدهای Control+Shift+J (Windows، Linux، Chrome OS) یا Command+Option+J (Mac) را فشار دهید تا خطا را در کنسول ببینید:

بهنظر میرسد خطایی در روش addToCart وجود دارد، بیایید نگاهی به آن بیندازیم. در آن روش، کجا سعی میکنیم به چیزی بهنام uid دسترسی پیدا کنیم و چرا باید null باشد؟ درحالحاضر این روش در public/js/homepage.js به این شکل است:
public/js/homepage.js
addToCart(id, itemData) {
console.log("addToCart", id, JSON.stringify(itemData));
return this.db
.collection("carts")
.doc(this.auth.currentUser.uid)
.collection("items")
.doc(id)
.set(itemData);
}
آها! ما به سیستم برنامه وارد نشدهایم. طبق اسناد اصالتسنجی Firebase، وقتی به سیستم وارد نشدهایم، auth.currentUser برابر با null است. بیایید بررسیای برای آن اضافه کنیم:
public/js/homepage.js
addToCart(id, itemData) {
// ADD THESE LINES
if (this.auth.currentUser === null) {
this.showError("You must be signed in!");
return;
}
// ...
}
آزمایش برنامه
اکنون، صفحه را بازآوری کنید و سپس روی افزودن به سبد خرید کلیک کنید. این بار باید خطای بهتری دریافت کنید:

اما اگر در نوار ابزار بالا روی ورود به سیستم کلیک کنید و سپس دوباره روی افزودن به سبد خرید کلیک کنید، خواهید دید که سبد خرید بهروز میشود.
بااینحال، بهنظر نمیرسد که این اعداد اصلاً درست باشند:

نگران نباشید، بهزودی این اشکال را برطرف میکنیم. ابتدا، بیایید عمیقاً بررسی کنیم که وقتی موردی را به سبد خریدتان اضافه کردید، واقعاً چه اتفاقی افتاد.
۶. راهاندازهای توابع محلی
کلیک کردن روی افزودن به سبد خرید زنجیرهای از رویدادها را آغاز میکند که شامل چندین شبیهساز است. در گزارشهای واسط خط فرمان Firebase، پساز افزودن موردی به سبد خریدتان، باید چیزی شبیه پیامهای زیر ببینید:
i functions: Beginning execution of "calculateCart" i functions: Finished "calculateCart" in ~1s
چهار رویداد کلیدی رخ داده است که این گزارشها و بهروزرسانی میانای کاربری را که مشاهده کردید تولید کرده است:

۱) Firestore Write - Client
سند جدیدی به مجموعه Firestore /carts/{cartId}/items/{itemId}/ اضافه میشود. میتوانید این کد را در تابع addToCart در public/js/homepage.js ببینید:
public/js/homepage.js
addToCart(id, itemData) {
// ...
console.log("addToCart", id, JSON.stringify(itemData));
return this.db
.collection("carts")
.doc(this.auth.currentUser.uid)
.collection("items")
.doc(id)
.set(itemData);
}
۲) Cloud Function راهاندازی شد
Cloud Function calculateCart بااستفاده از راهانداز onWrite، که میتوانید آن را در functions/index.js ببینید، به هر رویداد نوشتنی (ایجاد، بهروزرسانی، یا حذف) که برای موارد سبد خرید اتفاق میافتد گوش میدهد:
functions/index.js
exports.calculateCart = functions.firestore
.document("carts/{cartId}/items/{itemId}")
.onWrite(async (change, context) => {
try {
let totalPrice = 125.98;
let itemCount = 8;
const cartRef = db.collection("carts").doc(context.params.cartId);
await cartRef.update({
totalPrice,
itemCount
});
} catch(err) {
}
}
);
۳) Firestore Write - Admin
تابع calculateCart همه موارد موجود در سبد خرید را میخواند و تعداد و قیمت کل را جمع میکند، سپس سند «سبد خرید» را با مجموعهای جدید بهروز میکند (cartRef.update(...) بالا را ببینید).
۴) خواندن Firestore - کارخواه
فرانتاند وب برای دریافت بهروزرسانیهای مربوط به تغییرات سبد خرید مشترک شده است. پساز اینکه Cloud Function مجموعهای جدید را نوشت و میانای کاربر را بهروز کرد، بهروزرسانی همزمان دریافت میکند، همانطور که در public/js/homepage.js میبینید:
public/js/homepage.js
this.cartUnsub = cartRef.onSnapshot(cart => {
// The cart document was changed, update the UI
// ...
});
خلاصه
آفرین! شما بهتازگی یک برنامه کاملاً محلی راهاندازی کردهاید که از سه شبیهساز مختلف Firebase برای آزمایش کاملاً محلی استفاده میکند.

اما صبر کنید، چیزهای بیشتری موجود است! در بخش بعدی با این موارد آشنا میشوید:
- نحوه نوشتن آزمونهای واحدی که از «شبیهسازهای Firebase» استفاده میکنند.
- نحوه استفاده از «شبیهسازهای Firebase» برای اشکالزدایی «قوانین امنیتی».
۷. ایجاد قوانین امنیتی متناسب با برنامهتان
برنامه وب ما دادهها را میخواند و مینویسد اما تاکنون واقعاً نگران امنیت نبودهایم. Cloud Firestore از سیستمی بهنام «قوانین امنیتی» استفاده میکند تا مشخص کند چه کسی به خواندن و نوشتن دادهها دسترسی دارد. «مجموعه شبیهساز» روشی عالی برای نمونهسازی این قوانین است.
در ویرایشگر، فایل emulators-codelab/codelab-initial-state/firestore.rules را باز کنید. خواهید دید که ما سه بخش اصلی در قوانین خود داریم:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
// User's cart metadata
match /carts/{cartID} {
// TODO: Change these! Anyone can read or write.
allow read, write: if true;
}
// Items inside the user's cart
match /carts/{cartID}/items/{itemID} {
// TODO: Change these! Anyone can read or write.
allow read, write: if true;
}
// All items available in the store. Users can read
// items but never write them.
match /items/{itemID} {
allow read: if true;
}
}
}
درحالحاضر هرکسی میتواند دادهها را در پایگاه داده ما بخواند و بنویسد! میخواهیم مطمئن شویم که فقط عملیات معتبر انجام میشود و هیچ اطلاعات حساسی درز نمیکند.
درطول این codelab، با پیروی از «اصل حداقل امتیاز»، همه اسناد را قفل میکنیم و بهتدریج دسترسی اضافه میکنیم تا همه کاربران به همه دسترسیهای موردنیازشان برسند، نه بیشتر. بیایید دو قانون اول را با تنظیم شرط روی false بهروز کنیم تا دسترسی را رد کنیم:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
// User's cart metadata
match /carts/{cartID} {
// UPDATE THIS LINE
allow read, write: if false;
}
// Items inside the user's cart
match /carts/{cartID}/items/{itemID} {
// UPDATE THIS LINE
allow read, write: if false;
}
// All items available in the store. Users can read
// items but never write them.
match /items/{itemID} {
allow read: if true;
}
}
}
۸. اجرای شبیهسازها و آزمایشها
شبیهسازها را راهاندازی کنید
در خط فرمان، مطمئن شوید در emulators-codelab/codelab-initial-state/ هستید. ممکن است شبیهسازها همچنان از مراحل قبلی درحال اجرا باشند. اگر نه، شبیهسازها را دوباره راهاندازی کنید:
$ firebase emulators:start --import=./seed
وقتی شبیهسازها درحال اجرا باشند، میتوانید آزمایشها را بهطور محلی در آنها اجرا کنید.
اجرای آزمایشها
در خط فرمان در برگه پایانه جدید از دایرکتوری emulators-codelab/codelab-initial-state/
ابتدا به دایرکتوری توابع بروید (برای بقیه کدبخش در اینجا خواهیم ماند):
$ cd functions
اکنون آزمایشهای mocha را در دایرکتوری توابع اجرا کنید و به بالای خروجی پیمایش کنید:
# Run the tests
$ npm test
> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha
shopping carts
1) can be created and updated by the cart owner
2) can be read only by the cart owner
shopping cart items
3) can be read only by the cart owner
4) can be added only by the cart owner
adding an item to the cart recalculates the cart total.
- should sum the cost of their items
0 passing (364ms)
1 pending
4 failing
درحالحاضر چهار خرابی داریم. همانطور که فایل قوانین را میسازید، میتوانید با تماشای قبولی در آزمونهای بیشتر، پیشرفت را بسنجید.
۹. دسترسی ایمن به سبد خرید
دو مورد اول از موارد عدم موفقیت، آزمایشهای «سبد خرید» هستند که موارد زیر را آزمایش میکنند:
- کاربران فقط میتوانند سبدهای خرید خودشان را ایجاد و بهروزرسانی کنند
- کاربران فقط میتوانند سبدهای خرید خودشان را بخوانند
functions/test.js
it('can be created and updated by the cart owner', async () => {
// Alice can create her own cart
await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").set({
ownerUID: "alice",
total: 0
}));
// Bob can't create Alice's cart
await firebase.assertFails(bobDb.doc("carts/alicesCart").set({
ownerUID: "alice",
total: 0
}));
// Alice can update her own cart with a new total
await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").update({
total: 1
}));
// Bob can't update Alice's cart with a new total
await firebase.assertFails(bobDb.doc("carts/alicesCart").update({
total: 1
}));
});
it("can be read only by the cart owner", async () => {
// Setup: Create Alice's cart as admin
await admin.doc("carts/alicesCart").set({
ownerUID: "alice",
total: 0
});
// Alice can read her own cart
await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").get());
// Bob can't read Alice's cart
await firebase.assertFails(bobDb.doc("carts/alicesCart").get());
});
بیایید این آزمونها را با موفقیت پشت سر بگذاریم. در ویرایشگر، فایل قوانین امنیتی، firestore.rules، را باز کنید و عبارتهای داخل match /carts/{cartID} را بهروز کنید:
firestore.rules
rules_version = '2';
service cloud.firestore {
// UPDATE THESE LINES
match /carts/{cartID} {
allow create: if request.auth.uid == request.resource.data.ownerUID;
allow read, update, delete: if request.auth.uid == resource.data.ownerUID;
}
// ...
}
}
این قوانین اکنون فقط به مالک سبد خرید اجازه دسترسی خواندن و نوشتن میدهند.
برای درستیسنجی دادههای ورودی و اصالتسنجی کاربر، از دو شیء استفاده میکنیم که در زمینه هر قانون دردسترس است:
- شیء
requestحاوی دادهها و فرادادههای مربوط به عملیاتی است که درحال انجام است. - اگر پروژه Firebase از اصالتسنجی Firebase استفاده میکند، شیء
request.authکاربری را که درخواست را ارسال میکند توصیف میکند.
۱۰. دسترسی به سبد خرید آزمایشی
هرزمان firestore.rules ذخیره شود، «مجموعه شبیهساز» بهطور خودکار قوانین را بهروز میکند. میتوانید با نگاه کردن به برگه درحال اجرای شبیهساز برای پیام Rules updated، تأیید کنید که شبیهساز قوانین را بهروز کرده است:

آزمایشها را دوباره اجرا کنید و بررسی کنید که دو آزمایش اول اکنون با موفقیت انجام میشوند:
$ npm test
> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha
shopping carts
✓ can be created and updated by the cart owner (195ms)
✓ can be read only by the cart owner (136ms)
shopping cart items
1) can be read only by the cart owner
2) can be added only by the cart owner
adding an item to the cart recalculates the cart total.
- should sum the cost of their items
2 passing (482ms)
1 pending
2 failing
آفرین! اکنون دسترسی به سبدهای خرید را ایمن کردهاید. بیایید به آزمون ناموفق بعدی برویم.
۱۱. جریان «افزودن به سبد خرید» را در میانای کاربر بررسی کنید
درحالحاضر، اگرچه مالکان سبد خرید میتوانند سبد خریدشان را بخوانند و در آن بنویسند، نمیتوانند اقلام تکی را در سبد خریدشان بخوانند یا بنویسند. دلیلش این است که اگرچه مالکان به سند سبد خرید دسترسی دارند، اما به زیرمجموعه موارد سبد خرید دسترسی ندارند.
این وضعیت برای کاربران خراب است.
به میانای وب که در http://127.0.0.1:5000, درحال اجرا است برگردید و سعی کنید چیزی به سبد خریدتان اضافه کنید. خطای Permission Denied دریافت میکنید که از کنسول اشکالزدایی قابلمشاهده است، زیرا هنوز به کاربران اجازه دسترسی به اسناد ایجادشده در زیرمجموعه items را ندادهایم.
۱۲. اجازه دسترسی به موارد سبد خرید
این دو آزمایش تأیید میکنند که کاربران فقط میتوانند به سبد خرید خودشان مورد اضافه کنند یا موارد موجود در آن را بخوانند:
it("can be read only by the cart owner", async () => {
// Alice can read items in her own cart
await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart/items/milk").get());
// Bob can't read items in alice's cart
await firebase.assertFails(bobDb.doc("carts/alicesCart/items/milk").get())
});
it("can be added only by the cart owner", async () => {
// Alice can add an item to her own cart
await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart/items/lemon").set({
name: "lemon",
price: 0.99
}));
// Bob can't add an item to alice's cart
await firebase.assertFails(bobDb.doc("carts/alicesCart/items/lemon").set({
name: "lemon",
price: 0.99
}));
});
بنابراین میتوانیم قانونی بنویسیم که اگر کاربر فعلی همان UID را بهعنوان ownerUID در سند سبد خرید داشته باشد، دسترسی را مجاز کند. ازآنجاییکه نیازی به تعیین قوانین مختلف برای create, update, delete نیست، میتوانید از قانون write استفاده کنید که برای همه درخواستهایی که دادهها را تغییر میدهند اعمال میشود.
قانون اسناد را در زیرمجموعه موارد بهروز کنید. get در شرطی مقداری را از Firestore میخواند–در این مورد، ownerUID در سند سبد خرید.
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
// ...
// UPDATE THESE LINES
match /carts/{cartID}/items/{itemID} {
allow read, write: if get(/databases/$(database)/documents/carts/$(cartID)).data.ownerUID == request.auth.uid;
}
// ...
}
}
۱۳. آزمایش دسترسی به موارد سبد خرید
اکنون میتوانیم آزمایش را دوباره اجرا کنیم. به بالای برونداد پیمایش کنید و بررسی کنید که آزمایشهای بیشتری قبول شده باشند:
$ npm test
> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha
shopping carts
✓ can be created and updated by the cart owner (195ms)
✓ can be read only by the cart owner (136ms)
shopping cart items
✓ can be read only by the cart owner (111ms)
✓ can be added only by the cart owner
adding an item to the cart recalculates the cart total.
- should sum the cost of their items
4 passing (401ms)
1 pending
خوب است! اکنون همه آزمایشهای ما موفقیتآمیز است. یک آزمایش معلقه داریم، اما در چند مرحله به آن خواهیم رسید.
۱۴. جریان «افزودن به سبد خرید» را دوباره بررسی کنید
به وب فرانتاند ( http://127.0.0.1:5000) برگردید و موردی را به سبد خرید اضافه کنید. این مرحله مهمی برای تأیید این است که آزمایشها و قوانین ما با عملکرد موردنیاز مشتری مطابقت دارد. (بهیاد داشته باشید که آخرین باری که میانای کاربری را امتحان کردیم، کاربران نتوانستند موردی به سبد خریدشان اضافه کنند!)

وقتی firestore.rules ذخیره میشود، کارخواه بهطور خودکار قوانین را مجدداً بار میکند. بنابراین، چیزی به سبد خرید اضافه کنید.
خلاصه
آفرین! امنیت برنامهتان را بهبود بخشیدید، این گامی ضروری برای آماده کردن آن برای تولید است! اگر این برنامه تولید بود، میتوانستیم این آزمایشها را به خط لوله ادغام مداوم خود اضافه کنیم. این کار به ما اطمینان میدهد که در آینده دادههای سبد خرید ما این کنترلهای دسترسی را خواهند داشت، حتی اگر دیگران قوانین را تغییر دهند.

ولی صبر کنید، هنوز هست!
اگر ادامه دهید، با موارد زیر آشنا میشوید:
- نحوه نوشتن تابع راهاندازیشده با رویداد Firestore
- نحوه ایجاد آزمایشهایی که در چند شبیهساز کار میکنند
۱۵. راهاندازی کردن آزمایشهای Cloud Functions
تاکنون روی بخش کاربری برنامه وب و «قوانین امنیتی Firestore» تمرکز کردهایم. اما این برنامه از Cloud Functions نیز برای بهروز نگه داشتن سبد خرید کاربر استفاده میکند، بنابراین میخواهیم آن کد را هم آزمایش کنیم.
«مجموعه شبیهساز» آزمایش کردن Cloud Functions را بسیار آسان میکند، حتی توابعی که از Cloud Firestore و سرویسهای دیگر استفاده میکنند.
در ویرایشگر، فایل emulators-codelab/codelab-initial-state/functions/test.js را باز کنید و به آخرین آزمایش در فایل پیمایش کنید. درحالحاضر، بهعنوان درانتظار علامتگذاری شده است:
// REMOVE .skip FROM THIS LINE
describe.skip("adding an item to the cart recalculates the cart total. ", () => {
// ...
it("should sum the cost of their items", async () => {
...
});
});
برای فعال کردن آزمایش، .skip را بردارید تا به این شکل درآید:
describe("adding an item to the cart recalculates the cart total. ", () => {
// ...
it("should sum the cost of their items", async () => {
...
});
});
سپس، متغیر REAL_FIREBASE_PROJECT_ID را در بالای فایل پیدا کنید و آن را به «شناسه پروژه» واقعی Firebase خود تغییر دهید.:
// CHANGE THIS LINE
const REAL_FIREBASE_PROJECT_ID = "changeme";
اگر شناسه پروژهتان را فراموش کردهاید، میتوانید «شناسه پروژه» Firebase خود را در «تنظیمات پروژه» در «کنسول Firebase» پیدا کنید:

۱۶. انجام دادن گامبهگام آزمایشهای «توابع»
چون این آزمایش تعامل بین Cloud Firestore و Cloud Functions را اعتبارسنجی میکند، راهاندازی آن نسبتبه آزمایشهای codelabs قبلی بیشتر است. بیایید این آزمون را با هم مرور کنیم و ببینیم چه انتظاری از ما دارد.
ایجاد سبد خرید
Cloud Functions در محیط سرور مطمئنی اجرا میشود و میتواند از اصالتسنجی حساب سرویس استفادهشده توسط Admin SDK استفاده کند . ابتدا، برنامهای را بااستفاده از initializeAdminApp بهجای initializeApp مقداردهی اولیه میکنید. سپس، یک DocumentReference برای سبد خریدی که اقلام را به آن اضافه میکنیم ایجاد میکنید و سبد خرید را مقداردهی اولیه میکنید:
it("should sum the cost of their items", async () => {
const db = firebase
.initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
.firestore();
// Setup: Initialize cart
const aliceCartRef = db.doc("carts/alice")
await aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });
...
});
راهاندازی تابع
سپس، اسناد را به زیرمجموعه items سند سبد خرید ما اضافه کنید تا تابع را راهاندازی کنید. دو مورد اضافه کنید تا مطمئن شوید که افزودنی را که در تابع اتفاق میافتد آزمایش میکنید.
it("should sum the cost of their items", async () => {
const db = firebase
.initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
.firestore();
// Setup: Initialize cart
const aliceCartRef = db.doc("carts/alice")
await aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });
// Trigger calculateCart by adding items to the cart
const aliceItemsRef = aliceCartRef.collection("items");
await aliceItemsRef.doc("doc1").set({name: "nectarine", price: 2.99});
await aliceItemsRef.doc("doc2").set({ name: "grapefruit", price: 6.99 });
...
});
});
تنظیم کردن انتظارات آزمایش
از onSnapshot() برای ثبت شنونده برای هرگونه تغییر در سند سبد خرید استفاده کنید. onSnapshot() تابعی را برمیگرداند که میتوانید برای لغو ثبت شنونده فراخوانی کنید.
برای این آزمایش، دو محصول اضافه کنید که قیمت آنها باهم ۹٫۹۸ دلار باشد. سپس، بررسی کنید که آیا سبد خرید دارای itemCount و totalPrice موردانتظار است یا نه. اگر اینطور باشد، تابع کارش را انجام داده است.
it("should sum the cost of their items", (done) => {
const db = firebase
.initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
.firestore();
// Setup: Initialize cart
const aliceCartRef = db.doc("carts/alice")
aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });
// Trigger calculateCart by adding items to the cart
const aliceItemsRef = aliceCartRef.collection("items");
aliceItemsRef.doc("doc1").set({name: "nectarine", price: 2.99});
aliceItemsRef.doc("doc2").set({ name: "grapefruit", price: 6.99 });
// Listen for every update to the cart. Every time an item is added to
// the cart's subcollection of items, the function updates `totalPrice`
// and `itemCount` attributes on the cart.
// Returns a function that can be called to unsubscribe the listener.
await new Promise((resolve) => {
const unsubscribe = aliceCartRef.onSnapshot(snap => {
// If the function worked, these will be cart's final attributes.
const expectedCount = 2;
const expectedTotal = 9.98;
// When the `itemCount`and `totalPrice` match the expectations for the
// two items added, the promise resolves, and the test passes.
if (snap.data().itemCount === expectedCount && snap.data().totalPrice == expectedTotal) {
// Call the function returned by `onSnapshot` to unsubscribe from updates
unsubscribe();
resolve();
};
});
});
});
});
۱۷. اجرای آزمایشها
ممکن است شبیهسازها همچنان از آزمایشهای قبلی درحال اجرا باشند. اگر نه، شبیهسازها را راهاندازی کنید. از خط فرمان، این را اجرا کنید
$ firebase emulators:start --import=./seed
برگه پایانه جدیدی باز کنید (شبیهسازها را درحال اجرا رها کنید) و به دایرکتوری توابع بروید. ممکن است این مورد را از آزمایشهای قوانین امنیتی باز کرده باشید.
$ cd functions
اکنون آزمونهای واحد را اجرا کنید، باید درمجموع ۵ آزمون ببینید:
$ npm test
> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha
shopping cart creation
✓ can be created by the cart owner (82ms)
shopping cart reads, updates, and deletes
✓ cart can be read by the cart owner (42ms)
shopping cart items
✓ items can be read by the cart owner (40ms)
✓ items can be added by the cart owner
adding an item to the cart recalculates the cart total.
1) should sum the cost of their items
4 passing (2s)
1 failing
اگر به خطای خاص نگاه کنید، بهنظر میرسد خطای اتمام مهلت باشد. دلیلش این است که آزمایش منتظر است تا تابع بهدرستی بهروز شود، اما این اتفاق هرگز نمیافتد. اکنون آمادهایم تا تابع را برای برآورده کردن آزمون بنویسیم.
۱۸. نوشتن تابع
برای رفع این آزمایش، باید تابع را در functions/index.js بهروز کنید. اگرچه بخشی از این تابع نوشته شده است، اما کامل نیست. این تابع درحالحاضر به این صورت است:
// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
.firestore.document("carts/{cartId}/items/{itemId}")
.onWrite(async (change, context) => {
console.log(`onWrite: ${change.after.ref.path}`);
if (!change.after.exists) {
// Ignore deletes
return;
}
let totalPrice = 125.98;
let itemCount = 8;
try {
const cartRef = db.collection("carts").doc(context.params.cartId);
await cartRef.update({
totalPrice,
itemCount
});
} catch(err) {
}
});
تابع بهدرستی مرجع سبد خرید را تنظیم میکند، اما سپس بهجای محاسبه مقادیر totalPrice و itemCount، آنها را به مقادیر کدگذاریشده بهروز میکند.
واکشی و تکرار ازطریق
items زیرمجموعه
ثابت جدیدی، itemsSnap، را مقداردهی اولیه کنید تا زیرمجموعه items باشد. سپس، همه اسناد موجود در مجموعه را تکرار کنید.
// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
.firestore.document("carts/{cartId}/items/{itemId}")
.onWrite(async (change, context) => {
console.log(`onWrite: ${change.after.ref.path}`);
if (!change.after.exists) {
// Ignore deletes
return;
}
try {
let totalPrice = 125.98;
let itemCount = 8;
const cartRef = db.collection("carts").doc(context.params.cartId);
// ADD LINES FROM HERE
const itemsSnap = await cartRef.collection("items").get();
itemsSnap.docs.forEach(item => {
const itemData = item.data();
})
// TO HERE
return cartRef.update({
totalPrice,
itemCount
});
} catch(err) {
}
});
محاسبه totalPrice و itemCount
ابتدا، بیایید مقادیر totalPrice و itemCount را روی صفر مقداردهی اولیه کنیم.
سپس، منطق را به بلوک تکرارمان اضافه کنید. ابتدا بررسی کنید که مورد قیمت داشته باشد. اگر مقدار مورد مشخص نشده است، آن را بهطور پیشفرض روی 1 تنظیم کن. سپس، تعداد را به مجموع جاری itemCount اضافه کنید. درنهایت، قیمت محصول ضرب در تعداد را به مجموع جاری totalPrice اضافه کنید:
// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
.firestore.document("carts/{cartId}/items/{itemId}")
.onWrite(async (change, context) => {
console.log(`onWrite: ${change.after.ref.path}`);
if (!change.after.exists) {
// Ignore deletes
return;
}
try {
// CHANGE THESE LINES
let totalPrice = 0;
let itemCount = 0;
const cartRef = db.collection("carts").doc(context.params.cartId);
const itemsSnap = await cartRef.collection("items").get();
itemsSnap.docs.forEach(item => {
const itemData = item.data();
// ADD LINES FROM HERE
if (itemData.price) {
// If not specified, the quantity is 1
const quantity = itemData.quantity ? itemData.quantity : 1;
itemCount += quantity;
totalPrice += (itemData.price * quantity);
}
// TO HERE
})
await cartRef.update({
totalPrice,
itemCount
});
} catch(err) {
}
});
همچنین میتوانید برای کمک به اشکالزدایی حالتهای موفقیت و خطا، گزارشگیری اضافه کنید:
// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
.firestore.document("carts/{cartId}/items/{itemId}")
.onWrite(async (change, context) => {
console.log(`onWrite: ${change.after.ref.path}`);
if (!change.after.exists) {
// Ignore deletes
return;
}
let totalPrice = 0;
let itemCount = 0;
try {
const cartRef = db.collection("carts").doc(context.params.cartId);
const itemsSnap = await cartRef.collection("items").get();
itemsSnap.docs.forEach(item => {
const itemData = item.data();
if (itemData.price) {
// If not specified, the quantity is 1
const quantity = (itemData.quantity) ? itemData.quantity : 1;
itemCount += quantity;
totalPrice += (itemData.price * quantity);
}
});
await cartRef.update({
totalPrice,
itemCount
});
// OPTIONAL LOGGING HERE
console.log("Cart total successfully recalculated: ", totalPrice);
} catch(err) {
// OPTIONAL LOGGING HERE
console.warn("update error", err);
}
});
۱۹. اجرای مجدد آزمایشها
در خط فرمان، مطمئن شوید شبیهسازها همچنان درحال اجرا هستند و آزمایشها را دوباره اجرا کنید. نیازی به بازراهاندازی شبیهسازها نیست زیرا آنها بهطور خودکار تغییرات توابع را دریافت میکنند. باید ببینید که همه آزمایشها موفقیتآمیز بودهاند:
$ npm test
> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha
shopping cart creation
✓ can be created by the cart owner (306ms)
shopping cart reads, updates, and deletes
✓ cart can be read by the cart owner (59ms)
shopping cart items
✓ items can be read by the cart owner
✓ items can be added by the cart owner
adding an item to the cart recalculates the cart total.
✓ should sum the cost of their items (800ms)
5 passing (1s)
آفرین!
۲۰. آن را بااستفاده از واسط کاربر «ویترین فروشگاه» امتحان کنید
برای آزمایش نهایی، به برنامه وب ( http://127.0.0.1:5000/) برگردید و موردی را به سبد خرید اضافه کنید.

تأیید کنید که سبد خرید با مجموع درست بهروز میشود. فوقالعاده است!
خلاصه
یک چارچوب تست پیچیده را بین Cloud Functions ویژه Firebase و Cloud Firestore بررسی کردهاید. برای گذراندن آزمون، یک Cloud Function نوشتید. همچنین تأیید کردید که عملکرد جدید در واسط کاربر کار میکند! همه این کارها را بهصورت محلی و با اجرای شبیهسازها در دستگاه خودتان انجام دادید.
همچنین یک کارخواه وب ایجاد کردهاید که دربرابر شبیهسازهای محلی اجرا میشود، قوانین امنیتی را برای محافظت از دادهها سفارشی کردهاید، و قوانین امنیتی را بااستفاده از شبیهسازهای محلی آزمایش کردهاید.
