对于最新的稳定版本，请使用 Spring Boot 3.4.0！spring-doc.cn

适用于 GraphQL 的 Spring

如果要构建 GraphQL 应用程序，可以利用 Spring Boot 对 Spring for GraphQL 的自动配置。 Spring for GraphQL 项目基于 GraphQL Java。 您至少需要Starters。 由于 GraphQL 与传输无关，因此您还需要在应用程序中添加一个或多个额外的Starters，以便在 Web 上公开 GraphQL API：spring-boot-starter-graphqlspring-doc.cn

起动机 运输 实现

spring-boot-starter-webspring-doc.cn

HTTP 协议spring-doc.cn

Spring MVCspring-doc.cn

spring-boot-starter-websocketspring-doc.cn

WebSocket 浏览器spring-doc.cn

用于 Servlet 应用程序的 WebSocketspring-doc.cn

spring-boot-starter-webfluxspring-doc.cn

HTTP、WebSocketspring-doc.cn

Spring WebFluxspring-doc.cn

spring-boot-starter-rsocketspring-doc.cn

TCP、WebSocketspring-doc.cn

Reactor Netty 上的 Spring WebFluxspring-doc.cn

GraphQL 架构

Spring GraphQL 应用程序在启动时需要定义的架构。 默认情况下，您可以在 “.graphqls” 或 “.gqls” 架构文件下编写，Spring Boot 会自动获取它们。 您可以使用 自定义位置，并使用 自定义文件扩展名。src/main/resources/graphql/**spring.graphql.schema.locationsspring.graphql.schema.file-extensionsspring-doc.cn

如果您希望 Spring Boot 检测该位置的所有应用程序模块和依赖项中的 schema 文件， 您可以设置为 （注意前缀）。spring.graphql.schema.locations"classpath*:graphql/**/"classpath*:

在以下部分中，我们将考虑此示例 GraphQL 架构，定义两种类型和两种查询：spring-doc.cn

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.enabledfalse

GraphQL 运行时布线

GraphQL Java RuntimeWiring.Builder 可用于注册自定义标量类型、指令、类型解析程序、DataFetcher 等。 你可以在 Spring 配置中声明RuntimeWiringConfigurer bean 来访问RuntimeWiring.Builder。 Spring Boot 会检测此类 bean 并将它们添加到 GraphQlSource 构建器中。spring-doc.cn

但是，通常情况下，应用程序不会直接实现 DataFetcher，而是创建带注释的控制器。 Spring Boot 将自动检测具有 Comments 处理程序方法@Controller类，并将它们注册为 s。 以下是使用 @Controller 类的问候查询的示例实现：DataFetcherspring-doc.cn

import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

@Controller
public class GreetingController {

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

}
import org.springframework.graphql.data.method.annotation.Argument
import org.springframework.graphql.data.method.annotation.QueryMapping
import org.springframework.stereotype.Controller

@Controller
class GreetingController {

	@QueryMapping
	fun greeting(@Argument name: String): String {
		return "Hello, $name!"
	}

}

Querydsl 和 QueryByExample 存储库支持

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

使用 @GraphQlRepository 注释并扩展以下之一的 Spring Data 存储库：spring-doc.cn

被 Spring Boot 检测到，并被视为 DataFetcher 匹配顶级查询的候选者。spring-doc.cn

运输

HTTP 和 WebSocket

默认情况下，GraphQL HTTP 终端节点处于 HTTP POST 状态。 它还支持仅针对订阅的 Server Sent Events 的媒体类型。 可以使用 自定义路径。/graphql"text/event-stream"spring.graphql.pathspring-doc.cn

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

默认情况下，GraphQL WebSocket 终端节点处于关闭状态。要启用它：spring-doc.cn

  • 对于 Servlet 应用程序，请添加 WebSocket Startersspring-boot-starter-websocketspring-doc.cn

  • 对于 WebFlux 应用程序，不需要额外的依赖项spring-doc.cn

  • 对于这两者，必须设置 application 属性spring.graphql.websocket.pathspring-doc.cn

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

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

Spring Boot 支持名称空间下的许多 configuration properties;下面是一个简短的配置示例：spring.graphql.cors.*spring-doc.cn

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

RSocket 系列

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

Spring Boot 会自动配置一个 bean，你可以将其注入到组件中：RSocketGraphQlClient.Builder<?>spring-doc.cn

@Component
public class RSocketGraphQlClientExample {

	private final RSocketGraphQlClient graphQlClient;

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

然后发送请求： include-code：：RSocketGraphQlClientExample[tag=request]spring-doc.cn

异常处理

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

GraphiQL 和 Schema 打印机

Spring GraphQL 提供了基础设施，可帮助开发人员使用或开发 GraphQL API。spring-doc.cn

Spring GraphQL 附带一个默认的 GraphiQL 页面，该页面默认公开。 默认情况下，此页面处于禁用状态，可以使用该属性打开。 许多公开此类页面的应用程序将首选自定义版本。 默认实现在开发过程中非常有用，这就是为什么它在开发过程中使用 spring-boot-devtools 自动公开的原因。"/graphiql"spring.graphql.graphiql.enabledspring-doc.cn

您还可以选择在启用该属性时以文本格式公开 GraphQL 架构。/graphql/schemaspring.graphql.schema.printer.enabledspring-doc.cn