외부 API를 연동할 때 고려하면 좋은 점들

개요

최근 프로젝트에서 외부 API를 연동하는 일이 굉장히 많았었는데, 작업하면서 얻은 다양한 경험과 지식을 공유하고자 작성하게 되었습니다. 피드백은 언제든 환영이며 댓글 남겨주시면 감사하겠습니다.

 

 

1. I/O와 트랜잭션을 분리해라

트랜잭션은 데이터베이스와 통신하기 위해 커넥션을 필요로 한다. 하지만 이 커넥션을 생성하는 데는 꽤 많은 비용이 들며, 대부분 이를 절약하기 위해 웹 애플리케이션 서버(WAS)는 실행 시 미리 일정 수의 커넥션 객체를 만들어 풀에 저장한다. 그리고 클라이언트의 요청이 발생하면 이 풀에서 이미 생성되어 있는 커넥션 객체를 사용하는 방식을 이용한다.

그러나 커넥션 풀의 크기는 제한되어 있기 때문에, 동시에 수많은 요청들이 커넥션 풀의 개수 이상으로 오게 된다면, 커넥션을 획득하지 못한 요청들은 다른 요청이 끝나 커넥션이 반납될 때까지 기다리게 되기 때문에 지연이 발생하게 된다.

이러한 이유로 만약 트랜잭션 내부에 외부 API를 호출하는 I/O로직이 포함되어 있다면, 불필요하게 트랜잭션을 길게 잡고 있지 말도록 트랜잭션과 I/O 로직을 분리하는 것이 좋다. 다음의 방식들을 이용하면 손쉽게 분리할 수 있다.

1. 퍼사드 패턴(Facade Pattern) 사용
2. 이벤트 사용

퍼사드 패턴(Facade Pattern)은 사용하기 복잡한 클래스 라이브러리를 사용하기 편하게 간단한 인터페이스(API)로 구성하기 위한 구조 패턴이다. 보통 시스템이 복잡하거나 시스템을 사용하고 있는 외부와 결합도가 너무 높을 때 의존성을 낮추기 위해 사용한다. 혹은 순환 의존성 문제를 해결하기 위해서도 주로 사용한다.

@Service
public class FacadeExample {
    // 외부 api 연동 클래스
    private ExternalApiService apiService;
    
    // 트랜잭션을 처리하는 클래스
    private DatabaseService databaseService;
    
    public void saveDataFromExternalService(){
        Object data = apiService.getData();
        databaseService.save(data);
    }
}

위 예시에서 퍼사드 클래스는 외부 I/O 데이터를 수집하고, 데이터베이스에 저장하는 역할을 한다. 이를 통해 외부 API 요청과 트랜잭션을 분리할 수 있다.

두 번째는 이벤트를 사용하는 방법이다. 이전에 이 글에서 한번 정리한 적이 있다.

 

이 방식은 트랜잭션이 성공적으로 종료된 후에 특정 작업을 수행하는 경우에 효과적이다.

예를 들어, 회원가입 후 축하 메일을 전송하는 외부 API 호출이 필요한 상황을 가정해 보자. 이 경우 데이터의 일관성을 보장하기 위해 트랜잭션이 성공적으로 종료된 후에만 메일이 전송되어야 한다. 이를 위해 퍼사드 클래스에서 로직 마지막에 호출하는 방법으로 적용할 수도 있지만, ApplicationEventPublisher를 사용하여 트랜잭션이 성공적으로 커밋된 후에 이벤트 리스너가 작동하도록 설정할 수도 있다.

언제나 정답은 없기 때문에 본인의 프로젝트의 규칙과 상황에 알맞은 방법으로 적용하면 된다. 

 

 

2. 스레드풀로 요청 TPS를 조절해라

외부 API를 연동할 때는 우리 서비스의 컴퓨팅 환경도 중요하지만, 상대방의 컴퓨팅 환경을 특히 고려해야 한다. 우리 서비스가 초당 100개의 요청을 처리할 수 있더라도, 상대방 서버는 초당 10개의 요청만 처리할 수 있다면 해당 서버에 부하를 가하게 되기 때문이다.

