Migração do Spring Boot 3 para 4: Um Guia Estratégico para Preparar sua API para o Futuro

Sumário

Visão Geral
Pré-requisitos e Compatibilidade
Principais Mudanças Introduzidas
Fases da Migração
Detalhamento das Quebras de Compatibilidade
Configuração de Propriedades
Segurança (Spring Security 7)
Persistência (Hibernate 7 + Spring Data 2025.1)
Testes
Build e Ferramentas
Conclusão
Referências

1. Visão Geral

O Spring Boot 4.0 foi lançado em novembro de 2025 e representa a maior evolução do framework desde a mudança javax → jakarta introduzida no Spring Boot 3. Esta versão é construída sobre o Spring Framework 7 e o Jakarta EE 11, trazendo modularização completa do autoconfigure, suporte nativo a threads virtuais, versionamento de APIs REST e segurança de nulos via JSpecify.

Por que migrar?

Suporte ao Spring Boot 3.5 encerrando: Em 30/06/2026, encerra-se o suporte Open Source. Após essa data, sem patches de segurança.
Performance: Menor uso de memória, startup mais rápido com imagens nativas.
Modularidade: Mais de 70 starters granulares — reduza CVEs desnecessários.
Threads Virtuais: Suporte a Project Loom consolidado (disponível desde o 3.2, Java 21+).
Evolução das anotações: JSpecify integrado ao nível de API do framework.

Escopo da migração

Esta é uma migração major — espere trabalho real. Não basta simplesmente alterar a versão no pom.xml ou build.gradle. As principais áreas impactadas são:

Runtime Java (mínimo Java 17, recomendado Java 21)
Build tool (Gradle 8.14+, Maven 3.6.3+)
Dependências transitivas (Jackson 3, Hibernate 7, Spring Security 7)
Propriedades de configuração renomeadas/removidas
APIs deprecadas removidas

2. Pré-requisitos e Compatibilidade

Para o Spring Boot 4, as exigências de ambiente focam principalmente na versão do Java e nas ferramentas de build. Componentes internos (como Spring Framework 7, Jakarta EE 11 e Servlet 6.1) são resolvidos nativamente.

Requisitos Básicos

Java: Mínimo 17, porém o recomendado é o 21 (LTS) ou superior para extrair o máximo do framework.
Ferramentas de Build: Maven (mínimo 3.6.3, recomendado 3.9+) ou Gradle (mínimo 8.14, recomendado 9.x).
GraalVM (opcional): Versão 25+ caso vá compilar imagens nativas.

Nota: Não é necessário mapear individualmente as versões dos módulos (como Spring Security 7.0, Spring Data 2025.1, etc.). Como de praxe, o BOM (spring-boot-dependencies) do Spring Boot 4 gerencia o alinhamento de todas as bibliotecas oficiais do ecossistema automaticamente.

⚠️ Atenção — Ecossistema de terceiros: Bibliotecas externas (Spring Cloud, starters customizados, integrações proprietárias) podem ainda não ser compatíveis com Spring Boot 4. Audite todas as dependências antes de iniciar a migração.

3. Principais Mudanças Introduzidas

3.1 Modularização completa

O autoconfigure monolítico foi dividido em 70+ módulos focados. Isso reduz o tamanho dos artefatos e elimina dependências transitivas desnecessárias.

3.2 JSpecify e null safety

O Spring Boot 4 incorpora anotações JSpecify (@Nullable, @NonNull) em toda a API do framework, formalizando o contrato de nulos ao nível do compilador.

3.3 Suporte a Java 25 (mantendo Java 17)

Permite uso do Java 25, com retrocompatibilidade garantida para Java 17.

3.4 API Versioning nativo

Suporte built-in para versionamento de APIs REST sem necessidade de bibliotecas externas. O mecanismo utiliza o atributo version nas anotações de mapeamento já existentes (@RequestMapping, @GetMapping, etc.), com configuração via propriedades spring.mvc.apiversion.* e ApiVersionConfigurer.

Exemplo prático:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


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

    @GetMapping(version = "1.0")
    public List<UsuarioV1> listarV1() {
        // ...
    }

    @GetMapping(version = "2.0")
    public List<UsuarioV2> listarV2() {
        // ...
    }
}

