An Introduction to Domain Graph Service (DGS) Framework – 域图服务（DGS）框架简介

最后修改: 2022年 1月 31日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

One of the most significant paradigm changes over the last few years regarding client/server communication has been GraphQL, an open-source query language, and runtime for manipulating APIs. We can use it to request the exact data we need and therefore limit the number of requests we need.

在过去几年中，关于客户机/服务器通信的最重要的范式变化之一是GraphQL，这是一种开源的查询语言，以及用于操纵API的运行时间。我们可以用它来请求我们需要的确切数据，从而限制我们所需的请求数量。

Netflix created a Domain Graph Service Framework (DGS) server framework to make things even easier. In this quick tutorial, we’ll cover key features of the DGS Framework. We’ll see how to add this framework to our app and check how its basic annotations work. To learn more about GraphQL itself, check out our Introduction to GraphQL article.

Netflix创建了一个域图服务框架（DGS）服务器框架，使事情变得更加简单。在这个快速教程中，我们将介绍DGS框架的主要功能。我们将看到如何将这个框架添加到我们的应用程序中，并检查其基本注释如何工作。要了解有关GraphQL本身的更多信息，请查看我们的GraphQL入门文章。

2. Domain Graph Service Framework

2.域图服务框架

Netflix DGS (Domain Graph Service) is a GraphQL server framework written in Kotlin and based on Spring Boot. It’s designed to have minimal external dependencies aside from the Spring framework.

Netflix DGS（Domain Graph Service）是一个用Kotlin编写并基于Spring Boot的GraphQL服务器框架。除了Spring框架之外，它被设计为具有最小的外部依赖性。

The Netflix DGS framework uses an annotation-based GraphQL Java library built on top of Spring Boot. Besides the annotation-based programming model, it provides several useful features. It allows generating source code from GraphQL schemas. Let’s sum up some key features:

Netflix DGS框架使用了一个建立在Spring Boot之上的基于注解的GraphQL Java库。除了基于注解的编程模型，它还提供了几个有用的功能。它允许从GraphQL模式中生成源代码。 让我们总结一下一些关键特性。

  • Annotation-based Spring Boot programming model
  • Test framework for writing query tests as unit tests
  • Gradle/Maven Code Generation plugin to create types from schema
  • Easy integration with GraphQL Federation
  • Integration with Spring Security
  • GraphQL subscriptions (WebSockets and SSE)
  • File uploads
  • Error handling
  • Many extension points

3. Configuration

3.配置

Firstly, as the DGS framework is based on Spring Boot, let’s create a Spring Boot app. Then, let’s add the DGS dependency to our project:

首先，由于DGS框架是基于Spring Boot的，让我们创建一个Spring Boot应用程序。然后，让我们将DGS依赖性添加到我们的项目中。

<dependency>
    <groupId>com.netflix.graphql.dgs</groupId>
    <artifactId>graphql-dgs-spring-boot-starter</artifactId>
    <version>4.9.16</version>
</dependency>

4. Schema

4.计划

4.1. Development Approaches

4.1.发展方式

The DGS framework supports both development approaches – schema-first and code-first. But the recommended approach is schema-first, mainly because it’s easier to keep up with changes in the data model. Schema-first indicates that we first define the schema for the GraphQL service, and then we implement the code by matching the definitions in the schema. The framework picks up any schema files in the src/main/resources/schema folder by default.

DGS框架支持两种开发方法–模式优先和代码优先。但推荐的方法是模式优先，主要是因为它更容易跟上数据模型的变化。模式优先表示我们首先为GraphQL服务定义模式，然后我们通过匹配模式中的定义来实现代码。框架默认会拾取 src/main/resources/schema文件夹中的任何模式文件。

4.2. Implementation

4.2.实施

Let’s create a simple GraphQL schema for our example application using Schema Definition Language (SDL):

让我们使用Schema Definition Language (SDL)为我们的示例应用程序创建一个简单的GraphQL模式。

type Query {
    albums(titleFilter: String): [Album]
}

type Album {
    title: String
    artist: String
    recordNo: Int
}

This schema allows querying for a list of albums and, optionally, filtering by title.

该模式允许查询专辑列表，并可选择按title进行过滤。

5. Basic Annotation

5.基本注释

Let’s start with creating an Album class corresponding to our schema:

让我们先创建一个与我们的模式相对应的Album类。

public class Album {
    private final String title;
    private final String artist;
    private final Integer recordNo;

    public Album(String title, String artist, Integer recordNo) {
        this.title = title;
        this.recordNo = recordNo;
        this.artist = artist;
    }

    // standard getters
}

5.1. Data Fetcher

5.1.数据采集器

