The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Voltar aos Guias

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.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 .

Architecture

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.9.5: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

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.

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 append 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.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

quarkus.info.build

Additional properties to be added to the build section

Environment variable: QUARKUS_INFO_BUILD

Show more

Map<String,String>

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

Este guia abordou a criação de um aplicativo usando o Quarkus. No entanto, há muito mais pela frente. Recomendamos continuar a jornada criando sua segunda aplicação Quarkus, com serviços de desenvolvimento e persistência. seu segundo aplicativo Quarkus, Você pode aprender sobre a criação de um executável nativo e empacotá-lo em um contêiner com o guia de criação de um executável nativo guia de criação de um executável nativo. Se você estiver interessado em reatividade, sugerimos o guia de início com reatividade, onde você pode ver como implementar aplicações reativas com o 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…

Conteúdo Relacionado

Nos mesmos tópicos

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license.

This website was built with Jekyll, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

Navigation
Follow Us
Get Help
Languages
Quarkus is made of community projects
CC by 3.0 | Privacy Policy Sponsored by