DEV Community: Eduardo R. Ferreira

Capítulo 5: Construindo APIs RESTful com RESTEasy

Eduardo R. Ferreira — Wed, 18 Jun 2025 23:41:17 +0000

📚 Série: Quarkus: Desvendando o Desenvolvimento Moderno com Java

Este é o quinto capítulo de uma série completa sobre Quarkus. Prepare-se para uma jornada que vai transformar sua visão sobre desenvolvimento Java moderno!

Você já tem uma aplicação Quarkus funcionando e sabe como gerenciar dependências e configurações. Agora é hora de construir APIs que o mundo pode consumir! 🌍

No desenvolvimento moderno, APIs RESTful são a ponte entre diferentes sistemas - são elas que permitem que sua aplicação mobile converse com o backend, que microsserviços se comuniquem, e que sistemas externos integrem com sua solução.

O Quarkus, com sua integração otimizada com RESTEasy, torna a criação de APIs RESTful uma experiência incrível. Vamos descobrir como! 💪

🎯 O que você vai aprender

Conceitos fundamentais de REST e JAX-RS
Como criar endpoints REST no Quarkus
Tratamento robusto de erros e exceções
Validação profissional de dados
Manipulação de dados JSON/XML
Boas práticas para APIs de produção

🏗️ Fundamentos: REST e JAX-RS Explicados

REST: Mais que um Protocolo, uma Filosofia

REST (Representational State Transfer) não é apenas uma tecnologia - é um estilo arquitetural que define como sistemas distribuídos devem se comunicar.

Os pilares do REST são:

🎯 Recursos como Cidadãos de Primeira Classe

Tudo é um recurso: usuários, produtos, pedidos
Cada recurso tem uma URL única: /users/123, /products/456

🔄 Stateless por Design

Cada requisição é independente
O servidor não "lembra" de requisições anteriores
Isso facilita escalabilidade e cache

⚡ Verbos HTTP com Significado

GET → Buscar dados (sem efeitos colaterais)
POST → Criar novos recursos
PUT → Atualizar recursos completos
DELETE → Remover recursos
PATCH → Atualizações parciais

🎨 Múltiplas Representações

O mesmo recurso pode ser JSON, XML, HTML
O cliente escolhe o formato via headers

JAX-RS: REST para Desenvolvedores Java

JAX-RS (Java API for RESTful Web Services) é a especificação Java que transforma esses conceitos em código. É como ter um tradutor universal entre HTTP e Java.

// Isso é JAX-RS em ação! 🎉
@GET
@Path("/users/{id}")
@Produces("application/json")
public User getUser(@PathParam("id") Long id) {
    return findUserById(id);
}

O RESTEasy é uma das implementações mais robustas do JAX-RS, e o Quarkus o integra de forma nativa e supersônica! 🚄

🛠️ Mãos à Obra: Criando Nossa API de Produtos

Vamos construir uma API completa para gerenciar produtos. É um exemplo prático que você pode adaptar para qualquer domínio!

💡 Dica Pro: A dependencia quarkus-rest utiliza o resteasy-reactive é a versão mais moderna e performática. Ele usa programação reativa por baixo dos panos, mesmo que você escreva código "tradicional"!

Passo 1: O Modelo de Dados

Vamos criar nossa classe Product - simples, mas poderosa:

package com.example.model;

public class Product {
    public Long id;
    public String name;
    public String description;
    public Double price;

    // Construtor padrão (necessário para JSON)
    public Product() {}

    // Construtor completo
    public Product(Long id, String name, String description, Double price) {
        this.id = id;
        this.name = name;
        this.description = description;
        this.price = price;
    }

    // Método útil para debugging
    @Override
    public String toString() {
        return String.format("Product{id=%d, name='%s', price=%.2f}", 
                           id, name, price);
    }
}

🤔 Por que campos públicos? Quarkus foi desenhado para rodar de forma ultrarrápida, tanto no modo JVM quanto nativamente com GraalVM. Evitar reflection pesado, como o que é usado para acessar campos privados via getters/setters, melhora a performance da serialização/desserialização de JSON.

Frameworks como Jackson ou JSON-B conseguem acessar campos públicos diretamente, sem precisar de introspecção extra.

⚠️ Quando não usar campos públicos

Apesar da praticidade, campos públicos não são ideais em todos os cenários:

Quando você precisa de validações personalizadas ou lógica de negócio nos getters/setters.
Quando precisa proteger invariantes de estado da sua entidade.
Quando quer seguir padrões de encapsulamento rigorosos (como em DDD).

✅ Quando usar

Campos públicos são totalmente aceitáveis e até recomendados no Quarkus para:

DTOs
Modelos usados apenas para transporte
Testes e mocks
Classes simples e imutáveis

Passo 2: O Recurso REST - Onde a Mágica Acontece

Agora vem a parte mais interessante - nossa classe de recurso REST:

package com.example.resource;

import com.example.model.Product;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.atomic.AtomicLong;

@Path("/products")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ProductResource {

    // Simulando um banco de dados em memória
    private static final List<Product> products = new ArrayList<>();
    private static final AtomicLong idGenerator = new AtomicLong();

    // Dados de exemplo para testar
    static {
        products.add(new Product(
                idGenerator.incrementAndGet(),
                "MacBook Pro M3",
                "Laptop profissional para desenvolvimento",
                2999.99
        ));
        products.add(new Product(
                idGenerator.incrementAndGet(),
                "Mouse MX Master 3",
                "Mouse ergonômico para produtividade",
                89.99
        ));
        products.add(new Product(
                idGenerator.incrementAndGet(),
                "Teclado Mecânico RGB",
                "Teclado para gamers e desenvolvedores",
                159.99
        ));
    }

    @GET
    public List<Product> getAllProducts() {
        return products;
    }

    @GET
    @Path("/{id}")
    public Response getProductById(@PathParam("id") Long id) {
        Optional<Product> product = products.stream()
                .filter(p -> p.id == id)
                .findFirst();

        return product
                .map(p -> Response.ok(p).build())
                .orElse(Response.status(Response.Status.NOT_FOUND)
                        .entity("Produto não encontrado")
                        .build());
    }

    @POST
    public Response createProduct(Product product) {
        // Validação básica
        if (product.name == null || product.name.trim().isEmpty()) {
            return Response.status(Response.Status.BAD_REQUEST)
                    .entity("Nome do produto é obrigatório")
                    .build();
        }

        product.id = idGenerator.incrementAndGet();
        products.add(product);

        return Response.status(Response.Status.CREATED)
                .entity(product)
                .build();
    }

    @PUT
    @Path("/{id}")
    public Response updateProduct(@PathParam("id") Long id, Product updatedProduct) {
        Optional<Product> existingProduct = products.stream()
                .filter(p -> p.id == id)
                .findFirst();

        if (existingProduct.isPresent()) {
            Product product = existingProduct.get();
            product.name = updatedProduct.name;
            product.description = updatedProduct.description;
            product.price = updatedProduct.price;

            return Response.ok(product).build();
        }

        return Response.status(Response.Status.NOT_FOUND)
                .entity("Produto não encontrado")
                .build();
    }

    @DELETE
    @Path("/{id}")
    public Response deleteProduct(@PathParam("id") Long id) {
        boolean removed = products.removeIf(p -> p.id == id);

        if (removed) {
            return Response.noContent().build();
        }

        return Response.status(Response.Status.NOT_FOUND)
                .entity("Produto não encontrado")
                .build();
    }
}

🎯 Decifrando as Anotações JAX-RS

Cada anotação tem um propósito específico:

@Path("/products") → Define a URL base (/products)
@Produces(APPLICATION_JSON) → "Eu falo JSON!" 🗣️
@Consumes(APPLICATION_JSON) → "Eu entendo JSON!" 👂
@GET, @POST, etc. → Mapeia métodos HTTP
@PathParam("id") → Extrai valores da URL
Response → Controle total sobre status codes e headers

🧪 Testando Nossa API Básica

Inicie sua aplicação com:

mvn quarkus:dev

Agora você pode testar os endpoints:

📋 Listar todos os produtos

curl http://localhost:8080/products

🔍 Buscar produto específico

curl http://localhost:8080/products/1

➕ Criar novo produto

curl -X POST http://localhost:8080/products \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monitor 4K",
    "description": "Monitor ultrawide para programação",
    "price": 799.99
  }'

✏️ Atualizar produto

curl -X PUT http://localhost:8080/products/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MacBook Pro M3 - Atualizado",
    "description": "Versão atualizada com mais RAM",
    "price": 3299.99
  }'

🗑️ Deletar produto

curl -X DELETE http://localhost:8080/products/1

⚠️ Tratamento de Erros e Exceções

Agora que temos nossa API básica funcionando, precisamos torná-la robusta com um sistema profissional de tratamento de erros. Uma API robusta deve lidar graciosamente com situações inesperadas.

