Spring for GraphQL

GraphQL アプリケーションを構築する場合は、Spring Boot の Spring for GraphQL の自動構成を利用できます。Spring for GraphQL プロジェクトは GraphQL Java [GitHub] (英語) に基づいています。少なくとも spring-boot-starter-graphql スターターが必要です。GraphQL はトランスポートに依存しないため、GraphQL API を Web 上で公開するには、アプリケーションに 1 つ以上の追加のスターターが必要です。

スタータートランスポート実装

スターター	トランスポート	実装
`spring-boot-starter-web`	HTTP	Spring MVC
`spring-boot-starter-websocket`	WebSocket	サーブレットアプリ用の WebSocket
`spring-boot-starter-webflux`	HTTP、WebSocket	Spring WebFlux
`spring-boot-starter-rsocket`	TCP、WebSocket	Spring WebFlux on Reactor Netty

spring-boot-starter-web

HTTP

Spring MVC

spring-boot-starter-websocket

WebSocket

サーブレットアプリ用の WebSocket

spring-boot-starter-webflux

HTTP、WebSocket

Spring WebFlux

spring-boot-starter-rsocket

TCP、WebSocket

Spring WebFlux on Reactor Netty

GraphQL スキーマ

Spring GraphQL アプリケーションには、起動時に定義済みのスキーマが必要です。デフォルトでは、src/main/resources/graphql/** に ".graphqls" または ".gqls" スキーマファイルを書き込むことができ、Spring Boot はそれらを自動的に取得します。spring.graphql.schema.locations を使用して場所をカスタマイズし、spring.graphql.schema.file-extensions を使用してファイル拡張子をカスタマイズできます。

すべてのアプリケーションモジュール内のスキーマファイルとその場所の依存関係を Spring Boot で検出する場合は、spring.graphql.schema.locations を "classpath*:graphql/**/" に設定できます (classpath*: プレフィックスに注意してください)。

次のセクションでは、このサンプル GraphQL スキーマを検討し、2 つの型と 2 つのクエリを定義します。

type Query {
    greeting(name: String! = "Spring"): String!
    project(slug: ID!): Project
}

""" A Project in the Spring portfolio """
type Project {
    """ Unique string id used in URLs """
    slug: ID!
    """ Project name """
    name: String!
    """ URL of the git repository """
    repositoryUrl: String!
    """ Current support status """
    status: ProjectStatus!
}

enum ProjectStatus {
    """ Actively supported by the Spring team """
    ACTIVE
    """ Supported by the community """
    COMMUNITY
    """ Prototype, not officially supported yet  """
    INCUBATING
    """ Project being retired, in maintenance mode """
    ATTIC
    """ End-Of-Lifed """
    EOL
}

デフォルトでは、GraphiQL などのツールに必要なため、スキーマでフィールドイントロスペクションが許可 (英語) されます。スキーマに関する情報を公開したくない場合は、spring.graphql.schema.introspection.enabled を false に設定することでイントロスペクションを無効にできます。

GraphQL RuntimeWiring

GraphQL Java RuntimeWiring.Builder (英語) は、カスタムスカラー型、ディレクティブ、型リゾルバー、DataFetcher (英語) などを登録するために使用できます。Spring 構成で RuntimeWiringConfigurer (Javadoc) Bean を宣言して、RuntimeWiring.Builder (英語) にアクセスできます。Spring Boot はそのような Bean を検出し、GraphQlSource ビルダーに追加します。

ただし、通常、アプリケーションは DataFetcher (英語) を直接実装せず、代わりにアノテーション付きコントローラーを作成します。Spring Boot は、アノテーション付きハンドラーメソッドを持つ @Controller (Javadoc) クラスを自動的に検出し、DataFetcher として登録します。以下は、@Controller (Javadoc) クラスを使用した挨拶クエリの実装例です。

Java
Kotlin

import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

@Controller
public class GreetingController {

	@QueryMapping
	public String greeting(@Argument String name) {
		return "Hello, " + name + "!";
	}

}

import org.springframework.graphql.data.method.annotation.Argument
import org.springframework.graphql.data.method.annotation.QueryMapping
import org.springframework.stereotype.Controller

@Controller
class GreetingController {

	@QueryMapping
	fun greeting(@Argument name: String): String {
		return "Hello, $name!"
	}

}

Querydsl および QueryByExample リポジトリのサポート

Spring Data は、Querydsl リポジトリと QueryByExample リポジトリの両方をサポートしています。Spring GraphQL は Querydsl および QueryByExample リポジトリを DataFetcher として設定するできます。

