在Spring GraphQL项目公告和1.0里程碑的可用性之后,本博文旨在提供更多细节。
简介
如果你想开始学习,请到我们的参考文档,阅读 "Boot Starter "部分,或运行案例。
如果你对GraphQL了解不多,有很多好的学习资源。你可以从 graphql.org/learn 开始。
GraphQL被广泛采用,根据2020年的InfoQ架构趋势,它处于 “早期多数”。它为REST APIs提供了一种替代方案,更加关注数据,并提供了一种模式和查询语言供客户端使用。从客户端的角度来看,其吸引力在这份State of JavaScript 报告中很明显。你可以阅读GitHub的故事,了解它为什么使用GraphQL。
基础性支持
正如Andy Marek在开篇博客中写到的,Spring GraphQL是作为GraphQL Java团队的GraphQL Java Spring项目的继承者而设想的。这就是为什么我们合作的最初重点是匹配该功能,以及以最佳方式整合GraphQL Java和Spring。
为此,我们创建了以下基础性支持。:
- HTTP handlers–可用于Spring MVC和WebFlux,建立在WebMvc和WebFlux功能端点API上。
- WebSocket handlers–遵循graphql-ws的协议,支持GraphQL订阅流。
- Web Interception - 能够拦截每个GraphQL请求,检查HTTP头,并修改GraphQL
ExecutionInput
或ExecutionResult
。 - Boot starter–把所有的东西放在一起,变成一个可运行的应用程序。
除此之外,我们开始关注一些关键方面,如安全、测试和指标。
安全问题
GraphQL端点的URL很容易像往常一样安全。对于更细粒度的安全,应用程序可以在数据检索方法上使用Spring Security注释。这需要Spring Security上下文传播到数据检索方法,虽然GraphQL Java是对线程中立,但执行中的组件本身可以是异步的,并导致线程的切换。
这导致我们增加了对上下文传播的支持,从Web框架层面,通过GraphQL引擎,传播到数据获取组件。这包括Spring MVC和WebFlux应用的ThreadLocal
上下文和ReactorContext
。在这些功能到位后,Spring Security就可以工作了,不需要再进行任何专门的整合。
webmvc-http和webflux-security样本演示了Spring Security的使用。
异常处理
Spring GraphQL使应用程序能够创建多个独立的GraphQlExceptionResolver
组件,以解决GraphQL错误的异常,并将其纳入GraphQL响应中。它还提供了一个 "ErrorType "类型,用来对错误进行分类,其常见的类别包括 “BAD_REQUEST”、“UNAUTHORIZED”、“FORBIDDEN”、"NOT_FOUND "或默认的 “INTERNAL_ERROR”。
测试
你可以使用WebTestClient测试GraphQL请求,只需发送和接收JSON。然而,GraphQL的具体细节使这种方法比它应该的更麻烦。
这就是为什么Spring GraphQL包括WebGraphQlTester
,它定义了一个测试GraphQL请求的工作流程。它提供了以下好处。
- 验证GraphQL响应是200(OK)。
- 验证响应中的 “errors” 没有意外的错误。
- 在响应中的 "data"进行解码。
- 使用JsonPath对响应的不同部分进行解码。
- 测试订阅。
所有样本都使用GraphQlTester
.
指标
当启动器spring-boot-starter-actuator
存在时,GraphQL请求的指标被收集,包括请求和DataFetcher
执行计时器,以及一个错误计数器。
Querydsl 整合
Querydsl提供了一种灵活且类型安全的方法来表达查询谓词。Spring GraphQL建立在Spring Data Querydsl扩展的基础上,使其能够轻松创建一个支持Querydsl的DataFetcher
。它从GraphQL请求参数中准备了一个QuerydslPredicate
,并使用它来获取数据,这适用于JPA、MongoDB和LDAP。
webmvc-http样本使用Querydsl。
模式优先 VS 对象优先
GraphQL提供了一种模式语言,帮助客户创建有效的请求,启用GraphiQL UI编辑器,促进各团队之间的共同词汇,等等。这也带来了古老的模式与对象优先开发的两难问题。
我们的看法是,模式优先的开发应该是首选。它促进了技术和非技术背景的人之间的对话,它有助于工具的使用,它使跟踪变化更加容易,等等。GraphQL模式和Java类型之间也没有一一对应的关系。
也就是说,也有代码生成的空间,可以开始使用,客户可以创建查询,等等。像Netflix DGS这样的框架在这方面有很好的支持,可以和Spring GraphQL一起使用。
路线图和反馈信息
我们打算在9月2-3日SpringOne之前有一个第二里程碑。根据早期的反馈,我们已经有一些M2的问题在队列中,包括对GraphQL客户端、BatchLoader注册、文件上传的支持等等。
这个里程碑阶段将持续到11月的Spring Boot 2.6之后,届时Boot启动器将被计划移入Spring Boot仓库,以纳入Boot 2.7中。
我们的目标是拥有稳定的API,并在今年年底进入RC阶段。为了达到这个目标,我们需要你的反馈。请试一试,并创建一个问题,或在我们的问题跟踪器的现有问题下发表评论。
资源
关于Spring GraphQL功能的更多细节,请查看参考文档。
GraphQL Java和Spring团队将在今年的SpringOne会议上联合发表演讲,该会议再次连续两年免费在线举行。请注册参加我们的演讲,并与演讲者和与会者互动。