💡 챗봇2 스튜디오, 엔진 파일서버 연동 기능 구현 중 외부 서버로 API 를 호출하기 위해 공부

WebClient

개요

• 스프링 프레임워크에서 제공하는 HTTP 통신을 위한 비동기 클라이언트
• HTTP 요청을 보내고 응답을 받을 수 있도록 도와줌.

동작 특징

• Non-Blocking 방식: 요청 보낸 이후에도 제어권을 빼앗기지 않고 이후 로직을 수행.
• 비동기 방식으로 동작: 네트워크 요청이 완료될 때까지 프로그램의 실행이 중단되지 않도록 구현할 수 있음.
• 스레드나 동시성과 관련된 코드를 작성할 필요 없이 비동기 로직 구성이 가능함.
• Reactor에 기반한 API 제공하며,
• 외부 API로 요청을 할 때 응답 결과를 Mono와 Flux로 반환함

Mono, Flux

• WebFlux API에서 주로 사용되는 데이터 return 타입
• Reactor (Reactive Streams library)에서 제공하는 클래스
• 데이터 전달 건수에 따라 나뉨
  • 0~1개의 데이터 전달 ⇒ Mono
  • 0~N개의 데이터 전달 ⇒ Flux
• 둘을 왜 나눠놨을까? 데이터 설계를 할때 결과가 없거나 하나의 결과값만 받는 것이 명백한 경우, List나 배열을 사용하지 않는 것처럼, Multi Result가 아닌 하나의 결과셋만 받게 될 경우에는 불필요하게 Flux를 사용하지 않고 Mono를 사용.
  
• 자세한 동작 방식

Spring WebFlux

• WebClient를 포함하고 있는 프레임워크
• 스프링 프레임워크에서 Reactive-stack 웹 애플리케이션 제작을 위해 제공하는 웹 프레임워크
  • Reactive-stack 웹 애플리케이션: Reactive Streams API에 기반한 Non-Blocking 서버에서 구동되는 애플리케이션
    • Reactive Streams API
      • 요청 측에서 요청 받은 측의 데이터 처리 속도를 제어할 수 있게 함
      • blocking 형태에서는 waiting을 강제하는 것이 자연스러운 것처럼, non-blocking 형태에서는 producer가 consumer를 앞지르지 않도록 이벤트의 속도를 제어하는 것 (Back Pressure)이 중요함
        • consumer가 처리할 수 있는 데이터의 양 만큼만 producer에게 요청
• 이벤트 스트림을 기반으로 데이터를 처리하거나 비동기 방식으로 처리해야 하는 웹 어플리케이션을 개발할 때 WebFlux를 사용하는 것이 적절
  • 이벤트 스트림은 뭔데?
    • 이벤트가 발생할 때마다 데이터를 스트림으로 처리할 수 있게 해주는 방식
      • 데이터를 스트림으로 처리한다는 것은?
        • 데이터를 요소별로 처리할 수 있고, 이를 통해 코드의 가독성을 높일 수 있고, 요소들을 병렬로 처리할 수 있다는 것을 의미
    • 이벤트 스트림을 사용하면 이벤트가 발생할 때마다 데이터를 처리할 수 있음 (비동기 방식의 데이터 처리를 가능하게 함)
• 비동기 웹 어플리케이션 제작에 필요한 기능을 제공하는 FW!!

사용법

의존성 추가

• Gradle Dependency

  dependencies {
      compile 'org.springframework.boot:spring-boot-starter-webflux'
  }

Create: 생성

• create()

  • default 세팅/요청할 uri로 클라이언트를 바로 생성하는 메서드

  • WebClient의 default 세팅으로 아래와 같이 생성하거나, 요청할 uri를 파라미터로 넣어서 생성

    WebClient.create();
    WebClient.create("http://localhost:8080");

• build()

  • 모든 설정을 커스텀하여 클라이언트를 생성하는 메서드

  • Customization Options
    - uriBuilderFactory: base url을 커스텀한 UriBuilderFactory
    - defaultUriVariables: uri 템플릿을 배포할 때 사용하는 디폴트 값
    - defaultCookie: 모든 요청에 사용할 쿠키
    - defaultHeader: 모든 요청에 사용할 헤더
    - defaultRequest: 모든 요청을 커스텀할 Consumer
    - filter: 모든 요청에 사용할 클라이언트 필터
    - exchangeStrategies: HTTP 메시지 reader, writer 커스터마이징
    - clietConnector: HTTP 클라이언트 라이브러리 세팅

    WebClient client = WebClient.builder()
      .baseUrl("http://localhost:8080")
      .defaultCookie("cookieKey", "cookieValue")
      .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) 
      .defaultUriVariables(Collections.singletonMap("url", "http://localhost:8080"))
      .build();

Configuration: 정보 설정

• Timeout

  • Timeout과 관련된 설정 정보를 설정한 HttpClient 객체를 만들어 WebClient에 주입

    HttpClient httpClient = HttpClient.create()
    	.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)
    	.responseTimeout(Duration.ofMillis(5000))
    	.doOnConnected(conn -> 
    		conn.addHandlerLast(new ReadTimeoutHandler(5000, TimeUnit.MILLISECONDS))
    		.addHandlerLast(new WriteTimeoutHandler(5000, TimeUnit.MILLISECONDS)));
    
    WebClient client = WebClient.builder()
    	.clientConnector(new ReactorClientHttpConnector(httpClient))
    	.build();

  • 코드 설명: Connect Timeout과 ReadTimeout, WriteTimeout을 모두 5000ms로 지정한 HttpClient객체를 만들어 WebClient에 주입 한 예시.

