DEV Community: Diego de Sousa Brandão

Custo de tokens em LLMs: onde pesa e como evitar desperdício

Diego de Sousa Brandão — Mon, 21 Sep 2026 16:02:55 +0000

Resumo executivo

Em agentes de código o input domina o volume e o custo; em respostas pontuais e com raciocínio o output pesa mais por token. O desperdício evitável vem de contexto acumulado, modelo e esforço acima do necessário, cache quebrado e modos caros ligados sem necessidade, não da indentação.

Preço por token. O output custa 5x a 6x o input em todos os modelos de topo: Claude Opus 5 US$5/25, GPT-5.6 Sol US$4/20 (promoção), Gemini 3.1 Pro US$2/12, e US$10/50 no Fable 5.1 e no GPT-6 Astra.
Volume em agentes. Agentes gastam ~1.000x mais tokens que chat, com o input puxando o custo (arXiv 2604.22750). Num trace de PR da Sonar, 98% dos ~156 milhões de tokens foram leituras de cache e o output foi 0,19%.
Raciocínio. Thinking tokens são cobrados como output, vêm ligados por padrão e podem chegar a dezenas de milhares por requisição. O esforço é a maior alavanca.
Tokenizer. O do Claude a partir do 4.7 gera ~30% mais tokens que o anterior (Anthropic) e 1,4x a 1,7x mais que o do GPT em texto e código (Playcode). Compare custo por tarefa, não preço por token.
Cache e modos. A leitura de cache custa 10% do input (2,5% no Fable 5.1) e reescrever custa 12,5x mais (50x no Fable 5.1). Fast e Priority custam 1,8x a 2x, e o Batch corta 50%.
Erros de uso mais bem documentados. Sessão longa sem limpar, modelo caro como padrão, esforço alto sem necessidade, cache invalidado, leituras largas e agentes paralelos esquecidos.
Arquivos de contexto. CLAUDE.md, AGENTS.md e GEMINI.md entram em toda sessão e os agentes seguem o que eles dizem. No estudo da ETH Zurich, arquivos gerados por LLM elevaram o custo por tarefa em 20% a 23% sem ganho significativo de acerto. O custo vem do comportamento induzido, não do tamanho do texto.
Estratégias com ganho medido. Mascarar observações antigas (~50% menos custo, JetBrains), estabilizar o prefixo do cache (acerto de 7% para 84% e 59% a 70% de economia num agente em produção), carregar ferramentas sob demanda (de ~77 mil para ~8,7 mil tokens, Anthropic) e cortar instruções de teste de arquivos gerados (−16% a −21% de custo). Os números vêm de contextos diferentes e não se somam.
Formatação. Indentação, espaços e quebras de linha custam 13% a 15% dos tokens de arquivos reais de Java, C# e C++ e 4% dos de Python; a indentação sozinha vale ~8% a 10% nos exercícios de completar código. O modelo tende a repetir a formatação na saída. É real, mas secundário.

Recomendação: limpar contexto a cada tarefa, escolher modelo e esforço por tarefa, estabilizar o prefixo para cache, reduzir leituras e definições de ferramentas, impor tetos de gasto e medir custo por tarefa com o campo usage de cada resposta.

Escopo e qualidade das fontes

O estudo responde quatro perguntas: onde o custo de tokens se concentra (input ou output), quais erros de uso mais o geram, como evitá-los e quais estratégias de redução têm ganho medido em fonte primária ou caso de produção. Cobre Claude (Fable 5.1, Opus 5, Sonnet 5, Haiku 4.5), OpenAI (GPT-6 Astra e GPT-5.6 Sol, Terra e Luna) e Google (Gemini 3.1 Pro e 3.8 Flash), além dos arquivos de contexto do Claude Code, do Codex, do Gemini CLI, do Kimi Code CLI e do GLM. Data-base: 20/09/2026.

Método: cada número vem de página aberta em 20/09/2026, com prioridade para documentação oficial e papers. Onde a fonte é de um fornecedor que vende a solução ou de terceiros, isso está marcado. Cálculos próprios estão marcados como tais.

Cada fonte recebe uma nota de força:

A: paper, documentação ou página oficial.
B: medição de terceiro ou de fornecedor, com método descrito.
C: análise secundária.

Onde o custo se concentra: input em agentes, output em geração e raciocínio

O ponto de maior custo depende do padrão de uso.

Padrão de uso	Onde o custo pesa	Evidência
Chat e geração pontual	Output, 5x a 6x mais caro por token	Tabela de preços abaixo
Agente de código	Input, por releitura do contexto a cada passo	arXiv 2604.22750; trace de um PR
Modelo de raciocínio	Output invisível (thinking tokens)	Documentação da OpenAI e da Anthropic

Uso real em escala. O relatório OpenRouter/a16z (State of AI, 100 trilhões de tokens até nov/2025) mostra o prompt médio subindo de ~1,5 mil para mais de 6 mil tokens e a resposta de ~150 para ~400, uma razão de ~15 para 1 (cálculo nosso). Prompts de programação são 3 a 4x mais longos que os gerais e passam de 20 mil tokens de input, e mais de 50% dos tokens já passam por modelos de raciocínio. Com output 5x mais caro, o input ainda responde por ~75% do custo a preço cheio e sem cache (cálculo ilustrativo nosso). O dado vem de uma só plataforma e usa proxies para uso agêntico.

Agentes. Bai et al. (arXiv 2604.22750, abr/2026) analisaram trajetórias de 8 modelos de 2025 no SWE-bench Verified, com o agente OpenHands. Em média, uma tarefa agêntica usou 4,17 milhões de tokens (US$1,86), contra 1,19 mil (US$0,016) em raciocínio de código e 3,39 mil (US$0,023) em chat de código: de 1.200x a 3.500x mais tokens. A razão input/output é de ~154 para 1 em agentes, contra 0,16 e 1,33 nos outros dois, e o input puxa o custo mesmo com cache. Num estudo de caso com o Sonnet 4.5, a leitura de cache dominou volume e custo em todas as fases, embora o output custe muito mais por token.

A mesma tarefa varia: a run mais cara custa em média ~2x a mais barata, com extremos de até 30x. Mais tokens não garantem mais acerto (a acurácia sobe pouco e satura), e os modelos preveem o próprio gasto com correlação de no máximo 0,39, subestimando-o. Um loop ingênuo relê o histórico a cada passo: 20 passos de 1.000 tokens somam 210.000 tokens de input, não 20.000 (cálculo nosso).

Caso: um PR de 800 linhas (Sonar, 1/09/2026). O post da Sonar mede 512 idas e voltas, janela com pico de 458.700 tokens e ~156 milhões de tokens faturados por ~US$41: 152,8 milhões de leitura de cache, 3,1 milhões de escrita, 106 mil de input novo e 289 mil de output. Um arquivo de 618 linhas (6.472 tokens), lido para usar uma função de ~67 linhas, ficou no contexto por ~470 turnos: ~2,7 milhões de tokens relidos, cerca de US$0,54 à tarifa de cache citada (~US$0,20 por milhão). Em 18 PRs comparáveis, a média foi de ~234 milhões de tokens de contexto, ~700 idas e voltas e ~US$65 por PR (mediana ~US$52). Com essa tarifa, as 152,8 milhões de leituras custam ~US$30,6, cerca de 75% do total (cálculo nosso). Ressalvas: o post não nomeia o modelo nem o agente, mede um repositório e a Sonar vende a solução (análise crítica).

Documentação oficial: o custo cresce com a sessão. O Claude Code envia a conversa inteira a cada requisição, e cada uso de ferramenta gera outra requisição. Com cache, o histórico é relido à tarifa de cache, então uma pergunta de uma linha numa sessão aberta o dia todo consome o histórico inteiro. A primeira mensagem após uma pausa maior que o TTL reprocessa o contexto inteiro, e /compact é ele próprio uma requisição grande (docs).

Leitura: com agentes, otimizar input (contexto, cache, leituras) rende mais que otimizar output. Em geração direta e modelos de raciocínio, ocorre o inverso.

Evidência por modelo: o preço por token é parecido, o custo por tarefa não

Os modelos de topo custam de US$4 a US$10 por milhão de tokens de input, e o output custa 5x a 6x mais em todos; tokenizer, raciocínio e cache é que fazem o custo por tarefa divergir. A tabela traz US$ por milhão de tokens, contexto curto, tarifa padrão, lida nas páginas oficiais em 20/09/2026.

Modelo	Input	Output	Output/Input
Claude Fable 5.1	10	50	5x
GPT-6 Astra	10	50	5x
Claude Opus 5	5	25	5x
GPT-5.6 Sol	4 (promo)	20 (promo)	5x
Claude Sonnet 5	2	10	5x
GPT-5.6 Terra	2	12	6x
Gemini 3.1 Pro Preview	2	12	6x
Claude Haiku 4.5	1	5	5x
Gemini 3.8 Flash	0,75 (promo)	3,75 (promo)	5x
GPT-5.6 Luna	0,20	1,20	6x

O GPT-5.6 Sol está em promoção: a OpenAI garante US$4/20 pelo menos até 21/11/2026, e o preço anterior era US$5/30 (página oficial). Na Anthropic, o Sonnet 5 a US$2/10 é agora o preço padrão, e o aumento previsto para US$3/15 em 1/09/2026 não vai ocorrer. DeepSeek V4, Grok e Mistral ficaram fora da tabela porque não foram verificados em página oficial nesta revisão.

Fontes: páginas de preços da Anthropic, da OpenAI e do Google. O Gemini 3.8 Flash custa US$0,75/3,75 até 31/12/2026 e US$1,50/7,50 depois. GPT-6 Astra (OpenAI) e Claude Fable 5.1 (Anthropic) custam ambos US$10/50.

Cache, contexto longo e modos especiais: regras oficiais por fornecedor

Anthropic, OpenAI e Google cobram a leitura de cache a 10% do input (2,5% no Fable 5.1). A escrita, o prazo, o contexto longo e o que invalida o cache variam.

Fornecedor	Leitura de cache	Escrita ou armazenamento	Contexto longo
Anthropic	0,1x o input (0,025x no Fable 5.1)	Escrita 1,25x (5 min) ou 2x (1 h)	Janela de 1 milhão a preço padrão, sem sobretaxa (preços)
OpenAI	0,1x (Sol US$0,40; Astra US$1,00)	Escrita 1,25x (Sol US$5,00)	Acima de 272 mil tokens: 2x no input e 1,5x no output da requisição inteira (Sol)
Google	0,1x (3.1 Pro US$0,20; 3.8 Flash US$0,075)	Armazenamento por hora: US$4,50 por milhão (3.1 Pro), US$0,50 (3.8 Flash até 31/12/2026)	Acima de 200 mil tokens: US$4/18 no 3.1 Pro

Lote e prioridade. O Batch corta 50% do input e do output nos três fornecedores (Sol a US$2/10 no Batch). Os modos rápidos custam mais: fast mode do Opus 5 e do Opus 4.8 a US$10/50 (2x, indisponível no Batch), Fast mode da OpenAI 2x (Sol a US$8/40) e Priority do Gemini 3.1 Pro 1,8x (US$3,60/21,60).
Prazo. O TTL padrão é de 5 minutos, renova a cada uso e conta desde o início da requisição, inclusive o tempo de geração. No Claude Code o cache dura 1 h em assinatura e 5 min em API key ou com créditos de uso (docs).
O que invalida (Anthropic). O acerto exige prompt 100% idêntico até o breakpoint. Mudar definições de ferramentas invalida tudo. Ligar ou desligar web search ou citações e trocar o modo rápido invalidam sistema e mensagens. Mudar tool_choice, imagens, parâmetros de thinking ou output_config.effort invalida as mensagens. Em modelos com esforço por mensagem, mudar o esforço numa mensagem system preserva o prefixo (docs).
Erro clássico. Breakpoint num bloco que muda a cada requisição, como um timestamp: o cache é escrito toda vez e nunca lido. O ponto certo é o último bloco estável.
Mínimo. Abaixo de 512 tokens (Opus 5, Fable 5.1), 1.024 (Sonnet 5) ou 4.096 (Haiku 4.5) o prompt não entra em cache, sem erro.
Custo do erro. Reescrever o cache custa 12,5x mais que lê-lo (1,25x contra 0,1x) e 50x no Fable 5.1 (1,25x contra 0,025x); cálculo a partir das tarifas oficiais.
Residência de dados. inference_geo: "us" multiplica todos os tipos de token por 1,1x nos Claude 4.6 e posteriores; a OpenAI cobra +10% em endpoints regionais.

Tokenizer: o mesmo código vira 1,5x a 1,7x mais tokens no Claude atual que no GPT

A Anthropic informa que os modelos a partir do Claude 4.7 geram cerca de 30% mais tokens para o mesmo texto que o tokenizer anterior (preços). A Playcode comparou fornecedores com o count_tokens da Anthropic e conferiu contra requisições pagas. A tabela usa o o200k do GPT como 1,00x.

Conteúdo	Claude (novo)	Claude (antigo)	Gemini 3.x Flash
TypeScript (2.888 caracteres)	1,73x	1,32x	1,16x
Rust	1,58x	1,22x	1,19x
JavaScript	1,52x	1,26x	1,23x
Python	1,50x	1,22x	1,20x
Prosa em inglês	1,40x	1,05x	1,01x
Prosa em chinês	1,44x	1,45x	0,85x

Quem usa qual. Sonnet 5, Opus 4.8, Opus 5, Fable 5 e Fable 5.1 usam o tokenizer novo; Sonnet 4.6 e Opus 4.6 usam o antigo. O Fable 5.1 conta o input igual ao Fable 5.
Preço efetivo. Com a divergência média de 1,50x em pedidos típicos de código, a Playcode calcula que os US$5/25 do Opus 5 se comportam como US$7,50/37,50 na base do GPT, e os US$10/50 do Fable 5.1 como US$15/75. É estimativa de terceiro.
Cache também. Leituras e escritas de cache cobram por token, então a inflação as encarece na mesma proporção.
Output varia mais que input. Numa tarefa única (o mesmo SVG, esforço máximo, thinking incluído), os tokens de output foram: Sonnet 5 121.713; Fable 5.1 99.072; Opus 5 74.061; GPT-6 Astra 45.836; Fable 5 42.560; GPT-5.6 Terra 29.834; Gemini 3.7 Flash 13.863. É um prompt só: serve de indício, não de regra.
Agentes (modelos de 2025). No estudo de Bai et al., Claude Sonnet 4.5 e Kimi K2 consumiram em média mais de 1,5 milhão de tokens a mais que o GPT-5 nas mesmas tarefas (arXiv 2604.22750).

Compare por custo por tarefa, não por preço por token: rode o mesmo trabalho em cada modelo e leia o campo usage das respostas. O estudo de formatação da seção seguinte usou tokenizers de 2024–25 (GPT-4o, Claude 3.7, Gemini 1.5); não encontramos medição do efeito no tokenizer novo do Claude.

Reasoning tokens: cobrados como output, ligados por padrão e quase invisíveis

OpenAI e Anthropic documentam que tokens de raciocínio saem à tarifa de output, e a página de preços do Google rotula o output do Gemini como incluindo os tokens de thinking.

OpenAI. Os tokens de raciocínio não aparecem na API, ocupam a janela de contexto e são cobrados como output. Podem ir de algumas centenas a dezenas de milhares por resposta, e a OpenAI recomenda reservar ao menos 25.000 tokens para raciocínio e saída (guia). Se max_output_tokens se esgota durante o raciocínio, você paga input e raciocínio sem receber resposta visível.
Anthropic. No Claude Code o extended thinking vem ligado por padrão, é cobrado como output e seu orçamento padrão pode chegar a dezenas de milhares de tokens por requisição. Nos modelos Fable não dá para desligá-lo. MAX_THINKING_TOKENS só vale em modelos de orçamento fixo; os de raciocínio adaptativo ignoram orçamentos não nulos, então o controle é o esforço (/effort) (docs).
Padrões e modos (OpenAI). O GPT-5.6 usa esforço medium por padrão. O modo pro agrega mais trabalho do modelo e cobra pelas tarifas normais, então gasta mais tokens. O GPT-6 Astra não aceita none. O GPT-5.6 também renderiza por padrão o raciocínio de turnos anteriores (all_turns); current_turn reduz o contexto renderizado em fluxos longos.
Trocar o esforço e o cache. Na Anthropic, mudar o esforço invalida o cache de mensagens, salvo em modelos com esforço por mensagem. Na OpenAI, o item configuration_update (só no GPT-6 Astra) muda o esforço preservando o prefixo do prompt.
Ordem de grandeza. 4.000 tokens de thinking mais uma resposta de 500 somam 9x os tokens de output da resposta sozinha (cálculo nosso).
Mais raciocínio não é mais acerto. No estudo de agentes, a acurácia costuma atingir o pico em custo intermediário e satura depois (arXiv 2604.22750).

Formatação custa de 4% a 15% dos tokens em arquivos reais e ~25% em trechos de exercício

