Flutter GraphQL客户端插件simple_graphql的使用

simple_graphql 是一个简化版的GraphQL客户端插件，旨在减少繁琐的代码编写。以下是如何在Flutter项目中使用该插件的详细指南。

引言

simple_graphql 是 graphql 包的一个简化版本，它帮助开发者省去大量的样板代码。以下是关于如何开始使用它的教程。

安装

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

dependencies:
  simple_graphql: ^latest_version

然后运行 flutter pub get 来安装包。

开始使用

导入库并创建一个新的 SimpleGraphQL 实例：

import 'package:simple_graphql/simple_graphql.dart';

final client = SimpleGraphQL(apiUrl: 'https://api.example/graphql');

注意：API URL必须指定 /graphql 或其他路径结尾。

创建查询

要执行查询，只需调用 query() 方法：

final result = client.query(
  query: '''
    query ExampleQuery {
      getUser {
        id,
        name,
        email
      }
    }
  ''',
  resultBuilder: (data) {
    return User.fromMap(data['getUser']);
  },
);

这里 resultBuilder 参数是一个方便的构建器，返回解码后的结果 Map。通常你会在这里将结果序列化为具体的对象或直接返回原始的 Map。

创建变更

类似地，执行变更（mutation）时，可以调用 mutation() 方法：

final result = client.mutation(
  query: '''
    mutation CreatePost(\$title: String!, \$content: String!) {
      createPost(title: \$title, content: \$content) {
        id,
        title,
        content
      }
    }
  ''',
  variables: {'title': 'My Title', 'content': 'My Content'},
  resultBuilder: (data) {
    return Post.fromMap(data['createPost']);
  },
);

高级用法

认证与基于令牌的请求

你可以通过两种方式设置用于认证的令牌：在构造函数中设置或在每个查询/变更中设置。

在构造函数中设置令牌

final client = SimpleGraphQL(
  apiUrl: 'https://api.example/graphql',
  token: 'Bearer $token', // 必须包含前缀，如 "Bearer"
  authHeaderKey: 'Authorization', // 可选，默认为 'Authorization'
);

这将在所有查询和变更中使用 [AuthLink] 设置令牌。

在查询或变更中设置令牌

final result = client.query(
  query: '<Your query goes here>',
  resultBuilder: (data) => data,
  token: 'Bearer $token', // 必须包含前缀，如 "Bearer"
  authHeaderKey: 'Authorization', // 可选，默认为 'Authorization'
);

这将在特定的查询或变更中覆盖构造函数中设置的令牌。

自定义头信息

你也可以以类似的方式设置自定义头信息。

在构造函数中设置头信息

final client = SimpleGraphQL(
  apiUrl: 'https://api.example/graphql',
  defaultHeaders: {
    'customHeaderKey': 'Custom value',
  },
);

在查询或变更中设置头信息

final result = client.query(
  headers: {
    'customHeaderKey': 'Custom value',
  },
  query: '<Your query goes here>',
  resultBuilder: (data) => data,
);

默认情况下，headers 参数会与构造函数传递的 defaultHeaders 合并。

自定义策略

你可以像原生包一样定义请求的策略，例如获取策略、错误策略和缓存重读策略等。

示例：

final result = client.mutation(
  fetchPolicy: FetchPolicy.noCache,
  cacheRereadPolicy: CacheRereadPolicy.mergeOptimistic,
  errorPolicy: ErrorPolicy.ignore,
  mutation: ...,
  resultBuilder: (data) => ...,
);

示例Demo

下面是一个完整的Flutter应用示例，展示了如何集成和使用 simple_graphql：

import 'package:flutter/material.dart';
import 'package:simple_graphql/simple_graphql.dart';

void main() {
  runApp(const MyApp());
}

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(title: 'GraphQL Example'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  late final SimpleGraphQL client;
  dynamic _data;

  [@override](/user/override)
  void initState() {
    super.initState();
    client = SimpleGraphQL(apiUrl: 'https://api.example/graphql');
    fetchData();
  }

  Future<void> fetchData() async {
    final result = await client.query(
      query: '''
        query ExampleQuery {
          getUser {
            id,
            name,
            email
          }
        }
      ''',
      resultBuilder: (data) => data['getUser'],
    );

    setState(() {
      _data = result;
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: _data == null
            ? const CircularProgressIndicator()
            : Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Text('Name: ${_data['name']}'),
                  Text('Email: ${_data['email']}'),
                ],
              ),
      ),
    );
  }
}