Spring WebFlux (1)

스프링 리액티브 웹 스택 공식 레퍼런스를 한글로 번역한 문서입니다.

전체 목차는 여기에 있습니다.

스프링 프레임워크, 스프링 웹 MVC를 포함한 기존 웹 프레임워크는 서블릿 API와 서블릿 컨테이너를 위해 개발됐다. 5.0 버전에 추가된 스프링 웹플럭스는 리액티브 스택 웹 프레임워크다. 완전하게 논블로킹으로 동작하며, Reactive Streams back pressure를 지원하고, Netty, Undertow, 서블릿 3.1+ 컨테이너 서버에서 실행된다.

두 웹 프레임워크 모두 소스 모듈 이름과 동일하며(spring-webmvc, spring-webflux), 스프링 프레임워크에 공존한다. 원하는 모듈을 선택하면 된다. 둘 중 하나를 사용해 어플리케이션을 개발할 수 있고, 둘 다 사용할 수도 있다 (예를 들어, 스프링 MVC 컨트롤러에서 리액티브 WebClient를 사용하는 식으로).

1.1. Overview

스프링 웹플럭스는 왜 만들었나?

웹플럭스가 탄생한 이유 중 하나는 적은 쓰레드로 동시 처리를 제어하고 적은 하드웨어 리소스로 확장하기 위해 논블로킹 웹 스택이 필요했기 때문이다. 이전에도 서블릿 3.1은 논블로킹 I/O를 위한 API를 제공했다. 하지만 서블릿으로 논블로킹을 구현하려면 다른 동기 처리나(Filter, Servlet) 블로킹 방식(getParameter, getPart)을 쓰는 API를 사용하기 어렵다. 이런 점 때문에 어떤 논블로킹과도 잘 동작하는 새 공통 API를 만들게 됐다. 이미 비동기 논블로킹 환경에서 자리를 잡은 서버(e.g. Netty) 때문에라도 새 API가 필요했다.

또 다른 이유는 함수형 프로그래밍이다. 자바 5의 어노테이션 등장으로 선택의 폭이 넓어진 것처럼(어노테이션을 선언한 REST 컨트롤러나 유닛 테스트 등), 자바 8에서 추가된 람다 표현식덕분에 자바에서도 함수형 API를 작성할 수 있게 됐다. 이 기능은 논블로킹 어플리케이션을 만들 때도 요긴하게 쓰이며, 이제는 continuation-style API(CompletableFuture와 ReactiveX로 대중화된)로 비동기 로직을 선언적으로 작성할 수 있다. 프로그래밍 모델 관점에서 보면, 웹플럭스에서 어노테이션을 선언한 컨트롤러와 더불어 함수형 웹 엔드포인트를 사용할 수 있는 건 자바 8 덕분이다.

1.1.1. Define “Reactive”

이제 “논블로킹”과 “함수형”이 뭔지 알게 되었는데, 그러면 리액티브는 무슨 뜻일까?

“리액티브”라는 용어는 변화에 반응하는 것을 중심에 두고 만든 프로그래밍 모델을 의미한다 (I/O 이벤트에 반응하는 네트워크 컴포넌트, 마우스 이벤트에 반응하는 UI 컨트롤러 등). 논블로킹은 작업을 기다리기보단 완료되거나 데이터를 사용할 수 있게 되면 반응하므로, 이 말대로면 논블로킹도 리액티브다.

스프링은 “리액티브”와 관련한 중요한 메커니즘이 하나 더 있는데, 논블로킹 back pressure다. 동기식 명령형(imperative) 코드에서 블로킹 호출은 호출자를 강제로 기다리게 하는 일종의 back pressure다. 논블로킹 코드에선, 프로듀셔 속도가 컨슈머 속도를 압도하지 않도록 이벤트 속도를 제어한다.

리액티브 스트림은 back pressure를 통한 비동기 컴포넌트 간의 상호작용을 정의한 간단한 스펙이다(자바 9에서도 채택했다). 예를 들어 데이터 레포지토리(Publisher 역할)가 데이터를 만들고, HTTP 서버(Subscriber 역할)로 이 데이터로 요청을 처리할 수 있다. 리액티브 스트림을 쓰는 주목적은 subscriber가 publisher의 데이터 생산 속도를 제어하는 것이다.

자주 묻는 질문: publisher 속도를 늦출 수 없으면 어떻게 할까?

리액티브 스트림의 목적은 메커니즘과 경계를 확립하는 것이다. publisher가 속도를 늦출 수 없다면 버퍼에 담을지, 데이터를 날릴지, 실패로 처리할지 결정해야 한다.

1.1.2. Reactive API

리액티브 스트림은 컴포넌트 상호 작용에서 중요한 역할을 한다. 하지만 이건 라이브러리와 기반 구조에 사용되는 컴포넌트엔 유용해도, 어플리케이션 API에서 다루기엔 너무 저수준이다. 어플리케이션은 비동기 로직을 만들기 위한 풍부한 고수준 함수형 API가 필요하다 (자바 8 스트림 API와 비슷하지만 컬렉션만을 위한 게 아니다). 이게 바로 리액티브 라이브러리가 하는 일이다.

