외부 API를 호출할 때 어떤 방법을 사용해야할까?

[f1v3-dev]

관련 이슈: #16

책 검색을 위해 외부(카카오) API를 호출해야 하는 상황입니다.

스프링에서 제공하는 클라이언트 중 아래의 3가지의 특징과 장단점을 비교해보고자 합니다.

• RestTemplate
• WebClient
• OpenFeign

[f1v3-dev]

RestTemplate

https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-resttemplate

대표적인 Spring의 HTTP Client 중 하나이지만, 다음과 같은 대안을 권장하고 있습니다.

• 동기식 요청: RestClient
• 비동기/스트리밍: WebClient

주요 특징

• 오랫동안 Spring 진영에서 지원되고 있음
• 동기식 Blocking 방식으로 동작
• RESTful 원칙 준수

기본적인 사용법

Bean 등록

@Configuration
public class RestTemplateConfig {
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

요청 예시

@Service
public class ExampleService {
    private final RestTemplate restTemplate;
    
    public String getData() {
        return restTemplate.getForObject(
            "http://example.com/api",
            String.class
        );
    }
}

RestTemplate을 사용하여 외부 API를 호출해야하는 상황일 경우 타임아웃(Timeout), 재시도(retry), 로깅(Logging), 서킷 브레이커 등을 설정하는 방법을 알아두면 좋을 것 같습니다.

[Spring] RestTemplate 타임아웃(Timeout), 재시도(Retry), 로깅(Logging) 등 설정하기
[Spring] RestTemplate에 Resilence4J 서킷 브레이커 적용하는 방법과 예시

RestTemplate도 충분히 괜찮은 선택이지만 직접 API 호출 코드를 작성해야한다는 점과 스프링에서 다른 대안 방안을 권장하는 점에서 RestTemplate은 채택하지 않았습니다.

[f1v3-dev]

WebClient

https://docs.spring.io/spring-framework/reference/web/webflux-webclient.html

Spring WebFlux에 포함된 HTTP 클라이언트로, Non-Blocking I/O를 활용한 리액티브 프로그래밍 모델을 기반으로 합니다.

주요 특징

• 비동기/Non-Blocking 방식 지원
• 싱글 스레드 방식으로 동작
• Reactor 기반의 선언적 API 제공

Reactor: JVM 위에서 동작하는 논블로킹 애플리케이션을 만들기 위한 리액티브 라이브러리 라고 하네요?..

기본적인 사용법

Bean 등록

@Configuration
public class WebClientConfig {
    @Bean
    public WebClient webClient() {
        return WebClient.builder()
            .baseUrl("http://api.example.com")
            .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
            .build();
    }
}

요청 예시

@Service
public class ExampleService {
    private final WebClient webClient;
    
    public Mono<UserResponse> getUser(String userId) {
        return webClient.get()
            .uri("/users/{id}", userId)
            .retrieve()
            .bodyToMono(UserResponse.class);
    }
}

채택하지 않은 이유

1. 책 검색 API의 비동기 처리 부적합성

• 검색 결과를 즉시 사용자에게 보여줘야 하는 동기식 처리가 필요
• 사용자는 검색 결과를 기다리며 다음 작업을 진행할 수 없음
• UI가 검색 결과에 직접적으로 의존

비동기 처리는 회원가입 축하 이메일과 같은 즉시 응답이 필요하지 않은 경우에 적합하지만, 현재 상황은 그렇지 않아보입니다.

2. 러닝 커브와 복잡성

• Reactive Programming에 대한 경험 부족
• Mono/Flux와 같은 새로운 개념 학습 필요

WebClient는 비동기/Non-Blocking 이라는 기능을 제공하지만, 프로젝트의 요구사항과 팀의 기술적 배경을 고려할 때 현재 상황에서는 적합하지 않다고 생각했습니다.

물론, WebClient도 비동기를 사용할 수 있지만 다음으로 언급할 FeignClient 형태가 더욱 직관적인 방법이라고 생각했습니다.

만약 학습이 필요하다면 아래의 공식 레퍼런스를 한글로 번역한 문서를 확인하면 좋을 것 같아요.
https://godekdls.github.io/Reactive%20Spring/springwebflux/#111-define-reactive

[f1v3-dev]

OpenFeign (FeignClient)

https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html/

Spring Cloud OpenFeign은 Netflix에서 개발한 선언적 REST 클라이언트로, org.springframework.cloud 패키지에 포함이 되어있습니다.

주요 특징

• 선언적 REST Client - 인터페이스 + 어노테이션으로 구현 가능
• 동기식 HTTP 통신 방식 (비동기 처리도 가능)

기본적인 사용법

@FeignClient(name = "book-service", url = "${api.book.url}")
public interface BookClient {
    @GetMapping("/api/books")
    List<Book> searchBooks(
        @RequestParam String query,
        @RequestHeader(HttpHeaders.AUTHORIZATION) String authorization
    );
}

위처럼 Spring MVC의 어노테이션 방식으로 동일하게 사용이 가능합니다.

만약, RestTemplate 을 사용한다 했다면 아래와 같은 코드 구조로 호출을 해야합니다.

@Component
@RequiredArgsConstructor
public class BookRestTemplate {

    private final RestTemplate restTemplate;
    private final String apiUrl;
    private final String apiKey;

    public List<Book> search(String query) {
        String url = createSearchUrl(query);
        HttpHeaders headers = createHeaders();
        
        HttpEntity<?> entity = new HttpEntity<>(headers);
        
        ResponseEntity<List<Book>> response = restTemplate.exchange(
            url,
            HttpMethod.GET,
            entity,
            new ParameterizedTypeReference<List<Book>>() {}
        );
        return response.getBody();
    }

    private String createSearchUrl(String query) {
        return UriComponentsBuilder.fromUriString(apiUrl)
            .path("/api/books")
            .queryParam("query", query)
            .encode()
            .build()
            .toUriString();
    }

    private HttpHeaders createHeaders() {
        HttpHeaders headers = new HttpHeaders();
        headers.set(HttpHeaders.AUTHORIZATION, "KEY " + apiKey);
        return headers;
    }
}

선택 이유

1. 직관적인 인터페이스 기반으로 설계가 가능하며, 보일러플레이트 코드가 최소화 됩니다.
2. 코드의 가독성 측면에서도 뛰어나다고 생각을 했습니다.
3. 확장성을 고려했을 때 Retry, Circuit Breaker 등을 도입하기 편하다고 생각을 했습니다.

하지만, 어노테이션과 인터페이스 기반으로 테스트를 통해 확인해야하지만 테스트 도구를 지원하지 않는다는 단점이 존재하긴 합니다.