quarkus extension add quarkus-smallrye-graphql

./mvnw quarkus:add-extension -Dextensions='quarkus-smallrye-graphql'

./gradlew addExtension --extensions='quarkus-smallrye-graphql'

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-graphql</artifactId>
</dependency>

implementation("io.quarkus:quarkus-smallrye-graphql")

package org.acme.microprofile.graphql;

public class Film {

    public String title;
    public Integer episodeID;
    public String director;
    public LocalDate releaseDate;

}

public class Hero {

    public String name;
    public String surname;
    public Double height;
    public Integer mass;
    public Boolean darkSide;
    public LightSaber lightSaber;
    public List<Integer> episodeIds = new ArrayList<>();

}

enum LightSaber {
    RED, BLUE, GREEN
}

@ApplicationScoped
public class GalaxyService {

    private List<Hero> heroes = new ArrayList<>();

    private List<Film> films = new ArrayList<>();

    public GalaxyService() {

        Film aNewHope = new Film();
        aNewHope.title = "A New Hope";
        aNewHope.releaseDate = LocalDate.of(1977, Month.MAY, 25);
        aNewHope.episodeID = 4;
        aNewHope.director = "George Lucas";

        Film theEmpireStrikesBack = new Film();
        theEmpireStrikesBack.title = "The Empire Strikes Back";
        theEmpireStrikesBack.releaseDate = LocalDate.of(1980, Month.MAY, 21);
        theEmpireStrikesBack.episodeID = 5;
        theEmpireStrikesBack.director = "George Lucas";

        Film returnOfTheJedi = new Film();
        returnOfTheJedi.title = "Return Of The Jedi";
        returnOfTheJedi.releaseDate = LocalDate.of(1983, Month.MAY, 25);
        returnOfTheJedi.episodeID = 6;
        returnOfTheJedi.director = "George Lucas";

        films.add(aNewHope);
        films.add(theEmpireStrikesBack);
        films.add(returnOfTheJedi);

        Hero luke = new Hero();
        luke.name = "Luke";
        luke.surname = "Skywalker";
        luke.height = 1.7;
        luke.mass = 73;
        luke.lightSaber = LightSaber.GREEN;
        luke.darkSide = false;
        luke.episodeIds.addAll(Arrays.asList(4, 5, 6));

        Hero leia = new Hero();
        leia.name = "Leia";
        leia.surname = "Organa";
        leia.height = 1.5;
        leia.mass = 51;
        leia.darkSide = false;
        leia.episodeIds.addAll(Arrays.asList(4, 5, 6));


        Hero vader = new Hero();
        vader.name = "Darth";
        vader.surname = "Vader";
        vader.height = 1.9;
        vader.mass = 89;
        vader.darkSide = true;
        vader.lightSaber = LightSaber.RED;
        vader.episodeIds.addAll(Arrays.asList(4, 5, 6));

        heroes.add(luke);
        heroes.add(leia);
        heroes.add(vader);

    }

    public List<Film> getAllFilms() {
        return films;
    }

    public Film getFilm(int id) {
        return films.get(id);
    }

    public List<Hero> getHeroesByFilm(Film film) {
        return heroes.stream()
                .filter(hero -> hero.episodeIds.contains(film.episodeID))
                .collect(Collectors.toList());
    }

    public void addHero(Hero hero) {
        heroes.add(hero);
    }

    public Hero deleteHero(int id) {
        return heroes.remove(id);
    }

    public List<Hero> getHeroesBySurname(String surname) {
        return heroes.stream()
                .filter(hero -> hero.surname.equals(surname))
                .collect(Collectors.toList());
    }
}

@GraphQLApi (1)
public class FilmResource {

    @Inject
    GalaxyService service;

    @Query("allFilms") (2)
    @Description("Get all Films from a galaxy far far away") (3)
    public List<Film> getAllFilms() {
        return service.getAllFilms();
    }
}

