Spring Boot 4 : A Complete Guide to New Features, Improvements & Why You Should Upgrade

Hello, Spring developers! The wait is over. Spring Boot 4 (released November 2025) is here, and it isn't just a fresh coat of paint it is the start of a new generation for the framework.

If you’ve been building with Spring Boot 3, you might be wondering: "Do I really need to upgrade? What’s the big deal?" The short answer: Yes. Spring Boot 4 is all about modernizing your stack and trimming the fat. It shifts the baseline to the latest industry standards, making your applications lighter, faster, and easier to maintain.

Now first let see what we are going to cover in this blog and then we will deep dive in each topic to fully understand.

What We Will Cover :#

1. Modularity
2. Native API Versioning
3. Null Safety With JSpecify
4. Declarative HTTP Clients
5. Observability
6. Conclusion : future-proof your stack

Now once you have checklist in your mind, it’s time to deep dive…

1. Modularity#

The Problem: In Spring Boot 3, the spring-boot-autoconfigure JAR was like a massive suitcase packed for a 3-month vacation. Even if you were just going for a weekend trip (building a simple microservice), you had to carry that heavy suitcase containing configuration logic for things you’d never use (like LDAP, Neo4j, or Quartz).

The Fix: Spring Boot 4 unpacks the suitcase.

• What changed: The massive auto-configuration module has been split into many smaller, focused modules.
• The Benefit: When you add the spring-boot-starter-webmvc, you only get the configuration for WebMVC. You don't secretly inherit configuration classes for batch jobs or obscure databases.
• Why you care: Your application starts faster, uses less memory, and is much easier to debug because the "classpath noise" is gone.

2. Native API Versioning: No More Hacks#

Finally! One of the features developers have screamed for is now built right into the core.

The Old Way (The Headache) :

• Before Boot 4, if you wanted to version your API, you had to manually hardcode it into every single URL path:
  • @GetMapping("/api/v1/users")
  • @GetMapping("/api/v2/users")
• If you decided to change your versioning strategy from URL paths (e.g., /v1/) to Headers (e.g., X-API-VERSION: 1), you had to rewrite every single controller. It was a nightmare.

The New Way (The Clean Way)

• Spring Boot 4 introduces a version attribute directly in the @RequestMapping and @GetMapping annotations. You simply tag your method with a number, and Spring handles the rest.

A. The Controller Code#

Here is how clean your code looks now. You can mix and match versions easily.

Scenario 1: Different versions in the same class You have a generic "Hello" endpoint, but V1 and V2 behave differently.

@RestController
@RequestMapping("/hello")
public class HelloWorldController {

    // This handles version 1 requests
    @GetMapping(version = "1", produces = MediaType.TEXT_PLAIN_VALUE)
    public String sayHelloV1() {
        return "Hello World (I am V1)";
    }
    
    // This handles version 2 requests
    @GetMapping(version = "2", produces = MediaType.TEXT_PLAIN_VALUE)
    public String sayHelloV2() {
        return "Hi World (I am V2)";
    }
}

Final URLs after this change :

• V1 -> /api/v1/hello
• V2 → /api/v2/hello

Scenario 2: Versioning the whole class If the changes are massive, you might want a totally separate class for V3.

// Every endpoint in this class is automatically Version 3
@RestController
@RequestMapping(path = "/hello", version = "3")
public class HelloWorldV3Controller {
    
    @GetMapping(produces = MediaType.TEXT_PLAIN_VALUE)
    public String sayHello() {
        return "Hey World (I am the shiny new V3)";
    }
}

Final URLs after this change :

• V3 → /api/v3/hello

B. The Configuration (The "Brain")#

The annotations above just say "I am version 1." They don't say how the user asks for version 1. You define that strategy in one single place.

This is where the magic happens. You can choose:

• Path-based (e.g., /v1/hello) - Most popular
• Header-based (e.g., Accept-Version: 1)
• Query Param (e.g., /hello?v=1)

Here is the setup for the popular Path-Based strategy:

