Como debugar seu projeto Spring Boot usando o IntelliJ IDEA Community Edition
Como debugar/depurar seu projeto Spring Boot usando o IntelliJ IDEA Community Edition.
Você marcou o breakpoint no seu código, iniciou uma sessão de debug mas a execução não paralisou onde você marcou. É algo chato, irritante, que sempre ocorre comigo, porém fácil de resolver. Bora lá?
Ingredientes
- Intellij Idea Community Edition (em breve vai ser unificado ao Ultimate) versão 2025.2.1
- Sua aplicação usando Spring Boot 2.x ou 3.x
- Maven - por que é o que costumamos usar na itexto
- JDK - qualquer versão a partir do 8
Pra começar: você sabe como debugar (depurar) algo com Intellij IDEA?
É razoavelmente simples: envolve dois passos apenas. O primeiro é marcar o ponto no seu código em que você quer que a execução seja paralisada (é o breakpoint). Faça isto clicando no número da linha em seu editor, tal como no print abaixo:
Há dois pontos para iniciar a depuração. O primeiro está na aba Maven do IntelliJ. No grupo "Plugins/spring-boot" você vai buscar a opção "spring-boot:run". Clica com o botão direito do mouse sobre esta opção e depois sobre a alternativa "Debug...", tal como no print abaixo:
Após esta primeira execução vai aparecer nas opções de execução que fica no topo direito da IDE a opção pra depurar. É o ícone de "bichinho" que mostro no print abaixo:
Lindo né? Mega fácil: só que não. Apenas isto não irá parar a execução no seu breakpoint quando o código for executado.
Como resolver o problema
A causa raiz do problema é que a aplicação é executada em uma JVM diferente da do Maven: é o que se chama de "fork". Então segue uma solução que vale pra qualquer versão do Spring Boot.
Aqui está o textinho mágico que é a razão principal pela qual estou escrevendo esta receita (eu sempre esqueço):
-Dspring-boot.run.jvmArguments=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005Primeiro passo: modifique sua run configuration
Você irá modificar a "run configuration" do Maven. Há dois caminhos pra isto: o primeiro é na aba Maven do IntelliJ: clique com o botão direito sobre "spring-boot:run" e escolha a opção "Modify run configuration", tal como no print a seguir:
Ou no menu de execução, tal como no print a seguir:
Adicione o "texto mágico" que citei acima na caixa de texto "Run" da janela "Run/Debug Configurations", tal como no print:
Veja aqui a minha configuração de exemplo:
spring-boot:run -Dspring-boot.run.jvmArguments=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -f pom.xmlAtenção: o parâmetro "-f" deve sempre vir por último
Clique no botão "Ok" ou "Apply".
Segundo passo: depurando com alegria
Usando a run configuration que você alterou, inicie seu projeto. Não se esqueça de marcar seus breakpoints aonde você quer depurar o código.
No menu "Run" do IntelliJ, clique sobre a opção "Attach to Process", tal como no print a seguir:
Irá surgir uma janela:
Selecione o processo (pode ser meio confuso com execuções passadas). Execute o código que vai parar no seu breakpoint e...
A depuração está funcionando agora!
Atenção para a barra de ferramentas de execução: note que agora há dois processos que você pode parar, tal como exposto no print a seguir:
Aí você pode parar tanto o processo principal ("o do spring-boot:run") quanto o do depurador: "localhost:5005". Como funciona isto?
Passo 3 - entendendo a solução
Nós apenas habilitamos o agente de depuração da JVM o configurando para ouvir na porta 5005. Com isto, a sua aplicação está disponível para que qualquer outro processo Java de depuração possa se conectar e inspecionar seu ambiente de execução, paralisar execução, etc.
É possível inclusive depurar código remotamente assim. Recomendo? Não, só se você tiver pleno controle sobre o ambiente e a segurança do mesmo.
Concluindo e mostrando alternativas
Esta não é a única solução para o problema: a causa raiz é o fork mode que inicia a aplicação em um processo diferente do Maven.
Você também pode desabilitar o fork mode modificando seu arquivo pom.xml ou passando parâmetros para o Maven, tal como exposto neste link. O problema é que nem sempre funciona: pode variar de acordo com a versão do Spring Boot, Maven, IntelliJ.
Até a próxima!
Este é um excelente exemplo do que chamamos de "Receita": a solução de um problema que ocorre o tempo inteiro e que você precisa ter a solução salva em algum lugar. Recomendamos MUITO que você crie seu próprio livro de receitas. Quer conhecer esta nossa técnica? Leia o texto abaixo!