1. Exceções Personalizadas

Crie exceções específicas para seu domínio:

package com.example.exception;

public class ProductNotFoundException extends RuntimeException {
    public ProductNotFoundException(Long id) {
        super("Produto com ID " + id + " não foi encontrado");
    }
}

package com.example.exception;

public class InvalidProductDataException extends RuntimeException {
    public InvalidProductDataException(String message) {
        super(message);
    }
}

2. Classe de Resposta de Erro Padronizada

package com.example.exception;

import java.time.LocalDateTime;

public class ErrorResponse {
    public String code;
    public String message;
    public LocalDateTime timestamp;
    public String path;

    public ErrorResponse(String code, String message) {
        this.code = code;
        this.message = message;
        this.timestamp = LocalDateTime.now();
    }

    public ErrorResponse(String code, String message, String path) {
        this(code, message);
        this.path = path;
    }
}

3. Mapeadores de Exceção Globais

package com.example.exception;

import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;

@Provider
public class ProductNotFoundExceptionMapper implements ExceptionMapper<ProductNotFoundException> {

    @Override
    public Response toResponse(ProductNotFoundException exception) {
        return Response.status(Response.Status.NOT_FOUND)
                .entity(new ErrorResponse("PRODUCT_NOT_FOUND", exception.getMessage()))
                .build();
    }
}

package com.example.exception;

import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;

@Provider  
public class GeneralExceptionMapper implements ExceptionMapper<RuntimeException> {

    @Override
    public Response toResponse(RuntimeException exception) {
        // Log da exceção para monitoramento
        System.err.println("Erro interno: " + exception.getMessage());

        return Response.status(Response.Status.INTERNAL_SERVER_ERROR)
                .entity(new ErrorResponse("INTERNAL_ERROR", "Erro interno do servidor"))
                .build();
    }
}

4. Usando as Exceções no Resource

Agora podemos atualizar nosso resource para usar o sistema de tratamento de erros:

@GET
@Path("/{id}")
public Product getProductById(@PathParam("id") Long id) {
    return products.stream()
            .filter(p -> p.id.equals(id))
            .findFirst()
            .orElseThrow(() -> new ProductNotFoundException(id));
}

@POST
public Response createProduct(Product product) {
    // Validação de negócio usando nossa exceção personalizada
    if (products.stream().anyMatch(p -> p.name.equals(product.name))) {
        throw new InvalidProductDataException("Já existe um produto com este nome");
    }

    product.id = idGenerator.incrementAndGet();
    products.add(product);

    return Response.status(Response.Status.CREATED).entity(product).build();
}

Agora nossa API tem um sistema de tratamento de erros consistente e profissional! 🛡️

🛡️ Validação de Dados: Sua Primeira Linha de Defesa

Com o tratamento de erros implementado, podemos adicionar validação robusta que usa essas estruturas. APIs robustas nunca confiam nos dados que recebem!

Adicionando Bean Validation

Primeiro, adicione a extensão de validação:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-validator</artifactId>
</dependency>

Modelo com Validações

Atualize sua classe Product:

package com.example.model;

import jakarta.validation.constraints.*;

public class Product {
    public Long id;

    @NotBlank(message = "Nome é obrigatório")
    @Size(min = 2, max = 100, message = "Nome deve ter entre 2 e 100 caracteres")
    public String name;

    @Size(max = 500, message = "Descrição não pode exceder 500 caracteres")
    public String description;

    @NotNull(message = "Preço é obrigatório")
    @DecimalMin(value = "0.0", inclusive = false, message = "Preço deve ser maior que zero")
    @Digits(integer = 10, fraction = 2, message = "Preço deve ter no máximo 2 casas decimais")
    public Double price;

    public Product() {}

    public Product(Long id, String name, String description, Double price) {
        this.id = id;
        this.name = name;
        this.description = description;
        this.price = price;
    }
}

Ativando Validação nos Endpoints

Adicione @Valid nos métodos que recebem dados:

@POST
public Response createProduct(@Valid Product product) {
    product.id = idGenerator.incrementAndGet();
    products.add(product);
    return Response.status(Response.Status.CREATED).entity(product).build();
}

@PUT
@Path("/{id}")
public Response updateProduct(@PathParam("id") Long id, @Valid Product updatedProduct) {
    // ... resto do código
}

Personalizando Mensagens de Validação

Para ter controle total sobre as mensagens, você pode criar um tratador de exceções de validação que usa nossa estrutura de erro:

package com.example.exception;

import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;
import java.util.Set;
import java.util.stream.Collectors;

@Provider
public class ValidationExceptionMapper implements ExceptionMapper<ConstraintViolationException> {

    @Override
    public Response toResponse(ConstraintViolationException exception) {
        Set<ConstraintViolation<?>> violations = exception.getConstraintViolations();

        String errors = violations.stream()
                .map(violation -> {
                    // Extrai o último nome do caminho da propriedade
                    String path = violation.getPropertyPath().toString();
                    String field = path.contains(".") ? path.substring(path.lastIndexOf('.') + 1) : path;
                    return String.format("%s: %s", field, violation.getMessage());
                })
                .distinct()
                .collect(Collectors.joining(", "));

        return Response.status(Response.Status.BAD_REQUEST)
                .entity(new ErrorResponse("VALIDATION_ERROR", "Dados inválidos: " + errors))
                .build();
    }
}

Testando Validação

Tente criar um produto inválido:

curl -X POST http://localhost:8080/products \
  -H "Content-Type: application/json" \
  -d '{
    "name": "",
    "price": -10
  }'

Resposta esperada (Status: 400 Bad Request):

{
   "code":"VALIDATION_ERROR",
   "message":"Dados inválidos: price: Preço deve ser maior que zero, name: Nome deve ter entre 2 e 100 caracteres, name: Nome é obrigatório",
   "timestamp":"2025-06-17T21:54:22.5735566"
}

Agora nossa API tem validação consistente usando nosso sistema de tratamento de erros! 🎨

🎨 Suporte a Múltiplos Formatos

Embora JSON seja o padrão, às vezes você precisa suportar XML ou outros formatos. Com nossa base sólida de tratamento de erros e validação, podemos facilmente adicionar múltiplos formatos:

Para XML

Adicione a dependência JAXB:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-jaxb</artifactId>
</dependency>

Crie uma classe wrapper anotada com @XmlRootElement para encapsular a lista de produtos

package com.example.model;

import jakarta.xml.bind.annotation.XmlElement;
import jakarta.xml.bind.annotation.XmlRootElement;
import java.util.List;

@XmlRootElement(name = "products")
public class ProductList {

    private List<Product> products;

    public ProductList() {
        // necessário para JAXB
    }

    public ProductList(List<Product> products) {
        this.products = products;
    }

    @XmlElement(name = "product")
    public List<Product> getProducts() {
        return products;
    }

    public void setProducts(List<Product> products) {
        this.products = products;
    }
}

Adicione anotações JAXB no Modelo

package com.example.model;

import jakarta.xml.bind.annotation.XmlRootElement;
import jakarta.validation.constraints.*;

@XmlRootElement  // Necessário para XML
public class Product {
    public Long id;

    @NotBlank(message = "Nome é obrigatório")
    @Size(min = 2, max = 100, message = "Nome deve ter entre 2 e 100 caracteres")
    public String name;

    @Size(max = 500, message = "Descrição não pode exceder 500 caracteres")
    public String description;

    @NotNull(message = "Preço é obrigatório")
    @DecimalMin(value = "0.0", inclusive = false, message = "Preço deve ser maior que zero")
    public Double price;

    // ... construtores
}

Atualize as Anotações do Resource

@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public class ProductResource {

    @GET
    public ProductList getAllProducts() {
        return new ProductList(products);
    }

    // ... os outros métodos permanecem iguais
}

Testando XML

Receber resposta em XML:

curl -H "Accept: application/xml" http://localhost:8080/products/1

Resposta esperada:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<product>
    <id>1</id>
    <name>MacBook Pro M3</name>
    <description>Laptop profissional para desenvolvimento</description>
    <price>2999.99</price>
</product>

Enviar dados em XML:

curl -X POST http://localhost:8080/products \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
       <product>
         <name>Produto via XML</name>
         <description>Criado usando XML</description>
         <price>99.99</price>
       </product>'

🎭 Negociação de Conteúdo Automática

O RESTEasy faz negociação de conteúdo automaticamente baseada nos headers:

Accept: application/json → Resposta em JSON
Accept: application/xml → Resposta em XML
Accept: */* → JSON (padrão)
Content-Type: application/json → Lê JSON
Content-Type: application/xml → Lê XML

Outros Formatos Suportados

Para YAML (adicione quarkus-resteasy-reactive-yaml):

@Produces({MediaType.APPLICATION_JSON, "application/yaml"})

Para texto simples:

@GET
@Path("/info")
@Produces(MediaType.TEXT_PLAIN)
public String getInfo() {
    return "API de Produtos v1.0 - Total de produtos: " + products.size();
}

🚀 Dicas Pro para APIs de Produção

Com nossa base sólida (CRUD + tratamento de erros + validação + múltiplos formatos), podemos implementar recursos avançados para produção:

1. Paginação para Listas Grandes

Quando você tem milhares de produtos, retornar todos de uma vez não é viável:

@GET
public Response getAllProducts(
        @QueryParam("page") @DefaultValue("0") int page,
        @QueryParam("size") @DefaultValue("10") int size,
        @QueryParam("sort") @DefaultValue("id") String sortBy) {

    // Validação básica
    if (page < 0 || size < 1 || size > 100) {
        return Response.status(Response.Status.BAD_REQUEST)
                .entity(new ErrorResponse("INVALID_PARAMS", "Parâmetros de paginação inválidos"))
                .build();
    }

    // Simulando paginação (em um cenário real, isso viria do banco)
    int startIndex = page * size;
    int endIndex = Math.min(startIndex + size, products.size());

    List<Product> pageProducts = products.subList(startIndex, endIndex);

    return Response.ok(pageProducts)
            .header("X-Total-Count", products.size())
            .header("X-Page", page)
            .header("X-Page-Size", size)
            .build();
}

Testando paginação:

# Primeira página (produtos 0-2)
curl "http://localhost:8080/products?page=0&size=2"

# Segunda página (produto 3)  
curl "http://localhost:8080/products?page=1&size=2"

2. Filtros e Busca

Permita que os usuários encontrem o que procuram:

@GET
@Path("/search")
public Response searchProducts(
        @QueryParam("name") String name,
        @QueryParam("minPrice") Double minPrice,
        @QueryParam("maxPrice") Double maxPrice) {

    return Response.ok(products.stream()
                .filter(p -> name == null || p.name.toLowerCase().contains(name.toLowerCase()))
                .filter(p -> minPrice == null || p.price >= minPrice)
                .filter(p -> maxPrice == null || p.price <= maxPrice)
                .collect(Collectors.toList()))
                .build();
}

Exemplos de uso:

# Buscar produtos com "mac" no nome
curl "http://localhost:8080/products/search?name=mac"

# Produtos entre R$ 50 e R$ 200
curl "http://localhost:8080/products/search?minPrice=50&maxPrice=200"

# Combinar filtros
curl "http://localhost:8080/products/search?name=mouse&maxPrice=100"

3. Headers Úteis para Performance

@GET
@Path("/{id}")
public Response getProductById(@PathParam("id") Long id) {
    Optional<Product> product = findProductById(id);

    if (product.isPresent()) {
        return Response.ok(product.get())
                // Cache por 5 minutos
                .header("Cache-Control", "max-age=300")
                // ETag para versionamento
                .header("ETag", "\"" + product.get().hashCode() + "\"")
                // CORS headers
                .header("Access-Control-Allow-Origin", "*")
                .build();
    }

    throw new ProductNotFoundException(id);
}

4. Documentação com OpenAPI/Swagger

Adicione documentação automática:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

Anote seus endpoints se quiser personalizar:

import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.responses.ApiResponse;
import org.eclipse.microprofile.openapi.annotations.tags.Tag;

@Tag(name = "Produtos", description = "Operações relacionadas a produtos")
@Path("/products")
public class ProductResource {

    @GET
    @Operation(summary = "Listar todos os produtos", 
               description = "Retorna uma lista de todos os produtos disponíveis")
    @APIResponse(responseCode = "200", description = "Lista de produtos retornada com sucesso")
    public List<Product> getAllProducts() {
        return products;
    }

    @POST
    @Operation(summary = "Criar novo produto",
               description = "Cria um novo produto com os dados fornecidos")
    @APIResponse(responseCode = "201", description = "Produto criado com sucesso")
    @APIResponse(responseCode = "400", description = "Dados inválidos fornecidos")
    public Response createProduct(@Valid Product product) {
        // ... implementação
    }
}

Acesse a documentação:

Swagger UI: http://localhost:8080/q/swagger-ui/
OpenAPI JSON: http://localhost:8080/q/openapi

5. Versionamento de API

Quando sua API evolui, você precisa manter compatibilidade:

Opção 1: Versionamento por URL

@Path("/v1/products")
public class ProductResourceV1 {
    // Versão antiga da API
}

@Path("/v2/products") 
public class ProductResourceV2 {
    // Nova versão com recursos adicionais
}

Opção 2: Versionamento por Header

@GET
@Path("/products")
public Response getProducts(@HeaderParam("API-Version") String version) {
    if ("v2".equals(version)) {
        // Lógica da v2
        return Response.ok(enhancedProducts).build();
    }
    // Lógica padrão (v1)
    return Response.ok(products).build();
}

6. Rate Limiting Básico

Para APIs públicas, implemente limitação de taxa:

import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;

@Path("/products")
public class ProductResource {

    private final Map<String, AtomicInteger> requestCounts = new ConcurrentHashMap<>();
    private final int MAX_REQUESTS_PER_MINUTE = 100;

    @GET
    public Response getAllProducts(@Context HttpServletRequest request) {
        String clientIp = request.getRemoteAddr();

        // Verificar rate limit (implementação simplificada)
        AtomicInteger count = requestCounts.computeIfAbsent(clientIp, k -> new AtomicInteger(0));

        if (count.incrementAndGet() > MAX_REQUESTS_PER_MINUTE) {
            return Response.status(429) // Too Many Requests
                    .entity(new ErrorResponse("RATE_LIMIT_EXCEEDED", "Muitas requisições. Tente novamente em 60 segundos."))
                    .header("Retry-After", "60")
                    .build();
        }

        return Response.ok(products).build();
    }
}

🎯 Resumo do Capítulo

Parabéns! Você acabou de dominar a criação de APIs RESTful com Quarkus! 🎉

O que você conquistou:

✅ Entendeu os fundamentos de REST e JAX-RS

✅ Criou endpoints completos (CRUD)

✅ Implementou tratamento robusto de erros

✅ Adicionou validação profissional de dados

✅ Aprendeu sobre múltiplos formatos (JSON/XML)

✅ Descobriu dicas avançadas para APIs de produção

Sua API já está funcional e pronta para o mundo real! Mas ainda temos muito a explorar...

🔗 Continue a Jornada

👉 Capítulo 6: Persistência de Dados com Panache (Hibernate ORM) - Vamos conectar nossa API a um banco de dados utilizando Panache

💬 Vamos Conversar!

Gostou do capítulo? Tem alguma dúvida sobre APIs RESTful?

👍 Curta se foi útil
💬 Comente suas dúvidas ou experiências
🔔 Siga para não perder os próximos capítulos
🔄 Compartilhe com outros devs

Capítulo 4: Configuração de Aplicações Quarkus

Eduardo R. Ferreira — Tue, 17 Jun 2025 13:17:21 +0000

📚 Série: Quarkus: Desvendando o Desenvolvimento Moderno com Java

Este é o quarto capítulo de uma série completa sobre Quarkus. Prepare-se para uma jornada que vai transformar sua visão sobre desenvolvimento Java moderno!

Imagine desenvolver uma aplicação que funciona perfeitamente em desenvolvimento, mas quando chega à produção... 💥 BOOM! Problemas de configuração em todos os lugares. Familiar?

A configuração é literalmente o coração de qualquer aplicação moderna. É ela que permite que seu código se adapte graciosamente a diferentes ambientes sem precisar recompilar ou alterar uma única linha de código. No Quarkus, esse processo não é apenas simples - é elegante.

O Quarkus oferece um sistema de configuração robusto e flexível, baseado na especificação MicroProfile Config, que transforma o gerenciamento de propriedades em uma experiência quase mágica. Vamos descobrir como!

🚀 Gerenciamento de Propriedades: Seu Painel de Controle

No universo Quarkus, tudo começa com o arquivo src/main/resources/application.properties - seu painel de controle central. É aqui que você define as configurações que tornam sua aplicação inteligente e adaptável.

# application.properties - Seu centro de comando
quarkus.application.name=minha-super-app
quarkus.http.port=8080
minha.saudacao.personalizada=Bem-vindo ao poder do Quarkus!

Agora vem a parte interessante: como acessar essas propriedades no seu código? É aqui que a mágica do CDI se encontra com o sistema de configuração:

package com.example.resource;

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;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@Path("/config")
public class ConfigResource {

    @Inject
    @ConfigProperty(name = "quarkus.application.name")
    String nomeApp;

    @Inject
    @ConfigProperty(name = "minha.saudacao.personalizada", 
                   defaultValue = "Olá, desenvolvedor incrível!")
    String saudacaoPersonalizada;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String obterInfoConfiguracoes() {
        return String.format("""
            🎯 Nome da Aplicação: %s
            💬 Mensagem: %s
            """, nomeApp, saudacaoPersonalizada);
    }
}

🔥 Dica de Ouro: O defaultValue é seu melhor amigo! Ele garante que sua aplicação nunca quebre por causa de uma propriedade ausente, proporcionando uma experiência de desenvolvimento muito mais suave.

🎭 A Hierarquia das Configurações: Quem Manda Aqui?

Uma das funcionalidades mais poderosas do Quarkus é sua hierarquia de configurações. Imagine um sistema democrático onde cada fonte de configuração tem um "peso" diferente no voto final:

Ordem de Precedência (do menor para o maior poder):

🏠 Valores Padrão: Definidos no código via defaultValue
📄 application.properties: Seu arquivo de configuração base
🌍 Variáveis de Ambiente: Configurações do sistema operacional
⚡ Propriedades do Sistema Java: Passadas via linha de comando (-D)
🔧 MicroProfile Config Sources: Fontes customizadas avançadas

Exemplo Prático da Hierarquia:

# application.properties
quarkus.http.port=8080

# Variável de ambiente sobrescreve o arquivo
export QUARKUS_HTTP_PORT=9000

# Propriedade do sistema sobrescreve tudo
java -Dquarkus.http.port=8081 -jar minha-app-runner.jar

Resultado: Sua aplicação rodará na porta 8081 (a propriedade do sistema venceu)! 🏆

🎨 Perfis de Configuração: Uma Aplicação, Múltiplas Personalidades

Aqui está onde o Quarkus realmente brilha! Os perfis de configuração permitem que sua aplicação tenha diferentes "personalidades" dependendo do ambiente. É como ter múltiplos avatares no mesmo jogo!

Estrutura dos Arquivos de Perfil:

src/main/resources/
├── application.properties           # 🌟 Configurações globais
├── application-dev.properties       # 🛠️ Desenvolvimento
├── application-test.properties      # 🧪 Testes
└── application-prod.properties      # 🚀 Produção

Exemplo Completo de Configuração Multi-Ambiente:

application.properties (base para todos):

# Configurações compartilhadas
quarkus.application.name=minha-fantástica-app
quarkus.log.level=INFO

# Configurações que serão sobrescritas
meu.banco.url=jdbc:h2:mem:testdb
meu.servico.endpoint=http://localhost:8080/api
meu.cache.habilitado=false

application-dev.properties (desenvolvimento):

# Configurações específicas para desenvolvimento
meu.banco.url=jdbc:postgresql://localhost:5432/dev_db
meu.servico.endpoint=http://localhost:3000/api
quarkus.log.level=DEBUG
quarkus.live.reload.enabled=true

application-prod.properties (produção):

# Configurações otimizadas para produção
meu.banco.url=jdbc:postgresql://prod-cluster.empresa.com:5432/prod_db
meu.servico.endpoint=https://api.empresa.com/v1
meu.cache.habilitado=true
quarkus.log.level=WARN
quarkus.log.min-level=WARN

Ativando os Perfis:

# Desenvolvimento (padrão com quarkus:dev)
mvn quarkus:dev

# Teste (padrão ao executar testes)
mvn test

# Produção via variável de ambiente
export QUARKUS_PROFILE=prod
java -jar target/quarkus-app/quarkus-run.jar

# Produção via propriedade do sistema
java -Dquarkus.profile=prod -jar target/quarkus-app/quarkus-run.jar

💡 Exemplo Avançado: Configuração Inteligente

Vamos criar um exemplo mais sofisticado que demonstra o poder real do sistema de configuração:

package com.example.config;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import java.util.Optional;

@ApplicationScoped
public class ConfiguracaoApp {

    @Inject
    @ConfigProperty(name = "meu.servico.timeout", defaultValue = "5000")
    int timeoutServico;

    @Inject
    @ConfigProperty(name = "meu.cache.ttl", defaultValue = "3600")
    long cacheTtl;

    @Inject
    @ConfigProperty(name = "meu.debug.habilitado", defaultValue = "false")
    boolean debugHabilitado;

    // Propriedade opcional - pode não existir
    @Inject
    @ConfigProperty(name = "meu.feature.experimental")
    Optional<Boolean> featureExperimental;

    public String exibirConfiguracoes() {
        return String.format("""
            🔧 Configurações da Aplicação:
            ⏱️  Timeout do Serviço: %d ms
            💾 TTL do Cache: %d segundos
            🐛 Debug Habilitado: %s
            🧪 Feature Experimental: %s
            """,
                timeoutServico,
                cacheTtl,
                debugHabilitado ? "✅ Sim" : "❌ Não",
                featureExperimental.map(f -> f ? "✅ Ativa" : "❌ Inativa")
                        .orElse("🚫 Não configurada")
        );
    }
}

import com.example.config.ConfiguracaoApp;
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;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@Path("/config")
public class ConfigResource {

    @Inject
    @ConfigProperty(name = "quarkus.application.name")
    String nomeApp;

    @Inject
    @ConfigProperty(name = "minha.saudacao.personalizada", defaultValue = "Olá, desenvolvedor incrível!")
    String saudacaoPersonalizada;

    @Inject
    ConfiguracaoApp configuracaoApp;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String obterInfoConfiguracoes() {
        return String.format("""
            🎯 Nome da Aplicação: %s
            💬 Mensagem: %s
            """, nomeApp, saudacaoPersonalizada);
    }

    @GET
    @Path("/exibir")
    @Produces(MediaType.TEXT_PLAIN)
    public String exibirConfiguracoes() {
        return configuracaoApp.exibirConfiguracoes();
    }
}

🧪 Testando Nossa Aplicação

Execute a aplicação em modo de desenvolvimento:

mvn compile quarkus:dev

Teste os endpoints:

# Exemplo simples
curl "http://localhost:8080/config"

# Exemplo avançado
curl "http://localhost:8080/config/exibir"

🎯 Principais Vantagens do Sistema de Configuração do Quarkus

🔄 Zero Recompilação: Mude configurações sem rebuild
🌍 Multi-Ambiente: Uma aplicação, múltiplos comportamentos
🔒 Type-Safe: Injeção tipada de propriedades
⚡ Performance: Configurações resolvidas em tempo de compilação quando possível
📝 Documentação Automática: O Quarkus pode gerar documentação das suas configurações

🚀 Conclusão

O sistema de configuração do Quarkus não é apenas poderoso - é intuitivo e elegante. Ele transforma uma das tarefas mais tediosas do desenvolvimento (gerenciar configurações) em algo simples e prazeroso.

Com perfis, hierarquia de precedência e injeção tipada, você tem controle total sobre como sua aplicação se comporta em cada ambiente, mantendo seu código limpo e profissional.

No próximo capítulo, vamos mergulhar no mundo das APIs RESTful com RESTEasy e descobrir como criar endpoints poderosos e elegantes! 🎯

🔗 Continue a Jornada

👉 Capítulo 5: Construindo APIs RESTful com RESTEasy - Aprenda a construir uma API RESTful com Quarkus

💬 Gostou deste capítulo? Deixe um comentário contando qual aspecto da configuração do Quarkus mais te surpreendeu! E se você tem dúvidas sobre configurações específicas, compartilhe aqui - vamos resolver juntos!

🔔 Não perca os próximos capítulos! Siga-me aqui no Dev.to para receber notificações sempre que um novo capítulo for publicado.

Capítulo 3: Injeção de Dependências com CDI no Quarkus

Eduardo R. Ferreira — Tue, 17 Jun 2025 01:00:30 +0000

📚 Série: Quarkus: Desvendando o Desenvolvimento Moderno com Java

Este é o terceiro capítulo de uma série completa sobre Quarkus. Prepare-se para uma jornada que vai transformar sua visão sobre desenvolvimento Java moderno!

Se você chegou até aqui, já sabe que o Quarkus é um framework poderoso para construir aplicações Java modernas. Mas o que realmente faz a diferença entre uma aplicação bem estruturada e um "código espaguete"? A resposta está na Injeção de Dependências.

Hoje vamos mergulhar no CDI (Contexts and Dependency Injection), o coração que faz toda aplicação Quarkus bater de forma organizada e eficiente. 🚀

🎯 O que é Injeção de Dependências?

Imagine que você está construindo uma casa. Em vez de você mesmo fabricar cada tijolo, cada porta e cada janela, você recebe esses componentes prontos de fornecedores especializados. A Injeção de Dependências funciona de forma similar: em vez de sua classe criar suas próprias dependências, ela recebe objetos prontos de um "fornecedor" (o contêiner CDI).

Por que isso é revolucionário?

🧪 Testabilidade: Fácil de criar mocks e testes unitários
🔧 Manutenibilidade: Código mais limpo e modular
♻️ Reusabilidade: Componentes podem ser reutilizados facilmente
🔄 Flexibilidade: Troque implementações sem quebrar o código

📚 CDI: Contexts and Dependency Injection Explicado

O CDI é a especificação padrão do Jakarta EE (antigo Java EE) para gerenciar dependências, e o Quarkus a implementa de forma nativa e otimizada. Vamos entender os conceitos fundamentais:

🫘 Beans: Os Protagonistas do CDI

Beans são objetos gerenciados pelo contêiner CDI. Pense neles como "funcionários especializados" da sua aplicação - cada um tem uma função específica e o CDI se encarrega de coordená-los.

@ApplicationScoped
public class CalculadoraService {

    public double somar(double a, double b) {
        return a + b;
    }
}

🎯 Escopos: Definindo o Tempo de Vida

Os escopos determinam quando e por quanto tempo um bean existe na memória:

`@ApplicationScoped` - O Eterno

Uma única instância para toda a aplicação. Perfeito para serviços stateless.

@ApplicationScoped
public class ConfiguracaoService {

    private String versaoApp = "1.0.0";

    public String getVersaoApp() {
        return versaoApp;
    }
}

`@RequestScoped` - O Efêmero

Nova instância a cada requisição HTTP. Ideal para dados específicos da requisição.

@RequestScoped
public class ContadorRequisicaoService {

    private int contador = 0;

    public void incrementar() {
        contador++;
    }

    public int getContador() {
        return contador;
    }
}

`@Singleton` - O Único Verdadeiro

Garante uma única instância em toda a JVM, independente do contexto. Mais restritivo que @ApplicationScoped.

@Singleton
public class DatabaseConnectionPool {

    private final int maxConnections = 10;
    private int activeConnections = 0;

    public synchronized boolean acquireConnection() {
        if (activeConnections < maxConnections) {
            activeConnections++;
            return true;
        }
        return false;
    }

    public synchronized void releaseConnection() {
        if (activeConnections > 0) {
            activeConnections--;
        }
    }
}

`@Dependent` - O Dependente

Vive e morre junto com quem o utiliza.

@Dependent
public class UtilService {

    public String formatarTexto(String texto) {
        return texto.toUpperCase().trim();
    }
}

🔍 ApplicationScoped vs Singleton: Qual a Diferença?

Esta é uma dúvida muito comum! Ambos criam uma única instância, mas há diferenças importantes:

`@ApplicationScoped`

Contexto: Ligado ao contexto da aplicação CDI
Proxy: Cria um proxy para lazy loading
Flexibilidade: Pode ser desabilitado/reabilitado em contextos específicos
Performance: Pequeno overhead do proxy

`@Singleton`

Contexto: Independente de qualquer contexto CDI
Instanciação: Criação direta, sem proxy
Rigidez: Sempre ativa, não pode ser desabilitada
Performance: Acesso direto, sem overhead

Quando usar cada um?

// Use @ApplicationScoped para serviços de negócio
@ApplicationScoped
public class PedidoService {
    // Lógica de negócio que pode precisar ser mockada em testes
}

// Use @Singleton para recursos compartilhados críticos
@Singleton
public class MetricsCollector {
    // Recursos que NUNCA devem ter múltiplas instâncias
}

💉 Injeção Básica: Primeiros Passos

Vamos começar com exemplos simples para entender como a injeção funciona na prática:

1. Criando o Serviço de Saudação

package com.example.service;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class GreetingService {

    public String criarSaudacao(String nome) {
        if (nome == null || nome.trim().isEmpty()) {
            return "Olá, visitante anônimo! 👋";
        }
        return String.format("Olá, %s! Bem-vindo ao mundo Quarkus! 🚀", nome);
    }

    public String criarSaudacaoPersonalizada(String nome, String idioma) {
        if (nome == null || nome.trim().isEmpty()) {
            nome = "visitante";
        }

        return switch (idioma.toLowerCase()) {
            case "en" -> String.format("Hello, %s! Welcome to Quarkus world! 🚀", nome);
            case "es" -> String.format("¡Hola, %s! ¡Bienvenido al mundo Quarkus! 🚀", nome);
            case "fr" -> String.format("Bonjour, %s! Bienvenue dans le monde Quarkus! 🚀", nome);
            default -> String.format("Olá, %s! Bem-vindo ao mundo Quarkus! 🚀", nome);
        };
    }
}

2. Criando o Contador de Requisições

package com.example.service;

import jakarta.enterprise.context.RequestScoped;

@RequestScoped
public class RequestCounterService {

    private int contador = 0;
    private final long timestampInicializacao = System.currentTimeMillis();

    public void incrementar() {
        contador++;
    }

    public int getContador() {
        return contador;
    }

    public long getTempoVida() {
        return System.currentTimeMillis() - timestampInicializacao;
    }

    public String getEstatisticas() {
        return String.format("Requisições: %d | Tempo de vida: %d ms", 
                           contador, getTempoVida());
    }
}

3. Usando Injeção no Resource

package com.example.resource;

import com.example.service.GreetingService;
import com.example.service.RequestCounterService;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;

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

    @Inject
    GreetingService greetingService;

    @Inject
    RequestCounterService requestCounterService;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        requestCounterService.incrementar();

        String saudacao = greetingService.criarSaudacao("Mundo Quarkus");
        String estatisticas = requestCounterService.getEstatisticas();

        return String.format("%s\n📊 %s", saudacao, estatisticas);
    }

    @GET
    @Path("/personalizada")
    @Produces(MediaType.TEXT_PLAIN)
    public String helloPersonalizada(
            @QueryParam("nome") String nome,
            @QueryParam("idioma") String idioma) {

        requestCounterService.incrementar();

        if (idioma == null) {
            idioma = "pt";
        }

        String saudacao = greetingService.criarSaudacaoPersonalizada(nome, idioma);
        String estatisticas = requestCounterService.getEstatisticas();

        return String.format("%s\n📊 %s", saudacao, estatisticas);
    }
}

🎭 Interfaces e CDI: Programação Contra Abstrações

Agora que entendemos a injeção básica, vamos para um nível mais avançado: usando interfaces para criar código verdadeiramente desacoplado.

Por que usar Interfaces com CDI?

// ❌ Acoplamento forte - difícil de testar e modificar
@ApplicationScoped
public class EmailService {
    public void enviarEmail(String destinatario, String mensagem) {
        // Implementação específica de email
    }
}

// ✅ Baixo acoplamento - flexível e testável
public interface NotificationService {
    void enviarNotificacao(String destinatario, String mensagem);
}

@ApplicationScoped
public class EmailNotificationService implements NotificationService {
    @Override
    public void enviarNotificacao(String destinatario, String mensagem) {
        // Implementação específica de email
    }
}

Exemplo Avançado: Sistema de Notificações

Vamos criar um sistema que pode enviar notificações por diferentes canais:

// Interface base
package com.example.service;

public interface NotificationService {
    void enviarNotificacao(String destinatario, String mensagem);
    String getTipoNotificacao();
}

// Implementação para Email
package com.example.service;

import com.example.qualifier.Email;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class EmailNotificationService implements NotificationService {

    @Override
    public void enviarNotificacao(String destinatario, String mensagem) {
        System.out.println("📧 Enviando email para: " + destinatario);
        System.out.println("Mensagem: " + mensagem);
    }

    @Override
    public String getTipoNotificacao() {
        return "EMAIL";
    }
}

// Implementação para SMS
package com.example.service;

import com.example.qualifier.Sms;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class SmsNotificationService implements NotificationService {

    @Override
    public void enviarNotificacao(String destinatario, String mensagem) {
        System.out.println("📱 Enviando SMS para: " + destinatario);
        System.out.println("Mensagem: " + mensagem);
    }

    @Override
    public String getTipoNotificacao() {
        return "SMS";
    }
}

Resolvendo Ambiguidade com Qualifiers

Quando você tem múltiplas implementações da mesma interface, o CDI precisa saber qual usar. Aqui entram os Qualifiers:

package com.example.qualifier;

import jakarta.inject.Qualifier;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Qualifier
@Retention(RUNTIME)
@Target({METHOD, FIELD, PARAMETER, TYPE})
public @interface Email {
}

package com.example.qualifier;

import jakarta.inject.Qualifier;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Qualifier
@Retention(RUNTIME)
@Target({METHOD, FIELD, PARAMETER, TYPE})
public @interface Sms {
}

Agora marcamos nossas implementações:

@Email
@ApplicationScoped
public class EmailNotificationService implements NotificationService {
    // ... implementação
}

@Sms
@ApplicationScoped
public class SmsNotificationService implements NotificationService {
    // ... implementação
}

Criando o DTO para Requisições

package com.example.dto;

public class NotificationRequest {

    private String destinatario;
    private String mensagem;

    // Construtores
    public NotificationRequest() {}

    public NotificationRequest(String destinatario, String mensagem) {
        this.destinatario = destinatario;
        this.mensagem = mensagem;
    }

    // Getters e Setters
    public String getDestinatario() {
        return destinatario;
    }

    public void setDestinatario(String destinatario) {
        this.destinatario = destinatario;
    }

    public String getMensagem() {
        return mensagem;
    }

    public void setMensagem(String mensagem) {
        this.mensagem = mensagem;
    }
}

Injetando Implementações Específicas

package com.example.resource;

import com.example.dto.NotificationRequest;
import com.example.qualifier.Email;
import com.example.qualifier.Sms;
import com.example.service.NotificationService;
import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.core.MediaType;

@Path("/notifications")
public class NotificationResource {

    @Inject
    @Email
    NotificationService emailService;

    @Inject
    @Sms
    NotificationService smsService;

    @POST
    @Path("/email")
    @Consumes(MediaType.APPLICATION_JSON)
    public String enviarEmail(NotificationRequest request) {
        emailService.enviarNotificacao(request.getDestinatario(), request.getMensagem());
        return "Email enviado com sucesso!";
    }

    @POST
    @Path("/sms")
    @Consumes(MediaType.APPLICATION_JSON)
    public String enviarSms(NotificationRequest request) {
        smsService.enviarNotificacao(request.getDestinatario(), request.getMensagem());
        return "SMS enviado com sucesso!";
    }
}

Descoberta Dinâmica com Any e Instance

O CDI oferece uma forma elegante de trabalhar com múltiplas implementações:

package com.example.resource;

import com.example.dto.NotificationRequest;
import com.example.qualifier.Email;
import com.example.qualifier.Sms;
import com.example.service.NotificationService;
import jakarta.enterprise.inject.Any;
import jakarta.enterprise.inject.Instance;
import jakarta.inject.Inject;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;

import java.util.List;
import java.util.stream.Collectors;

@Path("/notifications")
public class NotificationResource {

    @Inject
    @Any
    Instance<NotificationService> notificationServices;

    @GET
    @Path("/tipos")
    @Produces(MediaType.APPLICATION_JSON)
    public List<String> listarTiposNotificacao() {
        return notificationServices.stream()
                .map(NotificationService::getTipoNotificacao)
                .collect(Collectors.toList());
    }

    @POST
    @Path("/all")
    @Consumes(MediaType.APPLICATION_JSON)
    public String enviarParaTodos(NotificationRequest request) {
        notificationServices.forEach(service -> 
            service.enviarNotificacao(request.getDestinatario(), request.getMensagem())
        );
        return "Notificação enviada por todos os canais!";
    }
}

🧪 Testando Nossa Aplicação

Adicione a extensão "rest-jsonb" ao seu projeto:

mvn quarkus:add-extension -Dextensions="rest-jsonb"

Execute a aplicação em modo de desenvolvimento:

mvn compile quarkus:dev

Teste os endpoints básicos:

# Saudação simples
curl http://localhost:8080/hello

# Saudação personalizada em português
curl "http://localhost:8080/hello/personalizada?nome=João&idioma=pt"

# Saudação personalizada em inglês
curl "http://localhost:8080/hello/personalizada?nome=John&idioma=en"

Teste os endpoints de notificação:

# Listar tipos de notificação disponíveis
curl http://localhost:8080/notifications/tipos

# Enviar email
curl -X POST http://localhost:8080/notifications/email \
  -H "Content-Type: application/json" \
  -d '{"destinatario":"joao@email.com","mensagem":"Olá do Quarkus!"}'

# Enviar SMS
curl -X POST http://localhost:8080/notifications/sms \
  -H "Content-Type: application/json" \
  -d '{"destinatario":"11999999999","mensagem":"Olá do Quarkus!"}'

# Enviar para todos os canais
curl -X POST http://localhost:8080/notifications/all \
  -H "Content-Type: application/json" \
  -d '{"destinatario":"contato","mensagem":"Mensagem broadcast!"}'

🧪 Testando com Interfaces: A Mágica dos Mocks

Com interfaces, criar testes fica muito mais simples:

package com.example.resource;

import io.quarkus.test.junit.QuarkusTest;
import jakarta.ws.rs.core.MediaType;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.containsString;

@QuarkusTest
class NotificationResourceTest {

    @Test
    void testEmailNotification() {
        // O Quarkus facilita a criação de mocks para interfaces
        String json = """
                    {
                        "destinatario": "test@email.com",
                        "mensagem": "Teste"
                    }
                """;

        given()
                .contentType(MediaType.APPLICATION_JSON)
                .body(json)
                .when()
                .post("/notifications/email")
                .then()
                .statusCode(200)
                .body(containsString("Email enviado com sucesso"));
    }
}

🎓 O Poder da Arquitetura CDI

O que acabamos de construir demonstra os princípios fundamentais de uma arquitetura bem estruturada:

Separação de Responsabilidades

GreetingService: Especializado em criar saudações
RequestCounterService: Especializado em contar requisições
NotificationService: Interface para diferentes tipos de notificação
GreetingResource: Especializado em expor endpoints REST

Baixo Acoplamento

Cada classe depende apenas de abstrações (interfaces), não de implementações concretas. Se precisarmos mudar de email para webhook, alteramos apenas a implementação da interface NotificationService.

Alta Testabilidade

Com CDI, criar testes unitários fica muito mais simples. Podemos facilmente criar mocks dos serviços:

@Test
void testGreetingResource() {
    // O CDI permite injetar mocks facilmente em testes
    GreetingService mockService = Mockito.mock(GreetingService.class);
    // ... resto do teste
}

Vantagens das Interfaces no CDI

🧪 Testabilidade Suprema: Fácil criação de mocks
🔄 Flexibilidade: Troque implementações sem alterar código cliente
📏 SOLID Principles: Dependency Inversion Principle na prática
🎭 Polimorfismo: Uma interface, múltiplas implementações

🚀 Otimizações do Quarkus

Uma das grandes vantagens do Quarkus é como ele otimiza o CDI:

Build Time Processing: Muito do trabalho de injeção acontece em tempo de build, não em runtime
Startup Rápido: Menos processamento na inicialização = startup mais rápido
Menor Consumo de Memória: Footprint reduzido comparado a frameworks tradicionais

💡 Dicas Importantes

⚠️ Cuidados com Escopos

@ApplicationScoped: Use para serviços stateless ou com estado thread-safe
@RequestScoped: Perfeito quando precisar de estado por requisição
@Singleton: Reserve para recursos críticos que devem ter instância única
Thread Safety: @ApplicationScoped e @Singleton precisam ser thread-safe se mantiverem estado

Exemplo de Thread Safety:

@ApplicationScoped
public class ContadorGlobalService {

    private final AtomicInteger contador = new AtomicInteger(0);

    public int incrementar() {
        return contador.incrementAndGet(); // Thread-safe
    }
}

🔍 Debugging CDI

Se você encontrar problemas com injeção, use:

mvn compile quarkus:dev -Dquarkus.arc.debug=true

🎯 Próximos Passos

No próximo capítulo, vamos aprender como configurar nossas aplicações Quarkus de forma profissional, explorando arquivos de propriedades, profiles e configurações externalizadas.

🔗 Continue a Jornada

👉 Capítulo 4: Configuração de Aplicações Quarkus - Aprenda a configurar sua aplicação como um profissional

🤝 Vamos Conversar!

O que você achou da injeção de dependências com CDI? Já teve experiência com outros frameworks de DI? Compartilhe sua experiência nos comentários!

Se este conteúdo foi útil para você:

👍 Deixe seu like
💬 Comente suas dúvidas ou sugestões
🔄 Compartilhe com outros desenvolvedores
👥 Me siga para não perder os próximos capítulos

Capítulo 2: Primeiros Passos com Quarkus

Eduardo R. Ferreira — Fri, 13 Jun 2025 14:44:31 +0000

📚 Série: Quarkus: Desvendando o Desenvolvimento Moderno com Java

Este é o segundo capítulo de uma série completa sobre Quarkus. Prepare-se para uma jornada que vai transformar sua visão sobre desenvolvimento Java moderno!

Agora que você já conhece o poder do Quarkus e suas vantagens, chegou a hora de colocar a mão na massa! Neste capítulo, vamos configurar seu ambiente de desenvolvimento, criar sua primeira aplicação "Hello World" e explorar o famoso Live Coding que vai revolucionar sua produtividade.

Se você é daqueles desenvolvedores que ama ver o código funcionando rapidamente, prepare-se para se apaixonar pelo Quarkus! 💜

🛠️ Configurando seu Ambiente de Desenvolvimento

Antes de mergulharmos no código, vamos preparar nosso ambiente. Não se preocupe, é mais simples do que parece!

1. Java Development Kit (JDK)

O Quarkus precisa do JDK 11 ou superior. Minha recomendação pessoal? Use uma versão LTS como JDK 17 ou JDK 21 - são mais estáveis e têm suporte garantido por anos.

Onde baixar:

Adoptium (OpenJDK) - gratuito e confiável
Amazon Corretto - versão da Amazon
Oracle JDK - versão oficial

Testando a instalação:

java -version
javac -version

Você deve ver algo como:

java version "17.0.8" 2023-07-18 LTS
Java(TM) SE Runtime Environment (build 17.0.8+9-LTS-211)

2. Sistema de Build: Maven ou Gradle

O Quarkus abraça tanto o Maven quanto o Gradle. Nesta série, usaremos o Maven por ser mais comum na comunidade Java, mas fique tranquilo - os conceitos se aplicam perfeitamente ao Gradle também.

Instalando o Maven:

Baixe em maven.apache.org
Configure as variáveis de ambiente
Teste com: mvn -v

3. IDE: Seu Melhor Amigo

Embora você possa usar qualquer editor de texto, uma boa IDE faz toda a diferença:

IntelliJ IDEA (Community é gratuita!) - minha preferida
VS Code com extensões Java - leve e poderosa
Eclipse com Quarkus Tools - clássica e confiável

4. Quarkus CLI (Recomendado!)

A CLI do Quarkus é como ter um assistente pessoal para seus projetos. Facilita tudo: criação de projetos, adição de extensões e muito mais.

Instalação:

Siga as instruções em quarkus.io/guides/cli-tooling
Teste com: quarkus --version

🎯 Criando sua Primeira Aplicação: Hello Quarkus!

Agora vem a parte divertida! Vamos criar nosso primeiro projeto Quarkus. Abra seu terminal favorito e vamos nessa:

⚠️ Evite usar Git Bash no Windows para rodar comandos Maven com -D
Ele pode interpretar os argumentos de forma incorreta.
✅ Use o Prompt de Comando (cmd) ou o PowerShell para evitar erros.

mvn io.quarkus.platform:quarkus-maven-plugin:3.6.4:create -DprojectGroupId=com.example -DprojectArtifactId=hello-quarkus -DclassName="com.example.GreetingResource" -Dpath="/hello"

🔍 Decifrando o comando:

quarkus-maven-plugin:3.6.4:create - invoca o plugin do Quarkus
projectGroupId=com.example - identificação do seu projeto
projectArtifactId=hello-quarkus - nome da pasta/projeto
className="com.example.GreetingResource" - classe REST inicial
path="/hello" - endpoint da sua API

Navegue para o projeto:

cd hello-quarkus

E agora... o momento mágico! Execute:

mvn quarkus:dev

Abra http://localhost:8080/hello no seu navegador e... voilà! 🎉

Você verá: Hello from Quarkus REST

📁 Anatomia de um Projeto Quarkus

Vamos explorar o que foi criado. A estrutura é bem familiar para quem já trabalha com Java:

hello-quarkus/
├── pom.xml                                 # Configurações Maven
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/
│   │   │       └── GreetingResource.java   # Sua primeira API REST
│   │   └── resources/
│   │       ├── application.properties      # Configurações da app
│   │       └── META-INF/resources/
│   │           └── index.html              # Página inicial
│   └── test/
│       └── java/com/example/
│           ├── GreetingResourceTest.java   # Testes unitários
│           └── GreetingResourceIT.java     # Testes de integração

Arquivos Importantes:

pom.xml - O coração do seu projeto Maven. Aqui ficam:

Dependências do Quarkus
Extensões (que veremos no próximo capítulo)
Configurações de build

GreetingResource.java - Sua primeira API REST:

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

application.properties - Onde a mágica da configuração acontece. Aqui você define:

Portas de conexão
Configurações de banco de dados
Propriedades customizadas

⚡ Live Coding: A Revolução da Produtividade

Aqui está o recurso que vai mudar sua vida como desenvolvedor! O Live Coding do Quarkus elimina aquela espera chata entre alteração e teste.

Como funciona na prática:

Certifique-se de que o modo dev está rodando:

   mvn quarkus:dev

Faça uma alteração no código: Abra GreetingResource.java e modifique o método:

   @GET
   @Produces(MediaType.TEXT_PLAIN)
   public String hello() {
       return "Olá, mundo! Quarkus é incrível! 🚀";
   }

Salve o arquivo (Ctrl+S)
Atualize o navegador - SEM REINICIAR NADA!

Resultado: Mudança instantânea! ⚡

O que o Live Coding detecta:

✅ Alterações no código Java
✅ Modificações em application.properties
✅ Novos recursos estáticos (HTML, CSS, JS)
✅ Adição de novas extensões
✅ Mudanças em templates

🎮 Experimente Você Mesmo!

Que tal brincar um pouco? Tente estas modificações:

Adicione um parâmetro à sua API:

@GET
@Path("/{name}")
@Produces(MediaType.TEXT_PLAIN)
public String hello(@PathParam("name") String name) {
    return "Olá, " + name + "! Bem-vindo ao Quarkus!";
}

Teste: http://localhost:8080/hello/SeuNome

Retorne JSON:

@GET
@Path("/json")
@Produces(MediaType.APPLICATION_JSON)
public JsonObject helloJson() {
    return Json.createObjectBuilder()
            .add("message", "Hello from Quarkus!")
            .add("timestamp", LocalDateTime.now().toString())
            .build();
}

Teste: http://localhost:8080/hello/json

🏁 Próximos Passos

Parabéns! 🎉 Você acabou de:

✅ Configurar seu ambiente Quarkus
✅ Criar sua primeira aplicação
✅ Experimentar o Live Coding
✅ Entender a estrutura de um projeto

No próximo capítulo, vamos mergulhar fundo na Injeção de Dependências com CDI - o sistema que vai organizar e potencializar seu código de forma elegante e profissional.

🔗 Continue a Jornada

👉 Capítulo 3: Injeção de Dependências com CDI no Quarkus - Descubra como organizar seu código de forma profissional

📝 Considerações Finais

O Quarkus realmente transforma a experiência de desenvolvimento Java. O Live Coding que você experimentou hoje é apenas o começo - nos próximos capítulos, vamos explorar recursos ainda mais poderosos que farão você questionar por que não conhecia isso antes!

Gostou do conteúdo?

👍 Deixe seu like se foi útil
💬 Comente suas dúvidas ou experiências
🔄 Compartilhe com outros devs
👀 Me siga para não perder os próximos capítulos!

💡 Dica Pro: Mantenha o modo dev sempre rodando enquanto desenvolve - você vai se surpreender com a velocidade que ganha!

Capítulo 1: Introdução ao Quarkus - O Java Supersônico para a Era da Nuvem

Eduardo R. Ferreira — Thu, 12 Jun 2025 15:18:01 +0000

📚 Série: Quarkus: Desvendando o Desenvolvimento Moderno com Java

Este é o primeiro capítulo de uma série completa sobre Quarkus. Prepare-se para uma jornada que vai transformar sua visão sobre desenvolvimento Java moderno!

Imagine iniciar uma aplicação Java em milissegundos, consumir 10x menos memória que frameworks tradicionais e ainda manter toda a robustez e familiaridade do ecossistema Java que você já conhece. Parece ficção científica? Bem-vindo ao Quarkus!

O mundo do desenvolvimento de software está em constante evolução, e a corrida por ferramentas que maximizam produtividade, otimizam performance e simplificam a criação de aplicações modernas nunca foi tão intensa. Neste cenário, o Java — uma das linguagens mais sólidas e utilizadas no universo corporativo — encontrou no Quarkus seu superpoder para dominar a era da nuvem e dos microsserviços.

🚀 O que é Quarkus?

Quarkus é um framework Java nativo para Kubernetes, especialmente otimizado para GraalVM e OpenJDK HotSpot. Ele foi meticulosamente projetado para tornar o Java a plataforma líder em microsserviços e aplicações serverless, entregando:

⚡ Tempos de inicialização de milissegundos
🧠 Consumo de memória drasticamente reduzido
🏗️ Arquitetura otimizada para contêineres

O nome "Quarkus" vem dos quarks — as partículas subatômicas fundamentais da matéria. Essa analogia captura perfeitamente a filosofia do framework: construir aplicações Java pequenas, rápidas e eficientes que se encaixam como uma luva em ambientes de nuvem e microsserviços.

// Com Quarkus, até um "Hello World" é supersônico!
@Path("/hello")
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello, Quarkus World!";
    }
}

O Quarkus se autodenomina "Supersonic Subatomic Java" — e essa não é apenas uma frase de marketing. É uma promessa de performance que ele cumpre religiosamente.

💡 Por que Escolher Quarkus? As Vantagens que Fazem a Diferença

⚡ Inicialização Ultrarrápida: Adeus Espera Eterna

Uma das maiores frustrações no desenvolvimento Java tradicional — especialmente em microsserviços e serverless — é o tempo de inicialização. Enquanto aplicações Spring Boot podem levar segundos (ou até minutos) para inicializar, o Quarkus quebra essa barreira:

JVM mode: Inicialização em centenas de milissegundos
Native mode: Inicialização em dezenas de milissegundos

Isso é crucial para:

🔄 Autoescalabilidade responsiva
⚡ Funções serverless eficientes
🏃‍♂️ Desenvolvimento ágil com feedback instantâneo

🧠 Memória Otimizada: Mais Aplicações, Menos Custo

O Quarkus consome até 10x menos memória que frameworks Java tradicionais. Na prática, isso significa:

💰 Redução significativa de custos de infraestrutura
📈 Maior densidade de aplicações por servidor
🎯 Melhor aproveitamento de recursos em contêineres

🛠️ Produtividade Turbinada: Desenvolvedor Feliz, Código Melhor

A experiência de desenvolvimento com Quarkus é revolucionária:

Live Coding: Mudanças em Tempo Real

# Inicie o modo de desenvolvimento
./mvnw quarkus:dev

# Altere seu código e veja as mudanças instantaneamente!
# Sem reinicializações, sem espera, sem interrupções.

Ecossistema Integrado

O Quarkus une o melhor do Java em uma experiência coesa:

JAX-RS para APIs REST
CDI para injeção de dependências
JPA/Hibernate para persistência
Kafka para mensageria
OpenAPI para documentação automática

🏗️ Container-First: Nascido para a Nuvem

Diferentemente de outros frameworks que foram adaptados para contêineres, o Quarkus foi projetado para eles:

🐳 Imagens Docker ultra-leves
☸️ Kubernetes e OpenShift nativos
🔧 GraalVM para executáveis nativos
📦 Deployment otimizado para nuvem

🌊 Reatividade Nativa: Performance Assíncrona

Com um core reativo baseado em Vert.x, o Quarkus oferece:

🔄 Processamento assíncrono eficiente
📊 Alta concorrência com poucos recursos
🎯 Microsserviços resilientes e escaláveis

⚖️ Quarkus vs. Concorrência: O Confronto dos Gigantes

🆚 Quarkus vs. Spring Boot

Aspecto	Quarkus	Spring Boot
Inicialização	Milissegundos	Segundos
Memória	~13MB	~100MB+
Executável Nativo	Nativo desde o início	Spring Native (recente)
Ecosistema	Crescente rapidamente	Maduro e estabelecido
Curva de Aprendizado	Familiar para devs Java	Muito familiar

Veredicto: Se você precisa de performance extrema e otimização para nuvem, Quarkus leva vantagem. Para ecossistema maduro e comunidade estabelecida, Spring Boot ainda é forte.

🆚 Quarkus vs. Micronaut

Ambos são frameworks modernos focados em microsserviços:

Quarkus: Melhor integração com ecossistema Java existente
Micronaut: Compilação em tempo de build mais agressiva

A escolha entre eles geralmente depende de preferências pessoais e ferramentas existentes no projeto.

🌟 O Ecossistema Quarkus: Um Universo de Possibilidades

O Quarkus não é apenas um framework — é um ecossistema completo que abraça:

📋 Padrões Java Enterprise

JAX-RS (APIs REST)
CDI (Injeção de Dependências)
JPA (Persistência)
Bean Validation (Validação)
MicroProfile (Microsserviços)

🔧 Bibliotecas Populares

Hibernate ORM (Mapeamento Objeto-Relacional)
Apache Kafka (Streaming de Dados)
SmallRye (Implementações MicroProfile)
Vert.x (Programação Reativa)
Camel (Integração de Sistemas)

🏗️ Ferramentas de Build

Maven e Gradle com plugins otimizados
Quarkus CLI para criação rápida de projetos
Docker e Kubernetes integrados

☁️ Plataformas de Nuvem

Kubernetes e OpenShift
AWS Lambda e Google Cloud Functions
Azure Functions e Knative

🎯 Conclusão: O Futuro do Java é Agora

O Quarkus representa uma evolução natural do Java para a era moderna. Ele mantém toda a robustez e familiaridade que amamos no Java, mas adiciona a agilidade e eficiência que os ambientes de nuvem exigem.

Se você está construindo microsserviços, aplicações serverless ou simplesmente quer uma experiência de desenvolvimento mais fluida, o Quarkus não é apenas uma opção — é a escolha inteligente.

🔗 Próximos Passos

Agora que você entendeu o que é e por que usar Quarkus, que tal colocar a mão na massa?

👉 Capítulo 2: Primeiros Passos com Quarkus - Aprenda a criar seu primeiro projeto e explorar as ferramentas essenciais.

💬 Vamos Conversar!

O que você achou desta introdução ao Quarkus? Já teve experiência com frameworks Java modernos? Compartilhe sua opinião nos comentários!

Curtiu o conteúdo? Deixe seu ❤️ e me siga para não perder os próximos capítulos desta série. Vamos juntos dominar o Quarkus!

DEV Community: Eduardo R. Ferreira

Capítulo 5: Construindo APIs RESTful com RESTEasy

🎯 O que você vai aprender

🏗️ Fundamentos: REST e JAX-RS Explicados

REST: Mais que um Protocolo, uma Filosofia

JAX-RS: REST para Desenvolvedores Java

🛠️ Mãos à Obra: Criando Nossa API de Produtos

Passo 1: O Modelo de Dados

⚠️ Quando não usar campos públicos

Apesar da praticidade, campos públicos não são ideais em todos os cenários:

✅ Quando usar

Campos públicos são totalmente aceitáveis e até recomendados no Quarkus para:

Passo 2: O Recurso REST - Onde a Mágica Acontece

🎯 Decifrando as Anotações JAX-RS

🧪 Testando Nossa API Básica

⚠️ Tratamento de Erros e Exceções

1. Exceções Personalizadas

2. Classe de Resposta de Erro Padronizada

3. Mapeadores de Exceção Globais

4. Usando as Exceções no Resource

🛡️ Validação de Dados: Sua Primeira Linha de Defesa

Adicionando Bean Validation

Modelo com Validações

Ativando Validação nos Endpoints

Personalizando Mensagens de Validação

Testando Validação

🎨 Suporte a Múltiplos Formatos

Para XML

Crie uma classe wrapper anotada com @XmlRootElement para encapsular a lista de produtos

Adicione anotações JAXB no Modelo

Atualize as Anotações do Resource

Testando XML

🎭 Negociação de Conteúdo Automática

Outros Formatos Suportados

🚀 Dicas Pro para APIs de Produção

1. Paginação para Listas Grandes

2. Filtros e Busca

3. Headers Úteis para Performance

4. Documentação com OpenAPI/Swagger

5. Versionamento de API

6. Rate Limiting Básico

🎯 Resumo do Capítulo

🔗 Continue a Jornada

💬 Vamos Conversar!

Capítulo 4: Configuração de Aplicações Quarkus

🚀 Gerenciamento de Propriedades: Seu Painel de Controle

🎭 A Hierarquia das Configurações: Quem Manda Aqui?

Ordem de Precedência (do menor para o maior poder):

Exemplo Prático da Hierarquia:

🎨 Perfis de Configuração: Uma Aplicação, Múltiplas Personalidades

Estrutura dos Arquivos de Perfil:

Exemplo Completo de Configuração Multi-Ambiente:

Ativando os Perfis:

💡 Exemplo Avançado: Configuração Inteligente

🧪 Testando Nossa Aplicação

🎯 Principais Vantagens do Sistema de Configuração do Quarkus

🚀 Conclusão

🔗 Continue a Jornada

Capítulo 3: Injeção de Dependências com CDI no Quarkus

🎯 O que é Injeção de Dependências?

Por que isso é revolucionário?

📚 CDI: Contexts and Dependency Injection Explicado

🫘 Beans: Os Protagonistas do CDI

🎯 Escopos: Definindo o Tempo de Vida

@ApplicationScoped - O Eterno

@RequestScoped - O Efêmero

@Singleton - O Único Verdadeiro

@Dependent - O Dependente

🔍 ApplicationScoped vs Singleton: Qual a Diferença?

@ApplicationScoped

@Singleton

Quando usar cada um?

💉 Injeção Básica: Primeiros Passos

1. Criando o Serviço de Saudação

2. Criando o Contador de Requisições

3. Usando Injeção no Resource

🎭 Interfaces e CDI: Programação Contra Abstrações

Por que usar Interfaces com CDI?

Exemplo Avançado: Sistema de Notificações

Resolvendo Ambiguidade com Qualifiers

`@ApplicationScoped` - O Eterno

`@RequestScoped` - O Efêmero

`@Singleton` - O Único Verdadeiro

`@Dependent` - O Dependente

`@ApplicationScoped`

`@Singleton`