As requisições agora podem ser roteadas nativamente com base no cabeçalho Accept-Version ou parâmetros na URL, configurados via application.properties.

3.5 HTTP Service Clients aprimorados

A abstração de clientes HTTP declarativos (introduzida no Spring Boot 3.x) atinge sua maturidade no Spring Boot 4. A configuração desses clientes usando o novo RestClient exige muito menos boilerplate, facilitando integrações baseadas em interfaces puras.

Exemplo prático:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 1. Definição da interface declarativa
@HttpExchange("/api/v1/pedidos")
public interface PedidoClient {

    @GetExchange("/{id}")
    Pedido buscarPorId(@PathVariable("id") String id);
    
    @PostExchange
    Pedido criarPedido(@RequestBody PedidoDTO dto);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 2. Configuração mais fluida no Spring Boot 4
@Configuration
public class ClientConfig {

    @Bean
    public PedidoClient pedidoClient(RestClient.Builder builder) {
        RestClient restClient = builder.baseUrl("https://api.parceiro.com").build();
        
        // A geração do proxy agora é muito mais direta com o RestClientAdapter
        RestClientAdapter adapter = RestClientAdapter.create(restClient);
        HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();
        
        return factory.createClient(PedidoClient.class);
    }
}

Dica: Para times migrando do antigo RestTemplate ou WebClient, o uso do RestClient acoplado às interfaces HTTP declarativas é o novo padrão ouro para chamadas externas.

3.6 Virtual Threads (Project Loom)

As threads virtuais do Java 21 já são suportadas desde o Spring Boot 3.2 (via spring.threads.virtual.enabled=true). O Spring Boot 4, construído sobre o Spring Framework 7, dá continuidade a esse suporte e melhora a compatibilidade do ecossistema — o Hibernate 7 e demais bibliotecas do stack foram testados e otimizados para compatibilidade com threads virtuais, minimizando situações de pinning de carrier threads.

4. Fases da Migração

Fase 0 — Preparação

Objetivo: Garantir que a aplicação está no estado ideal em Spring Boot 3.x antes de qualquer upgrade.

1
2
3
4
5
6
7
8


[ ] Atualizar para o Spring Boot 3.5.x mais recente
[ ] Compilar com flag -Xlint:deprecation
[ ] Resolver TODOS os warnings de deprecação
[ ] Mapear dependências de terceiros e verificar compatibilidade com SB4
[ ] Identificar bibliotecas sem release para Spring Framework 7
[ ] Garantir cobertura de testes adequada (unitários + integração)
[ ] Criar branch de migração isolada no repositório
[ ] Configurar pipeline CI dedicado para a branch de migração

Por que isso é crítico?

O Spring Boot 3.5 foi projetado como ponte para o 4.0. Todos os itens deprecados no 3.x que foram removidos no 4.0 já emitem warnings no 3.5. Resolver esses warnings no 3.5 é muito mais seguro do que descobrir as quebras diretamente no 4.0.

Fase 1 — Atualização do Runtime Java

Objetivo: Garantir que a JVM e o toolchain estejam compatíveis.

1
2
3
4
5
6


# Verificar versão atual
java -version

# Instalar Java 21 (recomendado via SDKMAN)
sdk install java 21.0.3-tem
sdk use java 21.0.3-tem

Atualize o pom.xml:

1
2
3
4
5


<properties>
    <java.version>21</java.version>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
</properties>

Atualize o build.gradle:

1
2
3
4
5


java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

Fase 2 — Atualização do Build Tool

Maven — pom.xml:

1
2
3
4
5
6


<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.0</version> <!-- Use a versão mais recente do 4.0 -->
    <relativePath/>
</parent>

Gradle — build.gradle:

1
2
3
4
5


plugins {
    id 'org.springframework.boot' version '4.1.0'
    id 'io.spring.dependency-management' version '1.1.7'
    id 'java'
}

Se usar Gradle, atualize para Gradle 9 (mínimo 8.14).

Fase 3 — Migração de Dependências

Adicionar o migrador de propriedades (temporário):

1
2
3
4
5
6


<!-- Maven -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

1
2


// Gradle
runtimeOnly("org.springframework.boot:spring-boot-properties-migrator")

⚠️ Remova essa dependência após concluir a migração de propriedades. Ela tem impacto de performance e não deve ir para produção.

Jackson 3 (breaking change):

O Spring Boot 4 usa Jackson 3, que muda o groupId e o namespace de pacotes: com.fasterxml.jackson passa a ser tools.jackson. Os imports no código precisam ser atualizados (exceto jackson-annotations, que mantém o groupId com.fasterxml.jackson.core e o pacote com.fasterxml.jackson.annotation).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<!-- Antes (Jackson 2.x) -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.x.x</version>
</dependency>

<!-- Depois (Jackson 3 — gerenciado pelo Spring Boot 4) -->
<!-- Novo groupId tools.jackson; remova a versão e deixe o BOM gerenciar -->
<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>

Hibernate Processor (breaking change):

1
2
3
4
5


// Antes
annotationProcessor("org.hibernate:hibernate-jpamodelgen")

// Depois
annotationProcessor("org.hibernate.orm:hibernate-processor")

Fase 4 — Refatoração de Código

Veja o Detalhamento das Quebras de Compatibilidade para guia completo por área.

Ordem recomendada:

Resolver erros de compilação (APIs removidas)
Atualizar imports e pacotes renomeados
Ajustar configurações de segurança
Revisar queries JPA/JPQL
Atualizar testes

Fase 5 — Validação e Testes

1
2
3
4
5
6
7
8


[ ] Executar bateria completa de testes unitários
[ ] Executar testes de integração com banco de dados real
[ ] Executar testes de contrato (Pact, Spring Cloud Contract)
[ ] Testes de carga/performance (comparar métricas com SB3)
[ ] Validar endpoints de segurança (autenticação + autorização)
[ ] Validar geração de tokens JWT/OAuth2
[ ] Testar em ambiente de staging idêntico à produção
[ ] Verificar logs de inicialização (sem warnings residuais)

Fase 6 — Deploy em Produção

Se for possível adotar uma estratégia de rollback parcial para validar a nova versão, esse é o cenário ideal. Caso contrário, esteja preparado para um rollback rápido se a aplicação apresentar instabilidades inesperadas. Se você ainda não utiliza estratégias de deploy gradual, considere estudar a adoção de Blue-Green deployment ou Canary release em seu pipeline.

5. Detalhamento das Quebras de Compatibilidade

5.1 Undertow removido

O Spring Boot 4 remove o suporte ao servidor Undertow. Aplicações que usam Undertow devem migrar para Tomcat (padrão) ou Jetty.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


<!-- Antes: usando Undertow -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-undertow</artifactId>
</dependency>

<!-- Depois: remova as exclusões e use Tomcat (padrão) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

5.2 `@MockBean` e `@SpyBean` removidos

As anotações @MockBean e @SpyBean do Spring Boot foram removidas e substituídas pelas anotações equivalentes do Spring Framework: @MockitoBean e @MockitoSpyBean. Esta é uma das quebras de compatibilidade mais comuns em suítes de teste existentes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// Antes (Spring Boot 3)
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.boot.test.mock.mockito.SpyBean;

@SpringBootTest
class MeuServicoTest {
    @MockBean
    private RepositorioUsuario repositorio;

