These tutorials target Micronaut Framework 3. Read, Guides for Micronaut Framework 4.

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: 3.9.2

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:

  • Some time on your hands

  • A decent text editor or IDE

  • JDK 1.8 or greater installed with JAVA_HOME configured appropriately

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=spring-web,spring-boot,views-thymeleaf,micronaut-validation \
    --build=maven
    --lang=java
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.

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 spring-web, spring-boot, views-thymeleaf, and micronaut-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.

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:

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;

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 javax.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 javax.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 javax.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 javax.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);
    }
}

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)
}

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

4.11. Views

Although the Micronaut framework is primarily designed around message encoding / decoding, there are occasions where it is convenient to render a view on the server side.

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>

4.11.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)
    }
}

4.11.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.

5. 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.

6. Next steps

Read more about Micronaut Spring.

7. Help with the Micronaut Framework

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