O estudo de Pan et al. (arXiv 2508.13666, lido na íntegra) mede o custo da formatação em duas etapas: uma amostra do Stack v2 (100 mil arquivos por linguagem em Java, C# e C++, tokenizer do GPT-4o) e um experimento principal com 10 modelos. Ambas removem só o que não altera a sintaxe. O paper cita o Python (4,0%) no mesmo estudo preliminar, sem repetir a amostra para ele.

Linguagem	Arquivos reais (GPT-4o)	Exercícios de completar código (média de 10 modelos)
Java	14,7%	34,9%
C++	13,2%	31,1%
C#	13,2%	25,3%
Python	4,0%	6,5%

No experimento principal, os modelos completam um trecho de código em Java, Python, C++ e C#, com cinco modelos comerciais (entre eles GPT-4o, Claude 3.7 e Gemini 1.5) e cinco de pesos abertos. Remover indentação, espaços e quebras de linha cortou em média 24,5% dos tokens de input (o texto do paper também cita 24,6% e 25,8%). Nenhum modelo perdeu mais de 4,2 pontos de Pass@1, e nenhuma queda foi significativa. No Claude 3.7 a redução média foi de 23,0%. Python cai menos porque a indentação é sintaxe.

Cada elemento (C++, Java, C#). A indentação sozinha responde por 7,9% dos tokens de input no Claude 3.7, 8,9% no Gemini 1.5 e 9,6% no GPT-4o. As quebras de linha pesam mais nos dois primeiros (14,6% e 17,5%); no GPT-4o, os espaços (10,7%) pesam mais que as quebras (7,5%). A diferença vem dos tokenizers.
Saída. O modelo repete a formatação mesmo com entrada sem ela: a redução média de output foi de só 2,5%. Pedir código sem formatação cortou 27,2% do output no GPT-4o sem perder acerto (Java, C++ e C#), mas o Gemini 1.5 quebrou a sintaxe e o Pass@1 em C++ caiu de 67,2% para 11,1%. Ajuste fino com 50 exemplos de Java reduziu o output em 24,8% (GPT-4o) e 35,9% (Gemini 1.5).
Limites. A tarefa é completar código, em quatro linguagens e com modelos de 2024–25. Os autores citam limites de generalização e a opacidade dos modelos comerciais. Nenhum modelo atual foi testado.

Leitura: a formatação é de 13% a 15% dos tokens em arquivos reais de Java, C# e C++, e a indentação sozinha vale cerca de 8% a 10% nos exercícios de completar código (Claude 3.7, Gemini 1.5 e GPT-4o). Como o output custa 5x a 6x o input, a formatação que o modelo gera pesa mais que a que você envia, mas ele tende a mantê-la. Pedir "sem formatação" exige teste, porque pode quebrar a sintaxe. A alternativa dos autores é uma ferramenta que remove a formatação na entrada e a restaura na saída.

Arquivos de contexto (CLAUDE.md, AGENTS.md, GEMINI.md): o que custam e quando compensam

Esses arquivos entram no contexto de toda sessão. O texto em si custa pouco com cache; o custo relevante vem do que ele faz o agente fazer. A medição mais rigorosa é a de Gloaguen et al. (arXiv 2602.11988, v2 de jun/2026, lido na íntegra): quatro agentes (Claude Code com Sonnet 4.5, Codex com GPT-5.2 e GPT-5.1 Mini, Qwen Code com Qwen3-30B), 300 tarefas do SWE-bench Lite e 138 tarefas de 12 repositórios com arquivos escrit

Métricas de efetividade de uso de IA — Spark Monitor

Diego de Sousa Brandão — Fri, 18 Sep 2026 13:00:57 +0000

Métricas de efetividade de uso de IA — Spark Monitor

Resumo da pesquisa sobre como medir se uma sessão de IA (Claude Code) foi produtiva, e como ranquear uso entre várias pessoas de forma fidedigna.

Problema-base

Token bruto (input/output/cache) mede atividade, não resultado. Ranquear pessoas só por isso vira Goodhart's law: o comportamento se otimiza para o número, não para a entrega.

Métricas para somar ao que o Spark Monitor já captura

Cache hit ratio = cache_read / (cache_read + input) — sinal de reuso eficiente de contexto.
Output por task fechada, não por sessão — normaliza por dificuldade da tarefa.
Sessões por task — muitas sessões para fechar 1 task indica retrabalho ou task mal escopada.
Rework rate real — % de código gerado por IA que é revertido ou reescrito em N dias. É a 5ª métrica oficial do DORA desde 2025. Sem esse dado, as métricas acima medem atividade, não qualidade.

Base acadêmica

Paper: Chen et al., "Beyond the Commit: Developer Perspectives on Productivity with AI Coding Assistants" — ICSE-SEIP 2026 (CMU + BNY Mellon). Survey com 2989 devs + 11 entrevistas.

Correlação entre satisfação percebida e tempo economizado auto-reportado: r = 0,34 (fraca). Confirma que métrica única não captura produtividade.
6 fatores identificados, agrupados em desenvolvimento / deploy / longo prazo:
1. Autossuficiência
2. Fricção e carga cognitiva
3. Taxa e qualidade de conclusão de tarefa
4. Facilidade de peer review
5. Expertise técnica (longo prazo)
6. Ownership do código (longo prazo)
Achado direto ao caso: commit frequency e taxa de aceite de sugestão (o que o Spark Monitor já capta) cobrem apenas o fator de deployment — não medem tempo real gasto nem qualidade.
Risco documentado: ranking competitivo por atividade tende a empurrar devs júnior a confiar demais na IA, corroendo aprendizado e senso de ownership.
Meta usa métrica própria, Diff Authoring Time (DAT) — tempo real de autoria de um diff, sinal mais fino que token bruto (Beller et al. 2025).

Gate de avaliação por LLM (se for implementado)

Riscos documentados de usar um LLM como juiz de código:

Viés de verbosidade — o juiz tende a preferir código/resposta mais longa, mesmo sem ganho real de conteúdo.
Autopreferência — o modelo tende a preferir a própria saída/estilo (efeito de menor "perplexidade").
Boa notícia: em tarefas verificáveis (código com teste/build), a autopreferência tende a refletir qualidade real — diferente de tarefas subjetivas como chat/resumo.

Desenho recomendado — gate em 2 camadas:

Camada objetiva (sem viés): testes automatizados passam, build ok, lint/análise estática.
Camada LLM-juiz: só para o que a camada objetiva não pega — legibilidade, aderência a padrão. Rubrica fixa, temperatura baixa, modelo juiz logado (idealmente diferente do modelo gerador). Calibrar periodicamente contra o rework rate real.

Mercado — não existe score pronto, mas existe a categoria

GitClear — mede churn, duplicação, idade do código, atribuição IA vs. humano. ~US$15/contribuidor/mês.
DX — feito pelos autores do SPACE e do DORA; lançou framework de IA dedicado em 2026 (utilização, impacto, custo).
Nenhuma resolve o problema sozinha. A própria DX publicou (mar/2026) que DORA isolado não é suficiente para times usando IA.

Dados já disponíveis para implementação

Projeto: campo cwd presente em cada linha do JSONL de sessão do Claude Code (~/.claude/projects/<cwd-codificado>/<uuid>.jsonl — no Windows, %USERPROFILE%\.claude\projects\), mais gitBranch. Já está no dado que o Spark Monitor lê.
Push feito pela própria IA: já registrado no mesmo JSONL, como tool_use/tool_result do Bash rodando git push.
Push manual do humano (fora do Claude Code): não está no log do Claude Code. Requer hook git global (git config --global core.hooksPath <pasta>, hook pre-push) — cobre todos os repositórios de uma vez. Atenção: pre-push confirma a intenção do push, não garante que a transferência de rede terminou com sucesso.
Atenção: "subiu pro remoto" ≠ "foi pra produção". Confirmar deploy real exige integração com CI/CD.

Fontes

Acadêmico

Chen et al., "Beyond the Commit: Developer Perspectives on Productivity with AI Coding Assistants", ICSE-SEIP 2026 — https://arxiv.org/abs/2602.03593
Wataoka et al., "Self-Preference Bias in LLM-as-a-Judge" — https://arxiv.org/html/2410.21819v1
"Judging the Judges: A Systematic Evaluation of Bias Mitigation Strategies in LLM-as-a-Judge Pipelines" — https://arxiv.org/pdf/2604.23178
"Do LLM Evaluators Prefer Themselves for a Reason?" (Univ. of Virginia, 2025) — https://papers.lunadong.com/paper/6021
DORA Research, AI Capabilities Model — https://dora.dev/research/ai/ai-capabilities-model

Indústria / mercado

GetDX, "How to Implement the AI Measurement Framework" — https://getdx.com/blog/how-to-implement-ai-measurement-framework/
GitClear, estudo de churn/duplicação em código gerado por IA — via https://arc.dev/talent-blog
Faros AI, "AI Engineering Report 2026" — https://www.faros.ai

Documentação técnica Claude Code

Formato JSONL de sessão — https://claude-dev.tools/docs/jsonl-format
Local dos logs (~/.claude/) — https://claude-dev.tools/docs/log-locations

Template de Avaliação de IAs de Coding

Diego de Sousa Brandão — Wed, 01 Jul 2026 18:01:36 +0000

Resumo Executivo

O que é este documento: um modelo padronizado para avaliar, de forma comparável e replicável, a capacidade real de ferramentas de IA aplicadas a desenvolvimento (Codex, Devin, Claude e demais), identificando com precisão o que cada uma faz bem, faz mal, ou não faz.

Por que essa metodologia: hoje o mercado divulga números de benchmarks públicos (como SWE-bench e Terminal-Bench) que servem como referência de capacidade geral, mas apresentam duas limitações relevantes para decisão de negócio:

Medem desempenho em projetos abertos de terceiros (majoritariamente Python), não refletem o comportamento em codebases proprietários, legados e no stack específico da empresa.
O resultado divulgado depende fortemente da ferramenta usada em torno do modelo (a forma como a IA é operacionalizada), não só do modelo em si — comparações "cruas" entre fornecedores tendem a ser enganosas.

Por isso, este template combina três referências reconhecidas no mercado — benchmarks públicos como ponto de partida, uma métrica de escala de dificuldade usada por institutos de avaliação de IA (METR) para medir até onde a ferramenta aguenta, e uma estrutura de avaliação usada em processos de seleção corporativa de ferramentas de IA (dimensões como confiabilidade, rastreabilidade, segurança e custo real) — com um piloto controlado, executado sobre código real da nossa operação, com critério e revisor únicos para todas as ferramentas testadas.

Resultado esperado: uma matriz objetiva, com evidência documentada, que sustenta a recomendação de qual ferramenta adotar, para qual finalidade, e com quais limitações conhecidas.

Princípio metodológico: o teste deve ser conduzido sobre uma tarefa real do backlog, nunca sobre um projeto de demonstração simplificado. A avaliação deve ser conduzida pelo mesmo revisor, com os mesmos critérios, para todas as ferramentas — garantindo comparabilidade.

1. Preparação do teste

Repositório real, com código legado, particularidades e convenções próprias — não um projeto novo e simplificado. É diante da complexidade real que se evidenciam os limites de cada ferramenta.
Linha de base humana: cronometrar quanto tempo um desenvolvedor Pleno leva para executar a mesma tarefa, como referência de comparação.
Revisor único: mesma pessoa e mesmo critério de avaliação (checklist de PR) para todas as ferramentas testadas.
Repetição: executar cada tarefa 2 a 3 vezes por ferramenta. O resultado de uma IA generativa varia entre execuções, mesmo para o mesmo pedido — uma única tentativa pode distorcer a avaliação.

2. Matriz de Capacidade por Ferramenta

Escala: 0 = não realiza | 1 = realiza com baixa qualidade, exige reescrita | 2 = realiza de forma razoável, exige ajustes | 3 = realiza em nível pronto para PR

Capacidade avaliada	Codex	Devin	Claude	Outra
Corrigir um bug simples em um único arquivo
Corrigir um bug que envolve múltiplos serviços simultaneamente
Alterar a assinatura de uma função e ajustar todos os pontos que a utilizam
Criar um novo endpoint seguindo o padrão já existente no projeto
Reter contexto de uma decisão do projeto após reabertura de sessão
Responder "se eu alterar isso, o que mais é impactado?" apenas com análise, sem executar mudanças
Escrever testes que cobrem cenários relevantes, não apenas o caminho principal
Compreender uma dependência de um projeto que não está aberto no contexto atual
Seguir os padrões de arquitetura do time sem instrução repetida
Reconhecer limitação de conhecimento e solicitar mais contexto, em vez de gerar resposta incorreta com aparência de correta

3. Teste de Limite de Capacidade

A dificuldade da tarefa deve ser escalonada progressivamente até que a ferramenta apresente falha — o objetivo é documentar em qual estágio cada uma deixa de performar de forma confiável:

Tarefa de 1 arquivo, equivalente a menos de 30 min de trabalho humano
Tarefa de 2 a 3 arquivos, equivalente a 1-2h de trabalho humano
Tarefa que atravessa múltiplos serviços/repositórios, equivalente a meio dia de trabalho humano
Tarefa sem especificação clara, que exige tomada de decisão de design, equivalente a um dia de trabalho humano

Esta abordagem é baseada no conceito de Time Horizon, métrica usada pelo instituto de pesquisa
METR para medir não "se a IA acerta", mas até qual complexidade/duração de tarefa humana a ferramenta
ainda mantém taxa de sucesso aceitável. Identificar o estágio em que cada ferramenta falha fornece
mais informação para decisão do que uma nota única.

4. Critérios Corporativos Complementares

Dimensão	Critério de avaliação	Codex	Devin	Claude
Consistência	O resultado varia significativamente entre execuções para o mesmo pedido?
Rastreabilidade	É possível identificar posteriormente qual ferramenta/versão gerou cada alteração?
Retenção de contexto	A ferramenta compreende o projeto como um todo ou apenas o que está aberto no momento?
Reversibilidade	Em caso de erro, é possível reverter apenas a alteração específica, ou o impacto se espalha por múltiplos arquivos?
Segurança da informação	Onde o código é processado/armazenado? Há uso do código para treinamento de modelo?
Custo real	Qual o tempo de revisão humana efetivamente economizado, descontado o tempo gasto em correções?

5. Ressalvas Metodológicas

A camada de operacionalização (produto) tem tanto peso quanto o modelo em si. O mesmo modelo (ex.: Claude) executado por diferentes produtos pode apresentar resultados distintos. Recomenda-se registrar não apenas "qual IA", mas "qual IA, em qual produto".
Benchmarks públicos não são preditivos do caso de uso específico. Os benchmarks de mercado avaliam majoritariamente projetos abertos em Python; não refletem o comportamento em ambiente Java de fintech legado, com Kafka e IBM MQ. Devem ser tratados como referência geral, não como critério de decisão.
Números divulgados por fornecedores devem ser tratados com cautela, especialmente quando não há metodologia reprodutível associada.
Demonstração de fornecedor não equivale a piloto controlado. O cenário apresentado em demonstrações tende a ser favorável (projeto simples e recente). A avaliação deve ocorrer sobre código real da operação, incluindo débito técnico.
O custo oculto deve ser mensurado. Tempo adicional de revisão sênior para correção do que foi gerado pela IA é custo, não apenas o tempo nominal economizado — deve compor o cálculo final de ganho de produtividade.

6. Prompts Padronizados para Execução dos Testes

Recomenda-se aplicar os mesmos prompts (ajustando apenas nome de arquivo/função) em Codex, Devin e Claude, garantindo comparabilidade entre os testes.

Correção de bug simples (1 arquivo)

"No arquivo [caminho], o teste [nome do teste] está falhando. Investigue a causa e corrija, sem alterar o comportamento esperado do teste."

Correção de bug cross-service

"O serviço [A] está retornando erro quando chama [B]. Rastreie o fluxo completo entre os dois serviços, identifique a origem do problema e proponha a correção. Antes de editar, indique quais arquivos pretende alterar."

Análise de impacto de mudança de assinatura

"Quero alterar a assinatura do método [nome] de [assinatura atual] para [nova assinatura]. Antes de qualquer alteração, liste todos os pontos do projeto que chamam esse método e o que será impactado."

Aderência a padrão existente

"Crie um novo endpoint [descrição] seguindo exatamente o mesmo padrão de arquitetura, nomenclatura e tratamento de erro já utilizado nos demais endpoints deste projeto. Não introduza um padrão novo."

Retenção de contexto (executar em sessão nova)

"Sem que eu forneça o contexto novamente: qual é a convenção que este projeto utiliza para tratamento de exceções? E para nomenclatura de branches?"
(aplica-se quando a ferramenta possui memória entre sessões — caso ela solicite o contexto de volta, esse já é um dado relevante sobre sua limitação)

Reconhecimento de limitação de conhecimento

"Implemente [funcionalidade dependente de uma biblioteca ou API que você sabe que não existe ou mudou recentemente]."
Objetivo: verificar se a ferramenta sinaliza incerteza, ou gera código plausível porém incorreto.

Análise sem execução

"Não realize nenhuma alteração ainda. Apenas explique: se eu alterar o tipo de retorno de [função] de X para Y, o que é impactado no projeto?"

Cobertura de teste

"Escreva testes unitários para [classe/função]. Inclua ao menos um cenário de borda não óbvio — entrada nula, lista vazia, concorrência ou timeout."

Teste de limite de complexidade (estágio 4 da seção 3)

"Preciso de [funcionalidade nova, sem especificação detalhada, que exige decisão de design]. Propositalmente não fornecerei todos os detalhes — faça as perguntas que considerar necessárias antes de iniciar a implementação."
Objetivo: verificar se a ferramenta solicita esclarecimento antes de agir, ou avança sobre premissas não validadas.

7. Fontes

SWE-bench / SWE-bench Verified / Pro — arxiv.org/pdf/2509.16941, swebench.com
Terminal-Bench 2.1 — tbench.ai, arxiv.org/html/2601.11868v1
METR Time Horizon — metr.org/time-horizons, arxiv.org/html/2503.14499v1
Checklist enterprise 6 dimensões (adaptado) — augmentcode.com/guides/cto-ai-coding-checklist
Pilot enterprise (metodologia de rollout) — lumenalta.com/insights/how-to-evaluate-ai-coding-tools-for-enterprise-teams
Governança de benchmarks / harness effect — digitalapplied.com/blog/swe-bench-terminal-bench-benchmark-guide-2026
Devin SWE-bench technical report — cognition.ai/blog/swe-bench-technical-report

JIT Compilation — Guia Didático

Diego de Sousa Brandão — Tue, 09 Jun 2026 01:55:42 +0000

O que você vai aprender:
Como a JVM decide o que compilar e quando · A diferença real entre C1 e C2 · O que é o Code Cache e por que ele pode derrubar sua performance · GraalVM: JIT vs Native Image · Project Leyden: como o Java 25 resolve o warmup de vez

Índice

1. O Problema Original
- A cena que todo dev Java já viveu
- Comparativo das abordagens
2. Just-In-Time Compilation
- O processo completo de um método na JVM
- Fluxo visual
- Por que a compilação não trava a aplicação
- Deoptimização — o que o curso não menciona
3. Os Dois Compiladores: C1 e C2
- Otimizações que o C2 aplica e o C1 não consegue
4. Code Cache
- Tamanhos padrão por versão
- O aviso mais temido em produção
- Flags essenciais para diagnóstico e tuning
- Detalhe importante sobre o CompileThreshold
5. GraalVM
- 5.1 Graal JIT — substituto do C2
- 5.2 Native Image — AOT total
- Comparativo: JIT clássico vs GraalVM Native Image
- Por que Native Image tem peak performance menor
6. Project Leyden
- Como funciona — em dois passos
- Linha do tempo dos JEPs do Leyden
- Comparativo final: os três mundos
7. Quando Parar de se Preocupar com Warmup
- Resposta direta: Java 25+
- Contexto prático para Kubernetes
8. Linha do Tempo e Resumo Executivo
- Evolução completa da performance JVM
- Resumo executivo — referência rápida
9. GraalVM vs sem GraalVM — análise com dados reais
- O que os dados dizem sobre adoção em produção
- Cenário 1 — Sem GraalVM: HotSpot JIT puro
- Cenário 2 — GraalVM modo JIT
- Cenário 3 — GraalVM Native Image
- Decisão rápida
Referências Bibliográficas

Seção 1 — O Problema Original

Por que o Java era lento e, como ele resolveu isso

A cena que todo dev Java já viveu

💡 Você mede a performance de um método logo que a aplicação sobe: 200ms.
Mede de novo 30 segundos depois: 8ms.
O que aconteceu? A aplicação estava "esquentando".
Isso tem nome, tem mecanismo e, a partir do Java 25, tem solução definitiva.

Java compila código-fonte (.java) para bytecode (.class) — um formato intermediário, agnóstico de plataforma. A JVM interpreta esse bytecode em qualquer máquina. Isso é o famoso write once, run anywhere.

O custo: interpretação instrução por instrução é lenta. Em 1996, Java rodava 10 a 20× mais lento que C.

Comparativo das abordagens

Abordagem	Portabilidade	Performance	Exemplo
Compilado nativo	❌ Binário por SO	⭐⭐⭐⭐⭐ Máxima	C / C++
Interpretado puro	✅ Bytecode universal	⭐ Baixa	Java 1.0 (1996)
JIT — híbrido	✅ Bytecode universal	⭐⭐⭐⭐⭐ Alta	Java 1.3+ (2000)
AOT Cache (Leyden)	✅ Bytecode universal	⭐⭐⭐⭐⭐ Alta + startup rápido	Java 24+ (2024)

💬 A pergunta que originou o JIT: e se a JVM pudesse aprender enquanto roda quais partes merecem ser compiladas para código nativo — sem abrir mão da portabilidade?

Seção 2 — Just-In-Time Compilation

Como a JVM observa, decide e compila em tempo real

O JIT é o mecanismo pelo qual a HotSpot JVM observa o código em execução e, quando identifica trechos chamados com frequência (hot spots), os compila para código de máquina nativo — em uma thread separada, sem parar a aplicação.

O processo completo de um método na JVM

Passo 1 — Execução interpretada (Tier 0)

A JVM começa interpretando o bytecode linha a linha. Lento, mas funciona imediatamente. Ao mesmo tempo, dois contadores são incrementados por método:

Method invocation count — quantas vezes o método foi chamado
Loop back-edge count — quantas vezes os loops do método executaram

Passo 2 — Compilação pelo C1, rápida e com profiling (Tiers 1–3)

Quando os contadores cruzam o Tier3CompileThreshold (padrão: 2.000 invocações), o método entra na fila JIT. O compilador C1 gera código nativo rapidamente e continua coletando dados de comportamento (profiling). A aplicação já roda mais rápido, mas ainda não no máximo.

Passo 3 — Compilação pelo C2, otimização agressiva (Tier 4)

Quando o método atinge o Tier4CompileThreshold (padrão: 15.000 invocações), o C2 entra em ação. Ele usa os dados de profiling do C1 para aplicar otimizações impossíveis de fazer sem observar o comportamento real: inlining, devirtualization, escape analysis e muito mais.

Passo 4 — Armazenamento no Code Cache

O código nativo compilado pelo C2 vai para o Code Cache — uma região especial da memória fora do heap. A partir daí, o método roda na velocidade máxima possível, sem interpretação, sem compilação, sem overhead.

Fluxo visual

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐     ┌──────────────┐
│   TIER 0    │ ──► │   TIERS 1 – 3    │ ──► │    TIER 4       │ ──► │  CODE CACHE  │
│             │     │                  │     │                 │     │              │
│ Interpretado│     │ C1 compila       │     │ C2 otimiza      │     │ Nativo em    │
│ puro        │     │ + coleta         │     │ agressivamente  │     │ memória      │
│             │     │ profiling        │     │                 │     │ especial     │
└─────────────┘     └──────────────────┘     └─────────────────┘     └──────────────┘
    Lento               Rápido                   Máximo                Ultra-rápido

O símbolo % no output de -XX:+PrintCompilation indica que o método está no Code Cache — o estado mais otimizado possível.

Por que a compilação não trava a aplicação?

✅ A fila JIT e os compiladores rodam em threads separadas. Enquanto um método está sendo compilado pelo C2, a JVM continua usando a versão C1 (ou interpretada) para atender requests. Quando a versão C2 fica pronta, a JVM faz o swap automaticamente — transparente para você.

⚠️ Deoptimização — o que o curso não menciona

❌ O C2 faz otimizações especulativas baseadas no que observou até agora. Se o comportamento mudar (ex: um método que era sempre chamado com Integer agora recebe String), a JVM pode deoptimizar o método — jogar fora a versão C2 e voltar para o C1 ou interpretado. Esse ciclo pode se repetir. Em produção, deoptimizações frequentes aparecem nos logs JIT como made not entrant e são sinais de código com comportamento inconsistente.

Seção 3 — Os Dois Compiladores: C1 e C2

Filosofias opostas, usadas na ordem certa

	C1 — Client Compiler	C2 — Server Compiler
Tiers	1, 2, 3	4 exclusivamente
Filosofia	Compila RÁPIDO, otimiza POUCO	Compila DEVAGAR, otimiza MUITO
Tempo de startup	Excelente	Ruim isolado
Peak performance	Boa	Máxima
Coleta profiling	Sim (tier 3)	Usa o que o C1 coletou
Escrito em	C++	C++ (HotSpot) / Java (Graal)
Caso ideal	Apps curta duração, CLIs	APIs, servidores, microsserviços

💬 Analogia: C1 é o mecânico que faz uma regulagem rápida para você sair logo. C2 é o engenheiro de F1 que passa a noite otimizando cada componente. A Tiered Compilation usa os dois na ordem certa, sem que você precise decidir.

Otimizações que o C2 aplica e o C1 não consegue

1. Method Inlining

// Antes — chamada separada com overhead
result = calculate(x);

int calculate(int x) {
    return x * 2 + 1;
}

// Depois — C2 inlina o corpo diretamente
result = x * 2 + 1;  // chamada eliminada

Elimina o overhead de chamada de método em hot paths. É a otimização mais impactante do C2.

2. Escape Analysis

// Antes — parece precisar de alocação no heap
Point p = new Point(x, y);
return p.x + p.y;

// Depois — C2 detecta que p não escapa do método
return x + y;  // objeto eliminado, zero alocação

Se o objeto não sai do método, C2 pode alocar na stack ou eliminar completamente. Reduz pressão no GC.

3. Devirtualization

// Antes — polimórfico: qual método chamar?
animal.sound();  // Dog? Cat? Bird?

// Depois — C2 observou: 99% das vezes é Dog
dog.sound();  // chamada direta + inlining

Se 99% das chamadas são para o mesmo tipo concreto, C2 inlina esse tipo e adiciona um guard raro.

4. Loop Unrolling

// Antes — loop com overhead de controle
for (int i = 0; i < 4; i++)
    sum += arr[i];

// Depois — C2 desenrola o loop
sum += arr[0];
sum += arr[1];
sum += arr[2];
sum += arr[3];

Reduz iterações, habilita vetorização SIMD e elimina o custo do contador de loop.

5. Dead Code Elimination

// Antes
boolean DEBUG = false;
if (DEBUG) {
    log.trace("calculando...");  // nunca vai rodar
}
return x * 2;

// Depois — C2 remove o bloco morto completamente
return x * 2;

6. Range Check Elimination

// Antes — Java verifica bounds a cada acesso
for (int i = 0; i < arr.length; i++)
    sum += arr[i];  // arr[i] verifica bounds toda vez

// Depois — C2 prova que o índice é sempre válido
// verificação eliminada no loop quente

Seção 4 — Code Cache

A região de memória que faz tudo isso funcionar e, que pode te trair

Após compilação pelo C2, o código nativo vai para o Code Cache — uma região de memória fora do heap Java, gerenciada separadamente. Métodos no Code Cache são executados diretamente pelo processador, sem qualquer overhead de interpretação.

Tamanhos padrão por versão

Versão Java	Tamanho padrão	Observação
Java ≤ 7 (32-bit)	32 MB	JVM 32-bit — removida no JDK 24
Java ≤ 7 (64-bit)	48 MB	—
Java 8+ (64-bit)	240 MB	Padrão atual — adequado para a maioria

❌ O aviso mais temido em produção

CodeCache is full. Compiler has been disabled.

A aplicação não cai. Mas o JIT para. Novos métodos não são compilados. Métodos podem ser desalojados e recompilados em loop. Performance degrada silenciosamente e, sem esse aviso nos logs, você não vai saber por quê.

Flags essenciais para diagnóstico e tuning

# Ver o que está sendo compilado em tempo real
-XX:+PrintCompilation

# Inspecionar tamanho atual do Code Cache
-XX:+PrintCodeCache

# Log completo para arquivo (útil em servidores remotos)
-XX:+UnlockDiagnosticVMOptions -XX:+LogCompilation

# Ajustar tamanho máximo do Code Cache
-XX:ReservedCodeCacheSize=256m

# Threads de compilação (1/3 para C1, 2/3 para C2)
-XX:CICompilerCount=6

# Threshold de invocações (só funciona sem Tiered Compilation)
-XX:CompileThreshold=10000

⚠️ Detalhe importante sobre o CompileThreshold

O -XX:CompileThreshold=10000 é amplamente citado mas quase nunca é o que a JVM usa. Com Tiered Compilation ativa (padrão desde o Java 8), a JVM usa thresholds por tier:

Tier3CompileThreshold = 2.000

Tier4CompileThreshold = 15.000

O CompileThreshold genérico só é relevante quando você desativa a Tiered Compilation com -XX:-TieredCompilation.

Seção 5 — GraalVM

Um terceiro compilador e, uma alternativa radical ao JIT

O GraalVM não é "só uma JVM mais rápida". É uma plataforma com duas abordagens fundamentalmente diferentes — que você precisa entender separadamente.

5.1 Graal JIT — substituto do C2, mesmo modelo JIT

O compilador Graal pode substituir o C2 dentro da HotSpot JVM usando a interface JVMCI (disponível desde o Java 9). Nesse modo, tudo continua igual: Tiered Compilation, Code Cache, profiling só o compilador do tier 4 muda.

-XX:+UseJVMCICompiler    # ativa o Graal JIT no lugar do C2

O Graal JIT é escrito em Java (não em C++ como o C2), o que permite otimizações mais sofisticadas e facilita evolução. Em benchmarks específicos, ele supera o C2 em throughput de pico.

5.2 Native Image — AOT total, sem JVM em runtime

A opção mais radical do GraalVM: compilação AOT (Ahead-Of-Time) completa. O bytecode vira um executável nativo antes da execução. Não há JVM em runtime. Não há JIT. Não há warmup.

# Gerar executável nativo
native-image -jar minha-aplicacao.jar

# Resultado: binário nativo (~50ms startup, memória mínima)

Comparativo: JIT clássico vs GraalVM Native Image

Característica	JIT (HotSpot padrão)	GraalVM Native Image
Startup	Segundos (warmup necessário)	~50ms (instantâneo)
Peak performance	Máxima — C2 adaptativo	Inferior — sem JIT em runtime
Uso de memória	Maior (JVM + heap)	Muito menor
Reflexão dinâmica	✅ Suportada nativamente	⚠️ Requer `reflect-config.json`
Spring Boot simples	✅ Funciona out of the box	✅ Funciona (GraalVM plugin)
Spring Boot complexo	✅ Funciona sempre	⚠️ Pode precisar de ajustes
Caso ideal	APIs, microsserviços com estado	Serverless, CLIs, functions
Build time	Padrão	Muito mais longa (5–15 min)

❌ Por que Native Image tem peak performance menor?

O JIT é adaptativo: ele observa o comportamento real em runtime e aplica otimizações especulativas baseadas nesse comportamento. O Native Image compila tudo antes, sem dados de runtime. Otimizações como devirtualization especulativa e inlining agressivo de chamadas polimórficas ficam comprometidas. Para cargas variáveis e código polimórfico, o C2 vence no longo prazo.

Seção 6 — Project Leyden

A solução definitiva para o warmup — sem abrir mão do JIT

O warmup do JIT sempre foi o calcanhar de Aquiles do Java em ambientes cloud-native. Containers que sobem a cada scale-out, funções serverless, pods Kubernetes, todos começam do zero, sem cache JIT. O Project Leyden resolve isso.

Como funciona — em dois passos

Passo 1 — Training Run (executado uma única vez)

A JVM roda a aplicação normalmente e salva em um arquivo .aot tudo que normalmente faria no startup e warmup: classes carregadas e linkadas, perfis de invocação, código JIT compilado para os hot spots identificados.

Passo 2 — Execuções de Produção (usam o cache)

Todos os starts subsequentes carregam o cache. Classes já linkadas, hot spots já identificados, código C2 já compilado para os métodos críticos. A aplicação começa com performance de pico desde o primeiro request — sem warmup.

# Passo 1: Training run (uma vez, fora de produção)
java -XX:AOTCacheOutput=app.aot -jar app.jar

# Passo 2: Todas as execuções em produção
java -XX:AOTCache=app.aot -jar app.jar

# Spring Boot 3.3+ já integra esse workflow nativamente

Linha do tempo dos JEPs do Leyden

Versão	Ano	JEP	O que entrega
JDK 24	2024	JEP 483	AOT Class Loading & Linking — classes pre-carregadas. Spring PetClinic 42% mais rápido no startup.
JDK 25	2025	JEP 515	AOT Method Profiling — perfis JIT no cache. Warmup praticamente eliminado.
JDK 26	2026	JEP 516	Cache universal, agnóstico de GC. Suporte a ZGC e Shenandoah. Cache baseline incluído no JDK — zero config.

Comparativo final: os três mundos

┌──────────────────────────┬────────────────────────────┬──────────────────────────┐
│    JIT CLÁSSICO          │   GRAALVM NATIVE IMAGE     │   PROJECT LEYDEN         │
│    (HotSpot)             │                            │   (JDK 25+)              │
├──────────────────────────┼────────────────────────────┼──────────────────────────┤
│ ✓ Portabilidade total    │ ✓ Startup instantâneo      │ ✓ Startup ~42% mais      │
│ ✓ Peak performance max   │ ✓ Memória mínima           │   rápido                 │
│ ✓ Reflexão dinâmica      │ ✓ Ideal para serverless    │ ✓ Warmup eliminado       │
│ ✓ Sem mudanças no código │                            │ ✓ Peak performance max   │
│                          │ ✗ Sem JIT em runtime       │ ✓ Reflexão dinâmica      │
│ ✗ Startup lento          │ ✗ Peak performance menor   │ ✓ Sem mudanças no código │
│ ✗ Warmup (código frio)   │ ✗ Reflexão = config manual │                          │
│                          │ ✗ Build demorada           │ ✗ Requer training run    │
└──────────────────────────┴────────────────────────────┴──────────────────────────┘

✅ A frase que resume tudo

GraalVM Native Image substitui o JIT — você abre mão de otimizações adaptativas em troca de startup instantâneo.

Project Leyden preserva o JIT — você tem startup rápido e peak performance máxima, sem abrir mão de nada.

Para sistemas bancários com Spring Boot, Hibernate e cargas variáveis, Leyden é a resposta certa.

Seção 7 — Quando Parar de se Preocupar com Warmup

A resposta direta, versão por versão

Versão	O que muda	Impacto real no warmup
Java 8	Tiered Compilation padrão	JIT mais inteligente. Warmup ainda existe, mas bem gerenciado.
Java 11	AppCDS estável	Startup ~10–20% mais rápido. Warmup JIT inalterado.
Java 17	AppCDS aprimorado + ZGC estável	Startup melhorado. Warmup JIT inalterado.
Java 21	Virtual Threads estáveis	⚠️ NÃO resolve warmup. Resolve throughput I/O-bound. São problemas diferentes.
Java 24	Leyden: AOT Class Loading	Startup 40%+ mais rápido. Warmup parcialmente melhorado.
Java 25	Leyden: AOT Method Profiling	✅ WARMUP PRATICAMENTE ELIMINADO. JIT começa otimizando do primeiro request.
Java 26	AOT Cache universal + ZGC	Zero configuração extra. Cache baseline no JDK. Solução madura e completa.

✅ Resposta direta: Java 25+ com AOT Method Profiling (JEP 515)

A partir do Java 25, o warmup do JIT deixa de ser uma preocupação para a grande maioria das aplicações. O AOT Cache armazena os perfis de execução dos métodos quentes, permitindo que o C2 compile os hot spots imediatamente no startup, sem precisar observar execuções repetidas. Para quem usa Spring Boot 3.3+, o suporte já está integrado com configuração mínima.

Contexto prático para Kubernetes e auto-scaling

Sem Leyden:

Cada novo pod sobe sem cache JIT
Os primeiros requests recebem latências elevadas
Em ambientes com escala horizontal frequente, isso impacta diretamente o p95 e p99 de latência

Com Leyden (JDK 25+):

O pod sobe com o AOT Cache
Hot spots já identificados, código C2 já compilado
Performance de pico desde o primeiro request
O AOT Cache pode ser incluído na imagem Docker — sem step extra em runtime

Para ambientes bancários com Spring Boot + Kubernetes: JDK 25 com AOT Method Profiling é o caminho. Não exige mudanças no código, preserva todo o ecossistema Spring, mantém a performance máxima do C2 e elimina o problema de cold start que existe hoje.

Seção 8 — Linha do Tempo e Resumo Executivo

Evolução completa da performance JVM

Versão	Ano	Marco
Java 1.0	1996	Interpretado puro — 10–20× mais lento que C
Java 1.1	1997	Primeiro JIT experimental — ainda muito básico
Java 1.3	2000	HotSpot JVM como padrão — JIT adaptativo com C1 e C2
Java 7	2011	Tiered Compilation disponível como opção
Java 8	2014	Tiered Compilation padrão — C1+C2 automático
Java 9	2017	JVMCI: suporte ao Graal JIT como alternativa ao C2
Java 11	2018	AppCDS estável — startup melhorado
Java 21	2023	Virtual Threads estáveis — throughput I/O-bound resolvido
Java 24	2024	Project Leyden: AOT Class Loading — startup 42% mais rápido
Java 25	2025	Project Leyden: AOT Method Profiling — warmup eliminado na prática
Java 26	2026	AOT Cache universal + ZGC — solução madura e completa

Resumo executivo — referência rápida

Conceito	O que você precisa saber
JIT	A JVM compila hot spots para código nativo em runtime, em thread separada, sem parar a aplicação.
Hot spot	Método com alto número de invocações ou iterações de loop — candidato à compilação JIT.
C1 (tiers 1–3)	Compila rápido com otimizações básicas. Coleta profiling para o C2.
C2 (tier 4)	Compila profundo com otimizações agressivas: inlining, escape analysis, devirtualization, loop unrolling.
Tiered Compilation	Estratégia padrão desde Java 8: usa C1 primeiro (startup rápido) e C2 depois (peak performance).
Code Cache	Região de memória onde vive o código nativo compilado. 240 MB padrão no Java 8+. Cheio = problema grave.
Deoptimização	JVM joga fora a versão C2 se o comportamento mudar. Normal, mas frequência alta indica código inconsistente.
Graal JIT	Substituto do C2 escrito em Java. Mesmo modelo JIT, otimizações diferentes. Ativo via `-XX:+UseJVMCICompiler`.
GraalVM Native Image	AOT total: sem JVM em runtime, sem warmup, mas sem JIT adaptativo. Ideal para serverless/CLIs.
Project Leyden	AOT Cache: treina uma vez, usa sempre. JDK 25 elimina warmup sem abrir mão do JIT ou do código atual.
Quando resolver	Java 25+ para enterprise/Spring. GraalVM Native Image para serverless/CLIs simples.

GraalVM vs sem GraalVM — análise com dados reais

O que os dados dizem sobre adoção em produção

Antes de entrar nos cenários, é importante calibrar as expectativas com números verificados.

O relatório New Relic State of the Java Ecosystem 2024 — baseado em dados de observabilidade de centenas de milhares de aplicações em produção — não registrou GraalVM Native Image como uma categoria de uso relevante entre as aplicações monitoradas. O relatório rastreia versões de JDK, vendors e GCs, mas o Native Image sequer aparece como item mensurável, o que por si só indica adoção marginal no universo enterprise geral. ¹

O relatório Azul State of Java 2025 — com mais de 2.000 profissionais Java respondentes globalmente, confirma que 99% das organizações pesquisadas utilizam Java ativamente, com quase 70% delas tendo mais da metade de suas aplicações rodando na JVM. O foco absoluto das empresas continua sendo JVM clássica com HotSpot. ²

O InfoQ Java Trends Report 2024 classifica o GraalVM Native Image para startup rápido na categoria "Early Majority" o que significa que a tecnologia existe e funciona, mas ainda não é mainstream. Para contexto, "Early Majority" no modelo de adoção de tecnologia representa algo entre 16% e 50% do mercado potencial, mas isso descreve o estágio de maturidade da tecnologia, não sua penetração real em produção. ³

Um dado de produção concreto vem do blog BackendBytes (fevereiro de 2026), que documentou migrações reais de equipes Spring Boot para Native Image: startup caindo de 7 segundos para 80ms, memória de 480 MB para 130 MB, mas com throughput em steady state 10 a 25% menor em comparação ao JIT. Esse número de queda de throughput é consistente entre múltiplas equipes migradas. ⁴

Um dado importante de contexto estratégico: em setembro de 2025, a Oracle anunciou o desacoplamento do GraalVM do Java SE, descontinuando o GraalVM Native Image para clientes do Java SE Product (Oracle JDK pago). O argumento oficial é que os objetivos de startup rápido e menor footprint serão perseguidos pelo Project Leyden como parte padrão do OpenJDK. Clientes usando o Graal JIT foram orientados a migrar de volta ao HotSpot JIT padrão. ⁵

O GraalVM Native Image continua disponível pela GraalVM Community Edition (mantida pela Oracle Labs e pela comunidade), mas o sinal estratégico é claro: a Oracle apostou no Leyden como caminho padrão, não no Native Image.

Os três cenários com benefícios e trade-offs reais

Cenário 1 — Sem GraalVM: HotSpot JIT puro

É o padrão atual de produção da grande maioria das aplicações Java no mundo. Você usa o C1 e o C2 da HotSpot, com Tiered Compilation ativa desde o Java 8.

Benefícios:

Peak performance máxima no longo prazo, o C2 faz otimizações adaptativas impossíveis de reproduzir em AOT
Funciona com qualquer biblioteca, framework ou padrão de reflexão sem configuração extra
Todo o ecossistema Spring, Hibernate, Jackson, Kafka funciona sem ressalvas
Deoptimização e recompilação automáticas quando o comportamento do código muda
Suporte e documentação amplíssimos, é a JVM que todos conhecem
Build time idêntico ao padrão, nenhuma etapa adicional

Trade-offs:

Startup lento: aplicações Spring Boot complexas levam de 4 a 11 segundos para estar prontas
Warmup necessário: os primeiros requests são mais lentos enquanto o JIT "aprende"
Em Kubernetes com auto-scaling, cada novo pod começa do zero sem cache JIT
Uso de memória maior, a JVM, o heap e o Code Cache consomem mais RAM

Quando usar: APIs enterprise, microsserviços com Spring Boot complexo, sistemas com Hibernate ou qualquer uso intenso de reflexão, cargas variáveis onde o C2 adaptativo faz diferença. Ou seja: a maioria das aplicações bancárias em produção hoje.

Cenário 2 — GraalVM modo JIT (Graal no lugar do C2)

A JVM continua sendo a HotSpot. Tiered Compilation, Code Cache, profiling, tudo igual. Só o compilador do tier 4 muda: o C2 é substituído pelo Graal, ativado com -XX:+UseJVMCICompiler.

Benefícios:

Comportamento idêntico para o desenvolvedor, nenhuma mudança no código ou no processo de build
O compilador Graal é escrito em Java (não em C++), o que permite algoritmos de otimização mais sofisticados
Em workloads específicos com código muito regular e previsível, pode superar o C2 em throughput de pico
Mantém todas as vantagens do JIT: deoptimização, profiling adaptativo, reflexão dinâmica

Trade-offs:

Em setembro de 2025, a Oracle orientou explicitamente que clientes do Oracle JDK migrem de volta ao HotSpot JIT padrão, sinalizando que esse caminho não é o futuro ⁵
Benefício de performance não é garantido, em muitos workloads o desempenho é equivalente ou ligeiramente inferior ao C2
Menos testado em produção que o C2, ecossistema de suporte mais restrito
O Graal JIT continua disponível na GraalVM CE, mas fora do mainstream Oracle

Quando usar: experimentos de performance em workloads muito específicos, pesquisa, ou contextos onde você já usa GraalVM CE e quer avaliar. Não recomendado como estratégia padrão de produção após o desacoplamento anunciado pela Oracle.

Cenário 3 — GraalVM Native Image (AOT total)

O bytecode vira um executável nativo antes de rodar. Não há JVM em runtime. Não há JIT. Não há warmup.

Benefícios:

Startup instantâneo: de 4–11 segundos para 40–120ms em migrações documentadas ⁴
Uso de memória drasticamente menor: redução de 60–70% em casos reais (480 MB → 130 MB) ⁴
Ideal para ambientes com SLA de startup agressivo no Kubernetes, resolve o problema de pods perdendo a janela de readiness
Binário auto-contido: não depende de JVM instalada no ambiente de execução
Superfície de ataque reduzida: código morto removido na análise estática de build time
Menor custo em funções serverless cobradas por tempo de execução e memória

Trade-offs:

Throughput em steady state 10–25% menor que o JIT em produção real, dado documentado em múltiplas migrações ⁴
A "closed-world assumption" exige que todo o código acessível seja conhecido em build time, reflexão dinâmica, proxies e carregamento dinâmico de classes precisam de configuração explícita
Spring Boot, Hibernate, Jackson e similares funcionam, mas exigem hints de reflexão no reflect-config.json ou anotações específicas, o Spring Native/GraalVM plugin automatiza parte disso, mas não tudo
Build time muito mais longa: de 5 a 15 minutos para aplicações médias, dependendo do tamanho do classpath
Debugging em produção é mais limitado, sem JVM, sem JVMTI, ferramentas como JFR e Async Profiler têm suporte parcial
Sem deoptimização: se o comportamento mudar, não há mecanismo de correção automática em runtime
A descontinuação para clientes Oracle JDK cria incerteza sobre o suporte de longo prazo fora da GraalVM CE ⁵

Quando usar: serviços serverless (AWS Lambda, Google Cloud Run), CLIs distribuídas como executável, microsserviços muito simples sem reflexão complexa, ambientes com SLA de startup impossível de cumprir com JVM clássica.

Decisão rápida

Sua aplicação é...

  API enterprise / Spring Boot complexo / reflexão / carga variável?
  └─► HotSpot JIT puro  (+ Leyden no JDK 25+ para resolver o warmup)

  Serverless / CLI / startup crítico / memória muito restrita?
  └─► GraalVM Native Image  (com validação cuidadosa de reflexão)

  Quero experimentar Graal JIT sem mudar nada?
  └─► -XX:+UseJVMCICompiler  (mas avalie o desacoplamento Oracle antes)

Referências Bibliográficas

[1] NEW RELIC. 2024 State of the Java Ecosystem Report. San Francisco: New Relic, 2024. Disponível em: https://newrelic.com/resources/report/2024-state-of-the-java-ecosystem. Acesso em: jun. 2025.

[2] AZUL SYSTEMS. Azul 2025 State of Java Survey & Report. Sunnyvale: Azul, jan. 2025. Disponível em: https://www.azul.com/newsroom/azul-2025-state-of-java-survey-report/. Acesso em: jun. 2025.

[3] INFOQ EDITORIAL TEAM. InfoQ Java Trends Report — December 2024. InfoQ, dez. 2024. Disponível em: https://www.infoq.com/articles/java-trends-report-2024/. Acesso em: jun. 2025.

[4] BACKENDBYTES. GraalVM Native Images in Production: From 5-Second Startup to 50ms. BackendBytes, fev. 2026. Disponível em: https://backendbytes.com/articles/graalvm-native-images-java-production/. Acesso em: jun. 2025.

[5] ORACLE. Detaching GraalVM from the Java Ecosystem Train. Oracle Java Blog, set. 2025. Disponível em: https://blogs.oracle.com/java/detaching-graalvm-from-the-java-ecosystem-train. Acesso em: jun. 2025.

[6] OPENJDK. JEP 483: Ahead-of-Time Class Loading & Linking. OpenJDK, 2024. Disponível em: https://openjdk.org/jeps/483. Acesso em: jun. 2025.

[7] OPENJDK. JEP 514: Ahead-of-Time Command-Line Ergonomics. OpenJDK, 2025. Disponível em: https://openjdk.org/jeps/514. Acesso em: jun. 2025.

[8] OPENJDK. JEP 515: Ahead-of-Time Method Profiling. OpenJDK, 2025. Disponível em: https://openjdk.org/jeps/515. Acesso em: jun. 2025.

[9] OPENJDK. JEP 516: Ahead-of-Time Cache. OpenJDK, 2026. Disponível em: https://openjdk.org/jeps/516. Acesso em: jun. 2025.

[10] BAELDUNG. JVM Tiered Compilation. Baeldung, 2024. Disponível em: https://www.baeldung.com/jvm-tiered-compilation. Acesso em: jun. 2025.

[11] ORACLE GRAAL TEAM. Announcing Oracle GraalVM for JDK 24. Oracle Graal Blog, 2024. Disponível em: https://blogs.oracle.com/graal/oracle-graalvm-for-jdk-24. Acesso em: jun. 2025.

[12] GRAALVM. Native Image Documentation. GraalVM, 2025. Disponível em: https://www.graalvm.org/latest/docs/. Acesso em: jun. 2025.

[13] INFOQ EDITORIAL TEAM. InfoQ Java Trends Report 2025. InfoQ, dez. 2025. Disponível em: https://www.infoq.com/articles/java-trends-report-2025/. Acesso em: jun. 2025.

Documento de estudo pessoal · Diego Brandão · 2025

Migração do Java 11 para Java 17: Benefícios e Trade-offs com Evidências Técnicas

Diego de Sousa Brandão — Sun, 07 Sep 2025 18:45:03 +0000

Índice

Resumo
Benefícios da Migração
- 1.1 Melhorias de Performance
- 1.2 Novos Recursos de Linguagem
- 1.3 Melhorias de Segurança
- 1.4 Suporte Long-Term Support (LTS)
Trade-offs e Desafios
- 2.1 Questões de Compatibilidade
- 2.2 Desafios Específicos da Migração
- 2.3 Custos de Migração
Casos de Estudo Reais
- 3.1 Salesforce
- 3.2 Halodoc
Recomendações Práticas
- 4.1 Estratégia de Migração
- 4.2 Alternativas Graduais
Conclusão
Referências

Resumo

A migração do Java 11 para Java 17 representa uma atualização estratégica significativa para aplicações enterprise. Java 17 é uma versão Long-Term Support (LTS) que oferece melhorias substanciais em performance, segurança e recursos de linguagem, com suporte Oracle Premier até setembro de 2026. Este artigo apresenta uma análise técnica baseada em evidências sobre os benefícios e trade-offs desta migração.

Estudos de benchmark demonstram ganhos de performance de 6-26% com Java 17, enquanto novos recursos como Records, Sealed Classes e melhor tratamento de NullPointerException melhoram significativamente a produtividade do desenvolvedor. Os principais trade-offs incluem questões de compatibilidade com bibliotecas legadas e a necessidade de atualização de dependências.

1. Benefícios da Migração

1.1 Melhorias de Performance

Evidências de Benchmark Independentes

A OptaPlanner conduziu benchmarks extensivos comparando Java 11, 16 e 17, utilizando hardware estável (Intel Xeon Silver 4116 @ 2.1 GHz, 128 GiB RAM) em problemas de otimização reais durante 5 minutos cada. Os resultados demonstraram melhorias consistentes de performance.

A Azul Systems reportou em benchmarks de 2025 que OpenJDK 17 foi 6% mais rápido que a baseline, enquanto soluções otimizadas como Azul Platform Prime alcançaram 26% de melhoria.

Melhorias no Garbage Collection

Java 17 introduz melhorias no garbage collector, particularmente em situações de baixa memória, resultando em ganhos de performance para aplicações que lidam com grandes datasets ou operações intensivas de memória.

O G1 garbage collector tornou-se padrão a partir do Java 9, oferecendo performance mais consistente e tempos de resposta mais previsíveis. ZGC (Z Garbage Collector) tornou-se production-ready no JDK 17, oferecendo coleta de lixo de baixa latência (sub-10ms) para heaps de até vários terabytes. Shenandoah está disponível em builds específicos como Red Hat OpenJDK e Amazon Corretto, mas não faz parte do Oracle JDK oficial.

1.2 Novos Recursos de Linguagem

Records

Records permitem criar classes de dados imutáveis especificando apenas os campos necessários; todos os outros métodos são gerados automaticamente. Records atuam como classes de dados onde todos os campos são final, garantindo imutabilidade da referência. Importante: Records são imutáveis por contrato apenas se usados com tipos imutáveis. O fato dos campos serem final garante imutabilidade da referência, mas não garante thread-safety absoluto se o campo for um objeto mutável.

// Java 11 - Classe tradicional
public class DataClass {
    private final Integer id;
    private final String name;

    public DataClass(Integer id, String name) {
        this.id = id;
        this.name = name;
    }

    public Integer getId() { return id; }
    public String getName() { return name; }

    @Override
    public boolean equals(Object o) { /* implementação */ }
    @Override
    public int hashCode() { /* implementação */ }
}

// Java 17 - Record
public record DataClass(Integer id, String name) {}

// Cuidado: Records com objetos mutáveis
public record PersonRecord(String name, List<String> hobbies) {}

PersonRecord person = new PersonRecord("João", new ArrayList<>());
person.hobbies().add("futebol"); // Modifica o estado interno!
// Para verdadeira imutabilidade, use List.copyOf() ou Collections.unmodifiableList()

Sealed Classes

Sealed Classes foram adicionadas à linguagem Java, restringindo quais outras classes ou interfaces podem estendê-las ou implementá-las, melhorando a segurança de tipos e organização do código.

Pattern Matching e Switch Expressions

Switch expressions melhoradas permitem sintaxe mais concisa e segura. O operador instanceof também foi aprimorado, permitindo verificação de tipo e cast em uma única linha. A principal vantagem é legibilidade e segurança de tipo, eliminando a necessidade de casts explícitos e reduzindo a possibilidade de ClassCastException.

Melhor Tratamento de NullPointerException

Uma atualização incrivelmente útil no Java 17 são as NullPointerExceptions melhoradas! Finalmente, nos logs de stack trace, é possível ver qual campo específico causou a NullPointerException.

// Java 17 - NPE melhorada
String s = null;
System.out.println(s.toLowerCase());

// Exception output:
// java.lang.NullPointerException: Cannot invoke "String.toLowerCase()" 
// because "s" is null

1.3 Melhorias de Segurança

Atualizações Regulares de Segurança

O modelo de lançamento de segurança Java mudou para estar alinhado com o cronograma Oracle Critical Patch Update (CPU), onde releases CPU são lançados na terceira terça-feira de janeiro, abril, julho e outubro.

JDK 17 introduziu melhorias significativas de segurança incluindo modo de validação segura XML habilitado por default, algoritmos SHA-1 desabilitados por padrão em assinaturas XML, e melhorias no suporte OCSP com requisições HTTP GET para performance.

Encapsulamento Forte de Internals do JDK

JEP 403 fortalece o encapsulamento de internals do JDK. Java 17 é fortemente encapsulado por padrão, então reflexão para internals do JDK não é mais permitida. Código que acessa campos e métodos não-públicos de APIs java.* lançará InaccessibleObjectException.

1.4 Suporte Long-Term Support (LTS)

Java 17 é uma versão LTS com Oracle Premier Support até setembro de 2026, proporcionando estabilidade e atualizações de segurança por período estendido. O processo de LTS garante que essas versões tornem-se mais estáveis e seguras devido a correções de bugs, melhorias de performance e patches de segurança.

2. Trade-offs e Desafios

2.1 Questões de Compatibilidade

Deprecação e Remoção de APIs

Provavelmente a mudança mais significativa relacionada à segurança no JDK 17 é JEP 411: Deprecate the Security Manager for Removal. JDK 17 inicia esse processo depreciando várias APIs do Security Manager.

Vários parâmetros JVM foram removidos ou depreciados até o Java 17. Se sua aplicação dependia das funcionalidades experimentais AOT ou Graal JIT no Java 11, considere a transição para GraalVM.

Problemas com Bibliotecas de Terceiros

Nem todas as bibliotecas e frameworks de terceiros têm garantia de suporte ao Java 17 imediatamente. Verificar compatibilidade e atualizações é crucial. Ferramentas de build (Maven, Gradle) e IDEs devem ser atualizadas para suportar Java 17.

2.2 Desafios Específicos da Migração

Problemas com Lombok

Um problema recorrente em migrações é incompatibilidade com versões antigas do Lombok. Um erro comum é:

java.lang.IllegalAccessError: class lombok.javac.apt.LombokProcessor cannot access class com.sun.tools.javac.processing.JavacProcessingEnvironment

A solução prática é atualizar o Lombok para uma versão compatível (por exemplo, >= 1.18.22) e validar a compilação/annotation-processing em ambientes CI e locais. Em casos extremos, configure o --add-opens temporariamente apenas para testes, mas prefira atualizar bibliotecas e remover dependências de internals.

Configuração de Garbage Collection

Embora coletores de lixo mais novos como G1 ofereçam melhor performance, eles podem requerer ajustes. Aplicações com configurações customizadas de GC precisarão revisitar essas configurações.

Modularização (Opcional)

Importante: A modularização NÃO é obrigatória para Java 17. Aplicações podem continuar usando o classpath tradicional exatamente como em Java 11. A migração para o Module System (JPMS) é completamente opcional e só deve ser considerada se você quiser benefícios específicos como:

Encapsulamento mais forte de pacotes internos
Dependências explícitas entre módulos
Redução de footprint de memória em aplicações modulares

A grande maioria das aplicações enterprise pode migrar para Java 17 sem qualquer mudança no sistema de módulos.

2.3 Custos de Migração

Testes Extensivos Necessários

Antes de migrar microserviços Java do JDK 11 para JDK 17, é essencial garantir que todos os testes unitários, de integração e de sistema passem com sucesso. Este passo é necessário para verificar que a aplicação funciona como esperado.

Tempo de Desenvolvimento

A Salesforce reportou que a migração do JDK 11 para JDK 17 levou três anos de planejamento com sete meses de desenvolvimento ativo. Importante: Este prazo reflete o tamanho massivo do ecossistema Salesforce (Sales Cloud, Service Cloud, Marketing Cloud) com milhares de aplicações e microserviços. Empresas menores terão prazos significativamente mais curtos - a maioria das organizações pode completar a migração em algumas semanas ou meses, dependendo da complexidade da arquitetura.

No entanto, as lições aprendidas pela Salesforce permitirão que futuras migrações, como JDK 21, sejam completadas em apenas um ano, demonstrando o valor do aprendizado organizacional.

3. Casos de Estudo Reais

3.1 Salesforce

A Salesforce liderou uma migração desafiadora do JDK 11 para JDK 17 para garantir performance e escalabilidade das aplicações principais, incluindo Sales Cloud, Service Cloud e Marketing Cloud. A migração entregou melhorias significativas de performance, possibilitando processamento mais rápido.

3.2 Halodoc

A Halodoc migrou seus microserviços backend Java do JDK 11 para JDK 17, enfrentando desafios específicos como conflitos entre dependências Redisson e Jackson, que foram resolvidos através de cuidadoso exame das versões de dependências e ajustes necessários para garantir compatibilidade.

4. Recomendações Práticas

4.1 Estratégia de Migração

Análise de Dependências: Analisar dependências do projeto para garantir compatibilidade com Java 17. Atualizar bibliotecas ou frameworks desatualizados para versões que suportem a nova versão Java.
Ambiente de Testes: Testar aplicação em ambiente especial de testes com JDK atualizado. Revisar e atualizar todas as dependências e ferramentas de build para versões compatíveis com JDK 17.
Análise Estática: Executar verificação estática de código para identificar onde problemas podem ocorrer. Ferramentas como Checkstyle, PMD, ou SpotBugs podem ser utilizadas.

4.2 Alternativas Graduais

Para organizações não prontas para migração completa, alguns fornecedores de JDK oferecem soluções otimizadas que podem combinar versões de API com JVMs mais recentes. É recomendável avaliar benchmarks específicos para seu caso de uso antes de adotar soluções comerciais que prometem melhorias de performance específicas.

5. Conclusão

A migração do Java 11 para Java 17 oferece benefícios substanciais e mensuráveis:

Benefícios Principais:

Melhorias de performance de 6-26% conforme benchmarks independentes
Recursos de linguagem modernos como Records, Sealed Classes e melhor tratamento de exceções (NPE melhoradas desde Java 14)
Melhorias significativas de segurança e encapsulamento forte
Suporte LTS: Oracle Premier até 2026, Extended até 2029, com alternativas de suporte de outros fornecedores
ZGC production-ready para aplicações que necessitam baixa latência

Trade-offs Principais:

Necessidade de atualização de dependências e ferramentas
Problemas específicos com bibliotecas como Lombok
Investimento em tempo de desenvolvimento e testes
Configurações de GC podem requerer ajustes dependendo do perfil da aplicação

Graças à forte compatibilidade retroativa do Java, a migração do 11 para o 17 tende a ser incremental e de baixo risco, especialmente em comparação com saltos maiores (ex: 8 → 17). A compatibilidade permite mudar para Java 17 sem alterações de código obrigatórias (modularização é opcional) e aproveitar todos os recursos atualizados. A versão 17 é Long-term Support, garantindo atualizações de segurança por período estendido com múltiplas opções de fornecedores.

Para organizações enterprise, a migração é altamente recomendada, especialmente considerando que aplicações de grande escala e alta carga verão definitivamente melhor performance, tempo de inicialização mais rápido e menor footprint de memória após a migração.

6. Referências

HashStudioz Technologies. (2024). Java Project Migration: Step-by-Step Guide from Java 11 to 17. Retrieved from https://www.hashstudioz.com/blog/java-11-to-java-17-migration-guide/
Bell-SW. (2024). How to Migrate from Java 11 to Java 17: Step-by-Step Tutorial. Retrieved from https://bell-sw.com/blog/migration-from-java-11-to-java-17/
HackerNoon. (2023). Is Migrating From Java 11 to Java 17 Worth It? Retrieved from https://hackernoon.com/is-migrating-from-java-11-to-java-17-worth-it
Medium - Pradeep Chirumamilla. (2024). Java 11 to Java 17 Migration: A Guide with Key Features and Code Implementation. Retrieved from https://medium.com/@pradeepchirumamilla01/java-11-to-java-17-migration-a-guide-with-key-features-and-code-implementation-dd63e0bd79e3
Halodoc Engineering. (2023). A Practical Guide to Migrating from JDK 11 to JDK 17. Retrieved from https://blogs.halodoc.io/jdk-17-migration/
Zenesys. (2024). Migrating a Project From Java 11 to Java 17: A Step-by-Step Guide. Retrieved from https://www.zenesys.com/migrating-a-project-from-java-11-to-java-17-a-step-by-step-guide
Medium - Alex Klimenko. (2025). Migrating from Java 8 to Java 17: What Changed and Potential Issues. Retrieved from https://medium.com/@alxkm/migrating-from-java-8-to-java-17-what-changed-and-potential-issues-85d2e85fc1ca
DEV Community - NIX. (2022). Migrating a Project From Java 11 to Java 17: A Step-by-Step Guide for Developers. Retrieved from https://dev.to/nix/migrating-a-project-from-java-11-to-java-17-a-step-by-step-guide-for-developers-42n
Salesforce Engineering. (2025). Behind Salesforce's JDK 11 to JDK 17 Migration. Retrieved from https://engineering.salesforce.com/behind-salesforces-jdk-11-to-jdk-17-migration-lessons-for-modernizing-large-scale-java-applications/
Medium - Alex Klimenko. (2024). Modernizing Legacy Java: A Practical Guide to Migrating to Java 17/21+. Retrieved from https://medium.com/@alxkm/modernizing-legacy-java-a-practical-guide-to-migrating-to-java-17-21-b3ab6a215f1f
OptaPlanner. (2021). How much faster is Java 17? Retrieved from https://www.optaplanner.org/blog/2021/09/15/HowMuchFasterIsJava17.html
Oracle. (2021). JDK 17 Release Notes, Important Changes, and Information. Retrieved from https://www.oracle.com/java/technologies/javase/17-relnote-issues.html
GitHub - Ionut Balosin. (2024). JVM Performance Benchmarks. Retrieved from https://github.com/ionutbalosin/jvm-performance-benchmarks
Azul Systems. (2025). Benchmarks Show Faster Java Performance Improvement. Retrieved from https://www.azul.com/blog/benchmarks-show-faster-java-performance-improvement/
Oracle. (2014). Avoiding Benchmarking Pitfalls on the JVM. Retrieved from https://www.oracle.com/technical-resources/articles/java/architect-benchmarking.html
oj! Algorithms. (2022). JDK17 Benchmark. Retrieved from https://www.ojalgo.org/2021/11/jdk17-benchmark/
Oracle. (2024). Overview of Java SE Subscription Enterprise Performance Pack. Retrieved from https://docs.oracle.com/en/java/java-components/enterprise-performance-pack/epp-user-guide/overview.html
Ionut Balosin. (2023). JVM Performance Comparison for JDK 17. Retrieved from https://ionutbalosin.com/2023/03/jvm-performance-comparison-for-jdk-17/
Pretius. (2022). Java 17 features: A comparison between versions 8 and 17. Retrieved from https://pretius.com/blog/java-17-features
Oracle. (2021). JDK Releases. Retrieved from https://www.java.com/releases/
Oracle. (2024). Consolidated JDK 17 Release Notes. Retrieved from https://www.oracle.com/java/technologies/javase/17all-relnotes.html
Oracle. (2025). Oracle Java SE Support Roadmap. Retrieved from https://www.oracle.com/java/technologies/java-se-support-roadmap.html
Baeldung. (2024). New Features in Java 17. Retrieved from https://www.baeldung.com/java-17-new-features
Oracle. (2024). Java™ SE Development Kit 17, 17.0.15 Release Notes. Retrieved from https://www.oracle.com/java/technologies/javase/17-0-15-relnotes.html
Oracle. (2024). Java Security Resource Center. Retrieved from https://www.oracle.com/java/technologies/security.html
Wikipedia. (2025). Java version history. Retrieved from https://en.wikipedia.org/wiki/Java_version_history
Sean Mullan. (2021). JDK 17 Security Enhancements. Retrieved from https://seanjmullan.org/blog/2021/09/14/jdk17
Red Hat. (2024). OpenJDK Life Cycle and Support Policy. Retrieved from https://access.redhat.com/articles/1299013
Oracle. (2021). Java Platform, Standard Edition Oracle JDK Migration Guide, Release 11. Retrieved from https://docs.oracle.com/en/java/javase/11/migrate/index.html
Oracle. (2024). Migrating From JDK 8 to Later JDK Releases. Retrieved from https://docs.oracle.com/en/java/javase/17/migrate/migrating-jdk-8-later-jdk-releases.html

Java Records vs Lombok: Guia Definitivo para Escolher a Ferramenta Certa

Diego de Sousa Brandão — Mon, 21 Jul 2025 23:23:42 +0000

Introdução

A eterna busca por reduzir o código boilerplate em Java ganhou duas ferramentas poderosas: Java Records (introduzidos no Java 14 e estabilizados no Java 16) e Lombok (biblioteca amplamente adotada há anos). Embora ambos ataquem o mesmo problema - a verbosidade do Java - eles fazem isso de maneiras fundamentalmente diferentes, com implicações importantes para o design e arquitetura do seu código.

Este artigo vai além da comparação superficial de sintaxe e mergulha nas diferenças semânticas, casos de uso práticos e trade-offs de cada abordagem.

Records Java: Mais que Redução de Boilerplate

O que são Records?

Records não são apenas uma forma concisa de criar classes - eles são tipos de produto com semântica específica. Segundo a JEP 395:

"Records são portadores transparentes de dados imutáveis"

A palavra-chave aqui é transparente. Records seguem o princípio:

"A API de um record modela o estado, todo o estado, e nada além do estado"

Exemplo Básico

// Antes: 40+ linhas de código boilerplate
public class Pessoa {
    private final String nome;
    private final int idade;

    public Pessoa(String nome, int idade) {
        this.nome = nome;
        this.idade = idade;
    }

    public String getNome() { return nome; }
    public int getIdade() { return idade; }

    @Override
    public boolean equals(Object o) { /* implementação */ }
    @Override
    public int hashCode() { /* implementação */ }
    @Override
    public String toString() { /* implementação */ }
}

// Depois: 1 linha
public record Pessoa(String nome, int idade) {}

Características dos Records

Imutabilidade por Design: Todos os campos são private final
Transparência: Não há estado oculto
Construtores Canônicos: Gerados automaticamente
Métodos Padrão: equals(), hashCode(), toString() implementados automaticamente
Acessores: Métodos com o mesmo nome dos componentes

Lombok: Flexibilidade Através de Anotações

O que é Lombok?

Lombok é uma biblioteca que gera código em tempo de compilação através de anotações. Não impõe semântica específica - é pura redução de boilerplate.

Exemplo com Lombok

@Data
public class Produto {
    private String nome;
    private double preco;

    // Método personalizado
    public void aplicarDesconto(double desconto) {
        this.preco -= desconto;
    }
}

Principais Anotações

@Data: Gera getters, setters, equals(), hashCode(), toString()
@Value: Classe imutável (equivalente a um record)
@Builder: Padrão Builder
@Slf4j: Injeção de logger
@Getter/@Setter: Getters e setters específicos

Comparação Detalhada

Aspecto	Records	Lombok
Semântica	Tipos de produto transparentes	Geração de código
Imutabilidade	Por padrão	Opcional (@Value)
Flexibilidade	Limitada	Alta
Herança	Não suportada	Suportada
Estado Oculto	Proibido	Permitido
Dependência Externa	Não	Sim
Versão Java	14+ (estável no 16+)	Qualquer
Desempenho	Nativo	Geração em tempo de compilação

Quando Usar Records

✅ Use Records para:

1. DTOs (Data Transfer Objects)

public record UsuarioDTO(String nome, String email, LocalDate nascimento) {}

2. Objetos de Valor

public record Dinheiro(BigDecimal valor, String moeda) {}

3. Respostas de API

public record ApiResponse<T>(T dados, int status, String mensagem) {}

4. Configurações Imutáveis

public record DatabaseConfig(String url, String usuario, int timeout) {}

5. Entidades JPA Simples (com limitações)

@Entity
public record Produto(
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    Long id,
    String nome,
    BigDecimal preco
) {}

❌ Evite Records quando:

Precisar de mutabilidade
Necessitar de herança
Requerer estado oculto
Trabalhar com frameworks que exigem construtores sem argumentos
Precisar de métodos de ciclo de vida JPA complexos

Quando Usar Lombok

✅ Use Lombok para:

1. Entidades JPA Complexas

@Entity
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Usuario {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String nome;
    private String email;

    @OneToMany(mappedBy = "usuario", cascade = CascadeType.ALL)
    private List<Pedido> pedidos = new ArrayList<>();
}

2. Modelos de Negócio com Comportamento

@Data
@Slf4j
public class ContaBancaria {
    private String numero;
    private BigDecimal saldo;

    public void sacar(BigDecimal valor) {
        log.info("Sacando {} da conta {}", valor, numero);
        if (saldo.compareTo(valor) >= 0) {
            saldo = saldo.subtract(valor);
        } else {
            throw new IllegalArgumentException("Saldo insuficiente");
        }
    }
}

3. Builders Complexos

@Builder
@Data
public class Relatorio {
    private String titulo;
    private LocalDate dataInicio;
    private LocalDate dataFim;
    private List<String> colunas;
    private Map<String, Object> parametros;
}

// Uso
Relatorio relatorio = Relatorio.builder()
    .titulo("Vendas Mensais")
    .dataInicio(LocalDate.now().minusMonths(1))
    .dataFim(LocalDate.now())
    .colunas(Arrays.asList("produto", "quantidade", "valor"))
    .build();

❌ Evite Lombok quando:

O projeto exigir zero dependências externas
Houver problemas de compatibilidade com IDEs
A equipe não estiver familiarizada com a biblioteca
Precisar de garantias semânticas específicas

Casos de Uso Práticos

Cenário 1: Sistema de E-commerce

// DTO para resposta da API - USE RECORD
public record ProdutoResponse(
    Long id,
    String nome,
    BigDecimal preco,
    String categoria
) {}

// Entidade JPA com comportamento - USE LOMBOK
@Entity
@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Produto {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String nome;
    private BigDecimal preco;
    private String categoria;
    private Integer estoque;

    public void reduzirEstoque(int quantidade) {
        if (estoque < quantidade) {
            throw new IllegalArgumentException("Estoque insuficiente");
        }
        this.estoque -= quantidade;
    }
}

Cenário 2: Sistema Bancário

// Objeto de valor imutável - USE RECORD
public record Moeda(String codigo, String nome, String simbolo) {}

// Entidade complexa com estado mutável - USE LOMBOK
@Entity
@Data
@EqualsAndHashCode(onlyExplicitlyIncluded = true)
@NoArgsConstructor
@Slf4j
public class Conta {
    @Id
    @EqualsAndHashCode.Include
    private String numero;

    private BigDecimal saldo;
    private String titular;

    @OneToMany(mappedBy = "conta", cascade = CascadeType.ALL)
    private List<Transacao> transacoes = new ArrayList<>();

    public void transferir(BigDecimal valor, Conta destino) {
        log.info("Transferindo {} de {} para {}", valor, this.numero, destino.numero);
        // Lógica de transferência
    }
}

Híbrido: Usando Records e Lombok Juntos

// Record com anotações do Lombok para funcionalidades adicionais
@Slf4j
public record ProcessamentoResult(
    String id,
    LocalDateTime timestamp,
    boolean sucesso,
    String mensagem
) {
    public ProcessamentoResult {
        log.info("Resultado do processamento {}: {}", id, sucesso ? "SUCESSO" : "FALHA");
    }
}

O Futuro: Spring Data Commons Recomenda Records

O Spring Framework oficialmente recomenda Records para DTOs e projeções:

// Recomendação oficial do Spring Data
public record NamesOnly(String firstname, String lastname) {}

// Em vez de usar Lombok
@Value
class NamesOnly {
    String firstname, lastname;
}

Diretrizes para Tomada de Decisão

Escolha Records quando:

✅ Estiver no Java 16+
✅ Precisar de objetos imutáveis
✅ Quiser garantias semânticas fortes
✅ Criar DTOs ou objetos de valor
✅ Buscar máxima performance (sem overhead de biblioteca)

Escolha Lombok quando:

✅ Precisar de flexibilidade máxima
✅ Trabalhar com herança
✅ Requerer mutabilidade
✅ Usar versões antigas do Java
✅ Precisar de funcionalidades como @builder ou @Slf4j

Use Ambos quando:

✅ Records para DTOs e objetos de valor
✅ Lombok para entidades e modelos de negócio
✅ Aproveitar o melhor de cada abordagem

Migração Gradual

Estratégia de Migração para Records:

Identifique candidatos: DTOs, objetos de valor, classes imutáveis simples
Migre gradualmente: Comece com classes menos críticas
Teste thoroughly: Verifique serialização e frameworks
Monitore performance: Records podem ter características diferentes

Exemplo de Migração:

// Antes (Lombok)
@Value
public class Endereco {
    String rua;
    String cidade;
    String cep;
}

// Depois (Record)
public record Endereco(String rua, String cidade, String cep) {}

Considerações de Performance

Records:

✅ Sem overhead de biblioteca
✅ Otimizações do compilador
⚠️ Criação de objetos em atualizações (imutabilidade)

Lombok:

✅ Código gerado otimizado
⚠️ Dependência de bibliotecas externas
⚠️ Possível overhead de reflection em algumas situações

Conclusão

A escolha entre Records e Lombok não é uma questão de "melhor" ou "pior", mas sim de adequação ao contexto:

Records brilham quando você precisa de semântica forte, imutabilidade e transparência
Lombok excele quando você precisa de flexibilidade, mutabilidade e compatibilidade com versões antigas

A tendência é usar ambos estrategicamente:

Records para DTOs, objetos de valor e dados imutáveis
Lombok para entidades complexas e modelos de negócio

Com o Java evoluindo e mais projetos adotando versões recentes, Records estão se tornando a escolha padrão para muitos casos de uso. No entanto, Lombok continuará relevante para cenários que demandam máxima flexibilidade.

A chave é entender que essas ferramentas resolvem problemas similares de maneiras diferentes, e a escolha certa depende das necessidades específicas do seu projeto, versão do Java e arquitetura da aplicação.

Referências Bibliográficas

Por que Abandonar @Autowired em Campos e Adotar Injeção via Construtor

Diego de Sousa Brandão — Tue, 15 Jul 2025 00:55:48 +0000

A injeção de dependência via construtor representa uma evolução natural das práticas de desenvolvimento com Spring Framework. Este documento apresenta os fundamentos técnicos que justificam essa transição e como implementá-la efetivamente em projetos modernos.

Contextualização

O Spring Framework oferece três formas principais de injeção de dependência: por campo (field injection), por setter e por construtor. Embora a injeção por campo seja visualmente mais limpa e requeira menos código, ela apresenta limitações significativas que impactam a qualidade, manutenibilidade e robustez das aplicações.

Principais Benefícios da Injeção via Construtor

1. Transparência e Dependências Explícitas

A injeção via construtor expõe claramente todas as dependências de uma classe em sua assinatura. Esta transparência facilita a compreensão do código, permitindo que desenvolvedores identifiquem rapidamente quais componentes uma classe necessita para funcionar corretamente.

Exemplo prático:

// Injeção por campo - dependências ocultas
@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;
    @Autowired
    private EmailService emailService;
    // Dependências não são evidentes na assinatura da classe
}

// Injeção por construtor - dependências explícitas
@Service
public class UserService {
    private final UserRepository userRepository;
    private final EmailService emailService;

    public UserService(UserRepository userRepository, EmailService emailService) {
        this.userRepository = userRepository;
        this.emailService = emailService;
    }
}

2. Testabilidade Aprimorada

A injeção via construtor elimina a dependência do contexto Spring durante os testes unitários. As classes podem ser instanciadas diretamente, com mocks injetados como parâmetros do construtor, resultando em testes mais rápidos e independentes.

Vantagens nos testes:

Eliminação da necessidade de reflection
Testes mais performáticos
Maior simplicidade na configuração de mocks
Independência do framework Spring nos testes unitários

3. Princípio Fail-Fast

A injeção por campo permite a criação de objetos mesmo quando dependências obrigatórias não estão disponíveis, resultando em NullPointerException apenas durante a execução. A injeção via construtor impede a criação do objeto sem suas dependências, tornando problemas visíveis imediatamente durante a inicialização da aplicação.

4. Imutabilidade e Thread Safety

Apenas através da injeção via construtor é possível definir campos de dependência como final. Esta imutabilidade oferece:

Segurança de thread: Campos final são thread-safe por natureza
Prevenção de efeitos colaterais: Impossibilita modificações acidentais das dependências
Clareza conceitual: Facilita o raciocínio sobre o estado dos objetos

5. Detecção Precoce de Dependências Circulares

Ciclos de dependência são detectados imediatamente durante a inicialização dos beans quando se utiliza injeção via construtor. Com injeção por campo, esses problemas podem permanecer ocultos até a execução específica do código afetado.

6. Incentivo ao Bom Design

A injeção via construtor evidencia classes com muitas dependências, naturalmente incentivando a aplicação do Princípio da Responsabilidade Única (SRP). Construtores com muitos parâmetros sinalizam a necessidade de refatoração e decomposição de responsabilidades.

7. Alinhamento com Práticas Modernas do Spring

Desde o Spring 4.3, o framework suporta injeção automática via construtor para classes com construtor único, dispensando a anotação @Autowired. Esta é a abordagem oficialmente recomendada pela equipe do Spring.

Implementação Prática

Padrão Recomendado (Sem Lombok)

@Service
public class OrderService {
    private final OrderRepository orderRepository;
    private final PaymentService paymentService;
    private final NotificationService notificationService;

    public OrderService(OrderRepository orderRepository, 
                       PaymentService paymentService,
                       NotificationService notificationService) {
        this.orderRepository = orderRepository;
        this.paymentService = paymentService;
        this.notificationService = notificationService;
    }

    // métodos da classe...
}

Com Lombok (Quando Apropriado)

@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;
    private final PaymentService paymentService;
    private final NotificationService notificationService;

    // métodos da classe...
}

Estratégia de Migração

Para Código Legado

Priorização: Inicie por classes críticas e com maior cobertura de testes
Refatoração gradual: Migre uma classe por vez para minimizar riscos
Testes de regressão: Garanta que a funcionalidade permanece inalterada
Validação: Verifique se não há dependências circulares expostas

Para Novos Desenvolvimentos

Adote injeção via construtor como padrão desde o início
Configure linters e ferramentas de análise estática para detectar uso de @Autowired em campos
Estabeleça como prática obrigatória em code reviews

Considerações Especiais

Dependências Opcionais

Para dependências opcionais, utilize @Autowired(required = false) no construtor ou considere padrões como Optional:

public UserService(UserRepository userRepository, 
                   @Autowired(required = false) CacheService cacheService) {
    this.userRepository = userRepository;
    this.cacheService = Optional.ofNullable(cacheService);
}

Performance

A injeção via construtor não apresenta overhead significativo em relação à injeção por campo. Os benefícios em qualidade e manutenibilidade superam amplamente qualquer diferença marginal de performance.

Conclusão

A adoção da injeção via construtor representa um investimento na qualidade de longo prazo do código. Os benefícios em testabilidade, clareza, robustez e alinhamento com as melhores práticas do Spring justificam plenamente essa transição.

Esta mudança não é apenas uma questão de preferência pessoal, mas uma evolução natural em direção a um código mais robusto, testável e maintível, alinhado com os princípios modernos de desenvolvimento de software.

Referências Bibliográficas

Maratona de Testes Automatizados — Step 1: Testes Unitários

Diego de Sousa Brandão — Sun, 08 Jun 2025 16:55:13 +0000

Maratona de Testes em Java: Da Teoria à Prática

Step 1: Testes Unitários - A Base Sólida da Pirâmide de Testes

Índice

Por que testes unitários são fundamentais?
O que realmente define um teste unitário?
O que exatamente devemos testar?
Estruturando seus testes com clareza
As ferramentas do ofício: JUnit e Mockito
Exemplo completo: Testando um Controller REST
Solitary vs. Sociable: Duas abordagens
DRY vs. DAMP nos testes
Evitando armadilhas comuns
Práticas avançadas e técnicas eficazes
Integração Contínua
Lições finais
Conclusão
Recursos recomendados
Referências Bibliográficas

Por que testes unitários são fundamentais?

Testes unitários são como os alicerces de um edifício: invisíveis para o usuário final, mas absolutamente essenciais para a integridade e sustentação de todo o sistema. Eles são a base da "Pirâmide de Testes", um conceito desenvolvido por Mike Cohn que organiza os testes em camadas de diferentes granularidades, indicando também quantos testes devemos ter em cada uma dessas camadas.

No artigo "The Practical Test Pyramid", Ham Vocke destaca que "seus testes unitários serão muito rápidos. Em uma máquina razoável, você poderá rodar milhares deles em poucos minutos." Esta velocidade é crucial para o desenvolvimento ágil, permitindo que você obtenha feedback praticamente instantâneo sobre suas alterações de código.

O que realmente define um teste unitário?

Um teste unitário eficaz possui estas características essenciais:

Característica	Descrição	Por quê isso importa
⚡ Rápido	Executa em milissegundos	Permite feedback imediato durante o desenvolvimento
🧩 Isolado	Sem dependência externa (rede, banco, disco)	Evita falhas por causas externas à unidade testada
🔄 Determinístico	Sempre produz o mesmo resultado	Elimina testes "flaky" (instáveis)
🎯 Focado	Verifica uma única lógica ou comportamento	Facilita identificar exatamente o que falhou
📖 Legível	Clara separação entre cenário e verificação	Permite manutenção e entendimento a longo prazo

Como Ham Vocke menciona, "teste pequenas partes da sua base de código em isolamento e evite acessar bancos de dados, o sistema de arquivos ou fazer requisições HTTP." Este isolamento é o que torna os testes unitários verdadeiramente "unitários".

O que exatamente devemos testar?

Segundo Vocke, "você pode escrever testes unitários para todas as classes do seu código de produção, independentemente da funcionalidade delas." Isso significa que quase tudo pode e deve ser testado unitariamente:

✅ Classes de domínio com regras de negócio
✅ Controllers (testar mapeamentos e respostas)
✅ Services (testar fluxos e orquestrações)
✅ Repositórios com lógica própria
✅ Utils, validators, formatters (funções de propósito específico)

O importante é focar no comportamento observável da unidade, não em sua implementação interna. Como Vocke recomenda, devemos "testar para o comportamento observável em vez de refletir a estrutura interna do código em nossos testes."

Estruturando seus testes com clareza

Ham Vocke destaca duas formas eficazes de estruturar testes, que ele chama de "uma boa estrutura para todos os seus testes":

📐 1. Arrange → Act → Assert

@Test
public void deveCalcularValorTotalComDesconto() {
    // Arrange - Prepara o cenário
    Produto produto = new Produto("Notebook", 2000.0);
    Cliente clienteVip = new Cliente("João", TipoCliente.VIP);

    // Act - Executa a ação
    double valorFinal = calculadoraPreco.calcular(produto, clienteVip);

    // Assert - Verifica o resultado
    assertEquals(1800.0, valorFinal, 0.001);
}

💬 2. Given → When → Then (estilo BDD)

@Test
public void clienteVipDeveReceberDescontoEspecial() {
    // Given - Dado um cliente VIP e um produto
    Cliente clienteVip = new Cliente("Maria", TipoCliente.VIP);
    Produto produto = new Produto("Smartphone", 1000.0);

    // When - Quando calcular o preço final
    double valorFinal = calculadoraPreco.calcular(produto, clienteVip);

    // Then - Então deve aplicar 10% de desconto
    assertEquals(900.0, valorFinal, 0.001);
}

Vocke sugere que este padrão "pode ser aplicado a outros testes de nível mais alto também. Em todos os casos, eles garantem que seus testes permaneçam fáceis e consistentes de ler."

As ferramentas do ofício: JUnit e Mockito

JUnit 5

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import static org.junit.jupiter.api.Assertions.*;

class CalculadoraTest {

    private Calculadora calc;

    @BeforeEach
    void setup() {
        calc = new Calculadora();
    }

    @Test
    @DisplayName("Soma de dois números positivos")
    void deveSomarDoisNumerosPositivos() {
        // Act
        int resultado = calc.somar(5, 3);

        // Assert
        assertEquals(8, resultado);
    }

    @Test
    @DisplayName("Divisão por zero deve lançar exceção")
    void deveLancarExcecaoAoDividirPorZero() {
        // Assert + Act (verificando exceção)
        assertThrows(ArithmeticException.class, () -> {
            calc.dividir(10, 0);
        });
    }
}

Mockito

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;

@ExtendWith(MockitoExtension.class)
class PedidoServiceTest {

    @Mock
    DescontoService descontoService;

    @Mock
    EmailService emailService;

    @InjectMocks
    PedidoService pedidoService;

    @Test
    void deveAplicarDescontoAoFinalizarPedido() {
        // Arrange
        Pedido pedido = new Pedido(1L, 100.0);
        when(descontoService.calcularDesconto(pedido)).thenReturn(10.0);

        // Act
        pedidoService.finalizarPedido(pedido);

        // Assert
        assertEquals(90.0, pedido.getValorTotal());
        verify(emailService).enviarConfirmacao(pedido);
    }
}

Exemplo completo: Testando um Controller REST

Vamos ver um exemplo prático de como testar um controller REST em Spring Boot:

O Controller em produção

@RestController
@RequestMapping("/api/produtos")
public class ProdutoController {

    private final ProdutoService produtoService;

    public ProdutoController(ProdutoService produtoService) {
        this.produtoService = produtoService;
    }

    @GetMapping("/{id}")
    public ResponseEntity<ProdutoDTO> buscarPorId(@PathVariable Long id) {
        return produtoService.buscarPorId(id)
                .map(produto -> ResponseEntity.ok(new ProdutoDTO(produto)))
                .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<ProdutoDTO> criar(@RequestBody @Valid ProdutoRequest request) {
        Produto produto = produtoService.criar(
            new Produto(request.getNome(), request.getPreco())
        );
        return ResponseEntity
            .created(URI.create("/api/produtos/" + produto.getId()))
            .body(new ProdutoDTO(produto));
    }
}

Teste unitário com MockMVC

Ham Vocke explica que ferramentas como MockMVC são importantes porque "Spring MVC's controller faz uso intensivo de anotações para declarar em quais caminhos eles estão escutando, quais verbos HTTP usar, quais parâmetros eles analisam do caminho da URL ou parâmetros de consulta e assim por diante. Simplesmente invocar um método do controller em seus testes unitários não testará todas essas coisas cruciais."

@ExtendWith(MockitoExtension.class)
class ProdutoControllerTest {

    private MockMvc mockMvc;

    @Mock
    private ProdutoService produtoService;

    @InjectMocks
    private ProdutoController produtoController;

    @BeforeEach
    void setup() {
        mockMvc = MockMvcBuilders
            .standaloneSetup(produtoController)
            .build();
    }

    @Test
    void deveRetornarProdutoQuandoExistir() throws Exception {
        // Arrange
        Produto produto = new Produto("Teclado Mecânico", 350.0);
        produto.setId(1L);

        when(produtoService.buscarPorId(1L))
            .thenReturn(Optional.of(produto));

        // Act & Assert
        mockMvc.perform(get("/api/produtos/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.nome").value("Teclado Mecânico"))
            .andExpect(jsonPath("$.preco").value(350.0));
    }

    @Test
    void deveRetornarNotFoundQuandoProdutoNaoExistir() throws Exception {
        // Arrange
        when(produtoService.buscarPorId(99L))
            .thenReturn(Optional.empty());

        // Act & Assert
        mockMvc.perform(get("/api/produtos/99"))
            .andExpect(status().isNotFound());
    }

    @Test
    void deveCriarNovoProduto() throws Exception {
        // Arrange
        Produto produtoParaSalvar = new Produto("Mouse", 89.9);
        Produto produtoSalvo = new Produto("Mouse", 89.9);
        produtoSalvo.setId(42L);

        when(produtoService.criar(any(Produto.class)))
            .thenReturn(produtoSalvo);

        // Act & Assert
        mockMvc.perform(post("/api/produtos")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\"nome\":\"Mouse\",\"preco\":89.9}")
        )
            .andExpect(status().isCreated())
            .andExpect(header().string("Location", "/api/produtos/42"))
            .andExpect(jsonPath("$.nome").value("Mouse"))
            .andExpect(jsonPath("$.preco").value(89.9));
    }
}

Solitary vs. Sociable: Duas abordagens para testes unitários

Segundo Vocke, "alguns argumentam que todos os colaboradores da sua unidade sob teste devem ser substituídos por mocks ou stubs", enquanto "outros argumentam que apenas colaboradores que são lentos ou têm efeitos colaterais maiores deveriam ser substituídos por stubs ou mocks."

Este conceito foi criado por Jay Fields em seu livro "Working Effectively with Unit Tests", que cunhou os termos "testes unitários solitários" para testes que substituem todos os colaboradores, e "testes unitários sociáveis" para testes que permitem interações com colaboradores reais.

Ham Vocke confessa: "Eu me vejo usando ambas as abordagens o tempo todo. Se se torna estranho usar colaboradores reais, usarei mocks e stubs generosamente. Se eu sentir que envolver o colaborador real me dá mais confiança em um teste, apenas faço stub das partes mais externas do meu serviço."

Exemplo de teste solitário (com mocks)

@Test
void deveCalcularImpostoSobreVendaComMocks() {
    // Arrange
    BigDecimal valorBase = new BigDecimal("1000.00");

    // Mockando todas as dependências
    when(aliquotaService.buscarAliquota("SP"))
        .thenReturn(new BigDecimal("0.18"));

    when(descontoService.calcularDesconto(valorBase))
        .thenReturn(new BigDecimal("100.00"));

    // Act
    BigDecimal imposto = calculadoraImpostoService.calcular(valorBase, "SP");

    // Assert
    assertEquals(new BigDecimal("162.00"), imposto); // (1000 - 100) * 0.18
}

Exemplo de teste sociável (com colaboradores reais)

@Test
void deveCalcularImpostoSobreVendaComColaboradoresReais() {
    // Arrange
    BigDecimal valorBase = new BigDecimal("1000.00");

    // Usando implementação real do serviço de desconto
    DescontoService descontoServiceReal = new DescontoServiceImpl();

    // Ainda mockando o serviço de alíquota (externo)
    AliquotaService aliquotaMock = mock(AliquotaService.class);
    when(aliquotaMock.buscarAliquota("SP"))
        .thenReturn(new BigDecimal("0.18"));

    // Injetando uma mistura de dependências reais e mockadas
    CalculadoraImpostoService calculadora = 
        new CalculadoraImpostoServiceImpl(descontoServiceReal, aliquotaMock);

    // Act
    BigDecimal imposto = calculadora.calcular(valorBase, "SP");

    // Assert
    assertEquals(new BigDecimal("180.00"), imposto); // Considerando que o desconto real é 0
}

DRY vs. DAMP nos testes: Equilibrando clareza e repetição

Ham Vocke alerta: "Não tente ser excessivamente DRY (Don't Repeat Yourself). Duplicação é aceitável se melhorar a legibilidade."

Em testes, muitas vezes é melhor priorizar a clareza em vez da não-repetição. Um acrônimo útil para recordar é DAMP: Descriptive And Meaningful Phrases.

Exemplo questionável (muito DRY):

// Definição central, reusada em todos os testes
private Cliente clienteVip;
private Produto produtoPadrao;

@BeforeEach
void setup() {
    clienteVip = new Cliente("João", TipoCliente.VIP);
    produtoPadrao = new Produto("Item", 100.0);
}

@Test
void deveAplicarDescontoVipEmProduto() {
    assertEquals(90.0, calculadoraPreco.calcular(produtoPadrao, clienteVip));
}

@Test
void deveIncluirFreteGratisPara() {
    assertTrue(beneficioService.temFreteGratis(clienteVip, produtoPadrao));
}

Exemplo melhor (mais DAMP):

@Test
void deveAplicarDescontoVipEmProduto() {
    // Arrange - Dados específicos para este teste
    Cliente clienteVip = new Cliente("João", TipoCliente.VIP);
    Produto notebook = new Produto("Notebook", 2000.0);

    // Act
    double valorComDesconto = calculadoraPreco.calcular(notebook, clienteVip);

    // Assert - Expectativa clara
    assertEquals(1800.0, valorComDesconto, 
                "Cliente VIP deve receber 10% de desconto");
}

@Test
void deveIncluirFreteGratisPara() {
    // Arrange - Dados específicos para este teste
    Cliente clienteVip = new Cliente("Maria", TipoCliente.VIP);
    Produto smartTV = new Produto("Smart TV", 1500.0);

    // Act
    boolean temFreteGratis = beneficioService.temFreteGratis(clienteVip, smartTV);

    // Assert - Expectativa clara
    assertTrue(temFreteGratis, 
              "Cliente VIP deve ter frete grátis independente do produto");
}

Evitando armadilhas comuns

"Mas eu preciso testar este método privado!"

Ham Vocke alerta: "Se você já se encontrou em uma situação em que realmente precisa testar um método privado, você deve dar um passo atrás e se perguntar por quê." Ele continua: "Estou bastante certo de que isso é mais um problema de design do que um problema de escopo."

Quando você sente essa necessidade, geralmente há um problema de design da classe — ela provavelmente está fazendo muitas coisas e violando o princípio da responsabilidade única.

A solução mais elegante:

// Antes: Classe grande com método privado complexo
public class FaturamentoService {
    public BigDecimal calcular(Pedido pedido) {
        // lógica...
        return calcularImpostos(valorBase); // método privado complexo
    }

    private BigDecimal calcularImpostos(BigDecimal valor) {
        // lógica complexa de cálculo de impostos
    }
}

// Depois: Extrair para uma classe dedicada com interface pública
public class FaturamentoService {
    private final ImpostoCalculator impostoCalculator;

    public FaturamentoService(ImpostoCalculator impostoCalculator) {
        this.impostoCalculator = impostoCalculator;
    }

    public BigDecimal calcular(Pedido pedido) {
        // lógica...
        return impostoCalculator.calcular(valorBase); // Agora é público!
    }
}

public class ImpostoCalculator {
    public BigDecimal calcular(BigDecimal valor) {
        // mesma lógica complexa, agora testável
    }
}

"Preciso ter 100% de cobertura!"

Vocke argumenta contra testar código trivial: "Sim, você deve testar a interface pública. Mais importante, no entanto, você não testa código trivial. Não se preocupe, Kent Beck disse que tudo bem. Você não ganhará nada testando getters ou setters simples ou outras implementações triviais."

Focar em cobertura por si só pode levar a testes ruins que não adicionam valor. Busque qualidade em vez de quantidade.

Práticas avançadas e técnicas eficazes

À medida que você ganha experiência em testes unitários, algumas técnicas avançadas podem ajudar a tornar seus testes mais elegantes, legíveis e fáceis de manter. Vejamos três técnicas importantes que podem elevar significativamente a qualidade da sua suite de testes.

1. Dados de teste expressivos

O que é: Métodos de fábrica (factory methods) ou objetos builders que criam dados de teste com nomes semânticos, em vez de usar configurações inline de objetos diretamente nos testes.

Quando usar:

Quando os objetos de teste têm muitas propriedades que precisam ser configuradas
Quando você repete a mesma configuração de objetos em vários testes
Quando a configuração obscurece a intenção principal do teste

Benefícios:

Foco no "o quê" está sendo testado, não no "como" os objetos são criados
Leitura mais natural - o nome do método descreve o cenário
Encapsulamento de detalhes irrelevantes para a intenção do teste
Fácil reutilização entre testes similares

// Ruim: Dados aleatórios desconexos
@Test
void deveAprovarCreditoParaClienteBomPagador() {
    Cliente cliente = new Cliente("X123", 35);
    cliente.setScoreCredito(750);
    cliente.setRendaMensal(5000.0);

    boolean aprovado = creditoService.analisarCredito(cliente, 10000.0);

    assertTrue(aprovado);
}

// Melhor: Nome do método de fábrica expressivo
@Test
void deveAprovarCreditoParaClienteBomPagador() {
    Cliente clienteBomPagador = criarClienteComBomHistoricoCredito();

    boolean aprovado = creditoService.analisarCredito(clienteBomPagador, 10000.0);

    assertTrue(aprovado);
}

private Cliente criarClienteComBomHistoricoCredito() {
    Cliente cliente = new Cliente("Maria", 35);
    cliente.setScoreCredito(750);
    cliente.setRendaMensal(5000.0);
    return cliente;
}

Você também pode evoluir para padrões mais sofisticados como builders fluentes:

// Usando um builder expressivo
@Test
void deveAprovarCreditoParaClienteBomPagador() {
    Cliente clienteBomPagador = ClienteBuilder.padrao()
        .comBomHistoricoCredito()
        .comRendaAdequada()
        .build();

    boolean aprovado = creditoService.analisarCredito(clienteBomPagador, 10000.0);

    assertTrue(aprovado);
}

2. Assertion libraries expressivas

O que são: Bibliotecas que oferecem uma sintaxe mais fluente e legível para verificações, substituindo os métodos padrão do JUnit.

Quando usar:

Para verificações complexas ou múltiplas em um único objeto
Quando se deseja uma leitura mais próxima da linguagem natural
Para verificações de coleções, onde se quer verificar múltiplos aspectos

Bibliotecas populares:

AssertJ: fluente e orientada a objetos
Hamcrest: baseada em matchers
Truth (Google): alternativa simples e expressiva

Benefícios:

Testes mais legíveis, quase como frases em inglês
Mensagens de erro mais descritivas quando falham
Encadeamento de verificações reduz duplicação
Maior expressividade para casos complexos

// JUnit padrão - Funcionais mas menos expressivas
assertEquals(3, lista.size());
assertTrue(lista.contains("item1"));
assertTrue(cliente.isAtivo());

// AssertJ - Mais fluente e expressivo
assertThat(lista)
    .hasSize(3)
    .contains("item1")
    .doesNotContain("item99");

assertThat(cliente.isAtivo()).isTrue();

Quando um teste falha, a mensagem de erro com AssertJ é mais informativa:

Expected size:<3> but was:<2>
Expected to contain:<"item1"> but did not

3. Testes parametrizados para casos similares

O que são: Testes que executam o mesmo código com diferentes entradas e expectativas de saída, gerando automaticamente múltiplos casos de teste a partir de uma única definição.

Quando usar:

Para testar múltiplas variações de um mesmo caso (comportamento com diferentes entradas)
Para regras de negócio que têm muitos casos específicos (ex: cálculos tributários)
Quando a lógica é a mesma, mas os dados variam
Para evitar duplicação de código em testes semelhantes

Benefícios:

Redução drástica de código duplicado
Facilidade para adicionar novos casos de teste
Documentação clara de todos os casos suportados
Facilita identificar quais casos específicos falharam

@ParameterizedTest
@CsvSource({
    "SP, 0.18",
    "RJ, 0.20",
    "MG, 0.17",
    "RS, 0.17"
})
void deveCalcularImpostoCorretoPorEstado(String estado, BigDecimal aliquotaEsperada) {
    // Arrange
    Produto produto = new Produto("Genérico", 100.0);

    // Act
    BigDecimal aliquota = impostoService.obterAliquota(estado, produto);

    // Assert
    assertEquals(aliquotaEsperada, aliquota);
}

O JUnit 5 suporta múltiplas fontes de dados para testes parametrizados:

@ValueSource: para listas simples de valores (@ValueSource(ints = {1, 2, 3}))
@CsvSource: para pares ou tuplas de valores como mostrado acima
@EnumSource: para testar com valores de um enum
@MethodSource: para casos complexos onde os dados são gerados por um método
@ArgumentsSource: para implementações personalizadas de geradores de dados

Essas técnicas avançadas são particularmente úteis quando sua base de código cresce e você precisa manter um conjunto grande de testes. Elas ajudam a reduzir a duplicação, melhorar a legibilidade e facilitar a manutenção a longo prazo.

Integração Contínua: Executando testes unitários automaticamente

Os testes unitários devem ser executados:

Localmente antes de commit/push
Na CI em cada push para qualquer branch
Antes de merge para branches principais

Este feedback rápido é possível graças à velocidade dos testes unitários.

Lições finais

Ham Vocke resume bem: "Uma vez que você pegar o jeito de escrever testes unitários, você se tornará cada vez mais fluente em escrevê-los. Substitua colaboradores externos por stubs, configure alguns dados de entrada, chame seu assunto sob teste e verifique se o valor retornado é o que você esperava."

Testes unitários são um investimento que:

⏱️ Economiza tempo a longo prazo
🔒 Permite refatorações com segurança
📚 Documenta o comportamento esperado
💻 Melhora o design do código
🧠 Reduz a carga cognitiva ao desenvolver

Conclusão

Como resumido no artigo de referência: "O código de teste é tão importante quanto o código de produção. Dê a ele o mesmo nível de cuidado e atenção. 'Isso é apenas código de teste' não é uma desculpa válida para justificar código desleixado."

Ao dominar a arte dos testes unitários, você estabelece a base sólida para construir um sistema robusto e confiável, que pode evoluir com segurança ao longo do tempo.

No próximo passo da nossa maratona, abordaremos testes de integração - a camada intermediária da pirâmide de testes que verifica como seus componentes trabalham juntos.

Recursos recomendados

📕 "Working Effectively with Unit Tests" por Jay Fields
📗 "Test Driven Development: By Example" por Kent Beck
📘 "Clean Code" por Robert C. Martin (capítulo sobre testes)
🌐 Documentação oficial do JUnit 5
🌐 Documentação oficial do Mockito
🌐 Documentação oficial do AssertJ

Referências Bibliográficas

Vocke, Ham. (2018). "The Practical Test Pyramid". Martin Fowler. Disponível em: https://martinfowler.com/articles/practical-test-pyramid.html
Cohn, Mike. (2009). "Succeeding with Agile: Software Development Using Scrum". Addison-Wesley Professional.
Fields, Jay. (2014). "Working Effectively with Unit Tests". Leanpub.
Beck, Kent. (2002). "Test Driven Development: By Example". Addison-Wesley Professional.
Martin, Robert C. (2008). "Clean Code: A Handbook of Agile Software Craftsmanship". Prentice Hall.
Fowler, Martin. (2006). "Mocks Aren't Stubs". MartinFowler.com. Disponível em: https://martinfowler.com/articles/mocksArentStubs.html
Spring Framework Documentation. "Testing". Disponível em: https://docs.spring.io/spring-framework/docs/current/reference/html/testing.html
JUnit 5 User Guide. Disponível em: https://junit.org/junit5/docs/current/user-guide/
Mockito Reference Documentation. Disponível em: https://javadoc.io/doc/org.mockito/mockito-core/latest/org/mockito/Mockito.html
AssertJ Documentation. Disponível em: https://assertj.github.io/doc/

Maratona de Testes Automatizados — Step 0: Fundamentos, Importância e a Pirâmide de Testes

Diego de Sousa Brandão — Tue, 06 May 2025 02:55:38 +0000

Step 0: Fundamentos, Importância e a Pirâmide de Testes

Índice

Por que testamos software?
Entendendo a Pirâmide de Testes
O Anti-padrão: O Sorvete de Testes
Duplicação Inteligente vs. Duplicação Desnecessária
DRY vs. DAMP em Testes
Testes de Caixa Branca vs. Caixa Preta
Princípios Essenciais para Todos os Níveis
O que vem a seguir?
Referências Bibliográficas

Por que testamos software?

Testar software transcende a simples busca por defeitos — é fundamentalmente um ato de construir confiança. Testes automatizados proporcionam a liberdade de evoluir o código sem receio, realizar refatorações profundas, validar integrações complexas, e entregar continuamente com a segurança de um sistema verificado.

Como Ham Vocke observa no artigo "The Practical Test Pyramid":

"Automating your repetitive tests can be a big game changer in your life as a software developer. Automate these tests and you no longer have to mindlessly follow click protocols in order to check if your software still works correctly. Automate your tests and you can change your codebase without batting an eye."

Tradução:

"Automatizar seus testes repetitivos pode ser um grande divisor de águas na sua vida como desenvolvedor de software. Automatize esses testes e você não precisará mais seguir protocolos de cliques sem pensar para verificar se seu software ainda funciona corretamente. Automatize seus testes e você poderá mudar sua base de código sem piscar."

A automação de testes é transformadora precisamente porque liberta desenvolvedores de tarefas repetitivas e tediosas, convertendo-as em verificações automáticas:

Testes manuais → Repetitivos → Tediosos → Propensos a erros → Lentos
Testes automatizados → Consistentes → Confiáveis → Rápidos → Confortantes

O impacto disso vai além da qualidade do software; reflete diretamente na qualidade de vida do desenvolvedor e na dinâmica das equipes.

Entendendo a Pirâmide de Testes

A Pirâmide de Testes (Test Pyramid) foi introduzida por Mike Cohn em seu livro Succeeding with Agile. Trata-se de uma metáfora visual poderosa que orienta a construção de uma suíte de testes balanceada, rápida e sustentável a longo prazo.

A pirâmide nos comunica dois conceitos fundamentais:

Diferentes níveis de granularidade: Os testes são agrupados em categorias que variam de escopo, desde pequenos métodos isolados até o sistema completo integrado.
Distribuição ideal: Quanto mais subimos na pirâmide, menor deve ser a quantidade de testes, seguindo o princípio de "muitos testes rápidos e baratos na base, poucos testes caros e lentos no topo".

Como Ham Vocke explica:

"Write lots of small and fast unit tests. Write some more coarse-grained tests and very few high-level tests that test your application from end to end."

Tradução:

"Escreva muitos testes unitários pequenos e rápidos. Escreva alguns testes mais abrangentes e muito poucos testes de alto nível que testem sua aplicação de ponta a ponta."

A estrutura contemporânea da pirâmide consiste em:

Nível	Tipo de Teste	Características	Quantidade
Base	Testes Unitários	Rápidos, isolados, confiáveis	Muitos
Meio	Testes de Integração	Verificam comunicação entre componentes	Moderada
Topo	Testes E2E/UI	Simulam comportamento do usuário	Poucos

Esta distribuição não é acidental — reflete o equilíbrio econômico entre velocidade de feedback, cobertura de cenários e custo de manutenção.

Nota sobre a Evolução da Pirâmide de Testes

Nota: Esta seção complementa o entendimento sobre a Pirâmide de Testes, explicando sua evolução histórica.

É importante destacar que a Pirâmide de Testes que apresentamos neste artigo representa uma versão mais contemporânea e refinada do conceito original introduzido por Mike Cohn.

A Pirâmide Original de Cohn (2009) consistia em três camadas:

Base: Testes Unitários (Unit Tests)
Meio: Testes de Serviço (Service Tests)
Topo: Testes de Interface do Usuário (UI Tests)

O termo "Service Tests" usado por Cohn era um tanto ambíguo e causou confusão na comunidade de desenvolvimento. Ele se referia a testes que verificavam a funcionalidade sem passar pela interface do usuário, mas que podiam envolver múltiplos componentes ou módulos.

A Pirâmide Moderna que apresentamos evoluiu para oferecer maior clareza e se adaptar às práticas atuais de desenvolvimento:

Base: Testes Unitários (Unit Tests)
Meio: Testes de Integração (Integration Tests)
Topo: Testes E2E/UI (End-to-End/UI Tests)

Por que a mudança?

Esta evolução não foi apenas uma questão de terminologia, mas reflete mudanças fundamentais nas práticas de desenvolvimento:

Maior granularidade: A camada intermediária agora é geralmente subdividida para acomodar diferentes tipos de integrações (API, componentes, contratos).
Arquiteturas distribuídas: Com a popularização de microsserviços e sistemas distribuídos, o conceito de "Service Tests" se tornou insuficiente para capturar a complexidade das integrações modernas.
DevOps e CI/CD: A automação completa de pipelines de entrega contínua demandou uma categorização mais precisa dos testes para otimizar velocidade e eficiência.
Práticas ágeis maduras: A experiência acumulada nas últimas décadas permitiu refinar o modelo para melhor servir aos fluxos de trabalho modernos.

Martin Fowler e outros influentes profissionais da área contribuíram para esta evolução, resultando em uma pirâmide mais detalhada e adaptada às necessidades contemporâneas de desenvolvimento de software.

A essência da metáfora original de Cohn permanece intacta: muitos testes rápidos na base, poucos testes lentos no topo. O refinamento da pirâmide representa nossa compreensão mais sofisticada de como implementar este princípio em contextos diversos e complexos.

O Anti-padrão: O Sorvete de Testes

Enquanto a pirâmide aponta para a estabilidade e eficiência, seu anti-padrão é o "Sorvete de Testes" (Test Ice Cream Cone), termo cunhado por Alberto Savoia e popularizado por Martin Fowler.

No sorvete de testes, a distribuição é invertida:

A base (testes unitários) é pequena ou inexistente
O meio (integração) é moderado
O topo (UI/E2E) é excessivamente volumoso

Ham Vocke alerta:

"Watch out that you don't end up with a test ice-cream cone that will be a nightmare to maintain and takes way too long to run."

Tradução:

"Tenha cuidado para não acabar com um sorvete de testes que será um pesadelo para manter e demorará muito tempo para executar."

As consequências desta distorção são severas:

Feedback lento: O ciclo de desenvolvimento se torna arrastado
Diagnóstico difícil: Falhas são complexas de isolar e corrigir
Fragilidade: Pequenas mudanças causam falhas em cascata
Alto custo: A manutenção consome recursos desproporcionais

A regra prática é: quanto mais alto o teste na pirâmide, maior o custo de manutenção, tempo de execução e propensão a falhas intermitentes ("flaky tests").

Duplicação Inteligente vs. Duplicação Desnecessária

Um equívoco comum é assumir que qualquer forma de duplicação de cobertura de testes é inaceitável. Ham Vocke apresenta uma visão mais equilibrada sobre este tema:

"If a higher-level test gives you more confidence that your application works correctly, you should have it. Writing a unit test for a Controller class helps to test the logic within the Controller itself. Still, this won't tell you whether the REST endpoint this Controller provides actually responds to HTTP requests."

Tradução:

"Se um teste de nível superior lhe dá mais confiança de que sua aplicação funciona corretamente, você deve tê-lo. Escrever um teste unitário para uma classe Controller ajuda a testar a lógica dentro do Controller em si. Ainda assim, isso não dirá se o endpoint REST que este Controller fornece realmente responde a requisições HTTP."

Existem dois tipos de duplicação em testes:

Duplicação inteligente: Testa o mesmo comportamento, mas sob perspectivas diferentes e complementares:

Teste unitário: valida a lógica interna
Teste de integração: valida a comunicação entre componentes
Teste E2E: valida o fluxo completo sob a perspectiva do usuário

Duplicação desnecessária: Testa exatamente o mesmo aspecto em múltiplos níveis, sem valor agregado:

Repetir todos os casos de borda e condicionais em todos os níveis da pirâmide
Duplicar testes de validação em múltiplas camadas

Ham Vocke recomenda:

"If you have tested all conditions confidently on a lower-level test, there's no need to keep a higher-level test in your test suite."

Tradução:

"Se você testou todas as condições com confiança em um teste de nível inferior, não há necessidade de manter um teste de nível superior em sua suíte de testes."

Isto nos leva a duas regras práticas:

Se um teste de nível superior encontra um erro e não há teste de nível inferior falhando, você precisa escrever um teste de nível inferior
Priorize a implementação de testes nos níveis mais baixos da pirâmide, sempre que possível.

DRY vs. DAMP em Testes

DRY (Don't Repeat Yourself) é um princípio fundamental da engenharia de software, mas em testes, existe uma tensão com outro princípio: DAMP (Descriptive And Meaningful Phrases).

Ham Vocke observa:

"Don't try to be overly DRY. Duplication is okay, if it improves readability. Try to find a balance between DRY and DAMP code."

Tradução:

"Não tente ser excessivamente DRY. Duplicação é aceitável, se melhorar a legibilidade. Tente encontrar um equilíbrio entre código DRY e DAMP."

Esta visão reflete uma maturidade na abordagem dos testes automatizados:

Princípio	Foco	Benefício	Riscos se usado em excesso
DRY	Evitar redundância	Facilidade de manutenção	Testes interdependentes e frágeis
DAMP	Clareza e intenção	Testes auto-documentados	Admite certa repetição, desde que contribua para a clareza

Em testes, clareza é frequentemente mais valiosa que concisão extrema, pois testes são lidos não apenas por quem os escreveu, mas por desenvolvedores investigando falhas ou entendendo o comportamento esperado do sistema.

Testes de Caixa Branca vs. Caixa Preta

Para compreender melhor os diferentes níveis da pirâmide, é útil relacioná-los com dois paradigmas clássicos de teste:

Testes de Caixa Branca (White Box):

Utilizam conhecimento da estrutura interna do código
Testam caminhos de execução, cobertura de branches, lógica interna
Focam em "como" o sistema implementa comportamentos
Predominantes em: testes unitários e testes de integração

Testes de Caixa Preta (Black Box):

Tratam o sistema como uma "caixa fechada"
Testam apenas as interfaces públicas e o comportamento observável
Focam em "o que" o sistema faz, não em como faz
Predominantes em: testes E2E e testes de aceitação

Existe também uma abordagem híbrida:

Testes de Caixa Cinza (Grey Box):

Combinam conhecimento da estrutura interna com teste via interfaces externas
Usam conhecimento do design para testar de forma mais eficiente
Comuns em: testes de integração e testes de API

Nível da Pirâmide	Tipo	Abordagem Predominante
Base	Unitários	Caixa Branca
Meio	Integração/Contratos	Caixa Cinza
Topo	UI, E2E, Aceitação	Caixa Preta

Princípios Essenciais para Todos os Níveis

Independentemente do nível da pirâmide, alguns princípios fundamentais devem ser observados:

Teste comportamento, não implementação:
- Foque no "o quê", não no "como"
- Isso permite refatoração sem quebrar testes

"Test for observable behavior instead." - Ham Vocke

Tradução:

"Teste o comportamento observável, em vez disso." - Ham Vocke

Código de teste é código de produção:
- Aplique as mesmas práticas de qualidade
- Refatore e mantenha limpo

"Test code is as important as production code. Give it the same level of care and attention." - Ham Vocke

Tradução:

"O código de teste é tão importante quanto o código de produção. Dê a ele o mesmo nível de cuidado e atenção." - Ham Vocke

Estruture claramente:
- Use padrão "Arrange-Act-Assert" ou "Given-When-Then"
- Mantenha o teste focado em um único aspecto

"A good structure for all your tests is this one: Set up the test data, Call your method under test, Assert that the expected results are returned." - Ham Vocke

Tradução:

"Uma boa estrutura para todos os seus testes é esta: Configure os dados de teste, Chame seu método sob teste, Verifique que os resultados esperados são retornados." - Ham Vocke

Priorize feedback rápido:
- Coloque testes rápidos nos primeiros estágios do pipeline
- Testes lentos em estágios posteriores

"A good build pipeline tells you that you messed up as quick as possible." - Ham Vocke

Tradução:

"Um bom pipeline de build informa que você errou o mais rápido possível." - Ham Vocke

Evite duplicação desnecessária:
- Se já está bem testado em nível mais baixo, um teste mais alto deve focar em novos aspectos
- Seja implacável eliminando testes que não agregam valor

"I delete high-level tests that are already covered on a lower level (given they don't provide extra value)." - Ham Vocke

Tradução:

"Eu excluo testes de alto nível que já estão cobertos em um nível inferior (desde que não forneçam valor adicional)." - Ham Vocke

O que vem a seguir?

No Step 1 da nossa maratona, mergulharemos a fundo na base da pirâmide: os testes unitários. Exploraremos:

A definição precisa de uma "unidade" de teste
A diferença entre testes "sociáveis" e "solitários"
O uso eficaz de Mocks e Stubs
A estruturação ideal de testes unitários
Exemplos práticos em Java utilizando JUnit e Mockito

Prepare-se para construir uma base sólida que permitirá que seu código evolua com segurança e confiança!

Referências Bibliográficas

Vocke, Ham. (2018). "The Practical Test Pyramid". Martin Fowler. Disponível em: https://martinfowler.com/articles/practical-test-pyramid.html
Cohn, Mike. (2009). "Succeeding with Agile: Software Development Using Scrum". Addison-Wesley Professional.
Fowler, Martin. (2012). "Test Pyramid". MartinFowler.com. Disponível em: https://martinfowler.com/bliki/TestPyramid.html
Freeman, Steve; Pryce, Nat. (2009). "Growing Object-Oriented Software, Guided by Tests". Addison-Wesley Professional.
Meszaros, Gerard. (2007). "xUnit Test Patterns: Refactoring Test Code". Addison-Wesley Professional.
Khorikov, Vladimir. (2020). "Unit Testing: Principles, Practices, and Patterns". Manning Publications.
Osherove, Roy. (2013). "The Art of Unit Testing: With Examples in .NET". Manning Publications.
Beck, Kent. (2002). "Test Driven Development: By Example". Addison-Wesley Professional.
Fields, Jay. (2014). "Working Effectively with Unit Tests". Leanpub.
Savoia, Alberto. (2011). "The Way of Testivus". Disponível em: https://www.artima.com/weblogs/viewpost.jsp?thread=203994

A Arte da Simplicidade no Desenvolvimento de Software: DRY, KISS, YAGNI e TDA

Diego de Sousa Brandão — Wed, 30 Apr 2025 22:59:33 +0000

"A simplicidade é o último grau de sofisticação." - Leonardo da Vinci

Índice

Introdução
O que são Princípios de Desenvolvimento de Software?
Por que seguir Princípios de Desenvolvimento é importante?
DRY - Don't Repeat Yourself (Não Se Repita)
DRY e o Padrão Factory
KISS - Keep It Simple, Stupid (Mantenha Simples, Estúpido)
YAGNI - You Aren't Gonna Need It (Você Não Vai Precisar Disso)
TDA - Tell, Don't Ask (Diga, Não Pergunte)
TDA e a Lei de Demeter
Críticas e Limitações dos Princípios
Integrando os Princípios em seu Desenvolvimento
Conclusão
Referências Bibliográficas

Introdução

No cenário atual do desenvolvimento de software, onde a complexidade dos sistemas cresce exponencialmente, a busca por clareza e simplicidade tornou-se uma necessidade fundamental. Desenvolvedores experientes reconhecem que código complicado não é sinônimo de código sofisticado - pelo contrário, a verdadeira elegância reside na simplicidade.

Este artigo explora quatro princípios fundamentais que transformaram o desenvolvimento de software: DRY (Don't Repeat Yourself), KISS (Keep It Simple, Stupid), YAGNI (You Aren't Gonna Need It) e TDA (Tell, Don't Ask). Estes princípios não são apenas técnicas isoladas, mas filosofias de design que, quando aplicadas corretamente, resultam em código mais limpo, manutenível e, paradoxalmente, mais poderoso.

O que são Princípios de Desenvolvimento de Software?

Princípios de desenvolvimento de software são diretrizes conceituais que orientam as decisões de design e implementação durante o processo de criação de software. Diferentemente de padrões de design específicos ou frameworks, estes princípios transcendem linguagens de programação e paradigmas, servindo como uma bússola para navegação no vasto campo de possibilidades do desenvolvimento de software.

Estes princípios representam o conhecimento acumulado ao longo de décadas pela comunidade global de desenvolvimento, capturando lições frequentemente aprendidas da maneira mais difícil: através de projetos malsucedidos, manutenções onerosas e bugs persistentes.

Por que seguir Princípios de Desenvolvimento é importante?

A importância de seguir princípios de desenvolvimento transcende preferências estéticas de código. Considere as seguintes vantagens:

Redução de custos a longo prazo: Sistemas bem projetados são consideravelmente mais econômicos para manter e estender.
Escalabilidade: Código que segue princípios sólidos adapta-se melhor ao crescimento da aplicação.
Facilidade de colaboração: Princípios compartilhados estabelecem uma linguagem comum entre desenvolvedores.
Resiliência: Sistemas bem projetados respondem melhor a mudanças nas especificações.
Qualidade perceptível: Usuários finais identificam indiretamente a qualidade do design através da confiabilidade e responsividade do sistema.

Examinemos agora os quatro princípios que são o foco deste artigo, explorando sua origem, aplicação e impacto.

DRY - Don't Repeat Yourself (Não Se Repita)

Origem e História

O princípio DRY foi formulado por Andy Hunt e Dave Thomas em seu influente livro "The Pragmatic Programmer", publicado em 1999. A definição original é direta e poderosa: "Todo conhecimento deve ter uma representação única, inequívoca e autoritativa dentro de um sistema."

Embora Hunt e Thomas tenham cunhado o termo, o conceito de evitar repetição em código já era uma prática valorizada anteriormente. O mérito deles foi articular e formalizar este conhecimento tácito que já circulava entre desenvolvedores experientes.

Por que é importante?

A importância do DRY reside em sua capacidade de reduzir significativamente a dívida técnica. Quando o mesmo código ou lógica é repetido em múltiplos lugares, qualquer alteração necessária deve ser implementada em todos esses locais. Inevitavelmente, alguns desses pontos serão esquecidos, resultando em inconsistências e bugs difíceis de rastrear.

Além disso, o DRY:

Reduz o tamanho do código, facilitando sua compreensão
Concentra a lógica em locais específicos, facilitando otimizações
Melhora a coesão do código, agrupando funcionalidades relacionadas
Minimiza a ocorrência de erros durante atualizações e manutenções

Exemplos Práticos em Java

Sem aplicar o princípio DRY:

@Service
public class ProdutoService {

    private final ProdutoRepository produtoRepository;

    public ProdutoService(ProdutoRepository produtoRepository) {
        this.produtoRepository = produtoRepository;        
    }

    public ProdutoResponseDTO buscarProdutoPorId(Long id) {
        Produto produto = produtoRepository.findById(id)
            .orElseThrow(() -> new RecursoNaoEncontradoException("Produto não encontrado"));

        ProdutoResponseDTO responseDTO = new ProdutoResponseDTO();
        responseDTO.setId(produto.getId());
        responseDTO.setNome(produto.getNome());
        responseDTO.setDescricao(produto.getDescricao());
        responseDTO.setPreco(produto.getPreco());
        responseDTO.setCategoria(produto.getCategoria());
        responseDTO.setDisponivel(produto.isDisponivel());
        return responseDTO;
    }

    public List<ProdutoResponseDTO> buscarTodosProdutos() {
        List<Produto> produtos = produtoRepository.findAll();

        List<ProdutoResponseDTO> responseDTOs = new ArrayList<>();
        for (Produto produto : produtos) {
            ProdutoResponseDTO responseDTO = new ProdutoResponseDTO();
            responseDTO.setId(produto.getId());
            responseDTO.setNome(produto.getNome());
            responseDTO.setDescricao(produto.getDescricao());
            responseDTO.setPreco(produto.getPreco());
            responseDTO.setCategoria(produto.getCategoria());
            responseDTO.setDisponivel(produto.isDisponivel());
            responseDTOs.add(responseDTO);
        }

        return responseDTOs;
    }

    public List<ProdutoResponseDTO> buscarProdutosPorCategoria(String categoria) {
        List<Produto> produtos = produtoRepository.findByCategoria(categoria);

        List<ProdutoResponseDTO> responseDTOs = new ArrayList<>();
        for (Produto produto : produtos) {
            ProdutoResponseDTO responseDTO = new ProdutoResponseDTO();
            responseDTO.setId(produto.getId());
            responseDTO.setNome(produto.getNome());
            responseDTO.setDescricao(produto.getDescricao());
            responseDTO.setPreco(produto.getPreco());
            responseDTO.setCategoria(produto.getCategoria());
            responseDTO.setDisponivel(produto.isDisponivel());
            responseDTOs.add(responseDTO);
        }

        return responseDTOs;
    }
}

Aplicando o princípio DRY:

@Service
public class ProdutoService {

    private final ProdutoRepository produtoRepository;

    public ProdutoService(ProdutoRepository produtoRepository) {
        this.produtoRepository = produtoRepository;        
    }

    public ProdutoResponseDTO buscarProdutoPorId(Long id) {
        Produto produto = produtoRepository.findById(id)
            .orElseThrow(() -> new RecursoNaoEncontradoException("Produto não encontrado"));

        return converterParaDTO(produto);
    }

    public List<ProdutoResponseDTO> buscarTodosProdutos() {
        List<Produto> produtos = produtoRepository.findAll();
        return produtos.stream()
                .map(this::converterParaDTO)
                .collect(Collectors.toList());
    }

    public List<ProdutoResponseDTO> buscarProdutosPorCategoria(String categoria) {
        List<Produto> produtos = produtoRepository.findByCategoria(categoria);
        return produtos.stream()
                .map(this::converterParaDTO)
                .collect(Collectors.toList());
    }

    private ProdutoResponseDTO converterParaDTO(Produto produto) {
        ProdutoResponseDTO responseDTO = new ProdutoResponseDTO();
        responseDTO.setId(produto.getId());
        responseDTO.setNome(produto.getNome());
        responseDTO.setDescricao(produto.getDescricao());
        responseDTO.setPreco(produto.getPreco());
        responseDTO.setCategoria(produto.getCategoria());
        responseDTO.setDisponivel(produto.isDisponivel());
        return responseDTO;
    }
}

Na versão DRY, extraímos a lógica de conversão da entidade para DTO em um método separado converterParaDTO(), que é reutilizado em todos os métodos que precisam dessa funcionalidade. Se a estrutura do DTO mudar ou se novos campos forem adicionados, precisamos alterar apenas esse método, não todos os lugares onde a conversão é feita.

Aplicando o princípio DRY com MapStruct:

Uma maneira ainda mais elegante de aplicar o princípio DRY para mapeamento entre objetos é utilizando a biblioteca MapStruct. Esta abordagem elimina completamente a necessidade de escrever código de mapeamento manual, reduzindo ainda mais a duplicação e o potencial para erros:

// 1. Definir a interface do mapper
@Mapper(componentModel = "spring")
public interface ProdutoMapper {

    ProdutoResponseDTO toDTO(Produto produto);

    List<ProdutoResponseDTO> toDTOList(List<Produto> produtos);
}

// 2. Refatorar o serviço para usar o mapper
@Service
public class ProdutoService {

    private final ProdutoRepository produtoRepository;
    private final ProdutoMapper produtoMapper;

    public ProdutoService(ProdutoRepository produtoRepository, ProdutoMapper produtoMapper) {
        this.produtoRepository = produtoRepository;
        this.produtoMapper = produtoMapper;
    }

    public ProdutoResponseDTO buscarProdutoPorId(Long id) {
        Produto produto = produtoRepository.findById(id)
            .orElseThrow(() -> new RecursoNaoEncontradoException("Produto não encontrado"));

        return produtoMapper.toDTO(produto);
    }

    public List<ProdutoResponseDTO> buscarTodosProdutos() {
        List<Produto> produtos = produtoRepository.findAll();
        return produtoMapper.toDTOList(produtos);
    }

    public List<ProdutoResponseDTO> buscarProdutosPorCategoria(String categoria) {
        List<Produto> produtos = produtoRepository.findByCategoria(categoria);
        return produtoMapper.toDTOList(produtos);
    }
}

O MapStruct gera automaticamente a implementação da interface ProdutoMapper durante o processo de compilação, eliminando toda a duplicação de código de mapeamento. Se a estrutura do DTO ou da entidade mudar, basta atualizar a interface do mapper e a implementação será regenerada automaticamente.

Esta abordagem oferece várias vantagens sobre o mapeamento manual:

Elimina completamente o código repetitivo: Não precisamos escrever nenhum código de mapeamento.
Alta performance: O código gerado pelo MapStruct é muito eficiente, similar ao que escreveríamos manualmente.
Menos propensão a erros: Se novos campos forem adicionados à entidade ou ao DTO, o compilador gerará avisos se o mapeamento não estiver completo.
Configurações avançadas: MapStruct oferece suporte a mapeamentos complexos, conversões personalizadas e herança.

Este é um exemplo perfeito da aplicação do princípio DRY levado ao seu máximo potencial, onde eliminamos não apenas a duplicação direta, mas também a necessidade de escrever código repetitivo em primeiro lugar.

DRY e o Padrão Factory

É importante destacar a relação sinérgica entre o princípio DRY e o padrão de design Factory. O padrão Factory é um dos padrões de criação mais utilizados na programação orientada a objetos e apresenta particular afinidade com o princípio DRY.

Quando aplicamos DRY para eliminar duplicação de código relacionado à criação de objetos complexos, frequentemente implementamos alguma variação do padrão Factory. Observe o exemplo com um cenário típico de API REST:

Sem Factory (violando DRY):

@RestController
@RequestMapping("/api/v1/pedidos")
public class PedidoController {

    private final PedidoService pedidoService;

    public PedidoController(PedidoService pedidoService) {
        this.pedidoService = pedidoService;        
    }

    @PostMapping
    public ResponseEntity<PedidoDTO> criarPedido(@RequestBody PedidoRequest request) {

        // Criação do cliente manualmente
        Cliente cliente = new Cliente();
        cliente.setId(request.getClienteId());
        cliente.setTipoCliente(TipoCliente.valueOf(request.getTipoCliente()));

        if (TipoCliente.PREMIUM.equals(cliente.getTipoCliente())) {
            cliente.setLimiteCredito(10000.0);
            cliente.setBeneficioFrete(true);
            cliente.setPrazoEntregaDias(2);
        } else if (TipoCliente.REGULAR.equals(cliente.getTipoCliente())) {
            cliente.setLimiteCredito(5000.0);
            cliente.setBeneficioFrete(false);
            cliente.setPrazoEntregaDias(5);
        } else { // NOVO
            cliente.setLimiteCredito(1000.0);
            cliente.setBeneficioFrete(false);
            cliente.setPrazoEntregaDias(7);
        }

        Pedido pedido = pedidoService.criarPedido(request, cliente);
        return ResponseEntity.ok(convertToDTO(pedido));
    }
}

@RestController
@RequestMapping("/api/v1/clientes")
public class ClienteController {

    private final ClienteService clienteService;

    public ClienteController (ClienteService clienteService) {
        this.clienteService = clienteService;        
    }

    @PostMapping
    public ResponseEntity<ClienteDTO> cadastrarCliente(@RequestBody ClienteRequest request) {

        // Criação do cliente manualmente (duplicação de código)
        Cliente cliente = new Cliente();
        cliente.setNome(request.getNome());
        cliente.setEmail(request.getEmail());
        cliente.setTipoCliente(TipoCliente.valueOf(request.getTipoCliente()));

        if (TipoCliente.PREMIUM.equals(cliente.getTipoCliente())) {
            cliente.setLimiteCredito(10000.0);
            cliente.setBeneficioFrete(true);
            cliente.setPrazoEntregaDias(2);
        } else if (TipoCliente.REGULAR.equals(cliente.getTipoCliente())) {
            cliente.setLimiteCredito(5000.0);
            cliente.setBeneficioFrete(false);
            cliente.setPrazoEntregaDias(5);
        } else { // NOVO
            cliente.setLimiteCredito(1000.0);
            cliente.setBeneficioFrete(false);
            cliente.setPrazoEntregaDias(7);
        }

        Cliente clienteSalvo = clienteService.salvarCliente(cliente);
        return ResponseEntity.ok(convertToDTO(clienteSalvo));
    }
}

Com Factory (aplicando DRY):

// Factory para criação de clientes
@Component
public class ClienteFactory {

    public Cliente criarCliente(Long id, String tipoClienteStr) {
        Cliente cliente = new Cliente();
        cliente.setId(id);

        TipoCliente tipoCliente = TipoCliente.valueOf(tipoClienteStr);
        cliente.setTipoCliente(tipoCliente);

        // Configuração baseada no tipo de cliente
  /*       
   * Estou utilizando neste exemplo o switch case do Java 21,
   * que introduz a sintaxe moderna com "->", mais legível e concisa.
 */
        switch (tipoCliente) {
            case PREMIUM -> configurarClientePremium(cliente);
            case REGULAR -> configurarClienteRegular(cliente);
            case NOVO    -> configurarClienteNovo(cliente);
       }

      return cliente;
    }

    public Cliente criarCliente(ClienteRequest request) {
        Cliente cliente = new Cliente();
        cliente.setNome(request.getNome());
        cliente.setEmail(request.getEmail());

        TipoCliente tipoCliente = TipoCliente.valueOf(request.getTipoCliente());
        cliente.setTipoCliente(tipoCliente);

        // Configuração baseada no tipo de cliente
        switch (tipoCliente) {
            case PREMIUM -> configurarClientePremium(cliente);
            case REGULAR -> configurarClienteRegular(cliente);
            case NOVO    -> configurarClienteNovo(cliente);
        }

        return cliente;
    }

    private void configurarClientePremium(Cliente cliente) {
        cliente.setLimiteCredito(10000.0);
        cliente.setBeneficioFrete(true);
        cliente.setPrazoEntregaDias(2);
    }

    private void configurarClienteRegular(Cliente cliente) {
        cliente.setLimiteCredito(5000.0);
        cliente.setBeneficioFrete(false);
        cliente.setPrazoEntregaDias(5);
    }

    private void configurarClienteNovo(Cliente cliente) {
        cliente.setLimiteCredito(1000.0);
        cliente.setBeneficioFrete(false);
        cliente.setPrazoEntregaDias(7);
    }
}

// Usando a Factory nos controllers
@RestController
@RequestMapping("/api/v1/pedidos")
public class PedidoController {

    private final PedidoService pedidoService;   
    private final ClienteFactory clienteFactory;

    public PedidoController(PedidoService pedidoService, 
                            ClienteFactory clienteFactory) {
        this.pedidoService = pedidoService;
        this.clienteFactory = clienteFactory;
    }

    @PostMapping
    public ResponseEntity<PedidoDTO> criarPedido(@RequestBody PedidoRequest request) {


        // Criação do cliente através da factory
        Cliente cliente = clienteFactory.criarCliente(
            request.getClienteId(), 
            request.getTipoCliente()
        );

        Pedido pedido = pedidoService.criarPedido(request, cliente);
        return ResponseEntity.ok(convertToDTO(pedido));
    }
}

@RestController
@RequestMapping("/api/v1/clientes")
public class ClienteController {

    private final ClienteService clienteService;    
    private final ClienteFactory clienteFactory;

    public ClienteController (ClienteService  clienteService, 
                              ClienteFactory clienteFactory) {
        this.clienteService = clienteService;
        this.clienteFactory = clienteFactory;
    }

    @PostMapping
    public ResponseEntity<ClienteDTO> cadastrarCliente(@RequestBody ClienteRequest request) {


        // Criação do cliente através da factory
        Cliente cliente = clienteFactory.criarCliente(request);

        Cliente clienteSalvo = clienteService.salvarCliente(cliente);
        return ResponseEntity.ok(convertToDTO(clienteSalvo));
    }
}

Este padrão não apenas elimina a duplicação, mas também centraliza a lógica de criação e configuração de clientes, facilitando futuras modificações e manutenção. Se as regras de negócio para um tipo específico de cliente mudarem, apenas os métodos relevantes na factory precisarão ser atualizados, em vez de buscar e alterar essa lógica em múltiplos controllers e serviços.

KISS - Keep It Simple, Stupid (Mantenha Simples, Estúpido)

Origem e História

O princípio KISS tem uma origem interessante no campo da engenharia aeroespacial. Foi atribuído a Kelly Johnson, engenheiro da Lockheed Skunk Works, responsável pelo design de aeronaves como o U-2 e o SR-71 Blackbird durante as décadas de 1960 e 1970. Johnson instruía seus engenheiros que seus sistemas deveriam ser simples o suficiente para serem reparados por um mecânico comum em condições de campo com ferramentas básicas.

O acrônimo "Keep It Simple, Stupid" foi posteriormente adotado pela Marinha dos EUA em 1960. O conceito rapidamente transcendeu o contexto militar e encontrou aplicação em diversas áreas, incluindo o desenvolvimento de software.

Por que é importante?

A importância do KISS no desenvolvimento de software é multifacetada:

Manutenibilidade: Código simples é mais fácil de entender e modificar.
Depuração: Soluções simples apresentam menor superfície para bugs potenciais.
Integração de novos desenvolvedores: Profissionais recém-chegados ao projeto conseguem compreender e contribuir para o código mais rapidamente.
Desempenho: Soluções simples frequentemente apresentam melhor desempenho que alternativas complexas.
Adaptabilidade: Sistemas simples geralmente respondem melhor a novos requisitos.

Exemplos Práticos em Java

Sem aplicar o princípio KISS:

@Service
public class ValidadorEmailService {    

    private final UsuarioRepository usuarioRepository;    
    private final EmailBlacklistRepository blacklistRepository;    
    private final ConfiguracoesService configuracoesService;

    public ValidadorEmailService(
            UsuarioRepository usuarioRepository,
            EmailBlacklistRepository blacklistRepository,
            ConfiguracoesService configuracoesService) {
        this.usuarioRepository = usuarioRepository;
        this.blacklistRepository = blacklistRepository;
        this.configuracoesService = configuracoesService;
    }

    public ValidationResult validarEmail(String email) {
        ValidationResult result = new ValidationResult();

        // Verificação 1: Email não pode ser nulo ou vazio
        if (email == null || email.trim().isEmpty()) {
            result.addError("EMAIL_EMPTY", "Email não pode ser vazio");
            return result;
        }

        // Verificação 2: Formato básico do email
        if (!email.contains("@")) {
            result.addError("EMAIL_INVALID_FORMAT", "Email deve conter @");
            return result;
        }

        // Verificação 3: Validação estrutural detalhada
        String[] partes = email.split("@");
        if (partes.length != 2) {
            result.addError("EMAIL_INVALID_STRUCTURE", "Email deve ter exatamente uma parte local e uma parte de domínio");
            return result;
        }

        String localPart = partes[0];
        String domainPart = partes[1];

        if (localPart.isEmpty()) {
            result.addError("EMAIL_LOCAL_PART_EMPTY", "Parte local do email não pode ser vazia");
            return result;
        }

        if (domainPart.isEmpty()) {
            result.addError("EMAIL_DOMAIN_EMPTY", "Domínio do email não pode ser vazio");
            return result;
        }

        if (!domainPart.contains(".")) {
            result.addError("EMAIL_INVALID_DOMAIN", "Domínio deve ter pelo menos um ponto");
            return result;
        }

        String[] domainParts = domainPart.split("\\.");
        for (String part : domainParts) {
            if (part.isEmpty()) {
                result.addError("EMAIL_INVALID_DOMAIN_PART", "Partes do domínio não podem ser vazias");
                return result;
            }
        }

        // Verificação 4: Verificação de caracteres permitidos
        String allowedCharsLocal = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.-_+";
        for (char c : localPart.toCharArray()) {
            if (allowedCharsLocal.indexOf(c) < 0) {
                result.addError("EMAIL_INVALID_CHAR_LOCAL", "Caractere não permitido na parte local: " + c);
                return result;
            }
        }

        String allowedCharsDomain = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.-";
        for (char c : domainPart.toCharArray()) {
            if (allowedCharsDomain.indexOf(c) < 0) {
                result.addError("EMAIL_INVALID_CHAR_DOMAIN", "Caractere não permitido no domínio: " + c);
                return result;
            }
        }

        // Verificação 5: Regras de negócio específicas
        if (blacklistRepository.isEmailDomainBlacklisted(domainPart)) {
            result.addError("EMAIL_DOMAIN_BLACKLISTED", "Domínio não permitido");
            return result;
        }

        if (usuarioRepository.existsByEmail(email) && configuracoesService.isEmailUniqueRequired()) {
            result.addError("EMAIL_ALREADY_EXISTS", "Email já cadastrado");
            return result;
        }

        // Se chegou até aqui, o email é válido
        result.setValid(true);
        return result;
    }
}

Aplicando o princípio KISS:

@Service
public class ValidadorEmailService {

    private final UsuarioRepository usuarioRepository;
    private final EmailBlacklistRepository blacklistRepository;   
    private final ConfiguracoesService configuracoesService;

    public ValidadorEmailService(UsuarioRepository usuarioRepository,
            EmailBlacklistRepository blacklistRepository,
            ConfiguracoesService configuracoesService) {
        this.usuarioRepository = usuarioRepository;
        this.blacklistRepository = blacklistRepository;
        this.configuracoesService = configuracoesService;
    }

    // Expressão regular para validação de email seguindo RFC 5322
    private static final Pattern EMAIL_PATTERN = 
        Pattern.compile("^[a-zA-Z0-9_+&*-]+(?:\\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,7}$");

    public ValidationResult validarEmail(String email) {
        ValidationResult result = new ValidationResult();

        // Verificação 1: Email não pode ser nulo ou vazio
        if (email == null || email.trim().isEmpty()) {
            result.addError("EMAIL_EMPTY", "Email não pode ser vazio");
            return result;
        }

        // Verificação 2: Formato do email usando regex
        if (!EMAIL_PATTERN.matcher(email).matches()) {
            result.addError("EMAIL_INVALID_FORMAT", "Formato de email inválido");
            return result;
        }

        // Verificação 3: Regras de negócio específicas
        String dominio = email.substring(email.lastIndexOf('@') + 1);

        if (blacklistRepository.isEmailDomainBlacklisted(dominio)) {
            result.addError("EMAIL_DOMAIN_BLACKLISTED", "Domínio não permitido");
            return result;
        }

        if (usuarioRepository.existsByEmail(email) && configuracoesService.isEmailUniqueRequired()) {
            result.addError("EMAIL_ALREADY_EXISTS", "Email já cadastrado");
            return result;
        }

        // Se chegou até aqui, o email é válido
        result.setValid(true);
        return result;
    }
}

Na versão KISS, utilizamos uma expressão regular padronizada para validar o formato do email, em vez de implementar manualmente todas as verificações estruturais. Isso torna o código significativamente mais curto, mais legível e menos propenso a erros, enquanto mantém todas as regras de negócio necessárias.

Aplicando o princípio KISS com expressão regular e Apache Commons Lang3:

import org.apache.commons.lang3.StringUtils;

@Service
public class ValidadorEmailService {

    private static final Pattern EMAIL_PATTERN = 
        Pattern.compile("^[a-zA-Z0-9_+&*-]+(?:\\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,7}$");

    public ValidationResult validarEmail(String email) {
        ValidationResult result = new ValidationResult();

        // Utilização do StringUtils.isBlank() da Apache Commons Lang3
        if (StringUtils.isBlank(email)) {
            result.addError("EMAIL_EMPTY", "Email não pode ser vazio");
            return result;
        }

        // Validação de formato com regex
        if (!EMAIL_PATTERN.matcher(email).matches()) {
            result.addError("EMAIL_INVALID_FORMAT", "Formato de email inválido");
            return result;
        }

        // Demais regras de negócio...

        result.setValid(true);
        return result;
    }
}

Por que isso é KISS?

Ao usar o método StringUtils.isBlank() da biblioteca Apache Commons Lang3, encapsulamos a verificação de null, string vazia e espaços em branco em uma única chamada clara e descritiva. Isso reduz ruído, melhora a legibilidade e evita erros comuns em validações manuais.

Essa abordagem exemplifica bem o princípio KISS — evitar reinventar a roda e utilizar ferramentas confiáveis para manter o código simples, expressivo e eficiente.

YAGNI - You Aren't Gonna Need It (Você Não Vai Precisar Disso)

Origem e História

O princípio YAGNI surgiu no contexto do Extreme Programming (XP), uma metodologia ágil de desenvolvimento de software formulada por Kent Beck no final dos anos 1990. O conceito central propõe que os desenvolvedores não devem adicionar funcionalidades até que sejam realmente necessárias, não apenas porque potencialmente poderiam ser úteis no futuro.

YAGNI é um princípio contra-intuitivo para muitos desenvolvedores, pois contraria o instinto natural de planejar com antecedência e tentar antecipar necessidades futuras. No entanto, a experiência coletiva da indústria demonstrou que a maioria das funcionalidades projetadas para uso futuro nunca são efetivamente necessárias, ou são implementadas de forma diferente quando a necessidade real emerge.

Por que é importante?

A importância do YAGNI pode ser compreendida através de seus benefícios diretos:

Foco em valor imediato: Direciona os recursos para resolver problemas reais e atuais.
Redução de complexidade: Cada funcionalidade adicional aumenta a complexidade do sistema.
Economia de recursos: Tempo e energia são conservados ao evitar desenvolvimento desnecessário.
Design mais claro: Sistemas projetados para resolver problemas reais tendem a apresentar designs mais coerentes.
Adaptabilidade: É mais fácil adaptar um sistema simples a novos requisitos do que retrabalhar um sistema complexo.

Exemplos Práticos em Java

Sem aplicar o princípio YAGNI:

@Entity
@Table(name = "usuarios")
public class Usuario {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String nome;

    @Column(nullable = false, unique = true)
    private String email;

    @Column(nullable = false)
    private String senha;

    // Campos necessários atualmente
    private boolean ativo;
    private LocalDateTime dataCriacao;
    private LocalDateTime ultimoLogin;

    // Campos para funcionalidades futuras que "talvez" sejam necessárias
    private String telefone;
    private String endereco;
    private String complemento;
    private String cidade;
    private String estado;
    private String cep;
    private LocalDate dataNascimento;
    private String genero;
    private String fotoPerfil;
    private String biografia;
    private String tokenResetSenha;
    private LocalDateTime dataExpiracaoToken;
    private boolean contaVerificada;
    private String tokenVerificacao;
    private Integer tentativasLogin;
    private boolean bloqueado;
    private LocalDateTime dataBloqueio;
    private String preferenciasNotificacao;
    private String configuracaoPrivacidade;
    private String tipoUsuario;
    private Float avaliacao;
    private Integer numeroAvaliacoes;

    // Relações que "podem ser úteis" no futuro
    @OneToMany(mappedBy = "usuario")
    private List<Pedido> pedidos;

    @OneToMany(mappedBy = "usuario")
    private List<Endereco> enderecos;

    @ManyToMany
    @JoinTable(
        name = "usuarios_interesses",
        joinColumns = @JoinColumn(name = "usuario_id"),
        inverseJoinColumns = @JoinColumn(name = "interesse_id")
    )
    private Set<Interesse> interesses;

    @ManyToMany
    @JoinTable(
        name = "usuarios_roles",
        joinColumns = @JoinColumn(name = "usuario_id"),
        inverseJoinColumns = @JoinColumn(name = "role_id")
    )
    private Set<Role> roles;

    // Getters e setters para TODOS os campos...
    // (métodos omitidos para brevidade)
}

@RestController
@RequestMapping("/api/v1/usuarios")
public class UsuarioController {

    private final UsuarioService usuarioService;

    public UsuarioController(UsuarioService usuarioService) {
        this.usuarioService = usuarioService;
    }

    @GetMapping("/{id}")
    public ResponseEntity<UsuarioDTO> buscarUsuario(@PathVariable Long id) {
        Usuario usuario = usuarioService.buscarPorId(id);
        UsuarioDTO dto = converterParaDTO(usuario);
        return ResponseEntity.ok(dto);
    }

    private UsuarioDTO converterParaDTO(Usuario usuario) {
        // Conversão com todos os campos possíveis
        UsuarioDTO dto = new UsuarioDTO();
        dto.setId(usuario.getId());
        dto.setNome(usuario.getNome());
        dto.setEmail(usuario.getEmail());
        dto.setAtivo(usuario.isAtivo());
        dto.setDataCriacao(usuario.getDataCriacao());
        dto.setUltimoLogin(usuario.getUltimoLogin());

        // Campos para funcionalidades futuras
        dto.setTelefone(usuario.getTelefone());
        dto.setEndereco(usuario.getEndereco());
        dto.setComplemento(usuario.getComplemento());
        dto.setCidade(usuario.getCidade());
        dto.setEstado(usuario.getEstado());
        dto.setCep(usuario.getCep());
        dto.setDataNascimento(usuario.getDataNascimento());
        dto.setGenero(usuario.getGenero());
        dto.setFotoPerfil(usuario.getFotoPerfil());
        dto.setBiografia(usuario.getBiografia());
        dto.setContaVerificada(usuario.isContaVerificada());
        dto.setBloqueado(usuario.isBloqueado());
        dto.setTipoUsuario(usuario.getTipoUsuario());
        dto.setAvaliacao(usuario.getAvaliacao());
        dto.setNumeroAvaliacoes(usuario.getNumeroAvaliacoes());

        // Relações
        if (usuario.getPedidos() != null) {
            dto.setPedidos(usuario.getPedidos().stream()
                .map(this::converterPedidoParaDTO)
                .collect(Collectors.toList()));
        }

        if (usuario.getEnderecos() != null) {
            dto.setEnderecos(usuario.getEnderecos().stream()
                .map(this::converterEnderecoParaDTO)
                .collect(Collectors.toList()));
        }

        return dto;
    }


}

Aplicando o princípio YAGNI:

@Entity
@Table(name = "usuarios")
public class Usuario {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String nome;

    @Column(nullable = false, unique = true)
    private String email;

    @Column(nullable = false)
    private String senha;

    // Apenas campos necessários para os requisitos atuais
    private boolean ativo;
    private LocalDateTime dataCriacao;
    private LocalDateTime ultimoLogin;

    // Getters e setters apenas para os campos existentes
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getNome() {
        return nome;
    }

    public void setNome(String nome) {
        this.nome = nome;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getSenha() {
        return senha;
    }

    public void setSenha(String senha) {
        this.senha = senha;
    }

    public boolean isAtivo() {
        return ativo;
    }

    public void setAtivo(boolean ativo) {
        this.ativo = ativo;
    }

    public LocalDateTime getDataCriacao() {
        return dataCriacao;
    }

    public void setDataCriacao(LocalDateTime dataCriacao) {
        this.dataCriacao = dataCriacao;
    }

    public LocalDateTime getUltimoLogin() {
        return ultimoLogin;
    }

    public void setUltimoLogin(LocalDateTime ultimoLogin) {
        this.ultimoLogin = ultimoLogin;
    }
}

@RestController
@RequestMapping("/api/v1/usuarios")
public class UsuarioController {

    private final UsuarioService usuarioService;

    public UsuarioController(UsuarioService usuarioService) {
        this.usuarioService = usuarioService;
    }

    @GetMapping("/{id}")
    public ResponseEntity<UsuarioDTO> buscarUsuario(@PathVariable Long id) {
        Usuario usuario = usuarioService.buscarPorId(id);
        UsuarioDTO dto = converterParaDTO(usuario);
        return ResponseEntity.ok(dto);
    }

    private UsuarioDTO converterParaDTO(Usuario usuario) {
        // Apenas os campos necessários atualmente
        UsuarioDTO dto = new UsuarioDTO();
        dto.setId(usuario.getId());
        dto.setNome(usuario.getNome());
        dto.setEmail(usuario.getEmail());
        dto.setAtivo(usuario.isAtivo());
        dto.setDataCriacao(usuario.getDataCriacao());
        dto.setUltimoLogin(usuario.getUltimoLogin());
        return dto;
    }

    // Apenas os métodos CRUD necessários...
}

Na versão YAGNI, a entidade Usuario e seu respectivo DTO contêm apenas os campos necessários para os requisitos atuais do sistema. Campos adicionais, relacionamentos e métodos que poderiam ser úteis no futuro foram eliminados. Isso resulta em um código mais limpo, mais fácil de entender e manter. Se futuramente houver necessidade de adicionar novos campos ou relacionamentos, eles podem ser incluídos quando a necessidade real surgir, evitando a complexidade desnecessária e o esforço de manutenção de código que pode nunca ser utilizado.

TDA - Tell, Don't Ask (Diga, Não Pergunte)

Origem e História

O princípio "Tell, Don't Ask" foi popularizado por Andy Hunt e Dave Thomas (os mesmos autores de "The Pragmatic Programmer" que formalizaram o DRY). O conceito fundamental estabelece que objetos devem ser responsáveis por seu próprio comportamento, e o código cliente deve "dizer" a um objeto o que fazer, em vez de "perguntar" sobre seu estado interno e tomar decisões baseadas nessa informação.

Este princípio é fundamentalmente relacionado à programação orientada a objetos e enfatiza o encapsulamento - o princípio de que os detalhes internos de um objeto devem ser ocultos do mundo exterior.

Por que é importante?

A importância do TDA manifesta-se em vários aspectos:

Encapsulamento: Mantém a lógica relacionada a dados específicos junto com esses dados.
Coesão: Resulta em classes mais coesas onde comportamentos relacionados estão agrupados.
Desacoplamento: Reduz o acoplamento entre componentes do sistema.
Manutenibilidade: Mudanças em regras de negócio afetam apenas as classes responsáveis por essas regras.
Testabilidade: Classes que seguem TDA são geralmente mais fáceis de testar isoladamente.

Exemplos Práticos em Java

Sem aplicar o princípio TDA:

@Service
public class PedidoService {

    private final PedidoRepository pedidoRepository;        
    private final ClienteRepository clienteRepository;    
    private final ProdutoRepository produtoRepository;    
    private final EmailService emailService;

    public PedidoService(PedidoRepository pedidoRepository, 
                        ClienteRepository clienteRepository,
                        ProdutoRepository produtoRepository,
                        EmailService emailService) {
        this.pedidoRepository = pedidoRepository;
        this.clienteRepository = clienteRepository;
        this.produtoRepository = produtoRepository;
        this.emailService = emailService;
    }

    public void processarPagamento(Long pedidoId, String formaPagamento) {
        Pedido pedido = pedidoRepository.findById(pedidoId)
            .orElseThrow(() -> new RecursoNaoEncontradoException("Pedido não encontrado"));

        Cliente cliente = pedido.getCliente();

        // Valida disponibilidade dos produtos
        for (ItemPedido item : pedido.getItens()) {
            Produto produto = item.getProduto();

            // Verifica se tem estoque suficiente
            if (produto.getEstoqueDisponivel() < item.getQuantidade()) {
                throw new NegocioException("Produto " + produto.getNome() + " sem estoque suficiente");
            }
        }

        // Verifica limite do cliente para pagamento por crédito
        if ("CREDITO".equals(formaPagamento)) {
            BigDecimal limiteDisponivel = cliente.getLimiteCredito().subtract(cliente.getSaldoUtilizado());

            if (pedido.getValorTotal().compareTo(limiteDisponivel) > 0) {
                throw new NegocioException("Cliente não possui limite de crédito suficiente");
            }

            // Atualiza saldo utilizado do cliente
            cliente.setSaldoUtilizado(cliente.getSaldoUtilizado().add(pedido.getValorTotal()));
            clienteRepository.save(cliente);
        }

        // Atualiza status do pedido e processa pagamento
        pedido.setStatus(StatusPedido.PAGO);
        pedido.setFormaPagamento(formaPagamento);
        pedido.setDataPagamento(LocalDateTime.now());

        // Reduz estoque dos produtos
        for (ItemPedido item : pedido.getItens()) {
            Produto produto = item.getProduto();
            produto.setEstoqueDisponivel(produto.getEstoqueDisponivel() - item.getQuantidade());
            produtoRepository.save(produto);
        }

        pedidoRepository.save(pedido);

        // Envia email de confirmação
// Utilizando Text Block (Java 15+) para melhor legibilidade da mensagem
String mensagem = """
    Seu pedido #%d no valor de R$ %.2f foi confirmado com sucesso.
    """.formatted(pedido.getId(), pedido.getValorTotal());

emailService.enviarEmail(cliente.getEmail(), "Confirmação de Pagamento", mensagem);

    }
}

Aplicando o princípio TDA:

@Service
public class PedidoService {

    private final PedidoRepository pedidoRepository;    
    private final EmailService emailService;

    public PedidoService(PedidoRepository pedidoRepository,
                         EmailService emailService){
    this.pedidoRepository = pedidoRepository;
    this.emailService = emailService;
    }

    public void processarPagamento(Long pedidoId, String formaPagamento) {
        Pedido pedido = pedidoRepository.findById(pedidoId)
            .orElseThrow(() -> new RecursoNaoEncontradoException("Pedido não encontrado"));

        // Validar disponibilidade de produtos
        pedido.validarDisponibilidadeProdutos();

        // Processar pagamento
        boolean pagamentoRealizado = pedido.processarPagamento(formaPagamento);

        if (!pagamentoRealizado) {
            throw new NegocioException("Falha ao processar pagamento");
        }

        pedidoRepository.save(pedido);

        // Enviar confirmação ao cliente
        pedido.enviarConfirmacao(emailService);
    }
}

@Entity
public class Pedido {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne
    private Cliente cliente;

    @OneToMany(cascade = CascadeType.ALL, mappedBy = "pedido")
    private List<ItemPedido> itens;

    @Enumerated(EnumType.STRING)
    private StatusPedido status;

    private String formaPagamento;
    private LocalDateTime dataPagamento;
    private BigDecimal valorTotal;

    // Outros campos e getters/setters

    public void validarDisponibilidadeProdutos() {
        for (ItemPedido item : itens) {
            if (!item.validarDisponibilidade()) {
                throw new NegocioException("Produto " + item.getProduto().getNome() + " sem estoque suficiente");
            }
        }
    }

    public boolean processarPagamento(String formaPagamento) {
        // Validar pagamento com base na forma escolhida
        if ("CREDITO".equals(formaPagamento)) {
            boolean temLimite = cliente.validarLimiteCredito(valorTotal);
            if (!temLimite) {
                return false;
            }
            cliente.utilizarCredito(valorTotal);
        }

        // Atualizar status e data
        this.status = StatusPedido.PAGO;
        this.formaPagamento = formaPagamento;
        this.dataPagamento = LocalDateTime.now();

        // Atualizar estoque
        itens.forEach(ItemPedido::atualizarEstoque);

        return true;
    }

    public void enviarConfirmacao(EmailService emailService) {
    // Utilizando Text Block (Java 15+) para melhor legibilidade da mensagem
    String mensagem = """
        Seu pedido #%d no valor de R$ %.2f foi confirmado com sucesso.
        """.formatted(id, valorTotal);

    emailService.enviarEmail(cliente.getEmail(), "Confirmação de Pagamento", mensagem);
}

    }
}

@Entity
public class Cliente {
    // Campos e outros métodos

    private BigDecimal limiteCredito;
    private BigDecimal saldoUtilizado;

    public boolean validarLimiteCredito(BigDecimal valorCompra) {
        BigDecimal limiteDisponivel = limiteCredito.subtract(saldoUtilizado);
        return valorCompra.compareTo(limiteDisponivel) <= 0;
    }

    public void utilizarCredito(BigDecimal valor) {
        this.saldoUtilizado = saldoUtilizado.add(valor);
    }
}

@Entity
public class ItemPedido {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne
    private Pedido pedido;

    @ManyToOne
    private Produto produto;

    private Integer quantidade;
    private BigDecimal valorUnitario;

    // Getters e setters

    public boolean validarDisponibilidade() {
        return produto.getEstoqueDisponivel() >= quantidade;
    }

    public void atualizarEstoque() {
        produto.reduzirEstoque(quantidade);
    }
}

@Entity
public class Produto {
    // Campos e getters/setters

    private Integer estoqueDisponivel;

    public void reduzirEstoque(int quantidade) {
        if (estoqueDisponivel < quantidade) {
            throw new NegocioException("Estoque insuficiente");
        }
        this.estoqueDisponivel -= quantidade;
    }
}

Na versão que aplica o princípio TDA, cada entidade é responsável por seu próprio comportamento. O PedidoService não pergunta mais sobre o estado interno dos objetos para tomar decisões; em vez disso, delega comportamentos aos objetos apropriados. Por exemplo:

O Pedido é responsável por validar a disponibilidade de seus itens.
O Cliente é responsável por validar seu próprio limite de crédito.
Cada ItemPedido sabe como validar sua disponibilidade e atualizar o estoque.
O Produto é responsável por gerenciar seu próprio estoque.

Este design encapsula melhor o comportamento dentro dos objetos relevantes, tornando o código mais modular, mais fácil de manter e estender. Além disso, facilita a adição de novas regras de negócio relacionadas a cada entidade sem precisar modificar o serviço principal.

TDA e a Lei de Demeter

É relevante observar que o princípio Tell, Don't Ask (TDA) frequentemente opera em conjunto com a Lei de Demeter (LoD), também conhecida como "princípio do menor conhecimento". A Lei de Demeter estabelece que um objeto só deve invocar métodos que pertençam a:

O próprio objeto
Objetos recebidos como parâmetros para o método
Objetos criados diretamente pelo método
Propriedades/campos diretos do objeto

No exemplo do TDA previamente discutido, quando transformamos o código, estamos também aderindo à Lei de Demeter. Vamos analisar um exemplo mais específico:

Código violando a Lei de Demeter:

@Service
public class RelatorioVendasService {

    private final VendaRepository vendaRepository;

    public RelatorioVendasService(VendaRepository vendaRepository) {
        this.vendaRepository = vendaRepository;
    }

    public RelatorioMensal gerarRelatorioMensal(Long lojaId, int mes, int ano) {
        List<Venda> vendas = vendaRepository.findByLojaIdAndPeriodo(lojaId, mes, ano);

        RelatorioMensal relatorio = new RelatorioMensal(lojaId, mes, ano);

        for (Venda venda : vendas) {
            // Viola Lei de Demeter: navega pela cadeia de objetos
            String nomeProduto = venda.getItens().get(0).getProduto().getNome();
            String categoriasProduto = venda.getItens().get(0).getProduto().getCategoria().getNome();
            String nomeVendedor = venda.getVendedor().getDepartamento().getGerente().getNome();

            // Mais código usando estas informações...
        }

        return relatorio;
    }
}

Código aderente à Lei de Demeter e ao TDA:

@Service
public class RelatorioVendasService {

    private final VendaRepository vendaRepository;

    public RelatorioVendasService(VendaRepository vendaRepository) {
        this.vendaRepository = vendaRepository;
    }

    public RelatorioMensal gerarRelatorioMensal(Long lojaId, int mes, int ano) {
        List<Venda> vendas = vendaRepository.findByLojaIdAndPeriodo(lojaId, mes, ano);

        RelatorioMensal relatorio = new RelatorioMensal(lojaId, mes, ano);

        // Delegamos a responsabilidade para a entidade Venda
        for (Venda venda : vendas) {
            relatorio.adicionarVenda(venda);
        }

        return relatorio;
    }
}

@Entity
public class Venda {
    // atributos e outros métodos

    public void adicionarAoRelatorio(RelatorioMensal relatorio) {
        // A Venda conhece sua própria estrutura e sabe como
        // extrair informações relevantes
        relatorio.adicionarValorVenda(this.valor);
        relatorio.registrarFormaPagamento(this.formaPagamento);

        for (ItemVenda item : this.itens) {
            item.adicionarAoRelatorio(relatorio);
        }

        this.vendedor.adicionarEstatisticasAoRelatorio(relatorio);
    }
}

public class ItemVenda {
    // atributos e outros métodos

    public void adicionarAoRelatorio(RelatorioMensal relatorio) {
        relatorio.adicionarItem(
            this.quantidade, 
            this.valorUnitario, 
            this.produto.obterInformacaoResumida()
        );
    }
}

public class Vendedor {
    // atributos e outros métodos

    public void adicionarEstatisticasAoRelatorio(RelatorioMensal relatorio) {
        relatorio.registrarVendedor(this.id, this.nome);
        relatorio.adicionarComissao(this.calcularComissao());

        // O Vendedor sabe como obter informações do departamento sem expor
        // a estrutura interna do departamento
        relatorio.registrarDepartamento(this.obterInformacaoDepartamento());
    }

    public String obterInformacaoDepartamento() {
        // Encapsula acesso à cadeia de objetos
        return this.departamento.obterInformacaoCompleta();
    }
}

No exemplo aderente à Lei de Demeter, cada objeto é responsável pelo seu próprio comportamento e por conhecer sua estrutura interna. O serviço não precisa navegar por cadeias de objetos, pois cada entidade sabe como extrair e fornecer suas próprias informações, seguindo o princípio "Tell, Don't Ask".

A Lei de Demeter é frequentemente resumida como "só fale com seus amigos imediatos, não com os amigos dos seus amigos". Essa abordagem reduz o acoplamento entre componentes, facilita a manutenção e promove um melhor encapsulamento, complementando perfeitamente o princípio TDA.

Críticas e Limitações dos Princípios

Apesar de seus evidentes benefícios, é importante reconhecer que cada um destes princípios tem suas limitações e críticas relevantes. Aplicá-los sem considerar o contexto específico pode resultar em problemas.

Críticas ao DRY

Acoplamento indesejado: A busca pela eliminação de toda duplicação pode criar acoplamento entre componentes que deveriam ser independentes. Quando partes do sistema que evoluem por razões diferentes compartilham código, mudanças em uma parte podem afetar outras desnecessariamente.
Abstração prematura: Para eliminar duplicação, frequentemente criamos abstrações que são difíceis de entender e podem ser mais complexas que a duplicação original. Isso levou ao princípio alternativo WET (Write Everything Twice ou "Escreva Tudo Duas Vezes"), sugerindo que alguma duplicação controlada pode ser preferível a abstrações inadequadas.
Repetição acidental vs. essencial: Nem toda semelhança no código representa uma verdadeira duplicação conceitual. Por vezes, partes do código parecem similares mas têm propósitos distintos e podem evoluir em direções diferentes.

Críticas ao KISS

Subjetividade da simplicidade: O que é "simples" para um desenvolvedor pode ser complexo para outro. Essa subjetividade dificulta a aplicação consistente do princípio.
Simplificação excessiva: Em sistemas intrinsecamente complexos, soluções excessivamente simplificadas podem não abordar adequadamente a complexidade inerente do domínio.
Compromisso com desempenho: Soluções mais simples podem não oferecer o desempenho ideal. Em sistemas com requisitos rigorosos de performance, o KISS pode conduzir a soluções subótimas.

Críticas ao YAGNI

Dívida técnica estrutural: Seguir YAGNI estritamente pode resultar em arquiteturas difíceis de adaptar posteriormente. Algumas decisões arquiteturais fundamentais são difíceis de modificar uma vez que o sistema está em produção.
Custo de retrabalho: Se uma funcionalidade inicialmente adiada realmente se torna necessária, o custo de implementá-la posteriormente pode ser significativamente maior do que teria sido se incorporada desde o início.
Conhecimento do domínio: Em domínios bem estabelecidos, desenvolvedores experientes podem prever com razoável precisão quais funcionalidades serão necessárias, tornando o YAGNI menos relevante.

Críticas ao TDA

Classes sobrecarregadas: Uma aplicação estrita do TDA pode resultar em classes com múltiplas responsabilidades, violando o Princípio de Responsabilidade Única (SRP).
Incompatibilidade com paradigmas funcionais: Em programação funcional ou em designs orientados a dados, o TDA pode ser inadequado ou simplesmente não aplicável.
Desafios com aspectos transversais: Funcionalidades como logging, segurança ou auditoria frequentemente necessitam "perguntar" sobre o estado interno dos objetos para funcionar adequadamente.

Como observado pelo arquiteto de software Sebastian Malaca, "princípios são genéricos e livres de contexto, mas soluções reais são baseadas em contexto, então ajuste os princípios ao contexto, não o contrário". Esta é uma perspectiva valiosa para considerar durante a aplicação destes princípios.

Integrando os Princípios em seu Desenvolvimento

Estes quatro princípios (DRY, KISS, YAGNI e TDA) não existem isoladamente - eles se complementam e, quando aplicados com discernimento, criam uma abordagem holística para o desenvolvimento de software de qualidade.

Como os princípios se relacionam?

DRY + KISS: A eliminação de duplicação (DRY) frequentemente resulta em soluções mais simples (KISS).
KISS + YAGNI: Manter a simplicidade (KISS) muitas vezes envolve evitar adicionar funcionalidades desnecessárias (YAGNI).
YAGNI + TDA: Concentrar-se apenas no necessário no momento (YAGNI) conduz a um design onde objetos têm responsabilidades claras e bem definidas (TDA).
TDA + DRY: Quando objetos são responsáveis por seu próprio comportamento (TDA), torna-se mais fácil evitar duplicação de lógica (DRY).

Implementando na Prática

Comece com KISS: Ao iniciar qualquer componente, busque a solução mais simples e direta possível.
Aplique YAGNI: Questione cada funcionalidade proposta: "É necessária agora?". Se a resposta for negativa, postergue sua implementação.
Refatore para DRY: À medida que o código evolui, identifique duplicações e refatore para eliminar redundâncias.
Estruture com TDA: Organize seu código orientado a objetos para que cada classe seja responsável por seu próprio comportamento.
Use discernimento: Lembre-se que princípios são diretrizes, não regras absolutas. Saiba quando ser flexível e adaptá-los ao contexto específico.

Conclusão

Os princípios DRY, KISS, YAGNI e TDA não são apenas técnicas de codificação - são uma filosofia de desenvolvimento que valoriza clareza, manutenção e eficácia. Quando você internaliza e aplica esses princípios, eles mudam não só o código que você escreve, mas também a maneira como você pensa sobre os problemas de software.

No mundo atual, onde a complexidade técnica cresce a cada dia, a habilidade de manter a simplicidade enquanto resolve problemas complexos é um diferencial valioso. Esses princípios dão um caminho confiável para alcançar esse equilíbrio difícil, desde que você os veja como guias e não como regras absolutas.

Lembre-se: os princípios existem para nos servir, não o contrário. O desenvolvedor maduro sabe quando aplicá-los rigorosamente e quando adaptá-los (ou até mesmo quebrá-los de propósito) para servir a um objetivo maior no design do sistema.

Como Leonardo da Vinci disse há séculos, "a simplicidade é o último grau de sofisticação". No desenvolvimento de software, essa verdade continua valendo, mas o caminho para a simplicidade nem sempre é fácil - exige discernimento, experiência e sabedoria para aplicar os princípios certos, na hora certa, do jeito certo.

Referências Bibliográficas

Hunt, A., & Thomas, D. (1999). The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley Professional.
Martin, R. C. (2008). Clean Code: A Handbook of Agile Software Craftsmanship. Prentice Hall.
Beck, K. (1999). Extreme Programming Explained: Embrace Change. Addison-Wesley Professional.
Fowler, M. (2018). Refactoring: Improving the Design of Existing Code (2nd ed.). Addison-Wesley Professional.
Freeman, S., & Pryce, N. (2009). Growing Object-Oriented Software, Guided by Tests. Addison-Wesley Professional.
Gamma, E., Helm, R., Johnson, R., & Vlissides, J. (1994). Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley Professional.
McConnell, S. (2004). Code Complete: A Practical Handbook of Software Construction (2nd ed.). Microsoft Press.
Castilho, R. (2014). Tell, don't ask. [Blog]. Disponível em: https://robsoncastilho.com.br/2014/05/11/conceitos-tell-dont-ask/
Souza, U. (2022). KISS, YAGNI, DRY – três princípios que todo desenvolvedor deveria conhecer! DEV Community. Disponível em: https://dev.to/urielsouza29/kiss-yagni-dry-tres-principios-que-todo-desenvolvedor-deveria-conhecer-47gg
Thiagomr. (2020). Desvendando o mundo mágico dos acrônimos: SOLID, KISS, YAGNI, DRY, DDD, TDD. DEV Community. Disponível em: https://dev.to/thiagomr/desvendando-o-mundo-magico-dos-acronimos-solid-kiss-yagni-dry-ddd-tdd-2onp
Lazaros. (2023). Conheça os 6 princípios essenciais para arquitetura de um software. Disponível em: https://www.lazaros.com.br/blog/6-principios-arquitetura-software/
Prado, L. P. (2017). O princípio Tell, Don't Ask. [Blog]. Disponível em: https://luizpauloprado.com.br/2017/01/04/o-principio-tell-dont-ask/
Fonseca Chaves, G. (2020). Conceito Tell, Don't Ask. LinkedIn. Disponível em: https://pt.linkedin.com/pulse/conceito-tell-dont-ask-guilherme-fonseca-chaves
Silva, R. (2019). Princípio Tell, Don't Ask. [Blog]. Disponível em: https://ramonsilva.net/post/princípio-tell-don-t-ask

Padronizando Commits Git com um Script Bash: Uma Solução Simples para um Problema Comum

Diego de Sousa Brandão — Mon, 28 Apr 2025 19:11:51 +0000

Índice

O que são Commits Semânticos e por que são importantes
A origem do problema
A solução: um hook Git em Bash
Anatomia do script
- O hook de validação
- O gerenciador de hooks
Instalação e uso
Conclusão e lições aprendidas
FAQ - Perguntas Frequentes
Próximos passos
Referências Bibliográficas

O que são Commits Semânticos e por que são importantes

Commits semânticos são uma convenção para escrever mensagens de commit padronizadas que comunicam claramente a intenção por trás de cada mudança no código. Esta abordagem surgiu da Convenção de Commits Convencionais (Conventional Commits), que por sua vez foi inspirada no Angular Commit Guidelines, utilizado pelo time do Google no desenvolvimento do Angular.

A ideia central é que cada commit deve descrever explicitamente seu propósito através de um formato estruturado:

tipo(escopo): descrição

Origem e Evolução

A convenção de commits semânticos ganhou popularidade por volta de 2015-2016, quando equipes de desenvolvimento começaram a perceber a necessidade de padronizar as mensagens de commit para facilitar a automação de processos como geração de changelogs e versionamento semântico. Inicialmente adotada por projetos JavaScript, a prática se espalhou para diversas linguagens e ecossistemas.

Tipos de Commits

Cada mensagem de commit começa com um "tipo" que indica a natureza da mudança:

feat: introduz uma nova funcionalidade no código
fix: corrige um bug ou problema
docs: alterações apenas na documentação
style: mudanças que não afetam o significado do código (espaços, formatação, etc.)
refactor: alteração de código que não corrige um bug nem adiciona uma feature
perf: melhoria de performance
test: adição ou correção de testes
build: alterações no sistema de build ou em dependências externas
ci: mudanças nos arquivos de configuração de CI/CD
chore: outras alterações que não modificam src ou arquivos de teste
revert: reverte um commit anterior

Onde:

escopo: opcional, indica a parte do código afetada
descrição: explica o que foi feito

Esta convenção traz diversos benefícios:

Legibilidade: Qualquer pessoa consegue entender rapidamente o propósito de um commit
Automatização: Permite gerar changelogs e versionamento semântico automaticamente
Organização: Facilita filtrar commits por tipo (apenas correções, apenas novas features)
Histórico significativo: Transforma o histórico de commits em uma documentação valiosa

Em equipes grandes ou projetos de longo prazo, essa padronização se torna ainda mais crucial, pois ajuda a manter todos alinhados sobre as mudanças realizadas.

A origem do problema

Ao trabalhar em projetos com múltiplos desenvolvedores, percebi a importância de manter um histórico de commits organizado e informativo.

Minha motivação principal para criar este script veio de minha experiência anterior como desenvolvedor full stack, quando tive a oportunidade de implementar o Husky no ecossistema Node.js - uma ferramenta que simplesmente "trava" commits que não seguem o padrão desejado. Após ver o impacto positivo dessa prática, eu queria algo igualmente eficaz e simples para meus projetos Java atuais, sem necessidade de configurações complexas ou dependências adicionais.

Embora existam algumas ferramentas semelhantes, como o JHusky (uma versão Java inspirada no Husky original) e alguns plugins Maven para hooks Git, descobri que muitas dessas soluções exigiam dependências específicas ou se integravam profundamente apenas com um único ecossistema. Eu queria algo verdadeiramente leve e portátil, que funcionasse em qualquer ambiente de desenvolvimento, independentemente das tecnologias utilizadas no projeto.

Foi aí que decidi criar minha própria ferramenta usando Bash, uma linguagem disponível em praticamente qualquer ambiente de desenvolvimento, permitindo que equipes com tecnologias mistas pudessem aproveitar os benefícios de padronização de commits sem precisar instalar ferramentas específicas de linguagem.

A solução: um hook Git em Bash

Decidi então criar uma solução simples: um script Bash que instala um Git hook para validar mensagens de commit, garantindo que elas sigam o padrão de commits semânticos.

Por que Bash? Porque está disponível em praticamente qualquer sistema Unix-like, não requer dependências externas, e qualquer desenvolvedor consegue modificá-lo para suas necessidades específicas.

Apresentação do Script

O script que desenvolvi tem duas partes principais: o hook commit-msg que faz a validação propriamente dita, e um gerenciador para instalar/remover esse hook em repositórios Git.

Aqui está o que ele faz:

Cria um hook commit-msg que valida mensagens de commit usando expressões regulares
Mostra feedbacks visuais coloridos quando o commit é rejeitado
Fornece exemplos corretos para ajudar o desenvolvedor
Permite instalar o hook em um repositório específico ou em todos os repositórios do sistema
Oferece uma interface amigável para gerenciar os hooks

Anatomia do script

O hook de validação

A parte principal do script é o hook em si, que valida a mensagem de commit usando uma expressão regular:

pattern="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9_-]+\))?: .{1,}"

if ! [[ $commit_msg =~ $pattern ]]; then
    # Exibe mensagem de erro formatada com instruções
    # ...
    exit 1
fi

Esta expressão regular garante que cada commit comece com um tipo válido (feat, fix, docs, etc.), opcionalmente seguido por um escopo entre parênteses, e depois por uma descrição.

Quando uma mensagem não segue esse padrão, o script exibe uma mensagem de erro colorida que explica o formato correto e mostra exemplos:

draw_box "ERRO: Mensagem de commit não segue o padrão semântico!" "$RED"
echo -e "\n$RED""Seu commit:$RESET $commit_msg"
echo -e "\n$YELLOW$BOLD""O formato correto é:$RESET <tipo>(<escopo>): <descrição>"
# ... explicação dos tipos válidos ...
echo -e "\n$BOLD$GREEN""Exemplos:$RESET"
draw_box "feat(login): adiciona validação de e-mail" "$GREEN"

Exemplo: A mensagem será exibida na aba de console do Git.

Exemplos rápidos

❌ Commits não semânticos (incorretos)	✅ Commits semânticos (corretos)
"Corrigido o bug de login"	`fix(auth): corrige validação de senha na tela de login`
"Adicionado novo botão"	`feat(ui): adiciona botão de exportar na tela de relatórios`
"Atualizando documentação"	`docs(readme): atualiza instruções de instalação`
"Melhorias no código"	`refactor(core): simplifica lógica de processamento de pagamentos`

O gerenciador de hooks

O script principal oferece uma interface de menu para:

Instalar o hook em um repositório específico ou globalmente
Remover hooks de um repositório específico ou globalmente
Sair do script

O menu é simples e intuitivo:

echo -e "${CYAN}===== ${BOLD}Gerenciador de Git Hook ($HOOK_NAME)${RESET}${CYAN} =====${RESET}"
echo -e "${BLUE}1)${RESET} ${BOLD}Instalar hook${RESET}"
echo -e "${BLUE}2)${RESET} ${BOLD}Remover hook${RESET}"
echo -e "${BLUE}3)${RESET} ${BOLD}Sair${RESET}"

Ao selecionar as opções 1 ou 2, você é apresentado a submenus que permitem escolher entre operações em um repositório específico ou em todos os repositórios do sistema.

Instalação e uso

A instalação do script é simples:

# Clone o repositório
git clone https://github.com/diegoSbrandao/git-hook-manager.git
cd git-hook-manager

# Torne o script executável
chmod +x install-windows-hook.sh

# Execute o script
./install-windows-hook.sh

Após executar o script, você verá um menu interativo:

===== Gerenciador de Git Hook (commit-msg) =====
1) Instalar hook
2) Remover hook
3) Sair
Escolha uma opção:

