Google Cloud CLI 提供一个内存中的本地模拟器, 可用于测试 Datastore 模式 Firestore 应用的 Firestore。 您可以将该模拟器与所有 Datastore 模式客户端库搭配使用。您应仅将模拟器用于本地测试。
将 gcloud emulators firestore
与 --database-mode=datastore-mode
搭配使用,以测试 Datastore 模式 Firestore 的行为。
请勿将模拟器用于生产部署。由于模拟器仅将数据存储在内存中,因此数据在各次运行之间不会保留。
安装模拟器
如需安装 Firestore 模拟器,请安装并更新 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 模式实例测试您的应用,以确定您需要哪些索引。
限制
模拟器不会强制执行生产环境中强制执行的所有限制。例如,模拟器可能会允许因为过大而会被生产服务拒绝的事务。请确保您熟悉文档中记录的限制,并且将您的应用设计为主动避免超出这些限制。