如何在Flutter中使用GraphQL：开发者手册

// 错误的做法——每次重新构建都会重新生成和解析查询字符串
Widget build(BuildContext context) {
  final query = '''
    query { ... }
  ''';
  return Query(options: QueryOptions(document: gql(query)), ...);
}

// 正确的做法——仅在程序启动时解析一次查询字符串，之后在多次重建中重复使用该字符串
const String myQuery = r'''
  query { ... }
''';

Widget build(BuildContext context) {
  return Query(options: QueryOptions(document: gql(myQuery)), ...);
}

对所有请求都使用networkOnly设置

有些开发者因为遇到过缓存失效的问题，所以将所有的查询请求都设置为networkOnly。虽然这样可以避免缓存数据失效的问题，但也会带来其他负面后果：性能下降（无法立即获取缓存数据）、数据消耗量增加、电池电量消耗更快，以及离线使用时会出现各种错误提示，而无法显示之前加载的内容。

正确的做法是根据数据的重要性和时效性来为不同的查询请求选择合适的获取策略，而不是对所有请求都统一应用相同的设置。

忘记取消订阅

Subscription组件会自动管理其WebSocket连接：当该组件被添加到界面中时，连接会被建立；而当组件从界面上移除时，连接也会被关闭。

但是，如果你在Bloc或任何长期存在的对象内部直接使用客户端的subscribe()方法，那么你将会得到一个需要自己管理的Stream对象。那些从未被取消的订阅会随着每次导航操作而默默地导致内存泄漏问题逐渐加剧：

class PostBloc extends Bloc〈PostEvent, PostState〉 {
  StreamSubscription? _commentSubscription;

  void startListeningToComments(String postId) {
    _commentSubscription = _repository
        .watchNewComments(postId)
        .listen((comment) => add(CommentReceived(comment)));
  }

  @override
  Future〈void〉 close() {
    _commentSubscription?.cancel(); // 在关闭之前一定要取消订阅
    return super.close();
  }
}

未正确处理部分GraphQL查询结果

GraphQL响应中可能同时包含data和errors信息。这时得到的就是部分查询结果：有些查询操作成功了，而有些则失败了。如果你只检查result.hasException这个属性，那么你可能会忽略那些伴随着成功返回的数据出现的GraphQL错误。

因此，你必须同时检查result.data和result.exception，并明确规定在各种情况下用户界面应该如何响应这些数据。

小型端到端示例

让我们构建一个可运行的完整应用程序，以便将所有相关内容放在具体的上下文中进行演示。我们将使用GitHub的GraphQL API，因此你无需自行搭建服务器就可以立即运行这个示例程序。该应用程序会获取当前已登录用户的仓库信息，并允许用户对这些仓库添加星标或取消星标，同时还会通过同一个代码库来展示查询操作、变更操作以及相应的UI响应效果。

在运行示例之前，请先前往https://github.com/settings/tokens生成一个个人访问令牌，确保该令牌至少具有read:user和repo权限。

GraphQL客户端

// lib graphql/client.dart

import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphqlflutter.dart';

// 在生产环境中切勿硬编码访问令牌，应使用flutter_secure_storage或其他安全机制来存储令牌。
const _githubToken = 'YOUR_GITHUB_TOKEN_HERE';

ValueNotifier〈GraphQLClient〉 buildGitHubClient() {
  final httpLink = HttpLink('https://api.github.comgraphql');

  final authLink = AuthLink(
    getToken: () => 'Bearer $_githubToken',
  );

  return ValueNotifier(
    GraphQLClient(
      link: authLink.concat(httpLink),
      cache:GraphQLCache(store: HiveStore()),
    ),
  );
}

这个文件用于配置一个GraphQL客户端，我们的Flutter应用程序将会使用这个客户端来与GitHub的GraphQL API进行交互。

它会建立与 https://api.github.comGraphQL 的 HTTP 连接，然后使用你的 GitHub 令牌添加身份验证层，因此每个请求都会包含一个 Bearer 令牌。

这两部分结合在一起，使得请求既能通过身份验证，又能正确地发送到 GitHub。

最后，它还会利用 GraphQLCache 和 HiveStore 实现缓存功能，这样数据就可以被存储在本地并重复使用，而无需每次都从网络中获取。

简单来说：它将我们的应用程序与 GitHub 连接起来，添加登录令牌，并通过本地缓存来提升性能。

查询操作

// libgraphql/queries/repo_queries.dart

