Spring for GraphQL

如果您想构建 GraphQL 应用程序，您可以利用 Spring Boot 对 {url-spring-graphql-site}[Spring for GraphQL] 的自动配置。Spring for GraphQL 项目基于 GraphQL Java。至少需要 spring-boot-starter-graphql 启动器。由于 GraphQL 与传输无关，因此还需要在应用程序中添加一个或多个启动器，以通过 Web 公开您的 GraphQL API：

If you want to build GraphQL applications, you can take advantage of Spring Boot’s auto-configuration for {url-spring-graphql-site}[Spring for GraphQL]. The Spring for GraphQL project is based on GraphQL Java. You’ll need the spring-boot-starter-graphql starter at a minimum. Because GraphQL is transport-agnostic, you’ll also need to have one or more additional starters in your application to expose your GraphQL API over the web:

Starter Transport Implementation

Starter	Transport	Implementation
`spring-boot-starter-web`	HTTP	Spring MVC
`spring-boot-starter-websocket`	WebSocket	WebSocket for Servlet apps
`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 for Servlet apps

spring-boot-starter-webflux

HTTP, WebSocket

Spring WebFlux

spring-boot-starter-rsocket

TCP, WebSocket

Spring WebFlux on Reactor Netty

GraphQL Schema

Spring GraphQL 应用程序在启动时需要定义一个架构。默认情况下，可以在 src/main/resources/graphql/** 下编写 “.graphqls” 或 “.gqls” 架构文件，Spring Boot 将自动提取它们。您可以使用 configprop:spring.graphql.schema.locations[] 自定义位置，并使用 configprop:spring.graphql.schema.file-extensions[] 自定义文件扩展名。

A Spring GraphQL application requires a defined schema at startup. By default, you can write ".graphqls" or ".gqls" schema files under src/main/resources/graphql/** and Spring Boot will pick them up automatically. You can customize the locations with configprop:spring.graphql.schema.locations[] and the file extensions with configprop:spring.graphql.schema.file-extensions[].

如果您希望 Spring Boot 检测您在应用程序的所有模块和依赖项中的给定位置的架构文件，则可以将 configprop:spring.graphql.schema.locations[] 设置为 "classpath*:graphql/*/" (note the classpath: 前缀）。

If you want Spring Boot to detect schema files in all your application modules and dependencies for that location, you can set configprop:spring.graphql.schema.locations[] to "classpath*:graphql/*/" (note the classpath: prefix).

在以下部分中，我们将考虑此示例 GraphQL 架构，定义两个类型和两个查询：

In the following sections, we’ll consider this sample GraphQL schema, defining two types and two queries:

Unresolved include directive in modules/ROOT/pages/web/spring-graphql.adoc - include::ROOT:example$resources/graphql/schema.graphqls[]

默认情况下， field introspection 将被允许在架构上，因为 GraphiQL 等工具需要它。如果您不希望公开关于架构的信息，则可以通过将 configprop:spring.graphql.schema.introspection.enabled[] 设置为 false 来禁用内省。

By default, field introspection will be allowed on the schema as it is required for tools such as GraphiQL. If you wish to not expose information about the schema, you can disable introspection by setting configprop:spring.graphql.schema.introspection.enabled[] to false.

GraphQL RuntimeWiring

GraphQL Java RuntimeWiring.Builder 可用于注册自定义标量类型、指令、类型解析器、DataFetcher，等等。可在你的 Spring 配置中声明 RuntimeWiringConfigurer bean，以获取对 RuntimeWiring.Builder 的访问权限。Spring Boot 将检测此类 bean 并将它们添加到 {url-spring-graphql-docs}/#execution-graphqlsource[GraphQlSource 生成器]。

The GraphQL Java RuntimeWiring.Builder can be used to register custom scalar types, directives, type resolvers, DataFetcher, and more. You can declare RuntimeWiringConfigurer beans in your Spring config to get access to the RuntimeWiring.Builder. Spring Boot detects such beans and adds them to the {url-spring-graphql-docs}/#execution-graphqlsource[GraphQlSource builder].

然而，通常，应用程序不会直接实现 DataFetcher，而是创建 {url-spring-graphql-docs}/#controllers[带注释的控制器]。Spring Boot 将自动检测有带注释处理程序方法的 @Controller 类，并将这些注册为 DataFetcher`s. Here’s a sample implementation for our greeting query with a `@Controller 类：

Typically, however, applications will not implement DataFetcher directly and will instead create {url-spring-graphql-docs}/#controllers[annotated controllers]. Spring Boot will automatically detect @Controller classes with annotated handler methods and register those as DataFetcher`s. Here’s a sample implementation for our greeting query with a `@Controller class:

Querydsl and QueryByExample Repositories Support

Spring Data 同时提供对 Querydsl 和 QueryByExample 存储库的支持。Spring GraphQL 可以将 {url-spring-graphql-docs}/#data[Querydsl 和 QueryByExample 存储库配置成 DataFetcher]。

Spring Data offers support for both Querydsl and QueryByExample repositories. Spring GraphQL can {url-spring-graphql-docs}/#data[configure Querydsl and QueryByExample repositories as DataFetcher].

带 @GraphQlRepository 注释并扩展下列类之一的 Spring Data 存储库：

Spring Data repositories annotated with @GraphQlRepository and extending one of:

QuerydslPredicateExecutor
ReactiveQuerydslPredicateExecutor
QueryByExampleExecutor
ReactiveQueryByExampleExecutor

将被 Spring Boot 检测，并被视为匹配顶级查询的 DataFetcher 候选。

are detected by Spring Boot and considered as candidates for DataFetcher for matching top-level queries.

Transports

HTTP and WebSocket

默认情况下，GraphQL HTTP 端点位于 HTTP POST /graphql。它还支持仅用于订阅的 Server Sent Events 的 "text/event-stream" 媒体类型。可使用 configprop:spring.graphql.path[] 自定义路径。

The GraphQL HTTP endpoint is at HTTP POST /graphql by default. It also supports the "text/event-stream" media type over Server Sent Events for subscriptions only. The path can be customized with configprop:spring.graphql.path[].

适用于 Spring MVC 和 Spring WebFlux 的 HTTP 端点由具有 RouterFunction 的 @Order 的 0 bean 提供。如果你定义了自己的 RouterFunction bean，你可能想要添加适当的 @Order 注释，以确保它们按正确的顺序进行排序。

The HTTP endpoint for both Spring MVC and Spring WebFlux is provided by a RouterFunction bean with an @Order of 0. If you define your own RouterFunction beans, you may want to add appropriate @Order annotations to ensure that they are sorted correctly.

默认情况下，GraphQL WebSocket 端点已关闭。若要启用它：

The GraphQL WebSocket endpoint is off by default. To enable it:

For a Servlet application, add the WebSocket starter spring-boot-starter-websocket
For a WebFlux application, no additional dependency is required
For both, the configprop:spring.graphql.websocket.path[] application property must be set

Spring GraphQL 提供了 {url-spring-graphql-docs}/#web-interception[Web 拦截] 模型。此功能非常适用于从 HTTP 请求头中检索信息并将其设置在 GraphQL 上下文中，或者从同一上下文获取信息并将其写入响应头。使用 Spring Boot，你可以声明一个 WebInterceptor bean，以将该 bean 注册到 Web 传输中。

Spring GraphQL provides a {url-spring-graphql-docs}/#web-interception[Web Interception] model. This is quite useful for retrieving information from an HTTP request header and set it in the GraphQL context or fetching information from the same context and writing it to a response header. With Spring Boot, you can declare a WebInterceptor bean to have it registered with the web transport.

{url-spring-framework-docs}/web/webmvc-cors.html[Spring MVC] 和 {url-spring-framework-docs}/web/webflux-cors.html[Spring WebFlux] 支持 CORS（跨域资源共享）请求。CORS 是通过不同域使用浏览器访问 GraphQL 应用程序时至关重要的 web 配置部分。

{url-spring-framework-docs}/web/webmvc-cors.html[Spring MVC] and {url-spring-framework-docs}/web/webflux-cors.html[Spring WebFlux] support CORS (Cross-Origin Resource Sharing) requests. CORS is a critical part of the web config for GraphQL applications that are accessed from browsers using different domains.

Spring Boot 支持 spring.graphql.cors.* 命名空间下的许多配置属性；以下是简短的配置示例：

Spring Boot supports many configuration properties under the spring.graphql.cors.* namespace; here’s a short configuration sample:

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

RSocket

RSocket 也可以作为传输，位于 WebSocket 或 TCP 之上。一旦设置 RSocket server is configured，我们就可以使用 configprop:spring.graphql.rsocket.mapping[] 在特定路由上配置 GraphQL 处理程序。例如，将该映射配置为 "graphql" 意味着我们可以在用 RSocketGraphQlClient 发送请求时将其用作路由。

RSocket is also supported as a transport, on top of WebSocket or TCP. Once the RSocket server is configured, we can configure our GraphQL handler on a particular route using configprop:spring.graphql.rsocket.mapping[]. For example, configuring that mapping as "graphql" means we can use that as a route when sending requests with the RSocketGraphQlClient.

Spring Boot 会自动配置一个你可以注入到你的组件中的 RSocketGraphQlClient.Builder<?> bean：

Spring Boot auto-configures a RSocketGraphQlClient.Builder<?> bean that you can inject in your components:

然后发送一个请求：include-code::RSocketGraphQlClientExample[tag=request]

And then send a request: include-code::RSocketGraphQlClientExample[tag=request]

Exception Handling

Spring GraphQL 允许应用程序注册一个或多个 Spring DataFetcherExceptionResolver`组件，这些组件将按顺序调用。异常必须解析为 `graphql.GraphQLError`对象列表，请参阅 {url-spring-graphql-docs}/#execution-exceptions[Spring GraphQL 异常处理文档]。Spring Boot 将自动检测 `DataFetcherExceptionResolver`bean 并将其注册到 `GraphQlSource.Builder。

