Spring for GraphQL Documentation

1. Overview

Spring for GraphQL provides support for Spring applications built on GraphQL Java. It is a joint collaboration between both teams. Our shared philosophy is to be less opinionated and more focused on comprehensive and wide-ranging support.

Spring for GraphQL is the successor of the GraphQL Java Spring project from the GraphQL Java team. It aims to be the foundation for all Spring, GraphQL applications.

The project is in a milestone phase towards a 1.0 release, currently, and looking for feedback. Please, use our issue tracker to report a problem, discuss a design issue, or request a feature.

To get started, check the Spring GraphQL starter on start.spring.io and the Samples sections.

2. Requirements

Spring for GraphQL requires the following as a baseline:

JDK8
Spring Framework 5.3
GraphQL Java 17
Spring Data 2021.1.0 or later for QueryDSL or Query by Example

3. Web Transports

Spring for GraphQL supports GraphQL requests over HTTP and over WebSocket.

3.1. HTTP

GraphQlHttpHandler handles GraphQL over HTTP requests and delegates to the Web Interception chain for request execution. There are two variants, one for Spring MVC and one for Spring WebFlux. Both handle requests asynchronously and have equivalent functionality, but rely on blocking vs non-blocking I/O respectively for writing the HTTP response.

Requests must use HTTP POST with GraphQL request details included as JSON in the request body, as defined in the proposed GraphQL over HTTP specification. Once the JSON body has been successfully decoded, the HTTP response status is always 200 (OK), and any errors from GraphQL request execution appear in the "errors" section of the GraphQL response.

GraphQlHttpHandler can be exposed as an HTTP endpoint by declaring a RouterFunction bean and using the RouterFunctions from Spring MVC or WebFlux to create the route. The Boot starter does this, see the Web Endpoints section for details, or check GraphQlWebMvcAutoConfiguration or GraphQlWebFluxAutoConfiguration it contains, for the actual config.

The Spring for GraphQL repository contains a Spring MVC HTTP sample application.

3.2. WebSocket

GraphQlWebSocketHandler handles GraphQL over WebSocket requests based on the protocol defined in the graphql-ws library. The main reason to use GraphQL over WebSocket is subscriptions which allow sending a stream of GraphQL responses, but it can also be used for regular queries with a single response. The handler delegates every request to the Web Interception chain for further request execution.

GraphQL Over WebSocket Protocols

There are two such protocols, one in the subscriptions-transport-ws library and another in the graphql-ws library. The former is not active and succeeded by the latter. Read this blog post for the history.

There are two variants of GraphQlWebSocketHandler, one for Spring MVC and one for Spring WebFlux. Both handle requests asynchronously and have equivalent functionality. The WebFlux handler also uses non-blocking I/O and back pressure to stream messages, which works well since in GraphQL Java a subscription response is a Reactive Streams Publisher.

The graphql-ws project lists a number of recipes for client use.

GraphQlWebSocketHandler can be exposed as a WebSocket endpoint by declaring a SimpleUrlHandlerMapping bean and using it to map the handler to a URL path. The Boot starter has options to enable this, see the Web Endpoints section for details, or check GraphQlWebMvcAutoConfiguration or GraphQlWebFluxAutoConfiguration it contains, for the actual config.

The Spring for GraphQL repository contains a WebFlux WebSocket sample application.

3.3. Web Interception

HTTP and WebSocket transport handlers delegate to a common Web interception chain for request execution. The chain consists of a sequence of WebGraphQlHandlerInterceptor components, followed by a ExecutionGraphQlService that invokes GraphQL Java.

WebGraphQlHandlerInterceptor is as a common contract to use in both Spring MVC and WebFlux applications. Use it to intercept requests, inspect HTTP request headers, or to register a transformation of the graphql.ExecutionInput:

class MyInterceptor implements WebGraphQlHandlerInterceptor {

    @Override
    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) {
        request.configureExecutionInput((executionInput, builder) -> {
            Map<String, Object> map = ... ;
            return builder.extensions(map).build();
        });
        return chain.next(request);
    }
}

Use WebGraphQlHandlerInterceptor also to intercept responses, add HTTP response headers, or transform the graphql.ExecutionResult:

class MyInterceptor implements WebGraphQlHandlerInterceptor {

    @Override
    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) {
        return chain.next(request)
                .map(response -> {
                    Object data = response.getData();
                    Object updatedData = ... ;
                    return response.transform(builder -> builder.data(updatedData));
                });
    }
}

WebGraphQlHandler provides a builder to initialize the Web interception chain. After you build the chain, you can use the resulting WebGraphQlHandler to initialize the HTTP or WebSocket transport handlers. The Boot starter configures all this, see the Web Endpoints section for details, or check GraphQlWebMvcAutoConfiguration or GraphQlWebFluxAutoConfiguration it contains, for the actual config.

4. Request Execution

ExecutionGraphQlService is the main Spring abstraction to call GraphQL Java to execute requests. Underlying transports, such as the Web Transports, delegate to ExecutionGraphQlService to handle requests.

The main implementation, DefaultExecutionGraphQlService, is configured with a GraphQlSource for access to the graphql.GraphQL instance to invoke.

4.1. `GraphQLSource`

GraphQlSource is a core Spring abstraction for access to the graphql.GraphQL instance to use for request execution. It provides a builder API to initialize GraphQL Java and build a GraphQlSource.

The default GraphQlSource builder, accessible via GraphQlSource.builder(), enables support for Reactive DataFetcher, Context Propagation, and Exception Resolution.

The Spring Boot starter initializes a GraphQlSource instance through the default GraphQlSource.Builder and also enables the following:

Load schema files from a configurable location.
Expose properties that apply to GraphQlSource.Builder.
Detect RuntimeWiringConfigurer beans.
Detect Instrumentation beans for GraphQL metrics.
Detect DataFetcherExceptionResolver beans for exception resolution.

For further customizations, you can declare your own GraphQlSourceBuilderCustomizer beans; for example, for configuring your own ExecutionIdProvider:

@Configuration(proxyBeanMethods = false)
class GraphQlConfig {

    @Bean
    public GraphQlSourceBuilderCustomizer sourceBuilderCustomizer() {
        return (builder) -> {
            builder.configureGraphQl(graphQlBuilder ->
                graphQlBuilder.executionIdProvider(new CustomExecutionIdProvider()));
        };
    }
}

4.1.1. Schema Resources

GraphQlSource.Builder can be configured with one or more Resource instances to be parsed and merged together. That means schema files can be loaded from just about any location.

By default, the Spring Boot starter finds schema files from a well-known classpath location, but you can change that to a location on the file system via FileSystemResource, to byte content via ByteArrayResource, or implement a custom Resource that loads schema files from a remote location or storage.

4.1.2. Schema Creation

By default, GraphQlSource.Builder uses the GraphQL Java GraphQLSchemaGenerator to create the graphql.schema.GraphQLSchema. This works for most applications, but if necessary, you can hook into the schema creation through the builder:

GraphQlSource.Builder builder = ...

builder.schemaResources(..)
        .configureRuntimeWiring(..)
        .schemaFactory((typeDefinitionRegistry, runtimeWiring) -> {
            // create GraphQLSchema
        })

The primary reason for this is to create the schema through a federation library.

The GraphQlSource section explains how to configure that with Spring Boot.

4.1.3. `RuntimeWiringConfigurer`

You can use RuntimeWiringConfigurer to register:

Custom scalar types.
Directives handling code.
TypeResolver, if you need to override the Default TypeResolver for a type.
DataFetcher for a field, although most applications will simply configure AnnotatedControllerConfigurer, which detects annotated, DataFetcher handler methods. The Spring Boot starter adds the AnnotatedControllerConfigurer by default.