이런 상황에서는 외부 API 요청을 위한 별도의 스레드 풀을 생성하여 요청 처리량(TPS)을 조절하는 것이 효과적이다.

별도로 스레드 풀을 설정하지 않고 사용한다면 공통 풀(common pool)을 사용할 것이다. 이 경우, 우리 컴퓨팅 환경이 허용하는 한 외부 API에 제한 없이 요청을 보내게 될 것이다. 이렇게 되면 외부 API를 제공하는 서버에 허용치 이상으로 요청이 가게 되어 해당 서버의 컴퓨팅 속도가 느려질 수 있다. 또한 서비스 A가 장애를 일으키면서 응답이 지연되면 풀에 남은 사용 가능한 커넥션이 줄어들면서 서비스 B와 C의 연동도 대기 상태에 놓이게 되는 연쇄 지연 문제가 발생하게 된다.

이러한 문제를 방지하기 위해 위 예시처럼 각 연동 API마다 별도의 스레드 풀을 지정하면 손쉽게 해결할 수 있다. 위의 경우에서는 서비스 A가 장애를 일으켜도 각 연동 서비스는 독립적인 스레드 풀을 갖기 때문에, 서비스 B와 C의 연동은 서비스 A의 상태에 영향을 받지 않는다.

또한 동시에 많은 요청이 들어오더라도, 스레드 풀에 지정된 스레드 수만큼만 동시에 작업을 처리할 수 있고, 나머지 요청들은 큐에서 대기하기 때문에 외부 API 서버에 가해지는 부하를 조절할 수 있다.

실제 사례로는 토스뱅크 대출 시스템 개발 과정에서도 살펴볼 수 있다.(SLASH 22 - 토스뱅크의 완전히 새로운 대출 시스템)

 

 

3. 비동기와 병렬 처리를 고려해라

하나의 로직에서 여러 개의 외부 API를 순차적으로 호출하는 경우, 처리시간이 상당히 소요될 수 있다. 이때 비동기와 병렬처리를 적용하면 전체적인 처리 시간을 크게 단축할 수 있다.

Java에서는 CompletableFuture를 활용하여 비동기와 병렬 처리를 구현할 수 있다. CompletableFuture 사용법에 대해서는 이전 글에서 작성한 적이 있다.

CompletableFuture를 사용할 때는 주의점이 있는데, 별도의 스레드 풀을 지정해주지 않으면 fork join pool이 사용된다는 점이다. fork join pool은 애플리케이션 전역에서 사용하는 풀로, 네트워크 I/O 작업과 같이 대기 시간이 긴 작업에서는 스레드가 블로킹되어 애플리케이션의 다른 부분에 영향을 줄 수 있으므로 I/O 위주의 작업일 경우 별도의 스레드풀을 꼭 지정해 주는 것이 좋다.

스레드 풀의 크기는 CPU Bound 작업의 경우 일반적으로 (코어 + 1)만큼을 지정해 준다. 하지만 I/O Bound 작업에서는 코어 수의 2배, 3배, 4배 혹은 그 이상을 상황에 따라 지정한다. 크기를 결정하기가 어려울 때는 아래의 공식을 참고하는 것도 좋다.

Nthreads = Ncpu * Ucpu * (1 + W/C)

- Ncpu는 사용 가능한 CPU 코어 수를 의미하며, Runtime.getRuntime().availableProcessors()가 반환하는 값을 사용한다.
- Ucpu는 CPU 활용 비율로, 0과 1 사이의 값을 가진다.
- W/C는 대기 시간과 계산 시간의 비율을 의미한다.

그렇다면 스레드풀의 개수를 무작정 많이 늘리면 성능이 좋아질까? 그건 또 아니다. CPU 코어에서 실행되던 스레드가 다른 스레드로 바뀔 때마다 Context Switching이 발생하며 이로 인해 CPU 시간이 추가로 소요된다. 따라서 CPU 코어 수를 초과하는 스레드를 생성하면 Context Switching으로 인한 오버헤드가 증가하게 되고 특정 개수 이상부터는 성능이 오히려 저하될 수 있다.

 

 

4. 서킷 브레이커를 통해 흐름을 제어해라

