문서가격블로그
문의하기
로그인무료로 가입하기
Back to Tech Articles

Go에서 견고한 HTTP 클라이언트 설계: 재시도, 시간 제한 및 서킷 브레이커를 통한 안정성 향상

10월 11, 2025
# Misc

Daniel Hayes

Full-Stack Engineer · Leapcell

이 게시물은 English, 日本語 및 Deutsch에서도 볼 수 있습니다.
Cover of "Go에서 견고한 HTTP 클라이언트 설계: 재시도, 시간 제한 및 서킷 브레이커를 통한 안정성 향상"

소개

현대의 분산 시스템에서 서비스들은 HTTP를 통해 서로 자주 상호작용합니다. Go의 net/http 패키지가 이러한 요청을 만드는 데 견고하고 효율적인 http.Client를 제공하지만, 원시적인 사용은 종종 프로덕션 요구 사항에 미치지 못합니다. 네트워크 호출은 본질적으로 신뢰할 수 없습니다. 일시적인 네트워크 문제, 서버 과부하 또는 예상치 못한 지연 시간으로 인해 실패할 수 있습니다. 적절한 안전 장치 없이는 이러한 실패가 시스템 전체에 전파되어 연쇄적인 장애를 일으키고 사용자 경험을 저하시킬 수 있습니다. 본 기사에서는 Go의 표준 http.Client를 래핑하여 필수적인 내결함성 패턴인 재시도, 시간 제한 및 서킷 브레이커를 통합하는 방법을 자세히 알아봅니다. 이러한 전략을 채택함으로써 애플리케이션의 복원력과 안정성을 크게 향상시켜 역경 속에서도 안정적인 통신을 보장할 수 있습니다.

핵심 개념 설명

구현 세부 사항에 앞서, 논의할 핵심 분산 시스템 패턴을 명확히 해 보겠습니다.

시간 제한(Timeout): 시간 제한은 작업이 중단되기 전에 허용되는 최대 지속 시간을 정의합니다. 주된 목적은 클라이언트가 응답을 무기한 기다리는 것을 방지하여 리소스를 확보하고 중단된 요청의 백로그를 방지하는 것입니다. 일반적으로 연결 시간 제한(연결 설정용)과 요청 시간 제한(전체 요청-응답 주기용)의 두 가지 유형이 있습니다.

재시도(Retry): 재시도 메커니즘은 실패가 일시적일 수 있다고 가정하고 실패한 작업을 자동으로 다시 시도합니다. 대상 서비스를 압도하지 않고 서비스가 복구할 시간을 주기 위해 지수 백오프 전략과 최대 시도 횟수를 사용하여 재시도를 구현하는 것이 중요합니다. 모든 오류가 재시도 가능한 것은 아닙니다. 예를 들어, '400 Bad Request'는 재시도 시 마법처럼 '200'으로 바뀌지 않습니다.

서킷 브레이커(Circuit Breaker): 전기 회로 차단기에서 영감을 받은 이 패턴은 애플리케이션이 실패할 운명인 작업을 반복적으로 실행하려고 시도하는 것을 방지합니다. 서킷 브레이커가 높은 비율의 실패를 감지하면 '트립'(열림)되어 후속 호출을 시도하지 않고 즉시 실패시킵니다. 미리 정의된 간격 후에 '반열림' 상태로 전환하여 제한된 수의 테스트 요청을 통과시킵니다. 이러한 요청이 성공하면 서킷이 다시 '닫힘' 상태가 됩니다. 그렇지 않으면 열림 상태로 돌아갑니다. 이 패턴은 연쇄적인 실패를 방지하고 실패하는 서비스가 복구할 시간을 줍니다.

복원력 있는 HTTP 클라이언트 구축

우리의 목표는 이러한 내결함성 기능을 원활하게 통합하는 http.Client의 데코레이터를 만드는 것입니다. 사용자 정의 HTTPClient 인터페이스와 그 구현을 설계해 보겠습니다.

초기 설정 및 기본 클라이언트

먼저, 쉬운 모의 테스트 및 테스트를 위해 HTTP 클라이언트에 대한 간단한 인터페이스를 정의합니다.

package resilientclient

import (
	"net/http"
	"time"
)

// HTTPClient 인터페이스는 당사 클라이언트에 대한 계약을 정의합니다.
type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

// defaultClient는 표준 http.Client를 래핑합니다.
type defaultClient struct {
	client *http.Client
}

// NewDefaultClient는 새 기본 클라이언트를 생성합니다.
func NewDefaultClient(timeout time.Duration) HTTPClient {
	return &defaultClient{
		client: &http.Client{
			Timeout: timeout, // 기본 요청 시간 제한
			Transport: &http.Transport{
				MaxIdleConns:        100,
				IdleConnTimeout:     90 * time.Second,
				TLSHandshakeTimeout: 10 * time.Second,
				// 더 많은 전송 옵션을 여기에 추가할 수 있습니다.
			},
		},
	}
}

