Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/manoelcampos/vendas-rest-quarkus

Aplicação de exemplo implementando serviços REST com Quarkus Framework e hospedando no heroku.com
https://github.com/manoelcampos/vendas-rest-quarkus

heroku java java-11 jax-rs panache postgres quarkus rest rest-api resteasy

Last synced: 12 days ago
JSON representation

Aplicação de exemplo implementando serviços REST com Quarkus Framework e hospedando no heroku.com

Awesome Lists containing this project

README 

        
:source-highlighter: highlightjs

:numbered:

:imagesdir: images



ifdef::env-github[]

:outfilesuffix: .adoc

:caution-caption: :fire:

:important-caption: :exclamation:

:note-caption: :paperclip:

:tip-caption: :bulb:

:warning-caption: :warning:

endif::[]



= Projeto de API REST Vendas usando o framework Quarkus image:https://github.com/manoelcampos/vendas-rest-quarkus/actions/workflows/maven.yml/badge.svg[maven,link=https://github.com/manoelcampos/vendas-rest-quarkus/actions/workflows/maven.yml]



Este projeto usa o Quarkus, o *_Supersonic Subatomic Java Framework_*. A estrutura inicial deste projeto foi gerada em https://code.quarkus.io. Mas se você usa o IntelliJ IDEA Ultimate, ele já tem suporte nativo criar e executar projetos Quarkus. No IntelliJ Community, você pode instalar o https://plugins.jetbrains.com/plugin/13234-quarkus-tools[plugin do Quarkus]. O Visual Studio Code possui uma https://marketplace.visualstudio.com/items?itemName=redhat.vscode-quarkus[extensão para Quarkus] também.



Se você quer aprender mais sobre Quarkus, visite https://quarkus.io.



== Requisitos



- Maven 3.8.1+

- JDK 17+



== Configurando a aplicação para execução



Antes de rodar a aplicação você deve abrir o arquivo e verificar

se as configurações no arquivo link:src/main/resources/application.properties[application.properties] estão corretas para o seu ambiente de desenvolvimento (como o tipo de BD usado).



No ambiente de desenvolvimento (dev), não precisa de um arquivo `.env` pois todas as configurações necessárias estão definidas  no arquivo link:src/main/resources/application.properties[application.properties]. Em tal ambiente, está sendo usado o banco Apache H2 em memória, que não requer instalação ou configuração específica. Assim, as variáveis definidas no arquivo link:.env.dist[.env.dist], devem ser criadas apenas no seu projeto no https://heroku.com.



== Executando a aplicação em modo de desenvolvimento



Você pode rodar sua aplicação no mode dev, que habilita o _live coding_ usando os scripts `mvnw` na raiz do projeto, de acordo com o seu SO.



O _live coding_ é também conhecido como _hot reload_. Normalmente basta salvar as alterações no seu projeto e o Quarkus irá detectar as alterações, compilar e recarregar à aplicação. Tudo isso normalmente em uma fração de segundo.



NOTE: Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/.



== Linux/macOS



[source,shell script]

----

./mvnw compile quarkus:dev



----



Se der problema de permissão para execução do script, atribua tal permissão com: 



[source,shell script]

----

chmod +x ./mvnw

----



== Windows



[source,shell script]

----

mvnw.cmd compile quarkus:dev

----



== Dependências adicionais incluídas no projeto



Ao criar o projeto pelo https://code.quarkus.io, foram incluídas algumas dependências a mais:



- `quarkus-hibernate-orm`: Implementação do Hibernate da API Bean Validation para validar dados.

- `quarkus-hibernate-validator`: Implementação do Hibernate da API Bean Validation para validar dados.

- `quarkus-hibernate-orm-panache`: Usa a biblioteca https://quarkus.io/guides/hibernate-orm-panache[Quarkus Panache], que implementa o padrão _Active Record_ para as classes de negócio que precisam persistir no banco, dispensando implementação de DAO/Repository. Assim, todos os métodos CRUD padrão são automaticamente fornecidos.

- `quarkus-hibernate-orm-rest-data-panache`: Criar https://quarkus.io/guides/rest-data-panache[REST Resources] de forma simplificada, apenas criando interfaces.

- `quarkus-resteasy-reactive`: Implementação do padrão JAX-RS do JavaEE para fornecer serviços REST.

- `quarkus-resteasy-reactive-jackson`: Serialização de objetos Java para JSON usando a biblioteca Jackson, que fornece recursos adicionais, como as anotações @JsonIgnore.

- `quarkus-smallrye-openapi`: Criar documentação Swagger (OpenAPI) automaticamente.

- `quarkus-agroal`: Pool de conexões.

- `quarkus-jdbc-h2`: Usa banco https://www.h2database.com[Apache H2] em memória para o ambiente dev, que não requer instalação ou configurações específicas.