외부 API를 사용할 때 특정 API에 문제가 발생하여 에러가 나거나 응답이 지연되는 상황에서 계속해서 해당 외부 API를 호출한다면 우리 애플리케이션의 응답도 지연되는 문제가 발생할 수 있다. 이런 경우 서킷브레이커를 활용하여 흐름을 제어할 수 있다.

서킷 브레이커는 전기 회로에서 과부하가 발생하면 회로를 끊어 피해를 최소화하는 원리에서 아이디어를 얻은 패턴이다. API 호출에 문제가 생겨 임계치 이상의 지연응답이나 에러율이 발생한다면 해당 API 호출을 더 이상 하지 않고, 즉시 에러를 반환하여 외부 서비스에 대한 불필요한 호출을 방지하고 우리 클라이언트에게 빠르게 응답을 보낼 수 있다. 또한 외부 API A를 B로 대체가 가능하다면 A의 호출을 중단하고 B를 호출하도록 제어할 수도 있다.

서킷 브레이커는 크게 세 가지 상태를 가진다. 

• Closed 상태: 정상적으로 작동하는 상태이다. API 호출이 잘 이루어지고, 에러율이 특정 임계치 이하일 경우 이 상태를 유지한다.
• Open 상태: API 호출에 문제가 생겨 에러율이 임계치를 초과하면, 서킷 브레이커는 Open 상태가 된다. 이 상태에서는 모든 API 호출을 차단하고, 즉시 에러 응답을 반환한다.
• Half-Open 상태: Open 상태에서 일정 시간이 지나면, 서킷 브레이커는 Half-Open 상태가 된다. 이 상태에서는 일부 API 호출을 허용하여 외부 서비스가 정상으로 복구되었는지를 확인한다. 이때 API 호출이 성공하면 서킷 브레이커는 다시 Closed 상태로 돌아가고, 실패하면 Open 상태를 유지한다.

서킷 브레이커를 구현하기 위한 라이브러리로는 Netflix의 Hystrix, Resilience4J 등이 있으니 활용하면 좋다.

 

 

5. Rate Limit을 걸어라

일정 시간 동안 동일한 요청이 지나치게 많이 들어오는 것을 제어하거나, 특정 기관에서 일정 시간 동안 API 호출 횟수를 제한하는 등의 상황에서 Rate Limit 기능을 적용하면 좋은 선택이 될 수 있다.

처리율 제한을 위한 다양한 알고리즘이 있으며 각각의 상황에 알맞게 적용하면 된다.

• 토큰 버킷 알고리즘:  버킷에 일정 시간마다 토큰이 쌓이고, 요청이 들어올 때마다 토큰을 사용하는 방식이다. 버킷에 토큰이 없다면 요청을 받지 않으며, 일정한 속도로 요청을 처리하는 데 적합하다.
• 누출 버킷 알고리즘: 버킷에 요청이 쌓이고 일정 속도로 버킷에서 누출되어 처리되는 방식이다. 버킷이 가득 찼을 때 추가로 들어오는 요청은 거부되며, 요청의 폭발적인 증가를 막는 데 유용하다.
• 고정 윈도우 알고리즘: 시간을 일정한 윈도우로 나누고, 각 윈도우에서 처리할 수 있는 요청의 수를 제한하는 방식이다. 윈도우가 바뀌면 요청 수는 초기화되며, 구현이 간단하지만 윈도우 변경 시점에 요청이 몰릴 수 있는 문제가 있다.
• 슬라이딩 로그 알고리즘: 고정 윈도우 알고리즘의 문제를 해결하기 위한 방식으로, 각 요청을 로그로 기록하고 일정 시간 동안의 로그 수를 확인하여 요청을 제한한다. 이 방식은 정확한 요청 수를 유지할 수 있지만, 로그를 관리하는 데 추가적인 비용이 든다.
• 슬라이딩 윈도우 알고리즘: 고정 윈도우와 슬라이딩 로그를 결합한 방식으로, 윈도우를 일정 간격으로 슬라이딩하면서 요청을 제한한다. 이 방식은 고정 윈도우의 문제를 해결하고 슬라이딩 로그보다 효율적으로 요청을 관리할 수 있다.

