Por Versão

Criando sua primeira aplicação

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

Iniciando uma aplicação
Criando um endpoint REST em Jakarta
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 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.9.9
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 the 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

A solução está localizada no diretório getting-started.

4. Iniciando uma aplicação

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

CLI

quarkus create app org.acme:getting-started \
    --extension='rest'
cd getting-started

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

Para obter mais informações sobre como instalar e usar a CLI do Quarkus, consulte o guia Quarkus CLI.

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.17.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -Dextensions='rest'
cd getting-started

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

Para usuários do Windows:

Se estiver usando cmd, (não use barra invertida '\' e coloque tudo na mesma linha)
Se estiver usando o Powershell, envolva os parâmetros '-D' entre aspas duplas, por exemplo, '"-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-rest</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-rest")

4.1. Os recursos Jakarta REST

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 jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

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

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

It’s a very simple REST endpoint, returning "Hello from Quarkus REST" to requests on "/hello".

Diferenças em relação ao Jakarta REST puro

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, rest]

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

$ curl -w "\n" http://localhost:8080/hello
Hello from Quarkus REST

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.

ArC comes as a dependency of quarkus-rest so you already have it handy.

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 jakarta.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 jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.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 Quarkus REST";
    }
}

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 Quarkus REST"));
    }

    @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

Quarkus heavily utilizes Jandex at build time, to discover various classes or annotations. One immediately recognizable application of this, is CDI bean discovery. As a result, most of the Quarkus extensions will not work properly if this build time discovery isn’t properly setup.

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

However, when working with a multi-module project, be sure to read the Working with multi-module projects section of the Maven or Gradle guides.

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. Endpoints não Relacionados à Aplicação

Várias extensões do Quarkus contribuem com endpoints que não são do aplicativo e que fornecem diferentes tipos de informações sobre o aplicativo. Exemplos dessas extensões são as extensões health , metrics , OpenAPI e extensões de informação.

Estes endpoints de aplicação não relacionados são normalmente acessíveis através do prefixo /q, da seguinte forma:

/q/health
/q/metrics
/q/openapi
/q/info

mas os usuários também podem optar por expor um que possa representar um risco de segurança numa porta TCP diferente, utilizando uma interface de gestão dedicada.

12.1. Endpoint de informação

Se a aplicação tiver a extensão quarkus-info, o Quarkus irá, por predefinição, expor o endpoint /q/info, que fornece informações sobre a compilação, a versão java, o controlo de versão e o sistema operacional. O nível de detalhes das informações expostas é configurável.

All CDI beans implementing the InfoContributor will be picked up and their data will be appended to the endpoint.

12.1.1. Referência de configuração

Propriedade de Configuração Fixa no Momento da Compilação - Todas as outras propriedades de configuração podem ser sobrepostas em tempo de execução.

Configuration property	Tipo	Padrão
`quarkus.info.enabled` Whether the info endpoint will be enabled Environment variable: `QUARKUS_INFO_ENABLED` Show more	boolean	`true`
`quarkus.info.path` The path under which the info endpoint will be located Environment variable: `QUARKUS_INFO_PATH` Show more	string	`info`
`quarkus.info.git.enabled` Whether git info will be included in the info endpoint Environment variable: `QUARKUS_INFO_GIT_ENABLED` Show more	boolean	`true`
`quarkus.info.git.mode` Controls how much information is present in the git section Environment variable: `QUARKUS_INFO_GIT_MODE` Show more	`standard`, `full`	`standard`
`quarkus.info.build.enabled` Whether build info will be included in the info endpoint Environment variable: `QUARKUS_INFO_BUILD_ENABLED` Show more	boolean	`true`
`quarkus.info.build."property-key"` Additional properties to be added to the build section Environment variable: `QUARKUS_INFO_BUILD__PROPERTY_KEY_` Show more	Map<String,String>
`quarkus.info.os.enabled` Whether os info will be included in the info endpoint Environment variable: `QUARKUS_INFO_OS_ENABLED` Show more	boolean	`true`
`quarkus.info.java.enabled` Whether java info will be included in the info endpoint Environment variable: `QUARKUS_INFO_JAVA_ENABLED` Show more	boolean	`true`

Configuration property

Tipo

Padrão

quarkus.info.enabled

Whether the info endpoint will be enabled

Environment variable: QUARKUS_INFO_ENABLED

boolean

true

quarkus.info.path

The path under which the info endpoint will be located

Environment variable: QUARKUS_INFO_PATH

string

info

quarkus.info.git.enabled

Whether git info will be included in the info endpoint

Environment variable: QUARKUS_INFO_GIT_ENABLED

boolean

true

quarkus.info.git.mode

Controls how much information is present in the git section

Environment variable: QUARKUS_INFO_GIT_MODE

standard, full

standard

quarkus.info.build.enabled

Whether build info will be included in the info endpoint

Environment variable: QUARKUS_INFO_BUILD_ENABLED

boolean

true

quarkus.info.build."property-key"

Additional properties to be added to the build section

Environment variable: QUARKUS_INFO_BUILD__PROPERTY_KEY_

Map<String,String>

quarkus.info.os.enabled

Whether os info will be included in the info endpoint

Environment variable: QUARKUS_INFO_OS_ENABLED

boolean

true

quarkus.info.java.enabled

Whether java info will be included in the info endpoint

Environment variable: QUARKUS_INFO_JAVA_ENABLED

boolean

true

13. E agora, o que vem por aí?

This guide covered the creation of an application using Quarkus. However, there is much more. We recommend continuing the journey by creating your second Quarkus application, with Dev Services and persistence. You can learn about creating a native executable and packaging it in a container with the building a native executable guide. 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. Os recursos Jakarta REST
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. Endpoints não Relacionados à Aplicação
- 12.1. Endpoint de informação
13. E agora, o que vem por aí?

Criando sua primeira aplicação

1. Pré-requisitos

2. Arquitetura

3. Solução

4. Iniciando uma aplicação

4.1. Os recursos Jakarta REST

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. Endpoints não Relacionados à Aplicação

12.1. Endpoint de informação

12.1.1. Referência de configuração

13. E agora, o que vem por aí?

Conteúdo Relacionado

Nos mesmos tópicos