如何在Flutter中使用GraphQL？求推荐适配的相关工具包

作为Flutter新手对接NestJS GraphQL后端，以下是最实用的工具包推荐和入门步骤：

核心工具包推荐 #

• graphql_flutter：Flutter生态中最主流的GraphQL客户端，由官方维护，支持查询、突变、WebSocket订阅，完美适配NestJS的Apollo Server配置，上手门槛低，文档完善。
• ferry：强类型GraphQL客户端，基于AST生成Dart模型，和NestJS的代码优先模式高度契合，适合中大型项目，能大幅减少手动编写数据模型的重复工作。
• artemis：专注于GraphQL代码生成的工具，可根据NestJS导出的Schema自动生成强类型Dart类，配合graphql_flutter使用，能实现严格的类型检查，避免 runtime 错误。

入门实操步骤 #

1. 添加依赖 #

在pubspec.yaml中引入所需依赖：

dependencies:
  graphql_flutter: ^5.1.2
  # 若需代码生成，添加以下依赖
  artemis: ^7.0.0
dev_dependencies:
  build_runner: ^2.4.4

执行flutter pub get安装依赖。

2. 初始化GraphQL客户端 #

对接NestJS的HTTP端点和WebSocket订阅端点（如果用实时推送）：

import 'package:graphql_flutter/graphql_flutter.dart';

// HTTP链接
final HttpLink httpLink = HttpLink('http://你的NestJS服务器地址/graphql');
// WebSocket链接（用于订阅）
final WebSocketLink webSocketLink = WebSocketLink(
  'ws://你的NestJS服务器地址/graphql',
  config: SocketClientConfig(autoReconnect: true),
);

// 根据请求类型自动切换链接
final Link link = Link.split(
  (request) => request.isSubscription,
  webSocketLink,
  httpLink,
);

// 初始化客户端
final GraphQLClient client = GraphQLClient(
  cache: GraphQLCache(), // 内置缓存，可按需配置
  link: link,
);

3. 执行查询与突变 #

查询数据

// 定义GraphQL查询
const String getUsersQuery = r'''
query GetUsers {
  users {
    id
    name
    email
  }
}
''';

// 在Widget中使用Query组件
Query(
  options: QueryOptions(document: gql(getUsersQuery)),
  builder: (QueryResult result, {VoidCallback? refetch, FetchMore? fetchMore}) {
    if (result.hasException) return Text(result.exception.toString());
    if (result.isLoading) return const CircularProgressIndicator();

    final List<dynamic> users = result.data?['users'] ?? [];
    return ListView.builder(
      itemCount: users.length,
      itemBuilder: (context, index) {
        final user = users[index];
        return ListTile(title: Text(user['name']), subtitle: Text(user['email']));
      },
    );
  },
);

执行突变（增删改）

// 定义突变
const String createUserMutation = r'''
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
  }
}
''';

// 触发突变
final MutationOptions options = MutationOptions(
  document: gql(createUserMutation),
  variables: {
    'input': {'name': '张三', 'email': 'zhangsan@example.com'}
  },
);

final QueryResult result = await client.mutate(options);
if (result.hasException) {
  // 处理错误
} else {
  // 处理返回数据
}

4. 强类型代码生成（可选） #

如果用artemis，先从NestJS的GraphQL端点导出Schema（访问http://你的服务器地址/graphql?export=schema下载schema.json），然后在项目根目录创建build.yaml：

targets:
  $default:
    builders:
      artemis:
        options:
          schema: lib/graphql/schema.json
          queries_glob: lib/graphql/**/*.graphql
          output_dir: lib/graphql/generated/

执行flutter pub run build_runner build自动生成Dart模型，之后就能用强类型对象处理查询结果，无需手动解析JSON。

额外注意事项 #

• 权限验证：如果NestJS用JWT鉴权，可在HttpLink中添加请求头：

  final HttpLink httpLink = HttpLink(
    'http://你的服务器地址/graphql',
    defaultHeaders: {'Authorization': 'Bearer ${你的JWT令牌}'},
  );
  

• 订阅适配：NestJS的Apollo Server默认支持WebSocket订阅，直接用WebSocketLink即可对接，无需额外配置。
• 缓存优化：graphql_flutter的GraphQLCache支持自定义策略，可根据项目需求配置缓存过期、数据更新规则。

内容的提问来源于stack exchange，提问作者Roeurb Navy