    @SpyBean
    private ServicoAuditoria auditoria;
}

// Depois (Spring Boot 4)
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.context.bean.override.mockito.MockitoSpyBean;

@SpringBootTest
class MeuServicoTest {
    @MockitoBean
    private RepositorioUsuario repositorio;

    @MockitoSpyBean
    private ServicoAuditoria auditoria;
}

⚠️ Outras mudanças relacionadas a testes: MockMvc agora exige @AutoConfigureMockMvc e TestRestTemplate exige @AutoConfigureTestRestTemplate para serem auto-configurados.

5.3 Spring Security — Mudança de defaults

O Spring Security 7 alterou comportamentos padrão que podem silenciosamente quebrar APIs REST sem mensagem de erro óbvia.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// Antes (Código legado com métodos deprecados ao longo do SB3) — CSRF desabilitado
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.csrf().disable()
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated());
    return http.build();
}

// Depois (SB4/Security 7) — API atualizada, sem métodos deprecados
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf.disable())
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .sessionManagement(session ->
            session.sessionCreationPolicy(SessionCreationPolicy.STATELESS));
    return http.build();
}

5.4 Jackson 3 — Mudanças de comportamento

Jackson 3 (incluído no Spring Boot 4) traz mudanças que podem afetar serialização/deserialização:

Mudança de namespace: com.fasterxml.jackson → tools.jackson (atualize os imports)
Comportamento padrão mais restritivo com tipos desconhecidos
Mudanças em como null é serializado em coleções
Módulos Jackson que importavam classes internas devem ser atualizados

Anotações renomeadas pelo Spring Boot 4:

Antes	Depois
`@JsonComponent`	`@JacksonComponent`
`@JsonMixin`	`@JacksonMixin`
`Jackson2ObjectMapperBuilderCustomizer`	`JsonMapperBuilderCustomizer`

1
2
3
4
5
6
7
8
9


// Verificar: configurações explícitas do ObjectMapper
@Bean
public ObjectMapper objectMapper() {
    return JsonMapper.builder()
        .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
        .addModule(new JavaTimeModule())
        .build();
}

5.5 Starter renames (módulos renomeados)

Alguns starters foram renomeados na modularização do Boot 4. Consulte a tabela completa de dependências no site oficial.

💡 Para migração gradual, o Spring Boot 4 oferece o starter spring-boot-starter-classic, que reúne dependências antes agrupadas nos starters monolíticos.

5.6 Outras remoções e mudanças relevantes

Além do Undertow, o Spring Boot 4 removeu suporte a:

Spock — descontinuado no 4.0 por falta de suporte ao Groovy 5 (reintegrado no 4.1.0 com Spock 2.4+)
Pulsar Reactive — auto-configuração removida
Spring Session Hazelcast — agora mantido pela equipe do Hazelcast
Spring Session MongoDB — agora mantido pela equipe do MongoDB
Launch scripts de uber jar executável (scripts específicos de Unix)

Mudanças de comportamento padrão a observar:

Liveness e readiness probes passam a vir habilitados por padrão
DevTools Live Reload vem desabilitado por padrão
Spring Retry não é mais gerenciado pelo BOM (declare a versão explicitamente se usar)
Spring Authorization Server agora faz parte do projeto Spring Security; gerencie a versão via a propriedade spring-security.version em vez de spring-authorization-server.version

6. Configuração de Propriedades

Use o spring-boot-properties-migrator para identificar propriedades alteradas automaticamente. Além disso, revise manualmente as configurações críticas.

Como usar o migrator

Adicione a dependência conforme Fase 3
Inicie a aplicação — o migrator imprime no log:
- Propriedades que foram renomeadas (migra em runtime automaticamente)
- Propriedades que foram removidas (você precisa agir manualmente)
Corrija as propriedades no application.properties / application.yml
Remova a dependência do migrator

7. Segurança (Spring Security 7)

7.1 OIDC e OAuth2