Unlike web frameworks, GraphQL does not use Jackson annotations to drive JSON serialization/deserialization. Custom data types and their serialization must be described as Scalars.

The Spring Boot starter detects beans of type RuntimeWiringConfigurer and registers them in the GraphQlSource.Builder. That means in most cases, you’ll' have something like the following in your configuration:

@Configuration
public class GraphQlConfig {

    @Bean
    public RuntimeWiringConfigurer runtimeWiringConfigurer(BookRepository repository) {

        GraphQLScalarType scalarType = ... ;
        SchemaDirectiveWiring directiveWiring = ... ;
        DataFetcher dataFetcher = QuerydslDataFetcher.builder(repository).single();

        return wiringBuilder -> wiringBuilder
                .scalar(scalarType)
                .directiveWiring(directiveWiring)
                .type("Query", builder -> builder.dataFetcher("book", dataFetcher));
    }
}

If you need to add a WiringFactory, e.g. to make registrations that take into account schema definitions, implement the alternative configure method that accepts both the RuntimeWiring.Builder and an output List<WiringFactory>. This allows you to add any number of factories that are then invoked in sequence.

4.1.4. Default `TypeResolver`

GraphQlSource.Builder registers ClassNameTypeResolver as the default TypeResolver to use for GraphQL Interfaces and Unions that don’t already have such a registration through a RuntimeWiringConfigurer. The purpose of a TypeResolver in GraphQL Java is to determine the GraphQL Object type for values returned from the DataFetcher for a GraphQL Interface or Union field.

ClassNameTypeResolver tries to match the simple class name of the value to a GraphQL Object Type and if it is not successful, it also navigates its super types including base classes and interfaces, looking for a match. ClassNameTypeResolver provides an option to configure a name extracting function along with Class to GraphQL Object type name mappings that should help to cover more corner cases:

GraphQlSource.Builder builder = ...
ClassNameTypeResolver classNameTypeResolver = new ClassNameTypeResolver();
classNameTypeResolver.setClassNameExtractor((klass) -> {
    // Implement Custom ClassName Extractor here
});
builder.defaultTypeResolver(classNameTypeResolver);

The GraphQlSource section explains how to configure that with Spring Boot.

4.1.5. Operation Caching

GraphQL Java must parse and validate an operation before executing it. This may impact performance significantly. To avoid the need to re-parse and validate, an application may configure a PreparsedDocumentProvider that caches and reuses Document instances. The GraphQL Java docs provide more details on query caching through a PreparsedDocumentProvider.

In Spring GraphQL you can register a PreparsedDocumentProvider through GraphQlSource.Builder#configureGraphQl: .

// Typically, accessed through Spring Boot's GraphQlSourceBuilderCustomizer
GraphQlSource.Builder builder = ...

// Create provider
PreparsedDocumentProvider provider = ...

builder.schemaResources(..)
        .configureRuntimeWiring(..)
        .configureGraphQl(graphQLBuilder -> graphQLBuilder.preparsedDocumentProvider(provider))

The GraphQlSource section explains how to configure that with Spring Boot.

4.1.6. Directives

The GraphQL language supports directives that "describe alternate runtime execution and type validation behavior in a GraphQL document". Directives are similar to annotations in Java but declared on types, fields, fragments and operations in a GraphQL document.

GraphQL Java provides the SchemaDirectiveWiring contract to help applications detect and handle directives. For more details, see Schema Directives in the GraphQL Java documentation.

In Spring GraphQL you can register a SchemaDirectiveWiring through a RuntimeWiringConfigurer. The Spring Boot starter detects such beans, so you might have something like:

@Configuration
public class GraphQlConfig {

    @Bean
    public RuntimeWiringConfigurer runtimeWiringConfigurer() {
        return builder -> builder.directiveWiring(new MySchemaDirectiveWiring());
    }

}

For an example of directives support check out the Extended Validation for Graphql Java library.

4.2. Reactive `DataFetcher`

The default GraphQlSource builder enables support for a DataFetcher to return Mono or Flux which adapts those to a CompletableFuture where Flux values are aggregated and turned into a List, unless the request is a GraphQL subscription request, in which case the return value remains a Reactive Streams Publisher for streaming GraphQL responses.

A reactive DataFetcher can rely on access to Reactor context propagated from the transport layer, such as from a WebFlux request handling, see WebFlux Context.

4.3. Context Propagation

Spring for GraphQL provides support to transparently propagate context from the Web Transports, through GraphQL Java, and to DataFetcher and other components it invokes. This includes both ThreadLocal context from the Spring MVC request handling thread and Reactor Context from the WebFlux processing pipeline.

4.3.1. WebMvc

A DataFetcher and other components invoked by GraphQL Java may not always execute on the same thread as the Spring MVC handler, for example if an asynchronous WebGraphQlHandlerInterceptor or DataFetcher switches to a different thread.

Spring for GraphQL supports propagating ThreadLocal values from the Servlet container thread to the thread a DataFetcher and other components invoked by GraphQL Java to execute on. To do this, an application needs to create a ThreadLocalAccessor to extract ThreadLocal values of interest:

public class RequestAttributesAccessor implements ThreadLocalAccessor {

    private static final String KEY = RequestAttributesAccessor.class.getName();

    @Override
    public void extractValues(Map<String, Object> container) {
        container.put(KEY, RequestContextHolder.getRequestAttributes());
    }

    @Override
    public void restoreValues(Map<String, Object> values) {
        if (values.containsKey(KEY)) {
            RequestContextHolder.setRequestAttributes((RequestAttributes) values.get(KEY));
        }
    }

    @Override
    public void resetValues(Map<String, Object> values) {
        RequestContextHolder.resetRequestAttributes();
    }

}

A ThreadLocalAccessor can be registered in the WebGraphHandler builder. The Boot starter detects beans of this type and automatically registers them for Spring MVC application, see the Web Endpoints section.

4.3.2. WebFlux

A Reactive DataFetcher can rely on access to Reactor context that originates from the WebFlux request handling chain. This includes Reactor context added by WebGraphQlHandlerInterceptor components.

4.4. Exception Resolution

GraphQL Java applications can register a DataFetcherExceptionHandler to decide how to represent exceptions from the data layer in the "errors" section of the GraphQL response.

Spring for GraphQL has a built-in DataFetcherExceptionHandler that is configured for use by the GraphQLSource builder. It enables applications to register one or more Spring DataFetcherExceptionResolver components that are invoked sequentially until one resolves the Exception to a list of graphql.GraphQLError objects.

DataFetcherExceptionResolver is an asynchronous contract. For most implementations, it would be sufficient to extend DataFetcherExceptionResolverAdapter and override one of its resolveToSingleError or resolveToMultipleErrors methods that resolve exceptions synchronously.

A GraphQLError can be assigned an graphql.ErrorClassification. Spring for GraphQL defines an ErrorType enum with common, error classification categories:

BAD_REQUEST
UNAUTHORIZED
FORBIDDEN
NOT_FOUND
INTERNAL_ERROR

Applications can use this to classify errors. If an error remains unresolved, by default it is marked as INTERNAL_ERROR.

4.5. Batch Loading

Given a Book and its Author, we can create one DataFetcher for a book and another for its author. This allows selecting books with or without authors, but it means books and authors aren’t loaded together, which is especially inefficient when querying multiple books as the author for each book is loaded individually. This is known as the N+1 select problem.

4.5.1. `DataLoader`

GraphQL Java provides a DataLoader mechanism for batch loading of related entities. You can find the full details in the GraphQL Java docs. Below is a summary of how it works:

Register DataLoader's in the DataLoaderRegistry that can load entities, given unique keys.
DataFetcher's can access DataLoader's and use them to load entities by id.
A DataLoader defers loading by returning a future so it can be done in a batch.
DataLoader's maintain a per request cache of loaded entities that can further improve efficiency.

4.5.2. `BatchLoaderRegistry`

The complete batching loading mechanism in GraphQL Java requires implementing one of several BatchLoader interface, then wrapping and registering those as DataLoaders with a name in the DataLoaderRegistry.

The API in Spring GraphQL is slightly different. For registration, there is only one, central BatchLoaderRegistry exposing factory methods and a builder to create and register any number of batch loading functions:

@Configuration
public class MyConfig {

    public MyConfig(BatchLoaderRegistry registry) {

        registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
            // return Mono<Map<Long, Author>
        });

        // more registrations ...
    }

}

The Spring Boot starter declares a BatchLoaderRegistry bean that you can inject into your configuration, as shown above, or into any component such as a controller in order register batch loading functions. In turn the BatchLoaderRegistry is injected into DefaultExecutionGraphQlService where it ensures DataLoader registrations per request.

By default, the DataLoader name is based on the class name of the target entity. This allows an @SchemaMapping method to declare a DataLoader argument with a generic type, and without the need for specifying a name. The name, however, can be customized through the BatchLoaderRegistry builder, if necessary, along with other DataLoader options.

For many cases, when loading related entities, you can use @BatchMapping controller methods, which are a shortcut for and replace the need to use BatchLoaderRegistry and DataLoader directly. s BatchLoaderRegistry provides other important benefits too. It supports access to the same GraphQLContext from batch loading functions and from @BatchMapping methods, as well as ensures Context Propagation to them. This is why applications are expected to use it. It is possible to perform your own DataLoader registrations directly but such registrations would forgo the above benefits.

4.5.3. Testing Batch Loading

Start by having BatchLoaderRegistry perform registrations on a DataLoaderRegistry:

BatchLoaderRegistry batchLoaderRegistry = new DefaultBatchLoaderRegistry();
// perform registrations...

DataLoaderRegistry dataLoaderRegistry = DataLoaderRegistry.newRegistry().build();
batchLoaderRegistry.registerDataLoaders(dataLoaderRegistry, graphQLContext);

Now you can access and test individual DataLoader's as follows:

DataLoader<Long, Book> loader = dataLoaderRegistry.getDataLoader(Book.class.getName());
loader.load(1L);
loader.loadMany(Arrays.asList(2L, 3L));
List<Book> books = loader.dispatchAndJoin(); // actual loading

assertThat(books).hasSize(3);
assertThat(books.get(0).getName()).isEqualTo("...");
// ...

5. Data Integration

Spring for GraphQL lets you leverage existing Spring technology, following common programming models to expose underlying data sources through GraphQL.

This section discusses an integration layer for Spring Data that provides an easy way to adapt a Querydsl or a Query by Example repository to a DataFetcher, including the option for automated detection and GraphQL Query registration for repositories marked with @GraphQlRepository.

5.1. Querydsl

Spring for GraphQL supports use of Querydsl to fetch data through the Spring Data Querydsl extension. Querydsl provides a flexible yet typesafe approach to express query predicates by generating a meta-model using annotation processors.

For example, declare a repository as QuerydslPredicateExecutor:

public interface AccountRepository extends Repository<Account, Long>,
            QuerydslPredicateExecutor<Account> {
}

Then use it to create a DataFetcher:

// For single result queries
DataFetcher<Account> dataFetcher =
        QuerydslDataFetcher.builder(repository).single();

// For multi-result queries
DataFetcher<Iterable<Account>> dataFetcher =
        QuerydslDataFetcher.builder(repository).many();

You can now register the above DataFetcher through a RuntimeWiringConfigurer.

The DataFetcher builds a Querydsl Predicate from GraphQL request parameters, and uses it to fetch data. Spring Data supports QuerydslPredicateExecutor for JPA, MongoDB, and LDAP.

If the repository is ReactiveQuerydslPredicateExecutor, the builder returns DataFetcher<Mono<Account>> or DataFetcher<Flux<Account>>. Spring Data supports this variant for MongoDB.

5.1.1. Build Setup

To configure Querydsl in your build, follow the official reference documentation:

For example:

Gradle

dependencies {
    //...

    annotationProcessor "com.querydsl:querydsl-apt:$querydslVersion:jpa",
            'org.hibernate.javax.persistence:hibernate-jpa-2.1-api:1.0.2.Final',
            'javax.annotation:javax.annotation-api:1.3.2'
}

compileJava {
    options.annotationProcessorPath = configurations.annotationProcessor
}

Maven

<dependencies>
    <!-- ... -->
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <version>${querydsl.version}</version>
        <classifier>jpa</classifier>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.hibernate.javax.persistence</groupId>
        <artifactId>hibernate-jpa-2.1-api</artifactId>
        <version>1.0.2.Final</version>
    </dependency>
    <dependency>
        <groupId>javax.annotation</groupId>
        <artifactId>javax.annotation-api</artifactId>
        <version>1.3.2</version>
    </dependency>
</dependencies>
<plugins>
    <!-- Annotation processor configuration -->
    <plugin>
        <groupId>com.mysema.maven</groupId>
        <artifactId>apt-maven-plugin</artifactId>
        <version>${apt-maven-plugin.version}</version>
        <executions>
            <execution>
                <goals>
                    <goal>process</goal>
                </goals>
                <configuration>
                    <outputDirectory>target/generated-sources/java</outputDirectory>
                    <processor>com.querydsl.apt.jpa.JPAAnnotationProcessor</processor>
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>

The webmvc-http sample uses Querydsl for artifactRepositories.

5.1.2. Customizations

QuerydslDataFetcher supports customizing how GraphQL arguments are bound onto properties to create a Querydsl Predicate. By default, arguments are bound as "is equal to" for each available property. To customize that, you can use QuerydslDataFetcher builder methods to provide a QuerydslBinderCustomizer.

A repository may itself be an instance of QuerydslBinderCustomizer. This is auto-detected and transparently applied during Auto-Registration. However, when manually building a QuerydslDataFetcher you will need to use builder methods to apply it.

QuerydslDataFetcher supports interface and DTO projections to transform query results before returning these for further GraphQL processing.

To learn what projections are, please refer to the Spring Data docs. To understand how to use projections in GraphQL, please see Selection Set vs Projections.

To use Spring Data projections with Querydsl repositories, create either a projection interface or a target DTO class and configure it through the projectAs method to obtain a DataFetcher producing the target type:

class Account {

    String name, identifier, description;

    Person owner;
}

interface AccountProjection {

    String getName();

    String getIdentifier();
}

// For single result queries
DataFetcher<AccountProjection> dataFetcher =
        QuerydslDataFetcher.builder(repository).projectAs(AccountProjection.class).single();

// For multi-result queries
DataFetcher<Iterable<AccountProjection>> dataFetcher =
        QuerydslDataFetcher.builder(repository).projectAs(AccountProjection.class).many();

5.1.3. Auto-Registration

If a repository is annotated with @GraphQlRepository, it is automatically registered for queries that do not already have a registered DataFetcher and whose return type matches that of the repository domain type. This includes both single value and multi-value queries.

By default, the name of the GraphQL type returned by the query must match the simple name of the repository domain type. If needed, you can use the typeName attribute of @GraphQlRepository to specify the target GraphQL type name.

Auto-registration detects if a given repository implements QuerydslBinderCustomizer and transparently applies that through QuerydslDataFetcher builder methods.

Auto-registration is performed through a built-in RuntimeWiringConfigurer that can be obtained from QuerydslDataFetcher. The Boot starter automatically detects @GraphQlRepository beans and uses them to initialize the RuntimeWiringConfigurer with.

