preface

I am pleased to announce that we have added the Spring GraphQL project and that the initial 1.0 release milestones are available. The project integrates GraphQL Java and Spring and was developed collaboratively between the two teams.

Today is GraphQL Java’s 6th birthday! A fundamental decision I made from the beginning was to treat any HTTP and IO aspects as separate considerations. GraphQL Java has always been “just” an engine that executes GraphQL requests. The decision paid off, but the obvious downside was the need to create your own HTTP adapter for actual use.

This has led to the creation of a number of GraphQL integrations for Spring over the years, including the GraphQL Java Spring project from the GraphQL Java team. But frankly, I’ve always longed for first-class Spring integration.

Introduce a,

If you want to get started, go to our reference documentation and read the “Boot Starter” section, or run Samples.

If you don’t know much about GraphQL, there are a number of great resources. You can start at graphql.org/learn.

Based on InfoQ 2020 architecture trends, GraphQL is widely adopted and in the “Early Majority”. It provides an alternative to the more data-focused REST API and provides a pattern and a query language for the client to use. In this JavaScript status report, the appeal is clear from the client’s perspective. You can read GitHub’s use case to see why it uses GraphQL.

Second, basic support

Spring GraphQL is considered the successor to the GraphQL Java Spring project of the GraphQL Java team. That’s why our initial collaboration focused on matching this functionality and best integrating GraphQL Java with Spring. To do this, we created the following base support:

  • HTTP Handlers – Available for Spring MVC and WebFlux, built on WebMvc and WebFlux functional endpoint apis.
  • WebSocket Handlers – a protocol from GraphQL-WS that supports GraphQL subscription flows.
  • Web Interception – The ability to intercept each GraphQL request, check the HTTP header, and modify GraphQL ExecutionInput or ExecutionResult.
  • Boot Starter – Put it all together in one running application.

Beyond that, we started to look at the key aspects of security, testing, and metrics.

Third, security

The URL of the GraphQL endpoint is as easy to secure as usual. For more fine-grained security, applications can use Spring security annotations on data retrieval methods. This requires the Spring security context to be propagated to the data retrieval method, and while GraphqlJava is thread-independent, the executing component itself can be asynchronous and cause a thread switch.

This enables us to add support for context propagation to the data retrieval component from the Web framework level through the GraphQL engine. This includes the ThreadLocal Context and Reactor Context for springMVC and WebFlux applications, respectively. With these features in place, Spring Security works without any further specialized integration.

The WebMVC-HTTP and Webflux-Security examples demonstrate the use of Spring Security.

Iv. Exception handling

Spring GraphQL enables applications to create multiple independent GraphQlExceptionResolver components to resolve exceptions to GraphQL errors for inclusion in the GraphQL response. By default, it also provides an ErrorType for classifying errors with common categories, such as BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, or INTERNAL_ERROR.

Five, the test

You can use WebTestClient to test the GraphQL request by simply sending and receiving JSON. However, the specific details of GraphQL make this method more cumbersome than it should be. That’s why Spring GraphQL adds WebGraphQlTester, which defines a workflow for testing GraphQL requests. It has the following advantages:

  • Verify that the GraphQL response is correct 200 (OK).
  • Verify an unexpected error under the “Error” key in the response.
  • Decodes under the “data” key in the response.
  • The different parts of the response are decoded using JsonPath.
  • Test subscriptions.

For an example of using GraphQlTester, see: samples.

6. Metrics

When the Spring-boot-starter – ACTUATOR dependency exists, metrics for GraphQL requests are collected, including request and DataFetcher execution times, and the number of errors.

Querydsl integration

Querydsl provides a flexible and type-safe way to express query predicates. Spring GraphQL builds on The Spring Data Querydsl Extension, making it easy to create DataFetcher supported by Querydsl. It prepares a Querydsl Predicate from the GraphQ L request parameter and uses it to retrieve data, which applies to JPA, MongoDB, and LDAP.

This WebMVC-HTTP example is the Querydsl used.

Schema priority and Object priority

GraphQL provides a Schema language that helps clients create valid requests, enable the GraphiQL UI editor, promote common vocabularies across teams, and more. It also addresses the age-old Schema vs Object first development dilemma.

Our view is that schema should be the first choice for development. It facilitates communication between people with technical and non-technical backgrounds, helps with tools, makes it easier to track changes, and so on. There is also no need for a strong one-to-one mapping between GraphQL Schema and Java types.

That is, there is also room for code generation, start, client creation queries, and so on. Frameworks like Netflix DGS have good support for this and can be used with Spring GraphQL.

9. Roadmap and Feedback

We intend to reach the second milestone before SpringOne on September 2-3. From early feedback, we’ve seen a number of M2 issues in the queue, including support for the GraphQL client, BatchLoader registration, file uploads, etc.

The milestone phase will last until after Spring Boot 2.6 in November, when the Boot Starter is scheduled to move into the Spring Boot repository for inclusion in Boot 2.7.

Our goal is to have a stable API and move into the RC phase later this year. For that, we need your feedback. Try using and creating Issues or Posting your thoughts in our issue Tracker.

Ten, resources,

For more details on The Features of Spring GraphQL, check out the reference documentation. GraphQL Java and the Spring team will be presented jointly at this year’s SpringOne conference, which will again be available for free via live streaming. Please sign up to participate and interact with speakers and attendees.

The translator said

We will also continue to follow and use Spring GraphQL and the Spring ecology as a whole. Please follow us.