B컷전문 | 개발과 인생의 이야기

Spring Boot에서 OpenFeign을 활용해 외부 API를 연동하는 아키텍처 설계 방법을 설명합니다. 선언적 HTTP 클라이언트 구현, 예외 처리, 로깅, 운영 적용 팁까지 실전 예제로 구성했습니다.

 

Spring Boot에서 외부 API를 호출할 때,
기존에는 RestTemplate이나 WebClient를 사용해 직접 요청/응답 코드를 작성하는 방식이 일반적이었습니다.
하지만 복잡한 API 연동이 많아질수록 코드가 중복되고,
가독성·테스트성·재사용성이 떨어지는 문제가 생깁니다.

이때 가장 실용적인 대안 중 하나가 바로 OpenFeign입니다.
OpenFeign은 HTTP 클라이언트를 인터페이스 선언만으로 자동 생성해주는 도구로,
Netflix OSS 생태계에서 시작되어 현재는 Spring Cloud 공식 지원 클라이언트입니다.

---

1. OpenFeign의 특징

항목 내용

개발 방식	인터페이스 선언만으로 API 호출 구현
통합성	Spring Cloud 및 Eureka 등과 자연스럽게 통합 가능
유지보수	응답 모델, 경로 변경에 대한 리팩토링이 용이
실무 적용	B2B 연동, 마이크로서비스 간 통신, API Gateway 연계 등에 자주 활용됨

---

2. OpenFeign 설정 방법

1) 의존성 추가 (Spring Boot 3 기준)

implementation 'org.springframework.cloud:spring-cloud-starter-openfeign'

※ 버전은 spring-cloud-dependencies BOM을 통해 관리:

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:2023.0.0"
    }
}

---

2) 애플리케이션 클래스에 Feign 활성화

@SpringBootApplication
@EnableFeignClients
public class MyApplication {}

---

3. Feign Client 인터페이스 선언

@FeignClient(name = "publicApiClient", url = "https://api.publicapis.org")
public interface PublicApiClient {

    @GetMapping("/entries")
    PublicApiResponse getEntries();
}

Feign은 위와 같은 인터페이스만으로도 GET https://api.publicapis.org/entries 요청을 자동 생성하고 응답을 바인딩합니다.

---

응답 DTO 예시

@Getter
public class PublicApiResponse {
    private int count;
    private List<Entry> entries;

    @Getter
    public static class Entry {
        private String API;
        private String Description;
        private String Link;
    }
}

---

4. Controller에서 사용

@RestController
@RequiredArgsConstructor
public class ApiController {

    private final PublicApiClient publicApiClient;

    @GetMapping("/external/apis")
    public ResponseEntity<?> getApis() {
        return ResponseEntity.ok(publicApiClient.getEntries());
    }
}

→ 선언적이고 가독성이 높은 외부 API 호출 코드 완성

---

5. 예외 처리 전략

Feign 사용 시 예외 처리 방식은 반드시 고려해야 합니다.
기본적으로 다음과 같은 예외가 발생할 수 있습니다.

• FeignException.FeignClientException (4xx)
• FeignException.FeignServerException (5xx)
• RetryableException (타임아웃 등)

1) Feign 에러 디코더 설정

@Configuration
public class FeignErrorDecoderConfig {

    @Bean
    public ErrorDecoder errorDecoder() {
        return (methodKey, response) -> {
            if (response.status() == 404) {
                return new CustomNotFoundException("API 응답 없음");
            }
            return new Default();
        };
    }
}

---

2) 로깅 설정 (FeignLoggerFactory)

@Bean
Logger.Level feignLoggerLevel() {
    return Logger.Level.FULL;
}

logging:
  level:
    com.example.client: DEBUG

---

6. 운영 환경 적용 팁

항목 전략

Base URL 관리	application.yml에 설정하고 @Value로 주입
Retry 정책	feign.retryer 설정으로 재시도 제어 가능
Timeout 제어	feign.client.config.default.connectTimeout 등 설정
Load Balancing	name 속성을 통해 Eureka 등과 통합 시 클러스터 호출 가능
요청 가시화	OpenFeign + Sleuth + Zipkin 조합으로 추적 가능

---

마무리 요약

항목 요약

사용 목적	선언적으로 외부 REST API 연동을 단순화
핵심 장점	코드량 감소, 인터페이스 기반 호출, 유지보수 용이
예외 처리	ErrorDecoder로 표준화 가능
운영 적용	Retry, Timeout, 로깅, 클러스터 연계까지 확장 가능
추천 사용처	마이크로서비스 간 통신, 외부 API 연동, 정형화된 서비스 호출

---

다음 편 예고

Spring Boot 시리즈 33편: Spring Cloud Gateway – API 게이트웨이 설계와 트래픽 라우팅 전략