Introduction
스프링 프레임워크, 스프링 Web MVC에 있는 웹프레임워크는 Servlet API와 Servlet 컨테이너를 만들기위한 용도였습니다. 반응형스택, 웹프레임워크, 스프링 웹플럭스는 5.0 버전 이후에 추가되었습니다. 완전한 논블럭킹, Reactive Streams 지원, 역압(back pressure) 그리고 Netty, Undertow, Servlet 3.1 이상 서버에서 동작합니다.
두 웹프레임워크들
spring-webmvc,
spring-webflux 는
스프링 프레임워크에서 나란히 공존하며 모듈들은 옵션입니다.
어플리케이션은 하나 또는 둘 다 사용할 수 있습니다.
e.g 스프링 MVC 컨트롤러와 리액티브 웹클라이언트
새로운 웹프레임워크가 왜 필요할까?
첫째, 적은 스레드 갯수로 비동기를 다루고 논블럭킹 웹스택과
적은 하드웨어 자원으로 확장이 필요하다는 것이다.서블렛 3.1은
논블럭킹 I/O API를 지원했다. 하지만, 동기(Filter
, Servlet
), 블럭킹(getParameter
, getPart
)은 Servlet API로 부터 멀어지게합니다.
using it leads away from the rest of the Servlet API where contracts are synchronous (Filter
, Servlet
) or blocking (getParameter
,getPart
).
이것이 모든 논블럭킹 런타임에 대해 기반 역할을하는 새로운 공통 API를 설계하게된 동기였습니다.
공통 API는 네티처럼 비동기, 논블럭 기반의 잘만들어진 서버들 때문에 중요합니다.
둘째, 함수형 프로그래밍입니다. Java 5때 어노테이션 추가처럼 Java 8에서도 기회가 생겼습니다. — e.g. 어노테이션이 붙은 REST 컨트롤러나 단위 테스트. 자바8에 람다 표현식이 추가됨은 자바에서 함수형 API를 이용할 기회가 생겼습니다. 이건 논블럭킹 어플리케이션과 continuation 스타일 API에 도움이 됩니다. — `CompletableFuture`나 ReactiveX는 비동기 로직의 선언적 프로그래밍을 지원합니다. 자바8은 스프링 웹플럭스가 어노테이션이 붙은 컨트롤러와 함수형 웹 엔드포인트 두가지를 제공할 수 있게하였습니다.
리액티브: 무엇이고 왜 쓰는거야?
왜 리액티브이며 우리에게 어떤 의미일까?
"리액티브"란 용어는 변화에 반응하는 프로그램 모델입니다. — 네트워크 컨퍼넌트는 I/O 이벤트에 반응하고, UI 컨트롤러는 마우스 이벤트에 반응하고 기타. 그런 의미에서 논블럭킹은 완료 명령(시그널)이나 데이터가 사용할 수 있을 때 반응합니다. 논블럭킹 역압 또한 중요한 메카니즘입니다. 동기, 명령형 코드, 블럭킹 호출에서 클라이언트를 기다리게 강제했습니다.(역주 - request가 처리량 이상 오는경우 응답이 급격히 느려지는 것을 의미하는것으로 보임.) 하지만 논블럭킹 코드는 처리하는 놈의 처리량을 넘치지 않게 이벤트 속도를 조절하는 것이 중요합니다.
reactive streams(역주 - reactive streams 리액티브 라이브러리 표준 인터페이스)는 small spec 와 자바 9의 adopted 이며 이들은 역압과 비동기 구성요소들간 상호작용을 정의합니다. 예를들어 데이터 저장소 — Publisher는 HTTP 서버처럼 데이터를 생성할 수 있습니다. Subscriber는 응답을 쓸수 있습니다. 리액티브 스트림의 주요 목적은 구독자가 퍼블리셔로부터 발생하는 데이터를 조절하는데 있습니다.
리액티브 API
reactive streams는 인터페이스로 중요한 역할을 합니다만
reactive stremas는 너무 로우레벨이라 어플리케이션 API에 유용하지 않습니다. 어플리케이션이 원하는건
비동기 로직을 구성하는데 필요로하는 더 추상화되고 더 풍부한 표현력을 가진 (컬렉션만 적용된 자바 8 Stream
API와 유사한) 함수형 API입니다.
이게 리액티브 라이브러리가 수행하는 역할입니다.
Reactor은 Spring WebFlux를 위해 선택한 리액티브 라이브러리입니다. 이건 Mono 와 Flux API 타입들은 ReactiveX의 vocabulary of operators와 비슷한 풍부한 오퍼레잍터들을 통해 0..1(Mono)과 0..N(Flux)의 데이터 시퀀스에서 작업할 수 있습니다. 리액터는 리액티브 스트림스 라이브러리이며 오퍼레이터는 논블록킹 역압을 지원합니다. 리액터는 서버사이드쪽의 자바에 특화되어있습니다. 스프링과 함께 가깝게 협업하며 개발되고 있습니다.
웹플럭스는 핵심 디펜던시로 리액터를 필요로합니다만 리액티브 스트림스를 통해 다른 리액티브 라이브러리랑 호환됩니다.(역 - Reactive streams는 interface, reactor와 rxjava는 구현체) 일반적으로 웹플럭스 API들은 `Publisher`를 입력으로 받고 내부적으로 Reactor 타입으로 적용시킨다. 그리고 `Flux`나 `Mono`를 결과로 반환합니다. 그럼 당신은 `Publisher`를 입력값으로 전달하고 결과값에 오퍼레이션들을 적용킬수 있다. — e.g. 어노테이션이 붙은 컨트롤러, 웹플럭스는 RxJava나 다른 리액티브 라이브러리를 적용할 수 있습니다. [웹플럭스-리액티브-라이브러리]에 더 상세하게 있습니다.
프로그래밍 모델
`spring-web`모듈은 스프링 웹플럭스의 기초가 되는 리액티브 기반을 포함합니다. — HTTP 추상화, 리액티브 스트림 서버 어댑터, 리액티브 코덱, 핵심 Web API
스프링 웹플럭스는 두가지 프로그래밍 모델 선택할 수 있게 제공합니다.
-
[웹플럭스 컨트롤러] — 스프링 MVC와 일치.
spring-web
모듈과 동일한 어노테이션 기반 컨트롤러. 스프링 MVC와 WebFlux 컨트롤러는 반환 타입으로 리액티브(Reactor, RxJava)를 지원합니다. 그래서 스프링 MVC와 WebFlux를 구별하기란 쉽지 않습니다. -
[웹플럭스-fn] — 가볍고, 람다 기반의 함수형 프로그래밍 모델입니다. 라우팅과 리퀘스트 처리를 할수 있는 작은 라이브러리 또는 유틸리티의 셋으로 생각하세요.
Choosing a web framework
Should you use Spring MVC or WebFlux? Let’s cover a few different perspectives.
If you have a Spring MVC application that works fine, there is no need to change. Imperative programming is the easiest way to write, understand, and debug code. You have maximum choice of libraries since historically most are blocking.
If you are already shopping for a non-blocking web stack, Spring WebFlux offers the same execution model benefits as others in this space and also provides a choice of servers — Netty, Tomcat, Jetty, Undertow, Servlet 3.1+ containers, a choice of programming models — annotated controllers and functional web endpoints, and a choice of reactive libraries — Reactor, RxJava, or other.
If you are interested in a lightweight, functional web framework for use with Java 8 lambdas or Kotlin then use the Spring WebFlux functional web endpoints. That can also be a good choice for smaller applications or microservices with less complex requirements that can benefit from greater transparency and control.
In a microservice architecture you can have a mix of applications with either Spring MVC or Spring WebFlux controllers, or with Spring WebFlux functional endpoints. Having support for the same annotation-based programming model in both frameworks makes it easier to re-use knowledge while also selecting the right tool for the right job.
A simple way to evaluate an application is to check its dependencies. If you have blocking persistence APIs (JPA, JDBC), or networking APIs to use, then Spring MVC is the best choice for common architectures at least. It is technically feasible with both Reactor and RxJava to perform blocking calls on a separate thread but you wouldn’t be making the most of a non-blocking web stack.
If you have a Spring MVC application with calls to remote services, try the reactive WebClient
.
You can return reactive types (Reactor, RxJava, or other)
directly from Spring MVC controller methods. The greater the latency per call, or the
interdependency among calls, the more dramatic the benefits. Spring MVC controllers
can call other reactive components too.
If you have a large team, keep in mind the steep learning curve in the shift to non-blocking,
functional, and declarative programming. A practical way to start without a full switch
is to use the reactive WebClient
. Beyond that start small and measure the benefits.
We expect that for a wide range of applications the shift is unnecessary.
If you are unsure what benefits to look for, start by learning about how non-blocking I/O works (e.g. concurrency on single-threaded Node.js is not an oxymoron) and its effects. The tag line is "scale with less hardware" but that effect is not guaranteed, not without some network I/O that can be slow or unpredictable. This Netflix blog post is a good resource.
Choosing a server
Spring WebFlux is supported on Netty, Undertow, Tomcat, Jetty, and Servlet 3.1+ containers. Each server is adapted to a common Reactive Streams API. The Spring WebFlux programming models are built on that common API.
Note
|
Common question: how can Tomcat and Jetty be used in both stacks? |
Spring Boot 2 uses Netty by default with WebFlux because Netty is more widely used in the async, non-blocking space and also provides both client and server that can share resources. By comparison Servlet 3.1 non-blocking I/O hasn’t seen much use because the bar to use it is so high. Spring WebFlux opens one practical path to adoption.
The default server choice in Spring Boot is mainly about the out-of-the-box experience. Applications can still choose any of the other supported servers which are also highly optimized for performance, fully non-blocking, and adapted to Reactive Streams back pressure. In Spring Boot it is trivial to make the switch.
Performance vs scale
Performance has many characteristics and meanings. Reactive and non-blocking generally
do not make applications run faster. They can, in some cases, for example if using the
WebClient
to execute remote calls in parallel. On the whole it requires more work to do
things the non-blocking way and that can increase slightly the required processing time.
The key expected benefit of reactive and non-blocking is the ability to scale with a small, fixed number of threads and less memory. That makes applications more resilient under load because they scale in a more predictable way. In order to observe those benefits however you need to have some latency including a mix of slow and unpredictable network I/O. That’s where the reactive stack begins to show its strengths and the differences can be dramatic.
Reactive Spring Web
The spring-web
module provides low level infrastructure and HTTP abstractions — client
and server, to build reactive web applications. All public APIs are build around Reactive
Streams with Reactor as a backing implementation.
Server support is organized in two layers:
-
HttpHandler and server adapters — the most basic, common API for HTTP request handling with Reactive Streams back pressure.
-
WebHandler API — slightly higher level but still general purpose server web API with filter chain style processing.
HttpHandler
Every HTTP server has some API for HTTP request handling. {api-spring-framework}/http/server/reactive/HttpHandler.html[HttpHandler] is a simple contract with one method to handle a request and response. It is intentionally minimal. Its main purpose is to provide a common, Reactive Streams based API for HTTP request handling over different servers.
The spring-web
module contains adapters for every supported server. The table below shows
the server APIs are used and where Reactive Streams support comes from:
Server name | Server API used | Reactive Streams support |
---|---|---|
Netty |
Netty API |
|
Undertow |
Undertow API |
spring-web: Undertow to Reactive Streams bridge |
Tomcat |
Servlet 3.1 non-blocking I/O; Tomcat API to read and write ByteBuffers vs byte[] |
spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge |
Jetty |
Servlet 3.1 non-blocking I/O; Jetty API to write ByteBuffers vs byte[] |
spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge |
Servlet 3.1 container |
Servlet 3.1 non-blocking I/O |
spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge |
Here are required dependencies, supported versions, and code snippets for each server:
Server name | Group id | Artifact name |
---|---|---|
Reactor Netty |
io.projectreactor.ipc |
reactor-netty |
Undertow |
io.undertow |
undertow-core |
Tomcat |
org.apache.tomcat.embed |
tomcat-embed-core |
Jetty |
org.eclipse.jetty |
jetty-server, jetty-servlet |
Reactor Netty:
HttpHandler handler = ...
ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler);
HttpServer.create(host, port).newHandler(adapter).block();
Undertow:
HttpHandler handler = ...
UndertowHttpHandlerAdapter adapter = new UndertowHttpHandlerAdapter(handler);
Undertow server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build();
server.start();
Tomcat:
HttpHandler handler = ...
Servlet servlet = new TomcatHttpHandlerAdapter(handler);
Tomcat server = new Tomcat();
File base = new File(System.getProperty("java.io.tmpdir"));
Context rootContext = server.addContext("", base.getAbsolutePath());
Tomcat.addServlet(rootContext, "main", servlet);
rootContext.addServletMappingDecoded("/", "main");
server.setHost(host);
server.setPort(port);
server.start();
Jetty:
HttpHandler handler = ...
Servlet servlet = new JettyHttpHandlerAdapter(handler);
Server server = new Server();
ServletContextHandler contextHandler = new ServletContextHandler(server, "");
contextHandler.addServlet(new ServletHolder(servlet), "/");
contextHandler.start();
ServerConnector connector = new ServerConnector(server);
connector.setHost(host);
connector.setPort(port);
server.addConnector(connector);
server.start();
Note
|
To deploy as a WAR to a Servlet 3.1+ container, wrap |
WebHandler API
HttpHandler
is the basis for running on different servers. On that base the WebHandler
API provides a slightly higher level processing chain of
exception handlers
({api-spring-framework}/web/server/WebExceptionHandler.html[WebExceptionHandler]), filters
({api-spring-framework}/web/server/WebFilter.html[WebFilter]), and a target handler
({api-spring-framework}/web/server/WebHandler.html[WebHandler]).
All components work on ServerWebExchange
— a container for the HTTP request and
response that also adds request attributes, session attributes, access to form data,
multipart data, and more.
The processing chain can be put together with WebHttpHandlerBuilder
which builds an
HttpHandler
that in turn can be run with a server adapter.
To use the builder either add components individually or point to an ApplicationContext
to have the following detected:
Bean name | Bean type | Count | Description |
---|---|---|---|
"webHandler" |
WebHandler |
1 |
Target handler after filters |
<any> |
WebFilter |
0..N |
Filters |
<any> |
WebExceptionHandler |
0..N |
Exception handlers after filter chain |
"webSessionManager" |
WebSessionManager |
0..1 |
Custom session manager; |
"serverCodecConfigurer" |
ServerCodecConfigurer |
0..1 |
Custom form and multipart data decoders; |
"localeContextResolver" |
LocaleContextResolver |
0..1 |
Custom resolver for |
Codecs
The spring-web
module provides
{api-spring-framework}/http/codec/HttpMessageReader.html[HttpMessageReader] and
{api-spring-framework}/http/codec/HttpMessageWriter.html[HttpMessageWriter]
for encoding and decoding the HTTP request and response body with Reactive Streams.
It builds on lower level contracts from spring-core
:
-
{api-spring-framework}/core/io/buffer/DataBuffer.html[DataBuffer] — abstraction for byte buffers — e.g. Netty
ByteBuf
,java.nio.ByteBuffer
-
{api-spring-framework}/core/codec/Encoder.html[Encoder] — serialize a stream of Objects to a stream of data buffers
-
{api-spring-framework}/core/codec/Decoder.html[Decoder] — deserialize a stream of data buffers into a stream of Objects
Basic Encoder
and Decoder
implementations exist in spring-core
but spring-web
adds
more for JSON, XML, and other formats. You can wrap any Encoder
and Decoder
as a reader
or writer with EncoderHttpMessageWriter
and DecoderHttpMessageReader
. There are some
additional, web-only reader and writer implementations for server-sent events, form data,
and more.
Finally, ClientCodecConfigurer
and ServerCodecConfigurer
can be used to initialize
a list of readers and writers. They include support for classpath detection and a
of defaults along with the ability to override or replace those defaults.
DispatcherHandler
Spring WebFlux, like Spring MVC, is designed around the front controller pattern where a
central WebHandler
, the DispatcherHandler
, provides a shared algorithm for request
processing while actual work is performed by configurable, delegate components.
This model is flexible and supports diverse workflows.
DispatcherHandler
discovers the delegate components it needs from Spring configuration.
It is also designed to be a Spring bean itself and implements ApplicationContextAware
for access to the context it runs in. If DispatcherHandler
is declared with the bean
name "webHandler" it is in turn discovered by
{api-spring-framework}/web/server/adapter/WebHttpHandlerBuilder.html[WebHttpHandlerBuilder]
which puts together a request processing chain as described in
WebHandler API.
Spring configuration in a WebFlux application typically contains:
-
DispatcherHandler
with the bean name "webHandler" -
WebFilter
andWebExceptionHandler
beans -
Others
The configuration is given to WebHttpHandlerBuilder
to build the processing chain:
ApplicationContext context = ...
HttpHandler handler = WebHttpHandlerBuilder.applicationContext(context);
The resulting HttpHandler
is ready for use with a
server adapter.
Special bean types
The DispatcherHandler
delegates to special beans to process requests and render the
appropriate responses. By "special beans" we mean Spring-managed Object instances that
implement one of the framework contracts listed in the table below.
Spring WebFlux provides built-in implementations of these contracts but you can also
customize, extend, or replace them.
Bean type | Explanation |
---|---|
HandlerMapping |
Map a request to a handler. The mapping is based on some criteria the details of
which vary by The main |
HandlerAdapter |
Help the |
HandlerResultHandler |
Process the result from the handler invocation and finalize the response. The built-in |
Framework Config
The DispatcherHandler
detects the special beans it needs in the ApplicationContext
.
Applications can declare the special beans they wish to have. However most applications
will find a better starting point in the WebFlux Java config which provide a higher level
configuration API that in turn make the necessary bean declarations.
See WebFlux Java Config for more details.
Processing
The DispatcherHandler
processes requests as follows:
-
Each
HandlerMapping
is asked to find a matching handler and the first match is used. -
If a handler is found, it is executed through an appropriate
HandlerAdapter
which exposes the return value from the execution asHandlerResult
. -
The
HandlerResult
is given to an appropriateHandlerResultHandler
to complete processing by writing to the response directly or using a view to render.
Annotated Controllers
Spring WebFlux provides an annotation-based programming model where @Controller
and
@RestController
components use annotations to express request mappings, request input,
exception handling, and more. Annotated controllers have flexible method signatures and
do not have to extend base classes nor implement specific interfaces.
Here is a basic example:
@RestController
public class HelloController {
@GetMapping("/hello")
public String handle() {
return "Hello WebFlux";
}
}
In this example the methods returns a String to be written to the response body.
@Controller
You can define controller beans using a standard Spring bean definition.
The @Controller
stereotype allows for auto-detection, aligned with Spring general support
for detecting @Component
classes in the classpath and auto-registering bean definitions
for them. It also acts as a stereotype for the annotated class, indicating its role as
a web component.
To enable auto-detection of such @Controller
beans, you can add component scanning to
your Java configuration:
@Configuration
@ComponentScan("org.example.web")
public class WebConfig {
// ...
}
@RestController
is a composed annotation that is itself annotated with
@Controller
and @ResponseBody
indicating a controller whose every method inherits the type-level
@ResponseBody
annotation and therefore writes to the response body (vs model-and-vew
rendering).
Request Mapping
The @RequestMapping
annotation is used to map requests to controllers methods. It has
various attributes to match by URL, HTTP method, request parameters, headers, and media
types. It can be used at the class-level to express shared mappings or at the method level
to narrow down to a specific endpoint mapping.
There are also HTTP method specific shortcut variants of @RequestMapping
:
-
@GetMapping
-
@PostMapping
-
@PutMapping
-
@DeleteMapping
-
@PatchMapping
The shortcut variants are
composed annotations — themselves annotated with @RequestMapping
. They are commonly used at the method level.
At the class level an @RequestMapping
is more useful for expressing shared mappings.
@RestController
@RequestMapping("/persons")
class PersonController {
@GetMapping("/{id}")
public Person getPerson(@PathVariable Long id) {
// ...
}
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public void add(@RequestBody Person person) {
// ...
}
}
URI Patterns
You can map requests using glob patterns and wildcards:
-
?
matches one character -
*
matches zero or more characters within a path segment -
**
match zero or more path segments
You can also declare URI variables and access their values with @PathVariable
:
@GetMapping("/owners/{ownerId}/pets/{petId}")
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
// ...
}
URI variables can be declared at the class and method level:
@Controller
@RequestMapping("/owners/{ownerId}")
public class OwnerController {
@GetMapping("/pets/{petId}")
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
// ...
}
}
URI variables are automatically converted to the appropriate type or`TypeMismatchException`
is raised. Simple types — int
, long
, Date
, are supported by default and you can
register support for any other data type.
URI variables can be named explicitly — e.g. @PathVariable("customId")
, but you can
leave that detail out if the names are the same and your code is compiled with debugging
information or with the -parameters
compiler flag on Java 8.
The syntax {*varName}
declares a URI variable that matches zero or more remaining
path segments. For example /resources/{*path}
matches all files /resources/
and the
"path"
variable captures the complete relative path.
The syntax {varName:regex}
declares a URI variable with a regular expressions with the
syntax {varName:regex}
— e.g. given URL "/spring-web-3.0.5 .jar"
, the below method
extracts the name, version, and file extension:
@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
public void handle(@PathVariable String version, @PathVariable String ext) {
// ...
}
URI path patterns can also have embedded ${…}
placeholders that are resolved on startup
via PropertyPlaceHolderConfigurer
against local, system, environment, and other property
sources. This can be used for example to parameterize a base URL based on some external
configuration.
Note
|
Spring WebFlux uses |
Spring WebFlux does not support suffix pattern matching — unlike Spring MVC, where a
mapping such as /person
also matches to /person.*
. For URL based content
negotiation, if needed, we recommend using a query parameter, which is simpler, more
explicit, and less vulnerable to URL path based exploits.
Pattern Comparison
When multiple patterns match a URL, they must be compared to find the best match. This is done
with PathPattern.SPECIFICITY_COMPARATOR
which looks for patterns that more specific.
For every pattern, a score is computed based the number of URI variables and wildcards where a URI variable scores lower than a wildcard. A pattern with a lower total score wins. If two patterns have the same score, then the longer is chosen.
Catch-all patterns, e.g. **
, {*varName}
, are excluded from the scoring and are always
sorted last instead. If two patterns are both catch-all, the longer is chosen.
Consumable Media Types
You can narrow the request mapping based on the Content-Type
of the request:
@PostMapping(path = "/pets", consumes = "application/json")
public void addPet(@RequestBody Pet pet) {
// ...
}
The consumes attribute also supports negation expressions — e.g. !text/plain
means any
content type other than "text/plain".
You can declare a shared consumes attribute at the class level. Unlike most other request mapping attributes however when used at the class level, a method-level consumes attribute will overrides rather than extend the class level declaration.
Tip
|
|
Producible Media Types
You can narrow the request mapping based on the Accept
request header and the list of
content types that a controller method produces:
@GetMapping(path = "/pets/{petId}", produces = "application/json;charset=UTF-8")
@ResponseBody
public Pet getPet(@PathVariable String petId) {
// ...
}
The media type can specify a character set. Negated expressions are supported — e.g.
!text/plain
means any content type other than "text/plain".
You can declare a shared produces attribute at the class level. Unlike most other request mapping attributes however when used at the class level, a method-level produces attribute will overrides rather than extend the class level declaration.
Tip
|
|
Parameters and Headers
You can narrow request mappings based on query parameter conditions. You can test for the
presence of a query parameter ("myParam"
), for the absence ("!myParam"
), or for a
specific value ("myParam=myValue"
):
@GetMapping(path = "/pets/{petId}", params = "myParam=myValue")
public void findPet(@PathVariable String petId) {
// ...
}
You can also use the same with request header conditions:
@GetMapping(path = "/pets", headers = "myHeader=myValue")
public void findPet(@PathVariable String petId) {
// ...
}
HTTP HEAD, OPTIONS
@GetMapping
— and also @RequestMapping(method=HttpMethod.GET)
, support HTTP HEAD
transparently for request mapping purposes. Controller methods don’t need to change.
A response wrapper, applied in the HttpHandler
server adapter, ensures a "Content-Length"
header is set to the number of bytes written and without actually writing to the response.
By default HTTP OPTIONS is handled by setting the "Allow" response header to the list of HTTP
methods listed in all @RequestMapping
methods with matching URL patterns.
For a @RequestMapping
without HTTP method declarations, the "Allow" header is set to
"GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS"
. Controller methods should always declare the
supported HTTP methods for example by using the HTTP method specific variants — @GetMapping
, @PostMapping
, etc.
@RequestMapping
method can be explicitly mapped to HTTP HEAD and HTTP OPTIONS, but that
is not necessary in the common case.
Handler methods
@RequestMapping
handler methods have a flexible signature and can choose from a range of
supported controller method arguments and return values.
Method arguments
The table below shows supported controller method arguments.
Reactive types (Reactor, RxJava, or other) are supported on arguments that require blocking I/O, e.g. reading the request body, to be resolved. This is marked in the description column. Reactive types are not expected on arguments that don’t require blocking.
JDK 1.8’s java.util.Optional
is supported as a method argument in combination with
annotations that have a required
attribute — e.g. @RequestParam
, @RequestHeader
,
etc, and is equivalent to required=false
.
Controller method argument | Description |
---|---|
|
Access to the full |
|
Access to the HTTP request or response. |
|
Access to the session; this does not forcing the start of a new session unless attributes are added. Supports reactive types. |
|
Currently authenticated user; possibly a specific |
|
The HTTP method of the request. |
|
The current request locale, determined by the most specific |
Java 6+: |
The time zone associated with the current request, as determined by a |
|
For access to URI template variables. |
|
For access to name-value pairs in URI path segments. |
|
For access to Servlet request parameters. Parameter values are converted to the declared method argument type. |
|
For access to request headers. Header values are converted to the declared method argument type. |
|
For access to the HTTP request body. Body content is converted to the declared method
argument type using |
|
For access to request headers and body. The body is converted with |
|
For access to a part in a "multipart/form-data" request. Supports reactive types. |
|
For access and updates of the implicit model that is exposed to the web view. |
Command or form object (with optional |
Command object whose properties to bind to request parameters — via setters or directly to
fields, with customizable type conversion, depending on Command objects along with their validation results are exposed as model attributes, by
default using the command class name - e.g. model attribute "orderAddress" for a command
object of type "some.package.OrderAddress". Supports reactive types. |
|
Validation results for the command/form object data binding; this argument must be declared immediately after the command/form object in the controller method signature. |
|
For marking form processing complete which triggers cleanup of session attributes
declared through a class-level |
|
For preparing a URL relative to the current request’s host, port, scheme, context path, and
the literal part of the servlet mapping also taking into account |
|
For access to any session attribute; in contrast to model attributes stored in the session
as a result of a class-level |
|
For access to request attributes. |
Return values
The table below shows supported controller method return values. Reactive types — Reactor, RxJava, or other are supported for all return values.
Controller method return value | Description |
---|---|
|
The return value is encoded through |
|
The return value specifies the full response including HTTP headers and body be encoded
through |
|
For returning a response with headers and no body. |
|
A view name to be resolved with |
|
A |
|
Attributes to be added to the implicit model with the view name implicitly determined from the request path. |
|
An API for model and view rendering scenarios. |
|
A method with a If none of the above is true, a |
|
Emit server-sent events; the |
Any other return type |
A single model attribute to be added to the implicit model with the view name implicitly
determined through a |
Unresolved directive in <stdin> - include::webflux-functional.adoc[leveloffset=+1]
WebFlux Java Config
The WebFlux Java config provides default configuration suitable for most applications along with a configuration API to customize it. For more advanced customizations, not available in the configuration API, see Advanced config mode.
You do not need to understand the underlying beans created by the Java config, but it’s
easy to seem them in WebFluxConfigurationSupport
, and if you want to learn more, see
Special bean types.
Enable WebFlux config
Use the @EnableWebFlux
annotation in your Java config:
@Configuration
@EnableWebFlux
public class WebConfig {
}
The above registers a number of Spring WebFlux infrastructure beans also adapting to dependencies available on the classpath — for JSON, XML, etc.
WebFlux config API
In your Java config implement the WebFluxConfigurer
interface:
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
// Implement configuration methods...
}
Conversion, formatting
By default formatters for Number
and Date
types are installed, including support for
the @NumberFormat
and @DateTimeFormat
annotations. Full support for the Joda Time
formatting library is also installed if Joda Time is present on the classpath.
To register custom formatters and converters:
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
@Override
public void addFormatters(FormatterRegistry registry) {
// ...
}
}
Note
|
See FormatterRegistrar SPI
and the |
Validation
By default if Bean Validation is present
on the classpath — e.g. Hibernate Validator, the LocalValidatorFactoryBean
is registered
as a global Validator for use with @Valid
and Validated
on
@Controller
method arguments.
In your Java config, you can customize the global Validator
instance:
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
@Override
public Validator getValidator(); {
// ...
}
}
Note that you can also register Validator
's locally:
@Controller
public class MyController {
@InitBinder
protected void initBinder(WebDataBinder binder) {
binder.addValidators(new FooValidator());
}
}
Tip
|
If you need to have a |
Content type resolvers
You can configure how Spring WebFlux determines the requested media types for
@Controller
's from the request. By default only the "Accept" header is checked but you
can also enable a query parameter based strategy.
To customize the requested content type resolution:
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
@Override
public void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
// ...
}
}
HTTP message codecs
To customize how the request and response body are read and written:
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
@Override
public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
// ...
}
}
ServerCodecConfigurer
provides a set of default readers and writers. You can use it to add
more readers and writers, customize the default ones, or replace the default ones completely.
For Jackson JSON and XML, consider using the {api-spring-framework}/http/converter/json/Jackson2ObjectMapperBuilder.html[Jackson2ObjectMapperBuilder] which customizes Jackson’s default properties with the following ones:
-
DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES
is disabled. -
MapperFeature.DEFAULT_VIEW_INCLUSION
is disabled.
It also automatically registers the following well-known modules if they are detected on the classpath:
-
jackson-datatype-jdk7: support for Java 7 types like
java.nio.file.Path
. -
jackson-datatype-joda: support for Joda-Time types.
-
jackson-datatype-jsr310: support for Java 8 Date & Time API types.
-
jackson-datatype-jdk8: support for other Java 8 types like
Optional
.
View resolvers
To configure view resolution:
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
@Override
public void configureViewResolvers(ViewResolverRegistry registry) {
// ...
}
}
Note that FreeMarker also requires configuration of the underlying view technology:
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
// ...
@Bean
public FreeMarkerConfigurer freeMarkerConfigurer() {
FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
configurer.setTemplateLoaderPath("classpath:/templates");
return configurer;
}
}
Static resources
This option provides a convenient way to serve static resources from a list of {api-spring-framework}/core/io/Resource.html[Resource]-based locations.
In the example below, given a request that starts with "/resources"
, the relative path is
used to find and serve static resources relative to "/static"
on the classpath. Resources
will be served with a 1-year future expiration to ensure maximum use of the browser cache
and a reduction in HTTP requests made by the browser. The Last-Modified
header is also
evaluated and if present a 304
status code is returned.
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/resources/**")
.addResourceLocations("/public", "classpath:/static/")
.setCachePeriod(31556926);
}
}
The resource handler also supports a chain of {api-spring-framework}/web/reactive/resource/ResourceResolver.html[ResourceResolver]'s and {api-spring-framework}/web/reactive/resource/ResourceTransformer.html[ResourceTransformer]'s. which can be used to create a toolchain for working with optimized resources.
The VersionResourceResolver
can be used for versioned resource URLs based on an MD5 hash
computed from the content, a fixed application version, or other. A
ContentVersionStrategy
(MD5 hash) is a good choice with some notable exceptions such as
JavaScript resources used with a module loader.
For example in your Java config;
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/resources/**")
.addResourceLocations("/public/")
.resourceChain(true)
.addResolver(new VersionResourceResolver().addContentVersionStrategy("/**"));
}
}
You can use ResourceUrlProvider
to rewrite URLs and apply the full chain of resolvers and
transformers — e.g. to insert versions. The WebFlux config provides a ResourceUrlProvider
so it can be injected into others.
Unlike Spring MVC at present in WebFlux there is no way to transparely rewrite static
resource URLs since the are no view technologies that can make use of a non-blocking chain
of resolvers and transformers (e.g. resources on Amazon S3). When serving only local
resources the workaround is to use ResourceUrlProvider
directly (e.g. through a custom
tag) and block for 0 seconds.
WebJars is also supported via WebJarsResourceResolver
and automatically registered when "org.webjars:webjars-locator"
is present on the
classpath. The resolver can re-write URLs to include the version of the jar and can also
match to incoming URLs without versions — e.g. "/jquery/jquery.min.js"
to
"/jquery/1.2.0/jquery.min.js"
.
Path Matching
Spring WebFlux uses parsed representation of path patterns — i.e. PathPattern
, and also
the incoming request path — i.e. RequestPath
, which eliminates the need to indicate
whether to decode the request path, or remove semicolon content, since PathPattern
can now access decoded path segment values and match safely.
Spring WebFlux also does not support suffix pattern matching so effectively there are only two
minor options to customize related to path matching — whether to match trailing slashes
(true
by default) and whether the match is case-sensitive (false
).
To customize those options:
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {
@Override
public void configurePathMatch(PathMatchConfigurer configurer) {
// ...
}
}
Advanced config mode
@EnableWebFlux
imports DelegatingWebFluxConfiguration
that (1) provides default
Spring configuration for WebFlux applications and (2) detects and delegates to
WebFluxConfigurer
's to customize that configuration.
For advanced mode, remove @EnableWebFlux
and extend directly from
DelegatingWebFluxConfiguration
instead of implementing WebFluxConfigurer
:
@Configuration
public class WebConfig extends DelegatingWebFluxConfiguration {
// ...
}
You can keep existing methods in WebConfig
but you can now also override bean declarations
from the base class and you can still have any number of other WebMvcConfigurer
's on
the classpath.
HTTP/2
Servlet 4 containers are required to support HTTP/2 and Spring Framework 5 is compatible with Servlet API 4. From a programming model perspective there is nothing specific that applications need to do. However there are considerations related to server configuration. For more details please check out the HTTP/2 wiki page.
Currently Spring WebFlux does not support HTTP/2 with Netty. There is also no support for pushing resources programmatically to the client.