Reactor는 스프링 웹플럭스가 선택한 리액티브 라이브러리다. 리액터는 Mono와 Flux API 타입을 제공한다. ReactiveX vocabulary of operators에 정리된 풍부한 연산자를 사용해 데이터 시퀀스를 0~1개는 Mono, 0~N개는 Flux로 표현할 수 있다. 리액터는 리액티브 스트림 라이브러리이기 때문에 모든 연산자는 논블로킹 back pressure를 지원한다. 리액터는 특히 서버 사이드 자바에 초점을 두고 스프링과 긴밀히 협력해서 개발됐다.

웹플럭스는 리액터를 핵심 라이브러리로 사용하지만, 다른 리액티브 라이브러리를 써도 리액티브 스트림으로 상호작용할 수 있다. 웹플럭스 API의 일반적인 룰은, 순수한 Publisher를 입력으로 받아 내부적으로 리액터 타입으로 맞추고, 이걸 사용해서 Flux나 Mono를 반환한다. 따라서 어떤 Publisher든 입력으로 전달하고 연산할 수 있지만, 다른 리액티브 라이브러리를 사용하려면 출력 형식을 맞춰줘야 한다. 웹플럭스는 가능만 하다면 (e.g. 어노테이션을 선언한 컨트롤러) 투명한 방식으로 RxJava나 다른 리액티브 라이브러리에 맞게 바꿔준다. 자세한 내용은 Reactive Libraries를 참고하라.

리액티브 API와는 별개로 웹플럭스는 코틀린의 코루틴 API와도 사용할 수 있는데, 이를 사용하면 좀 더 명령적(imperative)인 프로그래밍이 가능하다. 뒤에 나오는 코틀린 코드 샘플은 코루틴 API를 사용할 것이다.

1.1.3. Programming Models

spring-web 모듈에 있는 웹플럭스는, 여러 서버를 지원하기 위한 HTTP 추상화와 리액티브 스트림 어댑터, 코덱, Servlet API에 상응하는 코어 WebHandler API를 아우르는 개념이며, 이는 모두 논블로킹이다.

스프링 웹플럭스는 두 가지 프로그래밍 모델을 지원한다:

Annotated Controllers: 스프링 MVC와 동일하며 spring-web 모듈에 있는 같은 어노테이션을 사용한다. 스프링 MVC와 웹플럭스 컨트롤러 모두 리액티브(Reactor, RxJava) 리턴 타입을 지원하기 때문에 이 둘을 구분하기 어렵다. 한 가지 눈에 띄는 차이는 웹플럭스에선 @RequestBody로 리액티브 인자를 받을 수 있다는 것이다.
Functional Endpoints: 경량화된 람다 기반 함수형 프로그래밍 모델. 요청을 라우팅해주는 조그만한 라이브러리나 유틸리티 모음이라고 생각하면 된다. annotated controller와 다른 점은 어노테이션으로 의도를 선언해서 콜백 받기보단 요청을 어플리케이션이 처음부터 끝까지 다 제어한다는 것이다.

1.1.4. Applicability

스프링 MVC냐 웹플럭스냐?

많이들 하는 질문이지만 이분법적 사고는 좋지 않다. 둘 모두 선택의 폭을 넓혀준다고 보는 게 맞다. 이 둘은 지속성과 일관성을 위해 설계했으며, 함께 사용할 수 있고, 각자의 피드백이 서로에게 도움이 된다. 다음은 둘은 어떤 관련이 있는지, 공통점이 무엇이고 한쪽에서만 지원하는 게 무엇인지 나타낸 다이어그램이다:

Spring MVC VS WebFlux

먼저 다음 제안을 고려해 보라:

