github/awesome-copilot / skills/spring-boot-4-migration
spring-boot-4-migration
VerifiedMigrate a Spring Boot 3.x application to Spring Boot 4.0 (Spring Framework 7, Jackson 3, modular starters, JSpecify). Use only for an explicit Boot 3.x to 4 migration, or to fix build or test failures caused by it, or to review one. Not for 3.x patch bumps or 4.0 to 4.1 upgrades; follow the target Boot version release notes and upgrade guide for those. Covers Maven and Gradle (Kotlin DSL, version catalogs).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| references/01-prerequisites.md | markdown | 1.9 KB |
| references/02-starters-and-removed-features.md | markdown | 9.6 KB |
| references/03-jackson-3.md | markdown | 4.2 KB |
| references/04-core-framework.md | markdown | 4.2 KB |
| references/05-build-and-dependencies.md | markdown | 6.2 KB |
| references/06-configuration-properties.md | markdown | 3.0 KB |
| references/07-web-and-messaging.md | markdown | 7.3 KB |
| references/08-testing.md | markdown | 6.0 KB |
| references/09-actuator-and-observability.md | markdown | 2.7 KB |
| references/10-kotlin-and-java-build-config.md | markdown | 1.3 KB |
| references/11-checklist-pitfalls-resources.md | markdown | 5.9 KB |
references/04-core-framework.md
View on GitHub## Core Framework Changes
### Nullability Annotations: JSpecify
Spring Boot 4.0 adds **JSpecify nullability annotations** throughout the codebase.
**Impact:**
- Kotlin null-safety may flag new warnings/errors
- Null checkers (SpotBugs, NullAway) may report new issues
- **RestClient methods like `body()` are now explicitly marked as nullable** - always check for null or use `Objects.requireNonNull()`
**Migration for Kotlin:**
```kotlin
// Explicit nullable types may be required
fun processUser(id: String?): User? {
val nonNullId = id ?: return null // findById now requires a non-null ID
return userRepository.findById(nonNullId).orElse(null) // Optional<User> -> User?
}
// RestClient body() can return null
val body: String? = restClient.get()
.uri("https://api.example.com/data")
.retrieve()
.body(String::class.java) // Nullable - handle appropriately
if (body != null) {
println(body.length)
}
```
**Actuator endpoint parameters:**
- Cannot use `javax.annotations.NonNull` or `org.springframework.lang.Nullable`
- Use `org.jspecify.annotations.Nullable` instead
**libs.versions.toml:**
```toml
[libraries]
jspecify = { module = "org.jspecify:jspecify", version = "1.0.0" }
```
### Package Relocations
#### BootstrapRegistry
**Old import:**
```kotlin
import org.springframework.boot.BootstrapRegistry
```
**New import:**
```kotlin
import org.springframework.boot.bootstrap.BootstrapRegistry
```
#### EnvironmentPostProcessor
**Old import:**
```kotlin
import org.springframework.boot.env.EnvironmentPostProcessor
```
**New import:**
```kotlin
import org.springframework.boot.EnvironmentPostProcessor
```
**Update `META-INF/spring.factories`:**
```properties
# Old
org.springframework.boot.env.EnvironmentPostProcessor=com.example.MyPostProcessor
# New
org.springframework.boot.EnvironmentPostProcessor=com.example.MyPostProcessor
```
**Note:** Deprecated form still available temporarily but will be removed.
#### Entity Scan
**Old import:**
```kotlin
import org.springframework.boot.autoconfigure.domain.EntityScan
```
**New import:**
```kotlin
import org.springframework.boot.persistence.autoconfigure.EntityScan
```
### Logging Changes
#### Logback Default Charset
Log files now default to **UTF-8** (harmonized with Log4j2):
**logback-spring.xml (explicit configuration):**
```xml
<configuration>
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
<file>app.log</file>
<encoder>
<charset>UTF-8</charset> <!-- Now default -->
<pattern>%d{yyyy-MM-dd HH:mm:ss} - %msg%n</pattern>
</encoder>
</appender>
</configuration>
```
**Console logging:** Uses `Console#charset()` if available (Java 17+), otherwise falls back to UTF-8. This provides better platform compatibility while maintaining consistent encoding.
### DevTools Changes
#### Live Reload Disabled by Default
**application.yml:**
```yaml
spring:
devtools:
livereload:
enabled: true # Must explicitly enable in 4.0
```
**libs.versions.toml:**
```toml
[libraries]
spring-boot-devtools = { module = "org.springframework.boot:spring-boot-devtools", version.ref = "springBoot" }
```
**build.gradle.kts:**
```kotlin
dependencies {
developmentOnly(libs.spring.boot.devtools)
}
```
### PropertyMapper API Behavioral Change
**Breaking change:** No longer calls adapter/predicate methods by default when source is `null`.
**Migration pattern:**
```kotlin
// Old behavior (Spring Boot 3.x)
map.from(source::method).to(destination::method)
// Calls destination.method(null) if source returns null
// New behavior (Spring Boot 4.0)
map.from(source::method).to(destination::method)
// Skips call if source returns null
// Explicit null handling (new)
map.from(source::method).always().to(destination::method)
// Always calls destination.method(value), even if null
```
**Removed method:** `alwaysApplyingNotNull()` - remove this configuration: Boot 4 skips null source values by default. Do not replace it with `always()`, which explicitly passes nulls through; reserve `always()` for mappings that intentionally accept null.
**Migration example:** Review [Spring Boot commit 239f384ac0](https://github.com/spring-projects/spring-boot/commit/239f384ac0893d151b89f204886874c6adb00001) to see how Spring Boot itself adapted to the new API.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |