This guide walks you through the process of creating a "Hello, Spring!" RESTful web service with Spring WebFlux and then consumes that service with a WebClient.
| Note | This guide shows the functional way of using Spring WebFlux. You can also use annotations with WebFlux. |
You will build a RESTful web service with Spring Webflux and a WebClient consumer of that service. You will be able to see output in both System.out and at:
http://localhost:8080/helloYou 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:
-
Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.
-
Choose either Gradle or Maven and the language you want to use: Kotlin or Java.
-
Click Dependencies and select Spring Reactive Web.
-
Click Generate.
-
Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.
| Note | If your IDE has the Spring Initializr integration, you can complete this process from your IDE. |
| Note | You can also fork the project from GitHub and open it in your IDE or other editor. |
We’re going to start with a Greeting type that will be serialized as JSON by our RESTful service:
link:complete/src/main/java/com/example/reactivewebservice/Greeting.java[role=include]link:complete-kotlin/src/main/kotlin/com/example/reactivewebservice/Greeting.kt[role=include]In the Spring Reactive approach, we use a handler to handle the request and create a response, as shown in the following example:
link:complete/src/main/java/com/example/reactivewebservice/GreetingHandler.java[role=include]link:complete-kotlin/src/main/kotlin/com/example/reactivewebservice/GreetingHandler.kt[role=include]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:
link:complete/src/main/java/com/example/reactivewebservice/GreetingRouter.java[role=include]link:complete-kotlin/src/main/kotlin/com/example/reactivewebservice/GreetingRouter.kt[role=include]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:
link:complete/src/main/java/com/example/reactivewebservice/GreetingClient.java[role=include]link:complete-kotlin/src/main/kotlin/com/example/reactivewebservice/GreetingClient.kt[role=include]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.
| Tip | You can use WebClient to communicate with non-reactive, blocking services, too. |
We’re going to use the main() method to drive our application and get the Greeting message from our endpoint.
link:complete/src/main/java/com/example/reactivewebservice/ReactiveWebServiceApplication.java[role=include]link:complete-kotlin/src/main/kotlin/com/example/reactivewebservice/ReactiveWebServiceApplication.kt[role=include]Logging output is displayed. The service should be up and running within a few seconds.
Once the service has started, you can see a line that reads:
>> message = Hello, Spring!
That line comes from the reactive content being consumed by the WebClient. Naturally, you can find something more interesting to do with your output than put it in System.out.
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.
link:complete/src/test/java/com/example/reactivewebservice/GreetingRouterTest.java[role=include]link:complete-kotlin/src/test/kotlin/com/example/reactivewebservice/GreetingRouterTest.kt[role=include]Congratulations! You have developed a Reactive Spring application that includes a WebClient to consume a RESTful service!