Opções do menu:

1) Instalar Hook

1.1) Instalar hook a partir de um caminho: Para adicionar o hook em um repositório específico.
1.2) Instalar hook em todos os repositórios do sistema: Para uma instalação global.

2) Remover Hook

2.1) Remover hook de um repositório específico: Remove apenas hooks instalados por este script.
2.2) Remover hooks de todos os repositórios do sistema: Para remoção global.

O script foi desenvolvido para ser compatível com Linux, macOS, WSL e Git Bash no Windows, exigindo apenas requisitos básicos como bash, find e grep, que geralmente já estão disponíveis nestes sistemas.

Conclusão e lições aprendidas

O que aprendi com essa experiência é que às vezes soluções simples resolvem problemas complexos. O script não passa de 150 linhas de código Bash, mas teve um impacto significativo na qualidade do nosso trabalho.

Também aprendi que padronização traz consistência, e consistência facilita a colaboração. Quando todos seguem o mesmo padrão, a comunicação flui melhor.

Por fim, aprendi que ferramentas que ajudam os desenvolvedores a seguir boas práticas são tão importantes quanto as boas práticas em si. Não adianta estabelecer regras se não facilitamos o cumprimento delas.

FAQ - Perguntas Frequentes

Q: O script impede commits que não sejam semânticos?