quarkus dev

./mvnw quarkus:dev

./gradlew --console=plain quarkusDev

curl http://localhost:8080/graphql/schema.graphql

query allFilms {
  allFilms {
    title
    director
    releaseDate
    episodeID
  }
}

query allFilms {
  allFilms {
    title
    releaseDate
  }
}

    @Query
    @Description("Get a Films from a galaxy far far away")
    public Film getFilm(@Name("filmId") int id) {
        return service.getFilm(id);
    }

query getFilm {
  film(filmId: 1) {
    title
    director
    releaseDate
    episodeID
  }
}

query getFilms {
  film0: film(filmId: 0) {
    title
    director
    releaseDate
    episodeID
  }
  film1: film(filmId: 1) {
    title
    director
    releaseDate
    episodeID
  }
}

    public List<Hero> heroes(@Source Film film) { (1)
        return service.getHeroesByFilm(film);
    }

query getFilmHeroes {
  film(filmId: 1) {
    title
    director
    releaseDate
    episodeID
    heroes {
      name
      height
      mass
      darkSide
      lightSaber
    }
  }
}

当返回类似 getAllFilms 的集合时，可以使用批量形式，更高效地获取相关角色：

返回 Uni 或为方法添加 @NonBlocking，可以使查询采用响应式／非阻塞执行：

也可以使用 @NonBlocking：

使用 Uni 或 @NonBlocking 时，请求在事件循环线程上执行，而不是工作线程。

一个请求可以混合阻塞和非阻塞操作：

上例在事件循环上获取电影，然后切换到工作线程获取角色。

给方法添加 @RunOnVirtualThread，即可在虚拟线程中执行查询：

请同时遵循虚拟线程的通用使用指南。

当存在 JTA 事务管理器（如 Hibernate ORM 或 quarkus-narayana-jta）时，扩展会自动为阻塞式 GraphQL 操作添加事务行为，等同于标注 @Transactional。这方便了需要读写数据库的解析器。

仅当以下条件全部满足时，才添加隐式事务：

• 存在 TRANSACTIONS 能力，即类路径中有 JTA 扩展。

• 不存在 Hibernate Reactive；后者由响应式会话自行管理事务。

• 方法位于 @GraphQLApi 类中，且是 GraphQL 操作：@Query、@Mutation、@Subscription、@Name、@Resolver 或 @Source 方法。

• 方法返回阻塞类型。Uni、Multi、CompletionStage、CompletableFuture、Publisher 等响应式返回类型不会被自动事务化。

• 方法没有 @NonBlocking。

• 方法尚未显式标注 @Transactional；显式配置总是优先。

若某个操作不需要此行为，例如调用的库自行管理 JDBC 事务，可以标注：

也可以使用 REQUIRES_NEW 等其他 TxType 控制事务参与方式，因为显式注解优先于隐式事务。

先为英雄增加盟友。

创建表示 Ally 的实体：

更新 GalaxyService，加入盟友：

更新 FilmResource，允许查询全部盟友：

在 UI 中执行：

Ally 与 Hero 有一些共同字段，因此可以为所有角色建立共同抽象。

创建描述共同角色特征的 Java 接口：

更新 Hero 和 Ally，实现该接口：

schema 随之改变，新增 Ally 类型和 Character 接口：

更新 GalaxyService，返回所有角色：

现在客户端可以查询全部角色，而不仅是英雄。

向 FilmResource 添加：

在 UI 中执行：

目前 API 只能直接查询某个实体或实体列表。现在希望支持跨实体搜索。Hero 和 Ally 共有 Character 抽象，但它不包含 Film。

创建表示搜索结果可能类型的新抽象：

让实体实现 SearchResult：

为 GalaxyService 添加搜索：

向 FilmResource 添加：

在 UI 中执行：

    @Mutation
    public Hero createHero(Hero hero) {
        service.addHero(hero);
        return hero;
    }

    @Mutation
    public Hero deleteHero(int id) {
        return service.deleteHero(id);
    }

mutation addHero {
  createHero(hero: {
      name: "Han",
      surname: "Solo"
      height: 1.85
      mass: 80
      darkSide: false
      episodeIds: [4, 5, 6]
  	}
  )
  {
    name
    surname
  }
}

mutation DeleteHero {
  deleteHero(id :3){
    name
    surname
  }
}

    BroadcastProcessor<Hero> processor = BroadcastProcessor.create(); (1)

    @Mutation
    public Hero createHero(Hero hero) {
        service.addHero(hero);
        processor.onNext(hero); (2)
        return hero;
    }

    @Subscription
    public Multi<Hero> heroCreated(){
        return processor; (3)
    }

subscription ListenForNewHeroes {
  heroCreated {
    name
    surname
  }
}

    @Query
    public List<Hero> getHeroesWithSurname(@DefaultValue("Skywalker") String surname) {
        return service.getHeroesBySurname(surname);
    }

query heroWithDefaultSurname {
  heroesWithSurname{
    name
    surname
    lightSaber
  }
}
query heroWithSurnames {
  heroesWithSurname(surname: "Vader") {
    name
    surname
    lightSaber
  }
}

@Inject
Context context;

    @Query
    @Description("Get a Films from a galaxy far far away")
    public Film getFilm(Context context, int filmId) {
        // ...
    }

上下文还提供访问底层 graphql-java 的接口：

schema 生成期间也可以访问底层 graphql-java，直接添加功能：

通过观察者，可向 schema builder 添加自定义内容。

另一项 SmallRye 专有实验功能，可以将已有标量对应的 Java 类型映射成其他标量类型，也可以将原本会生成 GraphQL Type 或 Input 的复杂对象映射到已有标量。

将已有标量映射为另一种类型

public class Movie {

    @AdaptToScalar(Scalar.Int.class)
    Long idLongThatShouldChangeToInt;

    // ....
}

将复杂对象映射为标量

public class Person {

    @AdaptToScalar(Scalar.String.class)
    Phone phone;

    // ....
}

public class Phone {

    private String number;

    // Getters and setters....

    public static Phone fromString(String number) {
        Phone phone = new Phone();
        phone.setNumber(number);
        return phone;
    }
}

更复杂的情况可以提供 Adapter，在其中自行完成映射。

AdaptWith 的详情见 JavaDoc。

例如：

Map 的键和值可能在运行时变化，因此难以描述在 schema 中，GraphQL 默认不支持 Map。Quarkus 利用上述适配机制，将 Map 映射为带有可选 key 参数的 Entry<Key,Value>，使你可以返回整个 Map，也可以按键查询。

例如：

查询整个 Map 的所有字段：

响应示例：

也可以按键查询：

此时只返回对应的值：

@ErrorCode("some-business-error-code")
public class SomeBusinessException extends RuntimeException {
    // ...
}

{
    "errors": [
        {
            "message": "Unexpected failure in the system. Jarvis is working to fix it.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": [
                "annotatedCustomBusinessException"
            ],
            "extensions": {
                "exception": "io.smallrye.graphql.test.apps.error.api.ErrorApi$AnnotatedCustomBusinessException",
                "classification": "DataFetchingException",
                "code": "some-business-error-code" (1)
            }
        }
    ],
    "data": {
        ...
    }
}

在 application.properties 中添加：

这会生成两个资源：

生成的代理导出 Queries、Mutations、Subscriptions 对象，以及底层 client 实例：

每个函数接收与 GraphQL 操作参数对应的 variables 对象。包含选择集的 GraphQL 查询字符串在构建时自动生成。

订阅操作返回 Subscription 对象：

订阅使用 graphql-transport-ws WebSocket 子协议。

需要更多控制时，可直接导入 GraphQLClient：