توسعه محلی با Firebase Emulator Suite

۱. قبل از شروع

استفاده از ابزارهای پسین بدون سرور مانند Cloud Firestore و Cloud Functions بسیار آسان است، اما آزمایش آن‌ها می‌تواند دشوار باشد. «مجموعه شبیه‌ساز محلی Firebase» به شما امکان می‌دهد نسخه‌های محلی این سرویس‌ها را در ماشین توسعه نرم‌افزار خود اجرا کنید تا بتوانید برنامه‌تان را به‌سرعت و به‌طور ایمن توسعه دهید.

پیش‌نیازها

کارهایی که انجام خواهید داد

در این codelab، یک برنامه خرید آنلاین ساده را که توسط چندین سرویس Firebase پشتیبانی می‌شود، اجرا و اشکال‌زدایی خواهید کرد:

  • Cloud Firestore: پایگاه داده NoSQL بدون سرور با قابلیت مقیاس‌پذیری جهانی و قابلیت‌های هم‌زمان.
  • Cloud Functions: کد باطن بدون سرور که در پاسخ به رویدادها یا درخواست‌های HTTP اجرا می‌شود.
  • اصالت‌سنجی Firebase: سرویس اصالت‌سنجی مدیریت‌شده‌ای که با دیگر محصولات Firebase ادغام می‌شود.
  • میزبانی Firebase: میزبانی سریع و ایمن برای برنامه‌های وب.

برای فعال کردن توسعه محلی، برنامه را به «مجموعه شبیه‌ساز» متصل خواهید کرد.

2589e2f95b74fa88.png

همچنین با نحوه انجام کارهای زیر آشنا خواهید شد:

  • نحوه اتصال برنامه به «مجموعه شبیه‌ساز» و نحوه اتصال شبیه‌سازهای مختلف.
  • نحوه عملکرد 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

  1. بااستفاده از «حساب Google» خود به سیستم کنسول Firebase وارد شوید.
  2. برای ایجاد پروژه جدید، روی دکمه کلیک کنید و سپس نام پروژه را وارد کنید (برای مثال، Emulators Codelab).
  3. روی ادامه کلیک کنید.
  4. اگر درخواست شد، شرایط Firebase را مرور و قبول کنید، سپس روی ادامه کلیک کنید.
  5. (اختیاری) «کمک هوش مصنوعی» را در کنسول Firebase (به‌نام «Gemini در Firebase») فعال کنید.
  6. برای این codelab، به Google Analytics نیاز ندارید، بنابراین گزینه Google Analytics را خاموش کنید.
  7. روی ایجاد پروژه کلیک کنید، منتظر بمانید تا پروژه‌تان آماده شود، سپس روی ادامه دادن کلیک کنید.

کدتان را به پروژه 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 وارد شده‌اند.

4ef88d0148405d36.png

۴. اجرای برنامه

باز کردن برنامه

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

939f87946bac2ee4.png

استفاده از برنامه

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

a11bd59933a8e885.png

بیایید آن اشکال را برطرف کنیم! چون همه چیز در شبیه‌سازها اجرا می‌شود، می‌توانیم آزمایش کنیم و نگران تأثیر گذاشتن بر داده‌های واقعی نباشیم.

۵. اشکال‌زدایی برنامه

یافتن اشکال

بسیار خوب، بیایید در کنسول توسعه‌دهندگان Chrome نگاه کنیم. کلیدهای Control+Shift+J (Windows،‏ Linux،‏ Chrome OS) یا Command+Option+J (Mac) را فشار دهید تا خطا را در کنسول ببینید:

74c45df55291dab1.png

به‌نظر می‌رسد خطایی در روش 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;
    }

    // ...
  }

آزمایش برنامه

اکنون، صفحه را بازآوری کنید و سپس روی افزودن به سبد خرید کلیک کنید. این بار باید خطای بهتری دریافت کنید:

c65f6c05588133f7.png

اما اگر در نوار ابزار بالا روی ورود به سیستم کلیک کنید و سپس دوباره روی افزودن به سبد خرید کلیک کنید، خواهید دید که سبد خرید به‌روز می‌شود.

بااین‌حال، به‌نظر نمی‌رسد که این اعداد اصلاً درست باشند:

239f26f02f959eef.png

نگران نباشید، به‌زودی این اشکال را برطرف می‌کنیم. ابتدا، بیایید عمیقاً بررسی کنیم که وقتی موردی را به سبد خریدتان اضافه کردید، واقعاً چه اتفاقی افتاد.

‫۶. راه‌اندازهای توابع محلی

کلیک کردن روی افزودن به سبد خرید زنجیره‌ای از رویدادها را آغاز می‌کند که شامل چندین شبیه‌ساز است. در گزارش‌های واسط خط فرمان Firebase، پس‌از افزودن موردی به سبد خریدتان، باید چیزی شبیه پیام‌های زیر ببینید:

i  functions: Beginning execution of "calculateCart"
i  functions: Finished "calculateCart" in ~1s

چهار رویداد کلیدی رخ داده است که این گزارش‌ها و به‌روزرسانی میانای کاربری را که مشاهده کردید تولید کرده است:

68c9323f2ad10f7a.png

۱) 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 برای آزمایش کاملاً محلی استفاده می‌کند.

db82eef1706c9058.gif

اما صبر کنید، چیزهای بیشتری موجود است! در بخش بعدی با این موارد آشنا می‌شوید:

  • نحوه نوشتن آزمون‌های واحدی که از «شبیه‌سازهای 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، تأیید کنید که شبیه‌ساز قوانین را به‌روز کرده است:

5680da418b420226.png

آزمایش‌ها را دوباره اجرا کنید و بررسی کنید که دو آزمایش اول اکنون با موفقیت انجام می‌شوند:

$ 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) برگردید و موردی را به سبد خرید اضافه کنید. این مرحله مهمی برای تأیید این است که آزمایش‌ها و قوانین ما با عملکرد موردنیاز مشتری مطابقت دارد. (به‌یاد داشته باشید که آخرین باری که میانای کاربری را امتحان کردیم، کاربران نتوانستند موردی به سبد خریدشان اضافه کنند!)

69ad26cee520bf24.png

وقتی firestore.rules ذخیره می‌شود، کارخواه به‌طور خودکار قوانین را مجدداً بار می‌کند. بنابراین، چیزی به سبد خرید اضافه کنید.

خلاصه

آفرین! امنیت برنامه‌تان را بهبود بخشیدید، این گامی ضروری برای آماده کردن آن برای تولید است! اگر این برنامه تولید بود، می‌توانستیم این آزمایش‌ها را به خط لوله ادغام مداوم خود اضافه کنیم. این کار به ما اطمینان می‌دهد که در آینده داده‌های سبد خرید ما این کنترل‌های دسترسی را خواهند داشت، حتی اگر دیگران قوانین را تغییر دهند.

ba5440b193e75967.gif

ولی صبر کنید، هنوز هست!

اگر ادامه دهید، با موارد زیر آشنا می‌شوید:

  • نحوه نوشتن تابع راه‌اندازی‌شده با رویداد 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» پیدا کنید:

d6d0429b700d2b21.png

‫۱۶. انجام دادن گام‌به‌گام آزمایش‌های «توابع»

چون این آزمایش تعامل بین 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/) برگردید و موردی را به سبد خرید اضافه کنید.

69ad26cee520bf24.png

تأیید کنید که سبد خرید با مجموع درست به‌روز می‌شود. فوق‌العاده است!

خلاصه

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

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

c6a7aeb91fe97a64.gif