@Configuration
public class ApiConfig implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        // Tell Spring to look at the URL path to find the version number
        configurer.usePathSegment(1); 
    }
    
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        // This is the cool part: 
        // It dynamically builds the URL structure for you.
        // "v{version}" becomes "v1", "v2", or "v3" automatically.
        
        configurer.addPathPrefix("/api/v{version}", 
            HandlerTypePredicate.forAnnotation(RestController.class));
    }
}

Here we mentioned this : /api/v{version} so that is why our Apis’s will look like :

• /api/v{version}/endpoints
• example : /api/v1/hello

3. Null Safety With JSpecify#

This is arguably the most "under-the-hood" change, but it will save you the most headaches.

The Old Way (The Guessing Game)#

In previous versions of Spring (and Java in general), "Null Safety" was often just a suggestion.

• You wrote public String getUsername(Long id).
• Does it return null if the user isn't found? Or does it throw an exception?
• You didn't know. You had to read the documentation or, worse, wait for a NullPointerException (NPE) to crash your production app at 3 AM.

The New Way (JSpecify)#

Spring Boot 4 (and Framework 7) has completely adopted JSpecify. Think of JSpecify as a standard "Traffic Light" system that the entire Java ecosystem (Google, JetBrains, Spring) has finally agreed upon.

• @Nullable (Red Light): Stop! This value might be missing. Check it before you use it.
• @NonNull (Green Light): Go! This value is guaranteed to be there. No check needed.
• @NullMarked (The Zone): The most powerful feature. It sets the "default rules" for a whole package.

A. The "Package-Info" Trick (Game Changer)#

Instead of putting @NonNull on every single method, you can declare your entire package as a "Null Safe Zone". Create a file named package-info.java in your package folder:

// src/main/java/com/mycompany/users/package-info.java

@NullMarked // <--- MAGIC HAPPENS HERE
package com.mycompany.users;

import org.jspecify.annotations.NullMarked;

What this does: It tells the compiler (and your IDE), "Assume EVERYTHING in this package is Non-Null unless I explicitly say otherwise."

B. The Service Code#

Now, look how clean your service code becomes. You only tag the exceptions to the rule.

package com.mycompany.users;

import org.jspecify.annotations.Nullable;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    // 1. No annotation needed! 
    // Because of @NullMarked, Spring knows this CANNOT be null.
    public String formatUsername(String rawName) {
        return rawName.trim().toUpperCase();
    }

    // 2. Explicitly allowing Nulls
    // We use @Nullable to warn the caller: "This might be empty!"
    @Nullable
    public User findUserById(String id) {
        // ... database logic that might return nothing ...
        return null; 
    }
}

CC. The "Copilot" in Your IDE#

Because Spring Boot 4 uses these standard annotations, your IDE (like IntelliJ IDEA 2025.3+) becomes your safety cop.

• Scenario: You try to pass a null value to formatUsername(null).
• Old Result: App crashes at runtime.
• New Result: Your IDE highlights the code in RED while you are typing. It won't even let you compile it without a warning.

