Migrating from Spring Boot to Micronaut: Step-by-Step Guide

What is Micronaut and Why Migrate from Spring Boot?

Spring Boot has long been the dominant framework for building JVM-based applications, particularly microservices. However, as cloud-native and serverless architectures demand faster startup times, lower memory consumption, and sub-millisecond cold starts, the traditional runtime-based dependency injection and reflection-heavy approach of Spring Boot shows its limits. Micronaut is a modern, JVM-based framework designed from the ground up for cloud-native environments. It uses compile-time dependency injection, ahead-of-time (AOT) compilation, and a reflection-free design to deliver incredibly fast startup and low memory overhead, while still providing a familiar development model.

Migrating from Spring Boot to Micronaut can dramatically reduce your application’s footprint, enable effortless GraalVM native image compilation, and improve deployment density in containerized environments like Kubernetes. The frameworks share many conceptual similarities, which makes the transition manageable if you follow a systematic, step-by-step approach. This tutorial will walk you through a complete migration of a typical Spring Boot REST service (with JPA and dependency injection) to Micronaut, covering configuration, controllers, services, data access, exception handling, and testing.

Prerequisites

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Working knowledge of Spring Boot (controllers, services, JPA repositories)
Java 11+ installed (Micronaut supports Java 8 but Java 11 or 17 is recommended)
A build tool – either Gradle or Maven. Examples use Gradle.
An existing Spring Boot application you want to migrate (or follow along with a sample)

Step-by-Step Migration Guide

1. Project Setup and Dependencies

The first step is to replace Spring Boot starters with Micronaut’s equivalents. Micronaut provides a set of starters that bundle the necessary dependencies. You can either create a fresh Micronaut project using the mn CLI and move your code, or manually adjust the build file. Below is a Gradle comparison.

Spring Boot (build.gradle)

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

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

Micronaut (build.gradle)

plugins {
    id 'io.micronaut.application' version '3.7.7'
    id 'io.micronaut.aot' version '3.7.7'
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.micronaut:micronaut-http-server-netty'
    implementation 'io.micronaut:micronaut-http-client'
    implementation 'io.micronaut.data:micronaut-data-hibernate-jpa'
    implementation 'io.micronaut.sql:micronaut-jdbc-hikari'
    runtimeOnly 'com.h2database:h2'
    testImplementation 'io.micronaut.test:micronaut-test-junit5'
}

micronaut {
    runtime 'netty'
    testRuntime 'junit5'
}

If you use Maven, replace spring-boot-starter-web with micronaut-http-server-netty and spring-boot-starter-data-jpa with micronaut-data-hibernate-jpa. The Micronaut parent POM or BOM can simplify version management.

2. Migrating Configuration (application.yml)

Micronaut uses the same application.yml (or application.properties) file for configuration, but many property names differ. The server port and datasource configuration need to be updated.

Spring Boot (application.yml)

server:
  port: 8080

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driverClassName: org.h2.Driver
    username: sa
    password: ""
  jpa:
    hibernate:
      ddl-auto: update

Micronaut (application.yml)

micronaut:
  server:
    port: 8080

datasources:
  default:
    url: jdbc:h2:mem:testdb
    driverClassName: org.h2.Driver
    username: sa
    password: ""
    dialect: H2

jpa:
  default:
    properties:
      hibernate:
        hbm2ddl:
          auto: update

Note that the micronaut prefix replaces server, and datasource definitions are under datasources. The Hibernate dialect and DDL settings are also structured differently.

3. Dependency Injection Annotations

Micronaut performs dependency injection at compile time, eliminating reflection and proxy-based approaches. This means annotations like @Autowired are replaced by @Inject or simply removed if you use constructor injection (which Micronaut automatically detects). Stereotype annotations also change.

@Service → @Singleton (or @Prototype for non-singleton beans)
@Component → @Singleton
@Repository → handled by Micronaut Data repository interfaces (see step 6)
@Autowired → @Inject (or omit with constructor injection)

Example service migration:

Spring Boot Service

@Service
public class UserService {
    private final UserRepository userRepository;

    @Autowired
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public List findAll() {
        return userRepository.findAll();
    }
}

Micronaut Service

@Singleton
public class UserService {
    private final UserRepository userRepository;

    // Constructor injection automatically recognized
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public List findAll() {
        return userRepository.findAll();
    }
}

4. Controllers and Routing

Micronaut controllers are very similar to Spring’s @RestController, but the annotations are slightly different. The @Controller annotation is used instead of @RestController. Path mapping uses @Get, @Post, @Put, @Delete instead of @RequestMapping with method attributes. Request body binding uses @Body.

Spring Boot Controller

@RestController
@RequestMapping("/users")
public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public List getAllUsers() {
        return userService.findAll();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.save(user);
    }
}

Micronaut Controller

@Controller("/users")
public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @Get
    public List getAllUsers() {
        return userService.findAll();
    }

    @Post
    public User createUser(@Body User user) {
        return userService.save(user);
    }
}

