此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Boot 3.3.4！spring-doc.cn

此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Boot 3.3.4！spring-doc.cn

如果要构建 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
起动机 运输 实现

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
如果您希望 Spring Boot 检测该位置的所有应用程序模块和依赖项中的 schema 文件， 您可以设置为 （注意前缀）。spring.graphql.schema.locations"classpath*:graphql/**/"classpath*:
默认情况下，架构上将允许现场自省，因为 GraphiQL 等工具需要它。 如果不想公开有关架构的信息，可以通过设置为 来禁用自省。spring.graphql.schema.introspection.enabledfalse

GraphQL 运行时布线

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

但是，通常，应用程序不会直接实现，而是创建带 Comments 的控制器。 Spring Boot 将自动检测具有带注释的处理程序方法的类，并将它们注册为 s。 以下是带有类的问候查询的示例实现：DataFetcher@ControllerDataFetcher@Controllerspring-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

Spring Data 存储库，注释并扩展了以下之一：@GraphQlRepositoryspring-doc.cn

被 Spring Boot 检测到，并被视为匹配顶级查询的候选对象。DataFetcherspring-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 端点都由具有 of 的 bean 提供。 如果定义自己的 bean，则可能需要添加适当的 Comments 以确保它们被正确排序。RouterFunction@Order0RouterFunction@Order

默认情况下，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，您可以声明一个 bean 以将其注册到 Web 传输中。WebInterceptorspring-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 服务器后，我们可以使用 . 例如，配置该映射意味着我们可以在使用 .spring.graphql.rsocket.mapping"graphql"RSocketGraphQlClientspring-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 MVC 和 Spring WebFlux 的 HTTP 端点都由具有 of 的 bean 提供。 如果定义自己的 bean，则可能需要添加适当的 Comments 以确保它们被正确排序。RouterFunction@Order0RouterFunction@Order

异常处理

Spring GraphQL 使应用程序能够注册一个或多个按顺序调用的 Spring 组件。 Exception 必须解析为对象列表，请参阅 Spring GraphQL 异常处理文档。 Spring Boot 将自动检测 bean 并将其注册到 .DataFetcherExceptionResolvergraphql.GraphQLErrorDataFetcherExceptionResolverGraphQlSource.Builderspring-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