Note: To use these annotations in your own classes, you should add the JSpecify library to your build (it's super lightweight):

Maven:

<dependency>
    <groupId>org.jspecify</groupId>
    <artifactId>jspecify</artifactId>
    <version>1.0.0</version>
</dependency>

4. Declarative HTTP Clients: The "Feign Killer”#

This feature is the biggest "quality of life" upgrade in Spring Boot 4. It allows you to talk to other services just by writing an Interface, with zero third-party dependencies.

The Old Way (The Heavy Way)#

For years, we had two bad choices:

1. RestTemplate: You had to write verbose, ugly code for every single request (restTemplate.exchange(url, HttpMethod.GET, entity, class)).
2. Spring Cloud Feign: This was cleaner, but it required adding a massive external library (spring-cloud-starter-openfeign) that often caused version conflicts.

The New Way (Native & Clean)#

Spring Boot 4 gives you the cleanliness of Feign but uses the native Spring Framework engine underneath. No extra jars. No version conflicts.

A. The Interface (The "Contract")#

You simply define what you want to call, not how.

package com.mycompany.clients;

import org.springframework.web.service.annotation.GetExchange;
import org.springframework.web.service.annotation.HttpExchange;

// 1. Base URL logic goes here
@HttpExchange("/users") 
public interface UserClient {

    // 2. This looks just like a Controller!
    @GetExchange("/{id}")
    User getUserById(@PathVariable("id") String id);

    @PostExchange
    void createUser(@RequestBody User user);
}

Look at that code. It’s clean. It reads like English.

B. The Setup (The "Factory")#

Since this is just an interface, Spring needs to know how to build the actual object that does the work. We use the HttpServiceProxyFactory.

Put this in your AppConfig.java:

@Bean
public UserClient userClient(RestClient.Builder builder) {
    // 1. Create the underlying engine (RestClient is the new standard)
    RestClient restClient = builder.baseUrl("<https://api.example.com>").build();

    // 2. Create the "Magic Factory" that turns your Interface into code
    HttpServiceProxyFactory factory = HttpServiceProxyFactory
        .builderFor(RestClientAdapter.create(restClient))
        .build();

    // 3. Spit out the actual client bean
    return factory.createClient(UserClient.class);
}

C. The Usage#

Now, inject it anywhere. It feels just like calling a local method.

@Service
public class UserService {
    
    private final UserClient userClient;

    public UserService(UserClient userClient) {
        this.userClient = userClient;
    }

    public void doSomething(String id) {
        // No URLs, no HTTP entities, just method calls
        User u = userClient.getUserById(id); 
    }
}

5. Observability : The "High-Def" Dashboard#

The Old Way (The "Blind Spot")#

In the past, checking if your HTTPS certificate was about to expire required external tools, manual calendar reminders, or a 3 AM panic when the site went down. You also had to manually stitch together logs and metrics to figure out why a request was slow.

The New Way (Built-in Intelligence)#

Spring Boot 4 upgrades to Micrometer 2.0 and Actuator 4. The standout feature here isn't just codeit's the native SSL Health Monitoring.

A. SSL Certificate Monitoring (The "Lifesaver")#

Spring Boot now automatically watches your SSL certificates. If a certificate is close to expiring, the application's "Health" status goes DOWN (or warns you), so your load balancer can react before users get a security warning.

The Code: You don't write Java code for this. You just configure an "SSL Bundle" in your properties. Spring Actuator takes care of the rest.

application.properties:

# 1. Define the SSL Bundle
spring.ssl.bundle.jks.my-server-cert.key.alias=server
spring.ssl.bundle.jks.my-server-cert.keystore.location=classpath:server.p12
spring.ssl.bundle.jks.my-server-cert.keystore.password=secret

# 2. Enable the "Health" Watchdog
management.endpoint.health.show-details=always
management.health.ssl.enabled=true

The Result (JSON): When you hit /actuator/health, you now get this rich data automatically:

"ssl": {
    "status": "UP",
    "details": {
        "validSSL": [
            {
                "bundle": "my-server-cert",
                "expiresIn": "59 days", 
                "expiryDate": "2025-12-31T12:00:00Z"
            }
        ]
    }
}

If that expiresIn drops below a threshold (default is usually 14-30 days), your monitoring system gets an alert.

B. The "@Observed" Annotation#

If you want to track how long a specific method takes and how often it fails, you no longer need to write complex interceptors.

The Code: Just add @Observed.

@Service
public class PaymentService {

    // Spring creates a Timer + Counter + Trace automatically for this method
    @Observed(name = "payment.process")
    public PaymentResult processPayment(String orderId) {
        // ... complex logic ...
        return new PaymentResult("SUCCESS");
    }
}

Conclusion :#

Spring Boot 4 isn’t just an upgrade it is a mindset shift for building modern Java applications.

The Spring team didn’t just add shiny features; they redesigned the foundation so your apps can be lighter, more predictable, easier to scale, and safer by design.