A: Sim, o hook rejeita automaticamente commits inválidos e exibe uma mensagem de erro explicativa com exemplos corretos.

Q: É possível personalizar os tipos de commit aceitos?

A: Sim, você pode editar o script e modificar a expressão regular que define os tipos válidos.

Q: O script funciona em ambientes Windows?

A: Sim, ele é compatível com Git Bash e WSL (Windows Subsystem for Linux) no Windows.

Q: A instalação afeta todos os meus repositórios automaticamente?

A: Não, você precisa escolher se deseja instalar em um repositório específico ou em todos, dando controle total ao usuário.

Q: O hook afeta commits já realizados?

A: Não, o hook valida apenas novos commits, não alterando o histórico existente.

Próximos passos

É importante destacar que este script está atualmente em versão beta e ainda está em desenvolvimento. Como parte dos planos futuros, pretendo expandir sua funcionalidade integrando-o como um plugin para Maven ou IntelliJ IDEA, tornando-o ainda mais acessível para desenvolvedores Java.

Quando estas versões estiverem disponíveis, atualizarei esta documentação com as novas informações e instruções de uso. Se você tem interesse em contribuir com este projeto ou tem sugestões para estas futuras implementações, não hesite em entrar em contato ou abrir uma issue no repositório.

Referências Bibliográficas