// Do는 defaultClient에 대한 HTTPClient 인터페이스를 구현합니다.
func (c *defaultClient) Do(req *http.Request) (*http.Response, error) {
	return c.client.Do(req)
}

여기서 http.Client.Timeout을 통해 기본 요청 시간 제한을 이미 도입했습니다. 이는 무기한 대기를 방지하는 좋은 출발점입니다.

재시도 구현

재시도는 Do 메서드를 래핑합니다. 다른 HTTPClient를 인수로 받는 RetryClient를 도입할 것입니다.

package resilientclient

import (
	"fmt"
	"io"
	"io/ioutil"
	"log"
	"net/http"
	"time"
	"bytes"
)

// RetryConfig는 재시도 논계를 위한 매개 변수를 보유합니다.
type RetryConfig struct {
	MaxRetries    int
	InitialDelay  time.Duration
	MaxDelay      time.Duration
	// 특정 오류를 재시도하지 않아야 하는 경우 술어 함수를 추가합니다.
	ShouldRetry func(*http.Response, error) bool
}

// RetryClient는 HTTP 요청에 대한 재시도 논계를 제공합니다.
type RetryClient struct {
	delegate HTTPClient
	config   RetryConfig
}

// NewRetryClient는 재시도 기능이 있는 새 클라이언트를 생성합니다.
func NewRetryClient(delegate HTTPClient, config RetryConfig) *RetryClient {
	if config.MaxRetries == 0 {
		config.MaxRetries = 3 // 기본 재시도 횟수
	}
	if config.InitialDelay == 0 {
		config.InitialDelay = 100 * time.Millisecond // 기본 초기 지연
	}
	if config.MaxDelay == 0 {
		config.MaxDelay = 5 * time.Second // 기본 최대 지연
	}
	if config.ShouldRetry == nil {
		config.ShouldRetry = func(resp *http.Response, err error) bool {
			if err != nil {
				return true // 네트워크 오류는 일반적으로 재시도 가능합니다.
			}
			// 서버 측 오류(예: 5xx)를 나타내는 상태 코드
			return resp.StatusCode >= 500
		}
	}
	return &RetryClient{
		delegate: delegate,
		config:   config,
	}
}

func (c *RetryClient) Do(req *http.Request) (*http.Response, error) {
	var (
		resp *http.Response
		err  error
		delay = c.config.InitialDelay
	)

	for i := 0; i < c.config.MaxRetries; i++ {
		// 중요: 본문이 있는 요청의 경우, 첫 번째 시도 후 원본 판독기가 소비되므로
		// 각 재시도에 대해 본문 판독기를 재설정해야 합니다.
		if req.Body != nil {
			// 본문이 재설정 가능한지 확인합니다 (예: *http.NoBody, bytes.Buffer 또는 사용자 정의 io.Seeker).
			if seeker, ok := req.Body.(io.Seeker); ok {
				_, seekErr := seeker.Seek(0, io.SeekStart)
				if seekErr != nil {
					return nil, fmt.Errorf("failed to seek request body: %w", seekErr)
				}
			} else {
				// 탐색 가능하지 않은 경우, 전체 본문을 메모리로 읽고 새 NopCloser를 만듭니다.
				// 재시도가 예상되는 경우 원본 본문에 대해 `bytes.Buffer` 또는 `io.ReaderAt`을 사용하는 것을 고려하십시오.
				// 일반적으로 대규모 페이로드에는 이상적이지 않습니다.
				bodyBytes, readErr := ioutil.ReadAll(req.Body)
				if readErr != nil {
					return nil, fmt.Errorf("failed to read request body for retry: %w", readErr)
				}
				req.Body = ioutil.NopCloser(bytes.NewReader(bodyBytes))
			}
		}

		resp, err = c.delegate.Do(req)

		if c.config.ShouldRetry(resp, err) {
			log.Printf("Request failed (attempt %d/%d), retrying in %v. Error: %v", i+1, c.config.MaxRetries, delay, err)
			time.Sleep(delay)
			delay = time.Duration(float64(delay) * 2) // 지수 백오프
			if delay > c.config.MaxDelay {
				delay = c.config.MaxDelay
			}
			continue
		}
		return resp, err // 성공 또는 재시도 불가능한 오류
	}

	return resp, err // 모든 재시도가 실패하면 마지막 응답/오류 반환
}

