mirror of
https://github.com/spring-projects/spring-boot.git
synced 2026-09-20 14:39:36 +00:00
Start documenting WebFlux support
This commit adds new reference documentation sections about WebFlux support in Spring Boot: * Support for multiple HTTP servers (gh-8403) * `CodecCustomizer` and JSON codecs (gh-8897, gh-9166) * `WebClient.Builder` auto-configuration (gh-9522) * Tests with `@WebFluxTest` (gh-8401) * `WebTestClient` auto-configuration (gh-8399) * Support for Thymeleafi and Mustache templating (gh-8124, gh-8648) * Choose another HTTP server with WebFlux (closes gh-9690)
This commit is contained in:
Brian Clozel
@@ -621,7 +621,7 @@ that any HTTP request with the path "`/`" should be mapped to the `home` method.
|
||||
back to the caller.
|
||||
|
||||
TIP: The `@RestController` and `@RequestMapping` annotations are Spring MVC annotations
|
||||
(they are not specific to Spring Boot). See the {spring-reference}#mvc[MVC section] in
|
||||
(they are not specific to Spring Boot). See the {spring-reference}web.html#mvc[MVC section] in
|
||||
the Spring Reference Documentation for more details.
|
||||
|
||||
|
||||
|
||||
@@ -487,8 +487,78 @@ Spring Boot. The definitive list comes from searching the source code for
|
||||
|
||||
|
||||
|
||||
[[howto-embedded-servlet-containers]]
|
||||
== Embedded servlet containers
|
||||
[[howto-embedded-web-servers]]
|
||||
== Embedded Web servers
|
||||
|
||||
|
||||
|
||||
[[howto-use-another-web-server]]
|
||||
=== Use another Web server
|
||||
The Spring Boot starters bring a default embedded container for you:
|
||||
|
||||
* `spring-boot-starter-web` brings Tomcat with `spring-boot-starter-tomcat`,
|
||||
but `spring-boot-starter-jetty` and `spring-boot-starter-undertow` can be used instead.
|
||||
* `spring-boot-starter-webflux` brings Reactor Netty with `spring-boot-starter-reactor-netty`,
|
||||
but `spring-boot-starter-tomcat`, `spring-boot-starter-jetty` and
|
||||
`spring-boot-starter-undertow` can be used instead.
|
||||
|
||||
NOTE: Many starters only support Spring MVC, so they transitively bring
|
||||
`spring-boot-starter-web` into your application classpath
|
||||
|
||||
If you choose to use a different HTTP server, you need to exclude those dependencies
|
||||
and include the one you chose instead. Spring Boot provides separate starters for
|
||||
HTTP servers to help make this process as easy as possible.
|
||||
|
||||
Example in Maven, for Spring MVC:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
<exclusions>
|
||||
<!-- Exclude the Tomcat dependency -->
|
||||
<exclusion>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-tomcat</artifactId>
|
||||
</exclusion>
|
||||
</exclusions>
|
||||
</dependency>
|
||||
<!-- Use Jetty instead -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-jetty</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
Example in Gradle, for Spring WebFlux:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
configurations {
|
||||
// exclude Reactor Netty
|
||||
compile.exclude module: 'spring-boot-starter-reactor-netty'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
compile 'org.springframework.boot:spring-boot-starter-webflux'
|
||||
// Use Undertow instead
|
||||
compile 'org.springframework.boot:spring-boot-starter-undertow'
|
||||
// ...
|
||||
}
|
||||
----
|
||||
|
||||
NOTE: `spring-boot-starter-reactor-netty` is required to use the `WebClient`,
|
||||
so excluding it is not required if you wish to use a different HTTP server.
|
||||
|
||||
[[howto-configure-jetty]]
|
||||
=== Configure Jetty
|
||||
Generally you can follow the advice from
|
||||
_<<howto-discover-build-in-options-for-external-properties>>_ about
|
||||
`@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at
|
||||
`ServletWebServerFactoryCustomizer`. The Jetty APIs are quite rich so once you have
|
||||
access to the `JettyServletWebServerFactory` you can modify it in a number
|
||||
of ways. Or the nuclear option is to add your own `JettyServletWebServerFactory`.
|
||||
|
||||
|
||||
|
||||
@@ -828,104 +898,6 @@ include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.jav
|
||||
|
||||
|
||||
|
||||
[[howto-use-jetty-instead-of-tomcat]]
|
||||
=== Use Jetty instead of Tomcat
|
||||
The Spring Boot starters (`spring-boot-starter-web` in particular) use Tomcat as an
|
||||
embedded container by default. You need to exclude those dependencies and include the
|
||||
Jetty one instead. Spring Boot provides Tomcat and Jetty dependencies bundled together
|
||||
as separate starters to help make this process as easy as possible.
|
||||
|
||||
Example in Maven:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
<exclusions>
|
||||
<exclusion>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-tomcat</artifactId>
|
||||
</exclusion>
|
||||
</exclusions>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-jetty</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
Example in Gradle:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
configurations {
|
||||
compile.exclude module: 'spring-boot-starter-tomcat'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
compile 'org.springframework.boot:spring-boot-starter-web'
|
||||
compile 'org.springframework.boot:spring-boot-starter-jetty'
|
||||
// ...
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[howto-configure-jetty]]
|
||||
=== Configure Jetty
|
||||
Generally you can follow the advice from
|
||||
_<<howto-discover-build-in-options-for-external-properties>>_ about
|
||||
`@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at
|
||||
`ServletWebServerFactoryCustomizer`. The Jetty APIs are quite rich so once you have
|
||||
access to the `JettyServletWebServerFactory` you can modify it in a number
|
||||
of ways. Or the nuclear option is to add your own `JettyServletWebServerFactory`.
|
||||
|
||||
|
||||
|
||||
[[howto-use-undertow-instead-of-tomcat]]
|
||||
=== Use Undertow instead of Tomcat
|
||||
Using Undertow instead of Tomcat is very similar to <<howto-use-jetty-instead-of-tomcat,
|
||||
using Jetty instead of Tomcat>>. You need to exclude the Tomcat dependencies and include
|
||||
the Undertow starter instead.
|
||||
|
||||
Example in Maven:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
<exclusions>
|
||||
<exclusion>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-tomcat</artifactId>
|
||||
</exclusion>
|
||||
</exclusions>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-undertow</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
Example in Gradle:
|
||||
|
||||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
configurations {
|
||||
compile.exclude module: 'spring-boot-starter-tomcat'
|
||||
}
|
||||
|
||||
dependencies {
|
||||
compile 'org.springframework.boot:spring-boot-starter-web'
|
||||
compile 'org.springframework.boot:spring-boot-starter-undertow'
|
||||
// ...
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[howto-configure-undertow]]
|
||||
=== Configure Undertow
|
||||
Generally you can follow the advice from
|
||||
@@ -1288,7 +1260,7 @@ Check out {sc-spring-boot-autoconfigure}/web/servlet/WebMvcAutoConfiguration.{sc
|
||||
|
||||
[[howto-http-clients-proxy-configuration]]
|
||||
=== Configure RestTemplate to use a proxy
|
||||
As described in <<spring-boot-features.adoc#boot-features-restclient-customization>>,
|
||||
As described in <<spring-boot-features.adoc#boot-features-resttemplate-customization>>,
|
||||
a `RestTemplateCustomizer` can be used with `RestTemplateBuilder` to build a customized
|
||||
`RestTemplate`. This is the recommended approach for creating a `RestTemplate` configured
|
||||
to use a proxy.
|
||||
|
||||
@@ -36,7 +36,7 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
|
||||
:dependency-management-plugin-documentation: {dependency-management-plugin}/blob/master/README.md
|
||||
:spring-boot-maven-plugin-site: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/maven-plugin/
|
||||
:spring-boot-gradle-plugin: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/gradle-plugin/
|
||||
:spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/htmlsingle
|
||||
:spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/
|
||||
:spring-security-reference: http://docs.spring.io/spring-security/site/docs/{spring-security-docs-version}/reference/htmlsingle
|
||||
:spring-security-oauth2-reference: http://projects.spring.io/spring-security-oauth/docs/oauth2.html
|
||||
:spring-webservices-reference: http://docs.spring.io/spring-ws/docs/{spring-webservices-docs-version}/reference/htmlsingle
|
||||
@@ -52,8 +52,8 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
|
||||
:ant-manual: http://ant.apache.org/manual
|
||||
:code-examples: ../java/org/springframework/boot
|
||||
:gradle-user-guide: https://docs.gradle.org/3.4.1/userguide
|
||||
:jetty-documentation: https://www.eclipse.org/jetty/documentation/9.3.x
|
||||
:tomcat-documentation: https://tomcat.apache.org/tomcat-8.0-doc
|
||||
:jetty-documentation: https://www.eclipse.org/jetty/documentation/9.4.x
|
||||
:tomcat-documentation: https://tomcat.apache.org/tomcat-8.5-doc
|
||||
// ======================================================================================
|
||||
|
||||
include::documentation-overview.adoc[]
|
||||
|
||||
@@ -1657,8 +1657,10 @@ tried (`myPropertyName`, `MY_PROPERTY_NAME` etc).
|
||||
[[boot-features-developing-web-applications]]
|
||||
== Developing web applications
|
||||
Spring Boot is well suited for web application development. You can easily create a
|
||||
self-contained HTTP server using embedded Tomcat, Jetty, or Undertow. Most web
|
||||
applications will use the `spring-boot-starter-web` module to get up and running quickly.
|
||||
self-contained HTTP server using embedded Tomcat, Jetty, Undertow, or Netty.
|
||||
Most web applications will use the `spring-boot-starter-web` module to get up
|
||||
and running quickly. You can also choose to use to build reactive web applications
|
||||
by using the `spring-boot-starter-webflux` module.
|
||||
|
||||
If you haven't yet developed a Spring Boot web application you can follow the
|
||||
"Hello World!" example in the
|
||||
@@ -1700,7 +1702,7 @@ Here is a typical example `@RestController` to serve JSON data:
|
||||
----
|
||||
|
||||
Spring MVC is part of the core Spring Framework and detailed information is available in
|
||||
the {spring-reference}#mvc[reference documentation]. There are also several guides
|
||||
the {spring-reference}web.html#mvc[reference documentation]. There are also several guides
|
||||
available at http://spring.io/guides that cover Spring MVC.
|
||||
|
||||
|
||||
@@ -1722,9 +1724,9 @@ The auto-configuration adds the following features on top of Spring's defaults:
|
||||
* Automatic use of a `ConfigurableWebBindingInitializer` bean (see below).
|
||||
|
||||
If you want to keep Spring Boot MVC features, and
|
||||
you just want to add additional {spring-reference}#mvc[MVC configuration] (interceptors,
|
||||
you just want to add additional {spring-reference}web.html#mvc[MVC configuration] (interceptors,
|
||||
formatters, view controllers etc.) you can add your own `@Configuration` class of type
|
||||
`WebMvcConfigurerAdapter`, but *without* `@EnableWebMvc`. If you wish to provide custom
|
||||
`WebMvcConfigurer`, but *without* `@EnableWebMvc`. If you wish to provide custom
|
||||
instances of `RequestMappingHandlerMapping`, `RequestMappingHandlerAdapter` or
|
||||
`ExceptionHandlerExceptionResolver` you can declare a `WebMvcRegistrationsAdapter`
|
||||
instance providing such components.
|
||||
@@ -1827,7 +1829,7 @@ you set the `spring.mvc.message-codes-resolver.format` property `PREFIX_ERROR_CO
|
||||
By default Spring Boot will serve static content from a directory called `/static` (or
|
||||
`/public` or `/resources` or `/META-INF/resources`) in the classpath or from the root
|
||||
of the `ServletContext`. It uses the `ResourceHttpRequestHandler` from Spring MVC so you
|
||||
can modify that behavior by adding your own `WebMvcConfigurerAdapter` and overriding the
|
||||
can modify that behavior by adding your own `WebMvcConfigurer` and overriding the
|
||||
`addResourceHandlers` method.
|
||||
|
||||
In a stand-alone web application the default servlet from the container is also
|
||||
@@ -1912,7 +1914,7 @@ for more of the supported options.
|
||||
====
|
||||
This feature has been thoroughly described in a dedicated
|
||||
https://spring.io/blog/2014/07/24/spring-framework-4-1-handling-static-web-resources[blog post]
|
||||
and in Spring Framework's {spring-reference}/#mvc-config-static-resources[reference documentation].
|
||||
and in Spring Framework's {spring-reference}web.html#mvc-config-static-resources[reference documentation].
|
||||
====
|
||||
|
||||
|
||||
@@ -2069,8 +2071,8 @@ interface.
|
||||
|
||||
|
||||
You can also use regular Spring MVC features like
|
||||
{spring-reference}/#mvc-exceptionhandlers[`@ExceptionHandler` methods] and
|
||||
{spring-reference}/#mvc-ann-controller-advice[`@ControllerAdvice`]. The `ErrorController`
|
||||
{spring-reference}web.html#mvc-exceptionhandlers[`@ExceptionHandler` methods] and
|
||||
{spring-reference}web.html#mvc-ann-controller-advice[`@ControllerAdvice`]. The `ErrorController`
|
||||
will then pick up any unhandled exceptions.
|
||||
|
||||
|
||||
@@ -2159,12 +2161,12 @@ http://caniuse.com/#feat=cors[most browsers] that allows you to specify in a fle
|
||||
way what kind of cross domain requests are authorized, instead of using some less secure
|
||||
and less powerful approaches like IFRAME or JSONP.
|
||||
|
||||
As of version 4.2, Spring MVC {spring-reference}/#cors[supports CORS] out of the box.
|
||||
Using {spring-reference}/#_controller_method_cors_configuration[controller method CORS
|
||||
As of version 4.2, Spring MVC {spring-reference}web.html#cors[supports CORS] out of the box.
|
||||
Using {spring-reference}web.html#controller-method-cors-configuration[controller method CORS
|
||||
configuration] with
|
||||
{spring-javadoc}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`]
|
||||
annotations in your Spring Boot application does not require any specific configuration.
|
||||
{spring-reference}/#_global_cors_configuration[Global CORS configuration] can be defined
|
||||
{spring-reference}web.html#global-cors-configuration[Global CORS configuration] can be defined
|
||||
by registering a `WebMvcConfigurer` bean with a customized `addCorsMappings(CorsRegistry)`
|
||||
method:
|
||||
|
||||
@@ -2175,7 +2177,7 @@ method:
|
||||
|
||||
@Bean
|
||||
public WebMvcConfigurer corsConfigurer() {
|
||||
return new WebMvcConfigurerAdapter() {
|
||||
return new WebMvcConfigurer() {
|
||||
@Override
|
||||
public void addCorsMappings(CorsRegistry registry) {
|
||||
registry.addMapping("/api/**");
|
||||
@@ -2185,6 +2187,184 @@ method:
|
||||
}
|
||||
----
|
||||
|
||||
[[boot-features-spring-webflux]]
|
||||
=== The '`Spring WebFlux framework`'
|
||||
|
||||
Spring WebFlux is the new reactive web framework introduced in Spring Framework 5.0.
|
||||
Unlike Spring MVC, it does not require the Servlet API, is fully asynchronous and
|
||||
non-blocking, and implements the http://www.reactive-streams.org/[Reactive Streams]
|
||||
specification through http://projectreactor.io/[the Reactor project].
|
||||
|
||||
Spring WebFlux comes in two flavours — the annotation-based one is quite close to
|
||||
the Spring MVC model we know:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@RestController
|
||||
@RequestMapping("/users")
|
||||
public class MyRestController {
|
||||
|
||||
@GetMapping("/{user}")
|
||||
public Mono<User> getUser(@PathVariable Long user) {
|
||||
// ...
|
||||
}
|
||||
|
||||
@GetMapping("/{user}/customers")
|
||||
Flux<Customer> getUserCustomers(@PathVariable Long user) {
|
||||
// ...
|
||||
}
|
||||
|
||||
@DeleteMapping("/{user}")
|
||||
public Mono<User> deleteUser(@PathVariable Long user) {
|
||||
// ...
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
'`WebFlux.fn`', the functional variant, separates the routing configuration from the actual handling
|
||||
of the requests:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@Configuration
|
||||
public class RoutingConfiguration {
|
||||
|
||||
@Bean
|
||||
public RouterFunction<ServerResponse> monoRouterFunction(UserHandler userHandler) {
|
||||
return route(GET("/{user}").and(accept(APPLICATION_JSON)), userHandler::getUser)
|
||||
.andRoute(GET("/{user}/customers").and(accept(APPLICATION_JSON)), userHandler::getUserCustomers)
|
||||
.andRoute(DELETE("/{user}").and(accept(APPLICATION_JSON)), userHandler::deleteUser);
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
@Component
|
||||
public class UserHandler {
|
||||
|
||||
public Mono<ServerResponse> getUser(ServerRequest request) {
|
||||
// ...
|
||||
}
|
||||
|
||||
public Mono<ServerResponse> getUserCustomers(ServerRequest request) {
|
||||
// ...
|
||||
}
|
||||
|
||||
public Mono<ServerResponse> deleteUser(ServerRequest request) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
WebFlux is part of the Spring Framework and detailed information is available in
|
||||
the {spring-reference}web.html#web-reactive[reference documentation].
|
||||
|
||||
To get started, add the `spring-boot-starter-webflux` module to your application.
|
||||
|
||||
NOTE: Adding both `spring-boot-starter-web` and `spring-boot-starter-webflux`
|
||||
modules in your application will result in Spring Boot auto-configuring Spring
|
||||
MVC, not WebFlux. This behavior has been chosen because many Spring developers
|
||||
will add `spring-boot-starter-webflux` to their Spring MVC application to use
|
||||
the reactive `WebCLient`. You can still enforce your choice by setting the
|
||||
chosen application type like
|
||||
`SpringApplication.setWebApplicationType(WebApplicationType.REACTIVE)`.
|
||||
|
||||
[[boot-features-spring-webflux-auto-configuration]]
|
||||
==== Spring WebFlux auto-configuration
|
||||
Spring Boot provides auto-configuration for Spring WebFlux that works well with most
|
||||
applications.
|
||||
|
||||
The auto-configuration adds the following features on top of Spring's defaults:
|
||||
|
||||
* Configuring codecs for `HttpMessageReader` and `HttpMessageWriter` instances (see below).
|
||||
* Support for serving static resources, including support for WebJars (see below).
|
||||
|
||||
|
||||
If you want to keep Spring Boot WebFlux features, and
|
||||
you just want to add additional {spring-reference}web.html#web-reactive[WebFlux configuration]
|
||||
you can add your own `@Configuration` class of type `WebFluxConfigurer`,
|
||||
but *without* `@EnableWebFlux`.
|
||||
|
||||
If you want to take complete control of Spring WebFlux, you can add your own `@Configuration`
|
||||
annotated with `@EnableWebFlux`.
|
||||
|
||||
|
||||
[[boot-features-spring-webflux-httpcodecs]]
|
||||
==== HTTP codecs with HttpMessageReaders and HttpMessageWriters
|
||||
Spring WebFlux uses the `HttpMessageReader` and `HttpMessageWriter` interface to convert
|
||||
HTTP requests and responses. They are configured with `CodecConfigurer` with sensible defaults,
|
||||
by looking at the libraries available in your classpath.
|
||||
|
||||
Spring Boot will apply further customization using `CodecCustomizer` instances.
|
||||
For example, `spring.jackson.*` configuration keys will be applied to the Jackson codec.
|
||||
|
||||
If you need to add or customize codecs you can create a custom `CodecCustomizer` component:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
import org.springframework.boot.web.codec.CodecCustomizer;
|
||||
|
||||
@Configuration
|
||||
public class MyConfiguration {
|
||||
|
||||
@Bean
|
||||
public CodecCustomizer myCodecCustomizer() {
|
||||
return codecConfigurer -> {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
You can also leverage <<boot-features-json-components,Boot's custom JSON serializers and deserializers>>.
|
||||
|
||||
[[boot-features-spring-webflux-static-content]]
|
||||
==== Static Content
|
||||
By default Spring Boot will serve static content from a directory called `/static` (or
|
||||
`/public` or `/resources` or `/META-INF/resources`) in the classpath.
|
||||
It uses the `ResourceWebHandler` from Spring WebFlux so you
|
||||
can modify that behavior by adding your own `WebFluxConfigurer` and overriding the
|
||||
`addResourceHandlers` method.
|
||||
|
||||
By default, resources are mapped on `+/**+` but you can tune that via
|
||||
`spring.mvc.static-path-pattern`. For instance, relocating all resources to `/resources/**`
|
||||
can be achieved as follows:
|
||||
|
||||
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
spring.mvc.static-path-pattern=/resources/**
|
||||
----
|
||||
|
||||
You can also customize the static resource locations using
|
||||
`spring.resources.static-locations` (replacing the default values with a list of directory
|
||||
locations). If you do this the default welcome page detection will switch to your custom
|
||||
locations, so if there is an `index.html` in any of your locations on startup, it will be
|
||||
the home page of the application.
|
||||
|
||||
In addition to the '`standard`' static resource locations above, a special case is made
|
||||
for http://www.webjars.org/[Webjars content]. Any resources with a path in `+/webjars/**+`
|
||||
will be served from jar files if they are packaged in the Webjars format.
|
||||
|
||||
TIP: Spring WebFlux applications don't strictly depend on the Servlet API, so they can't
|
||||
be deployed as war and have no use of the `src/main/webapp` directory.
|
||||
|
||||
|
||||
|
||||
[[boot-features-spring-webflux-template-engines]]
|
||||
==== Template engines
|
||||
As well as REST web services, you can also use Spring WebFlux to serve dynamic HTML content.
|
||||
Spring WebFlux supports a variety of templating technologies including Thymeleaf, FreeMarker
|
||||
and Mustache.
|
||||
|
||||
Spring Boot includes auto-configuration support for the following templating engines:
|
||||
|
||||
* http://freemarker.org/docs/[FreeMarker]
|
||||
* http://www.thymeleaf.org[Thymeleaf]
|
||||
* http://mustache.github.io/[Mustache]
|
||||
|
||||
When you're using one of these templating engines with the default configuration, your
|
||||
templates will be picked up automatically from `src/main/resources/templates`.
|
||||
|
||||
|
||||
[[boot-features-jersey]]
|
||||
@@ -4050,7 +4230,7 @@ transparently, without any interference to the invoker. Spring Boot auto-config
|
||||
cache infrastructure as long as the caching support is enabled via the `@EnableCaching`
|
||||
annotation.
|
||||
|
||||
NOTE: Check the {spring-reference}/#cache[relevant section] of the Spring Framework
|
||||
NOTE: Check the {spring-reference}integration.html#cache[relevant section] of the Spring Framework
|
||||
reference for more details.
|
||||
|
||||
In a nutshell, adding caching to an operation of your service is as easy as adding the
|
||||
@@ -4092,8 +4272,8 @@ application uses. Practically all providers require you to explicitly configure
|
||||
cache that you use in the application. Some offer a way to customize the default caches
|
||||
defined by the `spring.cache.cache-names` property.
|
||||
|
||||
TIP: It is also possible to {spring-reference}/#cache-annotations-put[update] or
|
||||
{spring-reference}/#cache-annotations-evict[evict] data from the cache transparently.
|
||||
TIP: It is also possible to {spring-reference}integration.html#cache-annotations-put[update] or
|
||||
{spring-reference}integration.html#cache-annotations-evict[evict] data from the cache transparently.
|
||||
|
||||
NOTE: If you are using the cache infrastructure with beans that are not interface-based,
|
||||
make sure to enable the `proxyTargetClass` attribute of `@EnableCaching`.
|
||||
@@ -4395,7 +4575,7 @@ The `javax.jms.ConnectionFactory` interface provides a standard method of creati
|
||||
`javax.jms.Connection` for interacting with a JMS broker. Although Spring needs a
|
||||
`ConnectionFactory` to work with JMS, you generally won't need to use it directly yourself
|
||||
and you can instead rely on higher level messaging abstractions (see the
|
||||
{spring-reference}/#jms[relevant section] of the Spring Framework reference
|
||||
{spring-reference}integration.html#jms[relevant section] of the Spring Framework reference
|
||||
documentation for details). Spring Boot also auto-configures the necessary infrastructure
|
||||
to send and receive messages.
|
||||
|
||||
@@ -4880,8 +5060,8 @@ include::{code-examples}/kafka/KafkaSpecialProducerConsumerConfigExample.java[ta
|
||||
|
||||
|
||||
|
||||
[[boot-features-restclient]]
|
||||
== Calling REST services
|
||||
[[boot-features-resttemplate]]
|
||||
== Calling REST services with '`RestTemplate`'
|
||||
If you need to call remote REST services from your application, you can use Spring
|
||||
Framework's `RestTemplate` class. Since `RestTemplate` instances often need to be
|
||||
customized before being used, Spring Boot does not provide any single auto-configured
|
||||
@@ -4895,7 +5075,7 @@ Here's a typical example:
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@Service
|
||||
public class MyBean {
|
||||
public class MyService {
|
||||
|
||||
private final RestTemplate restTemplate;
|
||||
|
||||
@@ -4914,7 +5094,7 @@ TIP: `RestTemplateBuilder` includes a number of useful methods that can be used
|
||||
configure a `RestTemplate`. For example, to add BASIC auth support you can use
|
||||
`builder.basicAuthorization("user", "password").build()`.
|
||||
|
||||
[[boot-features-restclient-customization]]
|
||||
[[boot-features-resttemplate-customization]]
|
||||
=== RestTemplate customization
|
||||
There are three main approaches to `RestTemplate` customization, depending on how broadly
|
||||
you want the customizations to apply.
|
||||
@@ -4941,6 +5121,60 @@ Lastly, the most extreme (and rarely used) option is to create your own
|
||||
`RestTemplateBuilder` and will prevent any `RestTemplateCustomizer` beans from being used.
|
||||
|
||||
|
||||
[[boot-features-webclient]]
|
||||
== Calling REST services with '`WebClient`'
|
||||
|
||||
If you have Spring WebFlux on your classpath, you can also choose to use `WebClient`
|
||||
to call remote REST services; compared to `RestTemplate`, this client has more a
|
||||
functional feel to it and is fully reactive. You can create your own client
|
||||
instance with the builder `WebClient.create()`, which already provides a good
|
||||
out-of-the-box experience. See the
|
||||
{spring-reference}web.html#web-reactive-client[relevant section on WebClient].
|
||||
|
||||
Spring Boot will create and pre-configure such a builder for you; for example,
|
||||
client HTTP codecs will be configured just like the server ones
|
||||
(see <<boot-features-spring-webflux-httpcodecs,WebFlux HTTP codecs auto-configuration>>).
|
||||
|
||||
Here's a typical example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@Service
|
||||
public class MyService {
|
||||
|
||||
private final WebClient webClient;
|
||||
|
||||
public MyBean(WebClient.Builder webClientBuilder) {
|
||||
this.webClient = webClientBuilder.baseUrl("http://example.org").build();
|
||||
}
|
||||
|
||||
public Mono<Details> someRestCall(String name) {
|
||||
return this.webClient.get().url("/{name}/details", name)
|
||||
.retrieve().bodyToMono(Details.class);
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[boot-features-webclient-customization]]
|
||||
=== WebClient customization
|
||||
There are three main approaches to `WebClient` customization, depending on how broadly
|
||||
you want the customizations to apply.
|
||||
|
||||
To make the scope of any customizations as narrow as possible, inject the auto-configured
|
||||
`WebClient.Builder` and then call its methods as required. `WebClient.Builder` instances
|
||||
are stateful; any change on the builder will be reflected in all clients subsequently
|
||||
created with it. If you'd like to create several clients with the same builder, you can
|
||||
also consider cloning the builder with `WebClient.Builder other = builder.clone();`.
|
||||
|
||||
To make an application-wide, additive customization to all `WebClient.Builder` instances,
|
||||
you can declare `WebClientCustomizer` beans and change the `WebClient.Builder` as you
|
||||
would do locally at the point of injection.
|
||||
|
||||
Lastly, you can fall back to the original API and just use `WebClient.create()`. In that
|
||||
case, no auto-configuration nor `WebClientCustomizer` will be applied.
|
||||
|
||||
[[boot-features-validation]]
|
||||
== Validation
|
||||
@@ -4976,7 +5210,7 @@ The Spring Framework provides an easy abstraction for sending email using the
|
||||
`JavaMailSender` interface and Spring Boot provides auto-configuration for it as well as
|
||||
a starter module.
|
||||
|
||||
TIP: Check the {spring-reference}/#mail[reference documentation] for a detailed
|
||||
TIP: Check the {spring-reference}integration.html#mail[reference documentation] for a detailed
|
||||
explanation of how you can use `JavaMailSender`.
|
||||
|
||||
If `spring.mail.host` and the relevant libraries (as defined by
|
||||
@@ -5344,7 +5578,7 @@ If you use the
|
||||
the following provided libraries:
|
||||
|
||||
* http://junit.org[JUnit] -- The de-facto standard for unit testing Java applications.
|
||||
* {spring-reference}/#integration-testing[Spring Test] & Spring Boot Test --
|
||||
* {spring-reference}testing.html#integration-testing[Spring Test] & Spring Boot Test --
|
||||
Utilities and integration test support for Spring Boot applications.
|
||||
* http://joel-costigliola.github.io/assertj/[AssertJ] -- A fluent assertion library.
|
||||
* http://hamcrest.org/JavaHamcrest/[Hamcrest] -- A library of matcher objects (also known
|
||||
@@ -5374,7 +5608,7 @@ You can declare a dependency directly to `org.springframework:spring-test` or us
|
||||
`spring-boot-starter-test` '`Starter`' to pull it in transitively.
|
||||
|
||||
If you have not used the `spring-test` module before you should start by reading the
|
||||
{spring-reference}/#testing[relevant section] of the Spring Framework reference
|
||||
{spring-reference}testing.html#testing[relevant section] of the Spring Framework reference
|
||||
documentation.
|
||||
|
||||
|
||||
@@ -5713,7 +5947,7 @@ TIP: If you need to configure elements of the auto-configuration (for example wh
|
||||
filters should be applied) you can use attributes in the `@AutoConfigureMockMvc`
|
||||
annotation.
|
||||
|
||||
If you use HtmlUnit or Selenium, auto-configuration will also provide a `WebClient` bean
|
||||
If you use HtmlUnit or Selenium, auto-configuration will also provide an HTMLUnit `WebClient` bean
|
||||
and/or a `WebDriver` bean. Here is an example that uses HtmlUnit:
|
||||
|
||||
|
||||
@@ -5758,6 +5992,58 @@ definition.
|
||||
A list of the auto-configuration that is enabled by `@WebMvcTest` can be
|
||||
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.
|
||||
|
||||
[[boot-features-testing-spring-boot-applications-testing-autoconfigured-webflux-tests]]
|
||||
==== Auto-configured Spring WebFlux tests
|
||||
To test Spring WebFlux controllers are working as expected you can use the `@WebFluxTest`
|
||||
annotation. `@WebFluxTest` will auto-configure the Spring WebFlux infrastructure and limit
|
||||
scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`,and `WebFluxConfigurer`.
|
||||
Regular `@Component` beans will not be scanned when using this annotation.
|
||||
|
||||
Often `@WebFluxTest` will be limited to a single controller and used in combination with
|
||||
`@MockBean` to provide mock implementations for required collaborators.
|
||||
|
||||
`@WebFluxTest` also auto-configures `WebTestClient`, which offers a powerful way to quickly
|
||||
test WebFlux controllers without needing to start a full HTTP server.
|
||||
|
||||
TIP: You can also auto-configure `WebTestClient` in a non-`@WebFluxTest`
|
||||
(e.g. `SpringBootTest`) by annotating it with `@AutoConfigureWebTestClient`.
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
import org.junit.Test;
|
||||
import org.junit.runner.RunWith;
|
||||
|
||||
import org.springframework.beans.factory.annotation.Autowired;
|
||||
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
|
||||
import org.springframework.http.MediaType;
|
||||
import org.springframework.test.context.junit4.SpringRunner;
|
||||
import org.springframework.test.web.reactive.server.WebTestClient;
|
||||
|
||||
@RunWith(SpringRunner.class)
|
||||
@WebFluxTest(UserVehicleController.class)
|
||||
public class MyControllerTests {
|
||||
|
||||
@Autowired
|
||||
private WebTestClient webClient;
|
||||
|
||||
@MockBean
|
||||
private UserVehicleService userVehicleService;
|
||||
|
||||
@Test
|
||||
public void testExample() throws Exception {
|
||||
given(this.userVehicleService.getVehicleDetails("sboot"))
|
||||
.willReturn(new VehicleDetails("Honda", "Civic"));
|
||||
this.webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN)
|
||||
.exchange()
|
||||
.expectStatus().isOk()
|
||||
.expectBody(String.class).isEqualTo("Honda Civic");
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
A list of the auto-configuration that is enabled by `@WebFluxTest` can be
|
||||
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.
|
||||
|
||||
|
||||
[[boot-features-testing-spring-boot-applications-testing-autoconfigured-jpa-test]]
|
||||
@@ -5768,7 +6054,7 @@ Data JPA repositories. Regular `@Component` beans will not be loaded into the
|
||||
`ApplicationContext`.
|
||||
|
||||
Data JPA tests are transactional and rollback at the end of each test by default,
|
||||
see the {spring-reference}#testcontext-tx-enabling-transactions[relevant section] in the
|
||||
see the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in the
|
||||
Spring Reference Documentation for more details. If that's not what you want, you can
|
||||
disable transaction management for a test or for the whole class as follows:
|
||||
|
||||
@@ -5853,7 +6139,7 @@ will also configure an in-memory embedded database and a `JdbcTemplate`. Regular
|
||||
`@Component` beans will not be loaded into the `ApplicationContext`.
|
||||
|
||||
JDBC tests are transactional and rollback at the end of each test by default,
|
||||
see the {spring-reference}#testcontext-tx-enabling-transactions[relevant section] in the
|
||||
see the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in the
|
||||
Spring Reference Documentation for more details. If that's not what you want, you can
|
||||
disable transaction management for a test or for the whole class as follows:
|
||||
|
||||
@@ -5994,7 +6280,7 @@ beans will not be loaded into the `ApplicationContext`:
|
||||
----
|
||||
|
||||
Data Neo4j tests are transactional and rollback at the end of each test by default,
|
||||
see the {spring-reference}#testcontext-tx-enabling-transactions[relevant section] in the
|
||||
see the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in the
|
||||
Spring Reference Documentation for more details. If that's not what you want, you can
|
||||
disable transaction management for a test or for the whole class as follows:
|
||||
|
||||
@@ -6371,7 +6657,7 @@ and Undertow. If you're deploying a war file to a standalone container, Spring B
|
||||
assumes that the container will be responsible for the configuration of its WebSocket
|
||||
support.
|
||||
|
||||
Spring Framework provides {spring-reference}/#websocket[rich WebSocket support] that can
|
||||
Spring Framework provides {spring-reference}web.html#websocket[rich WebSocket support] that can
|
||||
be easily accessed via the `spring-boot-starter-websocket` module.
|
||||
|
||||
|
||||
@@ -6550,7 +6836,7 @@ application'. A web application is any application that is using a Spring
|
||||
[[boot-features-spel-conditions]]
|
||||
==== SpEL expression conditions
|
||||
The `@ConditionalOnExpression` annotation allows configuration to be included based on the
|
||||
result of a {spring-reference}/#expressions[SpEL expression].
|
||||
result of a {spring-reference}core.html#expressions[SpEL expression].
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user