Spring Boot中使用GraphQL

1. 简介

GraphQL是Facebook的一个相对较新的概念，被称为Web API的REST的替代品。

在本文中，我们将学习如何使用 Spring Boot 设置 GraphQL 服务器，以便我们可以将其添加到现有应用程序中或在新应用程序中使用它。

2. 什么是GraphQL？

传统的 REST API 使用服务器管理资源的概念。我们可以使用各种HTTP请求以一些标准方式操作这些资源。只要我们的 API 符合资源概念，这就可以很好地工作，但当我们需要偏离它时，很快就会分崩离析。

当客户端需要同时来自多个资源的数据时，例如请求博客文章和评论时，也会受到影响。通常，这是通过让客户端发出多个请求或让服务器提供可能并不总是需要的额外数据来解决的，从而导致更大的响应大小。

GraphQL 为这两个问题提供了解决方案。它允许客户端准确指定所需的数据，包括在单个请求中导航子资源，并允许在单个请求中进行多个查询。

它还以更多的 RPC 方式工作，使用命名查询和突变，而不是标准的强制操作集。这适用于将控件放在它所属的位置，API 开发人员指定可用的内容，API 使用者指定所需的内容。

例如，博客可能允许以下查询：

query {
    recentPosts(count: 10, offset: 0) {
        id
        title
        category
        author {
            id
            name
            thumbnail
        }
    }
}

此查询将：

• 索取十个最新帖子
• 对于每个帖子，请求 ID、标题和类别
• 对于每个帖子，请求作者，返回 ID、姓名和缩略图

在传统的 REST API 中，这需要 11 个请求，一个用于帖子，10 个用于作者，或者需要在帖子详细信息中包含作者详细信息。

2.1. GraphQL 模式

GraphQL 服务器公开了一个描述 API 的模式。此架构由类型定义组成。每种类型都有一个或多个字段，每个字段接受零个或多个参数并返回特定类型。

graph派生自这些字段相互嵌套的方式。请注意，graph不需要是非循环的，循环是完全可以接受的，但它是定向的。客户端可以从一个字段获取到其子字段，但除非架构显式定义此字段，否则它无法自动返回到父字段。

博客的示例 GraphQL 架构可能包含以下定义，描述帖子、文章作者和根查询，以获取博客上的最新文章：

type Post {
    id: ID!
    title: String!
    text: String!
    category: String
    author: Author!
}

type Author {
    id: ID!
    name: String!
    thumbnail: String
    posts: [Post]!
}

# The Root Query for the application
type Query {
    recentPosts(count: Int, offset: Int): [Post]!
}

# The Root Mutation for the application
type Mutation {
    createPost(title: String!, text: String!, category: String, authorId: String!) : Post!
}

某些名称末尾的“!”表示它是不可为空的类型。任何没有此值的类型都可以在服务器的响应中为 null。GraphQL 服务可以正确处理这些字段，使我们能够安全地请求可为空类型的子字段。

GraphQL 服务还使用一组标准字段公开架构，允许任何客户端提前查询架构定义。

这允许客户端自动检测架构何时更改，并允许客户端动态适应架构的工作方式。一个非常有用的例子是 GraphiQL 工具，它允许我们与任何 GraphQL API 进行交互。

3. 介绍 GraphQL Spring Boot Starter

Spring Boot GraphQL Starter 提供了一种在很短的时间内让 GraphQL 服务器运行的绝佳方法。使用自动配置和基于注释的编程方法，我们只需要编写服务所需的代码。

3.1. 设置服务

需要的依赖项：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-graphql</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

因为 GraphQL 与传输无关，所以我们在配置中包含 Web 启动器。这会在默认的 /graphql 端点上使用 Spring MVC 通过 HTTP 公开 GraphQL API。其他启动器可用于其他底层实现，例如Spring Webflux。如有必要，我们还可以在 application.properties 文件中自定义此端点。

3.2. 编写模式

GraphQL Boot 启动器的工作原理是处理 GraphQL 模式文件来构建正确的结构，然后将特殊的 bean 连接到此结构。Spring Boot GraphQL 启动器会自动查找这些模式文件。

