firebase-data-connect

Firebase Data Connect 技能

此技能介绍如何在 Flutter 应用中正确使用 Firebase Data Connect。

适用场景

在以下情况下使用此技能：

• 在 Flutter 项目中设置和配置 Firebase Data Connect。
• 设计 Data Connect 的架构、查询和变更。
• 实现生成的 SDK 调用，以执行类型化查询和变更。
• 处理网络故障、数据不一致和离线场景。
• 遵循安全和性能最佳实践。

---

1. 设置和配置

步骤 1：安装软件包

flutter pub add firebase_data_connect

步骤 2：导入并初始化

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

步骤 3：在 dataconnect/schema/schema.gql 中定义架构

type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int
  genre: String
  rating: Float
  description: String
}

步骤 4：在 dataconnect/connector/queries.gql 中定义查询和变更

query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    releaseYear
    genre
    rating
  }
}

mutation CreateMovie($title: String!, $releaseYear: Int, $genre: String) @auth(level: USER) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
  })
}

mutation DeleteMovie($id: UUID!) @auth(level: USER) {
  movie_delete(id: $id)
}

步骤 5：生成类型化 Flutter SDK

flutterfire generate

此操作会为每个查询和变更生成类型化的 Dart 类。

平台支持：

平台	支持情况
iOS	完全支持
Android	完全支持
Web	完全支持
其他平台	不支持

---

2. 执行查询和变更

使用生成的 SDK 执行类型化查询和变更：

// Execute a query
final result = await ListMoviesQuery().execute();
final movies = result.data.movies;

// Execute a mutation
await CreateMovieMutation(title: 'Inception', releaseYear: 2010, genre: 'Sci-Fi')
    .execute();

// Delete by ID
await DeleteMovieMutation(id: movieId).execute();

实时监听器

订阅查询变更以获取实时更新：

final subscription = ListMoviesQuery().subscribe();
subscription.listen((result) {
  final movies = result.data.movies;
  // Update UI with latest movie list
});

---

3. 性能和缓存

• 设计高效的查询，只请求所需字段，以尽量减少数据传输。
• 为大型数据集实现分页：

  query ListMoviesPaginated($limit: Int!, $offset: Int!) @auth(level: PUBLIC) {
    movies(limit: $limit, offset: $offset) {
      id
      title
      releaseYear
    }
  }
  

• 谨慎使用实时监听器，避免不必要的网络使用。
• 对于关键应用功能，可考虑通过在本地缓存查询结果来支持离线使用。

---

4. 错误处理

使用 try/catch 包装 Data Connect 调用，以处理网络和验证错误：

try {
  final result = await ListMoviesQuery().execute();
  return result.data.movies;
} on FirebaseException catch (e) {
  if (e.code == 'unavailable') {
    // Handle offline — return cached data
    return _localCache.getMovies();
  }
  rethrow;
}

• 对暂时性连接错误实现带指数退避的重试逻辑。
• 为数据验证失败提供有意义的错误消息。
• 监控错误率并调查反复出现的问题。

---

5. 安全

• 在架构中使用 @auth 指令控制访问级别（PUBLIC、USER、NO_ACCESS）。
• 集成Firebase Authentication，实现基于用户的访问控制。
• 在客户端和服务端验证数据。
• 处理用户信息时遵循数据隐私最佳实践。

---

参考资料

• Firebase Data Connect 文档
• Data Connect Flutter SDK 参考