Auto-registration does not support customizations. If you need that, you’ll need to use QueryByExampleDataFetcher to build and register the DataFetcher manually through a RuntimeWiringConfigurer.

5.2. Query by Example

Spring Data supports the use of Query by Example to fetch data. Query by Example (QBE) is a simple querying technique that does not require you to write queries through store-specific query languages.

Start by declaring a repository that is QueryByExampleExecutor:

public interface AccountRepository extends Repository<Account, Long>,
            QueryByExampleExecutor<Account> {
}

Use QueryByExampleDataFetcher to turn the repository into a DataFecher:

// For single result queries
DataFetcher<Account> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).single();

// For multi-result queries
DataFetcher<Iterable<Account>> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).many();

You can now register the above DataFetcher through a RuntimeWiringConfigurer.

The DataFetcher uses the GraphQL arguments map to create the domain type of the repository and use that as the example object to fetch data with. Spring Data supports QueryByExampleDataFetcher for JPA, MongoDB, Neo4j, and Redis.

If the repository is ReactiveQueryByExampleExecutor, the builder returns DataFetcher<Mono<Account>> or DataFetcher<Flux<Account>>. Spring Data supports this variant for MongoDB, Neo4j, Redis, and R2dbc.

5.2.1. Build Setup

Query by Example is already included in the Spring Data modules for the data stores where it is supported, so no extra setup is required to enable it.

5.2.2. Customizations

QueryByExampleDataFetcher supports interface and DTO projections to transform query results before returning these for further GraphQL processing.

To learn what projections are, please refer to the Spring Data documentation. To understand the role of projections in GraphQL, please see Selection Set vs Projections.

To use Spring Data projections with Query by Example repositories, create either a projection interface or a target DTO class and configure it through the projectAs method to obtain a DataFetcher producing the target type:

class Account {

    String name, identifier, description;

    Person owner;
}

interface AccountProjection {

    String getName();

    String getIdentifier();
}

// For single result queries
DataFetcher<AccountProjection> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).projectAs(AccountProjection.class).single();

// For multi-result queries
DataFetcher<Iterable<AccountProjection>> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).projectAs(AccountProjection.class).many();

5.2.3. Auto-Registration

Auto-registration is performed through a built-in RuntimeWiringConfigurer that can be obtained from QueryByExampleDataFetcher. The Boot starter automatically detects @GraphQlRepository beans and uses them to initialize the RuntimeWiringConfigurer with.

5.3. Selection Set vs Projections

A common question that arises is, how GraphQL selection sets compare to Spring Data projections and what role does each play?

The short answer is that Spring for GraphQL is not a data gateway that translates GraphQL queries directly into SQL or JSON queries. Instead, it lets you leverage existing Spring technology and does not assume a one for one mapping between the GraphQL schema and the underlying data model. That is why client-driven selection and server-side transformation of the data model can play complementary roles.

To better understand, consider that Spring Data promotes domain-driven (DDD) design as the recommended approach to manage complexity in the data layer. In DDD, it is important to adhere to the constraints of an aggregate. By definition an aggregate is valid only if loaded in its entirety, since a partially loaded aggregate may impose limitations on aggregate functionality.

In Spring Data you can choose whether you want your aggregate be exposed as is, or whether to apply transformations to the data model before returning it as a GraphQL result. Sometimes it’s enough to do the former, and by default the Querydsl and the Query by Example integrations turn the GraphQL selection set into property path hints that the underlying Spring Data module uses to limit the selection.

In other cases, it’s useful to reduce or even transform the underlying data model in order to adapt to the GraphQL schema. Spring Data supports this through Interface and DTO Projections.

Interface projections define a fixed set of properties to expose where properties may or may not be null, depending on the data store query result. There are two kinds of interface projections both of which determine what properties to load from the underlying data source:

Closed interface projections are helpful if you cannot partially materialize the aggregate object, but you still want to expose a subset of properties.
Open interface projections leverage Spring’s @Value annotation and SpEL expressions to apply lightweight data transformations, such as concatenations, computations, or applying static functions to a property.

DTO projections offer a higher level of customization as you can place transformation code either in the constructor or in getter methods.

DTO projections materialize from a query where the individual properties are determined by the projection itself. DTO projections are commonly used with full-args constructors (e.g. Java records), and therefore they can only be constructed if all required fields (or columns) are part of the database query result.

6. Annotated Controllers

Spring for GraphQL provides an annotation-based programming model where @Controller components use annotations to declare handler methods with flexible method signatures to fetch the data for specific GraphQL fields. For example:

@Controller
public class GreetingController {

        @QueryMapping (1)
        public String hello() { (2)
            return "Hello, world!";
        }

}

1	Bind this method to a query, i.e. a field under the Query type.
2	Determine the query from the method name if not declared on the annotation.

Spring for GraphQL uses RuntimeWiring.Builder to register the above handler method as a graphql.schema.DataFetcher for the query named "hello".

6.1. Declaration

You can define @Controller beans as standard Spring bean definitions. The @Controller stereotype allows for auto-detection, aligned with Spring general support for detecting @Controller and @Component classes on the classpath and auto-registering bean definitions for them. It also acts as a stereotype for the annotated class, indicating its role as a data fetching component in a GraphQL application.

AnnotatedControllerConfigurer detects @Controller beans and registers their annotated handler methods as DataFetchers via RuntimeWiring.Builder. It is an implementation of RuntimeWiringConfigurer which can be added to GraphQlSource.Builder. The Spring Boot starter automatically declares AnnotatedControllerConfigurer as a bean and adds all RuntimeWiringConfigurer beans to GraphQlSource.Builder and that enables support for annotated DataFetchers, see the GraphQL RuntimeWiring section in the Boot starter documentation.

6.2. `@SchemaMapping`

The @SchemaMapping annotation maps a handler method to a field in the GraphQL schema and declares it to be the DataFetcher for that field. The annotation can specify the parent type name, and the field name:

@Controller
public class BookController {

    @SchemaMapping(typeName="Book", field="author")
    public Author getAuthor(Book book) {
        // ...
    }
}

The @SchemaMapping annotation can also leave out those attributes, in which case the field name defaults to the method name, while the type name defaults to the simple class name of the source/parent object injected into the method. For example, the below defaults to type "Book" and field "author":

@Controller
public class BookController {

    @SchemaMapping
    public Author author(Book book) {
        // ...
    }
}

The @SchemaMapping annotation can be declared at the class level to specify a default type name for all handler methods in the class.

@Controller
@SchemaMapping(typeName="Book")
public class BookController {

    // @SchemaMapping methods for fields of the "Book" type

}

@QueryMapping, @MutationMapping, and @SubscriptionMapping are meta annotations that are themselves annotated with @SchemaMapping and have the typeName preset to Query, Mutation, or Subscription respectively. Effectively, these are shortcut annotations for fields under the Query, Mutation, and Subscription types respectively. For example:

@Controller
public class BookController {

    @QueryMapping
    public Book bookById(@Argument Long id) {
        // ...
    }

    @MutationMapping
    public Book addBook(@Argument BookInput bookInput) {
        // ...
    }

    @SubscriptionMapping
    public Flux<Book> newPublications() {
        // ...
    }
}

@SchemaMapping handler methods have flexible signatures and can choose from a range of method arguments and return values..

6.2.1. Method Signature

Schema mapping handler methods can have any of the following method arguments:

Method Argument Description