CHACON, S.; STRAUB, B. Pro Git. 2. ed. Apress, 2014. Disponível em: https://git-scm.com/book/en/v2
CONVENTIONAL COMMITS. Conventional Commits 1.0.0. Disponível em: https://www.conventionalcommits.org/

Nota: O projeto está licenciado sob a MIT License e está disponível em: https://github.com/diegoSbrandao/git-hook-manager.git. Sinta-se à vontade para adaptar às necessidades do seu projeto ou equipe. E se tiver sugestões de melhorias, ficarei feliz em recebê-las!

ArchUnit: Garantindo a Integridade Arquitetural de Aplicações Java

Diego de Sousa Brandão — Wed, 23 Apr 2025 02:39:45 +0000

Índice

Introdução
O que o ArchUnit faz?
Por que é importante?
- Documentação Executável
- Feedback Rápido
- Refatoração Segura
- Padronização em Equipes Distribuídas
- Evolução Controlada
Começando com ArchUnit
- Configuração do Projeto
- Escrevendo seu Primeiro Teste
- Executando os Testes
Exemplos Práticos
- Arquitetura em Camadas
- Arquitetura Limpa
Recursos Avançados do ArchUnit
- Regras Personalizadas Complexas
- Verificação de Interfaces e Herança
- Detecção de Ciclos de Dependência
- Cache de Importação
- Mensagens de Erro Personalizadas
- Utilizando Regras Pré-definidas
- Verificando Convenções de Nomenclatura
- Congelamento de Regras para Projetos Legados
Conclusão
Referência Bibliográfica

