Flutter Firebase集成辅助插件firebase_facilitator的使用

Flutter Firebase集成辅助插件firebase_facilitator的使用

简介

firebase_facilitator 是一个多功能的Flutter包，旨在简化与Firestore的CRUD（创建、读取、更新、删除）操作。它提供了处理常见任务的mixin，如创建、读取、更新和删除数据，以及可选的日志记录功能。

平台支持

依赖要求

• Flutter >= 3.3.0
• cloud_firestore: ^5.5.1
• fake_cloud_firestore: ^3.0.3
• firebase_auth: ^5.3.4 (可选，用于身份验证)
• firebase_core: ^3.8.1
• firebase_storage: ^12.3.7
• logger: ^2.4.0 (可选，用于日志记录)

使用示例

1. 导入必要的mixin

import 'package:firebase_facilitator/mixin/crud_repos.dart';
import 'package:firebase_facilitator/mixin/firestore_read_service.dart';
import 'package:firebase_facilitator/mixin/firestore_write_service.dart';
import 'package:firebase_facilitator/mixin/logger_service.dart';

2. 创建Firestore服务类

/// `ItemFirestoreService` 处理 "items" 集合的Firestore CRUD操作。
/// 它使用 `FirestoreReadRepository` 和 `FirestoreWriteRepository` mixin 来执行读取和写入操作，
/// 并提供日志记录服务以记录操作（可选）。
class ItemFirestoreService with FirestoreReadRepository, FirestoreWriteRepository {
  /// 提供从Firestore获取数据的读取服务实现。
  [@override](/user/override)
  FirestoreReadService get firestoreReadService => FirestoreServiceImpl();

  /// 提供在Firestore中保存和删除数据的写入服务实现。
  [@override](/user/override)
  FirestoreWriteService get firestoreWriteService => FirestoreWriteServiceImpl();

  /// 日志记录服务，用于跟踪操作。这里设置为 `true`，启用日志记录。
  [@override](/user/override)
  LoggerService? get loggerService => LoggerServiceImpl(true); // 可选

  /// 指定此服务操作的Firestore集合名称。
  [@override](/user/override)
  String get collection => "items";
}

3. 创建数据仓库类

/// `ItemRepository` 作为Firestore服务的抽象层，
/// 提供与 `ItemModel` 对象交互的具体方法。
class ItemRepository {
  final ItemFirestoreService firestoreService;

  /// 构造函数，需要传递一个 `ItemFirestoreService` 实例。
  ItemRepository(this.firestoreService);

  /// 从 "items" 集合中获取所有项目。
  Future<List<ItemModel>> fetchAllItems() async {
    try {
      final List<Map<String, dynamic>> rawData = await firestoreService.fetchAllDocuments();
      return rawData.map((element) => ItemModel.fromJson(element)).toList();
    } catch (e) {
      log('Error fetching items: $e');
      rethrow; // 传播错误以便进一步处理
    }
  }

  /// 获取分页文档。
  ///
  /// 此函数从Firestore集合中检索指定数量的文档（`limit`），从第一个文档开始或从由 `lastDocument` 指定的文档开始（用于继续分页）。
  /// 文档按指定字段（`orderByField`）排序，默认按 'createdAt' 字段排序。
  ///
  /// 分页是一种分批获取数据的技术，而不是一次性加载所有文档，这可以提高性能并减少内存使用。
  ///
  /// 参数：
  /// - [limit] (可选): 每页最大文档数，默认为10。
  /// - [lastDocument] (可选): 上一页最后一条文档的引用。如果提供，则从该文档之后开始下一页。如果没有提供，则从头开始。
  /// - [orderByField] (可选): 用于排序的Firestore字段，默认为 'createdAt'。
  ///
  /// 返回：
  /// - 一个包含已获取文档和其他分页相关信息的 `PaginationResult` 对象。
  ///
  /// 示例用法：
  /// ```dart
  /// final PaginationResult result = await fetchPaginatedDocuments(
  ///   limit: 20,
  ///   lastDocument: lastDocument, // 上一页的最后一条文档
  ///   orderByField: 'updatedAt',
  /// );
  /// ```
  ///
  /// 此函数使用 `firestoreService` 中的 `fetchPaginatedDocuments` 方法来处理Firestore读取操作。
  Future<PaginationResult> fetchPaginatedDocuments({
    int limit = 10,
    DocumentSnapshot? lastDocument,
    String orderByField = 'createdAt',
  }) async {
    // 使用提供的参数从Firestore获取分页文档。
    final PaginationResult paginationResult = await firestoreService.fetchPaginatedDocuments(
      limit: limit,
      lastDocument: lastDocument,
      orderByField: orderByField,
    );

    // 返回包含文档和分页元数据的结果。
    return paginationResult;
  }

  /// 保存新的 `ItemModel` 到Firestore。
  Future<void> saveItem({required ItemModel itemModel}) async {
    try {
      await firestoreService.saveDocument(data: itemModel.toJson());
    } catch (e) {
      log('Error saving item: $e');
    }
  }

