Springboot-4-Migration

# Spring Boot 3.x to 4.0 Migration Guide

Project Context

This guide provides comprehensive GitHub Copilot instructions for upgrading Spring Boot projects from version 3.x to 4.0, with emphasis on Gradle Kotlin DSL, version catalogs (`libs.versions.toml`), and Kotlin-specific considerations.

**Key architectural changes in Spring Boot 4.0:**

- Modular dependency structure with focused, smaller modules

- Spring Framework 7.x required

- Jakarta EE 11 (Servlet 6.1 baseline)

- Jackson 3.x migration (package namespace changes)

- Kotlin 2.2+ requirement

- Comprehensive property reorganization

System Requirements

Minimum Versions

- **Java**: 17+ (prefer latest LTS: Java 21 or 25)

- **Kotlin**: 2.2.0 or later

- **Spring Framework**: 7.x (managed by Spring Boot 4.0)

- **Jakarta EE**: 11 (Servlet 6.1 baseline)

- **GraalVM** (for native images): 25+

- **Gradle**: 8.5+ (for Kotlin DSL and version catalog support)

- **Gradle CycloneDX Plugin**: 3.0.0+

Verify Compatibility

# Check current versions
./gradlew --version
./gradlew dependencies --configuration runtimeClasspath

Pre-Migration Steps

1. Upgrade to Latest Spring Boot 3.5.x

Before migrating to 4.0, upgrade to the latest 3.5.x release:

// libs.versions.toml
[versions]
springBoot = "3.5.6" # Latest 3.x before migrating to 4.0

2. Clean Up Deprecations

Remove all deprecated API usage from Spring Boot 3.x. These will be compilation errors in 4.0:

# Build and review warnings
./gradlew clean build --warning-mode all

3. Review Dependency Changes

Compare your dependencies against:

- [Spring Boot 3.5.x Dependency Versions](https://docs.spring.io/spring-boot/3.5/appendix/dependency-versions/coordinates.html)

- [Spring Boot 4.0.x Dependency Versions](https://docs.spring.io/spring-boot/4.0/appendix/dependency-versions/coordinates.html)

Module Restructuring and Starter Changes

Critical: Modular Architecture

Spring Boot 4.0 introduces **smaller, focused modules** replacing large monolithic jars. This requires dependency updates in most projects.

**Important for Library Authors:** Due to the modularization effort and package reorganization, **supporting both Spring Boot 3 and Spring Boot 4 within the same artifact is strongly discouraged**. Library authors should publish separate artifacts for each major version to avoid runtime conflicts and ensure clean dependency management.

Migration Strategy: Choose One Approach

#### Option 1: Technology-Specific Starters (Recommended for Production)

Most technologies covered by Spring Boot now have **dedicated test starter companions**. This provides fine-grained control.

**Complete Starter Reference:** For comprehensive tables of all available starters (Core, Web, Database, Spring Data, Messaging, Security, Templating, Production-Ready, etc.) and their test companions, refer to the [official Spring Boot 4.0 Migration Guide](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide#starters).

**libs.versions.toml:**

[versions]
springBoot = "4.0.0"

[libraries]
# Core starters with dedicated test modules
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-webmvc", version.ref = "springBoot" }
spring-boot-starter-webmvc-test = { module = "org.springframework.boot:spring-boot-starter-webmvc-test", version.ref = "springBoot" }

spring-boot-starter-data-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa", version.ref = "springBoot" }
spring-boot-starter-data-jpa-test = { module = "org.springframework.boot:spring-boot-starter-data-jpa-test", version.ref = "springBoot" }

spring-boot-starter-security = { module = "org.springframework.boot:spring-boot-starter-security", version.ref = "springBoot" }
spring-boot-starter-security-test = { module = "org.springframework.boot:spring-boot-starter-security-test", version.ref = "springBoot" }

**build.gradle.kts:**

dependencies {