Flutter GraphQL客户端代码生成插件graphql_client_gen的使用

Generates opinionated graphql client annotated classes and methods defined by graphql_client_annotation for generating opinionated graphql client class.

The annotated classes must depend on GraphQLClient from this package in order to generate successfully.

配置 Setup

要为最新发布的 graphql_client_gen 版本配置您的项目，请参阅 example。

示例 Example

假设有一个实体类 Example 和一个带有 @gqlClient 注解的 graphql 客户端类 ExampleRemoteSource：

import 'package:graphql/client.dart';
import 'package:graphql_client_annotation/graphql_client_annotation.dart';

part 'example_remote_source.gqlc.dart';

@gqlClient
abstract class ExampleRemoteSource {
  const factory ExampleRemoteSource(
    GraphQLClient client,
  ) = _ExampleRemoteSource;

  @Query(
    parser: Example.fromJson,
    r'''
    query detailExample($id: String!) {
      detailExample(detailExampleInput: { exampleId: $id }) {
        id
        name
      }
    }
    ''',
  )
  Future<QueryResult<Example>> getExample1(Map<String, dynamic> variables);
}

构建后会生成对应的部分文件 example_remote_source.gqlc.dart：

part of 'example_remote_source.dart';

class _ExampleRemoteSource implements ExampleRemoteSource {
  const _ExampleRemoteSource(this._client);

  final GraphQLClient _client;

  static final _$getExample1Gql = gql(r'''
    query detailExample($id: String!) {
      detailExample(detailExampleInput: { exampleId: $id }) {
        id
        name
      }
    }
    ''');
  @override
  Future<QueryResult<Example>> getExample1(Map<String, dynamic> variables) {
    final QueryOptions<Example> options = QueryOptions<Example>(
      document: _$getExample1Gql,
      variables: variables,
      parserFn: Example.fromJson,
    );
    return _client.query(options);
  }
}

运行代码生成器 Running the code generator

添加注解后，您需要运行代码生成器以生成缺失的 .gqlc.dart 文件。

在 Dart 包中，运行以下命令：

dart run build_runner build

在 Flutter 包中，运行以下命令：

flutter pub run build_runner build

注解值 Annotation values

每个目标类必须是一个抽象类，并用 @GQLClient 或预定义的 @gqlClient 注解标记，每个将使用 GraphQLClient 的方法必须用 @Mutation 或 @Query 注解。

每个带注解的方法生成的代码默认返回值为 Future<QueryResult<YourEntity>>，其中 YourEntity 是您在 @Mutation 或 @Query 中定义的 parser 预期创建的类。

如果要自定义返回值，可以在 @GQLClient 或 @Mutation/@Query 中定义 mapper。例如：

给定一个库 app_gql_client.dart：

import 'package:graphql/client.dart';
import 'package:graphql_client_annotation/graphql_client_annotation.dart';
import 'package:meta/meta.dart';

@optionalTypeArgs
MyEntity<T> queryResultMapper<T>(QueryResult<T> queryResult) {
  return MyEntity<T>();
}

@optionalTypeArgs
MyEntity<Object> queryResultMapper2<T>(QueryResult<T> queryResult) {
  return MyEntity<Object>();
}

class MyEntity<T> {}

const GQLClient appGQLClient = GQLClient(mapper: queryResultMapper);

以及一个抽象类 ExampleRemoteSource：

import 'package:example/src/app_gql_client.dart';
import 'package:example/src/example.dart';
import 'package:graphql/client.dart';
import 'package:graphql_client_annotation/graphql_client_annotation.dart';

part 'example_remote_source.gqlc.dart';

@appGQLClient
abstract class ExampleRemoteSource {
  const factory ExampleRemoteSource(
    GraphQLClient client,
  ) = _ExampleRemoteSource;

  @Query(
    parser: Example.fromMap,
    fetchPolicy: FetchPolicy.networkOnly,
    r'''
    query detailExample($id: String!) {
      detailExample(detailExampleInput: { exampleId: $id }) {
        id
        name
      }
    }
    ''',
  )
  Future<MyEntity<Example>> getExample1(Map<String, dynamic> variables);

  @Mutation(
    parser: Example.fromMap,
    mapper: queryResultMapper2,
    r'''
    query example {
    ''',
  )
  Future<MyEntity<Object>> getExample2();
}

构建后会生成对应的部分文件 example_remote_source.gqlc.dart：

part of 'example_remote_source.dart';

class _ExampleRemoteSource implements ExampleRemoteSource {
  const _ExampleRemoteSource(this._client);

  final GraphQLClient _client;

  static final _$getExample1Gql = gql(r'''
    query detailExample($id: String!) {
      detailExample(detailExampleInput: { exampleId: $id }) {
        id
        name
      }
    }
    ''');
  @override
  Future<MyEntity<Example>> getExample1(Map<String, dynamic> variables) {
    final QueryOptions<Example> options = QueryOptions<Example>(
      document: _$getExample1Gql,
      variables: variables,
      fetchPolicy: FetchPolicy.networkOnly,
      parserFn: Example.fromMap,
    );
    return _client.query(options).then(queryResultMapper);
  }

  static final _$getExample2Gql = gql(r'''
    query example {
    ''');
  @override
  Future<MyEntity<Object>> getExample2() {
    final MutationOptions<Example> options = MutationOptions<Example>(
      document: _$getExample2Gql,
      parserFn: Example.fromMap,
    );
    return _client.mutate(options).then(queryResultMapper2);
  }
}

示例代码 Example Code

以下是一个完整的示例代码：

// example/lib/example.dart
export 'src/example.dart';