이미 잘 동작하고 있는 스프링 MVC 어플리케이션이 있다면, 굳이 바꿀 필요 없다. 명령적(Imperative) 프로그래밍은 작성하기도, 이해하기도, 디버깅하기도 가장 쉽다. 지금까지 대부분이 블로킹 방식을 사용했기 때문에, 사용할 수 있는 라이브러리가 가장 풍부하다.
이미 논블로킹 웹 스택을 알아보고 있다면, 스프링 웹플럭스는 다른 웹 스택과 같은 실행 환경을 제공하면서도, 다양한 서버(Netty, Tomcat, Jetty, Undertow, 서블릿 3.1+ 컨테이너)와 여러 리액티브 라이브러리(리액터, JxJava 등)를 지원하며, 두 가지 프로그래밍 모델(어노테이션을 선언한 컨트롤러와 함수형 웹 엔드포인트)을 사용할 수 있다.
자바 8 람다나 코틀린으로 개발할 수 있는 경량의 함수형 웹 프레임워크를 찾고 있다면, 스프링 웹플럭스의 함수형 웹 엔드포인트를 사용하면 된다. 로직을 투명하게 제어할 수 있기 때문에 요구사항이 덜 복잡한 소규모 어플리케이션이나 마이크로서비스에서도 좋은 선택이 될 것이다.
마이크로 아키텍처에선 스프링 MVC로 만든 어플리케이션과, 스프링 웹플럭스 컨트롤러나 함수형 엔트포인트를 사용한 어플리케이션을 조합할 수 있다. 두 프레임워크 모두 어노테이션 기반 프로그래밍 모델을 지원하기 때문에 새로 학습할 필요 없이 각자에 맞는 툴을 선택할 수 있다.
간단하게는 어플리케이션 의존성(dependency)을 확인해봐도 좋다. 블로킹 방식의 영속성 API(JPA, JDBC)나 네트워크 API를 사용하고 있다면 스프링 MVC가 최소한 아키텍처를 통일할 수 있으므로 가장 좋은 선택이다. 리액터나 RxJava로도 각 쓰레드에서 블로킹 API를 호출할 수 있지만, 이렇게 하면 논블로킹 웹 스택을 거의 활용하기 어렵다.
스프링 MVC 어플리케이션에서 외부 서비스를 호출한다면 한번 리액티브 WebClient를 사용해봐라. 스프링 MVC 컨트롤러 메소드에서도 리액티브 타입(Reactor, RxJava나 그 외)을 반환할 수 있다. 서비스 호출에 지연이 있거나 여러 서비스가 엮여 있는 API라면 효과가 더 좋을 것이다. 물론 다른 리액티브 컴포넌트도 스프링 MVC 컨트롤러에서 호출할 수 있다.
팀 규모가 크다면 논블로킹, 함수형, 선언적 프로그래밍은 러닝커브가 높다는 점도 고려해야 한다. 한 번에 전환하지 않고 리액티브 WebClient부터 적용해보는 것도 좋은 방법이다. 작은 것부터 시작해서 변화가 있는지 확인해 봐라. 굳이 전환할 필요가 없는 경우도 많을 것이다. 어떤 변화를 확인해야 할지 감이 오지 않는다면, 논블로킹 I/O 동작 방식과 효과를 학습하는 것부터 시작해라(예를 들어 싱글 쓰레드 기반 Node.js의 동시 처리).

1.1.5. Servers

스프링 웹플럭스는 톰캣, Jetty, 서블릿 3.1+ 컨테이너에서도, 서블릿 기반이 아닌 Netty나 Undertow에서도 잘 동작한다. 저수준 공통 API로 서버를 추상화하기 때문에 모든 서버에 고수준 프로그래밍 모델을 적용할 수 있다.

스프링 웹플럭스엔 서버 기동이나 중단을 위한 내장 기능은 없다. 하지만 스프링 설정과 웹플럭스 구조를 조립해 적은 코드로 손쉽게 어플리케이션을 실행할 수 있다.

스프링 부트에선 웹플럭스 스타터가 이 단계를 자동화해준다. 스타터는 기본으로 Netty를 사용하지만, 메이븐이나 그래들 dependency만 수정하면 톰캣이나 Jetty, Undertow로 쉽게 교체할 수 있다. 스프링 부트가 Netty를 디폴트로 사용하는 이유는 보통 비동기 논블로킹에 많이 사용하기도 하고, 클라이언트와 서버가 리소스를 공유할 수 있어서다.

톰캣과 Jetty는 스프링 MVC, 웹플럭스 모두 사용할 수 있다. 하지만 동작 방식이 다르다는 점에 주의하라. 스프링 MVC는 서블릿의 블로킹 I/O를 사용하며, 어플리케이션에서 필요하면 서블릿 API를 직접 사용할 수 있다. 스프링 웹플럭스는 서블릿 3.1 논블로킹 I/O로 동작하며, 서블릿 API는 저수준 어댑터에서 사용하기 때문에 노출돼 있지 않다.

스프링 웹플럭스에서 Undertow를 사용할 때는 서블릿 API가 아닌 Undertow API를 사용한다.

1.1.6. Performance

성능은 여러 의미로 해석할 수 있다. 리액티브랑 논블로킹을 사용한다고 해서 바로 어플리케이션이 빨라지는 건 아니다. 물론 빨라질 수도 있다 (예를 들어 WebClient를 사용해서 외부 서비스 호출을 병렬로 처리한다면). 전반적으로 보면 논블로킹 방식이 처리할 일이 더 많다 보니 처리 시간이 약간 더 길어질 수 있다.

리액티브와 논블로킹의 주된 이점은 고정된 적은 쓰레드와 적은 메모리로도 확장할 수 있다는 것이다. 예측할 수 있는 방법으로 확장하기 때문에 부하 속에서도 어플리케이션 복원 능력은 더 좋아진다. 하지만 이를 확인하려면 약간의 대기 시간이 필요하다 (느리고 예측 불가능한 네트워크 I/O 시간을 포함해서). 바로 여기서 리액티브 스택이 강점을 드러내며, 그 차이는 엄청나다.

1.1.7. Concurrency Model

스프링 MVC와 스프링 웹플럭스 둘 다 annotated controller를 사용할 수 있다는 점은 동일해도, 동시성 모델과 블로킹/쓰레드 기본 전략이 다르다.

