Flutter去重合并双Firebase Future<QuerySnapshot>供Future Builder渲染

Firebase Firestore 原生的 QuerySnapshot 是SDK封装的不可变结构，没法直接把两个查询的返回结果硬塞成原生实例，但完全可以通过并行触发双查询→按文档ID去重→构造符合QuerySnapshot接口的合并实例的路径，100%匹配原代码的类型要求，不用改动现有FutureBuilder的内部渲染代码。

具体落地步骤 #

• 并行触发双查询，别串行等结果
  用Future.wait同时发起两个搜索查询，整体耗时和单查询基本一致，不会比原来的串行写法慢：

  // 替代原有两个独立的Future定义，实现完整的合并逻辑
  Future<QuerySnapshot> mergeSearchResults(String searchKeyword) async {
    // 完全复用原代码的关键词归一化处理
    final normalizedStr = searchKeyword.toLowerCase().replaceAll(' ', '');
    // 并行执行两个查询
    final queryResults = await Future.wait([
      usersReference
          .where("searchName", isGreaterThanOrEqualTo: normalizedStr)
          .limit(5)
          .get(),
      usersReference
          .where("searchName", isEqualTo: normalizedStr)
          .limit(5)
          .get(),
    ]);
  

• 按文档唯一ID去重，别用文档内容判断
  直接以文档ID作为重复判断的唯一依据，避免同名字段的不同文档被误判成重复数据：

  final uniqueDocIds = <String>{};
    final mergedDocs = <DocumentSnapshot>[];
    // 遍历两个查询的所有返回文档，去重收集
    for (final snapshot in queryResults) {
      for (final doc in snapshot.docs) {
        if (!uniqueDocIds.contains(doc.id)) {
          uniqueDocIds.add(doc.id);
          mergedDocs.add(doc);
        }
      }
    }
  

• 构造适配QuerySnapshot接口的合并实例
  只实现FutureBuilder渲染会用到的核心方法，完全匹配返回类型要求：

  // 返回值类型和原变量要求的Future<QuerySnapshot>完全一致
    return MergedQuerySnapshot(
      docsList: mergedDocs,
      isFromCache: queryResults.first.metadata.isFromCache,
    );
  }
  

  对应的自定义快照实现类，不需要实现所有接口，只覆盖实际用到的成员就行：

  class MergedQuerySnapshot implements QuerySnapshot {
    final List<DocumentSnapshot> docsList;
    final bool isFromCache;
  
    MergedQuerySnapshot({
      required this.docsList,
      required this.isFromCache,
    });
  
    // FutureBuilder渲染依赖的核心属性
    @override
    List<DocumentSnapshot> get docs => docsList;
  
    @override
    int get size => docsList.length;
  
    @override
    bool get isEmpty => docsList.isEmpty;
  
    @override
    bool get isNotEmpty => docsList.isNotEmpty;
  
    @override
    SnapshotMetadata get metadata => SnapshotMetadata(
          hasPendingWrites: false,
          isFromCache: isFromCache,
        );
  
    // 合并场景下没有实时文档变更流，直接返回空列表即可
    @override
    List<DocumentChange> get docChanges => [];
  
    // 支持列表按索引取值的逻辑
    @override
    dynamic operator [](Object? index) => docsList[index as int];
  }
  

• 替换原有变量的赋值逻辑
  搜索触发时，直接把合并方法返回的Future赋值给原有futureSearchResults变量，FutureBuilder不需要做任何修改：

  // 原代码搜索触发位置替换成合并后的Future
  String str = "用户输入的搜索关键词";
  futureSearchResults = mergeSearchResults(str);
  

开发注意细节 #

• 如果需要控制合并后的总结果数上限，可在去重收集完成后对mergedDocs做截断，比如mergedDocs.take(10).toList()
• 可以根据业务需求对去重后的结果做二次排序，比如按和搜索关键词的匹配度从高到低排好再返回
• 不需要单独处理查询异常，Future.wait会自动把两个查询的任意错误向上抛出，和原FutureBuilder的错误捕获逻辑完全兼容，不会引入额外的异常处理成本

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