使用 Firestore 模拟器测试 Datastore 模式

Google Cloud CLI 提供一个内存中的本地模拟器, 可用于测试 Datastore 模式 Firestore 应用的 Firestore。 您可以将该模拟器与所有 Datastore 模式客户端库搭配使用。您应仅将模拟器用于本地测试。

gcloud emulators firestore--database-mode=datastore-mode 搭配使用,以测试 Datastore 模式 Firestore 的行为。

请勿将模拟器用于生产部署。由于模拟器仅将数据存储在内存中,因此数据在各次运行之间不会保留。

安装模拟器

如需安装 Firestore 模拟器,请安装并更新 gcloud CLI:

  1. 安装 gcloud CLI

  2. 更新您安装的 gcloud CLI 以获取最新版本 功能:

    gcloud components update
    

运行模拟器

  1. 运行以下命令启动模拟器:

    gcloud emulators firestore start --database-mode=datastore-mode
    

    该模拟器将输出其运行所在的主机和端口号。

    默认情况下,模拟器会尝试使用 127.0.0.1:8080。要绑定 连接到特定主机和端口,请使用可选的 --host-port 标志, 替换 HOSTPORT

    gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT
    
  2. 使用键盘快捷键 Control + C 停止模拟器。

连接到模拟器

如需将客户端库和应用连接到模拟器,请设置 DATASTORE_EMULATOR_HOST 环境变量。当此环境 变量时,客户端库会自动连接到模拟器。

export DATASTORE_EMULATOR_HOST="HOST:PORT"

将实体导入模拟器

借助模拟器的导入功能,您可以将一组实体导出文件中的实体加载到模拟器中。实体导出文件可在从 Datastore 模式数据库或模拟器实例中导出数据时加以创建。

您可以通过两种方式将实体导入模拟器。第一步是添加 在模拟器启动命令中添加 import-data 标志。第二种方法是向模拟器发送 POST 导入请求。您可以使用 curl 或类似工具。请参阅 示例。

协议

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:import \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'
如果模拟器使用其他端口,请修改 localhost:8080

CLI 标志

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY

其中:

  • [PROJECT_ID] 是您的项目 ID。
  • [DATABASE] 是数据库路径。例如,使用默认数据库的项目如下所示:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] 是实体导出文件中的 overall_export_metadata 文件的路径。例如:

    {"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}

在模拟器中导出实体

借助模拟器的导出功能,您可以将模拟器中的实体保存到一组实体导出文件中。然后,您可以使用导入操作将实体导出文件中的实体加载到 Datastore 模式数据库或模拟器实例中。

您可以通过两种方式从模拟器中导出实体。第一步是添加 在模拟器启动命令中添加 export-on-exit 标志。第二种方法是 向模拟器发送 POST 导出请求。您可以使用 curl 或类似工具。请参阅 示例。

协议

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:export \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE_PATH", "export_directory":"EXPORT_DIRECTORY"}'
如果模拟器使用其他端口,请修改 localhost:8080

CLI 标志

gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY

其中:

  • [PROJECT_ID] 是您的项目 ID。
  • [DATABASE_PATH] 是数据库路径。例如,使用默认数据库的项目如下所示:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] 用于指定模拟器保存实体导出文件的目录。此目录不得预先包含一组实体导出文件。例如:

    {"export_directory":"/home/user/myexports/2024-03-26/"}

在模拟器中保留数据

默认情况下,Firestore 模拟器不会将数据持久保留在磁盘上。 如需保留模拟器数据,请运行以下命令以使用导入和导出功能 标志以跨模拟器实例加载和保存数据:

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY --export-on-exit=EXPORT_DIRECTORY

重置模拟器数据

Firestore 模拟器包含一个 REST 端点,用于重置模拟器中的所有数据。您可以使用此端点在测试之间清除数据,而无需关闭模拟器。

要重置模拟器中的所有数据,请执行 HTTP POST 操作 并将 HOSTPORT 替换为 主机和端口,并将 PROJECT_ID 替换为您的 自己的项目 ID:

http://HOST:PORT/reset

如果模拟器不使用 127.0.0.1:8080,请调整主机和端口。 您的代码应等待关于重置完成或失败的 REST 确认信息。

您可以使用 curl 通过 shell 执行此操作:

$ curl -X POST "http://HOST:PORT/reset"

模拟器与生产环境的区别

该模拟器会尝试真实地重现生产服务的行为,但存在一些值得注意的限制。

并发和一致性

模拟器仅支持悲观并发和强一致性。模拟器不支持乐观并发和最终一致性设置。

交易

模拟器不会实现所有事务行为 可反映实际情况。当您要测试涉及对一个文档执行多次并发写入的功能时,模拟器完成写入请求的速度可能会很慢。在某些情况下,对数据的锁定可能需要长达 30 秒才会解除。如有需要,请考虑相应地调整测试超时时长。

索引

模拟器不会跟踪复合索引,而是执行任何有效查询。请务必对真实的 Datastore 模式实例测试您的应用,以确定您需要哪些索引。

限制

模拟器不会强制执行生产环境中强制执行的所有限制。例如,模拟器可能会允许因为过大而会被生产服务拒绝的事务。请确保您熟悉文档中记录的限制,并且将您的应用设计为主动避免超出这些限制。

后续步骤