- `quarkus-jdbc-postgresql`: Usa banco PostgreSQL em produção (por exemplo no https://heroku.com).



== Executando os serviços REST



=== Usando o IntelliJ



No IntelliJ, ao abrir uma classe que representa um recurso REST,

como a link:src/main/java/com/manoelcampos/rest/CategoriaResource.java[CategoriaResource], cada método que representa um endpoint

(uma operação na sua API REST), terá um ícone de globo no lado esquerdo da declaração do método, como pode ver na imagem  aseguir.



image:try-rest-endpoint-intellij.png[]



Ao clicar, ele abre um editor para você digitar e enviar uma requisição HTTP para tal endpoint. No entanto, não há uma interface gráfica amigável para facilitar a criação da requisição HTTP.



Se você precisar enviar um conteúdo como JSON no corpo (body) da requisição,

precisará alterar a linha incluída pelo IntelliJ para algo como:



[source,httprequest]

----

POST http://localhost:8080/categoria

Content-Type: application/json



{

  "titulo": "Calçados",

  "descricao": "Calçados masculinos, femininos e infatis"

}

----



Para enviar a requisição, basta clicar no botão   image:play.png[]   do lado esquerdo.



=== Usando extensões dos navegadores



Você pode utilizar um browser para testar seus endpoints REST. Assim, você terá uma interface amigável e intuitiva, facilitando muito os testes. A seguir são exibidas opções para Firefox e Chrome.



* Para o Firefox você pode baixar o plugin https://addons.mozilla.org/pt-BR/firefox/addon/restclient/[RESTClient].

* Para o Google Chrome utilizo a excelente extensão https://chrome.google.com/webstore/detail/talend-api-tester-free-ed/aejoelaoggembcahagimdiliamlcdmfm[Talend API Tester (antigo Restlet Client)].



A extensão _Talend API Tester_ tem um recurso extremamente útil de permitir criar projetos e salvar diferentes requisições HTTP dentro deste projeto. Assim, podemos facilmente reenviar tais requisições sem ter que configurá-las novamente.



== Empacotando e executando a app para um ambiente de produção



Você pode empacotar o projeto (criar um arquivo jar) para distribuição usando:



[source,shell script]

----

./mvnw package

----



O comando gera um arquivo `quarkus-run.jar` no diretório `target/quarkus-app/`. Tenha em mente que este não é um _über-jar_ (que inclui todas as dependências) e as dependências são copiadas para `target/quarkus-app/lib/`.



Desta forma, a aplicação pode ser executada com `java -jar target/quarkus-app/quarkus-run.jar`.



Se você quer criar um _über-jar_, execute o comando:



[source,shell script]

----

./mvnw package -Dquarkus.package.type=uber-jar

----



Deste modo, a aplicação agora pode ser executada com:



[source,shell script]

----

java -jar target/*-runner.jar

----



== Compilando um executável nativo



Você pode criar um executável nativo, que não dependerá da JVM para rodar, reduzindo as exigências de espaço em disco e agilizando a inicialização e melhorando o desempenho geral da app.

Para isto, se você tiver a https://www.graalvm.org[GraalVM] instalada, execute:



[source,shell script]

----

./mvnw package -Pnative

----



Ou se você não tem a GraalVM mas tem o https://www.docker.com[Docker] instalado e rodando, você pode compilar um executável nativo em um contêiner usando:



[source,shell script]

----

./mvnw package -Pnative -Dquarkus.native.container-build=true

----



Você pode rodar seu executável nativo com:



[source,shell script]

----

./target/vendas-rest-quarkus-*-runner

----



== Hospedando a aplicação no Heroku



Antes de começar, você precisa criar um projeto lá no Heroku e criar algumas variáveis de ambiente na página de configuração do projeto lá. Veja as instruções no arquivo link:.env.dist[]



O Heroku permite integração com o GitHub para quando um push foi feito para tal repositório e a aplicação for compilada com sucesso, ele ser implantada/atualizada automaticamente no Heroku. Para isto funcionar, é preciso habilitar essa integração na sua aplicação no Heroku.



Se a integração com o GitHub não for feita, você pode https://devcenter.heroku.com/articles/git[fazer a implantação (deploy) da aplicação manualmente], sempre que for lançar uma nova versão. Depois de configurar seu repositório como indicado acima, para fazer a implantação, basta executar:



[source,shell script]

----

git push heroku main

----



NOTE: `main` é o nome do branch com a versão do app que deseja implantar. Este nome pode ser `master` dependendo de como criou o repositório git.



Se quiser testar localmente a aplicação antes de enviar para o Heroku, pode executar `heroku local`. Assim, o cliente heroku irá executar os mesmos passos que executaria remotamente para colocar a aplicação no ar, incluindo os comandos definidos no arquivo link:Procfile[Procfile].



== Tutoriais sobre Quarkus e Heroku



* REST resources for Hibernate ORM with Panache (https://quarkus.io/guides/rest-data-panache[guide]): Generate JAX-RS resources for your Hibernate Panache entities and repositories

* Hibernate ORM (https://quarkus.io/guides/hibernate-orm[guide]): Define your persistent model with Hibernate ORM and JPA

* Hibernate Validator (https://quarkus.io/guides/validation[guide]): Validate object properties (field, getter) and method parameters for your beans (REST, CDI, JPA)

* SmallRye OpenAPI (https://quarkus.io/guides/openapi-swaggerui[guide]): Document your REST APIs with OpenAPI - comes with Swagger UI

* RESTEasy Reactive (https://quarkus.io/guides/resteasy-reactive[guide]): A JAX-RS implementation utilizing build time processing and Vert.x. This extension is not compatible with the quarkus-resteasy extension, or any of the extensions that depend on it.

* Hibernate ORM with Panache (https://quarkus.io/guides/hibernate-orm-panache[guide]): Simplify your persistence code for Hibernate ORM via the active record or the repository pattern

* Agroal - Database connection pool (https://quarkus.io/guides/datasource[guide]): Pool JDBC database connections (included in Hibernate ORM)

* https://devcenter.heroku.com/articles/getting-started-with-java[Getting Started on Heroku with Java].