• mutate()

  • WebClient는 한 번 빌드한 뒤 부터는 immutable 한데, WebClient를 싱글턴으로 사용하는 상황에서 default setting과 다르게 사용하고 싶은 경우 mutate를 통해 다른 설정값을 가지는 요청을 할 수 있게 된다.

    mutable: 값이 변할 수 있는
    immutable: 값이 변하지 않는

  • client1과 client2가 가리키는 객체는 같은 WebClient 인스턴스지만, mutate()를 이용해 서로 다른 설정값을 가지는 요청을 할 수 있게 된다.

  • 같은 객체에 client1과 client2에 다른 옵션값을 프리셋 해두는 느낌

    WebClient client1 = WebClient.builder()
            .filter(filterA).filter(filterB).build();
    
    WebClient client2 = client1.mutate()
            .filter(filterC).filter(filterD).build();
    
    // client1 has filterA, filterB
    // client2 has filterA, filterB, filterC, filterD

Request: 요청 보내기

• GET
  • Flux [GET] /employees Request: collection of employees as Flux

    @Autowired
    WebClient webClient;
    
    public Flux<Employee> findAll() {
    	return webClient.get()
    		.uri("/employees")
    		.retrieve() // body를 받아 디코딩하는 메서드
    		.bodyToFlux(Employee.class);
    }

  • Mono [GET] /employees/{id} Request: single employee by id as Mono

    @Autowired
    WebClient webClient;
    
    public Mono<Employee> findById(Integer id) {
    	return webClient.get()
    		.uri("/employees/" + id)
    		.retrieve()
    		.bodyToMono(Employee.class);
    }

• POST

  • [POST] /employees

  • Request: creates a new employee from request body

  • Response: returns the created employee

    @Autowired
    WebClient webClient;
    
    public Mono<Employee> create(Employee empl) {
    	return webClient.post()
    		.uri("/employees")
    		.body(Mono.just(empl), Employee.class) // body에 담아 요청할 데이터와 그 타입을 명시
    		.retrieve()
    		.bodyToMono(Employee.class); // POST 하고 받을 body가 없다면 파라미터로 Void.class를 입력
    }

Response: 응답 받기

• retrieve()
  • toEntity()

    • status, headers, body를 포함하는 ResponseEntity 타입으로 받을 수 있음

      Mono<ResponseEntity<Employee>> entityMon = client.get();
      	.uri("/employee/1")
      	.accept(MediaType.APPLICATION_JSON)
      	.retreive()
      	.toEntity(Employee.class);

  • toMono(), toFlux()

    • body의 데이터로만 받고 싶을 때 사용

      Mono<Employee> entityMono = client.get()
      	.uri("/employee/1")
      	.accept(MediaType.APPLICATION_JSON)
      	.retreive()
      	.bodyToMono(Employee.class);

• exchangeToMono(), exchangeToFlux()

  Mono<Employee> entityMono = client.get()
  	.uri("/employee/1")
  	.accept(MediaType.APPLICATION_JSON)
  	.exchangeToMono(resonse -> {
  		if (response.statusCode().equals(HttpStatus.OK)) {
  			return response.bodyToMono(Employee.class);
  		}	else {
  				return response.createException().flatMap(Mono::error);
  		}
  	})

• Mono<>, Flux<> 사용
  • Blocking으로 사용하고자 하는 경우

    • block()으로 blocking 방식으로 처리

      Mono<Employee> employeeMono = webClient.get()
      	/* 중략 */
      
      employeeMono.block();

  • Non-Blocking으로 사용하고자 하는 경우

    • .subscribe() 메서드를 통해 콜백함수 지정
      - 콜백함수: 어떤 이벤트에 의해 호출되어지는 함수

      Mono<Employee> employssFlux = webClient.get()
      	/* 중략 */
      
      employeeFlux.subscribe(employee -> { ... });	

ErrorHandling

에러 핸들링은 결과 값을 반환받을 때의 상황에 따라 적절히 처리할 수 있다.

• retreive()

  • .onStatus() 이용해서 StatusCode 별로 핸들링

    Mono<Employee> result = client.get()
    	.uri("/employee/{id}", id)
    	.accept(MediaType.APPLICATION_JSON)
    	.retreive()
    	.onStatus(HttpStatus::is4xxClientError, response -> ...)
    	.onStatus(HttpStatus::is5xxServerError, response -> ...)
    	.bodyToMono(Employee.class);

• exchangeToMono(), exchangeToFlux()

  • exchange를 통해 받은응답에 대한 statusCode를 이용해 분기처리하여 핸들링

    Mono<Object> enriryMono = client.get()
    	.uri("/persons/1")
    	.accept(MediaType.APPLICATION_JSON)
    	.exchangeToMono(response -> {
    		if (response.statusCode().equals(HttpStatus.OK)) {
    			return response.bodyToMono(Employee.class);
    		}	else if (response.statusCode().is4xxClientError()){
    				return response.bodyToMono(ErrorContainer.class);
    		} else {
    				return Mono.error(response.createException());
    		}
    	})

심화 학습 자료

Reactive Stack

Web on Reactive Stack

WebClient이용하여 Non-Blocking으로 개선하기

비효율적인 Blocking 코드를 WebClient를 통해 개선하기

Reference

Web on Reactive Stack

[Spring] WebFlux의 개념 / Spring MVC와 간단비교

[WebFlux] Mono와 Flux 개념과 구현

비효율적인 Blocking 코드를 WebClient를 통해 개선하기