[Spring] WebClient - 2. 요청 핸들링 및 API 구성

🔗[Spring] WebClient - 1. 개념 및 기본 설정

이전 장에서 기술한 WebClient 기본 설정이 완료되고 나면,

이를 활용하기 위해 요청을 받고 핸들링할 수 있는 API 구성이 필요하다.

 

📃​ RequestHandler

먼저 실제 HTTP 요청을 실행하고 핸들링하는 인프라 계층 서비스단을 작성한다.

@Service
@RequiredArgsConstructor
public class RequestHandler {

    private final ObjectMapper mapper;

    /**
     * WebClient GET 요청 후 결과 문자열 반환
     *
     * @param webClient WebClient
     * @param url String
     * @param params Map<String, String>
     * @return String
     */
    public String sendGetRequest(WebClient webClient, String url, Map<String, String> params) { // GET request
        MultiValueMap<String, String> queryParams = new LinkedMultiValueMap<>();
        queryParams.setAll(params);

        URI uri = UriComponentsBuilder
                .fromUriString(url)
                .queryParams(queryParams)
                .build().toUri();

        Mono<String> mono = webClient.get()
                .uri(uri)
                .accept(MediaType.APPLICATION_JSON)
                .retrieve()
                .onStatus(HttpStatusCode::is4xxClientError, response ->
                        Mono.error(new RuntimeException("URL : " + url + "] Bad Request - Error Code " + response.statusCode().value())))
                .onStatus(HttpStatusCode::is5xxServerError, response ->
                        Mono.error(new RuntimeException("URL : " + url + "] Internal Server Error - Error Code " + response.statusCode().value())))
                .bodyToMono(String.class);

        return mono.block();
    }

    /**
     * WebClient POST 요청 후 결과 문자열 반환
     *
     * @param webClient WebClient
     * @param url String
     * @param params Map<String, String>
     * @return String
     */
    public String sendPostRequest(WebClient webClient, String url, Map<String, String> params) { // POST request
        String body;
        try {
            body = mapper.writeValueAsString(params);
        } catch (JsonProcessingException e) {
            throw new RuntimeException(e);
        }

        URI uri = UriComponentsBuilder
                .fromUriString(url)
                .build().toUri();

        Mono<String> mono = webClient.post()
                .uri(uri)
                .contentType(MediaType.APPLICATION_JSON)
                .accept(MediaType.APPLICATION_JSON)
                .body(BodyInserters.fromValue(body))
                .retrieve()
                .onStatus(HttpStatusCode::is4xxClientError, response ->
                        Mono.error(new RuntimeException("URL : " + url + "] Bad Request - Error Code " + response.statusCode().value())))
                .onStatus(HttpStatusCode::is5xxServerError, response ->
                        Mono.error(new RuntimeException("URL : " + url + "] Internal Server Error - Error Code " + response.statusCode().value())))
                .bodyToMono(String.class);

        return mono.block();
    }

}

 

📑​ sendGetRequest

블로킹 방식으로 GET 요청을 처리 후 문자열로 응답을 반환한다.

public String sendGetRequest(WebClient webClient, String url, Map<String, String> params) { // GET request
    // MultiValueMap 생성
    MultiValueMap<String, String> queryParams = new LinkedMultiValueMap<>();
    queryParams.setAll(params); // 쿼리 파라미터 처리를 위해, Map 을 MultiValueMap 으로 변환

    // URI 구성
    URI uri = UriComponentsBuilder
            .fromUriString(url) // 기본 URL 설정
            .queryParams(queryParams) // 쿼리 파라미터 추가
            .build().toUri(); // URI 객체로 반환

    // WebClient 요청 구성
    Mono<String> mono = webClient.get() // GET 메소드 지정
            .uri(uri) // 요청 URI 설정
            .accept(MediaType.APPLICATION_JSON) // Accept 헤더 설정
            .retrieve() // 응답 추출 시작
            .onStatus(HttpStatusCode::is4xxClientError, response -> // 4xx 에러 처리
                    Mono.error(new RuntimeException("URL : " + url + "] Bad Request - Error Code " + response.statusCode().value())))
            .onStatus(HttpStatusCode::is5xxServerError, response -> // 5xx 에러 처리
                    Mono.error(new RuntimeException("URL : " + url + "] Internal Server Error - Error Code " + response.statusCode().value())))
            .bodyToMono(String.class); // 응답 본문을 String 으로 변환

    return mono.block(); // 비동기 실행을 블로킹하여 결과 반환
}

 

