实现 GraphQL 服务器

本文将向您展示如何实现一个 GraphQL 服务器。

您将构建什么

您将构建一个 GraphQL 服务器来管理您的个人任务(即待办事项列表)。

该应用程序由几个文件组成:

  1. tasks.graphqls 模式文件

  2. Task 数据类

  3. GraphQLVerticle

您需要什么

  • 文本编辑器或 IDE

  • Java 17 或更高版本

  • Maven 或 Gradle

创建项目

此项目的代码包含功能等效的 Maven 和 Gradle 构建文件。

使用 Maven

以下是您应该使用的 pom.xml 文件的内容

使用 Gradle

假设您使用带有 Kotlin DSL 的 Gradle,您的 build.gradle.kts 文件应如下所示

使用 Vert.x Web 和 GraphQL 管理任务

创建模式

首先,让我们为任务管理应用程序创建一个 GraphQL 模式

GraphQL 模式 src/main/resources/tasks.graphqls
type Task {
  id: String
  description: String
  completed: Boolean
}

type Query {
  allTasks(uncompletedOnly: Boolean = true): [Task]
}

type Mutation {
  complete(id: String!): Boolean
}

该模式定义了

  • Task 类型,包含 3 个字段:iddescriptioncompleted

  • allTasks 查询,返回一个任务数组,并可选地接受一个参数 uncompletedOnly(默认为 true

  • complete 变更,接受任务 id 作为参数,并返回一个布尔值,指示操作是否成功

实现服务器

在应用程序中,任务将由 Task 类建模

  1. 当创建 Task 实例时,会分配一个随机标识符

重要
Task 类的字段名称必须与相应的 GraphQL 模式类型中的字段名称匹配。

在启动时,我们将创建一些条目

然后必须设置 GraphQL-Java 引擎

  1. 从类路径读取模式文件

  2. TypeDefinitionRegistry 是 GraphQL-Java 运行时中与模式文件定义等效的部分

  3. RuntimeWiring 告诉 GraphQL-Java 如何解析类型和获取数据

  4. GraphQLSchema 连接运行时类型定义与类型解析器和数据获取器

  5. 创建应用程序的 GraphQL 引擎

到目前为止一切顺利。那么如何实现一个数据获取器呢?

allTasks 数据获取器从 DataFetchingEnvironment 中获取 uncompletedOnly 参数。其值由客户端提供,或者(如模式文件中所定义)设置为 true

警告
请勿在数据获取器中阻塞 Vert.x 事件循环。在本指南中,数据集很小且来自内存,因此以阻塞方式实现 allTasks 是安全的。当使用数据库、缓存或 Web 服务时,请确保您的数据获取器返回一个 CompletionStage。有关更多详细信息,请参阅 Vert.x Web GraphQL 处理程序文档

complete 变更的代码没有太大不同

它获取客户端提供的 id 参数,然后查找相应的任务。如果找到任务,则更新它,并且变更返回 true 表示成功。

就快完成了!现在让我们在 verticle 的 start 方法中把所有东西放在一起

  1. 为 GraphQL-Java 对象创建 Vert.x Web GraphQL 处理程序

  2. 定义一个包罗万象的 Vert.x Web 路由并设置 BodyHandler(处理 POST 请求体所需)

  3. 为 GraphQL 查询定义一个 Vert.x Web 路由并设置 GraphQL 处理程序

运行应用程序

GraphQLVerticle 需要一个 main 方法

  1. 创建 Vertx 上下文

  2. 部署 GraphQLVerticle

然后您可以运行应用程序

  • 直接从您的 IDE 运行,或者

  • 使用 Maven:mvn compile exec:java,或者

  • 使用 Gradle:./gradlew run (Linux, macOS) 或 gradlew run (Windows)。

以下示例使用 HTTPie 命令行 HTTP 客户端。如果您的系统尚未安装,请参阅其安装文档。

列出未完成的任务

要列出未完成的任务,请打开您的终端并执行此操作

http :8080/graphql query='
query {
  allTasks {
    id,
    description
  }
}'

您应该会看到类似以下内容:

{
    "data": {
        "allTasks": [
            {
                "description": "Learn GraphQL",
                "id": "4a9f53fd-584f-4169-b725-6b320043db8b"
            },
            {
                "description": "Profit",
                "id": "03770db5-a8ad-44b3-ad6e-6fe979015088"
            },
            {
                "description": "Build awesome GraphQL server",
                "id": "6b000f72-8aa9-4f4e-9539-5da2ab11cd94"
            }
        ]
    }
}

完成一项任务

要完成学习 GraphQL 任务

http :8080/graphql query='
mutation {
  complete(id: "4a9f53fd-584f-4169-b725-6b320043db8b")
}'
注意
上述查询中使用的 id 必须更改为您应用程序生成的值。

任务完成后,您将看到

{
    "data": {
        "complete": true
    }
}

检索所有任务

如果您需要检索所有任务,包括已完成的任务,请确保在 allTasks 查询中将 uncompletedOnly 参数设置为 false

http :8080/graphql query='
query {
  allTasks(uncompletedOnly: false) {
    id
    description
    completed
  }
}'

预期输出是

{
    "data": {
        "allTasks": [
            {
                "completed": true,
                "description": "Learn GraphQL",
                "id": "4a9f53fd-584f-4169-b725-6b320043db8b"
            },
            {
                "completed": false,
                "description": "Profit",
                "id": "03770db5-a8ad-44b3-ad6e-6fe979015088"
            },
            {
                "completed": false,
                "description": "Build awesome GraphQL server",
                "id": "6b000f72-8aa9-4f4e-9539-5da2ab11cd94"
            }
        ]
    }
}

总结

本文档涵盖了

  1. Vert.x Web GraphQL 处理程序设置,

  2. 实现简单的查询和变更数据获取器。


最近发布:2025-02-01 00:40:34 +0000。