Firestore gRPC Listen接口未推送文档删除事件问题排查

问题描述 #

使用Postman调用firestore.googleapis.com的gRPC Listen接口，通过Firebase控制台手动修改Firestore数据测试：

• 新增文档时能正常收到document_change消息
• 删除文档时，无法收到document_change、document_delete或document_remove消息，但过滤器响应中的计数会随删除操作减少，说明删除已被识别但未推送变更

操作流程 #

• 调用Listen接口
• 发送ListenRequest请求
• 检查响应，获取目标ID对应的过滤器计数，以及CURRENT类型target_change响应中的resumeToken
• 结束流
• 在网页UI中删除文档
• 再次调用Listen接口
• 携带步骤3获取的计数和resumeToken发送ListenRequest
• 检查响应，目标ID对应的过滤器计数降低，但未收到任何文档变更或删除相关消息

ListenRequest示例 #

Metadata: google-cloud-resource-prefix = projects/project1/databases/database1

{
    "database": "projects/project1/databases/database1",
    "add_target": {
        "target_id": 1,
        "resume_token": "CgkIzoO/uauyiwM=",
        "expected_count": {"value": 6},
        "query": {
            "parent": "projects/project1/databases/database1/documents",
            "structured_query": {
                "from": [
                    {
                        "collection_id": "TestCollection1",
                        "all_descendants": false
                    }
                ]
            }
        }
    },
    "once": false
}

问题排查与解决方案 #

1. 结构化查询无语法错误 #

你的查询语法是正确的，针对指定集合的默认监听本应覆盖文档的增、改、删事件，问题不在查询结构本身。

2. expected_count参数误用导致删除事件不推送 #

当携带resume_token恢复监听时，expected_count用于验证当前快照的文档数量是否与预期匹配。但Firestore在恢复增量更新时，只会推送自上次快照以来的新增/修改事件——删除操作导致的计数减少，不会主动触发document_delete事件，因为被删除的文档已经从resume_token对应的快照中移除。

3. 正确的监听实现方式 #

• 保持长连接不中断：Listen接口设计为双向长连接模式，只有保持流持续开启，才能实时接收所有变更（包括删除）。你当前断开流再重连的流程，不适合实时监听场景。
• 重连时移除expected_count：如果必须断开重连，删除expected_count参数，让Firestore重新发送当前集合的完整快照，此时会包含已删除文档的document_delete事件。
• 确认无额外过滤条件：你的查询没有设置过滤规则，这点没问题，默认集合监听会覆盖所有文档操作。

4. 其他排查方向 #

• 权限验证：确认Bearer令牌包含datastore.listen权限（Firebase Admin SDK令牌默认包含，自定义令牌需额外配置）。
• 客户端工具限制：Postman的gRPC客户端可能在双向流重连时存在解析问题，建议用官方SDK（如Node.js、Java）测试对比，排除工具本身的问题。
• 后端状态排查：尝试在不同Firestore区域测试，排除特定节点临时故障，但这种情况概率极低。

内容的提问来源于stack exchange，提问作者user17331277