Firebase JS SDK 中时间戳字段缓存查询问题的分析与解决方案

问题背景

在使用 Firebase JS SDK 的 Firestore 模块时，开发者在启用了持久化缓存功能后，发现针对时间戳(Timestamp)字段的等值查询(equality query)无法返回预期的结果。具体表现为：当查询条件为精确匹配某个时间戳时，返回结果为空；而当使用范围查询(>=和<)时，却能正确返回所有匹配文档。

问题复现条件

该问题在以下特定环境下出现：

1. 使用 Firebase JS SDK 版本 10.7.2
2. 启用了持久化本地缓存功能
3. 在 Web Worker 中运行 Firestore
4. 查询条件为时间戳字段的精确匹配
5. 客户端自动创建了索引

技术分析

根本原因

经过 Firebase 团队的调查，发现问题出在客户端索引与时间戳字段查询的交互上。当满足以下所有条件时，查询会出现异常：

• 启用了持久化缓存
• 存在客户端自动创建的索引
• 查询条件为时间戳字段的精确匹配

现象解释

在问题场景中，开发者观察到：

1. 禁用缓存时，等值查询能正确返回结果
2. 启用缓存后，等值查询返回空结果
3. 改用范围查询(>=和<)可以绕过问题
4. 日志显示服务器端确实有匹配文档(expectedCount正确)

这表明问题不是数据本身的问题，而是客户端缓存处理逻辑的缺陷，特别是在处理时间戳字段和索引的交互时。

解决方案

临时解决方案

Firebase 团队提供了以下临时解决方案：

1. 禁用客户端索引自动创建： 不要调用 enablePersistentCacheIndexAutoCreation() 方法，保持其默认禁用状态。

2. 清除现有索引： 使用 deleteAllPersistentCacheIndexes(indexManager) 方法清除所有已创建的客户端索引。

3. 手动创建必要索引： 如果确实需要某些字段的索引(非时间戳字段)，可以使用 setIndexConfiguration(firestore, configuration) 方法手动创建。

替代查询方案

开发者发现可以将等值查询转换为小范围查询来绕过此问题：

const start = Timestamp.fromMillis(ms);
const end = Timestamp.fromMillis(ms + 1000);
const query = query(collection, where("timestampField", ">=", start), 
                          where("timestampField", "<", end));

这种方法在实际测试中表现正常，可以作为临时解决方案使用。

最佳实践建议

1. 谨慎使用客户端索引：在 Firebase 修复此问题前，避免在时间戳字段上创建客户端索引。

2. 测试缓存行为：在启用持久化缓存后，务必测试所有类型的查询，特别是涉及时间戳的查询。

3. 监控日志：启用调试日志(setLogLevel('debug'))有助于诊断类似问题。

4. 多环境验证：在开发过程中，应在禁用缓存和启用缓存两种状态下验证查询结果。

总结

这是一个特定于 Firebase JS SDK 中 Firestore 模块的缓存处理问题，主要影响时间戳字段的等值查询。虽然 Firebase 团队已经确认问题并正在开发修复方案，但开发者可以通过禁用自动索引创建或调整查询方式来解决当前遇到的问题。理解这一问题的本质有助于开发者在其他类似场景中更好地诊断和解决数据查询异常。