스프링 MVC는 (그리고 일반적인 서블릿 어플리케이션이라면) 어플리케이션이 처리 중인 쓰레드가 잠시 중단될 수 있다(예를 들어 외부 서비스를 호출하면). 그렇기 때문에 서블릿 컨테이너는 이 블로킹을 대비에 큰 쓰레드 풀로 요청을 처리한다.

스프링 웹플럭스는 (그리고 일반적인 논블로킹 서버라면) 실행 중인 쓰레드가 중단되지 않는다는 전제가 있다. 따라서 논블로킹 서버는 작은 쓰레드 풀(이벤트 루프 워커)을 고정해놓고 요청을 처리한다.

“확장”과 “적은 쓰레드”가 모순처럼 들릴지도 모르지만, 쓰레드를 중단하지 않는다는 건(그리고 콜백에 처리를 맡기는 건) 요청을 처리할 다른 쓰레드가 필요 없고, 그렇기 때문에 블로킹을 대비할 필요가 없다는 뜻이다.

Invoking a Blocking API

블로킹 라이브러리를 사용해야 한다면 어떻게 해야 할까? 리액터, RxJava 모두 다른 쓰레드로 요청을 처리해 주는 publishOn 오퍼레이터를 지원한다. 블로킹을 쉽게 피해갈 수 있다는 말이긴 하지만, 블로킹 API 자체가 동시성 모델에 적합하지 않다는 걸 유념하라.

Mutable State

리액터와 RxJava에서 로직은 연산자로 표현한다. 연산자를 사용하면 런타임에 분리된 환경에서 리액티브 파이프라인을 만들고, 각 파이프라인에서 데이터를 순차적으로 처리한다. 파이프라인 안에 있는 코드는 절대 동시에 실행되지 않으므로 더 이상 상태 공유(mutable state)를 신경 쓰지 않아도 된다.

Threading Model

스프링 웹플럭스를 사용하는 어플리케이션은 어떤 쓰레드를 얼마나 실행할까?

최소한의 설정으로 스프링 웹플럭스 서버를 띄우면(예를 들어 데이터 접근이나 다른 dependency가 없는), 서버는 쓰레드 한 개로 운영하고, 소량의 쓰레드로 요청을 처리할 수 있다(보통은 CPU 코어 수만큼). 하지만 서블릿 컨테이너는 서블릿 블로킹 I/O와 서블릿 3.1 논블로킹 I/O를 모두 지원하기 때문에 더 많은 쓰레드를 실행할 것이다 (예를 들어 톰캣은 10개).
리액티브 WebClient는 이벤트 루프를 사용한다. 따라서 적은 쓰레드를 고정해 두고 쓴다(예를 들어 리액터 Netty 커넥터를 쓴다면 reactor-http-nio-로 시작하는 쓰레드를 확인할 수 있다). 단, 클라이언트와 서버에서 모두 리액터 Netty를 사용하면 디폴트로 이벤트 루프 리소스를 공유한다.
리액터와 RxJava는 스케줄러라는 추상화된 쓰레드 풀 전략을 제공한다. publishOn 연산자가 나머지 연산을 다른 쓰레드 풀로 전환할 때도 이 스케줄러를 사용한다. 스케줄러는 이름을 보면 동시 처리 전략을 알 수 있다. 예를 들어, 제한된 쓰레드로 CPU 연산이 많은 처리를 할 때는 “parallel”, 여러 쓰레드로 I/O가 많은 처리를 할 때는 “elastic”이다. 이런 쓰레드를 본다면 코드 어딘가에서 그 이름에 해당하는 쓰레드 풀 Scheduler 전략을 사용하고 있다는 뜻이다.
데이터에 접근하는 라이브러리나 다른 외부 dependency에서 쓰레드를 따로 실행하는 경우도 있다.

Configuring

스프링 프레임워크에서 서버를 직접 실행시키거나 중단할 수는 없다. 서버의 쓰레드 모델 바꾸고 싶다면 각 서버에 맞는 설정 API를 참고하거나, 아니면 스프링 부트를 써서 각 서버에 맞는 스프링 부트 옵션을 설정하면 된다. WebClient는 코드로 직접 설정할 수 있다. 다른 라이브러리는 해당 라이브러리 문서를 확인하라.

1.2. Reactive Core

spring-web을 사용하면 다음과 같은 방법으로 리액티브 웹 어플리케이션을 만들 수 있다:

서버 쪽 요청은 저수준과 고수준으로 나눠서 처리한다.
- HttpHandler: 논블로킹 I/O와 리액티브 스트림 back pressure로 HTTP 요청을 처리한다. 리액터 Netty, Undertow, 톰캣, Jetty, 서블릿 3.1+ 컨테이너 어댑터와 함께 사용한다.
- WebHandler API: 약간 더 고수준으로, 어노테이션을 선언한 컨트롤러나 함수형 엔드포인트같이 구체적인 프로그래밍 모델로 작성하는 범용 웹 API다.
클라이언트 사이드에서는 기본적으로 ClientHttpConnector가 논블로킹 I/O와 리액티브 스트림 back pressure로 HTTP 요청을 처리한다. Reactor Netty, 리액티브 Jetty HttpClient 어댑터와 함께 사용하며, 어플리케이션에서 사용하는 고수준 WebClient는 이를 기반으로 동작한다.
클라이언트와 서버 사이드 모두, 코덱으로 HTTP 요청과 응답 컨텐츠를 직렬화/역직렬화힌다.

