HTTP 클라이언트: WebClient 사용법

 

스프링 부트 3에서 WebClient는 HTTP 요청을 수행하기 위한 강력한 HTTP 클라이언트로, 비동기 방식으로 서버와 통신할 수 있는 기능을 제공합니다. 이전에 주로 사용하던 RestTemplate의 대안으로, 더 유연하고 현대적인 HTTP 요청 처리를 지원합니다. 이 글에서는 WebClient를 설정하고 사용하는 방법을 단계별로 알아보고, 다양한 예제와 함께 실전 활용 사례를 설명합니다.

---

1. WebClient란 무엇인가?

WebClient는 스프링 WebFlux 모듈에서 제공되는 비동기 논블로킹 HTTP 클라이언트입니다. 그러나 WebFlux가 아닌 스프링 MVC 기반의 프로젝트에서도 사용할 수 있습니다. 주요 특징은 다음과 같습니다:

• 비동기 요청 처리: 응답을 기다리지 않고 작업을 진행.
• 반응형 프로그래밍 지원: Mono, Flux와 같은 리액티브 스트림과 통합 가능.
• 다양한 HTTP 메서드 지원: GET, POST, PUT, DELETE 등 모든 HTTP 메서드와의 연동.
• 커스터마이징 가능: 헤더, 타임아웃, 로깅 등을 자유롭게 설정 가능.

---

2. WebClient 설정

기본 설정

WebClient를 사용하려면 의존성을 추가해야 합니다. Spring Boot 3에서는 의존성이 대부분 포함되어 있으나, 확인이 필요합니다.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

WebClient는 두 가지 방식으로 생성할 수 있습니다:

1. WebClient.create(): 기본 설정을 사용하는 방법.
2. WebClient.Builder: 커스터마이징된 클라이언트를 생성하는 방법.

WebClient 인스턴스 생성

import org.springframework.web.reactive.function.client.WebClient;

public class WebClientExample {

    // 기본 WebClient 인스턴스 생성
    private final WebClient webClient = WebClient.create("https://api.example.com");

    // Builder로 설정 커스터마이징
    private final WebClient customWebClient = WebClient.builder()
            .baseUrl("https://api.example.com")
            .defaultHeader("Authorization", "Bearer your-token")
            .build();
}

---

3. WebClient 사용 방법

WebClient를 사용한 기본적인 HTTP 요청 방법을 살펴보겠습니다.

1) GET 요청

import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

public class GetRequestExample {
    private final WebClient webClient = WebClient.create("https://jsonplaceholder.typicode.com");

    public void fetchPost() {
        Mono response = webClient.get()
                .uri("/posts/1")
                .retrieve()
                .bodyToMono(String.class);

        response.subscribe(System.out::println);
    }
}

• .uri(): 요청할 URI를 지정합니다.
• .retrieve(): 서버 응답을 가져오는 메서드.
• .bodyToMono(): 응답 본문을 Mono로 변환.

2) POST 요청

import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

public class PostRequestExample {
    private final WebClient webClient = WebClient.create("https://jsonplaceholder.typicode.com");

    public void createPost() {
        Mono response = webClient.post()
                .uri("/posts")
                .bodyValue(new Post(1, "WebClient 사용법", "스프링 부트3 WebClient 예제"))
                .retrieve()
                .bodyToMono(String.class);

        response.subscribe(System.out::println);
    }
}

// 요청에 사용할 데이터 클래스
class Post {
    private int userId;
    private String title;
    private String body;

    // 생성자, Getter, Setter
    public Post(int userId, String title, String body) {
        this.userId = userId;
        this.title = title;
        this.body = body;
    }
}

3) 예외 처리

HTTP 요청 도중 발생할 수 있는 오류를 처리하기 위해 .onStatus()를 사용합니다.

import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.WebClientResponseException;
import reactor.core.publisher.Mono;

public class ErrorHandlingExample {
    private final WebClient webClient = WebClient.create("https://api.example.com");

    public void fetchWithErrorHandling() {
        webClient.get()
                .uri("/invalid-endpoint")
                .retrieve()
                .onStatus(
                        status -> status.is4xxClientError() || status.is5xxServerError(),
                        clientResponse -> Mono.error(new RuntimeException("HTTP 에러 발생"))
                )
                .bodyToMono(String.class)
                .doOnError(WebClientResponseException.class, e -> System.out.println("에러: " + e.getMessage()))
                .subscribe(System.out::println);
    }
}

---

4. 실전 활용 예시

예시 1: 외부 API와 통합

외부 API에서 데이터를 가져와 처리하는 간단한 예제입니다.

public void fetchWeatherData() {
    Mono weather = webClient.get()
            .uri("https://api.weatherapi.com/v1/current.json?key=your-api-key&q=Seoul")
            .retrieve()
            .bodyToMono(WeatherResponse.class);

    weather.subscribe(System.out::println);
}

예시 2: 파일 업로드

multipart/form-data 형식으로 파일을 업로드합니다.

import org.springframework.core.io.FileSystemResource;

public void uploadFile() {
    webClient.post()
            .uri("/upload")
            .bodyValue(new FileSystemResource("/path/to/file"))
            .retrieve()
            .bodyToMono(String.class)
            .subscribe(System.out::println);
}

예시 3: OAuth 인증 처리

OAuth2 토큰을 사용해 API를 호출합니다.

public void fetchWithOAuth() {
    String token = "Bearer your-access-token";

    webClient.get()
            .uri("/secure-data")
            .header("Authorization", token)
            .retrieve()
            .bodyToMono(String.class)
            .subscribe(System.out::println);
}

---

5. 마무리

스프링 부트 3의 WebClient는 HTTP 요청 처리를 간소화하면서도 강력한 기능을 제공합니다. 비동기와 리액티브 프로그래밍을 지원하므로 대규모 API 호출이나 데이터 처리 작업에서 유용하게 사용할 수 있습니다. 위의 다양한 예제를 참고해 프로젝트에 맞는 방식으로 WebClient를 활용해 보세요.