Firestore runTransaction的timeout参数设置不生效问题

• 插件版本bug：cloud_firestore 4.0.0版本之前，Dart层传入runTransaction的timeout参数没有正确透传给Android/iOS原生SDK，原生端默认单轮事务尝试的超时固定为10秒，扣除网络建连、请求序列化的开销后，实际触发超时的时长稳定在9秒左右，和Dart层设置的参数值无关。
• 事务写法不符合规范：Firestore事务强制要求所有写操作必须基于事务内读取到的最新文档快照执行，你贴的代码没有先读取目标文档就直接调用update，会触发客户端内置的自动重试逻辑，此时超时控制完全走原生端默认的重试退避、总超时规则，自定义timeout参数不会生效。
• 逻辑认知偏差：就算参数透传正常，传入的timeout仅控制单轮事务尝试的超时时间，不是事务从启动到结束的总超时。事务遇到网络波动、文档版本冲突等可重试错误时，会按指数退避规则自动重试，默认最多重试5次，总耗时天然会大于单轮设置的timeout值。

1. 先修正事务写法，严格遵循先读后写的规则：

final db = FirebaseFirestore.instance;
final docref = db.collection('appdata').doc(docID);
final data = {'rueckruf': FieldValue.serverTimestamp()};

db.runTransaction((transaction) async {
  // 必须在事务内先读取目标文档的最新快照
  final docSnap = await transaction.get(docref);
  // 按需增加文档存在性校验
  if (!docSnap.exists) {
    throw StateError("Target document does not exist");
  }
  // 基于读取结果执行写操作
  transaction.update(docref, data);
}, timeout: const Duration(seconds: 3)).then((value) {
  // 事务执行成功的后续逻辑
}, onError: (e) {
  // 事务执行失败的错误处理
});

2. 将项目依赖的cloud_firestore版本升级到4.0.0及以上，新版本已经修复了Dart层timeout参数不透传的问题，设置的单轮尝试超时会正常生效。
3. 如果需要控制事务的总运行时长硬超时，不要依赖SDK自带的timeout参数，在外层通过Dart原生的Future.timeout方法实现即可：

db.runTransaction((transaction) async {
  final docSnap = await transaction.get(docref);
  if (!docSnap.exists) throw StateError("Target document does not exist");
  transaction.update(docref, data);
}, timeout: const Duration(seconds: 3))
.timeout(const Duration(seconds: 3), onTimeout: () {
  throw TimeoutException("Transaction total runtime exceeded 3 seconds");
}).then((value) {
  // 成功逻辑
}, onError: (e) {
  // 统一错误处理
});

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