Table of Contents

Run a Spring Boot application as a Micronaut application

Write an application using Spring Boot annotations and compute it into a Micronaut application at compilation time.

Authors: Sergio del Amo

Micronaut Version: 4.4.0

1. Getting Started

In this guide, we will create a Micronaut application written in Java.

You will write an application that includes no dependencies on Micronaut itself in the source code (only Spring dependencies) but is computed into a Micronaut application at compilation time.

2. What you will need

To complete this guide, you will need the following:

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=yaml,spring-web,spring-boot,views-thymeleaf,validation \
    --build=maven \
    --lang=java \
    --test=junit
If you don’t specify the --build argument, Gradle is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add yaml, spring-web, spring-boot, views-thymeleaf, and validation features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features and apply those changes to your application.

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Dependencies

Micronaut for Spring allows you to use traditional Spring annotations, which are mapped to Micronaut annotations at compilation time. This allows you to write an application that can be imported to another Spring or Micronaut application without change.

To use Spring Framework Annotations, write Spring MVC controllers, and support Spring Boot features, add both features spring-web and spring-boot when you create the application with Micronaut CLI and/or Micronaut Launch. These features include the following dependencies:

pom.xml
<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-annotation</artifactId>
</path>
<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-web-annotation</artifactId>
</path>
<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-boot-annotation</artifactId>
</path>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-web</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-boot</artifactId>
    <scope>runtime</scope>
</dependency>

4.2. Application

Create an Application class:

src/main/java/example/micronaut/Application.java
package example.micronaut;

import io.micronaut.runtime.Micronaut;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication (1)
public class Application {

    public static void main(String... args) {
        Micronaut.run(Application.class);
    }
}
1 In a Spring Boot application, the @SpringBootApplication enables Spring Boot’s auto-configuration mechanism, enables @Component scan on the package where the application is located, and allows the application to register extra beans in the context or import additional configuration classes.

4.3. @ConfigurationProperties

src/main/java/example/micronaut/GreetingConfiguration.java
package example.micronaut;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component (1)
@ConfigurationProperties("greeting") (2)
public class GreetingConfiguration {

    private String template = "Hello, %s!";

    public String getTemplate() {
        return template;
    }

    public void setTemplate(String template) {
        this.template = template;
    }
}
1 org.springframework.stereotype.Component maps to io.micronaut.context.annotation.Bean at compilation time. Spring will scan the application for classes annotated with @Component. It instantiates those classes and fulfills the injection points.
2 org.springframework.boot.context.properties.ConfigurationProperties maps to io.micronaut.context.annotation.ConfigurationProperties at compilation time.
The @Prototype annotation is a synonym for @Bean because the default scope in a Micronaut application is prototype.

4.4. Configuration

Add some configuration which will populate this GreetingConfiguration:

Since Micronaut Framework 4.0, to use YAML configuration, you have to add the YAML dependency.
src/main/resources/application.yml
greeting:
  template: "Hola, %s!"

4.5. POJO

Create a POJO that uses Jackson Annotations.

src/main/java/example/micronaut/Greeting.java
package example.micronaut;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.micronaut.serde.annotation.Serdeable;

@Serdeable
public class Greeting {

    private final long id;
    private final String content;

    @JsonCreator
    public Greeting(@JsonProperty("id") long id, @JsonProperty("content") String content) {
        this.id = id;
        this.content = content;
    }

    public long getId() {
        return id;
    }

    public String getContent() {
        return content;
    }
}

4.6. Service

Add a service that showcases configuration injection and validation.

src/main/java/example/micronaut/GreetingService.java
package example.micronaut;

import org.springframework.stereotype.Service;
import org.springframework.validation.annotation.Validated;

import jakarta.validation.constraints.Pattern;
import java.util.Optional;
import java.util.concurrent.atomic.AtomicLong;
import java.util.concurrent.atomic.AtomicReference;

@Service (1)
@Validated (2)
public class GreetingService {

    private final AtomicLong counter = new AtomicLong();

    private final GreetingConfiguration greetingConfiguration;

    private final AtomicReference<Greeting> lastGreeting = new AtomicReference<>();

    public GreetingService(GreetingConfiguration greetingConfiguration) { (3)
        this.greetingConfiguration = greetingConfiguration;
    }

    public Greeting greeting(@Pattern(regexp = "\\D+") String name) { (4)
        final Greeting greeting = new Greeting(counter.incrementAndGet(),
                String.format(greetingConfiguration.getTemplate(), name));
        lastGreeting.set(greeting);
        return greeting;
    }