Method Argument	Description
`@Argument`	For access to a named field argument bound to a higher-level, typed Object. See `@Argument`.
`@Arguments`	For access to all field arguments bound to a higher-level, typed Object. See `@Arguments`.
`@ProjectedPayload` Interface	For access to field arguments through a project interface. See `@ProjectedPayload` Interface.
Source	For access to the source (i.e. parent/container) instance of the field. See Source.
`DataLoader`	For access to a `DataLoader` in the `DataLoaderRegistry`. See `DataLoader`.
`@ContextValue`	For access to a value from the localContext, if it is an instance of `GraphQLContext`, or from the `GraphQLContext` of `DataFetchingEnvironment`.
`GraphQLContext`	For access to the context from the `DataFetchingEnvironment`.
`java.security.Principal`	Obtained from the Spring Security context, if available.
`@AuthenticationPrincipal`	For access to `Authentication#getPrincipal()` from the Spring Security context.
`DataFetchingFieldSelectionSet`	For access to the selection set for the query through the `DataFetchingEnvironment`.
`Locale`, `Optional<Locale>`	For access to the `Locale` from the `DataFetchingEnvironment`.
`DataFetchingEnvironment`	For direct access to the underlying `DataFetchingEnvironment`.

@Argument

For access to a named field argument bound to a higher-level, typed Object. See @Argument.

@Arguments

For access to all field arguments bound to a higher-level, typed Object. See @Arguments.

@ProjectedPayload Interface

For access to field arguments through a project interface. See @ProjectedPayload Interface.

Source

For access to the source (i.e. parent/container) instance of the field. See Source.

DataLoader

For access to a DataLoader in the DataLoaderRegistry. See DataLoader.

@ContextValue

For access to a value from the localContext, if it is an instance of GraphQLContext, or from the GraphQLContext of DataFetchingEnvironment.

GraphQLContext

For access to the context from the DataFetchingEnvironment.

java.security.Principal

Obtained from the Spring Security context, if available.

@AuthenticationPrincipal

For access to Authentication#getPrincipal() from the Spring Security context.

DataFetchingFieldSelectionSet

For access to the selection set for the query through the DataFetchingEnvironment.

Locale, Optional<Locale>

For access to the Locale from the DataFetchingEnvironment.

DataFetchingEnvironment

For direct access to the underlying DataFetchingEnvironment.

Schema mapping handler methods can return any value, including Reactor Mono and Flux as described in Reactive DataFetcher.

6.2.2. `@Argument`

In GraphQL Java, DataFetchingEnvironment provides access to a map of field-specific argument values. The values can be simple scalar values (e.g. String, Long), a Map of values for more complex input, or a List of values.

Use the @Argument annotation to have an argument bound to a target object and injected into the handler method. Binding is performed by mapping argument values to a primary data constructor of the expected method parameter type, or by using a default constructor to create the object and then map argument values to its properties. This is repeated recursively, using all nested argument values and creating nested target objects accordingly. For example:

@Controller
public class BookController {

    @QueryMapping
    public Book bookById(@Argument Long id) {
        // ...
    }

    @MutationMapping
    public Book addBook(@Argument BookInput bookInput) {
        // ...
    }
}

By default, if the method parameter name is available (requires the -parameters compiler flag with Java 8+ or debugging info from the compiler), it is used to look up the argument. If needed, you can customize the name through the annotation, e.g. @Argument("bookInput").

The @Argument annotation does not have a "required" flag, nor the option to specify a default value. Both of these can be specified at the GraphQL schema level and are enforced by GraphQL Java.

If binding fails, a BindException is raised with binding issues accumulated as field errors where the field of each error is the argument path where the issue occurred.

You can use @Argument on a Map<String, Object> argument, to obtain all argument values. The name attribute on @Argument must not be set.

6.2.3. `@Arguments`

Use the @Arguments annotation, if you want to bind the full arguments map onto a single target Object, in contrast to @Argument, which binds a specific, named argument.

For example, @Argument BookInput bookInput uses the value of the argument "bookInput" to initialize BookInput, while @Arguments uses the full arguments map and in that case, top-level arguments are bound to BookInput properties.

6.2.4. `@Argument(s)` Validation

If a Bean Validation Validator (or typically, a LocalValidatorFactoryBean) bean is present in the application context, the AnnotatedControllerConfigurer will auto-detect it and configure support for validation. Controller arguments annotated with @Valid and @Validated are then validated before method invocation.

Bean Validation lets you declare constraints on types, as the following example shows:

public class BookInput {

    @NotNull
    private String title;

    @NotNull
    @Size(max=13)
    private String isbn;
}

We can then mark our argument for validation with @Valid:

@Controller
public class BookController {

    @MutationMapping
    public Book addBook(@Argument @Valid BookInput bookInput) {
        // ...
    }
}

If an error occurs during validation, a ConstraintViolationException is thrown and can be later resolved with a custom DataFetcherExceptionResolver.

Unlike Spring MVC, handler method signatures do not support the injection of BindingResult for reacting to validation errors: those are globally dealt with as exceptions.

6.2.5. `@ProjectedPayload` Interface

As an alternative to using complete Objects with @Argument, you can also use a projection interface to access GraphQL request arguments through a well-defined, minimal interface. Argument projections are provided by Spring Data’s Interface projections when Spring Data is on the class path.

To make use of this, create an interface annotated with @ProjectedPayload and declare it as a controller method parameter. If the parameter is annotated with @Argument, it applies to an individual argument within the DataFetchingEnvironment.getArguments() map. When declared without @Argument, the projection works on top-level arguments in the complete arguments map.

For example:

@Controller
public class BookController {

    @QueryMapping
    public Book bookById(BookIdProjection bookId) {
        // ...
    }

    @MutationMapping
    public Book addBook(@Argument BookInputProjection bookInput) {
        // ...
    }
}

@ProjectedPayload
interface BookIdProjection {

    Long getId();
}

@ProjectedPayload
interface BookInputProjection {

    String getName();

    @Value("#{target.author + ' ' + target.name}")
    String getAuthorAndName();
}

6.2.6. Source

In GraphQL Java, the DataFetchingEnvironment provides access to the source (i.e. parent/container) instance of the field. To access this, simply declare a method parameter of the expected target type.

@Controller
public class BookController {

    @SchemaMapping
    public Author author(Book book) {
        // ...
    }
}

The source method argument also helps to determine the type name for the mapping. If the simple name of the Java class matches the GraphQL type, then there is no need to explicitly specify the type name in the @SchemaMapping annotation.

A @BatchMapping handler method can batch load all authors for a query, given a list of source/parent books objects.

6.2.7. `DataLoader`

When you register a batch loading function for an entity, as explained in Batch Loading, you can access the DataLoader for the entity by declaring a method argument of type DataLoader and use it to load the entity:

@Controller
public class BookController {

    public BookController(BatchLoaderRegistry registry) {
        registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
            // return Map<Long, Author>
        });
    }

    @SchemaMapping
    public CompletableFuture<Author> author(Book book, DataLoader<Long, Author> loader) {
        return loader.load(book.getAuthorId());
    }

}

By default, BatchLoaderRegistry uses the full class name of the value type (e.g. the class name for Author) for the key of the registration, and therefore simply declaring the DataLoader method argument with generic types provides enough information to locate it in the DataLoaderRegistry. As a fallback, the DataLoader method argument resolver will also try the method argument name as the key but typically that should not be necessary.

Note that for many cases with loading related entities, where the @SchemaMapping simply delegates to a DataLoader, you can reduce boilerplate by using a @BatchMapping method as described in the next section.

6.3. `@BatchMapping`

Batch Loading addresses the N+1 select problem through the use of an org.dataloader.DataLoader to defer the loading of individual entity instances, so they can be loaded together. For example:

@Controller
public class BookController {

    public BookController(BatchLoaderRegistry registry) {
        registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
            // return Map<Long, Author>
        });
    }

    @SchemaMapping
    public CompletableFuture<Author> author(Book book, DataLoader<Long, Author> loader) {
        return loader.load(book.getAuthorId());
    }

}

