powered byiMasterstutoriais · referência · código em portuguêsPatrocínio
Java

Spring Boot 4: como migrar seu projeto 3.x sem parar a entrega

As release notes oficiais do Spring Boot 4.0 mudam pacotes, renomeiam propriedades e trazem starters novos. Veja o que quebra, o que é opcional e a ordem recomendada para migrar um projeto 3.x em produção.

Por Marcelo TeixeiraColunista7 min de leitura
Spring Boot 4: como migrar seu projeto 3.x sem parar a entrega
Spring Boot 4: como migrar seu projeto 3.x sem parar a entrega

Este guia organiza o que está nas release notes oficiais do Spring Boot 4.0, mantidas por Andy Wilkinson no wiki do projeto no GitHub (revisão de 16 de setembro de 2026), na ordem que importa para quem precisa tirar um projeto 3.x do lugar sem parar a esteira de deploy. Os exemplos abaixo foram escritos contra as release notes publicadas pela equipe do Spring Boot para a versão 4.0.

Baseline de JDK e build tool

O Spring Boot 4.0 é construído sobre o Spring Framework 7.0. As release notes oficiais não especificam qual versão mínima de JDK passa a ser exigida nessa major; antes de migrar, vale checar a documentação de compatibilidade do projeto para confirmar se é preciso trocar de JDK antes de tocar no Spring Boot.

No build, o Gradle 9 passou a ser suportado, mas o Gradle 8.14 ou mais recente continua funcionando — não há prazo de corte anunciado nas release notes para quem fica no 8.x. No Maven, a recomendação é atualizar o maven-javadoc-plugin para a versão 3.12 e o maven-antrun-plugin para a 3.2, já que ambos aparecem na lista de dependências de terceiros atualizadas.

Uma novidade de infraestrutura que facilita o teste antecipado: desde a milestone 4.0.0-M1, todas as milestones e release candidates do Spring Boot passaram a ser publicadas também no Maven Central, além do repositório repo.spring.io. Isso elimina a necessidade de declarar um repositório extra só para experimentar uma milestone 4.x.

Pacotes e starters que mudaram de lugar

Três mudanças de empacotamento merecem checagem manual antes do mvn dependency:tree ou do gradle dependencies rodarem limpos:

  • Os health indicators de MongoDB saíram do artefato spring-boot-data-mongodb e foram para spring-boot-mongodb, com os pacotes Java atualizados de acordo. Isso permite expor saúde do MongoDB usando só o driver Java, sem depender do Spring Data MongoDB — mas quebra qualquer import direto da classe antiga.
  • Um starter novo, spring-boot-starter-opentelemetry, concentra as dependências para exportar métricas e traces via OTLP e auto-configura o SDK do OpenTelemetry. Quem hoje monta essa stack manualmente pode trocar várias dependências avulsas por esse starter único.
  • Para quem usa Kotlin Serialization em vez de Jackson, o módulo spring-boot-kotlinx-serialization-json e o starter spring-boot-starter-kotlin-serialization contribuem um bean Json configurável pelas propriedades spring.kotlinx.serialization.json.*, com um HttpMessageConverter próprio que entra antes dos conversores JSON padrão.

Propriedades e classes renomeadas

Esta é a parte que mais costuma quebrar silenciosamente, porque o Spring sobe sem erro e o comportamento muda sem aviso. As release notes listam renomeações pontuais que valem um grep no seu application.properties ou application.yml:

properties
# antes (Spring Boot 3.x) -> depois (Spring Boot 4.0)
# management.tracing.enabled=true -> management.tracing.export.enabled=true
# spring.dao.exceptiontranslation.enabled=true -> spring.persistence.exceptiontranslation.enabled=true
management.tracing.export.enabled=true
spring.persistence.exceptiontranslation.enabled=true
management.health.ssl.certificate-validity-warning-threshold=14d

No código, a anotação @ConditionalOnEnabledTracing virou @ConditionalOnEnabledTracingExport, e a classe ScheduledTasksObservabilityAutoConfiguration foi renomeada para ScheduledTasksObservationAutoConfiguration. Se o projeto referencia alguma dessas classes diretamente (comum em testes de auto-configuração customizada), o build quebra na compilação, não em runtime — o que pelo menos facilita achar o problema.

O status WILL_EXPIRE_SOON do health check de SSL foi removido: um certificado nesse estado agora aparece como VALID, e as cadeias próximas do vencimento vão para uma entrada nova chamada expiringChains dentro do health response. Quem monitora esse status específico num dashboard ou alerta precisa reescrever a regra.

Para MongoDB, uma propriedade nova, spring.data.mongodb.representation.big-decimal, controla como valores BigDecimal e BigInteger são persistidos. Outras propriedades de MongoDB também foram renomeadas — a lista completa está no guia de migração oficial, não nas release notes, então vale abrir os dois documentos lado a lado.

As dependências major que carregam o maior risco

A lista de upgrades de dependências do Spring Boot 4.0 é longa, mas algumas pesam mais que outras na hora de migrar:

DependênciaVersão em 4.0Por que importa
Jackson3.0Major version nova; o suporte a Jackson 2 passa a existir apenas em forma depreciada
Spring Framework7.0Base de todo o restante da atualização de dependências do Spring Boot 4.0
Hibernate7.2Projetos com queries nativas ou customizações de dialect merecem teste de regressão
Spring Security7.0Major version; configurações de segurança customizadas precisam de revisão
Tomcat / Jetty11.0 / 12.1Servidores embarcados também sobem de major, com Jakarta Servlet 6.1