  /// 根据ID从Firestore中获取单个项目。
  Future<ItemModel> fetchItemByID({required String itemId}) async {
    try {
      final Map<String, dynamic>? rawData = await firestoreService.fetchDocumentById(docId: itemId);
      if (rawData == null) throw Exception("Item not found");
      return ItemModel.fromJson(rawData);
    } catch (e) {
      log('Error fetching item by ID: $e');
      rethrow;
    }
  }

  /// 根据ID从Firestore中删除项目。
  Future<void> deleteItem({required String id}) async {
    try {
      await firestoreService.deleteDocument(documentId: id);
    } catch (e) {
      log('Error deleting item: $e');
    }
  }

  /// 将文件上传到Firebase Storage并记录生成的URL。
  Future<void> uploadFile() async {
    final FilePickerResult? result = await FilePicker.platform.pickFiles(type: FileType.image);
    if (result == null) return; // 未选择文件

    final String? filePath = result.paths.firstOrNull;
    if (filePath == null) return;

    try {
      final String imageUrl = await firestoreService.uploadFile(
        filePath: filePath,
        storagePath: "$imagePath/file.jpg",
      );
      log('File uploaded successfully. URL: $imageUrl');
    } catch (e) {
      log('Error uploading file: $e');
    }
  }

  /// 从Firebase Storage下载文件到本地目录。
  Future<void> downloadFile() async {
    final String? directoryPath = await FilePicker.platform.getDirectoryPath();
    if (directoryPath == null) return;

    try {
      await firestoreService.downloadFile(
        storagePath: "$imagePath/file.jpg",
        destinationPath: "$directoryPath/file.jpg",
      );
      log('File downloaded successfully');
    } catch (e) {
      log('Error downloading file: $e');
    }
  }

  /// 从Firebase Storage删除文件。
  Future<void> deleteFile() async {
    try {
      await firestoreService.deleteFile(storagePath: "$imagePath/file.jpg");
      log('File deleted successfully');
    } catch (e) {
      log('Error deleting file: $e');
    }
  }
}

4. 创建数据模型类

/// `ItemModel` 表示 "items" 集合中的项目，包含 `id`、`name` 和 `price` 字段。
class ItemModel {
  final String id;
  final String name;
  final double price;

  /// 构造函数，用于创建 `ItemModel` 对象。
  ItemModel({required this.id, required this.name, required this.price});

  /// 从JSON创建 `ItemModel`。
  factory ItemModel.fromJson(Map<String, dynamic> json) {
    return ItemModel(
      id: json['id'] as String,
      name: json['name'] as String,
      price: (json['price'] as num).toDouble(),
    );
  }

  /// 将 `ItemModel` 转换为JSON。
  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'price': price,
    };
  }
}

5. 主应用程序入口

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:file_picker/file_picker.dart';
import 'package:firebase_facilitator/mixin/crud_repos.dart';
import 'package:firebase_facilitator/mixin/firestore_read_service.dart';
import 'package:firebase_facilitator/mixin/firestore_write_service.dart';
import 'package:firebase_facilitator/mixin/logger_service.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Firebase Facilitator Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: ItemListScreen(),
    );
  }
}

class ItemListScreen extends StatefulWidget {
  [@override](/user/override)
  _ItemListScreenState createState() => _ItemListScreenState();
}

class _ItemListScreenState extends State<ItemListScreen> {
  final ItemFirestoreService _firestoreService = ItemFirestoreService();
  final ItemRepository _itemRepository = ItemRepository(_firestoreService);
  List<ItemModel> _items = [];

  [@override](/user/override)
  void initState() {
    super.initState();
    _fetchItems();
  }

  Future<void> _fetchItems() async {
    try {
      final items = await _itemRepository.fetchAllItems();
      setState(() {
        _items = items;
      });
    } catch (e) {
      print('Error fetching items: $e');
    }
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Item List'),
      ),
      body: ListView.builder(
        itemCount: _items.length,
        itemBuilder: (context, index) {
          final item = _items[index];
          return ListTile(
            title: Text(item.name),
            subtitle: Text('Price: ${item.price}'),
            trailing: IconButton(
              icon: Icon(Icons.delete),
              onPressed: () async {
                try {
                  await _itemRepository.deleteItem(id: item.id);
                  setState(() {
                    _items.removeAt(index);
                  });
                } catch (e) {
                  print('Error deleting item: $e');
                }
              },
            ),
          );
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () async {
          final newItem = ItemModel(
            id: DateTime.now().millisecondsSinceEpoch.toString(),
            name: 'New Item',
            price: 9.99,
          );
          await _itemRepository.saveItem(itemModel: newItem);
          setState(() {
            _items.add(newItem);
          });
        },
        child: Icon(Icons.add),
      ),
    );
  }
}