HTTP 与 Web 开发

构建 GraphQL 服务端应用

本指南将向你展示如何使用 Vert.x Web GraphQL 模块快速搭建高性能 GraphQL 数据查询与变更服务。

你将构建什么

你将构建一个 GraphQL 服务端，用于管理个人待办事项任务（Todo List）。

该应用程序由以下几个核心文件组成：

tasks.graphqls：GraphQL Schema 契约定义文件；
Task：数据实体 POJO 类；
GraphQLVerticle：驱动服务的 Vert.x Verticle。

创建工程项目

本项目代码提供了 Maven 与 Gradle 两种构建方式，二者完全等价。

使用 Maven

以下是推荐的 pom.xml 构建配置：

Maven pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>io.vertx.howtos</groupId>
  <artifactId>graphql-howto</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <vertx.version>5.0.0.CR2</vertx.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.vertx</groupId>
        <artifactId>vertx-stack-depchain</artifactId>
        <version>${vertx.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-web-graphql</artifactId>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.13.0</version>
        <configuration>
          <release>17</release>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.5.0</version>
        <configuration>
          <mainClass>io.vertx.howtos.graphql.GraphQLVerticle</mainClass>
        </configuration>
      </plugin>
    </plugins>
  </build>

</project>

使用 Gradle

若使用带有 Kotlin DSL 的 Gradle，对应的 build.gradle.kts 文件如下：

Gradle build.gradle.kts

plugins {
  java
  application
}

repositories {
  mavenCentral()
}

java {
  toolchain {
    languageVersion.set(JavaLanguageVersion.of(17))
  }
}

dependencies {
  implementation(platform("io.vertx:vertx-stack-depchain:5.0.0.CR2"))
  implementation("io.vertx:vertx-web-graphql")
}

application {
  mainClass.set("io.vertx.howtos.graphql.GraphQLVerticle")
}

使用 Vert.x Web 与 GraphQL 管理待办事项

定义 GraphQL Schema 契约

首先，我们需要在资源目录中定义待办应用的 GraphQL Schema：

GraphQL Schema 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
}

该 Schema 定义了：

Task 类型：包含 id、description（描述）与 completed（是否已完成）三个字段；
allTasks 查询（Query）：返回任务列表，支持传入可选的 uncompletedOnly 参数（默认值为 true，即仅查询未完成事项）；
complete 变更（Mutation）：接收任务的 id 作为参数，并返回布尔值表示该任务标记完成是否成功。

编写服务端核心逻辑

在应用层，待办任务由 Task 类进行映射：

Java src/main/java/io/vertx/howtos/graphql/Task.java

package io.vertx.howtos.graphql;

import java.util.UUID;

public record Task(String id, String description, boolean completed) {

  public Task(String description) {
    this(UUID.randomUUID().toString(), description, false); (1)
  }
}

1	创建 `Task` 实例时自动为其生成并分配随机唯一标识。

Task 类中的字段名称必须与 GraphQL Schema 中声明的字段名称严格保持一致。

在应用启动时，我们预置几条初始任务数据：