【译】Hello, Spring GraphQL

1,224

前言

我很高兴地宣布我们新增了 Spring GraphQL 项目并且 1.0 发布的初始里程碑可用。该项目集成了 GraphQL Java 和 Spring,并在两个团队之间协作开发。

今天是 GraphQL Java 的 6 岁生日!我从一开始所做的一个基本决定是将任何 HTTP 和 IO 方面作为单独的考虑。GraphQL Java 一直“只是”一个执行 GraphQL 请求的引擎。这个决定得到了回报,但明显的缺点是需要为实际使用创建自己的 HTTP 适配器。

这导致多年来为 Spring 创建了大量的 GraphQL 集成,包括来自 GraphQL Java 团队的 GraphQL Java Spring 项目。但坦率地说,我一直渴望一流的 Spring 集成。

一、介绍

如果您想开始使用,请转到我们的 参考文档 并阅读 “Boot Starter” 部分, 或运行 samples

如果您对 GraphQL 不太了解,这里有很多很好的资源。 你可以从 graphql.org/learn 开始。

基于 InfoQ 2020 年 架构趋势 ,GraphQL 被 广泛采用 并处于“Early Majority”。它提供了一种更专注于数据的 REST API 的替代方案,并提供了一种模式和一种供客户端使用的查询语言。 在这份 JavaScript 现状报告 中,从客户端的角度来看,这种吸引力是显而易见的。 你可以阅读 GitHub 的使用案例 ,了解它为什么使用 GraphQL。

二、基础支持

Spring GraphQL 被认为是 GraphQL Java 团队的 GraphQL Java Spring 项目的继承者。 这就是为什么我们最初的合作重点是匹配该功能以及以最佳方式集成 GraphQL Java 和 Spring。 为此,我们创建了以下基础支持:

  • HTTP handlers – 可用于 Spring MVC 和 WebFlux,建立在 WebMvcWebFlux 功能性端点 API。
  • WebSocket handlers – 来自 graphql-ws 的协议,支持 GraphQL 订阅流。
  • Web Interception – 能够拦截每个 GraphQL 请求、检查 HTTP 标头以及修改 GraphQL ExecutionInput 或 ExecutionResult.
  • Boot starter – 将所有这些放在一个可运行的应用程序中。

除此之外,我们开始研究 security、测试和 metrics 等关键方面。

三、安全

GraphQL 端点的 URL 像往常一样易于保护。为了获得更细粒度的安全性,应用程序可以在数据检索方法上使用 Spring 安全性注释。这需要 Spring 安全上下文传播到数据检索方法,虽然 graphqljava 与线程无关,但执行中的组件本身可以是异步的,并导致线程切换。

这使我们能够通过 GraphQL 引擎,从 Web 框架级别向数据获取组件添加对上下文传播的支持。这分别包括 springmvc 和 WebFlux 应用程序的 ThreadLocal 上下文和 Reactor Context。在这些特性就绪之后,Spring Security 就可以工作,而不需要任何进一步的专门集成。

webmvc-httpwebflux-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).
  • 验证响应中 “error” key 下的意外错误。
  • 在响应中的 “data” key 下解码。
  • 使用 JsonPath 对响应的不同部分进行解码。
  • 测试订阅。

所以的使用GraphQlTester 的示例请见: samples

六、Metrics 指标

当 spring-boot-starter-actuator 依赖存在时, 会收集 GraphQL 请求的指标, 包括请求和 DataFetcher 执行时间以及错误数。

七、Querydsl 集成

Querydsl 提供了一种灵活且类型安全的方法来表达查询谓词。Spring GraphQL 建立在 Spring Data Querydsl extension 之上,可以轻松创建由 Querydsl 支持的 DataFetcher。 它从 GraphQ L 请求参数准备一个 Querydsl Predicate,并使用它来获取数 据,这适用于 JPA、MongoDB 和 LDAP。

这个 webmvc-http 示例就是使用的 Querydsl。

八、Schema 优先与 Object 优先

GraphQL 提供了一种 schema 语言,可以帮助客户机创建有效的请求、启用 GraphiQL UI 编辑器、跨团队提升通用词汇表,等等。它还提出了古老的 schema vs object 优先的开发困境。

我们的观点是,应该首选 schema 优先开发。它有助于技术和非技术背景人员之间的沟通,有助于使用工具,更容易跟踪更改,等等。GraphQL schema 和 Java 类型之间也不需要一对一的强映射。

也就是说,代码生成、开始、客户端创建查询等也有空间。 像 Netflix DGS 这样的框架对此有很好的支持,可以与 Spring GraphQL 一起使用。

九、Roadmap 和 Feedback

我们打算在 9 月 2 日至 3 日的 SpringOne 之前实现第二个里程碑。 从早期的反馈中,我们已经在队列中发现了许多 M2的问题,包括对 GraphQL 客户端的支持、BatchLoader 注册、文件上传等。

里程碑阶段将持续到 11 月 Spring Boot 2.6 之后,届时 Boot starter 计划移入 Spring Boot 存储库,以包含在 Boot 2.7 中。

我们的目标是拥有稳定的 API,并在今年晚些时候进入 RC 阶段。 为此,我们需要您的反馈。 请尝试一下使用和创建 issues 或是在我们的 issue tracker 中发表自己的见解。

十、资源

有关 Spring GraphQL 功能的更多细节, 请查看 参考文档 . GraphQL Java 和 Spring 团队将在今年的 SpringOne 大会上联合展示,该大会将再次通过线上直播免费参与。请注册参加我们的演讲并与演讲者和参会者互动。

译者说

我们也会持续关注和使用 Spring GraphQL 和整个 Spring 生态,欢迎关注我们。