Firestore事务中向数组添加元素防超订的正确实现方案

核心结论 #

• 你注释掉的transaction.update()是必须使用的写法，数组类型字段的事务修改也必须走该方法，没有例外。
• 你当前直接调用eventDocRef.update()的写法完全脱离事务管控，高并发场景下必然出现超订。
• 你遇到的Instance of 'Future<void>'报错属于传值错误，不是事务本身的功能问题。

当前写法的超订风险说明 #

Firestore事务的原子性、冲突重试、并发校验能力，仅对事务实例（即代码中传入回调的transaction对象）调用的get/set/update/delete操作生效。你现在的写法存在三个致命问题：

• 直接通过文档引用调用的eventDocRef.update()属于独立的普通写请求，完全不被事务管控，你之前读到的报名人数校验结果和后续写操作没有绑定关系。高并发下多个请求会同时读到“剩余名额充足”，随后各自执行写操作，直接超订。
• 循环中多次调用eventDocRef.update()会生成多个独立写请求，不会被事务合并，也不会在校验不通过时自动回滚。
• 普通写操作不会触发事务的冲突重试机制：如果在你读完人数到执行写的间隙，其他请求已经把名额占满，你的写操作不会重新校验名额，会直接写入成功。

报错原因与修正方案 #

报错根因 #

你之前尝试写的transaction.update(eventDocRef, {"attendees": newEvent})逻辑本身就写错了：newEvent是你调用普通update()返回的Future<void>对象，你把Future实例作为字段值传给Firestore，序列化时自然会报类型错误，和事务API本身无关。

正确实现代码 #

写事务时注意两个原则：所有读写操作都通过transaction对象调用，不要在事务回调里执行普通文档写操作；数组更新一次性传入所有待添加的元素，减少不必要的写请求和冲突概率。

final eventDocRef = events.doc(event.documentId);
final addedGuests = ref.watch(guestsProvider);

return await FirebaseFirestore.instance.runTransaction((transaction) async {
  // 必须通过transaction读取文档，纳入事务版本管控
  final eventSnap = await transaction.get(eventDocRef);
  // 计算本次需要新增的报名总人数：当前用户 + 携带嘉宾
  final int addCount = 1 + addedGuests.guests.length;
  final int currentAttendeeNum = (eventSnap.get("attendees") as List).length;
  final int maxAttendeeNum = eventSnap.get("max attendees") as int;

  // 名额不足直接抛错终止事务
  if (maxAttendeeNum < currentAttendeeNum + addCount) {
    throw "活动已约满";
  }

  // 一次性组装所有要加入报名列表的用户ID
  final List<String> waitAddUids = [
    FirebaseAuth.instance.currentUser!.uid,
    ...addedGuests.guests.map((guest) => guest.uid!)
  ];

  // 必须通过transaction执行更新，保证读校验和写入的原子性
  transaction.update(eventDocRef, {
    "attendees": FieldValue.arrayUnion(waitAddUids)
  });
});

补充说明 #

• 事务回调内推荐用async/await语法，避免链式.then写法容易混入普通异步操作的问题。
• 上述写法配合arrayUnion的原子数组操作能力，在高并发下会自动触发冲突重试：如果提交时检测到文档被其他请求修改，Firestore会重新执行整个事务逻辑，拉取最新的报名人数重新校验，直到写入成功或者名额不足报错，从机制上避免超订。
• 不需要循环多次调用update，单次arrayUnion传入所有待加ID即可，多次调用只会提升事务冲突概率，没有任何收益。

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