const String fetchViewerReposQuery = r'''
  query FetchViewerRepos($count: Int!) {
    viewer {
      login
      name
      avatarUrl
      repositories(
        first: $count
        orderBy: { field: STARGAZERS, direction: DESC }
        ownerAffiliations: [OWNER]
      ) {
        nodes {
          id
          name
          description
          stargazerCount
          primaryLanguage {
            name
            color
          }
          viewerHasStarred
        }
      }
    }
  }
''';

这个文件定义了一个 GraphQL 查询，用于从 GitHub 获取当前登录用户及其仓库的相关信息。

该查询的名称为 FetchViewerRepos，它接受一个参数 $count，用于指定返回多少个仓库。

首先，它会获取代表当前登录用户的 viewer 对象，然后从中提取基本的个人资料信息，如 login、name 和 avatarUrl。

接着，它会获取该用户的 repositories，并且查询结果会受到 $count 参数的限制。这些仓库会按照获得星标的数量降序排列，而且只有用户自己是这些仓库的所有者时，这些仓库才会被包含在查询结果中。

对于每一个仓库，它会请求以下信息：

• id（用于识别和缓存）,
• name,
• description,
• stargazerCount（获得的星标数量），
• primaryLanguage（包括其名称和颜色），
• viewerHasStarred（当前用户是否给该仓库点了星标）。

简单来说，这个查询就是在请求：“请提供当前登录用户的个人资料信息以及他们最受欢迎的几个仓库的列表，并为每个仓库提供关键详细信息。”

变更操作

// libgraphql/mutations/repo_mutations.dart

const String addStarMutation = r'''
  mutation AddStar($repoId: ID!) {
    addStar(input: { starrableId: $repoId }) {
      starrable {
        ... on Repository {
          id
          stargazerCount
          viewerHasStarred
        }
      }
    }
  }
''';

const String removeStarMutation = r'''
  mutation RemoveStar($repoId: ID!) {
    removeStar(input: { starrableId: $repoId }) {
      starrable {
        ... on Repository {
          id
          stargazerCount
          viewerHasStarred
        }
      }
    }
  }
''';

该文件定义了两种GraphQL mutation，它们允许我们的应用程序在GitHub上为仓库添加星标或移除星标。

第一种mutation是addStarMutation，它的作用是为仓库添加星标。该mutation接受一个名为$repoId的变量，这个变量代表仓库的唯一ID。执行该mutation时，会使用这个ID调用addStar函数。响应返回的内容包括更新后的仓库信息，具体来说包括：

• 仓库的id，

• 更新后的stargazerCount（即星标的数量），

• 以及viewerHasStarred（添加星标后该值为true）。

第二种mutation是removeStarMutation，它的作用与前者相反，即从仓库中移除星标，同样使用$repoId作为参数。调用removeStar函数后，响应也会返回以下信息：

• 仓库的id，

• 更新后的stargazerCount，

• 以及viewerHasStarred（移除星标后该值为false）。

这两种mutation都使用了GraphQL中的inline fragments技术（例如... on Repository），以确保返回的数据被正确地识别为Repository类型。

简单来说：一种mutation用于添加星标，另一种用于移除星标，但它们都会返回仓库状态的变化信息，这样用户的界面就能立即更新显示这些变化。

入口点

// lib/main.dart

import 'package:flutter/material.dart';
import 'package:graphql_flutter graphqlflutter.dart';
import 'graphql/client.dart';
import 'screens/repos/screen.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initHiveForFlutter();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return GraphQLProvider(
      client: buildGitHubClient(),
      child: MaterialApp(
        title: 'GitHub Repos',
        debugShowCheckedModeBanner: false,
        theme: ThemeData(
          colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo),
          useMaterial3: true,
        ),
        home: const ReposScreen(),
      ),
    );
  }
}

这就是我们Flutter应用的入口点，它将所有组件连接在一起。

main()函数首先通过Widgets FlutterBinding.ensureInitialized()确保Flutter环境已经初始化，这是进行任何异步操作之前的必要步骤。随后它会调用initHiveForFlutter()来准备本地存储空间，因为我们的GraphQL客户端会使用Hive来进行缓存操作。最后，通过runApp()启动应用程序。

MyApp组件负责构建整个应用的结构。其中最重要的部分是GraphQLProvider，它将我们创建的GraphQL客户端（通过buildGitHubClient()获得）注入到整个应用程序的组件树中。这样一来，应用中的任何组件都可以直接使用GraphQL进行查询或操作，而无需手动传递客户端对象。

在 `GraphQLProvider` 中，你定义了一个带有基本应用设置的 `MaterialApp`，这些设置包括标题、主题以及是否禁用调试提示栏。首页被设置为 `ReposScreen`，这意味着当应用程序启动时，用户看到的第一个页面就是这个屏幕。

Repos Screen

// lib/screens/repos_screen.dart

