GraphQL标准的Java实现graphql-java概述

秒速五厘米 2022-05-27 11:11 1272阅读 0赞

GraphQL标准提供了多种主流编程语言的实现，本文介绍其中的Java实现graphql-java。所谓GraphQL标准的实现，就是一个GraphQL服务器的实现，通过一组软件组件，以支持请求的解析、验证和执行GraphQL查询。

graphql-java就是GraphQL标准的Java语言实现之一，当前最新版本是8.0。在Maven项目中配置如下：

<dependency>
        <groupId>com.graphql-java</groupId>
        <artifactId>graphql-java</artifactId>
        <version>8.0</version>
    </dependency>

本文主要介绍graphql-java的核心的GraphQL Schema定义。

1. GraphQL Schema

就类似于数据库服务器要响应用户对数据库的访问，首先要定义数据库Schema一样。GraphQL服务器要是响应用户对REST数据的查询请求，也要定义一个描述服务数据的结构，就是GraphQL Schema。

为了定义GraphQL Schema，graphql-java提供了如下两种定义的方式：

*  代码中编程定义动态GraphQL Schema

GraphQLObjectType fooType = newObject()
        .name("Ci")
        .field(newFieldDefinition()
                .name("product_number")
                .type(GraphQLString))
        .build();

如代码所示，运行中创建了新类型Ci，并为其定义了属性product\_number，该属性的类型为Scalar的GraphQLString。

*  使用SDL (Schema Definition Language)在独立的资源文件中定义静态GraphQL Schema

创建src/main/resources/myschema.graphqls文件，定义类型Ci如下：

type Ci {
        product_number: String
    }

这里，为了示例，两种方式定义的GraphQL Schema完全等价。

实际上定义完整的GraphQL Schema还有具体的语法，请参考[创建GraphQL Schema][GraphQL Schema]。

2. DataFetcher/TypeResolver

GraphQL Schema中的每个字段类型，都关联一个DataFetcher（在Node.js实现或Python实现中被称为resolver函数），用以为GraphQL Schema中的字段类型获取数据。数据源可以是数据库或REST服务，并将数据表示为Java POJO对象。DataFetcher对象可以直接读取Java POJO对象的属性，再使用Jackson或GSON转换为JSON格式的数据。

DataFetcher pnDataFetcher = new DataFetcher() {
        @Override
        public Object get(DataFetchingEnvironment environment) {
            Map response = fetchPnFromDatabase(environment.getArgument("product_number"));
    		List<GraphQLError> errors = ((List)response.get("errors")).stream()
    			.map(MyMapGraphQLError::new)
    			.collect(Collectors.toList());
    		return new DataFetcherResult(response.get("data"), errors);
        }
    };

GraphQLObjectType objectType = newObject()
            .name("Ci")
            .field(newFieldDefinition()
                    .name("product_number")
                    .type(GraphQLString)
                    .dataFetcher(pnDataFetcher))
            .build();

注意，这里的dataFetcher()方法的使用。

与DataFetcher获取数据的作用相似，TypeResolver提供了更强大的功能，能够根据获取的数据转换为对应的Schema中定义的字段类型，这对面向接口的编程有很大的意义。在一个获取数据的方法中，定义返回的类型是接口，而实际返回可能是实现该接口的任何对象，根据获取的数据转换为对应的对象，返回即可。

3. Runtime Wiring

创建完毕GraphQL Schema还只是开始，还要将其应用在GraphQL服务器上。这就类似于定义数据库结构的SDL脚本已经准备就绪，但是真正在数据库服务器上执行后才生效。

在GraphQL服务器上真正执行GraphQL Schema使其运行起来，是通过Runtime Wiring，这样才能够得到一个可执行的GraphQL Schema。典型代码如下：

File schemaFile = loadSchema("myschema.graphqls");
    
    SchemaParser schemaParser = new SchemaParser();
    TypeDefinitionRegistry typeRegistry = schemaParser.parse(schemaFile);
    
    RuntimeWiring wiring = RuntimeWiring.newRuntimeWiring()....build();
    SchemaGenerator schemaGenerator = new SchemaGenerator();
    GraphQLSchema graphQLSchema = schemaGenerator.makeExecutableSchema(typeRegistry, wiring);

4. GraphQL服务

已经有了完整的可响应请求的GraphQL Schema，现在就运行起来吧。

GraphQL build = GraphQL.newGraphQL(graphQLSchema).build();

5. Execution请求GraphQL服务

1) 请求参数

在请求应用中，可以直接将请求参数以字符串的形式传递给GraphQL服务，如下所示：

ExecutionResult executionResult = build.execute("query { hero { name } }");

也可以先构建ExecutionInput对象（适合复杂的请求参数），然后再传递给GraphQL服务，如下所示：

ExecutionInput executionInput = ExecutionInput.newExecutionInput().query("query { hero { name } }")
            .build();
    ExecutionResult executionResult = build.execute(executionInput);

2)处理结果

GraphQL服务的响应结果在data中，如果出错则在

executionResult.getData().toString();
    List<GraphQLError> errors = executionResult.getErrors();

如果要将得到的响应数据序列化为JSON格式，为了完全兼容GraphQL标准，建议首先将响应结果进行规范化转换，然后再调用Jackson或GSON等JSON库进行JSON格式转换。

Map<String, Object> toSpecificationResult = executionResult.toSpecification();
    doWithJson(toSpecificationResult);

这里只讨论了同步的请求，异步请求可以参考其[文档][Link 1]。

参考链接：

https://github.com/graphql-java/graphql-java

http://graphql-java.readthedocs.io/en/latest/

[GraphQL Schema]: http://graphql-java.readthedocs.io/en/latest/schema.html
[Link 1]: http://graphql-java.readthedocs.io/en/latest/execution.html#asynchronous-execution