8.6.GraphQL

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

启动器	传输方式	底层实现
spring-boot-starter-web	HTTP协议	春季MVC
spring-boot-starter-websocket	WebSocket	用于 Servlet 应用程序的 WebSocket
spring-boot-starter-webflux	HTTP、网络套接字	Spring WebFlux
spring-boot-starter-rsocket	TCP、网络套接字	Reactor Netty 上的 Spring WebFlux

8.6.1. GraphQL Schema

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 模式，定义两种类型和两个查询：

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来禁用自省。

8.6.2. GraphQL 运行时接线

GraphQL JavaRuntimeWiring.Builder可用于注册自定义标量类型、指令、类型解析器DataFetcher等。您可以在 Spring 配置中声明RuntimeWiringConfigurer beans 以访问RuntimeWiring.Builder. Spring Boot 检测此类 bean 并将它们添加到GraphQlSource builder中。

然而，通常情况下，应用程序不会直接实现DataFetcher，而是创建带注释的控制器。Spring Boot 将自动检测带有@Controller注释处理方法的类并将其注册为DataFetcher。以下是我们的问候语查询的@Controller类实现示例：

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

8.6.3. Querydsl 和 QueryByExample 存储库支持

Spring Data 提供对 Querydsl 和 QueryByExample 存储库的支持。Spring GraphQL 可以将 Querydsl 和 QueryByExample 存储库配置为DataFetcher.

Spring Data 存储库注释@GraphQlRepository并扩展以下之一：

• QuerydslPredicateExecutor

• ReactiveQuerydslPredicateExecutor

• QueryByExampleExecutor

• ReactiveQueryByExampleExecutor

由 Spring Boot 检测到并视为DataFetcher匹配顶级查询的候选者。

8.6.4. 传输

HTTP 和 WebSocket

默认情况下，GraphQL HTTP 端点位于 HTTP POST /graphql。可以使用spring.graphql.path 自定义路径。

Spring MVC 和 Spring WebFlux 的 HTTP 端点均由 @Order 为 0 的 RouterFunction bean 提供。如果您定义自己的 RouterFunction bean，则可能需要添加适当的 @Order 注释以确保它们正确排序。

GraphQL WebSocket 端点默认处于关闭状态。要启用它：

• 对于 Servlet 应用程序，添加 WebSocket 启动器spring-boot-starter-websocket

• 对于 WebFlux 应用程序，不需要额外的依赖项

• 对于两者，都必须设置应用程序属性spring.graphql.websocket.path

Spring GraphQL 提供了Web 拦截模型。这对于从 HTTP 请求标头检索信息并将其设置在 GraphQL 上下文中或从同一上下文中获取信息并将其写入响应标头非常有用。使用 Spring Boot，您可以声明一个WebInterceptorbean 以将其注册到 Web 传输。

Spring MVC和Spring WebFlux支持 CORS（跨源资源共享）请求。CORS 是 GraphQL 应用程序 Web 配置的关键部分，可从使用不同域的浏览器访问这些应用程序。

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

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

RSocket

RSocket 还支持作为 WebSocket 或 TCP 之上的传输。配置 RSocket 服务器后，我们可以使用 spring.graphql.rsocket.mapping在特定路由上配置 GraphQL 处理程序。例如，将该映射配置为“graphql”意味着我们可以在使用 RSocketGraphQlClient 发送请求时将其用作路由。

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

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

然后发送请求：

Mono<Book> book = this.graphQlClient.document("{ bookById(id: \"book-1\"){ id name pageCount author } }")
    .retrieve("bookById")
    .toEntity(Book.class);

8.6.5. 异常处理

Spring GraphQL 使应用程序能够注册一个或多个按顺序调用的 Spring DataFetcherExceptionResolver组件。异常必须解析为graphql.GraphQLError对象列表，请参阅Spring GraphQL 异常处理文档。Spring Boot 将自动检测DataFetcherExceptionResolverbean 并将它们注册到GraphQlSource.Builder.

8.6.6. GraphiQL 和 Schema 打印

Spring GraphQL 提供了基础设施来帮助开发人员使用或开发 GraphQL API。

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

您还可以选择在启用spring.graphql.schema.printer.enabled属性，以/graphql/schema文本格式公开 GraphQL Schema 。