Создаем GraphQL API с помощью Guice и Spark

GraphQL это современный язык запросов для получения данных с сервера. Существует большое количество документации по построению API для целого вороха платформ, но к сожалению официальная документация для Java содержит лишь один пример, предполагающий построение приложения на базе Spring Framework. Пример скрывает некоторые детали реализации, заставляя пользователя читать исходники. В статье мы это исправим и создадим аналог на связке Google Guice и Spark. Перед тем как продолжить я рекомендую ознакомиться с оригинальным туторалом, т.к. я не буду углубляться в архитектуру библиотеки и описания сущностей GraphQL Java

1. Создание Guice приложения

За сборку приложения у нас будет отвечать Gradle. Для начала создайте новую папку, в ней терминал и введите gradle init

На предложенные вопросы нужно ответить следующим образом:

Select type of project to generate: application
Select implementation language: Java
Select build script DSL: Kotlin
Select test framework: JUnit Jupiter
Project name: guice-spark-graphql
Source package: guice.spark.graphql

Для вас будет создан шаблонный проект Java приложения с точкой входа в классе src/main/java/guice/spark/graphql/App.java

Далее нам следует объявить наши зависимости в файле build.gradle.kts

dependencies {
    // This dependency is used by the application.
    implementation("com.google.guava:guava:29.0-jre")
    //Guice
    implementation("com.google.inject:guice:5.0.1") //NEW

    //Spark
    implementation("com.sparkjava:spark-core:2.9.3") //NEW
    implementation("com.sparkjava:spark-template-velocity:2.7.1") ////NEW spark template engine
    implementation("org.slf4j:slf4j-simple:1.7.21") //NEW fix Spark SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
    implementation("com.fasterxml.jackson.core:jackson-databind:2.12.3") //NEW

    //graphql
    implementation("com.graphql-java:graphql-java:16.2") //NEW

    // Use JUnit Jupiter API for testing.
    testImplementation("org.junit.jupiter:junit-jupiter-api:5.6.2")

    // Use JUnit Jupiter Engine for testing.
    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.6.2")
}

Здесь мы добавляем зависимости от Guice, GraphQL и Spark вместе с Slf4j, Jackson и Velocity Template. Guava и тестовые зависимости необязательны, но с ними жить становится как-то проще

2. Схема данных GraphQL

Для использования GraphQL первым делом нужно объявить схему данных, которая будет описывать API. Создаем файл schema.graphqls в каталоге src/main/resources

type Query {
  bookById(id: ID): Book 
}

type Book {
  id: ID
  name: String
  pageCount: Int
  author: Author
}

type Author {
  id: ID
  firstName: String
  lastName: String
}

3. Настраиваем Guice

Создадим экземпляр Guice DI контейнера в файле src/main/java/guice/spark/graphql/App.java

public class App {
    @Inject
    private GraphQLService service;

    public static void main(String[] args) {
        App app = new App();

        Injector injector = Guice.createInjector(new GraphQLModule());
        injector.injectMembers(app);

        app.service.initialize();
    }
}

Guice создаст новый Injector, наполненный объявленными в модуле GraphQLModule компонентами. С помощью метода injector.injectMembers(app)в поле service окажется полностью собранный и готовый к использованию сервис GraphQLService, но перед этим подробнее остановимся том, как объявляются компоненты

4. GraphQLModule

Объявление компонентов в Guice происходит в модулях. Создадим файл src/main/java/guice/spark/graphql/GraphQLModule.java

public class GraphQLModule extends AbstractModule {
    protected void configure() {
        bind(GraphQLService.class).asEagerSingleton();
        bind(GraphQL.class).toProvider(GraphQlProvider.class).asEagerSingleton();
        bind(ObjectMapper.class).asEagerSingleton();
    }
}

Метод configureописывает базовую структуру нашего приложения:

• GraphQLService будет содержать логику инициализации контроллеров Spark и принимать запросы от внешних клиентов c помощью Spark, направляя их на обработку в инстанс GraphQL

• GraphQLбудет запрашивать необходимые данные и возвращать ответ

• ObjectMapperбудет все это дело сериализовать в JSON и возвращать обратно клиенту

5. GraphQlProvider

Для сложных случаев, например когда нам необходимо создавать наш GraphQLинстанс и при этом параметризовать его, мы используем механизм Provider в Guice, который служит фабрикой объектов. Создаем класс GraphQlProvider

public class GraphQlProvider implements Provider<GraphQL> {

    private GraphQLDataFetchers graphQLDataFetchers;

    @Inject
    public GraphQlProvider(GraphQLDataFetchers graphQLDataFetchers) {
        this.graphQLDataFetchers = graphQLDataFetchers;
    }

    @Override
    public GraphQL get() {
        URL url = Resources.getResource("schema.graphqls");
        String sdl = null;
        try {
            sdl = Resources.toString(url, Charsets.UTF_8);
        } catch (IOException e) {
            e.printStackTrace();
        }
        GraphQLSchema graphQLSchema = buildSchema(sdl);
        return GraphQL.newGraphQL(graphQLSchema).build(); 
    }

    private GraphQLSchema buildSchema(String sdl) {
        TypeDefinitionRegistry typeRegistry = new SchemaParser().parse(sdl);
        RuntimeWiring runtimeWiring = buildWiring();
        SchemaGenerator schemaGenerator = new SchemaGenerator();
        return schemaGenerator.makeExecutableSchema(typeRegistry, runtimeWiring);
    }

    private RuntimeWiring buildWiring() {
        return RuntimeWiring.newRuntimeWiring()
                .type(newTypeWiring("Query")
                        .dataFetcher("bookById", graphQLDataFetchers.getBookByIdDataFetcher()))
                .type(newTypeWiring("Book")
                        .dataFetcher("author", graphQLDataFetchers.getAuthorDataFetcher()))
                .build();
    }
}