For the straight-forward case of loading an associated entity, shown above, the @SchemaMapping method does nothing more than delegate to the DataLoader. This is boilerplate that can be avoided with a @BatchMapping method. For example:

@Controller
public class BookController {

    @BatchMapping
    public Mono<Map<Book, Author>> author(List<Book> books) {
        // ...
    }
}

The above becomes a batch loading function in the BatchLoaderRegistry where keys are Book instances and the loaded values their authors. In addition, a DataFetcher is also transparently bound to the author field of the type Book, which simply delegates to the DataLoader for authors, given its source/parent Book instance.

To be used as a unique key, Book must implement hashcode and equals.

By default, the field name defaults to the method name, while the type name defaults to the simple class name of the input List element type. Both can be customized through annotation attributes. The type name can also be inherited from a class level @SchemaMapping.

6.3.1. Method Signature

Batch mapping methods support the following arguments:

Method Argument Description

Method Argument	Description
`List<K>`	The source/parent objects.
`java.security.Principal`	Obtained from Spring Security context, if available.
`@ContextValue`	For access to a value from the `GraphQLContext` of `BatchLoaderEnvironment`, which is the same context as the one from the `DataFetchingEnvironment`.
`GraphQLContext`	For access to the context from the `BatchLoaderEnvironment`, which is the same context as the one from the `DataFetchingEnvironment`.
`BatchLoaderEnvironment`	The environment that is available in GraphQL Java to a `org.dataloader.BatchLoaderWithContext`.

List<K>

The source/parent objects.

java.security.Principal

Obtained from Spring Security context, if available.

@ContextValue

For access to a value from the GraphQLContext of BatchLoaderEnvironment, which is the same context as the one from the DataFetchingEnvironment.

GraphQLContext

For access to the context from the BatchLoaderEnvironment, which is the same context as the one from the DataFetchingEnvironment.

BatchLoaderEnvironment

The environment that is available in GraphQL Java to a org.dataloader.BatchLoaderWithContext.

Batch mapping methods can return:

Return Type Description

Return Type	Description
`Mono<Map<K,V>>`	A map with parent objects as keys, and batch loaded objects as values.
`Flux<V>`	A sequence of batch loaded objects that must be in the same order as the source/parent objects passed into the method.
`Map<K,V>`, `List<V>`	Imperative variants, e.g. without remote calls to make.

Mono<Map<K,V>>

A map with parent objects as keys, and batch loaded objects as values.

Flux<V>

A sequence of batch loaded objects that must be in the same order as the source/parent objects passed into the method.

Map<K,V>, List<V>

Imperative variants, e.g. without remote calls to make.

7. Security

The path to a Web GraphQL endpoint can be secured with HTTP URL security to ensure that only authenticated users can access it. This does not, however, differentiate among different GraphQL requests on such a shared endpoint on a single URL.

To apply more fine-grained security, add Spring Security annotations such as @PreAuthorize or @Secured to service methods involved in fetching specific parts of the GraphQL response. This should work due to Context Propagation that aims to make Security, and other context, available at the data fetching level.

The Spring for GraphQL repository contains samples for Spring MVC and for WebFlux.

8. Client

Spring for GraphQL includes client support for executing GraphQL requests over HTTP or over WebSocket.

8.1. `GraphQlClient`

GraphQlClient defines a common workflow for executing GraphQL requests and subscriptions that is independent of and agnostic to the underlying transport. To create an instance, you’ll need to start from either the HttpGraphQlClient or the WebSocketGraphQlClient extensions.

The main purpose of a GraphQlClient extension is to provide a transport specific Builder. There is also a common Builder in GraphQlClient with configuration options that apply to any extension.

8.1.1. HTTP

HttpGraphQlClient uses WebClient to execute GraphQL requests over HTTP.

WebClient webClient = ... ;
HttpGraphQlClient graphQlClient = HttpGraphQlClient.create(webClient);

The HttpGraphQlClient extension is nothing but a GraphQlClient with a specialized builder. Once created, it exposes the same workflow for request execution that is independent of the underlying transport.

This means you can only configure HTTP request details at build time, and those apply to all requests through that client instance. To change HTTP request details, use mutate() on an existing HttpGraphQlClient to create another instance with different configuration:

WebClient webClient = ... ;

HttpGraphQlClient graphQlClient = HttpGraphQlClient.builder(webClient)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

// Perform requests with graphQlClient...

HttpGraphQlClient anotherGraphQlClient = graphQlClient.mutate()
        .headers(headers -> headers.setBasicAuth("peter", "..."))
        .build();

// Perform requests with anotherGraphQlClient...

8.1.2. WebSocket

WebSocketGraphQlClient uses WebSocketClient from Spring WebFlux to execute GraphQL requests over WebSocket:

String url = "http://localhost:8080/graphql";
WebSocketClient client = new ReactorNettyWebSocketClient();

WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client).build();

Once created, WebSocketGraphQlClient exposes the same transport agnostic workflow for request execution as any GrahQlClient. To change any transport details, use mutate() on an existing WebSocketGraphQlClient to create another with different configuration:

URI url = ... ;
WebSocketClient client = ... ;

WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

// Use graphQlClient...

WebSocketGraphQlClient anotherGraphQlClient = graphQlClient.mutate()
        .headers(headers -> headers.setBasicAuth("peter", "..."))
        .build();

// Use anotherGraphQlClient...

Connection

A connection is established transparently when requests are made. There is only one shared, active connection at a time. If the connection is lost, it is re-established on the next request.

WebSocketGraphQlClient also exposes lifecycle methods:

start() - connect the WebSocket and initialize the GraphQL session. This can be used on startup up to be ready for requests, but it is not required.
stop() - cancels ongoing requests and subscriptions, and closes the connection. A stopped client rejects new requests. Use start() to re-establish the connection and allow requests again.

Interceptor

The GraphQL over WebSocket protocol defines a number of connection oriented messages in addition to executing requests. For example, a client sends "connection_init" and the server responds with "connection_ack" at the start of a connection.

For WebSocket transport specific interception, you can create a WebSocketGraphQlClientInterceptor:

static class MyInterceptor implements WebSocketGraphQlClientInterceptor {

    @Override
    public Mono<Object> connectionInitPayload() {
        // ... the "connection_init" payload to send
    }

    @Override
    public Mono<Void> handleConnectionAck(Map<String, Object> ackPayload) {
        // ... the "connection_ack" payload received
    }

}

Register the above interceptor as any other GraphQlClientInterceptor and use it also to intercept GraphQL requests, but note there can be at most one interceptor of type WebSocketGraphQlClientInterceptor.

8.1.3. Builder

GraphQlClient defines a parent Builder with common configuration options for the builders of all extensions. Currently, it has lets you configure:

DocumentSource strategy to load the document for a request from a file
Interception of executed requests

8.2. Requests

Once you have a GraphQlClient, you can begin to perform requests via retrieve() or execute() where the former is only a shortcut for the latter.

8.2.1. Retrieve

The below retrieves and decodes the data for a query:

String document = "{" +
        "  project(slug:\"spring-framework\") {" +
        "   name" +
        "   releases {" +
        "     version" +
        "   }"+
        "  }" +
        "}";

Mono<Project> projectMono = graphQlClient.document(document) (1)
        .retrieve("project") (2)
        .toEntity(Project.class); (3)

1	The operation to perform.
2	The path under the "data" key in the response map to decode from.
3	Decode the data at the path to the target type.

The input document is a String that could be a literal or produced through a code generated request object. You can also define documents in files and use a Document Source to resole them by file name.

The path is relative to the "data" key and uses a simple dot (".") separated notation for nested fields with optional array indices for list elements, e.g. "project.name" or "project.releases[0].version".

