|
对于最新的稳定版本，请使用 Spring Boot 3.5.5！ |
GraphQL 的 Spring
如果您想构建 GraphQL 应用程序，您可以利用 Spring Boot 对 Spring for GraphQL 的自动配置。
Spring for GraphQL 项目基于 GraphQL Java。
您将需要spring-boot-starter-graphql至少是入门菜。
由于 GraphQL 与传输无关，因此您还需要在应用程序中有一个或多个额外的Starters才能通过 Web 公开您的 GraphQL API：
| 起动机 | 运输 | 实现 |
|---|---|---|
|
HTTP |
弹簧 MVC |
|
Web套接字 |
用于 Servlet 应用程序的 WebSocket |
|
HTTP、Web套接字 |
Spring WebFlux |
|
TCP、Web套接字 |
Reactor Netty 上的 Spring WebFlux |
GraphQL 架构
Spring GraphQL 应用程序在启动时需要定义的模式。
默认情况下，您可以在src/main/resources/graphql/**Spring Boot 将自动拾取它们。
您可以使用spring.graphql.schema.locations文件扩展名为spring.graphql.schema.file-extensions.
如果您希望 Spring Boot 检测该位置的所有应用程序模块和依赖项中的模式文件，
您可以设置spring.graphql.schema.locations自"classpath*:graphql/**/"（请注意classpath*:前缀）。 |
在以下部分中，我们将考虑此示例 GraphQL 架构，定义两种类型和两个查询：
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.enabled自false. |
GraphQL 运行时布线
The GraphQL JavaRuntimeWiring.Builder可用于注册自定义标量类型、指令、类型解析器、DataFetcher，等等。
您可以声明RuntimeWiringConfigurerbean 以访问RuntimeWiring.Builder.
Spring Boot 检测此类 bean 并将它们添加到 GraphQlSource 构建器中。
但是，通常情况下，应用程序不会实现DataFetcher直接创建带注释的控制器。
Spring Boot 会自动检测@Controller具有带注释的处理程序方法的类，并将它们注册为DataFetchers.
下面是问候语查询的示例实现，其中包含@Controller类：
-
Java
-
Kotlin
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 Data 存储库用@GraphQlRepository并扩展以下之一：
被 Spring Boot 检测到并被视为候选者DataFetcher用于匹配顶级查询。
运输
HTTP 和 WebSocket
GraphQL HTTP 端点位于 HTTP POST/graphql默认情况下。
它还支持"text/event-stream"媒体类型仅适用于订阅的服务器发送事件。
路径可以通过以下方式进行自定义spring.graphql.path.
Spring MVC 和 Spring WebFlux 的 HTTP 端点由RouterFunction带有@Order之0.
如果您定义自己的RouterFunctionbeans，您可能希望添加适当的@Order注释以确保它们正确排序。 |
默认情况下，GraphQL WebSocket 端点处于关闭状态。要启用它，请执行以下作：
-
对于 Servlet 应用程序，请添加 WebSocket Starters
spring-boot-starter-websocket -
对于 WebFlux 应用程序，不需要额外的依赖项
-
对于两者，
spring.graphql.websocket.path应用程序属性必须设置
Spring GraphQL 提供了一个 Web 拦截模型。
这对于从 HTTP 请求标头检索信息并在 GraphQL 上下文中设置它或从同一上下文获取信息并将其写入响应标头非常有用。
使用 Spring Boot，您可以声明WebGraphQlInterceptorbean 将其注册到 Web 传输中。
Spring MVC 和 Spring WebFlux 支持 CORS（跨域资源共享）请求。 CORS 是 GraphQL 应用程序的 Web 配置的关键部分，这些应用程序从使用不同域的浏览器访问。
Spring Boot 支持spring.graphql.cors.*Namespace;下面是一个简短的配置示例：
-
Properties
-
YAML
spring.graphql.cors.allowed-origins=https://example.org
spring.graphql.cors.allowed-methods=GET,POST
spring.graphql.cors.max-age=1800sspring:
graphql:
cors:
allowed-origins: "https://example.org"
allowed-methods: GET,POST
max-age: 1800sRS袜子
RSocket 也支持作为 WebSocket 或 TCP 之上的传输。
配置 RSocket 服务器后，我们可以使用spring.graphql.rsocket.mapping.
例如，将该映射配置为"graphql"意味着我们可以在发送请求时将其用作路由，并使用RSocketGraphQlClient.
Spring Boot 自动配置一个RSocketGraphQlClient.Builder<?>您可以注入组件的 bean：
-
Java
-
Kotlin
@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=请求]
异常处理
Spring GraphQL 使应用程序能够注册一个或多个 SpringDataFetcherExceptionResolver按顺序调用的组件。
异常必须解析为GraphQLError对象，请参阅 Spring GraphQL 异常处理文档。
Spring Boot 会自动检测DataFetcherExceptionResolverbean 并将它们注册到GraphQlSource.Builder.
GraphiQL 和架构打印机
Spring GraphQL 提供了基础设施，用于帮助开发人员使用或开发 GraphQL API。
Spring GraphQL 附带一个默认的 GraphiQL 页面，该页面在"/graphiql"默认情况下。
默认情况下，此页面处于禁用状态，可以使用spring.graphql.graphiql.enabled财产。
许多公开此类页面的应用程序更喜欢自定义生成。
默认实现在开发过程中非常有用，这就是为什么它会自动公开spring-boot-devtools在开发过程中。
您还可以选择以文本格式公开 GraphQL 架构，网址为/graphql/schema当spring.graphql.schema.printer.enabled属性已启用。