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 模式,定义两种类型和两个查询:
默认情况下,模式上将允许进行字段自省,因为这是 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
类实现示例:
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,您可以声明一个WebInterceptor
bean 以将其注册到 Web 传输。
Spring MVC和Spring WebFlux支持 CORS(跨源资源共享)请求。CORS 是 GraphQL 应用程序 Web 配置的关键部分,可从使用不同域的浏览器访问这些应用程序。
Spring Boot 支持spring.graphql.cors.*
命名空间下的多种配置属性;这是一个简短的配置示例:
RSocket
RSocket 还支持作为 WebSocket 或 TCP 之上的传输。配置 RSocket 服务器后,我们可以使用 spring.graphql.rsocket.mapping
在特定路由上配置 GraphQL 处理程序。例如,将该映射配置为“graphql”意味着我们可以在使用 RSocketGraphQlClient
发送请求时将其用作路由。
Spring Boot 自动配置一个RSocketGraphQlClient.Builder<?>
可以注入到组件中的 bean:
然后发送请求:
8.6.5. 异常处理
Spring GraphQL 使应用程序能够注册一个或多个按顺序调用的 Spring DataFetcherExceptionResolver
组件。异常必须解析为graphql.GraphQLError
对象列表,请参阅Spring GraphQL 异常处理文档。Spring Boot 将自动检测DataFetcherExceptionResolver
bean 并将它们注册到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 。
最后更新于