Flutter GraphQL客户端插件graphql_client_flutter的使用

Flutter GraphQL客户端插件graphql_client_flutter的使用

标题

GraphQL Client Flutter

内容

A powerful, flexible, and feature-rich GraphQL client for Flutter applications. Simplify interactions with GraphQL APIs with built-in caching, error handling, real-time subscriptions, batch operations, and more.

• Flutter: Flutter Logo
• Dart: Dart Logo
• Pub Version:
• License:
• CI:

目录

1. 特性
2. 安装
3. 开始使用
4. 使用
   • 配置客户端
   • 执行查询
   • 执行突变
   • 订阅
   • 批量操作
   • 缓存管理
   • 错误处理
5. 高级配置
   • 自定义拦截器
   • 重试逻辑
   • 日志选项
6. 测试
7. 贡献
8. 许可证
9. 补充信息

特性

• 全GraphQL支持
  • 精湛地处理查询、突变和订阅。
• 高级缓存
  • 多种缓存策略（例如，网络优先、缓存优先）。
  • 内存和持久存储选项。
  • 支持缓存条目的时间到活（TTL）。
• 内置重试机制
  • 可配置的重试尝试次数和延迟。
  • 指数退避策略。
• 强大的错误处理
  • 详细的错误信息带堆栈跟踪。
  • 可定制的错误处理策略。
• 全面的日志记录
  • 请求和 响应日志。
  • GraphQL查询和JSON数据的漂亮打印。
• 批量操作
  • 在单个网络请求中执行多个操作。
• 订阅支持
  • 实时数据更新通过WebSocket订阅。
• 干净架构
  • 设计用于维护和测试。

安装

在项目 pubspec.yaml 文件中添加依赖项：

dependencies:
  graphql_client_flutter: ^1.0.0

然后运行：

dart pub get

开始使用

要开始使用 graphql_client_flutter，您需要配置客户端以连接到您的GraphQL API端点。

示例

import 'package:graphql_client_flutter/graphql_client_flutter.dart';

void main() async {
  // 创建客户端配置
  final config = GraphQLConfig(
    endpoint: 'https://api.example.com/graphql',
    subscriptionEndpoint: 'wss://api.example.com/graphql',
    defaultCachePolicy: CachePolicy.cacheFirst,
    defaultTimeout: Duration(seconds: 30),
    enableLogging: true,
    maxRetries: 3,
    retryDelay: Duration(seconds: 1),
    defaultHeaders: {
      'Authorization': 'Bearer YOUR_TOKEN',
    },
  );

  // 初始化客户端
  final client = GraphQLClientBase(config: config);

  // 使用客户端执行操作
}

配置客户端

首先，导入包并创建一个配置：

import 'package:graphql_client_flutter/graphql_client_flutter.dart';

void main() async {
  // 创建客户端配置
  final config = GraphQLConfig(
    endpoint: 'https://api.example.com/graphql',
    subscriptionEndpoint: 'wss://api.example.com/graphql',
    defaultCachePolicy: CachePolicy.cacheFirst,
    defaultTimeout: Duration(seconds: 30),
    enableLogging: true,
    maxRetries: 3,
    retryDelay: Duration(seconds: 1),
    defaultHeaders: {
      'Authorization': 'Bearer YOUR_TOKEN',
    },
  );

  // 初始化客户端
  final client = GraphQLClientBase(config: config);

  // ... 使用客户端
}

执行查询

使用 query 方法执行GraphQL查询：

final response = await client.query<Map<String, dynamic>>(
  '''
  query GetUsers(\$limit: Int) {
    users(limit: \$limit) {
      id
      name
      email
    }
  }
  ''',
  variables: {'limit': 10},
  cachePolicy: CachePolicy.cacheAndNetwork,
  ttl: Duration(minutes: 10),
);

if (response.hasErrors) {
  print('Errors: ${response.errors}');
} else {
  print('Users: ${response.data?['users']}');
}

执行突变

使用 mutate 方法执行GraphQL突变：

final response = await client.mutate<Map<String, dynamic>>(
  '''
  mutation CreateUser(\$input: CreateUserInput!) {
    createUser(input: \$input) {
      id
      name
      email
    }
  }
  ''',
  variables: {
    'input': {
      'name': 'Jane Doe',
      'email': 'jane@example.com',
    },
  },
  invalidateCache: ['GetUsers'], // 指定要失效的查询
);

if (response.hasErrors) {
  print('Errors: ${response.errors}');
} else {
  print('Created User: ${response.data?['createUser']}');
}

订阅

订阅实时数据使用 subscribe 方法：

final subscription = client.subscribe<Map<String, dynamic>>(
  '''
  subscription OnNewUser {
    userCreated {
      id
      name
      email
    }
  }
  ''',
).listen(
  (response) {
    print('New User: ${response.data?['userCreated']}');
  },
  onError: (error) {
    print('Subscription error: $error');
  },
);

// 记得在完成时取消订阅
await subscription.cancel();

批量操作

使用 batch 方法执行多个操作在一个网络请求中：

final batchResponse = await client.batch([
  BatchOperation(
    query: '''
      query GetUser(\$id: ID!) {
        user(id: \$id) {
          id
          name
        }
      }
    ''',
    variables: {'id': '1'},
  ),
  BatchOperation(
    query: '''
      mutation UpdateUser(\$id: ID!, \$input: UpdateUserInput!) {
        updateUser(id: \$id, input: \$input) {
          id
          name
          email
        }
      }
    ''',
    variables: {
      'id': '1',
      'input': {'name': 'Updated Name'},
    },
  ),
]);

// 访问单独的响应
final getUserResponse = batchResponse.responses[0];
final updateUserResponse = batchResponse.responses[1];

缓存管理

使用提供的方法管理缓存：

// 清除整个缓存
await client.clearCache();

// 效应特定查询
await client.invalidateQueries(['GetUsers', 'GetUser']);

// 获取缓存统计信息
final stats = await client.getCacheStats();
print('Cache Stats: $stats');

错误处理

优雅地处理错误：

try {
  final response = await client.query('your query');
  if (response.hasErrors) {
    // 处理GraphQL错误
    for (final error in response.errors!) {
      print('Error: ${error.message}');
    }
  } else {
    // 使用响应数据
  }
} on GraphQLException catch (e) {
  // 处理由客户端抛出的异常
  print('GraphQL Exception: ${e.message}');
} catch (e) {
  // 处理其他异常
  print('General Exception: $e');
}

高级配置

自定义拦截器

您可以提供自定义拦截器来扩展客户端的功能：

final client = GraphQLClientBase(
  config: config,
  interceptors: [
    MyCustomInterceptor(),
    // 添加其他拦截器
  ],
);

重试逻辑

配置失败请求的重试行为：

final config = GraphQLConfig(
  endpoint: 'https://api.example.com/graphql',
  maxRetries: 5,
  retryDelay: Duration(seconds: 2),
  // 选项性地提供一个自定义 shouldRetry 函数
);

日志选项

精细调整日志设置使用 LoggingInterceptor：

final client = GraphQLClientBase(
  config: config,
  interceptors: [
    LoggingInterceptor(
      options: LoggingOptions(
        logRequests: true,
        logResponses: true,
        logErrors: true,
      ),
      prettyPrintJson: true,
    ),
  ],
);

测试

此包包括全面的测试以确保可靠性和正确性。要运行测试，请使用以下命令：

dart test test/graphql_client_test.dart

确保已安装必要的开发依赖项，如指定在 pubspec.yaml 中：