Guava, Resilience4j, Bucket4j 등의 라이브러리를 활용하면, Rate Limit 기능을 쉽게 구현할 수 있다. 인터넷에 이에 관한 다양한 자료들이 많으니 자세한 학습을 원한다면 찾아보길 바라며, 책으로 학습하고 싶다면 가상 면접 사례로 배우는 대규모 설계 시스템 설계 기초 1권에서 찾아볼 수 있다.

 

 

6. 타임아웃을 설정해라

Java에서 RestTemplate나 WebClient를 사용할 때, 타임아웃을 명시적으로 설정하지 않으면 무제한으로 설정된다. 이러한 상황에서 동시에 대기하는 외부 연동 개수가 많아지면, 내 서비스의 속도는 점차 느려지게 되며 최악의 경우 모든 스레드가 대기 상태에 빠져 다른 클라이언트 요청에 응답할 수 있는 스레드가 남아있지 않게 된다. 따라서 타임아웃 설정은 반드시 필요하다.

보통 연결 타임아웃(Connection Timeout)과 읽기 타임아웃(Read Timeout)을 1초에서 5초 이내로 설정한다. 일반적으로 정상적인 통신인 경우 대부분 이 안에 완료되기 때문이다. 하지만 상황에 달라질 수 있으므로, 애플리케이션의 상황에 알맞게 적용하면 된다.

• 연결 타임아웃(Connection Timeout): 클라이언트가 서버에 연결을 시도하고, 연결이 성공할 때까지의 시간을 의미한다. 네트워크 상태나 서버의 가용성 등에 따라 변할 수 있다.
• 읽기 타임아웃(Read Timeout): 서버와 연결이 성공한 후, 클라이언트가 응답을 기다리는 시간을 의미한다. 외부 서비스의 처리 속도에 따라 변할 수 있다.

 

 

7. 캐싱 처리를 고려해라

외부 API로부터 데이터를 조회해오는 경우, 해당 데이터가 실시간 성이 짙은 값이 아니라면 매번 요청을 보내는 것보다는 캐싱된 값을 응답하는 것도 좋은 방법이다. API 연동 과정을 아무리 최적화하더라도 애초에 불필요한 호출을 줄이는 것이 가장 효율적인 방법일 수 있다는 것을 명심하자.

 

 

8. 재시도 처리해라

API 통신은 네트워크 이슈 등으로 간헐적으로 실패할 수 있다. 그러므로 한 번의 호출이 실패했을 때 즉시 실패 응답을 반환하기보다는, 일정 횟수만큼 요청을 재시도하는 것이 더 효율적일 수 있다.

Spring은 이런 재시도 처리를 쉽게 구현할 수 있도록 spring-retry 라이브러리에서 RetryTemplate을 제공한다. RestTemplate을 사용하는 경우에는 RetryTemplate을 구현해야 하며, WebClient를 사용하는 경우에는 WebClient 자체에서 재시도 기능을 제공하기 때문에 별도로 구현할 필요 없이 재시도 횟수만 지정해 주면 된다. 

아래는 RestTemplate와 WebClient에서 재시도 로직을 사용하는 방법이다.

@Configuration
class RestTemplateConfig {

    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplateBuilder()
                .setConnectTimeout(Duration.ofSeconds(5))
                .setReadTimeout(Duration.ofSeconds(5))
                .additionalInterceptors(clientHttpRequestInterceptor())
                .build();
    }

    public ClientHttpRequestInterceptor clientHttpRequestInterceptor() {
        return (request, body, execution) -> {
            RetryTemplate retryTemplate = new RetryTemplate();
            retryTemplate.setRetryPolicy(new SimpleRetryPolicy(3));
            try {
                return retryTemplate.execute(context -> execution.execute(request, body));
            } catch (Throwable throwable) {
                throw new RuntimeException(throwable);
            }
        };
    }

}

WebClient webClient = WebClient.create("http://example.com");
webClient.get()
    .uri("/some-data")
    .retrieve()
    .bodyToMono(String.class)
    .retryWhen(Retry.backoff(3, Duration.ofSeconds(1))) // 재시도 횟수와 간격 설정
    .subscribe();