By Version

Criando sua primeira aplicação

Saiba como criar um aplicativo Hello World Quarkus. Este guia abrange:

Iniciando uma aplicação
Creating a JAX-RS endpoint
Injetando os beans
Testes funcionais
Empacotamento da aplicação

1. Pré-requisitos

Para concluir este guia, você precisa:

Cerca de 15 minutos
Um IDE
JDK 11+ instalado com 'JAVA_HOME' configurado adequadamente
Apache Maven 3.8.6
Opcionalmente, o Quarkus CLI se você quiser usá-lo

Certifique-se de que o Maven está usando a versão do Java que você espera

Se você tiver várias instalações do JDK, pode ser que o Maven não use o Java esperado e você pode acabar obtendo resultados inesperados. Você pode verificar qual JDK o Maven está usando executando o comando mvn —version.

2. Arquitetura

Neste guia, criamos um aplicativo simples que atende a um endpoint hello . Para demonstrar a injeção de dependência, esse endpoint usa um bean greeting .

Este guia também abrange o teste do endpoint.

3. Solução

We recommend that you follow the instructions from Bootstrapping project and onwards to create the application step by step.

No entanto, pode ir diretamente para o exemplo completo.

Baixe o arquivo ou clone o repositório git:

git clone https://github.com/quarkusio/quarkus-quickstarts.git

The solution is located in the getting-started directory.

4. Iniciando uma aplicação

A forma mais fácil de criar um novo projeto Quarkus é abrir um terminal e executar o seguinte comando:

For Linux & MacOS users

CLI

quarkus create app org.acme:getting-started \
    --stream=2.16 \
    --extension='resteasy-reactive'
cd getting-started

Para criar um projeto Gradle, adicione a opção --gradle ou --gradle-kotlin-dsl.

For more information about how to install the Quarkus CLI and use it, please refer to the Quarkus CLI guide.

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:2.16.12.Final:create \
    -DplatformVersion=2.16 \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -Dextensions='resteasy-reactive'
cd getting-started

Para criar um projeto Gradle, adicione a opção '-DbuildTool=gradle' ou '-DbuildTool=gradle-kotlin-dsl'.

For Windows users

If using cmd , (don’t use backward slash \ and put everything on the same line)
If using Powershell , wrap -D parameters in double quotes e.g. "-DprojectArtifactId=getting-started"