1.2.1. `HttpHandler`

HttpHandler는 요청과 응답을 처리하는 메소드를 하나만 가지고 있다. 의도한 유일한 역할은 여러 HTTP 서버 API를 추상화하는 것이다.

지원하는 서버 API는 아래 표에 나타냈다:

서버 이름	사용하는 Server API	리액티브 스트림 지원
Netty	Netty API	Reactor Netty
Undertow	Undertow API	spring-web: Undertow to 리액티브 스트림 브릿지
톰캣	서블릿 3.1 논블로킹 I/O; ByteBuffers로 byte[]를 읽고 쓰는 톰캣 API	spring-web: 서블릿 3.1 논블로킹 I/O to 리액티브 스트림 브릿지
Jetty	서블릿 3.1 논블로킹 I/O; ByteBuffers로 byte[]를 쓰는 Jetty API	spring-web: 서블릿 3.1 논블로킹 I/O to 리액티브 스트림 브릿지
서블릿 3.1 컨테이너	서블릿 3.1 논블로킹 I/O	spring-web: 서블릿 3.1 논블로킹 I/O to 리액티브 스트림 브릿지

서버 dependency는 아래 테이블에 있다(지원 버전 참고):

서버 이름	Group id	Artifact name
리액터 Netty	io.projectreactor.netty	reactor-netty
Undertow	io.undertow	undertow-core
톰캣	org.apache.tomcat.embed	tomcat-embed-core
Jetty	org.eclipse.jetty	jetty-server, jetty-servlet

다음은 각 서버 API 어댑터를 활용하는 HttpHandler 코드다:

리액터 Netty

java kotlin

HttpHandler handler = ...
ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler);
HttpServer.create().host(host).port(port).handle(adapter).bind().block();

val handler: HttpHandler = ...
val adapter = ReactorHttpHandlerAdapter(handler)
HttpServer.create().host(host).port(port).handle(adapter).bind().block()

Undertow

java kotlin

HttpHandler handler = ...
UndertowHttpHandlerAdapter adapter = new UndertowHttpHandlerAdapter(handler);
Undertow server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build();
server.start();

val handler: HttpHandler = ...
val adapter = UndertowHttpHandlerAdapter(handler)
val server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build()
server.start()

Tomcat

java kotlin

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();

val handler: HttpHandler = ...
val servlet = TomcatHttpHandlerAdapter(handler)

val server = Tomcat()
val base = File(System.getProperty("java.io.tmpdir"))
val rootContext = server.addContext("", base.absolutePath)
Tomcat.addServlet(rootContext, "main", servlet)
rootContext.addServletMappingDecoded("/", "main")
server.host = host
server.setPort(port)
server.start()

Jetty

java kotlin

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();

val handler: HttpHandler = ...
val servlet = JettyHttpHandlerAdapter(handler)

val server = Server()
val contextHandler = ServletContextHandler(server, "")
contextHandler.addServlet(ServletHolder(servlet), "/")
contextHandler.start();

val connector = ServerConnector(server)
connector.host = host
connector.port = port
server.addConnector(connector)
server.start()

서블릿 3.1+ 컨테이너

서블릿 3.1+ 컨테이너에 WAR를 배포하려면 WAR에 AbstractReactiveWebInitializer를 확장해서 추가하면 된다. 이 클래스는 HttpHandler, ServletHttpHandlerAdapter를 감싸고 있으며, 이 핸들러를 Servlet으로 등록한다.

1.2.2. `WebHandler` API

org.springframework.web.server 패키지를 보면, HttpHandler가 WebHandler와, 여러 WebExceptionHandler, WebFilter로 체인을 형성해 요청을 처리하는 범용 웹 API를 제공한다. WebHttpHandlerBuilder에 컴포넌트를 등록하거나, 스프링 ApplicationContext 위치만 알려주면 자동으로 컴포넌트를 체인에 추가한다.

HttpHandler는 서로 다른 HTTP 서버를 쓰기 위한 추상화가 전부인 반면, WebHandler API는 아래와 같이 웹 어플리케이션에서 흔히 쓰는 광범위한 기능을 제공한다:

User session과 Session attributes.
Request attributes.
Locale, Principal 리졸브
form 데이터 파싱, 캐시 조회.
multipart 데이터 추상화.
기타 등등

Special bean types

다음은 WebHttpHandlerBuilder에 직접 등록하거나 어플리케이션 컨텍스트에서 자동으로 주입받을 수 있는 컴포넌트다:

Bean name	Bean type	Count	Description
<any>	`WebExceptionHandler`	0..N	`WebFilter` 체인과 `WebHandler`에서 발생한 예외를 처리한다. 자세한 내용은 Exceptions를 참고하라.
<any>	`WebFilter`	0..N	다른 필터 체인과 `WebHandler` 전후에 요청을 가로채 원하는 로직을 넣을 수 있다. 자세한 내용은 Filters를 참고하라.
`webHandler`	`WebHandler`	1	요청을 처리하는 핸들러.
`webSessionManager`	`WebSessionManager`	0..1	`WebSession`의 매니저. `WebSession`은 `ServerWebExchange`로 접근할 수 있다. 디폴트는 `DefaultWebSessionManager`다.
`serverCodecConfigurer`	`ServerCodecConfigurer`	0..1	form 데이터나 multipart 데이터를 파싱하는 `HttpMessageReader`를 설정하기 위한 인터페이스. 이 데이터는 `ServerWebExchange`로 접근할 수 있다. 디폴트는 `ServerCodecConfigurer.create()`를 사용한다.
`localeContextResolver`	`LocaleContextResolver`	0..1	`LocaleContext` 리졸버. `LocaleContext`는 `ServerWebExchange`로 접근한다. 디폴트 리졸버는 `AcceptHeaderLocaleContextResolver`다.
`forwardedHeaderTransformer`	`ForwardedHeaderTransformer`	0..1	forwarded 헤더를 파싱해서 추출 후 제거하거나, 제거만 하고 헤더 정보를 무시할 수도 있다. 디폴트는 사용하지 않는 것이다.

Form Data

ServerWebExchange는 form 데이터(application/x-www-form-urlencoded)에 접근할 수 있는 다음 메소드를 제공한다:

java kotlin

Mono<MultiValueMap<String, String>> getFormData();

suspend fun getFormData(): MultiValueMap<String, String>

DefaultServerWebExchange는 설정에 있는 HttpMessageReader를 사용해 form 데이터를 MultiValueMap으로 파싱한다. 디폴트로 사용하는 리더는 ServerCodecConfigurer 빈에 있는 FormHttpMessageReader다 (Web Handler API 참고).

Exception Handler	Description
`ResponseStatusExceptionHandler`	HTTP status code를 지정할 수 있는 `ResponseStatusException`을 처리한다.
`WebFluxResponseStatusExceptionHandler`	`ResponseStatusExceptionHandler`를 확장한 것으로, 다른 exception 타입도 `@ResponseStatus`를 선언해서 HTTP staus code를 정할 수 있다. 이 핸들러는 WebFlux Config 안에 선언돼 있다.

Bean type	Explanation
`HandlerMapping`	요청을 핸들러에 매핑한다. 매핑 기준은 `HandlerMapping` 구현체마다 다르다 (어노테이션을 선언한 컨트롤러, URL 패턴 매칭 등). 주로 쓰는 구현체는 `@RequestMapping`을 선언한 메소드를 찾는 `RequestMappingHandlerMapping`, 함수형 엔드포인트를 라우팅하는 `RouterFunctionMapping`, URI path 패턴으로 `WebHandler`를 찾는 `SimpleUrlHandlerMapping` 등이 있다.
`HandlerAdapter`	`HandlerAdapter`가 핸들러를 실행하는 방법을 알고 있기 때문에, `DispatcherHandler`는 어떤 핸들러든지 받아 처리할 수 있다. 예를 들어 어노테이션을 선언한 컨트롤러를 실행하려면 리졸버가 필요한데, `HandlerAdapter`를 사용하면 `DispatcherHandler`는 이런 디테일을 몰라도 된다.
`HandlerResultHandler`	핸들러가 건네 준 결과를 처리하고 응답을 종료한다. Result Handling를 참고하라.

Result Handler Type	Return Values	Default Order
`ResponseEntityResultHandler`	`ResponseEntity`, 보통 `@Controller`에서 사용.	0
`ServerResponseResultHandler`	`ServerResponse`, 보통 함수형 엔드포인트에서 사용.	0
`ResponseBodyResultHandler`	`@ResponseBody` 메소드나 `@RestController`에서 리턴한 값을 처리.	100
`ViewResolutionResultHandler`	`CharSequence`, `View`, Model, `Map`, Rendering이나 다른 `Object`를 model attribute로 처리. View Resolution 참고.	`Integer.MAX_VALUE`

Pattern	Description	Example
`?`	문자 하나	`"/pages/t?st.html"`은 `"/pages/test.html"`, `"/pages/t3st.html"` 둘 다 매칭된다
`*`	path segment 안에 있는 0개 이상의 문자	`"/resources/.png"`는 `"/resources/file.png"`와 매칭된다. `"/projects//versions"`는 `"/projects/spring/versions"`와는 매칭되지만 `"/projects/spring/boot/versions"`과는 매칭되지 않는다.
`**`	path 마지막에 있는 0개 이상의 path segment	`"/resources/"`는 `"/resources/file.png"`, `"/resources/images/file.png"`와 매칭된다. `""`는 path 마지막에서만 사용할 수 있기 때문에 `"/resources/**/file.png"`는 사용할 수 없다.
`{name}`	path segment 하나와 매칭되며, 이 segment를 “name”이라는 변수에 저장한다.	`"/projects/{project}/versions"`를 `"/projects/spring/versions"`와 매칭하면 `project` 변수는 `spring`이다.
`{name:[a-z]+}`	정규식 `"[a-z]+"`과 매칭되는 값을 “name”이라는 변수에 저장한다.	`"/projects/{project:[a-z]+}/versions"`는 `"/projects/spring/versions"`와는 매칭되지만 `"/projects/spring1/versions"`랑은 매칭되지 않는다.
`{*path}`	path 마지막에 있는 0개 이상의 path segment를 나타내며, “path”라는 변수에 이 값을 저장한다.	`/resources/{*file}`은 `"/resources/images/file.png"`와 매칭되고 `file` 변수는 `/images/file.png`가 된다.