Micronaut also supports reactive return types like Mono or Single if you prefer reactive programming.

5. Service Layer and Repository

The service layer remains largely unchanged except for the stereotype annotation and constructor injection. The real shift happens in the data access layer.

6. Data Access and JPA Repositories

Micronaut Data provides a similar repository abstraction to Spring Data JPA, but it uses its own annotations and interfaces. You replace CrudRepository / JpaRepository with Micronaut’s CrudRepository (from io.micronaut.data.repository) and annotate with @Repository. Query methods work the same way, using method naming conventions or @Query.

Spring Boot Repository

@Repository
public interface UserRepository extends JpaRepository {
    Optional findByEmail(String email);
}

Micronaut Repository

@Repository
public interface UserRepository extends CrudRepository {
    Optional findByEmail(String email);
}

Ensure you import io.micronaut.data.repository.CrudRepository. Micronaut Data supports compile-time generation of the repository implementation, avoiding runtime proxies. For JPA, the entity class remains the same, annotated with javax.persistence.Entity or jakarta.persistence.Entity depending on version. You may need to add a @JpaRepository annotation on the interface if you want explicit JPA support.

Entity example (unchanged)

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // getters and setters
}

7. Exception Handling

In Spring Boot, global exception handling is done with @ControllerAdvice and @ExceptionHandler. Micronaut offers @ErrorHandler and @GlobalBean to achieve the same. Alternatively, you can use an ExceptionHandler that implements ExceptionHandler interface.

Spring Boot Exception Handler

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity handleNotFound(UserNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                             .body(new ErrorResponse("User not found"));
    }
}

Micronaut Global Exception Handler

@GlobalBean
@ErrorHandler
public class GlobalExceptionHandler {
    @ExceptionHandler(UserNotFoundException.class)
    public HttpResponse handleNotFound(UserNotFoundException ex) {
        return HttpResponse.status(HttpStatus.NOT_FOUND)
                           .body(new ErrorResponse("User not found"));
    }
}

Micronaut’s HttpResponse replaces Spring’s ResponseEntity. The @ErrorHandler annotation can also be placed on a method inside a controller for local handling.

8. Testing

Micronaut provides its own testing framework that integrates with JUnit 5 and Mockito. Replace @SpringBootTest with @MicronautTest. Dependency injection works out of the box, and you can mock beans using @MockBean or @Replaces.

Spring Boot Test

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserControllerTest {
    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void testGetUsers() {
        ResponseEntity> response = restTemplate.exchange(
            "/users", HttpMethod.GET, null, new ParameterizedTypeReference>() {});
        assertEquals(HttpStatus.OK, response.getStatusCode());
    }
}

Micronaut Test

@MicronautTest
class UserControllerTest {
    @Inject
    private HttpClient httpClient;

    @Test
    void testGetUsers() {
        List users = httpClient.toBlocking().retrieve(
            "/users", Argument.listOf(User.class));
        assertFalse(users.isEmpty());
    }
}

Micronaut’s HttpClient is a built-in reactive HTTP client. The toBlocking() method allows blocking assertions in tests.

Best Practices for a Smooth Migration

Leverage compile-time DI: Avoid reflection by using @Singleton, @Inject, and constructor injection. Micronaut will catch missing beans at compile time, reducing runtime surprises.
Migrate incrementally: Start with a single module or service, perhaps a simple REST endpoint, and gradually move others. Run tests after each step.
Use Micronaut’s CLI or Launch: Generate a fresh Micronaut project from micronaut.io/launch to see the expected structure and dependencies, then copy your business logic.
Keep configuration externalized: Use environment variables or configuration files to handle differences between Spring and Micronaut property keys during transition.
Adopt Micronaut Data for repositories: It provides compile-time validation of queries and eliminates unnecessary runtime overhead.
Revisit exception handling: Micronaut’s error handling model is different; test thoroughly to ensure proper HTTP status codes and response bodies.
Embrace GraalVM native images: Once migrated, you can compile to a native binary with minimal changes, achieving sub-millisecond startup and very low memory footprint. Micronaut’s AOT support makes this straightforward.
Use Micronaut’s built-in HTTP client: Replace RestTemplate or WebClient with Micronaut’s declarative HTTP client (@Client annotation) for better performance and compile-time checks.

Conclusion

Migrating from Spring Boot to Micronaut is a worthwhile investment for teams aiming to optimize cloud-native workloads. The frameworks share many patterns, making the transition a matter of updating annotations, configuration keys, and dependencies rather than rewriting business logic. By following the steps outlined in this guide—replacing starters, adjusting configuration, migrating controllers, services, repositories, exception handling, and tests—you can achieve a fully functional Micronaut application that starts in milliseconds, consumes a fraction of the memory, and is ready for GraalVM native compilation. The journey requires attention to detail, but the resulting performance gains and cloud-native capabilities provide a strong return on that effort.