Flutter中Firestore随机获取用户文档异常问题排查求助

核心问题分析 #

1. 分页逻辑失效：复用lastDocument跨两个互斥的查询区间（>=randomValue和<randomValue）完全无效，因为上一次查询的文档不在下一次查询的范围内，导致后续分页返回空或少量结果。
2. 客户端过滤导致数量不足：先按limit查询数据库，但客户端过滤掉不符合条件的用户后，剩余数量不够，而 fallback 查询仅按剩余数量请求，未考虑 fallback 结果也会被过滤的情况。
3. 随机数生成脱离实际数据范围：生成的随机数是2-8位整数，但如果数据库中random字段的实际范围和这个不匹配，会导致首次查询命中结果过少。
4. 空指针风险：alreadyFetchedProfiles参数可能为null，直接用!强制解包会引发异常。
5. 分页时随机值重置：每次调用接口都重新生成随机值，导致分页逻辑断裂，无法实现连续的批量获取。

修复后的代码 #

import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:firebase_auth/firebase_auth.dart';
import 'dart:math';

import '../models/user_profile.dart';

// 新增分页状态类，记录当前查询的区间和最后文档
class PagingState {
  final bool isUpperRange; // 是否在 >=randomValue 的区间查询
  final int randomValue;
  final DocumentSnapshot? lastDocument;

  PagingState({required this.isUpperRange, required this.randomValue, this.lastDocument});
}

Future<List<UserProfile>> fetchMatchedProfiles({
  int limit = 5,
  PagingState? pagingState,
  List<String>? alreadyFetchedProfiles,
}) async {
  try {
    print("Fetching matched profiles (limit: $limit)...");

    final firestore = FirebaseFirestore.instance;
    final currentUser = FirebaseAuth.instance.currentUser;
    if (currentUser == null) return [];

    // 初始化已获取列表，避免空指针
    final fetchedUids = alreadyFetchedProfiles ?? [];

    // 获取当前用户性别
    final currentUserGender = (await firestore
            .collection('users')
            .doc(currentUser.uid)
            .collection('profile')
            .doc('user-data')
            .get())
        .data()?['gender'] ?? '';
    if (currentUserGender.isEmpty) return [];

    final targetGender = currentUserGender == 'Male' ? 'Female' : 'Male';
    print("Current Gender: $currentUserGender, Target Gender: $targetGender");

    // 初始化随机值和查询区间：首次查询生成随机值，分页时沿用之前的
    final randomValue = pagingState?.randomValue ?? await _generateRandomValue(firestore);
    final isUpperRange = pagingState?.isUpperRange ?? true;

    // 构建查询：首次查 >=randomValue，分页时沿用当前区间，直到该区间耗尽再切换
    late Query query;
    if (isUpperRange) {
      query = firestore
          .collection('users')
          .where('verification_status', isEqualTo: 'verified')
          .where('random', isGreaterThanOrEqualTo: randomValue)
          .orderBy('random')
          .limit(limit);
    } else {
      query = firestore
          .collection('users')
          .where('verification_status', isEqualTo: 'verified')
          .where('random', isLessThan: randomValue)
          .orderBy('random')
          .limit(limit);
    }

    // 分页时，在当前区间内使用lastDocument
    if (pagingState?.lastDocument != null) {
      query = query.startAfterDocument(pagingState!.lastDocument!);
    }

    final querySnapshot = await query.get();
    List<UserProfile> profiles = [];
    DocumentSnapshot? newLastDocument;

    for (var userDoc in querySnapshot.docs) {
      newLastDocument = userDoc;
      final uid = userDoc.id;

      // 过滤当前用户和已获取的用户
      if (uid == currentUser.uid || fetchedUids.contains(uid)) continue;

      // 获取用户数据
      final userDataDoc = await userDoc.reference
          .collection('profile')
          .doc('user-data')
          .get(const GetOptions(source: Source.serverAndCache));
      if (!userDataDoc.exists) continue;

      final userData = userDataDoc.data()!;
      // 性别过滤
      if (userData['gender'] != targetGender) continue;

      // 转换为UserProfile
      profiles.add(UserProfile.fromFirestore(
        uid,
        {
          'firstName': userData['firstName'],
          'lastName': userData['lastName'],
          'designation': userData['designation'],
          'dob': userData['dob'],
          'height': userData['height'],
          'gender': userData['gender'],
          'city': userData['city'],
          'state': userData['state'],
          'image_urls': userData['image_urls'],
          'email': userData['email'],
          'phoneNumber': userData['phoneNumber'],
          'whatsapp_number': userData['whatsapp_number'],
        },
        {}, {}, {}, {}, {}, userDoc,
      ));
      fetchedUids.add(uid);

      // 达到目标数量提前退出
      if (profiles.length == limit) break;
    }

    // 如果当前区间没拿到足够数量，切换到另一个区间继续获取
    if (profiles.length < limit) {
      final remainingLimit = limit - profiles.length;
      final fallbackQuery = firestore
          .collection('users')
          .where('verification_status', isEqualTo: 'verified')
          .where('random', isLessThan: randomValue)
          .orderBy('random')
          .limit(remainingLimit);

      final fallbackSnapshot = await fallbackQuery.get();
      for (var userDoc in fallbackSnapshot.docs) {
        final uid = userDoc.id;
        if (uid == currentUser.uid || fetchedUids.contains(uid)) continue;

        final userDataDoc = await userDoc.reference
            .collection('profile')
            .doc('user-data')
            .get(const GetOptions(source: Source.serverAndCache));
        if (!userDataDoc.exists) continue;

        final userData = userDataDoc.data()!;
        if (userData['gender'] != targetGender) continue;

        profiles.add(UserProfile.fromFirestore(
          uid,
          {
            'firstName': userData['firstName'],
            'lastName': userData['lastName'],
            'designation': userData['designation'],
            'dob': userData['dob'],
            'height': userData['height'],
            'gender': userData['gender'],
            'city': userData['city'],
            'state': userData['state'],
            'image_urls': userData['image_urls'],
            'email': userData['email'],
            'phoneNumber': userData['phoneNumber'],
            'whatsapp_number': userData['whatsapp_number'],
          },
          {}, {}, {}, {}, {}, userDoc,
        ));
        fetchedUids.add(uid);

        if (profiles.length == limit) break;
      }
    }

    // 生成新的分页状态：如果当前区间还有文档，继续用当前区间；否则切换到另一个区间
    PagingState? newPagingState;
    if (profiles.isNotEmpty) {
      newPagingState = PagingState(
        isUpperRange: isUpperRange && newLastDocument != null,
        randomValue: randomValue,
        lastDocument: newLastDocument,
      );
    }

    print("Fetched ${profiles.length} profiles.");
    return profiles;
  } catch (e) {
    print('Error fetching matched profiles: $e');
    return [];
  }
}

