외부 API 연동 — 타임아웃·재시도·멱등성·서킷 브레이커·동시 한도·폴백

협력사 API 가 느리거나 죽거나 틀린 답을 줄 때 우리 시스템이 같이 죽지 않도록, HttpClient 하나로 타임아웃·재시도·멱등 키·서킷 브레이커·동시 한도·폴백을 직접 만들어 봅니다.

1. 왜 배우는가

Spring Boot + MyBatis 로 사내 업무 시스템을 만들면 결제 PG, 문자 발송, 공공데이터, 사내 다른 시스템 API 를 자주 호출합니다. 이런 호출은 우리가 통제할 수 없는 상대에게 의존합니다. 상대가 느려지거나 죽거나 이상한 응답을 주는 순간이 반드시 옵니다.

문제는 그 순간이 우리 서버 전체를 끌고 내려갈 수 있다는 점입니다. 톰캣 스레드 200개가 모두 죽은 상대의 응답을 기다리며 멈추면, 그 API 와 아무 관련 없는 화면까지 함께 멈춥니다. 이런 "연쇄 장애" 를 막는 것이 이번 레슨의 목표입니다.

실무 확장 07 레슨은 우리가 API 서버가 되어 요청을 받는 쪽을 다뤘습니다. 이번 레슨은 반대로 우리가 클라이언트가 되어 남의 API 를 호출하는 쪽입니다. 같은 HTTP 지식이지만 지켜야 할 규칙은 다릅니다.

배울 내용은 타임아웃, 재시도, 멱등성, 서킷 브레이커, 동시 한도, 폴백, 폐쇄망 연동 설정 일곱 가지입니다. 코드는 java-src/extension/11_external_api 에 있고 Main·ApiClient·CircuitBreaker·FakePartner 네 파일로 구성됩니다.

FakePartner 는 협력사 API 가 보이는 증상, 즉 느림·간헐 오류·항상 오류·잘못된 요청을 같은 JVM 안에서 재현하는 가짜 서버입니다. Main 을 실행하면 이 증상들을 ApiClient 로 실제로 방어하는 8가지 장면을 볼 수 있습니다.

이런 방어를 처음부터 다 넣을 필요는 없습니다. 호출량이 적은 사내 API 는 타임아웃만으로 충분한 경우가 많고, 결제처럼 돈이 오가는 호출만 멱등 키와 서킷까지 갖춥니다. 이 레슨은 6가지를 전부 보여주지만, 실제 적용은 위험도에 따라 골라 쓰는 것이 맞습니다.