在 Spring GraphQL 项目宣布以及 1.0 里程碑版本发布之后，本博客文章旨在提供更多详细信息。

引言

如果您想快速入门，请前往我们的参考文档，阅读“Boot Starter”部分，或运行示例。

如果您对 GraphQL 知之甚少，有很多不错的资源。您可以从graphql.org/learn开始学习。

GraphQL 已被广泛采用，并且根据 InfoQ 2020 年的架构趋势，它处于“早期多数”阶段。它提供了一种替代 REST API 的方案，更侧重于数据，并为客户端提供 schema 和查询语言。从客户端的角度来看，这种吸引力在 State of JavaScript 报告中显而易见。您可以阅读GitHub 的故事，了解它为何使用 GraphQL。

基础支持

正如 Andy Marek 在开篇博客中所写，Spring GraphQL 被构想为 GraphQL Java 团队的 GraphQL Java Spring 项目的继任者。这就是为什么我们最初的合作重点是匹配其功能，并以最佳方式集成 GraphQL Java 和 Spring。

为此，我们创建了以下基础支持：

• HTTP 处理程序 -- 同时支持 Spring MVC 和 WebFlux，构建在 WebMvc 和 WebFlux 功能端点 API 之上。
• WebSocket 处理程序 -- 遵循来自 graphql-ws 的协议，支持 GraphQL 订阅流。
• Web 拦截 -- 能够拦截每个 GraphQL 请求，检查 HTTP 头，并修改 GraphQL ExecutionInput 或 ExecutionResult。
• Boot starter -- 将所有组件整合到一个可运行的应用程序中。

除此之外，我们开始关注关键方面，如安全性、测试和指标。

安全性

GraphQL 端点的 URL 通常很容易保护。对于更细粒度的安全性，应用程序可以在数据检索方法上使用 Spring Security 注解。这需要将 Spring Security 上下文传播到数据检索方法，虽然 GraphQL Java 对线程是中立的，但执行中的组件本身可以是异步的，并可能导致线程切换。

这促使我们增加了从 Web 框架层面、通过 GraphQL 引擎到数据获取组件的上下文传播支持。这包括 Spring MVC 应用程序的 ThreadLocal 上下文和 WebFlux 应用程序的 Reactor Context。这些功能到位后，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。

指标

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

Querydsl 集成

Querydsl 提供了一种灵活且类型安全的方式来表达查询谓词（predicate）。Spring GraphQL 构建在 Spring Data 的 Querydsl 扩展之上，可以轻松创建由 Querydsl 支持的 DataFetcher。它从 GraphQL 请求参数中准备 Querydsl Predicate，并使用它来获取数据，这适用于 JPA、MongoDB 和 LDAP。

的 webmvc-http 示例使用了 Querydsl。

Schema 优先 vs Object 优先

GraphQL 提供了一种 schema 语言，帮助客户端创建有效的请求，启用 GraphiQL UI 编辑器，促进团队之间的通用词汇使用等。它也带来了由来已久的 schema 优先 vs object 优先的开发困境。

我们认为应该优先采用 schema 优先的开发方式。它有助于促进技术和非技术背景人员之间的交流，有助于工具的使用，使得跟踪变更更容易等等。此外，GraphQL schema 和 Java 类型之间也不存在一对一的映射。

话虽如此，代码生成也有其应用空间，比如快速入门，为客户端创建查询等。像 Netflix DGS 这样的框架对此提供了出色的支持，可以与 Spring GraphQL 一起使用。

路线图和反馈

我们计划在 9 月 2-3 日的 SpringOne 大会之前发布第二个里程碑版本。基于早期反馈，我们已经为 M2 版本安排了一些问题，包括支持 GraphQL 客户端、BatchLoader 注册、文件上传等等。

里程碑阶段将持续到 11 月 Spring Boot 2.6 发布之后，届时 Boot starter 将计划迁移到 Spring Boot 仓库中，以便包含在 Boot 2.7 中。

我们的目标是今年晚些时候拥有稳定的 API 并进入 RC（发布候选）阶段。为了实现这一目标，我们需要您的反馈。请尝试使用它，并在我们的问题跟踪器中创建或评论现有问题。

资源

有关 Spring GraphQL 功能的更多详细信息，请查阅参考文档。

GraphQL Java 和 Spring 团队将在今年的 SpringOne 大会上联合进行演讲，该大会连续第二年免费在线举办。请注册参加我们的演讲，并与演讲者和与会者互动。