요청 본문에 대한 중요 고려 사항: 본문(예: POST, PUT)을 보내는 요청을 재시도할 때 req.Body(io.ReadCloser)는 첫 번째 Do 호출 후에 소비됩니다. 후속 재시도의 경우 본문이 비어 있게 되어 잘못된 요청이 발생합니다. 제공된 코드는 본문이 io.Seeker인 경우 백으로 또는 전체 본문을 메모리로 읽어 새 NopCloser를 만들어 이를 처리하려고 시도합니다. 대규모 본문의 경우 메모리로 읽는 것은 비효율적일 수 있으므로 원래 http.Request 본문을 탐색 가능하도록 설계하는 것이 좋습니다(예: bytes.Buffer 사용).

서킷 브레이커 구현

서킷 브레이커의 경우 sony/gobreaker와 같은 성숙한 라이브러리를 활용할 수 있습니다. 이 라이브러리는 서킷 브레이커 패턴에 대한 강력한 구현을 제공합니다.

package resilientclient

import (
	"fmt"
	"net/http"
	"time"

	"github.com/sony/gobreaker"
)

// CircuitBreakerClient는 서킷 브레이킹 기능으로 HTTPClient를 래핑합니다.
type CircuitBreakerClient struct {
	delegate HTTPClient
	breaker  *gobreaker.CircuitBreaker
}

// NewCircuitBreakerClient는 서킷 브레이커 기능이 있는 새 클라이언트를 생성합니다.
func NewCircuitBreakerClient(delegate HTTPClient, settings gobreaker.Settings) *CircuitBreakerClient {
	if settings.Name == "" {
		settings.Name = "default-circuit-breaker"
	}
	if settings.Timeout == 0 {
		settings.Timeout = 60 * time.Second // '열림' 상태에서 '반열림' 시도까지 대기 시간
	}
	if settings.MaxRequests == 0 {
		settings.MaxRequests = 1 // '반열림' 상태에서 1개의 요청 허용
	}
	if settings.Interval == 0 {
		settings.Interval = 5 * time.Second // 카운트 재설정 시간
	}
	if settings.ReadyToTrip == nil {
		settings.ReadyToTrip = func(counts gobreaker.Counts) bool {
			failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
			// 요청이 3회 이상이고 60%가 실패하면 트립
			return counts.Requests >= 3 && failureRatio >= 0.6
		}
	}

	return &CircuitBreakerClient{
		delegate: delegate,
		breaker:  gobreaker.NewCircuitBreaker(settings),
	}
}

func (c *CircuitBreakerClient) Do(req *http.Request) (*http.Response, error) {
	// Execute 메서드는 브레이커가 닫혔거나 반열림 상태이면 제공된 함수를 호출합니다.
	// 브레이커가 열려 있으면 즉시 gobreaker.ErrOpenState를 반환합니다.
	result, err := c.breaker.Execute(func() (interface{}, error) {
		resp, err := c.delegate.Do(req)
		if err != nil {
			// delegate의 오류 (네트워크 오류, 시간 초과 등)는 실패로 간주되어야 합니다.
			return nil, err
		}
		// 서킷 브레이커의 경우, 서버 측 오류(5xx)도 실패로 간주합니다.
		if resp.StatusCode >= 500 {
			// 중요: 리소스 누수를 방지하려면 인터페이스에 nil만 반환하는 경우에도
			// 본문을 읽고 닫아야 합니다.
			// 또는 이상적으로는 *http.Response를 interface{}로 반환하고 호출자가
			// 실패 시 본문을 처리하도록 하는 것이 더 깨끗합니다.
			// 여기서는 단순화를 위해 실패를 표시합니다.
			return resp, fmt.Errorf("server error: %d", resp.StatusCode)
		}
		return resp, nil
	})

	if err != nil {
		if err == gobreaker.ErrOpenState {
			return nil, fmt.Errorf("circuit breaker is open: %w", err)
		}
		// 서버 오류 또는 네트워크 오류인 경우 원본 오류를 반환합니다.
		// 오류가 형식화된 서버 오류인 경우 인터페이스로 반환된 경우 응답을 추출할 수 있습니다.
		if resp, ok := result.(*http.Response); ok && resp != nil {
			return resp, err // 서킷 트립 고려 전에 받은 응답 반환
		}
		return nil, err
	}

	return result.(*http.Response), nil
}

gobreaker 라이브러리는 상태 전환(닫힘, 열림, 반열림) 및 오류 횟수를 자동으로 처리합니다. gobreaker.Settings로 구성하여 트립 및 복구를 위한 임계값을 정의합니다. Execute 메서드는 실제 작업을 수행하는 함수를 인수로 받아 interface{}, error를 반환합니다. gobreaker 라이브러리는 반환된 오류를 사용하여 작업이 실패했는지 여부를 결정합니다.

엮기