Spring GraphQL enables applications to register one or more Spring DataFetcherExceptionResolver components that are invoked sequentially. The Exception must be resolved to a list of graphql.GraphQLError objects, see {url-spring-graphql-docs}/#execution-exceptions[Spring GraphQL exception handling documentation]. Spring Boot will automatically detect DataFetcherExceptionResolver beans and register them with the GraphQlSource.Builder.

GraphiQL and Schema printer

Spring GraphQL 为开发人员在消费或开发 GraphQL API 时提供了基础设施。

Spring GraphQL offers infrastructure for helping developers when consuming or developing a GraphQL API.

Spring GraphQL 随附一个默认的 GraphiQL页面，默认情况下在 "/graphiql"`中公开。该页面默认情况下处于禁用状态，可以使用 configprop:spring.graphql.graphiql.enabled[] 属性将其打开。公开此类页面的许多应用程序将更喜欢自定义构建。默认实现对于开发非常有用，这就是为什么它在开发过程中使用 `spring-boot-devtools自动公开的原因。

Spring GraphQL ships with a default GraphiQL page that is exposed at "/graphiql" by default. This page is disabled by default and can be turned on with the configprop:spring.graphql.graphiql.enabled[] property. Many applications exposing such a page will prefer a custom build. A default implementation is very useful during development, this is why it is exposed automatically with spring-boot-devtools during development.

当 configprop:spring.graphql.schema.printer.enabled[] 属性已启用时，您还可以在 `/graphql/schema`中以文本格式公开 GraphQL 模式。

You can also choose to expose the GraphQL schema in text format at /graphql/schema when the configprop:spring.graphql.schema.printer.enabled[] property is enabled.