將您的應用程式連接到 Cloud Firestore 模擬器

在將您的應用程式連接到 Cloud Firestore 模擬器之前,請確保您了解 Firebase 本機模擬器套件的整體工作流程,並安裝和設定本機模擬器套件並查看其CLI 命令

選擇 Firebase 項目

Firebase 本機模擬器套件模擬單一 Firebase 專案的產品。

若要選擇要使用的項目,請在啟動模擬器之前,在 CLI 中在工作目錄中執行firebase use 。或者,您可以將--project標誌傳遞給每個模擬器指令。

本機模擬器套件支援模擬真實的Firebase 專案和演示專案。

項目類型特徵與模擬器一起使用
真實的

真正的 Firebase 專案是您建立和配置的專案(很可能透過 Firebase 控制台)。

真實專案具有即時資源,例如資料庫執行個體、儲存桶、函數或您為該 Firebase 專案設定的任何其他資源。

在處理真實的 Firebase 專案時,您可以為任何或所有受支援的產品運行模擬器。

對於您未模擬的任何產品,您的應用程式和程式碼將與即時資源(資料庫執行個體、儲存桶、函數等)進行互動。

示範

示範 Firebase 專案沒有真正的Firebase 配置,也沒有即時資源。這些項目通常透過代碼實驗室或其他教程存取。

示範項目的項目 ID 具有demo-前綴。

使用示範 Firebase 專案時,您的應用程式和程式碼與模擬器互動。如果您的應用程式嘗試與未運行模擬器的資源進行交互,則該程式碼將會失敗。

我們建議您盡可能使用演示項目。好處包括:

  • 設定更簡單,因為您無需建立 Firebase 專案即可運行模擬器
  • 更強的安全性,因為如果您的程式碼意外調用非模擬(生產)資源,則不會發生資料變更、使用和計費
  • 更好的離線支持,因為無需訪問互聯網即可下載 SDK 配置。

檢測您的應用程式以與模擬器對話

啟動時,Cloud Firestore 模擬器會為firebase.json檔案中的每個firestore配置建立一個預設資料庫和一個命名資料庫。使用firebase.json檔案將 Cloud Firestore 安全性規則明確指派給指定資料庫。

命名資料庫也會隱式創建,以回應對引用特定資料庫的模擬器的任何 SDK 或 REST API 呼叫。這種隱式創建的資料庫按照開放規則運作。

目前,Emulator Suite UI 支援與預設資料庫的互動工作。

Android、Apple 平台和 Web SDK

設定應用程式內配置或測試類別以與 Cloud Firestore 交互,如下所示。請注意,在以下範例中,應用程式程式碼連接到預設專案資料庫。有關涉及預設資料庫以外的其他 Cloud Firestore 資料庫的範例,請參閱多個資料庫指南

Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
迅速
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.isPersistenceEnabled = false
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Web modular API

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);

Web namespaced API

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}

使用模擬器測試由 Firestore 事件觸發的Cloud Functions 無需進行任何額外設定。當 Firestore 和 Cloud Functions 模擬器同時運作時,它們會自動協同運作。

管理 SDK

設定FIRESTORE_EMULATOR_HOST環境變數後,Firebase Admin SDK 會自動連接到 Cloud Firestore 模擬器:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

如果您的程式碼在 Cloud Functions 模擬器內執行,您的專案 ID 和其他配置將在呼叫initializeApp時自動設定。

如果您希望 Admin SDK 程式碼連接到在其他環境中執行的共用模擬器,則需要指定使用 Firebase CLI 設定的相同專案 ID 。您可以直接將專案ID傳遞給initializeApp或設定GCLOUD_PROJECT環境變數。

Node.js 管理 SDK
admin.initializeApp({ projectId: "your-project-id" });
環境變數
export GCLOUD_PROJECT="your-project-id"

在測試之間清除資料庫

Production Firestore 不提供用於刷新資料庫的平台 SDK 方法,但 Firestore 模擬器為您提供了專門用於此目的的 REST 端點,可以從測試框架設定/拆卸步驟、測試類別或 shell(例如,使用curl )在測試開始之前。您可以使用此方法作為簡單關閉模擬器進程的替代方法。

在適當的方法中,執行 HTTP DELETE 操作,為下列端點提供您的 Firebase 專案 ID(例如firestore-emulator-example ):

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

當然,您的程式碼應該等待刷新完成或失敗的 REST 確認。

您可以從 shell 執行此操作:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

實施這樣的步驟後,您可以對測試進行排序並觸發您的功能,並確信舊資料將在運行之間被清除,並且您正在使用新的基線測試配置。

導入導出數據

資料庫和 Cloud Storage for Firebase 模擬器可讓您從正在執行的模擬器實例匯出資料。定義要在單元測試或持續整合工作流程中使用的基準資料集,然後將其匯出以在團隊之間共用。

firebase emulators:export ./dir

在測試中,在模擬器啟動時導入基線資料。

firebase emulators:start --import=./dir

您可以指示模擬器在關閉時匯出數據,可以指定匯出路徑,也可以只使用傳遞給--import標誌的路徑。

firebase emulators:start --import=./dir --export-on-exit

這些資料導入和匯出選項也適用於firebase emulators:exec指令。有關更多信息,請參閱模擬器命令參考。

可視化安全規則活動

當您完成原型和測試循環時,您可以使用本機模擬器套件提供的視覺化工具和報告。

使用請求監視器

Cloud Firestore 模擬器可讓您在模擬器套件 UI 中視覺化用戶端請求,包括 Firebase 安全規則的評估追蹤。

開啟Firestore > 請求標籤以查看每個請求的詳細評估順序。

Firestore 模擬器要求監視器顯示安全規則評估

視覺化規則評估報告

當您將安全規則新增至原型時,您可以使用本機模擬器套件偵錯工具對其進行偵錯。

執行一套測試後,您可以存取測試覆蓋率報告,其中顯示每個安全規則的評估。

若要取得報告,請在模擬器執行時查詢模擬器上公開的端點。對於瀏覽器友善的版本,請使用以下 URL:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

這會將您的規則分解為表達式和子表達式,您可以將滑鼠懸停在這些表達式和子表達式上以獲取更多信息,包括計算數量和返回值。對於此資料的原始 JSON 版本,請在查詢中包含以下 URL:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

此處,報告的 HTML 版本突出顯示了引發未定義和空值錯誤的評估:

Cloud Firestore 模擬器與生產環境有何不同

Cloud Firestore 模擬器嘗試忠實複製生產服務的行為,但存在一些明顯的限制。

Cloud Firestore 的多資料庫支持

目前,Emulator Suite UI 支援預設資料庫的互動式建立、編輯、刪除、請求監控和安全性視覺化,但不支援其他命名資料庫。

但是,模擬器本身會根據firebase.json檔案中的配置建立一個命名資料庫,並隱含地回應 SDK 或 REST API 呼叫。

交易

模擬器目前並未實現生產中看到的所有事務行為。當您測試涉及對一個文件進行多個並發寫入的功能時,模擬器完成寫入請求的速度可能會很慢。在某些情況下,鎖定可能需要長達 30 秒才能釋放。如果需要,請考慮相應地調整測試超時。

索引

模擬器不追蹤複合索引,而是執行任何有效的查詢。請務必針對真實的 Cloud Firestore 執行個體測試您的應用,以確定您需要哪些索引。

限制

模擬器不會強制執行生產中強制執行的所有限制。例如,模擬器可能允許因過大而被生產服務拒絕的交易。確保您熟悉記錄的限制,並確保您設計的應用程式能夠主動避免這些限制。

接下來是什麼?