O caso mais delicado da tabela é o Jackson. A equipe do Spring Boot deixou explícito nas release notes que "Jackson 2 support ships in a deprecated form" — ou seja, quem tem código próprio importando classes de com.fasterxml.jackson na versão 2 ainda funciona, mas já está na fila de remoção. Vale planejar essa migração separadamente, antes ou depois do upgrade do Spring Boot em si.

O que é novo e vale olhar, mas não bloqueia a migração

Nem toda novidade do Spring Boot 4.0 precisa entrar no escopo da migração. Dá para subir de versão primeiro e adotar essas features depois, com calma:

Nota da redação: o código desta seção não foi executado em ambiente real. Valide antes de usar em produção.

java
package com.example.client;

import org.springframework.web.bind.annotation.PostExchange;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.bind.annotation.RequestBody;

import java.util.Map;

@HttpExchange(url = "https://echo.zuplo.io")
public interface EchoService {

    @PostExchange
    Map<?, ?> echo(@RequestBody Map<String, String> message);

}

Com auto-configuração nova para HTTP Service Clients, essa interface vira um bean injetável sem implementação manual. Outras adições que não exigem migração imediata: API Versioning configurável via spring.mvc.apiversion.* ou spring.webflux.apiversion.*; a API JmsClient como alternativa ao JmsTemplate (que continua funcionando sem mudanças); o RestTestClient, injetável em testes com @SpringBootTest ou @AutoConfigureMockMvc; e suporte a Redis Static Master/Replica via spring.data.redis.masterreplica.nodes, disponível apenas com o driver Lettuce.

A ordem recomendada para migrar sem parar a entrega

A própria equipe do Spring Boot recomenda, nas release notes, que quem está numa versão anterior ao 3.5 passe por ela primeiro antes de ir para o 4.0. A partir daí, a sequência que reduz risco de quebra em produção é:

  1. Suba para Spring Boot 3.5 se ainda não estiver lá, e rode a suíte de testes completa nessa versão.
  2. Trate todo warning de depreciação que o 3.5 já emite — boa parte do que quebra no 4.0 já aparecia como aviso antes.
  3. Confira o changelog de configuração oficial do projeto para a lista completa de propriedades renomeadas, não só as citadas nas release notes.
  4. Atualize o build tool (Gradle para 8.14+ ou 9, ou os plugins de Maven listados) antes de trocar a versão do Spring Boot.
  5. Troque a versão do Spring Boot para 4.0 e rode o build; corrija os erros de compilação ligados a classes renomeadas (ConditionalOnEnabledTracingExport, ScheduledTasksObservationAutoConfiguration) e aos pacotes movidos do MongoDB.
  6. Ajuste application.properties/application.yml com as propriedades renomeadas e rode os testes de integração, prestando atenção especial a health checks de SSL e a métricas de tracing.
  7. Se o projeto usa Jackson diretamente, isole esse ponto e planeje a saída do Jackson 2 como tarefa separada, já que ele só existe em forma depreciada no 4.0.
  8. Faça o deploy em canário antes do rollout completo, dado o volume de majors (Framework, Security, Hibernate, Jackson) que sobem juntos.

Quando não vale migrar agora

Em resumo: adie o upgrade se o projeto ainda não passou pelo Spring Boot 3.5, se depende pesadamente de classes do Jackson 2 espalhadas pelo código, ou se não tem cobertura de teste suficiente para validar Hibernate 7.2 e Spring Security 7.0 ao mesmo tempo. Migrar um monólito grande direto de 3.0 para 4.0, pulando o passo intermediário, multiplica o número de breaking changes a diagnosticar de uma vez.

Próximo passo

Depois de aplicar esta checagem, o guia de migração oficial "v3.5 → v4.0" no wiki do spring-projects/spring-boot traz a lista completa de propriedades renomeadas, incluindo as de MongoDB que não couberam nas release notes. Vale também abrir o changelog de configuração do projeto antes de cada etapa, e usar o Spring Initializr para comparar as dependências de um projeto novo em 4.0 com o pom.xml ou build.gradle atual.

Fonte: GitHub (spring-projects/spring-boot): Spring Boot 4.0 Release Notes

PatrocínioContinue estudando JavaTrilhas completas, projetos e exercícios na DevMedia.Travou em algum passo?Pergunte no Fórum iMastersPoste o trecho de código e o erro: a comunidade responde.Notícias da stackO que saiu de novo, no iMastersLançamentos, versões e eventos do ecossistema dev.

Este artigo foi escrito por Marcelo Teixeira. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.

Marcelo Teixeira

Editor virtual de Java do Linha de Código. Cobre Java moderno (records, pattern matching, virtual threads), Spring Boot, JPA e Hibernate, Maven e Gradle, e o Kotlin quando ele conversa com a JVM. Escreve para quem mantém o monólito da empresa e para quem está aprendendo a primeira linguagem tipada, sempre declarando a versão do JDK e do framework.

Próximos passoso que estudar a partir daqui

  1. você está aquiSpring Boot 4: como migrar seu projeto 3.x sem parar a entrega
  2. mesmo autorRecords em Java: o que são, quando substituem a classe e as pegadinhas com JPA e JacksonJava · 1 min

Newsletter

Os melhores tutoriais da semana, no seu e-mail

Toda semana, os tutoriais novos das sete stacks e o guia de referência que vale guardar. Gratuita, sem spam.