Introdução

Em projetos de software de médio e grande porte, garantir que o código siga os padrões arquiteturais definidos é um desafio contínuo. Conforme o código cresce e mais desenvolvedores participam do projeto, torna-se cada vez mais difícil manter a consistência arquitetural. É nesse contexto que o ArchUnit surge como uma ferramenta poderosa para desenvolvedores Java.

ArchUnit é uma biblioteca Java de código aberto que possibilita testar de forma automatizada se o código segue as regras arquiteturais estabelecidas. Ao contrário de ferramentas de análise estática tradicionais, o ArchUnit permite que você defina regras específicas para seu domínio e integre os testes de arquitetura diretamente na sua suíte de testes unitários.

O que o ArchUnit faz?

O ArchUnit permite que você teste aspectos como:

Dependências entre pacotes e classes: Garantir que camadas específicas não dependam de outras camadas indevidamente.
Convenções de nomenclatura: Certificar que nomes de classes e métodos sigam os padrões estabelecidos.
Uso adequado de anotações: Verificar se anotações específicas estão presentes onde deveriam estar.
Acesso a métodos e campos: Verificar que determinados métodos ou campos só são acessados em contextos específicos.
Estrutura de herança: Garantir que certas classes herdem ou implementem interfaces específicas.
Ciclos de dependência: Identificar e evitar ciclos de dependência que possam comprometer a manutenibilidade.
Validação de padrões arquiteturais conhecidos: Testar a conformidade com padrões como Arquitetura em Camadas, Arquitetura Limpa, etc.