Decoding can result in FieldAccessException if the given path is not present, or the field value is null and has an error. FieldAccessException provides access to the response and the field:

Mono<Project> projectMono = graphQlClient.document(document)
        .retrieve("project")
        .toEntity(Project.class)
        .onErrorResume(FieldAccessException.class, ex -> {
            ClientGraphQlResponse response = ex.getResponse();
            // ...
            ResponseField field = ex.getField();
            // ...
        });

8.2.2. Execute

Retrieve is only a shortcut to decode from a single path in the response map. For more control, use the execute method and handle the response:

For example:

Mono<Project> projectMono = graphQlClient.document(document)
        .execute()
        .map(response -> {
            if (!response.isValid()) {
                // Request failure... (1)
            }

            ResponseField field = response.field("project");
            if (!field.hasValue()) {
                if (field.getError() != null) {
                    // Field failure... (2)
                }
                else {
                    // Optional field set to null... (3)
                }
            }

            return field.toEntity(Project.class); (4)
        });

1	The response does not have data, only errors
2	Field that is `null` and has an associated error
3	Field that was set to `null` by its `DataFetcher`
4	Decode the data at the given path

8.2.3. Document Source

The document for a request is a String that may be defined in a local variable or constant, or it may be produced through a code generated request object.

Alternatively, you can also keep documents in files with extensions .graphql or ` .gql`, on the classpath or anywhere else, and refer to those by file name. For example, given:

src/main/resources/graphql/project.graphql

query projectReleases($slug: ID!) {
    project(slug: $slug) {
        name
        releases {
            version
        }
    }
}

You can then:

Mono<Project> projectMono = graphQlClient.documentName("project") (1)
        .variable("slug", "spring-framework") (2)
        .retrieve()
        .toEntity(Project.class);

1	Load the document from "project.graphql"
2	Provide variable values.

The "JS GraphQL" plugin for IntelliJ supports GraphQL query files with code completion.

You can use the GraphQlClient Builder to customize the DocumentSource for loading documents by names.

8.3. Subscription Requests

GraphQlClient can execute subscriptions over transports that support it. Currently, only the WebSocket transport supports GraphQL streams, so you’ll need to create a WebSocketGraphQlClient.

8.3.1. Retrieve

To start a subscription stream, use retrieveSubscription which is similar to retrieve for a single response but returning a stream of responses, each decoded to some data:

Flux<String> greetingFlux = client.document("subscription { greetings }")
        .retrieveSubscription("greeting")
        .toEntity(String.class);

A subscription stream may end with:

SubscriptionErrorException if the server ends the subscription with an explicit "error" message that contains one or more GraphQL errors. The exception provides access to the GraphQL errors decoded from that message.
GraphQlTransportException such as WebSocketDisconnectedException if the underlying connection is closed or lost in which case you can use the retry operator to reestablish the connection and start the subscription again.

8.3.2. Execute

Retrieve is only a shortcut to decode from a single path in each response map. For more control, use the executeSubscription method and handle each response directly:

Flux<String> greetingFlux = client.document("subscription { greetings }")
        .executeSubscription()
        .map(response -> {
            if (!response.isValid()) {
                // Request failure...
            }

            ResponseField field = response.field("project");
            if (!field.hasValue()) {
                if (field.getError() != null) {
                    // Field failure...
                }
                else {
                    // Optional field set to null... (3)
                }
            }

            return field.toEntity(String.class)
        });

8.4. Interception

You create a GraphQlClientInterceptor to intercept all requests through a client:

static class MyInterceptor implements GraphQlClientInterceptor {

    @Override
    public Mono<ClientGraphQlResponse> intercept(ClientGraphQlRequest request, Chain chain) {
        // ...
        return chain.next(request);
    }

    @Override
    public Flux<ClientGraphQlResponse> interceptSubscription(ClientGraphQlRequest request, SubscriptionChain chain) {
        // ...
        return chain.next(request);
    }

}

Once the interceptor is created, register it through the client builder:

URI url = ... ;
WebSocketClient client = ... ;

WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client)
        .interceptor(new MyInterceptor())
        .build();

9. Testing

Spring for GraphQL provides dedicated support for testing GraphQL requests over HTTP or WebSocket, and for testing GraphQL requests executed directly against a server.

To make use of this, add spring-graphql-test to your build:

Gradle

dependencies {
    // ...
    testImplementation 'org.springframework.graphql:spring-graphql-test:1.0.0-M6'
}

Maven

<dependencies>
    <!-- ... -->
    <dependency>
        <groupId>org.springframework.graphql</groupId>
        <artifactId>spring-graphql-test</artifactId>
        <version>1.0.0-M6</version>
        <scope>test</scope>
    </dependency>
</dependencies>

9.1. `GraphQlTester`

GraphQlTester defines a common workflow for testing GraphQL requests. It is independent of and agnostic to the underlying transport. To create an instance, you’ll need to choose a specific GraphQlTester extension as a starting point.

To test with a client sending requests to a server over a transport, use the HTTP or the WebSocket GraphQlTester extensions. For server side tests, executed without any client, use the GraphQlService or the WebGraphQlHandler extensions.

The main purpose of a GraphQlTester extension is to provide a transport specific Builder. There is also a Builder in GraphQlTester with common configuration options that apply to any extension.

9.1.1. HTTP

HttpGraphQlTester uses WebTestClient to execute GraphQL requests over HTTP, with or without a live server, depending on how WebTestClient is configured.

To test in Spring WebFlux, without a live server, point to your Spring configuration that declares the GraphQL HTTP endpoint:

ApplicationContext context = ... ;

WebTestClient client =
        WebTestClient.bindToApplicationContext(context)
                .configureClient()
                .baseUrl("/graphql")
                .build();

HttpGraphQlTester tester = HttpGraphQlTester.create(client);

To test in Spring MVC, without a live server, do the same using MockMvcWebTestClient:

ApplicationContext context = ... ;

WebTestClient client =
        MockMvcWebTestClient.bindToApplicationContext(context)
                .configureClient()
                .baseUrl("/graphql")
                .build();

HttpGraphQlTester tester = HttpGraphQlTester.create(client);

Or to test against a live server running on a port:

WebTestClient client =
        WebTestClient.bindToServer()
                .baseUrl("http://localhost:8080/graphql")
                .build();

HttpGraphQlTester tester = HttpGraphQlTester.create(client);

The HttpGraphQlTester extension is nothing but a GraphQlTester with a specialized builder. Once created, it exposes the same workflow for testing requests that is independent of the underlying transport.

This means you can only configure HTTP request details at build time, and those apply to all requests through that Tester instance. To change HTTP request details, use mutate() on an existing HttpGraphQlTester to create another instance with different configuration:

HttpGraphQlTester tester = HttpGraphQlTester.builder(clientBuilder)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

// Use tester...

HttpGraphQlTester anotherTester = tester.mutate()
        .headers(headers -> headers.setBasicAuth("peter", "..."))
        .build();

// Use anotherTester...

9.1.2. WebSocket

WebSocketGraphQlTester uses WebSocketClient from Spring WebFlux to execute GraphQL requests over WebSocket:

String url = "http://localhost:8080/graphql";
WebSocketClient client = new ReactorNettyWebSocketClient();

WebSocketGraphQlTester tester = WebSocketGraphQlTester.builder(url, client).build();

Once created, WebSocketGraphQlTester exposes the same transport agnostic workflow for request execution as any GrahQlTeste. To change any transport details, use mutate() on an existing WebSocketGraphQlTester to create another with different configuration:

URI url = ... ;
WebSocketClient client = ... ;

WebSocketGraphQlTester tester = WebSocketGraphQlTester.builder(url, client)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

