What’s New in Spring GraphQL 1.0? A Deep Dive into Features and Roadmap

Preface

I am pleased to announce the addition of the Spring GraphQL project with the initial 1.0 milestone now available. The project integrates GraphQL Java and Spring, developed collaboratively between the two teams.

1. Introduction

To get started, refer to the reference documentation and read the "Boot Starter" section, or run the samples.

If you are new to GraphQL, many good resources are available, starting with graphql.org/learn .

Based on the InfoQ 2020 architecture trends, GraphQL is widely adopted and in the "Early Majority" stage. It offers a data‑centric alternative to REST APIs and provides a query language for clients. The JavaScript State of the Union report highlights its appeal from a client perspective, and GitHub’s use cases illustrate why they chose GraphQL.

2. Core Support

Spring GraphQL is considered the successor to the GraphQL Java Spring project. The initial focus was to match its functionality and integrate GraphQL Java with Spring in the best possible way. The core support includes:

HTTP handlers – usable with Spring MVC and WebFlux, built on functional endpoint APIs.

WebSocket handlers – based on the graphql‑ws protocol, supporting GraphQL subscription streams.

Web Interception – can intercept each GraphQL request, inspect HTTP headers, and modify the GraphQL ExecutionInput or ExecutionResult.

Boot starter – packages all of the above into a runnable application.

In addition, work has begun on security, testing, and metrics.

3. Security

GraphQL endpoint URLs are, as usual, easy to protect. For finer‑grained security, applications can use Spring Security annotations on data‑fetching methods. This requires the Spring Security context to propagate to those methods; although graphql‑java itself is thread‑agnostic, components involved in execution may be asynchronous and cause thread switches.

This enables the GraphQL engine to add context propagation support from the web‑framework level to data‑fetching components, covering both Spring MVC and WebFlux ThreadLocal and Reactor Context. Once these features are ready, Spring Security works without any additional dedicated integration.

Examples webmvc-http and webflux-security demonstrate Spring Security usage.

4. Exception Handling

Spring GraphQL allows applications to create multiple independent GraphQlExceptionResolver components to resolve GraphQL errors and include them in the response. By default it also provides an ErrorType enum for classifying common error categories such as BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, or INTERNAL_ERROR.

5. Testing

You can test GraphQL requests with WebTestClient by sending and receiving JSON, but GraphQL‑specific details make this approach cumbersome. That is why Spring GraphQL adds WebGraphQlTester, which defines a workflow for testing GraphQL requests. Its advantages include:

Verifying that the GraphQL response returns HTTP 200 (OK).

Checking for unexpected errors under the "error" key.

Decoding the "data" key in the response.

Using JsonPath to decode different parts of the response.

Testing subscriptions.

Examples of using WebGraphQlTester can be found in the samples.

6. Metrics

When the spring-boot-starter-actuator dependency is present, metrics for GraphQL requests are collected, including request counts, DataFetcher execution times, and error numbers.

7. Querydsl Integration

Querydsl provides a flexible, type‑safe way to express query predicates. Spring GraphQL builds on the Spring Data Querydsl extension, allowing easy creation of DataFetchers backed by Querydsl. It prepares a Querydsl Predicate from GraphQL request parameters and uses it to fetch data for JPA, MongoDB, or LDAP.

The webmvc-http example demonstrates Querydsl usage.

8. Schema‑First vs Object‑First

GraphQL offers a schema language that helps clients create valid requests, enables the GraphiQL UI editor, and promotes a common vocabulary across teams. It also raises the classic schema‑vs‑object‑first development dilemma.

Our view is that schema‑first development should be preferred. It aids communication between technical and non‑technical stakeholders, works well with tooling, and makes change tracking easier. A one‑to‑one strong mapping between GraphQL schema and Java types is not required.

Code generation, bootstrapping, and client query creation also have space; frameworks like Netflix DGS support this and can be used alongside Spring GraphQL.

9. Roadmap and Feedback

We plan to achieve the second milestone before SpringOne (Sept 2‑3). Early feedback has already surfaced many M2 issues, including GraphQL client support, BatchLoader registration, and file uploads.

The milestone phase will continue until after Spring Boot 2.6 (November), when the Boot starter is expected to move into the Spring Boot repository and be included in Boot 2.7.

Our goal is a stable API and an RC later this year. We need your feedback—please try it out, create issues, or share insights on our issue tracker.

10. Resources

For more details on Spring GraphQL features, see the reference documentation. The GraphQL Java and Spring teams will present jointly at this year’s SpringOne conference, which will be streamed online for free. Register to attend the talks and interact with speakers and attendees.

Translator’s Note

We will continue to follow and use Spring GraphQL and the broader Spring ecosystem. Follow our public account “JAVA 架构日记” for updates.