我们需要将这些“.graphqls”或“.gqls”模式文件保存在
src/main/resources/graphql/**位置下，Spring Boot会自动拾取它们。像往常一样，我们可以使用
spring.graphql.schema.locations 自定义位置，并使用
spring.graphql.schema.file-extensions 配置属性自定义文件扩展名。

一个要求是必须只有一个根查询和最多一个根突变。与架构的其余部分不同，我们不能将其拆分到文件之间。这是 GraphQL 模式定义的限制，而不是 Java 实现的限制。

3.3. Root Query Resolver

根查询需要具有特殊批注的方法来处理此根查询中的各种字段。与模式定义不同，根查询字段只有一个 Spring Bean 没有限制。

我们需要用@QueryMapping注释来注释处理程序方法，并将它们放在应用程序中的标准@Controller组件中。这会将带注释的类注册为 GraphQL 应用程序中的数据获取组件：

@Controller
public class PostController {

    private PostDao postDao;

    @QueryMapping
    public List<Post> recentPosts(@Argument int count, @Argument int offset) {
        return postDao.getRecentPosts(count, offset);
    }
}

上面定义了方法 recentPosts，我们将使用它来处理之前定义的模式中 recentPosts 字段的任何 GraphQL 查询。此外，该方法必须具有使用与架构中的相应参数对应的@Argument批注的参数。

它还可以选择采用其他与 GraphQL 相关的参数，例如 GraphQLContext、DataFetchingEnvironment 等，以访问底层上下文和环境。

该方法还必须为 GraphQL 模式中的类型返回正确的返回类型，正如我们将要看到的。我们可以使用任何简单的类型，String，Int，List等，以及等效的Java类型，系统只是自动映射它们。

3.4. 使用 bean 来表示Types

GraphQL 服务器中的每个复杂类型都由 Java Bean 表示，无论是从根查询还是从结构中的其他任何位置加载。同一个 Java 类必须始终表示相同的 GraphQL 类型，但类的名称不是必需的。

Java Bean 中的字段将根据字段名称直接映射到 GraphQL 响应中的字段：

public class Post {
    private String id;
    private String title;
    private String category;
    private String authorId;
}

Java Bean 上任何未映射到 GraphQL 模式的字段或方法都将被忽略，但不会导致问题。

3.5. Complex Values的字段解析器

有时，字段的值对于加载来说并不重要。这可能涉及数据库查找、复杂计算或其他任何内容。@SchemaMapping注释将处理程序方法映射到架构中具有相同名称的字段，并将其用作该字段的 DataFetcher。

@SchemaMapping
public Author author(Post post) {
    return authorDao.getAuthor(post.getAuthorId());
}

重要的是，如果客户端不请求字段，那么 GraphQL 服务器将不会执行检索它的工作。这意味着，如果客户端检索帖子并且不要求作者字段，则不会执行上面的author() 方法，也不会进行 DAO 调用。或者，我们也可以在注释中指定父类型名称和字段名称：

@SchemaMapping(typeName="Post", field="author")
public Author getAuthor(Post post) {
    return authorDao.getAuthor(post.getAuthorId());
}

在这里，注释属性用于将其声明为架构中author字段的处理程序。

3.6. 可为空值

GraphQL 模式的概念是，某些类型可为空，而其他类型则不可为空。我们在 Java 代码中直接使用 null 值来处理这个问题。相反，我们可以将 Java 8 中的新 Optional 类型直接用于可为空的类型，系统将对这些值执行正确的操作。

这非常有用，因为这意味着我们的 Java 代码与方法定义中的 GraphQL 模式更明显地相同。

3.7. 突变

到目前为止，我们所做的一切都是为了从服务器检索数据。GraphQL 还能够通过突变更新存储在服务器上的数据。

从代码的角度来看，查询没有理由不能更改服务器上的数据。我们可以轻松编写接受参数、保存新数据并返回这些更改的查询解析器。这样做会给 API 客户端带来令人惊讶的副作用，并被视为不良做法。

相反，应使用突变来通知客户端这将导致正在存储的数据发生更改。

与 Query 类似，通过在控制器中用 @MutationMapping 注释处理程序方法来定义突变。然后，来自突变字段的返回值与来自查询字段的返回值完全相同，从而允许检索嵌套值：

@MutationMapping
public Post createPost(@Argument String title, @Argument String text,
  @Argument String category, @Argument String authorId) {

    Post post = new Post();
    post.setId(UUID.randomUUID().toString());
    post.setTitle(title);
    post.setText(text);
    post.setCategory(category);
    post.setAuthorId(authorId);

    postDao.savePost(post);

    return post;
}

4. GraphiQL

GraphQL 还有一个名为 GraphiQL 的配套工具。这个 UI 工具可以与任何 GraphQL 服务器通信，并有助于针对 GraphQL API 使用和开发。

Spring GraphQL 附带了一个默认的 GraphQL 页面，该页面在 /graphiql 端点处公开。默认情况下，终结点处于禁用状态，但可以通过启用
spring.graphql.graphiql.enabled 属性来打开它。这提供了一个非常有用的浏览器内工具来编写和测试查询，尤其是在开发和测试期间。