    public Optional<Greeting> getLastGreeting() {
        return Optional.ofNullable(lastGreeting.get());
    }
}
1 org.springframework.stereotype.Service maps to io.micronaut.context.annotation.Bean at compilation time. A Spring @Service indicates that they hold business logic.
2 The @Validated annotation tells Spring to validate parameters passed into a method of the annotated class.
3 Use constructor injection to inject a bean of type GreetingConfiguration.
4 Use jakarta.validation.constraints Constraints to ensure the data matches your expectations.

4.6.1. Service Test

Create a test to verify validation works as expected.

src/test/java/example/micronaut/GreetingServiceTest.java
package example.micronaut;

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.function.Executable;

import jakarta.validation.ConstraintViolationException;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertThrows;

@MicronautTest(startApplication = false) (1)
class GreetingServiceTest {

    @Inject
    GreetingService greetingService;

    @Test
    void regexValidationNonDigitsWork() {
        assertDoesNotThrow(() -> greetingService.greeting("foo"));
        Executable e = () -> greetingService.greeting("12foo");
        assertThrows(ConstraintViolationException.class, e);
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context. This test does not need the embedded server. Set startApplication to false to avoid starting it.

4.7. @RestController

Micronaut Spring only supports @RestController semantics. A @RestController request handling method serializes return objects into an HTTP response. Create a controller that uses the following Spring annotations.

src/main/java/example/micronaut/GreetingController.java
package example.micronaut;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.ui.Model;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;

import jakarta.validation.constraints.Pattern;

@RestController (1)
public class GreetingController {

    private final GreetingService greetingService;

    public GreetingController(GreetingService greetingService) { (2)
        this.greetingService = greetingService;
    }

    @GetMapping("/greeting") (3)
    public Greeting greeting(
            @RequestParam(value="name", defaultValue="World") @Pattern(regexp = "\\D+") String name) {  (4)
        return greetingService.greeting(name);
    }

    @PostMapping("/greeting") (5)
    public Greeting greetingByPost(@RequestBody Greeting greeting) { (6)
        return greetingService.greeting(greeting.getContent());
    }

    @DeleteMapping("/greeting") (7)
    public ResponseEntity<?> deleteGreeting() { (8)
        MultiValueMap<String, String> headers = new LinkedMultiValueMap<>();
        headers.add("Foo", "Bar");
        return new ResponseEntity<>(headers, HttpStatus.NO_CONTENT); (8)
    }

    @GetMapping("/greeting-status") (3)
    @ResponseStatus(code = HttpStatus.CREATED) (9)
    public Greeting greetingWithStatus(
            @RequestParam(value="name", defaultValue="World") @Pattern(regexp = "\\D+") String name) {
        return greetingService.greeting(name);
    }
}
1 org.springframework.web.bind.annotation.RestController.html maps to io.micronaut.http.annotation.Controller at compilation time.
2 Use constructor injection to inject a bean of type GreetingService.
3 org.springframework.web.bind.annotation.GetMapping maps to io.micronaut.http.annotation.Get at compilation time.
4 org.springframework.web.bind.annotation.RequestParam maps to io.micronaut.http.annotation.QueryValue at compilation time.
5 org.springframework.web.bind.annotation.PostMapping maps to io.micronaut.http.annotation.Post at compilation time.
6 org.springframework.web.bind.annotation.RequestBody maps to io.micronaut.http.annotation.Body at compilation time.
7 org.springframework.web.bind.annotation.DeleteMapping maps to io.micronaut.http.annotation.Delete at compilation time.
8 Special support is provided by the micronaut-spring-web dependency to allow the application to return a ResponseEntity.
9 org.springframework.web.bind.annotation.ResponseStatus maps to io.micronaut.http.annotation.Status at compilation time.

4.8. Tests

4.8.1. Declarative HTTP Client

You can use Spring annotations with a declarative Micronaut HTTP Client.

src/test/java/example/micronaut/GreetingClient.java
package example.micronaut;

import io.micronaut.http.client.annotation.Client;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;

import io.micronaut.core.annotation.Nullable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;

@Client("/") (1)
public interface GreetingClient {

    @GetMapping("/greeting{?name}") (2)
    Greeting greet(@Nullable String name);

    @PostMapping("/greeting") (3)
    Greeting greetByPost(@RequestBody Greeting greeting); (4)

    @DeleteMapping("/greeting") (5)
    HttpStatus deletePost();

    @GetMapping("/nested/greeting{?name}") (2)
    Greeting nestedGreet(@RequestParam @Nullable String name); (6)

    @GetMapping("/greeting-status{?name}") (2)
    ResponseEntity<Greeting> greetWithStatus(@RequestParam @Nullable String name); (6)
}
1 Use @Client("/") to declare a declarative HTTP Client pointing to the application.
2 org.springframework.web.bind.annotation.GetMapping maps to io.micronaut.http.annotation.Get at compilation time.
3 org.springframework.web.bind.annotation.PostMapping maps to io.micronaut.http.annotation.Post at compilation time.
4 org.springframework.web.bind.annotation.RequestBody maps to io.micronaut.http.annotation.Body at compilation time.
5 org.springframework.web.bind.annotation.DeleteMapping maps to io.micronaut.http.annotation.Delete at compilation time.
6 org.springframework.web.bind.annotation.RequestParam maps to io.micronaut.http.annotation.QueryValue at compilation time.

and use it in a test:

src/test/java/example/micronaut/GreetingControllerTest.java
package example.micronaut;

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import jakarta.inject.Inject;
import static org.junit.jupiter.api.Assertions.*;

@MicronautTest
class GreetingControllerTest {

    @Inject
    GreetingClient greetingClient;

    @Test
    void testGreetingService() {
        assertEquals(
                "Hola, John!",
                greetingClient.greet("John").getContent()
        );
    }
}

4.9. @Scheduled

You can use the @Scheduled annotation to schedule a recurring task. Create a Job:

src/main/java/example/micronaut/GreetingJob.java
package example.micronaut;

import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.Optional;

@Component (1)
public class GreetingJob {
    private static final Logger LOG = LoggerFactory.getLogger(GreetingJob.class);

    private final GreetingService greetingService;

    public GreetingJob(GreetingService greetingService) { (2)
        this.greetingService = greetingService;
    }

    @Scheduled(fixedDelayString = "30s") (3)
    void printLastGreeting() {
        final Optional<Greeting> lastGreeting = greetingService.getLastGreeting();
        lastGreeting.ifPresent(greeting -> {
            LOG.info("Last Greeting was = {}", greeting.getContent());
        });
    }
}
1 org.springframework.stereotype.Component maps to io.micronaut.context.annotation.Bean at compilation time. Spring will scan the application for classes annotated with @Component. It instantiates those classes and fulfills the injection points.
2 Use constructor injection to inject a bean of type GreetingService.
3 org.springframework.scheduling.annotation.Scheduled maps to io.micronaut.scheduling.annotation.Scheduled at compilation time. You can use @Scheduled annotation to schedule a recurring task.

4.10. Server side HTML Rendering

4.10.1. Thymeleaf view

5. Views

To use the Thymeleaf Java template engine to render views in a Micronaut application, add the following dependency on your classpath.

pom.xml
<dependency>
    <groupId>io.micronaut.views</groupId>
    <artifactId>micronaut-views-thymeleaf</artifactId>
    <scope>compile</scope>
</dependency>

Create a Thymeleaf view to render the UI for the controller:

src/main/resources/views/home.html
<!DOCTYPE html>
<html>
<head>
    <title>Home</title>
</head>
<body>
    <h1 th:text="${message}"></h1>
</body>
</html>

5.1. Controller

src/main/java/example/micronaut/HomeController.java
package example.micronaut;

import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController (1)
public class HomeController {
    @GetMapping(path = "/", produces = "text/html") (2)
    public String home(Model model) { (3)
        model.addAttribute(
                "message",
                "Welcome to Micronaut for Spring");

        return "home"; (4)
    }
}
1 org.springframework.web.bind.annotation.RestController.html maps to io.micronaut.http.annotation.Controller at compilation time.
2 org.springframework.web.bind.annotation.GetMapping maps to io.micronaut.http.annotation.Get at compilation time.
3 You can use org.springframework.ui.Model in combination with Micronaut Views.
4 the View’s name

5.2. Controller Test

Add a test that proves you can use org.springframework.ui.Model and render server-side HTML.

src/test/java/example/micronaut/HomeControllerTest.java
package example.micronaut;

import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

@MicronautTest (1)
class HomeControllerTest {

    @Inject
    @Client("/")
    HttpClient httpClient; (2)

    @Test
    void renderServerSideHTMLwithThymeleafAndMicronautViews() {
        String expected = "<!DOCTYPE html>\n" +
                "<html>\n"+
                "<head>\n"+
                "    <title>Home</title>\n"+
                "</head>\n"+
                "<body>\n"+
                "    <h1>Welcome to Micronaut for Spring</h1>\n"+
                "</body>\n"+
                "</html>";
        String html = httpClient.toBlocking().retrieve("/");
        assertEquals(expected, html);
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
2 Inject the HttpClient bean and point it to the embedded server.

6. Running the Application

To run the application, use the ./mvnw mn:run command, which starts the application on port 8080.

Execute the API:

 curl "http://localhost:8080/greeting?name=Sergio"
{"id":1,"content":"Hola, Sergio!"}

If you wait 30 seconds, you will see a log statement from GreetingJob.

7. Next steps

Read more about Micronaut Spring.

8. Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

9. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…​).