import 'package:flutter/material.dart';
import 'package:graphql_flutter graphqlflutter.dart';
import '../graphql/queries/repo_queries.dart';
import '../graphql/mutations/repo_mutations.dart';

class ReposScreen extends StatelessWidget {
  const ReposScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Query(
      options: QueryOptions(
        document: gql-fetchViewerReposQuery),
        variables: const {'count': 15},
        fetchPolicy: FetchPolicy.cacheAndNetwork,
      ),
      builder: (QueryResult result,
          {VoidCallback? refetch, FetchMore? fetchMore}) {
        if (result isLoading && result.data == null) {
          return const Scaffold(
            body: Center(child: CircularProgressIndicator()),
          );
        }

        if (result.hasException) {
          return Scaffold(
            body: Center(
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  const Icon(Icons.error_outline,
                      size: 48, color: Colors.red),
                  const SizedBox(height: 12),
                  Text(
                    result.exception?.graphqlErrors.firstOrNull?.message
                        ?? '发生错误',
                    textAlign: TextAlign.center,
                  ),
                  const SizedBox(height: 16),
                  ElevatedButton(
                    onPressed: refetch,
                    child: const Text('重试'),
                  ),
                ],
              ),
            ),
          );
        }

        final viewer =
            result.data?['viewer'] as Map?;
        final repos =
            (viewer?['repositories']?['nodes'] as List(dynamic>)?? null
                    ?.cast>() ?? [];

        return Scaffold(
          appBar: AppBar(
            title: Row(
              children: [
                if (viewer?['avatarUrl'] != null)
                  CircleAvatar(
                    backgroundImage:
                        NetworkImage(viewer!['avatarUrl'] as String),
                    radius: 16,
                  ),
                const SizedBox(width: 8),
                Text(viewer?['name'] as String?? ?? viewer?['login'] as String?? ?? ""),
              ],
            ),
            // 用于指示背景数据正在更新中
            bottom: result isLoading
                ? const PreferredSize(
                    preferredSize: Size.fromHeight(2),
                    child: LinearProgressIndicator(),
                  )
                : null,
          ),
          body: RefreshIndicator(
            onRefresh: () async => refetch?.call(),
            child: ListView.separated(
              padding: const EdgeInsets.all(16),
              itemCount: repos.length,
              separatorBuilder: (_, __) => const SizedBox(height: 8),
              itemBuilder: (context, index) => {
                  RepoCard(repo: repos[index]);
            ),
          ),
        );
      },
    );
  }
}

class RepoCard extends StatelessWidget {
  final Map repo;

  const RepoCard({super.key, required this.repo});