O Spring Security 7 atualiza a conformidade OIDC. Se sua aplicação usa autenticação OAuth2/OIDC, revise:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// Configuração de Resource Server (JWT)
@Bean
public SecurityFilterChain resourceServerFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/public/**").permitAll()
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer(oauth2 -> oauth2
            .jwt(jwt -> jwt.decoder(jwtDecoder()))
        );
    return http.build();
}

7.2 CORS

Revise configurações de CORS — os defaults podem ter mudado:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();
    config.setAllowedOrigins(List.of("https://meudominio.com"));
    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
    config.setAllowedHeaders(List.of("*"));
    
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", config);
    return source;
}

8. Persistência (Hibernate 7 + Spring Data 2025.1)

8.1 Hibernate 7 — Principais mudanças

O Hibernate 7 traz melhorias significativas de performance e compatibilidade com threads virtuais (usa ReentrantLock em vez de blocos synchronized).

Semantic Query Model (SQM): O Hibernate 7 otimiza queries automaticamente via SQM. Queries HQL/JPQL existentes devem funcionar, mas edge cases com queries nativas complexas devem ser testados.

Processor renomeado:

1
2
3
4
5
6


// build.gradle
// Antes
annotationProcessor 'org.hibernate:hibernate-jpamodelgen'

// Depois
annotationProcessor 'org.hibernate.orm:hibernate-processor'

8.2 Spring Data 2025.1

O Spring Data 2025.1 muda a geração de queries derivadas:

1
2
3
4
5
6
7


// Queries derivadas agora geram JPQL como string em build-time
// (antes usavam Criteria API em runtime)
// Isso melhora startup e compatibilidade com GraalVM
// Comportamento deve ser transparente, mas teste queries complexas:
interface UserRepository extends JpaRepository<User, Long> {
    List<User> findByNomeAndStatusOrderByCreatedAtDesc(String nome, Status status);
}

Processamento de queries em build-time:

A partir do Spring Data 2025.1, queries são processadas em compile time por padrão. Isso melhora startup e GraalVM native, mas pode revelar erros de JPQL que antes só apareciam em runtime.

9. Testes

9.1 Migração de `@MockBean` / `@SpyBean`

A mudança mais impactante em testes é a remoção de @MockBean e @SpyBean (veja a Seção 5.2). Busque os usos no projeto inteiro antes de atualizar:

1
2


# Buscar usos das anotações removidas
grep -rn "import org.springframework.boot.test.mock.mockito\|@MockBean\|@SpyBean" src/test/

Substitua por @MockitoBean / @MockitoSpyBean (do pacote org.springframework.test.context.bean.override.mockito).

9.2 Mockito puro (sem contexto Spring)

Para testes unitários que não sobem o contexto Spring, o padrão com Mockito permanece inalterado:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// JUnit 5 + Mockito moderno
@ExtendWith(MockitoExtension.class)
class ServicoTest {
    @Mock
    private RepositorioUsuario repositorio;
    
    @InjectMocks
    private ServicoUsuario servico;
    
    @Test
    void deveRetornarUsuario() {
        // ...
    }
}

9.3 Testcontainers (recomendado para integração)

O Spring Boot 4 aprimora a integração com Testcontainers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@SpringBootTest
@Testcontainers
class IntegracaoTest {
    
    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");
    
    // O @ServiceConnection elimina a necessidade do @DynamicPropertySource,
    // configurando automaticamente as propriedades do datasource.
}

10. Build e Ferramentas

10.1 Gradle 9

Se migrar para Gradle 9, atente para:

APIs do Gradle que foram removidas no 9.x
Comportamento mais estrito em cache e task configuration avoidance
Verificação de dependências mais rigorosa

1
2


# Verificar problemas de compatibilidade com Gradle 9
./gradlew help --warning-mode all

10.2 GraalVM Native Image

Para imagens nativas, atualize para GraalVM 25:

1
2
3
4
5
6
7
8


# Com SDKMAN (Usando Java 21, mas Java 25 também é suportado)
sdk install java 21.0.3-graal
sdk use java 21.0.3-graal

# Build nativo
./mvnw -Pnative native:compile
# ou
./gradlew nativeCompile

10.3 Spring Boot Docker Compose

Não esqueça de aproveitar o suporte nativo ao spring-boot-docker-compose (introduzido no SB 3.1). Ao ter um arquivo compose.yaml no projeto, o Spring Boot gerencia automaticamente o ciclo de vida dos containers (como banco de dados e mensageria) durante o desenvolvimento local.

10.4 Spring Boot 4.1

O Spring Boot 4.1 foi lançado em junho de 2026, com melhorias reativas e maior modularização do GraalVM. Ao planejar a migração, considere mirar diretamente na linha 4.1 em vez do 4.0 para já partir da versão mais recente.

11. Conclusão

A migração do Spring Boot 3 para o 4 não é apenas uma atualização técnica — é um passo estratégico para alinhar o projeto às práticas modernas de desenvolvimento.

Com suporte nativo para versionamento de APIs, melhorias de desempenho e maior integração com o ecossistema Jakarta EE, a versão 4 simplifica a manutenção e prepara o caminho para arquiteturas mais resilientes e escaláveis.

Planejar cada etapa, testar incrementalmente e documentar as mudanças são os pilares para uma transição suave. Ao final, o esforço de migração se traduz em um código mais limpo, seguro e preparado para o futuro.

Obrigado por chegar até aqui.