Spring Boot에서 외부 API 연동을 설계할 때 보는 것

게시 2021/08/26

By August

조회 7 분읽는 시간

백엔드 개발을 하다 보면 내부 비즈니스 로직보다 외부 API를 붙이는 일이 더 자주 느껴질 때가 있다. 결제, 문자 발송, 인증, 배송, 지도, 파일 변환처럼 실무의 많은 기능이 외부 시스템과의 연동 위에서 동작한다.

외부 API 연동에서 중요한 것은 호출 코드 한 줄보다 장애가 났을 때 어디서 실패하고, 어떤 책임으로 복구할 것인지를 구조적으로 정리하는 것이다.

외부 API 연동은 왜 별도로 봐야 하나

외부 API는 내 애플리케이션이 통제하지 못하는 요소를 포함한다.

응답 속도가 느릴 수 있다
일시적으로 실패할 수 있다
응답 형식이 바뀔 수 있다
네트워크 문제와 인증 문제를 동반한다

즉, 단순한 메서드 호출이 아니라 불안정한 경계(boundary)를 다루는 일이다.

가장 먼저 정해야 할 것

외부 API 연동을 붙일 때는 먼저 이 세 가지를 분리해서 생각하는 편이 좋다.

호출 책임: HTTP 요청과 응답 처리
해석 책임: 외부 응답을 내부 모델로 변환
비즈니스 책임: 외부 응답을 바탕으로 어떤 결정을 할 것인가

이 세 책임이 한 클래스에 섞이면 테스트도 어렵고 장애 분석도 어려워진다.

어떤 클라이언트를 쓸 것인가

Spring 계열에서는 보통 다음 선택지가 있다.

RestTemplate
WebClient
OpenFeign 같은 선언형 클라이언트

중요한 것은 도구보다 기준이다.

`RestTemplate`

동기 호출에 단순하게 쓰기 쉽다
기존 레거시 코드와 호환성이 좋다

`WebClient`

논블로킹 모델과 더 잘 맞는다
타임아웃, 필터, 리액티브 흐름 구성에 유리하다

선언형 클라이언트

인터페이스 기반으로 호출 코드를 단순화할 수 있다
다만 숨겨진 설정을 잘 모르면 장애 원인 파악이 늦어질 수 있다

DTO를 바로 노출하지 않는 이유

외부 API 응답을 내부 도메인 모델과 바로 섞어 쓰면, 외부 형식 변화가 내부 전역으로 퍼진다.

그래서 보통은:

외부 응답 DTO
내부 변환 모델
서비스에서 사용할 값

처럼 한 번 경계를 분리하는 편이 낫다.

장애를 대비해 반드시 봐야 하는 것

타임아웃

타임아웃 없이 외부 API를 호출하면, 느린 응답이 전체 요청 지연으로 전파된다. 연결 타임아웃과 읽기 타임아웃을 분리해서 잡는 것이 기본이다.

재시도

재시도는 만능이 아니다. 일시적 네트워크 오류에는 도움이 되지만, 중복 요청이 위험한 API에서는 오히려 부작용이 생긴다. 따라서 idempotency를 먼저 확인해야 한다.

회로 차단과 fallback

외부 장애가 지속될 때 무한히 같은 연동을 붙잡고 있으면 전체 서비스가 같이 느려질 수 있다. 실패율이 높을 때는 빠르게 실패시키고, 대체 경로를 둘지 판단해야 한다.

로깅과 추적

외부 연동은 장애가 나면 “우리 쪽 문제인지 상대 문제인지”부터 구분해야 한다. 요청 URI, 상태 코드, 응답 시간, 추적 ID 같은 정보가 남아야 원인을 좁히기 쉽다.

외부 API와 MSA는 다른 문제다

실무에서 종종 외부 API 연동과 MSA를 비슷하게 보는 경우가 있지만, 둘은 다르다.

외부 API 연동: 다른 조직 또는 다른 시스템과의 경계
MSA: 내부 시스템을 여러 서비스로 분리한 구조

둘 다 네트워크 호출을 사용하지만, 통제 가능성과 계약 관리 방식이 다르다. 외부 API는 보통 더 불안정하고, 변경 통제가 어렵다.

테스트는 어떻게 가져가야 하나

외부 API 연동은 보통 세 수준으로 나눠서 보는 것이 좋다.

변환 로직 단위 테스트
HTTP 호출 레이어 통합 테스트
실제 연동 계약 확인 테스트

모든 테스트를 실 API에 의존하면 느리고 불안정해진다. 반대로 모킹만 하면 실제 응답 형식 문제를 놓치기 쉽다.

정리

Spring Boot에서 외부 API를 연동할 때 중요한 것은 어떤 클라이언트를 쓰느냐보다, 외부 경계를 어디서 어떻게 격리하느냐다.

핵심은 다음과 같다.

호출 책임과 비즈니스 책임을 분리한다
타임아웃과 실패 전략을 명시한다
외부 DTO와 내부 모델을 분리한다
장애 분석이 가능하도록 로그와 추적 정보를 남긴다

외부 API 연동은 기능 구현보다 실패 시나리오 설계가 더 중요하다는 점을 먼저 기억하는 편이 좋다.

Notes, Web