Flutter GraphQL 请求插件 custom_graphql_flutter 的使用

在本指南中，我们将详细介绍如何在 Flutter 中使用 custom_graphql_flutter 插件来执行 GraphQL 请求。我们将涵盖安装、基本用法、查询（包括分页）、突变（包括乐观突变）以及订阅。

引言

custom_graphql_flutter 提供了一套用于 graphql/client.dart 的 Flutter API 和小部件。它们在 GitHub 上共同开发，您可以在那里找到更深入的例子。我们也有一个活跃的社区在 Discord 上。

本指南主要关注设置、小部件以及 Flutter 特定的注意事项。对于 graphql API 的更多详细信息，请参阅 graphql 的 README。

有用的章节

• 深度链接指南
• 直接缓存访问
• 缓存写入严格性
• 策略
• 异常
• AWS AppSync 支持
• GraphQL 上传
• 构建时解析 ASTs

有用的 API 文档

• GraphQLCache
• GraphQLDataProxy API 文档（直接缓存访问）

安装

首先，在 pubspec.yaml 文件中添加依赖：

$ flutter pub add custom_graphql_flutter

然后在 Dart 代码中导入：

import 'package:custom_graphql_flutter/graphql_flutter.dart';

使用

为了连接到 GraphQL 服务器，我们需要创建一个 GraphQLClient。GraphQLClient 需要 cache 和 link 两个参数才能初始化。

在我们的示例中，我们将使用 Github 公共 API。我们将使用 HttpLink 并将其与 AuthLink 连接起来以附加我们的 GitHub 访问令牌。对于缓存，我们将使用 GraphQLCache。

import 'package:custom_graphql_flutter/graphql_flutter.dart';
import 'package:hive/hive.dart';
import 'package:path_provider/path_provider.dart';

void main() async {
  // 我们将使用 HiveStore 进行持久化，
  // 因此我们需要初始化 Hive。
  await initHiveForFlutter();
  
  final HttpLink httpLink = HttpLink(
    'https://api.github.com/graphql',
  );

  final AuthLink authLink = AuthLink(
    getToken: () async => 'Bearer <YOUR_PERSONAL_ACCESS_TOKEN>',
    // 或者
    // getToken: () => 'Bearer <YOUR_PERSONAL_ACCESS_TOKEN>',
  );

  final Link link = authLink.concat(httpLink);

  ValueNotifier<GraphQLClient> client = ValueNotifier(
    GraphQLClient(
      link: link,
      // 默认存储是 InMemoryStore，它不会持久化到磁盘
      cache: GraphQLCache(store: HiveStore()),
    ),
  );

  runApp(MyApp(client: client));
}

GraphQL Provider

为了使用客户端，您的 Query 和 Mutation 小部件必须包装在 GraphQLProvider 小部件中。

建议将 MaterialApp 包裹在 GraphQLProvider 小部件中。

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

class MyApp extends StatelessWidget {
  final ValueNotifier<GraphQLClient> client;

  MyApp({required this.client});

  @override
  Widget build(BuildContext context) {
    return GraphQLProvider(
      client: client,
      child: MaterialApp(
        title: 'Flutter Demo',
        home: MyHomePage(),
      ),
    );
  }
}

查询

创建查询就像创建一个多行字符串一样简单：

String readRepositories = """
  query ReadRepositories(\$nRepositories: Int!) {
    viewer {
      repositories(last: \$nRepositories) {
        nodes {
          id
          name
          viewerHasStarred
        }
      }
    }
  }
""";

在您的小部件中：

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

class MyHomePage extends StatefulWidget {
  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    return Query(
      options: QueryOptions(
        document: gql(readRepositories),
        variables: {
          'nRepositories': 50,
        },
        pollInterval: const Duration(seconds: 10),
      ),
      builder: (QueryResult result, { VoidCallback? refetch, FetchMore? fetchMore }) {
        if (result.hasException) {
          return Text(result.exception.toString());
        }

        if (result.isLoading) {
          return const Text('Loading');
        }

        List? repositories = result.data?['viewer']?['repositories']?['nodes'];

        if (repositories == null) {
          return const Text('No repositories');
        }

        return ListView.builder(
          itemCount: repositories.length,
          itemBuilder: (context, index) {
            final repository = repositories[index];
            return Text(repository['name'] ?? '');
          },
        );
      },
    );
  }
}

