使用 Firestore Bundle Builder 扩展程序

Firestore Bundle Builder (firestore-bundle-builder) 扩展程序会部署一个 HTTP 函数,用于提供 Cloud Firestore 数据捆绑包。您需要在 Firestore 文档中定义捆绑包,然后,该扩展程序会通过 HTTP 请求以及 Firebase Hosting CDN 或 Cloud Storage 的各种内置缓存机制来提供静态二进制文件数据捆绑包。如果不存在任何捆绑包或现有捆绑包均已过期,此函数将按需构建并缓存一个新的捆绑包。

如需使用此扩展程序,您需要先在 Firestore 中通过该扩展程序的管理员信息中心创建一个或多个捆绑包规范。捆绑包规范指明了您的命名查询(即要添加到捆绑包的集合查询及特定文档路径)的定义方式。

在捆绑包规范内,您还可以定义要在命名查询中使用的参数。调用 HTTP 函数时,您可以使用网址查询参数来设置这些参数的值。

上面的链接提供了一些相关指令,以便您可以在本地运行管理员实用程序。设置 Web 应用后,请前往 localhost:3000 以使用该界面创建规范:

示例

构建和提供捆绑包

安装该扩展程序并创建捆绑包规范后,您便可以开始通过调用该扩展程序提供的 HTTP 端点来构建和提供捆绑包。

根据捆绑包规范,系统可能会从客户端的缓存、Firebase Hosting 缓存或 Cloud Storage 文件中返回请求的捆绑包。如果所有缓存均已过期,系统会发出一个新的提供请求来触发 Firestore 查询并按需构建捆绑包。

您可以利用重写规则设置一个指向提供函数的 Firebase Hosting 网站,从而利用 Firebase Hosting CDN 的功能。CDN 会将您的捆绑包复制到许多不同的服务器上,这样您的用户便可自动从最近的服务器加载该捆绑包。这是首选方法。

如需在 Firebase Hosting 中进行此设置,请使用以下内容创建或修改 firebase.json 文件,然后部署该网站

{
  "hosting": {
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "rewrites": [
      {
        "source": "/bundles/*",
        "function": "ext-firestore-bundle-builder-serve"
      }
    ]
  }
}

部署完成后,您便可以使用该网站的网址从 CDN 访问您的捆绑包。例如:https://your-site-url.com/bundles/:bundleId

或者,如果您不想使用 Firebase Hosting,也可以将该扩展程序配置为在 Cloud Storage 中缓存数据。在这种情况下,您可以直接调用已部署的 HTTP 函数来生成捆绑包。

客户端集成

接下来,您可以通过 Cloud Firestore SDK 的 loadBundle API 使用捆绑包。首先,您需要下载捆绑包,然后将其提供给 SDK。例如:

import { loadBundle } from "firebase/firestore";

// Download the bundle from the Firebase Hosting CDN:
const bundle = await fetch("/bundles/:bundleId");

// If not using a CDN, download the bundle directly:
// const bundle = await fetch('https://<location>-<project-id>.cloudfunctions.net/ext-firestore-bundle-builder-serve/:bundleId');

await loadBundle(bundle);

加载完成后,您便可以使用捆绑包中的数据:

如果您在定义捆绑包时指定了文档路径数组,则可以通过捆绑包获取客户端上的文档数据:

import { getFirestore, doc, getDocFromCache } from "firebase/firestore";
// Bundle Document IDs: ['users/92x1NgSWYKUC4AG4s2nHGMR2ikZ2']

const ref = doc(getFirestore(), "users/92x1NgSWYKUC4AG4s2nHGMR2ikZ2");
const snapshot = await getDocFromCache(ref);

如果您指定了查询,则可以使用 namedQuery API 从捆绑包运行查询:

import { getFirestore, namedQuery } from "firebase/firestore";
const query = await namedQuery(getFirestore(), "queryId");
const snapshot = await getDocsFromCache(query);

查询 ID 会被定义为每个 queries 属性定义的键(见下文)。