Data fetchers are responsible for returning data for a query. The @DgsQuery, @DgsMutation, and @DgsSubscription annotations are shorthands to define data fetchers on the Query, Mutation, and Subscription types. All mentioned annotations are equivalent to the @DgsData annotation. We can use one of these annotations on a Java method to make that method a data fetcher and define a type with a parameter.

数据提取器负责为查询返回数据。@DgsQuery, @DgsMutation,和@DgsSubscription 注解是在Query, Mutation和Subscription类型上定义数据获取器的缩写。我们可以在一个Java方法上使用这些注解之一，使该方法成为一个数据获取器，并定义一个带有参数的类型。

5.2. Implementation

5.2.实施

So, to define the DGS data fetcher, we need to create a query method in the @DgsComponent class. We want to query a list of Albums in our example, so let’s mark the method with @DgsQuery:

因此，为了定义DGS数据获取器，我们需要在@DgsComponent类中创建一个查询方法。在我们的例子中，我们想查询一个Albums的列表，所以让我们用@DgsQuery来标记这个方法。

private final List<Album> albums = Arrays.asList(
  new Album("Rumours", "Fleetwood Mac", 20),
  new Album("What's Going On", "Marvin Gaye", 10), 
  new Album("Pet Sounds", "The Beach Boys", 12)
  );

@DgsQuery
public List<Album> albums(@InputArgument String titleFilter) {
    if (titleFilter == null) {
        return albums;
    }
    return albums.stream()
      .filter(s -> s.getTitle().contains(titleFilter))
      .collect(Collectors.toList());
}

We also marked arguments of the method with the annotation @InputArgument. This annotation will use the name of the method argument to match it with the name of an input argument sent in the query.

我们还用注解@InputArgument来标记方法的参数。这个注解将使用方法参数的名称与查询中发送的输入参数的名称相匹配。

6. Code-Gen Plugin

6. 代码生成插件

DGS also comes with a code-gen plugin to generate Java or Kotlin code from GraphQL Schema. Code generation is typically integrated with the build.

DGS还配备了一个代码生成插件，用于从GraphQL模式中生成Java或Kotlin代码。代码生成通常与构建集成。

The DGS Code Generation plugin is available for Gradle and Maven. The plugin generates code during our project’s build process based on our Domain Graph Service’s GraphQL schema file. The plugin can generate data types for types, input types, enums, and interfaces, sample data fetchers, and type-safe query API. There is also a DgsConstants class containing the names of types and fields.

DGS代码生成插件可用于Gradle和Maven。该插件在我们项目的构建过程中，基于我们的Domain Graph Service的GraphQL模式文件生成代码。该插件可以生成类型、输入类型、枚举和接口的数据类型、样本数据获取器和类型安全的查询API。还有一个DgsConstants类，包含了类型和字段的名称。

7. Testing

7.测试

A convenient way to query our API is GraphiQL. GraphiQL is a query editor that comes out of the box with the DGS framework. Let’s start our application on the default Spring Boot port and check the URL http://localhost:8080/graphiql. Let’s try the following query and test the result:

GraphiQL是DGS框架开箱即用的查询编辑器。让我们在默认的Spring Boot端口上启动我们的应用程序并检查URL http://localhost:8080/graphiql。让我们尝试以下查询并测试结果。

{
    albums{
        title
    }
}

Note that, unlike with REST, we have to specifically list which fields we want to be returned from our query. Let’s see the response:

请注意，与REST不同，我们必须具体列出我们希望从查询中返回的字段。让我们看看响应。

{
  "data": {
    "albums": [
      {
        "title": "Rumours"
      },
      {
        "title": "What's Going On"
      },
      {
        "title": "Pet Sounds"
      }
    ]
  }
}

8. Conclusion

8.结语

Domain Graph Service Framework is an easy and quite attractive way of using GraphQL. It uses higher-level building blocks to handle query execution and such. The DGS framework makes all this available with a convenient Spring Boot programming model. This framework has some useful features that we cover in the article.

域图服务框架是使用GraphQL的一种简单且相当有吸引力的方式。它使用更高级别的构建块来处理查询执行等问题。DGS框架通过一个方便的Spring Boot编程模型使所有这些都可以使用。这个框架有一些有用的功能，我们将在文章中介绍。

We talked about configuring DGS in our app and looked at some of its basic annotations. Then, we wrote a simple application to check how to create data from the schema and query them. Finally, we tested our API by using GraphiQL. As always, the example can be found over on GitHub.

我们谈到了在我们的应用程序中配置DGS，并看了它的一些基本注释。然后，我们写了一个简单的应用程序来检查如何从模式中创建数据并查询它们。最后，我们通过使用GraphiQL测试了我们的API。一如既往，这个例子可以在GitHub上找到over。