或者，如果您更喜欢使用 flutter-hooks，您可以这样写：

import 'package:flutter/material.dart';
import 'package:custom_graphql_flutter/graphql_flutter.dart';
import 'package:flutter_hooks/flutter_hooks.dart';

class MyHomePage extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final readRepositoriesResult = useQuery(
      QueryOptions(
        document: gql(readRepositories),
        variables: {
          'nRepositories': 50,
        },
        pollInterval: const Duration(seconds: 10),
      ),
    );
    final result = readRepositoriesResult.result;

    if (result.hasException) {
      return Text(result.exception.toString());
    }

    if (result.isLoading) {
      return const Text('Loading');
    }

    List? repositories = result.data?['viewer']?['repositories']?['nodes'];

    if (repositories == null) {
      return const Text('No repositories');
    }

    return ListView.builder(
      itemCount: repositories.length,
      itemBuilder: (context, index) {
        final repository = repositories[index];
        return Text(repository['name'] ?? '');
      },
    );
  }
}

分页

您可以使用 fetchMore() 函数在 Query 构建器中执行分页。fetchMore() 函数允许您运行一个新的 GraphQL 操作并将新结果合并到原始结果中。此外，您可以重用原始查询的某些方面，例如查询或变量。

为了使用 fetchMore() 函数，您需要首先定义 FetchMoreOptions 变量用于新的查询。

final Map pageInfo = result.data['search']['pageInfo'];
final String fetchMoreCursor = pageInfo['endCursor'];

FetchMoreOptions opts = FetchMoreOptions(
  variables: {'cursor': fetchMoreCursor},
  updateQuery: (previousResultData, fetchMoreResultData) {
    final List<dynamic> repos = [
      ...previousResultData['search']['nodes'] as List<dynamic>,
      ...fetchMoreResultData['search']['nodes'] as List<dynamic>
    ];

    fetchMoreResultData['search']['nodes'] = repos;
    return fetchMoreResultData;
  },
);

然后，调用 fetchMore() 函数并传递您定义的 FetchMoreOptions 变量。

RaisedButton(
  child: Row(
    mainAxisAlignment: MainAxisAlignment.center,
    children: <Widget>[
      Text("Load More"),
    ],
  ),
  onPressed: () {
    fetchMore(opts);
  },
)

突变

同样，首先创建一个突变字符串：

String addStar = """
  mutation AddStar(\$starrableId: ID!) {
    addStar(input: {starrableId: \$starrableId}) {
      starrable {
        viewerHasStarred
      }
    }
  }
""";

突变的语法与查询非常相似。唯一的区别是构建函数的第一个参数是一个突变函数。只需调用它即可触发突变。

Mutation(
  options: MutationOptions(
    document: gql(addStar),
    update: (GraphQLDataProxy cache, QueryResult result) {
      return cache;
    },
    onCompleted: (dynamic resultData) {
      print(resultData);
    },
  ),
  builder: (
    RunMutation runMutation,
    QueryResult result,
  ) {
    return FloatingActionButton(
      onPressed: () => runMutation({
        'starrableId': '<A_STARTABLE_REPOSITORY_ID>',
      }),
      tooltip: 'Star',
      child: Icon(Icons.star),
    );
  },
);

对应的钩子实现如下：

import 'package:flutter/material.dart';
import 'package:custom_graphql_flutter/graphql_flutter.dart';
import 'package:flutter_hooks/flutter_hooks.dart';

class MyHomePage extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final addStarMutation = useMutation(
      MutationOptions(
        document: gql(addStar),
        update: (GraphQLDataProxy cache, QueryResult result) {
          return cache;
        },
        onCompleted: (dynamic resultData) {
          print(resultData);
        },
      ),
    );
    return FloatingActionButton(
      onPressed: () => addStarMutation.runMutation({
        'starrableId': '<A_STARTABLE_REPOSITORY_ID>',
      }),
      tooltip: 'Star',
      child: Icon(Icons.star),
    );
  }
}

graphql 还提供了文件上传支持。

乐观突变

