Flutter StreamBuilder缓存优先加载致limit查询超量问题

问题根因 #

两个问题的诱因分别是：

• 返回文档数超过10条：第一是代码里orderby拼写错误，Firestore 官方API方法为orderBy（B大写），拼写错误会导致排序、limit约束失效；第二是列表更新逻辑有缺陷，每次Stream触发快照更新时都直接遍历docChanges往全局products列表追加数据，没有在首次全量数据返回时清空旧缓存数据，多次触发Stream就会不断累加数据，最终超过limit设置的阈值。
• 缓存优先展示乱序数据：Firestore 默认快照源策略为「本地缓存优先、服务端同步在后」，Stream会先后抛出两次快照：先抛未做排序的本地缓存快照，再抛按规则排序的服务端快照。原有逻辑没有判断快照来源，直接把缓存快照的数据写入列表，就会出现先显示乱序数据、之后跳转为正确排序结果的现象，首次安装、本地缓存不准时问题尤其明显。

修复方案 #

1. 修正查询语法错误，把orderby改为官方标准方法orderBy，确保排序、limit约束生效。
2. 新增首次加载标记，区分全量拉取和增量更新场景：首次拿到服务端返回的全量快照时，先清空全局products列表的旧数据，再写入新的查询结果；后续分页、数据变更场景再通过docChanges做增量更新，避免数据重复累加。
3. 增加快照来源判断：首次加载阶段如果拿到的是本地缓存快照，可以选择展示加载占位，等服务端数据返回后再渲染列表；如果要保留离线体验，就对缓存拿到的文档手动按standing字段做升序排序后再写入列表，避免乱序。
4. 增量更新时对数据做去重、位置校验，根据docChanges的变更类型（新增/修改/删除）对应处理列表数据，不要无脑追加。

修复后核心代码 #

// 记得在State类里声明首次加载标记
bool _isFirstLoad = true;

@override
void didUpdateWidget(covariant oldWidget) {
  super.didUpdateWidget(oldWidget);
  // 切换分类时重置状态，清空旧数据
  if (oldWidget.selectedCategory != widget.selectedCategory) {
    _isFirstLoad = true;
    products.clear();
  }
}

StreamBuilder<QuerySnapshot>(
  stream: _ref.collection("products")
      .where("category", isEqualTo: widget.selectedCategory.nameLabel)
      .orderBy("standing", descending: false) // 修正拼写错误
      .limit(10)
      .snapshots(),
  builder: (context, snapshot) {
    // 等待连接状态时展示加载态
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const Center(child: CircularProgressIndicator());
    }
    if (snapshot.hasError) {
      return Center(child: Text("加载失败：${snapshot.error}"));
    }

    final querySnap = snapshot.data!;
    // 首次加载拿到缓存快照的处理：如果要等服务端数据就留加载态，要离线展示就手动排序缓存数据
    if (_isFirstLoad && querySnap.metadata.isFromCache) {
      // 离线展示方案：取出缓存docs手动排序后写入列表
      // final cacheDocs = querySnap.docs..sort((a,b) => (a.data() as Map)['standing'].compareTo((b.data() as Map)['standing']));
      // products = cacheDocs.map((e) => Products.fromJson(e.data() as Map<String, dynamic>)).toList();
      return const Center(child: CircularProgressIndicator());
    }

    // 首次拿到服务端全量数据，清空旧列表全量写入
    if (_isFirstLoad && !querySnap.metadata.isFromCache) {
      products.clear();
      _isFirstLoad = false;
      products.addAll(
        querySnap.docs.map((doc) => Products.fromJson(doc.data() as Map<String, dynamic>))
      );
    } else {
      // 非首次加载，处理增量变更
      for (final change in querySnap.docChanges) {
        final productData = Products.fromJson(change.doc.data() as Map<String, dynamic>);
        switch (change.type) {
          case DocumentChangeType.added:
            // 去重后按快照返回的位置插入
            if (products.indexWhere((p) => p.id == change.doc.id) == -1) {
              products.insert(change.newIndex, productData);
            }
            break;
          case DocumentChangeType.modified:
            final modifyIndex = products.indexWhere((p) => p.id == change.doc.id);
            if (modifyIndex != -1) {
              products.removeAt(modifyIndex);
              products.insert(change.newIndex, productData);
            }
            break;
          case DocumentChangeType.removed:
            products.removeWhere((p) => p.id == change.doc.id);
            break;
        }
      }
    }

    return ProductsList.vertical(
      scrollController: _scrollProducts,
      products: products,
      scroll: true,
    );
  },
)

注意事项 #

• 分页加载下一页数据时，要基于当前已加载的最后一条文档构造startAfterDocument查询，不要重复触发初始查询，否则会导致数据重复。
• 如果不需要离线缓存能力，可以在构造查询时配置数据源策略强制从服务端拉取数据，不过会损失离线可用性，按需选择。

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