// 根据数据库中random字段的实际范围生成随机值
Future<int> _generateRandomValue(FirebaseFirestore firestore) async {
  // 获取random字段的最小和最大值，确保生成的随机值在有效范围内
  final minQuery = await firestore
      .collection('users')
      .where('verification_status', isEqualTo: 'verified')
      .orderBy('random')
      .limit(1)
      .get();
  final maxQuery = await firestore
      .collection('users')
      .where('verification_status', isEqualTo: 'verified')
      .orderBy('random', descending: true)
      .limit(1)
      .get();

  final minRandom = minQuery.docs.isNotEmpty ? minQuery.docs.first.data()['random'] as int : 100;
  final maxRandom = maxQuery.docs.isNotEmpty ? maxQuery.docs.first.data()['random'] as int : 99999999;

  final random = Random();
  return random.nextInt(maxRandom - minRandom + 1) + minRandom;
}

关键修复点说明 #

1. 新增分页状态类：记录当前查询的区间（上半区/下半区）、随机值和最后文档，保证分页逻辑连续，不会跨区间无效复用lastDocument。
2. 按区间优先查询：首次查询先查上半区，分页时优先耗尽当前区间的所有数据，再切换到下半区，避免分页断裂。
3. 动态生成随机值：根据数据库中random字段的实际范围生成随机值，确保随机值落在有效区间内，提升首次查询的命中量。
4. 处理客户端过滤的情况：循环查询直到拿到足够数量的符合条件的用户，避免因过滤导致数量不足。
5. 初始化已获取列表：避免alreadyFetchedProfiles为null引发的空指针异常。

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