Projeto de API REST Vendas usando o framework Quarkus

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 plugin do Quarkus. O Visual Studio Code possui uma extensão para Quarkus também.

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

1. Requisitos

Maven 3.8.1+
JDK 17+

2. 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 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 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 .env.dist, devem ser criadas apenas no seu projeto no https://heroku.com.

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

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

4. Linux/macOS

./mvnw compile quarkus:dev

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

chmod +x ./mvnw

5. Windows

mvnw.cmd compile quarkus:dev

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

7. Executando os serviços REST

7.1. Usando o IntelliJ

No IntelliJ, ao abrir uma classe que representa um recurso REST, como a 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.

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:

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 do lado esquerdo.

7.2. 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 RESTClient.
Para o Google Chrome utilizo a excelente extensão 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.

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

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

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

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

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

java -jar target/*-runner.jar

9. 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 GraalVM instalada, execute:

./mvnw package -Pnative

Ou se você não tem a GraalVM mas tem o Docker instalado e rodando, você pode compilar um executável nativo em um contêiner usando:

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

Você pode rodar seu executável nativo com:

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

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

git push heroku main

📎	`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 Procfile.

11. Tutoriais sobre Quarkus e Heroku

REST resources for Hibernate ORM with Panache (guide): Generate JAX-RS resources for your Hibernate Panache entities and repositories
Hibernate ORM (guide): Define your persistent model with Hibernate ORM and JPA
Hibernate Validator (guide): Validate object properties (field, getter) and method parameters for your beans (REST, CDI, JPA)
SmallRye OpenAPI (guide): Document your REST APIs with OpenAPI - comes with Swagger UI
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 (guide): Simplify your persistence code for Hibernate ORM via the active record or the repository pattern
Agroal - Database connection pool (guide): Pool JDBC database connections (included in Hibernate ORM)
Getting Started on Heroku with Java.

manoelcampos / vendas-rest-quarkus Goto Github PK

vendas-rest-quarkus's Introduction