Por que é importante?

A importância do ArchUnit vai além da simples verificação de código:

1. Documentação Executável

O ArchUnit transforma decisões arquiteturais em testes executáveis, servindo como documentação viva do projeto. Novos membros da equipe podem entender rapidamente as convenções arquiteturais examinando os testes.

2. Feedback Rápido

Ao integrar testes de arquitetura na sua pipeline de CI/CD, você recebe feedback imediato quando uma mudança no código viola as regras arquiteturais estabelecidas, prevenindo a degradação gradual da arquitetura.

3. Refatoração Segura

Durante grandes refatorações, o ArchUnit pode garantir que as mudanças respeitem as regras arquiteturais, dando confiança para evoluir o código com segurança.

4. Padronização em Equipes Distribuídas

Em equipes grandes ou distribuídas, o ArchUnit ajuda a manter consistência nas práticas de desenvolvimento, mesmo quando a comunicação direta entre equipes é limitada.

5. Evolução Controlada

Quando a arquitetura precisa evoluir, você pode atualizar os testes de arquitetura para refletir as novas diretrizes, facilitando a transição controlada de um padrão arquitetural para outro.

Começando com ArchUnit

Vamos ver como configurar e começar a usar o ArchUnit em um projeto Java:

Configuração do Projeto

Para Maven (pom.xml):

