此页面由 Cloud Translation API 翻译。

使用 Firestore 模拟器测试 Datastore 模式

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

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

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

安装模拟器

如需安装 Firestore 模拟器，请安装并更新 gcloud CLI：

安装 gcloud CLI。
更新您的 gcloud CLI 安装，以获取最新功能：
```
gcloud components update
```

运行模拟器

运行以下命令启动模拟器：
```
gcloud emulators firestore start --database-mode=datastore-mode
```
该模拟器将输出其运行所在的主机和端口号。

默认情况下，模拟器会尝试使用 127.0.0.1:8080。如需将该模拟器绑定到特定的主机和端口，请使用可选的 --host-port 标志，并替换 HOST 和 PORT：
```
gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT
```
使用键盘快捷键 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 操作，将 HOST 和 PORT 替换为您选择的主机和端口，并将 PROJECT_ID 替换为您自己的项目 ID：

http://HOST:PORT/reset

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

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

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

模拟器与生产环境的区别

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

并发和一致性

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

交易

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

索引

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

限制

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

后续步骤

了解如何使用实体、属性和键
了解查询