Isso gera o seguinte em `./getting-started:

a estrutura Maven
um resource org.acme.GreetingResource exposto em /hello
um teste unitário associado
uma landing page acessível em http://localhost:8080 depois de iniciar a aplicação
exemplo de arquivos Dockerfile para os modos native e jvm em src/main/docker
o arquivo de configuração da aplicação

Depois de gerado, consulte pom.xml . Você encontrará a importação do Quarkus BOM, que permite omitir a versão das diferentes dependências do Quarkus. Além disso, você pode ver o quarkus-maven-plugin responsável pelo empacotamento da aplicação e que também fornece o modo de desenvolvimento.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>${quarkus.platform.artifact-id}</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<build>
    <plugins>
        <plugin>
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>quarkus-maven-plugin</artifactId>
            <version>${quarkus.platform.version}</version>
            <extensions>true</extensions>
            <executions>
                <execution>
                    <goals>
                        <goal>build</goal>
                        <goal>generate-code</goal>
                        <goal>generate-code-tests</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

No projeto Gradle, você encontrará uma configuração semelhante:

o plugin Quarkus Gradle
uma diretiva enforcedPlatform para o Quarkus BOM

Se nos concentrarmos na seção das dependências, podemos ver que a extensão permite o desenvolvimento de aplicações REST:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-reactive</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-resteasy-reactive")

4.1. The JAX-RS resources

Durante a criação do projeto, o arquivo src/main/java/org/acme/GreetingResource.java foi criado com o seguinte conteúdo:

package org.acme;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/hello")
public class GreetingResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello from RESTEasy Reactive";
    }
}

É um endpoint REST muito simples, retornando "Hello from RESTEasy Reactive" para requests em "/hello".

Differences with vanilla JAX-RS

Com o Quarkus, não há necessidade de criar uma classe Application . Ela é suportada, mas não é obrigatória. Além disso, apenas uma instância do recurso é criada e não uma por request. Você pode configurar usando as diferentes anotações *Scoped ( ApplicationScoped , RequestScoped , etc).

5. Executando a aplicação

Agora estamos prontos para executar a nossa aplicação:

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

[INFO] --------------------< org.acme:getting-started >---------------------
[INFO] Building getting-started 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ getting-started ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] skip non existing resourceDirectory <path>/getting-started/src/main/resources
[INFO]
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ getting-started ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 2 source files to <path>/getting-started/target/classes
[INFO]
[INFO] --- quarkus-maven-plugin:<version>:dev (default-cli) @ getting-started ---
Listening for transport dt_socket at address: 5005
2019-02-28 17:05:22,347 INFO  [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation
2019-02-28 17:05:22,635 INFO  [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 288ms
2019-02-28 17:05:22,770 INFO  [io.quarkus] (main) Quarkus started in 0.668s. Listening on: http://localhost:8080
2019-02-28 17:05:22,771 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy-reactive]

Uma vez iniciado, você pode fazer o request no endpoint fornecido:

$ curl -w "\n" http://localhost:8080/hello
Hello from RESTEasy Reactive

Pressione CTRL+C para parar a aplicação, ou mantenha-a em execução e aproveite o fast hot-reload (reload automático incrivelmente rápido).

Adicione automaticamente uma quebra de linha com curl -w “\n”

Estamos usando curl -w “\n” neste exemplo para evitar que seu terminal imprima um ‘%’ ou coloque tanto o resultado quanto o próximo prompt de comando na mesma linha.

6. Utilizando injeção

A injeção de dependência no Quarkus é baseada no ArC, que é uma solução de injeção de dependência baseada em CDI adaptada à arquitetura do Quarkus. Se você não conhece CDI, recomendamos que leia o guia Introdução ao CDI .

O Quarkus apenas implementa um subconjunto das funcionalidades CDI e inclui funcionalidades não normalizadas e APIS específicos. Você pode obter mais informações sobre este assunto no guia Contexts and Dependency Injection.

O ArC vem como uma dependência do quarkus-resteasy-reactive, então você já o tem à disposição.

Vamos modificar a aplicação e adicionar um companion bean. Crie o arquivo src/main/java/org/acme/GreetingService.java com o seguinte conteúdo:

package org.acme;

import javax.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class GreetingService {

    public String greeting(String name) {
        return "hello " + name;
    }

}

Edite a classe GreetingResource para injetar o GreetingService e crie um novo endpoint utilizando-o:

package org.acme;

import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/hello")
public class GreetingResource {

    @Inject
    GreetingService service;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("/greeting/{name}")
    public String greeting(String name) {
        return service.greeting(name);
    }

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello from RESTEasy Reactive";
    }
}

Se você parou a aplicação (lembre-se de que não é necessário fazer isso, pois as alterações serão implantadas automaticamente pelo nosso recurso de reload automático), reinicie o aplicativo com:

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

Em seguida, verifique se o endpoint retorna hello quarkus como esperado:

$ curl -w "\n" http://localhost:8080/hello/greeting/quarkus
hello quarkus

7. Modo de desenvolvimento

quarkus:dev executa o Quarkus no modo de desenvolvimento. Isso habilita recarregamento automático com compilação em segundo plano, o que significa que, ao modificar seus arquivos Java e/ou seus arquivos de recursos e atualizar seu navegador, essas alterações entrarão automaticamente em vigor. Isso também funciona para arquivos de recursos, como o arquivo de configuração (properties) . Ao atualizar o navegador, é disparada uma verificação no espaço de trabalho e, se forem detectadas alterações, os arquivos Java são recompilados e a aplicação é redeployada; seu request é então atendido pela aplicação redeployada. Se houver problemas com a compilação ou o deployment, uma página de erro informará você.

Isso também escutará um depurador na porta 5005 . Se quiser aguardar a conexão do depurador antes de executá-lo, você pode passar -Dsuspend na linha de comando. Se você não quiser o depurador, pode usar -Ddebug=false .

8. Testando

Até agora, tudo bem, mas não seria melhor adicionar alguns testes, apenas por precaução?

No arquivo compilado gerado, é possível ver 2 dependências de teste:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-junit5</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>rest-assured</artifactId>
    <scope>test</scope>
</dependency>

build.gradle

testImplementation("io.quarkus:quarkus-junit5")
testImplementation("io.rest-assured:rest-assured")

O Quarkus suporta testes JUnit 5.

Por isso, no caso do Maven, a versão do plug-in Surefire Maven deve ser definida, pois a versão padrão não suporta o JUnit 5:

<plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>${surefire-plugin.version}</version>
    <configuration>
       <systemPropertyVariables>
          <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
          <maven.home>${maven.home}</maven.home>
       </systemPropertyVariables>
    </configuration>
</plugin>

Também definimos a propriedade do sistema java.util.logging para garantir que os testes usarão o gerenciador de logs correto e maven.home para garantir que a configuração personalizada de ${maven.home}/conf/settings.xml seja aplicada (se houver).

O projeto gerado contém um teste simples. Edite src/test/java/org/acme/GreetingResourceTest.java para corresponder ao conteúdo a seguir:

package org.acme;

import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import java.util.UUID;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;

@QuarkusTest
public class GreetingResourceTest {

    @Test    (1)
    public void testHelloEndpoint() {
        given()
          .when().get("/hello")
          .then()
             .statusCode(200)    (2)
             .body(is("Hello from RESTEasy Reactive"));
    }

    @Test
    public void testGreetingEndpoint() {
        String uuid = UUID.randomUUID().toString();
        given()
          .pathParam("name", uuid)
          .when().get("/hello/greeting/{name}")
          .then()
            .statusCode(200)
            .body(is("hello " + uuid));
    }

}

1	Ao utilizar o runner `QuarkusTest`, você informa ao JUnit para iniciar a aplicação antes dos testes.
2	Verificar o código de status e o conteúdo da resposta HTTP

Estes testes utilizam o RestAssured, mas sinta-se à vontade para utilizar a sua biblioteca favorita.

Você pode executá-los utilizando o Maven:

./mvnw test

Você também pode executar o teste diretamente a partir do seu IDE (certifique-se de que parou primeiro a aplicação).

Por padrão, os testes serão executados na porta 8081 para não entrar em conflito com o aplicativo em execução. Configuramos automaticamente o RestAssured para usar essa porta. Se quiser usar um cliente diferente, use a anotação @TestHTTPResource para injetar diretamente o URL do aplicativo testado em um campo da classe de teste. Esse campo pode ser do tipo String , URL ou URI . Essa anotação também pode receber um valor para o caminho do teste. Por exemplo, se eu quiser testar um Servlet mapeado para /myservlet , basta adicionar o seguinte no meu teste:

@TestHTTPResource("/myservlet")
URL testUrl;

A porta de teste pode ser controlada por meio da propriedade de configuração quarkus.http.test-port . O Quarkus também cria uma propriedade de sistema chamada test.url que é definida como o URL de teste básico para situações em que o usuário não pode usar injeção.

9. Trabalhar com projectos multi-módulos (multi-module) ou módulos externos

O Quarkus faz um uso intensivo do o Jandex durante o processo de compilação para descobrir várias classes ou anotações. Uma aplicação imediatamente reconhecível disso é a descoberta de bean CDI. Como resultado, a maioria das extensões do Quarkus não funcionará adequadamente se essa descoberta em tempo de compilação não estiver configurada corretamente.

Este índice é criado por padrão no projeto para o qual o Quarkus está configurado, graças aos nossos queridos plugins Maven e Gradle.

No entanto, ao trabalhar com um projeto de vários módulos (multi-module), não deixe de ler a seção Working with multi-module projects dos guias do Maven ou do Gradle .

Se você planeja usar módulos externos (por exemplo, uma biblioteca externa para todos os objetos do seu domínio), será necessário tornar esses módulos conhecidos pelo processo de indexação adicionando o plug-in Jandex (se puder modificá-los) ou por meio da propriedade quarkus.index-dependency dentro do seu application.properties (útil nos casos em que não é possível modificar o módulo).

Para mais informações, leia a seção Bean Discovery do guia CDI.

10. Empacotando e executando a aplicação

A aplicação é empacotada utilizando:

CLI

quarkus build

Maven

./mvnw install

Gradle

./gradlew build

Gera diversos resultados no diretório /target:

getting-started-1.0.0-SNAPSHOT.jar - contendo apenas as classes e os recursos dos projetos, é o artefato regular produzido pela compilação do Maven - não é o jar executável;
o diretório quarkus-app que contém o arquivo jar quarkus-run.jar , que é um jar executável. Esteja ciente de que não se trata de um über-jar , pois as dependências são copiadas para subdiretórios em quarkus-app/lib/ .

Você pode executar a aplicação utilizando: java -jar target/quarkus-app/quarkus-run.jar

Se você quiser implantar seu aplicativo em algum lugar (normalmente em um contêiner), você precisará implantar todo o diretório quarkus-app.

Antes de executar a aplicação, não se esqueça de parar o modo de recarregamento automático (hot reload) (pressione CTRL+C), ou terá um conflito de portas.

Por padrão, quando um aplicativo Quarkus é iniciado (no modo normal ou de desenvolvimento), ele exibe um banner de arte ASCII. O banner pode ser desativado definindo quarkus.banner.enabled=false em application.properties , definindo a propriedade do sistema Java -Dquarkus.banner.enabled=false ou definindo a variável de ambiente QUARKUS_BANNER_ENABLED como false . Além disso, os usuários podem fornecer um banner personalizado colocando o arquivo de banner em src/main/resources e configurando quarkus.banner.path=name-of-file em application.properties .

12. O que vem a seguir?

This guide covered the creation of an application using Quarkus. However, there is much more. We recommend continuing the journey with the building a native executable guide, where you learn about creating a native executable and packaging it in a container. If you are interested in reactive, we recommend the Getting Started with Reactive guide, where you can see how to implement reactive applications with Quarkus.

Além disso, o documento do guia de ferramentas explica como:

montar um projeto com uma única linha de comando
ativar o modo de desenvolvimento (hot reload)
importar o projeto no seu IDE favorito
e muito mais…

1. Pré-requisitos
2. Arquitetura
3. Solução
4. Iniciando uma aplicação
- 4.1. The JAX-RS resources
5. Executando a aplicação
6. Utilizando injeção
7. Modo de desenvolvimento
8. Testando
9. Trabalhar com projectos multi-módulos (multi-module) ou módulos externos
10. Empacotando e executando a aplicação
11. Configurando o banner
12. O que vem a seguir?

Criando sua primeira aplicação

1. Pré-requisitos

2. Arquitetura

3. Solução

4. Iniciando uma aplicação

4.1. The JAX-RS resources

5. Executando a aplicação

6. Utilizando injeção

7. Modo de desenvolvimento

8. Testando

9. Trabalhar com projectos multi-módulos (multi-module) ou módulos externos

10. Empacotando e executando a aplicação

11. Configurando o banner

12. O que vem a seguir?