通过向 RunMutation 传递 optimisticResult，GraphQLCache 允许进行乐观突变。它将两次调用 update(GraphQLDataProxy cache, QueryResult result)（一次急切地使用 optimisticResult），并重新广播所有查询以使用乐观缓存状态。

有关如何与 update 提供的 proxy 进行接口的完整和注释详尽的说明，可以查看 GraphQLDataProxy API 文档。

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () {
        toggleStar(
          { 'starrableId': repository['id'] },
          optimisticResult: {
            'action': {
              'starrable': {'viewerHasStarred': !starred}
            }
          },
        );
      },
    );
  }
}

订阅

订阅的语法再次类似于查询，但它利用了 WebSocket 和 dart Streams 来从服务器提供实时更新。

为了使用订阅，订阅消费链接必须从您的 HttpLink 或其他终止链接路由中分离出来：

link = Link.split((request) => request.isSubscription, websocketLink, link);

然后，您可以订阅服务器模式提供的任何 subscription：

final subscriptionDocument = gql(
  r'''
    subscription reviewAdded {
      reviewAdded {
        stars, commentary, episode
      }
    }
  ''',
);

class MyHomePage extends StatefulWidget {
  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Subscription(
          options: SubscriptionOptions(
            document: subscriptionDocument,
          ),
          builder: (result) {
            if (result.hasException) {
              return Text(result.exception.toString());
            }

            if (result.isLoading) {
              return Center(
                child: const CircularProgressIndicator(),
              );
            }
            return ResultAccumulator.appendUniqueEntries(
              latest: result.data,
              builder: (context, {results}) => DisplayReviews(
                reviews: results.reversed.toList(),
              ),
            );
          }
        ),
      )
    );
  }
}

对应的钩子实现如下：

import 'package:flutter/material.dart';
import 'package:custom_graphql_flutter/graphql_flutter.dart';
import 'package:flutter_hooks/flutter_hooks.dart';

class MyHomePage extends HooksWidget {
  @override
  Widget build(BuildContext context) {
    final subscriptionResult = useSubscription(
      SubscriptionOptions(
        document: subscriptionDocument,
      ),
    );
    
    Widget child;
    if (subscriptionResult.hasException) {
      child = Text(subscriptionResult.exception.toString());
    } else if (subscriptionResult.isLoading) {
      child = Center(
        child: const CircularProgressIndicator(),
      );
    } else {
      child = ResultAccumulator.appendUniqueEntries(
        latest: subscriptionResult.data,
        builder: (context, {results}) => DisplayReviews(
          reviews: results.reversed.toList(),
        ),
      );    
    }
    return Scaffold(
      body: Center(child: child)
    );
  }
}

其他钩子

除了 useMutation、useQuery 和 useSubscription，该包还包含以下钩子：

final client = useGraphQLClient(); // 获取当前客户端
final observableQuery = useWatchQuery(WatchQueryOptions(...)); // 监视查询
final mutationObservableQuery = useWatchMutation(WatchQueryOptions(...)); // 监视突变

GraphQL Consumer

如果您想直接使用 client，比如其直接缓存更新方法，您可以使用 GraphQLConsumer 从任何 GraphQLProvider 下降的 context 中获取它：

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

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return GraphQLConsumer(
      builder: (GraphQLClient client) {
        // 对客户端做些什么

        return Container(
          child: Text('Hello world'),
        );
      },
    );
  }
}

代码生成

该包本身不支持代码生成，但 graphql_codegen 做到了！

该包生成钩子和选项，消除了序列化的麻烦，并通过类型安全给您信心。

例如，通过创建 .graphql 文件：

query ReadRepositories($nRepositories: Int!) {
  viewer {
    repositories(last: $nRepositories) {
      nodes {
        id
        name
      }
    }
  }
}

构建后，您可以通过钩子在代码中查询：

final queryResult = useQueryReadRepositories(
  OptionsQueryReadRepositories(
    variables: VariablesQueryReadRepositories(
      nRepositories: 10
    )
  )
);
if (queryResult.result.hasException) {
  return Text(queryResult.result.exception.toString());
}
if (queryResult.result.isLoading) {
  return Text(text: "LOADING");
}
final data = queryResult.result.parsedData;

return Column(
  children: data?.viewer.repositories.nodes.map((node) => Text(text: node.name)).toList() ?? [],
);