Firestore子集合监听器双触发与文档监听器行为差异咨询

问题背景 #

我正在开发以Firebase为后端的iOS应用，目前遇到子集合监听器行为异常的问题：

数据结构 #

顶层集合命名为families，其下包含名为chores的子集合，结构参考下图：

监听器实现代码 #

iOS端为chores子集合添加监听器的代码如下：

func readChoreCollection(_ familyId: String) {
    if familyChoresListener == nil {
        let choreCollection = database.collection("families").document(familyId).collection("chores")
        familyChoresListener = choreCollection.order(by: "created")
            .addSnapshotListener(includeMetadataChanges: false) { [weak self] querySnapshot, error in
                print("\(#fileID) \(#function): \(choreCollection.path)")
                guard let querySnapshot = querySnapshot else {
                    print("\(#fileID) \(#function): Error fetching documents: \(error!)")
                    return
                }
                let chores: [Chore] = querySnapshot.documents
                    .compactMap { document in
                        do {
                            return try document.data(as: Chore.self)
                        } catch {
                            print("\(#fileID) \(#function): error")
                            return nil
                        }
                    }
                if chores.isEmpty {
                    print("\(#fileID) \(#function): received empty list, publishing nil...")
                    self?.familyChoresPublisher.send(nil)
                } else {
                    print("\(#fileID) \(#function): received chores data, publishing ... \(querySnapshot.metadata.hasPendingWrites)")
                    self?.familyChoresPublisher.send(chores)
                }
            }
    }
}

现象描述 #

根据Firestore官方文档，查询结果发生变化（新增、删除、修改文档）时，快照处理器会收到新的查询快照。我向chores子集合新增文档时，监听器确实会触发，但会连续触发两次：一次对应本地变更，一次对应远端变更，运行日志如下：

ChoreReward/ChoreRepository.swift readChoreCollection(_:): received chores data, publishing ... true
ChoreReward/ChoreService.swift addSubscription(): received and cached a non-nil chore list
ChoreReward/ChoreRepository.swift readChoreCollection(_:): families/tgO0B4bjq8uwAzmBaOtL/chores
ChoreReward/ChoreRepository.swift readChoreCollection(_:): received chores data, publishing ... false
ChoreReward/ChoreService.swift addSubscription(): received and cached a non-nil chore list

两次回调分别对应hasPendingWrites = true（本地待写入状态）和hasPendingWrites = false（服务端已确认状态），符合文档中“本地变更会在提交到服务端前优先触发回调”的描述，但我在应用内使用的其他文档级监听器仅会在远端变更时触发一次，不会出现两次触发的情况。

疑问 #

文档监听器与集合/查询监听器是否存在行为差异？该差异是否为官方预期设计？

回答 #

这是Firestore的预期官方行为，文档监听器和集合/查询监听器在事件触发逻辑上没有本质差异，你观察到的单文档监听器只触发一次，是场景或代码判断逻辑差异导致的，不是底层设计不一致。

两次触发的原因 #

Firestore SDK为了实现低延迟的UI响应，默认开启延迟补偿（Latency Compensation）机制：

• 第一次回调（hasPendingWrites = true）：调用写入接口后，SDK不会等待服务端返回结果，会立刻把未提交的写入更新到本地缓存，触发所有匹配该数据的监听器。这时候拿到的是乐观更新的本地数据，目的是让UI可以立刻响应用户操作，省去网络往返的等待时间。
• 第二次回调（hasPendingWrites = false）：服务端成功持久化写入数据后，会把确认结果回传给SDK，SDK更新本地缓存中对应文档的状态（标记为已提交），再次触发监听器。

注：你设置的includeMetadataChanges: false只会过滤掉「文档内容无变化、仅同步元数据更新」的事件，本地写入带来的内容+元数据同时变更的事件不会被过滤，所以两次触发和这个参数配置无关。

单文档监听器只触发一次的常见原因 #

你遇到的单文档监听器没有两次触发，基本是以下两种情况之一：

• 单文档监听器的回调中没有打印/判断hasPendingWrites字段，两次回调都正常收到了，但没有区分状态，误以为只触发了一次。
• 注册单文档监听器的时机晚于本地写入完成的节点，错过了第一次本地待写入状态的回调，只收到了服务端确认后的回调。

可选优化方案 #

如果你的业务不需要区分本地乐观更新和服务端确认状态，只需要处理最终落库的稳定数据，可以在监听器回调最前面加一层判断，过滤掉待写入状态的事件即可：

// 集合/查询监听器使用
guard !querySnapshot.metadata.hasPendingWrites else { return }

// 单文档监听器使用
guard !documentSnapshot.metadata.hasPendingWrites else { return }

两种监听器的metadata判断逻辑完全一致，不存在行为差异。

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