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/07-web-and-messaging.md
View on GitHub## Web Framework Changes
### Static Resource Locations
`PathRequest#toStaticResources()` now includes `/fonts/**` by default.
**Security configuration (exclude fonts if needed):**
```kotlin
import org.springframework.boot.security.autoconfigure.web.StaticResourceLocation
import org.springframework.boot.security.autoconfigure.web.servlet.PathRequest
@Configuration
@EnableWebSecurity
class SecurityConfig {
@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
http {
authorizeHttpRequests {
// Exclude fonts if needed
authorize(PathRequest.toStaticResources()
.atCommonLocations()
.excluding(StaticResourceLocation.FONTS), permitAll)
authorize(anyRequest, authenticated)
}
}
return http.build()
}
}
```
### HttpMessageConverters Deprecation
`HttpMessageConverters` deprecated due to framework improvements (conflated client/server converters).
**Migration:**
```kotlin
// Old (Spring Boot 3.x)
import org.springframework.boot.autoconfigure.http.HttpMessageConverters
import org.springframework.context.annotation.Bean
@Configuration
class WebConfig {
@Bean
fun customConverters(): HttpMessageConverters {
return HttpMessageConverters(MyCustomConverter())
}
}
// New (Spring Boot 4.0)
import org.springframework.boot.http.converter.autoconfigure.ClientHttpMessageConvertersCustomizer
import org.springframework.boot.http.converter.autoconfigure.ServerHttpMessageConvertersCustomizer
@Configuration
class WebConfig {
// Separate client and server converters
@Bean
fun clientConvertersCustomizer(): ClientHttpMessageConvertersCustomizer {
return ClientHttpMessageConvertersCustomizer { builder ->
builder.addCustomConverter(MyCustomClientConverter())
}
}
@Bean
fun serverConvertersCustomizer(): ServerHttpMessageConvertersCustomizer {
return ServerHttpMessageConvertersCustomizer { builder ->
builder.addCustomConverter(MyCustomServerConverter())
}
}
}
```
### Trailing Slash URL Matching Removed
`PathMatchConfigurer#setUseTrailingSlashMatch(true)` is **removed** in Spring Framework 7 / Spring Boot 4.
There is no replacement configuration knob — `/foo` and `/foo/` are no longer treated as the same route.
**Migration:** register Spring Framework's `UrlHandlerFilter` as a
`FilterRegistrationBean` so it runs ahead of the security chain. `wrapRequest()` makes it forward transparently (no
redirect), preserving the old behavior end-to-end:
```java
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.web.filter.UrlHandlerFilter;
@Configuration
class WebConfig {
// After ForwardedHeaderFilter, before ServletRequestPathFilter and security filters.
private static final int BEFORE_SECURITY_FILTER_ORDER = -101;
@Bean
FilterRegistrationBean<UrlHandlerFilter> trailingSlashHandlerFilter() {
UrlHandlerFilter filter = UrlHandlerFilter.trailingSlashHandler("/**").wrapRequest().build();
FilterRegistrationBean<UrlHandlerFilter> registration = new FilterRegistrationBean<>(filter);
registration.setOrder(BEFORE_SECURITY_FILTER_ORDER);
return registration;
}
}
```
### Jersey and Jackson 3 Incompatibility
**Jersey 4.0 limitation:** Spring Boot 4.0 supports Jersey 4.0, which **does not yet support Jackson 3**.
**Solution:** Use `spring-boot-jackson2` compatibility module **either in place of or alongside** `spring-boot-jackson`:
**libs.versions.toml:**
```toml
[libraries]
spring-boot-starter-jersey = { module = "org.springframework.boot:spring-boot-starter-jersey", version.ref = "springBoot" }
spring-boot-jackson2 = { module = "org.springframework.boot:spring-boot-jackson2", version.ref = "springBoot" }
# Optional: Keep Jackson 3 for non-Jersey parts of application
spring-boot-jackson = { module = "org.springframework.boot:spring-boot-jackson", version.ref = "springBoot" }
```
**build.gradle.kts:**
```kotlin
dependencies {
implementation(libs.spring.boot.starter.jersey)
implementation(libs.spring.boot.jackson2) // Required for Jersey JSON processing
// Optional: Use Jackson 3 elsewhere in application
// implementation(libs.spring.boot.jackson)
}
```
**Note:** If using only Jersey in your application, you can replace Jackson 3 entirely with Jackson 2 compatibility module.
## Messaging Framework Changes
### Kafka Streams Customizer Replacement
**Deprecated `StreamsBuilderFactoryBeanCustomizer` → `StreamsBuilderFactoryBeanConfigurer`:**
```kotlin
// Old (Spring Boot 3.x)
import org.springframework.boot.autoconfigure.kafka.StreamsBuilderFactoryBeanCustomizer
@Configuration
class KafkaStreamsConfig {
@Bean
fun streamsCustomizer(): StreamsBuilderFactoryBeanCustomizer {
return StreamsBuilderFactoryBeanCustomizer { factoryBean ->
factoryBean.setKafkaStreamsCustomizer { streams ->
// Custom config
}
}
}
}
// New (Spring Boot 4.0)
import org.springframework.kafka.config.StreamsBuilderFactoryBeanConfigurer
@Configuration
class KafkaStreamsConfig {
@Bean
fun streamsConfigurer(): StreamsBuilderFactoryBeanConfigurer {
return StreamsBuilderFactoryBeanConfigurer { factoryBean ->
factoryBean.setKafkaStreamsCustomizer { streams ->
// Custom config
}
}
}
}
```
**Note:** New configurer implements `Ordered` with default value `0`.
### Kafka Retry Property Change
**application.yml migration:**
```yaml
# Old (Spring Boot 3.x)
spring:
kafka:
retry:
topic:
backoff:
random: true
# New (Spring Boot 4.0)
spring:
kafka:
retry:
topic:
backoff:
jitter: 0.5 # More flexible than boolean
```
### RabbitMQ Retry Customizer Split
**Spring AMQP moved from Spring Retry → Spring Framework core retry**, with customizer split:
```kotlin
// Old (Spring Boot 3.x)
import org.springframework.boot.autoconfigure.amqp.RabbitRetryTemplateCustomizer
@Configuration
class RabbitConfig {
@Bean
fun retryCustomizer(): RabbitRetryTemplateCustomizer {
return RabbitRetryTemplateCustomizer { template ->
// Applies to both RabbitTemplate and listeners
}
}
}
// New (Spring Boot 4.0)
import org.springframework.boot.amqp.autoconfigure.RabbitTemplateRetrySettingsCustomizer
import org.springframework.boot.amqp.autoconfigure.RabbitListenerRetrySettingsCustomizer
@Configuration
class RabbitConfig {
// For RabbitTemplate operations
@Bean
fun templateRetryCustomizer(): RabbitTemplateRetrySettingsCustomizer {
return RabbitTemplateRetrySettingsCustomizer { settings ->
settings.retryPolicySettings.maxRetries = 5L
}
}
// For message listeners
@Bean
fun listenerRetryCustomizer(): RabbitListenerRetrySettingsCustomizer {
return RabbitListenerRetrySettingsCustomizer { settings ->
settings.retryPolicySettings.maxRetries = 3L
}
}
}
```
These customizers exist since Spring Boot 4.0.0 (`maxRetries` counts retries after the first attempt, unlike the old `maxAttempts`). In Spring Boot 4.2+ they moved to the `org.springframework.boot.rabbitmq.autoconfigure` package; adjust the imports when upgrading to 4.2.
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: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | 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: 197k | Updated | Claude CodeCodex | Verified | Install |