Метод get() вернет нам готовый, настроенный GraphQL инстанс. При создании мы должны указать схему которую мы объявили выше, а также назначить обработчики поступающих запросов

6. GraphQLDataFetchers

DataFetcher это одна из самых важных концепций библиотеки GraphQL Java. DataFetcher содержит всю бинес-логику по обработке поступающих запросов.

Создадим файл src/main/java/guice/spark/graphql/GraphQLDataFetchers.java

@Singleton
public class GraphQLDataFetchers {
    private static List<Map<String, String>> books = Arrays.asList(
            ImmutableMap.of("id", "book-1",
                    "name", "Harry Potter and the Philosopher's Stone",
                    "pageCount", "223",
                    "authorId", "author-1"),
            ImmutableMap.of("id", "book-2",
                    "name", "Moby Dick",
                    "pageCount", "635",
                    "authorId", "author-2"),
            ImmutableMap.of("id", "book-3",
                    "name", "Interview with the vampire",
                    "pageCount", "371",
                    "authorId", "author-3")
    );

    private static List<Map<String, String>> authors = Arrays.asList(
            ImmutableMap.of("id", "author-1",
                    "firstName", "Joanne",
                    "lastName", "Rowling"),
            ImmutableMap.of("id", "author-2",
                    "firstName", "Herman",
                    "lastName", "Melville"),
            ImmutableMap.of("id", "author-3",
                    "firstName", "Anne",
                    "lastName", "Rice")
    );

    public DataFetcher getBookByIdDataFetcher() {
        return dataFetchingEnvironment -> {
            String bookId = dataFetchingEnvironment.getArgument("id");
            return books
                    .stream()
                    .filter(book -> book.get("id").equals(bookId))
                    .findFirst()
                    .orElse(null);
        };
    }

    public DataFetcher getAuthorDataFetcher() {
        return dataFetchingEnvironment -> {
            Map<String, String> book = dataFetchingEnvironment.getSource();
            String authorId = book.get("authorId");
            return authors
                    .stream()
                    .filter(author -> author.get("id").equals(authorId))
                    .findFirst()
                    .orElse(null);
        };
    }
}

Аннотация @Singletonсообщит Guice что если кто-то попытается получить инстанс этого класса он будет автоматически создан и предоставлен. В таких тривиальных случаях объявление в блоке configureмодуля GraphQLModuleне требуется, однако можно его там указать при желании - это повысит читабельность кода

7. GraphQLService

Пора предоставить возможность пользователям обращаться к нашему API по средствам web запросов. Как было сказано выше за это будет отвечать класс GraphQLService

Создадим его src/main/java/guice/spark/graphql/GraphQLService.java

public class GraphQLService {
    private final GraphQL graphQL;
    private final ObjectMapper mapper;

    @Inject
    public GraphQLService(GraphQL graphQL, ObjectMapper mapper) {
        this.graphQL = graphQL;
        this.mapper = mapper;
    }

    public void initialize() {
        post("/graphql", (request, response) -> {
            GraphQLRequestBody body = mapper.readValue(request.body(), GraphQLRequestBody.class);

            String query = body.getQuery();
            if (query == null) {
                query = "";
            }

            ExecutionResult executionResult = graphQL.execute(
                    ExecutionInput.newExecutionInput()
                            .query(query)
                            .operationName(body.getOperationName())
                            .variables(body.getVariables())
                            .build()
            );

            response.type("application/json");
            return mapper.writeValueAsString(executionResult.toSpecification());
        });
        
        get("/playground", (req, res) -> new VelocityTemplateEngine().render(
                new ModelAndView(Collections.emptyMap(), "playground.html"))
        );
    }

При первом обращении к методу initializeбудет запущен Jetty web server на дефолтном порту 4567. Мы предоставляем пользователю два ендпойнта:

При POST запросе на адрес http://localhost:4567/graphql ObjectMapper десериализует его в объект класса GraphQLRequestBody после чего отправит GraphQL инстансу на выполнение. Ответ виде JSON вернется обратно пользователю.

На всякий случай код класса GraphQLRequestBody:

public class GraphQLRequestBody {
    private String query;
    private String operationName;
    private Map<String, Object> variables;

    public String getQuery() {
        return query;
    }

    public void setQuery(String query) {
        this.query = query;
    }

    public String getOperationName() {
        return operationName;
    }

    public void setOperationName(String operationName) {
        this.operationName = operationName;
    }

    public Map<String, Object> getVariables() {
        return variables;
    }

    public void setVariables(Map<String, Object> variables) {
        this.variables = variables;
    }
}

При GET запросе на адрес http://localhost:4567/playground будет отрендерен playground.html файл, который также необходимо положить в папку src/main/resources. Это наш тул для проверки API прямо в браузере. Скачать его можно здесь

Теперь все готово и мы можем запустить приложение. Открываем браузере адрес http://localhost:4567/playground и видим нашу тестовую песочницу

Тестируем наш API

Все готово. Теперь на запрос:

query {
  bookById(id: "book-1") {
    name,
    author {
      firstName
    }
  }
}

вы должны получить ответ от API:

{
  "data": {
    "bookById": {
      "name": "Harry Potter and the Philosopher's Stone",
      "author": {
        "firstName": "Joanne"
      }
    }
  }
}

Полный исходный код и дополнительная информация

• Все исходники можно найти здесь https://github.com/fzn7/guice-spark-graphql

• Больше информации о GraphQL можно найти https://github.com/graphql-java/