<!-- Dependência principal do ArchUnit -->
<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit5</artifactId>
    <version>1.4.0</version>
    <scope>test</scope>
</dependency>

Para Gradle (build.gradle):

dependencies {
    testImplementation 'com.tngtech.archunit:archunit-junit5:1.4.0'
}

Escrevendo seu Primeiro Teste

Depois de adicionar as dependências, você pode criar seu primeiro teste de arquitetura. Comece com algo simples:

package com.example.archunit;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.lang.ArchRule;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;

public class ArchitectureTest {

    // Importando classes do seu projeto para análise
    JavaClasses importedClasses = new ClassFileImporter()
            .importPackages("com.example.project");

    @Test
    public void servicesShouldNotDependOnControllers() {
        // Definindo uma regra arquitetural
        ArchRule rule = classes()
                .that().resideInAPackage("..service..")
                .should().notDependOnClassesThat()
                .resideInAPackage("..controller..");

        // Verificando se a regra é respeitada
        rule.check(importedClasses);
    }
}

Este teste simples verifica se as classes no pacote service não dependem de classes no pacote controller, o que é uma regra comum em arquiteturas em camadas.

Executando os Testes

Para executar os testes de arquitetura:

Via Maven:

   mvn test

Via Gradle:

   ./gradlew test

Na sua IDE: Execute o teste como qualquer outro teste JUnit.

Se alguma regra for violada, você verá um erro no teste com uma mensagem detalhada explicando quais classes violaram a regra e como.

Por exemplo:

Architecture Violation [Priority: MEDIUM] - Rule 'classes that reside in a package '..service..' should not depend on classes that reside in a package '..controller..'' was violated (1 times):
Method com.example.project.service.UserService.getControllerData() calls method com.example.project.controller.UserController.getData()

Utilizando JUnit 5 para Simplificar os Testes

Se você estiver usando JUnit 5, pode simplificar ainda mais seus testes usando as anotações fornecidas pelo ArchUnit:

@AnalyzeClasses(packages = "com.example.project")
public class ArchitectureRulesTest {

    // O ArchUnit irá importar automaticamente as classes e verificar a regra
    @ArchTest
    static final ArchRule servicesShouldNotDependOnControllers = classes()
            .that().resideInAPackage("..service..")
            .should().notDependOnClassesThat()
            .resideInAPackage("..controller..");

    // Regras adicionais podem ser definidas como campos estáticos
    @ArchTest
    static final ArchRule repositoriesShouldBeAccessedOnlyByServices = classes()
            .that().resideInAPackage("..repository..")
            .should().onlyBeAccessedByClassesThat()
            .resideInAPackage("..service..");
}

Usando esta abordagem, não é necessário escrever explicitamente o código para importar as classes ou verificar as regras. O ArchUnit cuida disso automaticamente e também implementa um cache de classes entre os testes para melhorar o desempenho.

Exemplos Práticos

Vejamos dois exemplos práticos de como utilizar o ArchUnit para garantir a integridade de diferentes padrões arquiteturais:

Exemplo 1: Arquitetura em Camadas (Layered Architecture)

Este exemplo demonstra como validar uma arquitetura em camadas tradicional, comum em muitas aplicações:

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.library.Architectures;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.library.Architectures.layeredArchitecture;

public class LayeredArchitectureTest {

    @Test
    public void testLayeredArchitecture() {
        JavaClasses importedClasses = new ClassFileImporter()
                .importPackages("com.mycompany.app");

        // Definindo a arquitetura em camadas usando o padrão predefinido
        Architectures.LayeredArchitecture layeredArchitecture = layeredArchitecture()
                // Definindo as camadas e os pacotes onde elas residem
                .layer("Controller").definedBy("..controller..")
                .layer("Service").definedBy("..service..")
                .layer("Repository").definedBy("..repository..")
                .layer("Domain").definedBy("..domain..")

                // Definindo as regras de dependência entre camadas
                .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
                .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
                .whereLayer("Repository").mayOnlyBeAccessedByLayers("Service")
                .whereLayer("Domain").mayOnlyBeAccessedByLayers("Service", "Repository");

        // Verificando a arquitetura
        layeredArchitecture.check(importedClasses);
    }
}

Este teste valida um padrão arquitetural em camadas típico onde:

Controllers ficam no topo da hierarquia e não devem ser acessados por outras camadas
Services podem ser acessados apenas pelos Controllers
Repositories podem ser acessados apenas por Services
O Domain (entidades) pode ser acessado por Services e Repositories

Exemplo 2: Arquitetura Limpa (Clean Architecture / Onion Architecture)

Este exemplo verifica a conformidade com os princípios da Arquitetura Limpa:

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.library.Architectures.onionArchitecture;

public class CleanArchitectureTest {

    @Test
    public void testCleanArchitecture() {
        JavaClasses importedClasses = new ClassFileImporter()
                .importPackages("com.mycompany.app");

        // Definindo a arquitetura limpa (onion architecture)
        // Note que esta funcionalidade está disponível no pacote com.tngtech.archunit.library
        onionArchitecture()
                // Definindo as camadas da arquitetura limpa
                .domainModels("..domain.model..")
                .domainServices("..domain.service..")
                .applicationServices("..application..")
                .adapter("persistence", "..adapter.persistence..")
                .adapter("rest", "..adapter.rest..")
                .adapter("cli", "..adapter.cli..")

                // A verificação é implícita: camadas internas não podem
                // depender de camadas externas
                .check(importedClasses);
    }
}

Este teste valida os princípios fundamentais da Arquitetura Limpa, onde:

O núcleo do domínio não depende de nenhuma outra camada
A camada de aplicação depende apenas do domínio
Os adaptadores (persistence, rest, cli) dependem da aplicação e do domínio

Note que a função onionArchitecture() é disponibilizada pelo pacote com.tngtech.archunit.library.Architectures, então certifique-se de incluir a dependência correta.

Recursos Avançados do ArchUnit

Além dos exemplos acima, o ArchUnit oferece recursos avançados que muitos desenvolvedores desconhecem:

Regras Personalizadas Complexas

Você pode criar regras de arquitetura altamente específicas usando a API fluente do ArchUnit:

ArchRule rule = classes()
    .that().areAnnotatedWith(RestController.class)
    .should().haveSimpleNameEndingWith("Controller")
    .andShould().bePublic()
    .andShould().onlyAccessMethodsThat(areDeclaredInController().or(areDeclaredInService()));

Verificação de Interfaces e Herança

Embora o ArchUnit não tenha suporte nativo direto para verificação de hierarquia completa, você pode verificar implementações de interfaces ou extensões de classes específicas:

// Verificando se todas as classes em um pacote implementam uma interface
ArchRule rule = classes()
    .that().resideInAPackage("..repository..")
    .should().implement(JpaRepository.class);

// Verificando se todas as classes que têm um determinado sufixo estendem uma classe base
ArchRule rule2 = classes()
    .that().haveSimpleNameEndingWith("Controller")
    .should().beAssignableTo(BaseController.class);

Detecção de Ciclos de Dependência

Os ciclos de dependência são um dos problemas arquiteturais mais difíceis de detectar manualmente:

ArchRule noCyclicDependencies = slices()
    .matching("com.mycompany.app.(*)..")
    .should().beFreeOfCycles();

Cache de Importação

Para melhorar a performance dos testes em bases de código grandes, o ArchUnit oferece opções de cache:

ClassFileImporter importer = new ClassFileImporter()
    .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
    .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_JARS);

JavaClasses classes = importer.importPackages("com.mycompany.app");

É importante notar que este cache funciona apenas durante a mesma execução de testes e não persiste entre diferentes execuções ou builds. Ele melhora a performance ao reutilizar as classes importadas na mesma execução dos testes.

Mensagens de Erro Personalizadas

Melhore a compreensão quando os testes falham:

ArchRule rule = classes()
    .that().areAnnotatedWith(Entity.class)
    .should().resideInAPackage("..domain.model..")
    .because("Entities são parte do modelo de domínio");

Utilizando Regras Pré-definidas

O ArchUnit fornece várias regras pré-definidas na classe GeneralCodingRules que podem ser utilizadas diretamente:

import static com.tngtech.archunit.library.GeneralCodingRules.*;

@ArchTest
static final ArchRule noClassesShouldUseJodaTime = NO_CLASSES_SHOULD_USE_JODATIME;

@ArchTest
static final ArchRule noClassesShouldUseStandardStreams = NO_CLASSES_SHOULD_ACCESS_STANDARD_STREAMS;

@ArchTest
static final ArchRule noClassesShouldThrowGenericExceptions = NO_CLASSES_SHOULD_THROW_GENERIC_EXCEPTIONS;

@ArchTest
static final ArchRule noClassesShouldUseJavaUtilLogging = NO_CLASSES_SHOULD_USE_JAVA_UTIL_LOGGING;

Observe que estas regras pré-definidas estão disponíveis no pacote com.tngtech.archunit.library, e não no core do ArchUnit. Certifique-se de incluir a dependência correta.

Verificando Convenções de Nomenclatura

Você pode garantir que suas convenções de nomenclatura sejam seguidas:

@ArchTest
static final ArchRule serviceClassesShouldHaveServiceSuffix = classes()
    .that().resideInAPackage("..service..")
    .should().haveSimpleNameEndingWith("Service");

@ArchTest
static final ArchRule repositoryClassesShouldHaveRepositorySuffix = classes()
    .that().resideInAPackage("..repository..")
    .should().haveSimpleNameEndingWith("Repository")
    .orShould().haveSimpleNameEndingWith("Dao");

Congelamento de Regras para Projetos Legados

Para equipes que trabalham com código legado, o ArchUnit oferece a funcionalidade de "congelamento" (freezing) de regras. Isso permite que você mantenha as violações existentes, mas impede novas violações:

// Criando uma regra normal
ArchRule rule = classes()
    .that().resideInAPackage("..service..")
    .should().notDependOnClassesThat()
    .resideInAPackage("..controller..");

// Congelando a regra para permitir violações existentes
FreezingArchRule frozenRule = FreezingArchRule.freeze(rule);

// Verificando apenas novas violações
frozenRule.check(importedClasses);

Esta técnica é extremamente útil quando você quer melhorar gradualmente a arquitetura de um sistema legado sem ter que corrigir todas as violações de uma só vez.

Conclusão

O ArchUnit representa um avanço significativo na forma como garantimos a qualidade arquitetural em projetos Java. Ao transformar regras arquiteturais em testes automatizados, ele ajuda a manter a integridade do código mesmo à medida que o projeto cresce e evolui.

A ferramenta não apenas detecta violações arquiteturais precocemente, mas também serve como documentação viva das decisões arquiteturais tomadas pela equipe. Isto facilita a adaptação de novos membros e garante consistência em equipes distribuídas.

Se você está enfrentando desafios para manter a consistência arquitetural em seu projeto Java, o ArchUnit pode ser uma adição valiosa ao seu conjunto de ferramentas de qualidade de código.

Para ver um exemplo prático de implementação dos conceitos apresentados neste artigo, você pode acessar o repositório Arquitetura em Camadas com ArchUnit que demonstra a aplicação desses princípios com exemplos de código e testes de arquitetura personalizados.