  @override
  Widget build(BuildContext context) {
    final language =
        repo['primaryLanguage'] as Map?;
    final isStarred = repo['viewerHasStarred'] as bool?? false;
    final starCount = repo['stargazerCount'] as int?? 0;
    final repoId = repo['id'] as String;
    final mutationDoc = isStarred ? removeStarMutation : addStarMutation;
    final mutationKey = isStarred ? 'removeStar' : 'addStar';

    return Mutation(
      options: MutationOptions(
        document: gql(mutationDoc),
        // 该mutation操作会返回id、stargazerCount以及viewerHasStarded字段。
        // 系统会使用缓存机制根据id来更新相关数据，并将变化通知给所有存储有该仓库信息的组件。
        onError: (error) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(
                error?.graphqlErrors.firstOrNull?.message
                    ?? '操作失败',
              ),
            ),
          );
        },
      ),
      builder: (RunMutation runMutation, QueryResult? mutationResult) {
        final isMutating = mutationResult?.isLoading?? false;

        // 优先使用mutation结果中的数据，这样UI就能显示最新的状态。
        final starrable =
            (mutationResult?.data?[mutationKey] as Map?)?[
                'starrable'] as Map?;

        final currentStarred =
            starrable?['viewerHasStarred'] as bool?? isStarred;
        final currentCount =
            starrable?['stargazerCount'] as int?? starCount;

        return Card(
          child: Padding(
            padding: const EdgeInsets.all(16),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Row(
                  children: [
                    Expanded(
                      child: Text(
                        repo['name'] as String?? '',
                        style: Theme.of(context)
                            .textTheme
                            .titleMedium
                            ?.copyWith.fontWeight: FontWeight.bold),
                      ),
                    ),
                    isMutating
                        ? const SizedBox(
                            width: 24,
                            height: 24,
                            child: CircularProgressIndicator(
                                strokeWidth: 2),
                          )
                        : IconButton(
                            onPressed: () => runMutation(
                              {'repoId': repoId},
                              // 如果是乐观更新，就会在服务器响应之前立即更新UI。
                              optimisticResult: {
                                mutationKey: {
                                  'starrable': {
                                    '__typename': 'Repository',
                                    'id': repoId,
                                    'stargazerCount': isStarred
                                        ? starCount - 1
                                        : starCount + 1,
                                    'viewerHasStarred': !isStarred,
                                  }
                                }
                              },
                            ),
                            icon: Icon(
                              currentStarred
                                  ? Icons.star
                                  : Icons.star_border,
                              color: currentStarred
                                  ? Colors.amber
                                  : Colors.grey,
                            ),
                            tooltip:
                                currentStarred ? '取消星标' : '添加星标',
                          ),
                  ],
                ),
                if (repo['description'] != null)
                  Padding(
                    padding: const EdgeInsets.only(top: 4),
                    child: Text(
                      repo['description'] as String,
                      style: Theme.of(context).textTheme.bodySmall,
                      maxLines: 2,
                      overflow: TextOverflow.ellipsis,
                    ),
                  ),
                const SizedBox(height: 12),
                Row(
                  children: [
                    if (language != null) ...[
                      Container(
                        width: 12,
                        height: 12,
                        decoration: BoxDecoration(
                          shape: BoxShape.circle,
                          color: _parseColor(
                              language['color'] as String?),
                        ),
                      ),
                      const SizedBox(width: 4),
                      Text(
                        language['name'] as String?? ?? '',
                        style: Theme.of(context).textTheme.bodySmall,
                      ),
                      const SizedBox(width: 16),
                    ],
                    const IconIcons.star, size: 14, color: Colors.amber),
                    const SizedBox(width: 4,
                      child: Text(_formatCount(currentCount),
                      style: Theme.of(context).styleType.bodySmall),
                    ),
                  ],
                ),
              ],
            ),
          ),
        );
      },
    );
  }

  Color _parseColor(String? hex) {
    if (hex == null) return Colors.grey;
    final hexValue = hex.replaceFirst('#', '');
    return Color(int.parse('FF$hexValue', radix: 16));
  }

  String _formatCount(int count) {
    if (count >= 1000) return `${(count / 1000).toStringAsFixed(1)}k';
    return count.toString();
  }
}

这段代码使用graphql_flutter在Flutter中构建了一个类似GitHub的仓库界面，它严重依赖GraphQL查询、变更操作以及缓存机制来确保用户界面与远程数据保持同步。
在顶层结构中，ReposScreen组件通过graphqlflutter提供的Query组件从GraphQL接口获取数据。该查询(fetchViewerReposQuery)会请求当前用户及其拥有的仓库列表，并通过参数count: 15来限制返回的仓库数量。其获取数据的策略为cacheAndNetwork，这意味着系统会先尝试显示缓存中的数据，然后再从网络中获取最新数据并进行更新。
当查询结果还在加载中且没有缓存数据时，界面会显示一个加载指示器；如果出现错误，则会显示错误信息并提供一个重试按钮，点击该按钮会重新执行查询操作。
一旦数据获取完成，程序会从响应结果中提取用户信息及仓库列表，然后使用Scaffold结构来呈现界面：AppBar上会显示用户的头像和名称，而ListView则会用RepoCard组件展示每个仓库的详细信息。
每个RepoCard代表一个仓库，其UI逻辑被封装在Mutation组件中。这个组件负责处理将某个仓库添加到“星标列表”中或从列表中移除的操作。根据该仓库是否已被标记为星标(viewerHasStarred)，系统会自动选择相应的变更操作。
当用户点击星标按钮时，runMutation函数会被调用，并传入对应的仓库ID。同时，系统会使用optimisticResult机制来确保UI在服务器响应之前立即得到更新，因此星标的数量和图标会立刻发生变化，从而提供流畅的使用体验。
此外，这个变更操作还定义了一个onError处理函数，用于在操作过程中出现错误时显示提示信息。
在Mutation组件的实现中，如果变更操作的结果已经可用，系统会优先使用这些数据来更新UI，而不是原始的查询结果。这样就能确保无论变更操作是否成功完成，UI都能反映最新的状态。
每个仓库卡片上会显示仓库名称、可选描述、主要使用的语言（用彩色圆点标出）以及星标数量。对于较大的星标数量，系统会采用“1.2k”这样的格式来显示。
在变更操作进行期间，星标按钮上也会显示加载指示器，这样用户就能知道系统正在处理相关请求。
总之，这段代码的核心思想在于：GraphQL的规范化缓存机制在幕后发挥了重要作用。当某个仓库的信息发生变动时，缓存会自动更新所有依赖于该仓库ID的UI元素，从而确保所有内容始终保持一致，而无需手动刷新整个列表。