Flutter Firestore：监听数据流时如何捕获服务器连接异常？

Firestore的snapshots()流默认不会在网络异常或无法连接服务器时触发onError回调，仅会返回缓存数据；而依赖isFromCache判断连接状态的方式不可靠——即使有正常网络，也可能因数据同步延迟等原因返回缓存值，关闭离线持久化也无法彻底避免误判。

可行解决方案：自定义封装流，结合初始服务器校验与元数据监听 #

通过封装流实现两个核心逻辑：

1. 初始连接校验：订阅流前先执行一次强制从服务器获取数据的请求，失败则直接抛出异常。
2. 实时同步状态监控：开启元数据变化监听，若长时间处于缓存状态且无服务器同步更新，则判定为连接异常并抛出错误。

封装代码示例

import 'dart:async';
import 'package:cloud_firestore/cloud_firestore.dart';

Stream<QuerySnapshot<T>> snapshotsWithServerValidation<T>(Query<T> query) async* {
  // 1. 初始服务器连接校验
  try {
    // 强制从服务器获取数据，超时时间可根据需求调整
    await query.get(const GetOptions(source: Source.server)).timeout(const Duration(seconds: 5));
  } on FirebaseException catch (e) {
    yield* Stream.error(e);
    return;
  } on TimeoutException {
    yield* Stream.error(FirebaseException(
      plugin: 'cloud_firestore',
      message: '连接Firestore服务器超时',
    ));
    return;
  }

  var lastValidServerSync = DateTime.now();
  const maxCacheDuration = Duration(seconds: 10);

  // 2. 监听快照流并校验同步状态
  yield* query.snapshots(includeMetadataChanges: true).transform(
    StreamTransformer.fromHandlers(
      handleData: (snap, sink) {
        if (!snap.metadata.isFromCache) {
          // 成功从服务器获取数据，更新同步时间
          lastValidServerSync = DateTime.now();
          sink.add(snap);
        } else {
          // 检查缓存状态持续时间
          if (DateTime.now().difference(lastValidServerSync) > maxCacheDuration) {
            sink.addError(FirebaseException(
              plugin: 'cloud_firestore',
              message: '无法连接到Firestore服务器，当前数据为缓存内容',
            ));
          } else {
            // 短时间缓存，仍正常输出（可能是同步中）
            sink.add(snap);
          }
        }
      },
    ),
  );
}

使用方式

snapshotsWithServerValidation(
  _firestore.collection('stuff').where("someBool", isEqualTo: false)
).listen(
  (snap) {
    // 处理正常快照数据
  },
  onError: (e) {
    // 处理连接异常
    debugPrint(e.toString());
  }
);

说明 #

• 初始校验确保订阅流前已成功连接服务器，避免一开始就返回缓存数据而无法察觉异常。
• 元数据监听结合超时判断，能区分“临时同步延迟”和“长期无法连接服务器”的情况，减少误判。
• 超时时间和缓存阈值可根据业务需求调整。

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