응답을 추출 시, retrieve 와 exchange 처리 방식을 사용 가능하며, 각 처리 방식의 차이점은 아래와 같다.

 

📌 retrieve

• 간단한 응답 처리에 적합하며 응답 본문만 접근 가능
• 간단하고 안전한 API 구성에 사용
• 메모리 안정적

📌 exchange

• 전체 ClientResponse 에 접근 가능
• 응답 헤더, 쿠키 등 세부 정보 접근 가능
• 수동으로 리소스 해제 필요
• 메모리 누수 가능성 존재

일반적으로 retrieve 사용을 우선 고려하고, 필요한 경우에만 exchange 를 사용한다.

exchange 사용 시, 메모리 누수 방지를 위해 항상 응답을 소비하고 doFinally 등을 사용하여 리소스를 정리하여야한다.

 

​📑 sendPostRequest

블로킹 방식으로 POST 요청을 처리 후 문자열로 응답을 반환한다.

public String sendPostRequest(WebClient webClient, String url, Map<String, String> params) { // POST request
    // 요청 바디 생성
    String body;
    try {
        body = mapper.writeValueAsString(params); // Map 을 JSON 문자열로 변환
    } catch (JsonProcessingException e) {
        throw new RuntimeException(e);
    }

    // URI 구성
    URI uri = UriComponentsBuilder
            .fromUriString(url) // 기본 URL 설정
            .build().toUri(); // URI 객체로 변환

    Mono<String> mono = webClient.post() // POST 메소드 지정
            .uri(uri) // 요청 URI 설정
            .contentType(MediaType.APPLICATION_JSON) // Content-Type 헤더 설정
            .accept(MediaType.APPLICATION_JSON) // Accept 헤더 설정
            .body(BodyInserters.fromValue(body)) // 요청 바디 설정
            .retrieve() // 응답 추출 시작
            .onStatus(HttpStatusCode::is4xxClientError, response -> // 4xx 에러 처리
                    Mono.error(new RuntimeException("URL : " + url + "] Bad Request - Error Code " + response.statusCode().value())))
            .onStatus(HttpStatusCode::is5xxServerError, response -> // 5xx 에러 처리
                    Mono.error(new RuntimeException("URL : " + url + "] Internal Server Error - Error Code " + response.statusCode().value())))
            .bodyToMono(String.class); // 응답 본문을 String 으로 변환

    return mono.block(); // 비동기 실행을 블로킹하여 결과 반환
}

 

논 블로킹 방식에 대한 핸들링의 경우, 메소드의 반환 타입을 String 에서 Mono<String> 으로 변경하고,

반환 시 block 을 수행하지 않고 Mono 객체를 반환한다.

// 반환 타입을 Mono<String> 으로 지정
public Mono<String> sendNonBlockingRequest(WebClient webClient, String url, Map<String, String> params) { // POST request
    String body;
    try {
        body = mapper.writeValueAsString(params);
    } catch (JsonProcessingException e) {
        return Mono.error(e); // 에러 처리를 Mono 로 감싸 반환
    }

    URI uri = UriComponentsBuilder
            .fromUriString(url)
            .build().toUri();

    return webClient.post() // 응답 Mono 객체를 바로 반환
            .uri(uri)
            .contentType(MediaType.APPLICATION_JSON)
            .accept(MediaType.APPLICATION_JSON)
            .body(BodyInserters.fromValue(body))
            .retrieve()
            .onStatus(HttpStatusCode::is4xxClientError, response ->
                    Mono.error(new RuntimeException("URL : " + url + "] Bad Request - Error Code " + response.statusCode().value())))
            .onStatus(HttpStatusCode::is5xxServerError, response ->
                    Mono.error(new RuntimeException("URL : " + url + "] Internal Server Error - Error Code " + response.statusCode().value())))
            .bodyToMono(String.class);
}

---

📃 RequestService

다음은 지정한 요청 처리 방식에 따라 RequestHandler 를 통해 응답을 받고,

비즈니스 로직을 구현 및 데이터를 가공 및 예외 처리하는 비즈니스 계층 서비스단을 작성한다.