이 데코레이터 패턴의 장점은 이러한 클라이언트를 서로 엮을 수 있다는 것입니다. 일반적인 설정은 다음과 같습니다. CircuitBreakerClient는 RetryClient를 래핑하고 RetryClient는 DefaultClient를 래핑합니다. 이는 다음을 보장합니다.

  1. 시도하기 전에 서킷 브레이커는 원격 서비스가 다운되었을 가능성이 있는지 확인합니다.
  2. 서킷이 닫히면(또는 반열림 상태이면) 요청이 재시도 논리로 진행됩니다.
  3. 재시도 논리는 백오프로 일시적인 오류를 처리합니다.
  4. 기본 defaultClient는 기본 시간 제한으로 실제 HTTP 요청을 처리합니다.
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"time"

	"github.com/sony/gobreaker"
	"your_module_path/resilientclient" // resilientclient가 하위 패키지에 있다고 가정
)

func main() {
	// 1. 기본 시간 제한으로 기본 클라이언트 생성
	baseClient := resilientclient.NewDefaultClient(5 * time.Second)

	// 2. 재시도 논리로 래핑
	retryConfig := resilientclient.RetryConfig{
		MaxRetries:   5,
		InitialDelay: 200 * time.Millisecond,
		MaxDelay:     10 * time.Second,
		ShouldRetry: func(resp *http.Response, err error) bool {
			if err != nil {
				return true // 네트워크 오류 시 재시도
			}
			// 특정 서버 오류 또는 너무 많은 요청에 대해서만 재시도
			return resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= http.StatusInternalServerError
		}}
	retryClient := resilientclient.NewRetryClient(baseClient, retryConfig)

	// 3. 서킷 브레이커로 래핑
	cbSettings := gobreaker.Settings{
		Name:        "ExternalService",
		MaxRequests: 3,                 // 반열림 상태에서 3개의 요청 허용
		Interval:    5 * time.Second,   // 5초마다 카운트 재설정
		Timeout:     30 * time.Second,  // 반열림 시도 전 30초 동안 열림
		ReadyToTrip: func(counts gobreaker.Counts) bool {
			failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
			return counts.Requests >= 10 && failureRatio >= 0.3 // 요청 10개 중 30% 실패 시 트립
		},
	}
	resilientHttClient := resilientclient.NewCircuitBreakerClient(retryClient, cbSettings)

	// 예제 사용법
	for i := 0; i < 20; i++ {
		req, err := http.NewRequest("GET", "http://localhost:8080/api/data", nil)
		if err != nil {
			log.Fatalf("Error creating request: %v", err)
		}

		log.Printf("Making request %d...", i+1)
		resp, err := resilientHttClient.Do(req)
		if err != nil {
			log.Printf("Request %d ERROR: %v", i+1, err)
			time.Sleep(500 * time.Millisecond) // 호출 간 약간의 지연 시뮬레이션
			continue
		}

		defer resp.Body.Close()
		body, _ := io.ReadAll(resp.Body)
		log.Printf("Request %d SUCCESS: Status %d, Body: %s", i+1, resp.StatusCode, string(body))
		time.Sleep(500 * time.Millisecond)
	}
}

이 main 함수는 resilientHttClient를 구성하고 사용하는 방법을 보여줍니다. 일반적으로 http://localhost:8080/api/data를 실제 서비스 엔드포인트로 바꿔야 합니다.

적용 시나리오

이 패턴은 다음에서 매우 유용합니다.

  • 마이크로서비스 통신: 네트워크 문제 또는 일시적인 의존성 과부하에도 불구하고 서비스 간 호출이 안정적으로 유지되도록 합니다.
  • 외부 API 통합: 속도 제한이 있거나 간헐적으로 불안정한 타사 API를 안정적으로 사용합니다.
  • 데이터베이스 상호 작용 (간접적): http.Client는 직접적인 데이터베이스 상호 작용용은 아니지만, 데이터베이스를 프론트하는 HTTP API를 노출하는 서비스가 있는 경우 이러한 패턴은 데이터베이스 관련 서비스 장애로부터 보호합니다.

결론

Go의 표준 http.Client를 재시도, 시간 제한 및 서킷 브레이커 논리로 프로그래밍 방식으로 래핑함으로써 기본 HTTP 클라이언트를 프로덕션 준비가 된 내결함성 구성 요소로 전환했습니다. 이 계층화된 접근 방식은 데코레이터 패턴을 사용하여 관심사를 분리하고 코드를 더 유지 관리하기 쉽고 강력하게 만듭니다. 이러한 패턴을 구현하는 것은 단순히 오류를 처리하는 것이 아니라, 정상적으로 저하되고 복구되는 복원력 있는 시스템을 구축하는 것이며, 까다로운 분산 환경에서도 지속적인 작동을 보장합니다. 견고함은 선택 사항이 아니라 안정적인 분산 시스템의 기본입니다.

Share this article

HackerNews

More Posts from Leapcell

cover

Goose 대 GORM 마이그레이션 - Go 프로젝트에 적합한 데이터베이스 마이그레이션 도구 선택하기

cover

Go 웹 핸들러에서 데이터 무결성 보장하기

Popular Posts