Controller method argument	Description
`ServerWebExchange`	`ServerWebExchange`는 HTTP 요청, 응답, request attributes, session attributes를 모두 포함하고 있는 컨테이너다. `checkNotModified` 메소드도 지원한다.
`ServerHttpRequest`, `ServerHttpResponse`	HTTP 요청과 응답에 접근할 수 있다.
`WebSession`	세션에 접근할 수 있다. 세션에 접근해도 attribute를 추가하지 않으면 새 세션을 열지 않는다. 리액티브 타입을 지원한다.
`java.security.Principal`	현재 인증된 유저 — `Principal` 구현체가 있다면 구현체를 리졸브한다. 리액티브 타입을 지원한다.
`org.springframework.http.HttpMethod`	요청 HTTP 메소드
`java.util.Locale`	요청의 locale 정보. `LocaleResolver`가 가장 구체적인 locale을 리졸브한다. — 사실상 `LocaleResolver`/`LocaleContextResolver` 설정이 결정한다.
`java.util.TimeZone` + `java.time.ZoneId`	요청에 사용된 타임존. `LocaleContextResolver`가 결정한다.
`@PathVariable`	URI 템플릿 변수에 접근하는 용도. URI Patterns 참고.
`@MatrixVariable`	URI path segment를 name/value 쌍으로 접근하는 용도. Matrix Variables 참고.
`@RequestParam`	서블릿 request 파라미터에 접근할 수 있다. 파라미터 값은 메소드에 선언한 인자 타입으로 변환된다. `@RequestParam` 참고. `@RequestParam`은 생략해도 된다. — 예를 들어 어노테이션을 생략하고, 파라미터 대신 attribute를 매핑할 수도 있다. 테이블 마지막에 나오는 “Any other argument” 참고.
`@RequestHeader`	요청 헤더에 접근하는 용도. 헤더 값은 메소드에 선언한 인자 타입으로 변환된다. @RequestHeader 참고.
`@CookieValue`	쿠키에 접근하는 용도. 쿠키 값은 메소드에 선언한 인자 타입으로 변환된다. @CookieValue 참고.
`@RequestBody`	HTTP request body에 접근하는 용도. `HttpMessageReader`가 body를 메소드에 선언한 인자 타입으로 변환한다. 리액티브 타입을 지원한다. @RequestBody 참고.
`HttpEntity<B>`	요청 헤더와 body에 접근하는 용도. `HttpMessageReader`가 body를 변환한다. 리액티브 타입을 지원한다. HttpEntity 참고.
`@RequestPart`	`multipart/form-data` 요청에서 part에 접근하는 용도. 리액티브 타입을 지원한다. Multipart Content, Multipart Data 참고.
`java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap`	HTML 컨트롤러가 템플릿으로 뷰를 렌더링할 때 사용하는 모델에 접근할 수 있다.
`@ModelAttribute`	model에 있는 attribute에 접근할 수 있다(attribute가 없다면 model 초기화만 한다). 이때 데이터를 바인딩하면서 유효성도 함께 검사한다. `@ModelAttribute`, Model, DataBinder 참고. `@ModelAttribute`는 생략해도 된다. 이 테이블 마지막에 나오는 “Any other argument”를 참고하라.
`Errors`, `BindingResult`	커맨드 객체를 메소드 인자에 바인딩할 땐 유효성을 검증할 수 있는데(e.g. `@ModelAttribute`), 이때 발생한 에러에 접근하는 용도로 사용한다. `Errors`, `BindingResult` 인자는 유효성을 검증하는 인자 바로 뒤에 사용해야 한다.
`SessionStatus` + 클래스 레벨 `@SessionAttributes`	`@SessionAttributes` 어노테이션을 클래스에 선언하면 세션에 attribute를 저장하는데, `SessionStatus`를 인자로 받아 session 처리가 완료됐다고 알려주면 session attribute를 지운다. 자세한 내용은 `@SessionAttributes` 참고.
`UriComponentsBuilder`	요청 호스트, 포트, 스킴, path로 URL을 만들 수 있다. URI Links 참고.
`@SessionAttribute`	session attribute에 접근하는 용도. 클래스 레벨에 `@SessionAttributes`를 선언하면 세션에 model attribute를 저장하지만, 메소드 인자에 `@SessionAttribute`를 선언하면 session attribute에 접근할 수 있다. 자세한 내용은 `@SessionAttribute` 참고.
`@RequestAttribute`	request attribute에 접근하는 용도. 자세한 내용은 `@RequestAttribute` 참고.
Any other argument	그 외 타입을 메소드 인자로 선언하면 BeanUtils#isSimpleProperty 결과가 true인 경우엔 `@RequestParam`에, 그 외는 `@ModelAttribute`로 리졸브한다.