@Service
@Slf4j
@RequiredArgsConstructor
public class RequestService {

    private final RequestHandler requestHandler; // 요청 핸들링 서비스
    private final WebClientFactory webClientFactory; // WebClient 반환 팩토리
    private final UtilService utilService; // 예시용 가상 서비스

    /**
     * 블로킹 POST 요청
     *
     * @param url String
     * @param params Map<String, String>
     * @return String
     */
    public String blockRequest(String url, Map<String, String> params) {
        return requestHandler.sendPostRequest(webClientFactory.getWebClient(), url, params);
    }

    /**
     * 논 블로킹 Mono POST 요청
     *
     * @param url String
     * @param params Map<String, String>
     * @return Mono<String>
     */
    public Mono<String> monoRequest(String url, Map<String, String> params) {
        return requestHandler.sendNonBlockPostRequest(webClientFactory.getWebClient(), url, params)
                .flatMap(this::parseResponse) // 메소드 체이닝 가능
                .doOnSuccess(resp -> log.info("process completed: {}", resp))
                .doOnError(error -> log.info("error occurred: {}", error.getMessage()));
    }

    /**
     * 논 블로킹 Subscribe POST 요청
     *
     * @param url String
     * @param params Map<String, String>
     */
    public void subscribeRequest(String url, Map<String, String> params) {
        requestHandler.sendNonBlockPostRequest(webClientFactory.getWebClient(), url, params)
                .subscribe(
                        resp -> log.info("process completed: {}", resp),
                        error -> log.error("error occurred: {}", error.getMessage())
                );
    }

    /**
     * 응답 처리 보조 메소드
     *
     * @param resp String
     * @return Mono<String>
     */
    private Mono<String> parseResponse(String resp) {
        return utilService.parseResponse(resp) // 해당 메소드는 Mono.just(String) 로 반환
                .doOnSuccess(result -> log.info("data parsing completed: {}", result))
                .doOnError(error -> log.error("data parsing failed: {}", error.getMessage()));
    }

}

 

위 클래스의 메소드중 논 블로킹 방식 메소드의 반환 타입으로 Mono 와 subscribe() 두 종류를 명시하였다.

각 반환 타입의 차이점은 아래와 같다.

 

📌 Mono(Flux) 반환

• 지연 실행(lazy execution)
• 파이프라인 구성 가능
• 다른 리액티브 연산자와 조합 가능
• 스프링 WebFlux 와 통합 용이

📌 subscribe()

• 즉시 실행됨
• void 반환
• 메소드 내에서 처리가 완료됨
• 주로 최종 소비자에서 사용

---

📃 RequestController

끝으로 클라이언트의 HTTP 요청을 받아들이는 앤드포인트를 제공하는 표현 계층 컨트롤러단을 작성한다.

@RequestMapping("/api")
@RestController
@RequiredArgsConstructor
public class RequestController {

    private final RequestService requestService;

    /**
     * 블로킹 POST 요청
     *
     * @param req RequestDTO
     * @return String
     */
    @PostMapping("/post/block")
    public String blockRequest(@RequestBody RequestDTO req) {
        return requestService.blockRequest(req.getUrl(), req.getParams());
    }

    /**
     * 논 블로킹 Mono POST 요청
     *
     * @param req RequestBody
     * @return Mono<String>
     */
    @PostMapping("/post/mono")
    public Mono<String> monoRequest(@RequestBody RequestDTO req) {
        return requestService.monoRequest(req.getUrl(), req.getParams());
    }

    /**
     * 논 블로킹 Subscribe POST 요청
     *
     * @param req RequestBody
     * @return Mono<String>
     */
    @PostMapping("/post/subscribe")
    public ResponseEntity<Void> subscribeRequest(@RequestBody RequestDTO req) {
        requestService.subscribeRequest(req.getUrl(), req.getParams());
        return ResponseEntity.accepted().build(); // 202 Accepted, 요청은 접수되었으나, 처리는 추후에 완료
    }

}

 

마치며

이처럼 WebClient 는 비동기 방식의 HTTP 요청을 보다 유연하고 효율적으로 처리할 수 있도록 도와준다.

상술한 기능외에도 retry, filter, 더 구체적인 에러 핸들링 기능들을 활용하면,
더 높은 확장성과 안정성을 갖춘 애플리케이션을 구축할 수 있다.