@GraphQlRepository (Javadoc) でアノテーションが付けられ、次のいずれかを継承する Spring Data リポジトリ:

Spring Boot によって検出され、トップレベルのクエリに一致する DataFetcher (英語) の候補として考慮されます。

トランスポート

HTTP および WebSocket

GraphQL HTTP エンドポイントは、デフォルトでは HTTP POST /graphql です。また、サブスクリプションのみで Server Sent Events 経由の "text/event-stream" メディア型もサポートしています。パスは spring.graphql.path でカスタマイズできます。

Spring MVC と Spring WebFlux の両方の HTTP エンドポイントは、@Order (Javadoc) が 0 である RouterFunction Bean によって提供されます。独自の RouterFunction Bean を定義する場合は、それらが正しくソートされるように、適切な @Order (Javadoc) アノテーションを追加することをお勧めします。

GraphQL WebSocket エンドポイントはデフォルトでオフになっています。有効にするには:

サーブレットアプリケーションの場合は、WebSocket スターター spring-boot-starter-websocket を追加します
WebFlux アプリケーションの場合、追加の依存関係は必要ありません
どちらの場合も、spring.graphql.websocket.path アプリケーションプロパティを設定する必要があります

Spring GraphQL は Web インターセプトモデルを提供します。これは、HTTP リクエストヘッダーから情報を取得して GraphQL コンテキストに設定したり、同じコンテキストから情報を取得してレスポンスヘッダーに書き込んだりするのに非常に便利です。Spring Boot を使用すると、WebGraphQlInterceptor (Javadoc) Bean を宣言して、Web トランスポートに登録することができます。

Spring MVC および Spring WebFlux は、CORS（クロスオリジンリソースシェアリング）リクエストをサポートします。CORS は、さまざまなドメインを使用するブラウザーからアクセスされる GraphQL アプリケーションの Web 構成の重要な部分です。

Spring Boot は、spring.graphql.cors.* 名前空間で多くの構成プロパティをサポートします。設定例を次に示します。

プロパティ
YAML

spring.graphql.cors.allowed-origins=https://example.org
spring.graphql.cors.allowed-methods=GET,POST
spring.graphql.cors.max-age=1800s

spring:
  graphql:
    cors:
      allowed-origins: "https://example.org"
      allowed-methods: GET,POST
      max-age: 1800s

RSocket

RSocket は、WebSocket または TCP 上のトランスポートとしてもサポートされています。RSocket サーバーが構成されているを使用すると、spring.graphql.rsocket.mapping を使用して特定のルートで GraphQL ハンドラーを構成できます。たとえば、マッピングを "graphql" として構成すると、RSocketGraphQlClient (Javadoc) を使用してリクエストを送信するときにそれをルートとして使用できます。

Spring Boot は、コンポーネントに挿入できる RSocketGraphQlClient.Builder<?> Bean を自動構成します。

Java
Kotlin

@Component
public class RSocketGraphQlClientExample {

	private final RSocketGraphQlClient graphQlClient;

	public RSocketGraphQlClientExample(RSocketGraphQlClient.Builder<?> builder) {
		this.graphQlClient = builder.tcp("example.spring.io", 8181).route("graphql").build();
	}

@Component
class RSocketGraphQlClientExample(private val builder: RSocketGraphQlClient.Builder<*>) {

次に、リクエストを送信します: include-code::RSocketGraphQlClientExample[tag=request]

例外処理

Spring GraphQL を使用すると、アプリケーションは、順番に呼び出される 1 つ以上の Spring DataFetcherExceptionResolver (Javadoc) コンポーネントを登録できます。例外は、GraphQLError (英語) オブジェクトのリストに解決する必要があります ( Spring GraphQL 例外処理ドキュメントを参照)。Spring Boot は、DataFetcherExceptionResolver (Javadoc) Bean を自動的に検出し、GraphQlSource.Builder (Javadoc) に登録します。

GraphiQL とスキーマプリンター

Spring GraphQL は、GraphQLAPI を使用または開発する際に開発者を支援するためのインフラストラクチャーを提供します。

Spring GraphQL には、デフォルトで "/graphiql" で公開されるデフォルトの GraphiQL [GitHub] (英語) ページが付属しています。このページはデフォルトで無効になっており、spring.graphql.graphiql.enabled プロパティでオンにできます。このようなページを公開する多くのアプリケーションは、カスタムビルドを好みます。デフォルトの実装は開発中に非常に役立ちます。これが、開発中に spring-boot-devtools で自動的に公開される理由です。

spring.graphql.schema.printer.enabled プロパティが有効になっている場合は、/graphql/schema で GraphQL スキーマをテキスト形式で公開することもできます。