Controller method return value	Description
`@ResponseBody`	리턴한 값을 `HttpMessageWriter`로 인코딩해서 body에 쓴다. `@ResponseBody` 참고.
`HttpEntity<B>`, `ResponseEntity<B>`	HTTP 헤더를 포함해서 response를 직접 지정할 수 있다. body는 `HttpMessageWriter`로 인코딩한다. `ResponseEntity` 참고.
`HttpHeaders`	body 없이 헤더로만 응답하는 용도.
`String`	`ViewResolver`에서 사용하는 view name으로, 커맨드 객체와 `@ModelAttribute` 메소드로 만든 모델과 함께 사용한다. 핸들러 메소드에서도 `Model`을 인자로 받아 attribute를 추가할 수 있다(앞에서 설명했다).
`View`	커맨드 객체와 `@ModelAttribute` 메소드로 만든 모델과 함께 렌더링하는 `View` 인스턴스. 핸들러 메소드에서도 `Model`을 인자로 받아 attribute를 추가할 수 있다(앞에서 설명했다).
`java.util.Map`, `org.springframework.ui.Model`	모델에 attribute를 추가할 수 있다. view name은 요청 path로 결정한다.
`@ModelAttribute`	모델에 attribute를 추가할 수 있다. view name은 요청 path로 결정한다. `@ModelAttribute`는 생략해도 된다. 이 테이블 마지막에 나오는 “Any other return value”를 참고하라.
`Rendering`	model과 view를 만드는 API.
`void`	void 메소드는 비동기 값(`Mono<Void>`)이나 null을 리턴한 경우도 포함이다. 이때는 `ServerHttpResponse`, `ServerWebExchange` 인자가 있거나, `@ResponseStatus` 어노테이션을 선언했다면 요청을 완료한 것으로 간주한다. ETag나 `lastModified` 헤더로 클라이언트 캐시가 최신이라고 판단했을 때도 동일하다. 자세한 내용은 Controllers를 참조하라. 그 외엔 REST 컨트롤러에선 “response body가 없음”을 의미하고, HTML 컨트롤러에선 디폴트 view name을 선택한다.
`Flux<ServerSentEvent>`, `Observable<ServerSentEvent>`, or other reactive type	서버 전송 이벤트(SSE)를 발생시킨다. 데이터만 전송하면 된다면 `ServerSentEvent` 래퍼는 생략해도 된다(단, 헤더에 `text/event-stream`을 사용하거나, `produces` attribute로 매핑해야 한다).
Any other return value	`String`은 view name으로 사용하고, `void`면 디폴트 view name을 사용한다. 그 외에는 BeanUtils#isSimpleProperty 결과가 false면 모델 attribute로 사용하고, true면 리졸브하지 못한다.

Spring Web on Reactive Stack

Spring WebFlux (1)

목차

1.1. Overview

1.1.1. Define “Reactive”

1.1.2. Reactive API

1.1.3. Programming Models

1.1.4. Applicability

1.1.5. Servers

1.1.6. Performance

1.1.7. Concurrency Model

1.2. Reactive Core

1.2.1. HttpHandler

1.2.2. WebHandler API

Special bean types

Form Data

Multipart Data

Forwarded Headers

1.2.3. Filters

CORS

1.2.4. Exceptions

1.2.5. Codecs

Jackson JSON

Form

Multipart

Limits

Streaming

DataBuffer

1.2.6. Logging

Log Id

Sensitive Data

Custom codecs

1.3. DispatcherHandler

1.3.1. Special Bean Types

1.3.2. WebFlux Config

1.3.3. Processing

1.3.4. Result Handling

1.3.5. Exceptions

1.3.6. View Resolution

Handling

Redirecting

Content Negotiation

1.4. Annotated Controllers

1.4.1. @Controller

1.4.2. Request Mapping

URI Patterns

Pattern Comparison

Consumable Media Types

Producible Media Types

Parameters and Headers

HTTP HEAD, OPTIONS

Custom Annotations

Explicit Registrations

1.4.3. Handler Methods

Method Arguments

Return Values

Type Conversion

Matrix Variables

@RequestParam

@RequestHeader

@CookieValue

@ModelAttribute

@SessionAttributes

@SessionAttribute

@RequestAttribute

Multipart Content

@RequestBody

HttpEntity

@ResponseBody

ResponseEntity

Jackson JSON

JSON Views

1.4.4. Model

1.4.5. DataBinder

1.4.6. Managing Exceptions

REST API exceptions

1.4.7. Controller Advice

1.2.1. `HttpHandler`

1.2.2. `WebHandler` API

`DataBuffer`

`@RequestParam`

`@RequestHeader`

`@CookieValue`

`@ModelAttribute`

`@SessionAttributes`

`@RequestAttribute`

`@RequestBody`

`HttpEntity`

`@ResponseBody`

`ResponseEntity`

1.4.5. `DataBinder`