Flutter自动化Firebase配置生成插件flutterfire_gen的使用

flutterfire_gen 是一个用于Flutter中Cloud Firestore代码生成的包。它通过在Dart中描述Cloud Firestore文档的结构，自动生成符合特定需求的样板代码。

动机

通过描述Cloud Firestore文档的模式，flutterfire_gen 可以自动生成满足以下要求的样板代码：

• 为读取、创建、更新（和删除）操作生成最合适的接口。
• 生成类型安全的方法进行读取、创建、更新和删除。
• 设置不同的默认值用于读取、创建和更新操作。
• 在创建和更新时自动使用 FieldValue.serverTimestamp()。
• 提供处理实际值（如42, [1, 3, 5]）和 FieldValue（如FieldValue.increment(1), FieldValue.arrayUnion([7])）的接口用于创建和更新操作。
• 允许使用 JsonConverter 等。

如何使用

安装

在您的Flutter应用的 pubspec.yaml 文件中添加以下依赖项：

dependencies:
  cloud_firestore: latest
  firebase_core: latest
  flutterfire_gen_annotation: latest
  flutterfire_gen_utils: latest
  json_annotation: latest # 如果需要使用 JsonConverter

dev_dependencies:
  build_runner: latest
  flutterfire_gen: latest

定义Cloud Firestore文档模式

使用 @FirestoreDocument 注解来描述一个Todo文档的模式：

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

part 'todo.flutterfire_gen.dart';

@FirestoreDocument(path: 'todos/{todoId}')
class Todo {
  const Todo({
    required this.title,
    required this.isCompleted,
    required this.createdAt,
    required this.updatedAt,
  });

  final String title;
  
  @ReadDefault(false)
  @CreateDefault(false)
  final bool isCompleted;

  @alwaysUseFieldValueServerTimestampWhenCreating
  final DateTime? createdAt;

  @alwaysUseFieldValueServerTimestampWhenCreating
  @alwaysUseFieldValueServerTimestampWhenUpdating
  final DateTime? updatedAt;
}

运行代码生成器

执行以下命令运行代码生成器：

flutter pub run build_runner build --delete-conflicting-outputs

确保源文件包含类似 part 'todo.flutterfire_gen.dart'; 的行。

使用生成的查询类

对于标注了 @FirestoreDocument 的 Todo 类，会生成一个名为 TodoQuery 的类，提供基本的读写方法：

读取示例

final query = TodoQuery();

Future<List<ReadTodo>> fetchTodos() => query.fetchDocuments();

Stream<List<ReadTodo>> subscribeTodos() => query.subscribeDocuments();

Future<ReadTodo?> fetchTodo(String todoId) =>
    query.fetchDocument(todoId: todoId);

Stream<ReadTodo?> subscribeTodo(String todoId) =>
    query.subscribeDocument(todoId: todoId);

创建示例

Future<DocumentReference<CreateTodo>> addTodo(String title) =>
    query.add(createTodo: CreateTodo(title: title));

Future<DocumentReference<CreateTodo>> addCompletedTodo(String title) =>
    query.add(createTodo: CreateTodo(title: title, isCompleted: true));

更新示例

Future<void> updateCompletionStatus({
  required String todoId,
  required bool isCompleted,
}) =>
    query.update(
      todoId: todoId,
      updateTodo: UpdateTodo(isCompleted: isCompleted),
    );

高级功能

自定义模式定义类名和生成类名

可以通过修改 build.yaml 来定制生成类的名字前缀或后缀。

使用JsonConverter

可以将 json_annotation 包中的 JsonConverter 应用于字段转换。

@JsonSerializable()
class Repository {
  @_visibilityConverter
  final Visibility visibility;
}

enum Visibility { public, private }

const _visibilityConverter = _VisibilityConverter();

class _VisibilityConverter implements JsonConverter<Visibility, String> {
  const _VisibilityConverter();

  @override
  Visibility fromJson(String json) => Visibility.fromString(json);

  @override
  String toJson(Visibility visibility) => visibility.name;
}

使用FieldValue

可以在创建或更新操作中使用 FieldValue 来指定相对值或数组操作。

@allowFieldValue
final int fieldValueAllowedInt;

@allowFieldValue
final List<String> fieldValueAllowedList;

示例Demo

以下是一个完整的示例，展示了如何使用 flutterfire_gen 进行数据的操作：

import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
import 'todo.dart';

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

  final query = TodoQuery();

  // 获取所有todos
  final todos = await query.fetchDocuments();
  for (final todo in todos) {
    print(todo.todoId);
  }

  // 获取未完成的todos
  final notCompletedTodos = await query.fetchDocuments(
    queryBuilder: (query) => query.where('isCompleted', isEqualTo: false),
  );
  for (final todo in notCompletedTodos) {
    print(todo.todoId);
  }

  // 实时订阅todos
  query.subscribeDocuments();

  // 添加新todo
  final addedDocumentReference =
      await query.add(createTodo: const CreateTodo(title: 'A new Todo'));
  print(addedDocumentReference.id);

  // 更新todo状态
  await query.update(
    todoId: 'todoId',
    updateTodo: const UpdateTodo(isCompleted: true),
  );

  // 删除todo
  await query.delete(todoId: 'anotherTodoId');
}