// Use tester...

WebSocketGraphQlTester anotherTester = tester.mutate()
        .headers(headers -> headers.setBasicAuth("peter", "..."))
        .build();

// Use anotherTester...

WebSocketGraphQlTester provides a stop() method that you can use to have the WebSocket connection closed, e.g. after a test runs.

9.1.3. `GraphQlService`

Many times it’s enough to test GraphQL requests on the server side, without the use of a client to send requests over a transport protocol. To test directly against a ExecutionGraphQlService, use the GraphQlServiceTester extension:

GraphQlService service = ... ;
GraphQlServiceTester tester = GraphQlServiceTester.create(service);

9.1.4. `WebGraphQlHandler`

The GraphQlService extension lets you test on the server side, without a client. However, in some cases it’s useful to involve server side transport handling with given mock transport input.

The WebGraphQlHandlerTester extension lets you processes request through the WebGraphQlHandlerInterceptor chain before handing off to ExecutionGraphQlService for request execution:

WebGraphQlHandler handler = ... ;
WebGraphQlHandlerTester tester = WebGraphQlHandlerTester.create(handler);

The builder for this extension allows you to define HTTP request details:

WebGraphQlHandler handler = ... ;

WebGraphQlHandlerTester tester = WebGraphQlHandlerTester.builder(handler)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

9.1.5. Builder

GraphQlTester defines a parent Builder with common configuration options for the builders of all extensions. It lets you configure the following:

errorFilter - a predicate to suppress expected errors, so you can inspect the data of the response.
documentSource - a strategy for loading the document for a request from a file on the classpath or from anywhere else.
responseTimeout - how long to wait for request execution to complete before timing out.

9.2. Requests

Once you have a GraphQlTester, you can begin to test requests. The below executes a query for a project and uses JsonPath to extract project release versions from the response:

String document = "{" +
        "  project(slug:\"spring-framework\") {" +
        "   releases {" +
        "     version" +
        "   }"+
        "  }" +
        "}";

graphQlTester.document(document)
        .execute()
        .path("project.releases[*].version")
        .entityList(String.class)
        .hasSizeGreaterThan(1);

The JsonPath is relative to the "data" section of the response.

You can also create document files with extensions .graphql or .gql under "graphql/" on the classpath and refer to them by file name. For example, given a file called projectReleases.graphql in src/main/resources/graphql, with content:

query projectReleases($slug: ID!) {
    project(slug: $slug) {
        releases {
            version
        }
    }
}

You can then use:

graphQlTester.documentName("projectReleases") (1)
        .variable("slug", "spring-framework") (2)
        .execute()
        .path("project.releases[*].version")
        .entityList(String.class)
        .hasSizeGreaterThan(1);

1	Refer to the document in the file named "project".
2	Set the `slug` variable.

The "JS GraphQL" plugin for IntelliJ supports GraphQL query files with code completion.

If a request does not have any response data, e.g. mutation, use executeAndVerify instead of execute to verify there are no errors in the response:

graphQlTester.query(query).executeAndVerify();

See Errors for more details on error handling.

9.3. Subscriptions

To test subscriptions, call executeSubscription instead of execute to obtain a stream of responses and then use StepVerifier from Project Reactor to inspect the stream:

Flux<String> greetingFlux = tester.document("subscription { greetings }")
        .executeSubscription()
        .toFlux("greetings", String.class);  // decode at JSONPath

StepVerifier.create(greetingFlux)
        .expectNext("Hi")
        .expectNext("Bonjour")
        .expectNext("Hola")
        .verifyComplete();

Subscriptions are supported only with WebSocketGraphQlTester, or with the server side GraphQlService and WebGraphQlHandler extensions.

9.4. Errors

When you use verify(), any errors under the "errors" key in the response will cause an assertion failure. To suppress a specific error, use the error filter before verify():

graphQlTester.query(query)
        .execute()
        .errors()
        .filter(error -> ...)
        .verify()
        .path("project.releases[*].version")
        .entityList(String.class)
        .hasSizeGreaterThan(1);

You can register an error filter at the builder level, to apply to all tests:

WebGraphQlTester graphQlTester = WebGraphQlTester.builder(client)
        .errorFilter(error -> ...)
        .build();

If you want to verify that an error does exist, and in contrast to filter, throw an assertion error if it doesn’t, then use exepect instead:

graphQlTester.query(query)
        .execute()
        .errors()
        .expect(error -> ...)
        .verify()
        .path("project.releases[*].version")
        .entityList(String.class)
        .hasSizeGreaterThan(1);

You can also inspect all errors through a Consumer, and doing so also marks them as filtered, so you can then also inspect the data in the response:

graphQlTester.query(query)
        .execute()
        .errors()
        .satisfy(errors -> {
            // ...
        });

10. Samples

This Spring for GraphQL repository contains sample applications for various scenarios.

You can run those by cloning this repository and running main application classes from your IDE or by typing the following on the command line:

$ ./gradlew :samples:{sample-directory-name}:bootRun

Spring for GraphQL Documentation

1. Overview

2. Requirements

3. Web Transports

3.1. HTTP

3.2. WebSocket

3.3. Web Interception

4. Request Execution

4.1. GraphQLSource

4.1.1. Schema Resources

4.1.2. Schema Creation

4.1.3. RuntimeWiringConfigurer

4.1.4. Default TypeResolver

4.1.5. Operation Caching

4.1.6. Directives

4.2. Reactive DataFetcher

4.3. Context Propagation

4.3.1. WebMvc

4.3.2. WebFlux

4.4. Exception Resolution

4.5. Batch Loading

4.5.1. DataLoader

4.5.2. BatchLoaderRegistry

4.5.3. Testing Batch Loading

5. Data Integration

5.1. Querydsl

5.1.1. Build Setup

5.1.2. Customizations

5.1.3. Auto-Registration

5.2. Query by Example

5.2.1. Build Setup

5.2.2. Customizations

5.2.3. Auto-Registration

5.3. Selection Set vs Projections

6. Annotated Controllers

6.1. Declaration

6.2. @SchemaMapping

6.2.1. Method Signature

6.2.2. @Argument

6.2.3. @Arguments

6.2.4. @Argument(s) Validation

6.2.5. @ProjectedPayload Interface

6.2.6. Source

6.2.7. DataLoader

6.3. @BatchMapping

6.3.1. Method Signature

7. Security

8. Client

8.1. GraphQlClient

8.1.1. HTTP

8.1.2. WebSocket

Connection

Interceptor

8.1.3. Builder

8.2. Requests

8.2.1. Retrieve

8.2.2. Execute

8.2.3. Document Source

8.3. Subscription Requests

8.3.1. Retrieve

8.3.2. Execute

8.4. Interception

9. Testing

9.1. GraphQlTester

9.1.1. HTTP

9.1.2. WebSocket

9.1.3. GraphQlService

9.1.4. WebGraphQlHandler

9.1.5. Builder

9.2. Requests

9.3. Subscriptions

9.4. Errors

10. Samples

4.1. `GraphQLSource`

4.1.3. `RuntimeWiringConfigurer`

4.1.4. Default `TypeResolver`

4.2. Reactive `DataFetcher`

4.5.1. `DataLoader`

4.5.2. `BatchLoaderRegistry`

6.2. `@SchemaMapping`

6.2.2. `@Argument`

6.2.3. `@Arguments`

6.2.4. `@Argument(s)` Validation

6.2.5. `@ProjectedPayload` Interface

6.2.7. `DataLoader`

6.3. `@BatchMapping`

8.1. `GraphQlClient`

9.1. `GraphQlTester`

9.1.3. `GraphQlService`

9.1.4. `WebGraphQlHandler`