Like most Spring Getting Started guides , you can start from scratch and complete each step or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.

To start from scratch , move on to Starting with Spring Initializr .

To skip the basics , do the following:

When you finish , you can check your results against the code in gs-reactive-rest-service/complete .

You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.

To manually initialize the project:

We’re going to start with a Greeting POJO that will be serialized as JSON by our RESTful service:

src/main/java/hello/Greeting.java

package com.example.reactivewebservice;
public class Greeting {
  private String message;
  public Greeting() {
  public Greeting(String message) {
    this.message = message;
  public String getMessage() {
    return this.message;
  public void setMessage(String message) {
    this.message = message;
  @Override
  public String toString() {
    return "Greeting{" +
        "message='" + message + '\'' +
   
In the Spring Reactive approach, we use a handler to handle the request and create a response, as shown in the following example:
   
src/main/java/hello/GreetingHandler.java
    
package com.example.reactivewebservice;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.BodyInserters;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Mono;
@Component
public class GreetingHandler {
  public Mono<ServerResponse> hello(ServerRequest request) {
    return ServerResponse.ok().contentType(MediaType.APPLICATION_JSON)
      .body(BodyInserters.fromValue(new Greeting("Hello, Spring!")));
   
This simple reactive class always returns a JSON body with a “Hello, Spring!” greeting. It could return many other things, including a stream of items from a database, a stream of items that were generated by calculations, and so on. Note the reactive code: a Mono object that holds a ServerResponse body.
   
In this application, we use a router to handle the only route we expose (/hello), as shown in the following example:
   
src/main/java/hello/GreetingRouter.java
    
package com.example.reactivewebservice;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.web.reactive.function.server.ServerResponse;
import static org.springframework.web.reactive.function.server.RequestPredicates.GET;
import static org.springframework.web.reactive.function.server.RequestPredicates.accept;
@Configuration(proxyBeanMethods = false)
public class GreetingRouter {
  @Bean
  public RouterFunction<ServerResponse> route(GreetingHandler greetingHandler) {
    return RouterFunctions
      .route(GET("/hello").and(accept(MediaType.APPLICATION_JSON)), greetingHandler::hello);
   
The router listens for traffic on the /hello path and returns the value provided by our reactive handler class.
   
The Spring RestTemplate class is, by nature, blocking. Consequently, we do not want to use it in a reactive application. For reactive applications, Spring offers the WebClient class, which is non-blocking. We use a WebClient-based implementation to consume our RESTful service:
   
src/main/java/hello/GreetingClient.java
    
package com.example.reactivewebservice;
import reactor.core.publisher.Mono;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.client.WebClient;
@Component
public class GreetingClient {
  private final WebClient client;
  // Spring Boot auto-configures a `WebClient.Builder` instance with nice defaults and customizations.
  // We can use it to create a dedicated `WebClient` for our component.
  public GreetingClient(WebClient.Builder builder) {
    this.client = builder.baseUrl("http://localhost:8080").build();
  public Mono<String> getMessage() {
    return this.client.get().uri("/hello").accept(MediaType.APPLICATION_JSON)
        .retrieve()
        .bodyToMono(Greeting.class)
        .map(Greeting::getMessage);
   
The WebClient class uses reactive features, in the form of a Mono to hold the content of the message (returned by the getMessage method). This is using a function API, rather than an imperative one, to chain reactive operators.
   
It can take time to get used to Reactive APIs, but the WebClient has interesting features and can also be used in traditional Spring MVC applications.
   
We’re going to use the main() method to drive our application and get the Greeting message from our endpoint.
   
src/main/java/hello/Application.java
    
package com.example.reactivewebservice;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
@SpringBootApplication
public class ReactiveWebServiceApplication {
  public static void main(String[] args) {
    ConfigurableApplicationContext context = SpringApplication.run(ReactiveWebServiceApplication.class, args);
    GreetingClient greetingClient = context.getBean(GreetingClient.class);
    // We need to block for the content here or the JVM might exit before the message is logged
    System.out.println(">> message = " + greetingClient.getMessage().block());
   
@SpringBootApplication is a convenience annotation that adds all of the following:
    
@Configuration: Tags the class as a source of bean definitions for the application context.
    
@EnableAutoConfiguration: Tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings. For example, if spring-webmvc is on the classpath, this annotation flags the application as a web application and activates key behaviors, such as setting up a DispatcherServlet.
    
@ComponentScan: Tells Spring to look for other components, configurations, and services in the hello package, letting it find the controllers.
   
The main() method uses Spring Boot’s SpringApplication.run() method to launch an application. Did you notice that there was not a single line of XML? There is no web.xml file, either. This web application is 100% pure Java and you did not have to deal with configuring any plumbing or infrastructure.
   
Build an executable JAR
    
You can run the application from the command line with Gradle or Maven. You can also build a single executable JAR file that contains all the necessary dependencies, classes, and resources and run that. Building an executable jar makes it easy to ship, version, and deploy the service as an application throughout the development lifecycle, across different environments, and so forth.
    
If you use Gradle, you can run the application by using ./gradlew bootRun. Alternatively, you can build the JAR file by using ./gradlew build and then run the JAR file, as follows:
   
Now that the application is running, you can test it. To start with, you can open a browser and go to http://localhost:8080/hello and see, “Hello, Spring!” For this guide, we also created a test class to get you started on testing with the WebTestClient class.
   
src/test/java/hello/GreetingRouterTest.java
    
package com.example.reactivewebservice;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.reactive.server.WebTestClient;
import static org.assertj.core.api.Assertions.assertThat;
@ExtendWith(SpringExtension.class)
//  We create a `@SpringBootTest`, starting an actual server on a `RANDOM_PORT`
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class GreetingRouterTest {
  // Spring Boot will create a `WebTestClient` for you,
  // already configure and ready to issue requests against "localhost:RANDOM_PORT"
  @Autowired
  private WebTestClient webTestClient;
  @Test
  public void testHello() {
    webTestClient
      // Create a GET request to test an endpoint
      .get().uri("/hello")
      .accept(MediaType.APPLICATION_JSON)
      .exchange()
      // and use the dedicated DSL to test assertions against the response
      .expectStatus().isOk()
      .expectBody(Greeting.class).value(greeting -> {
        assertThat(greeting.getMessage()).isEqualTo("Hello, Spring!");
   
Congratulations! You have developed a Reactive Spring application that includes a WebClient to consume a RESTful service!
   
Want to write a new guide or contribute to an existing one? Check out our contribution guidelines.