패키지 함수와 클라이언트 메서드

패키지 레벨 HTTP 메서드

클라이언트를 생성할 필요 없이 직접 요청을 전송합니다. 내부적으로 지연 초기화된 기본 클라이언트를 사용합니다.

Get

func Get(url string, options ...RequestOption) (*Result, error)

GET 요청을 전송합니다.

result, err := httpc.Get("https://api.example.com/data",
    httpc.WithBearerToken(token),
    httpc.WithQuery("page", 1),
)

Post

func Post(url string, options ...RequestOption) (*Result, error)

POST 요청을 전송합니다.

result, err := httpc.Post("https://api.example.com/users",
    httpc.WithJSON(map[string]any{"name": "test"}),
)

Put / Patch / Delete / Head / Options

func Put(url string, options ...RequestOption) (*Result, error)
func Patch(url string, options ...RequestOption) (*Result, error)
func Delete(url string, options ...RequestOption) (*Result, error)
func Head(url string, options ...RequestOption) (*Result, error)
func Options(url string, options ...RequestOption) (*Result, error)

Request

func Request(ctx context.Context, method, url string, options ...RequestOption) (*Result, error)

컨텍스트가 포함된 범용 요청 메서드로, 타임아웃과 취소 제어를 지원합니다.

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := httpc.Request(ctx, "GET", "https://api.example.com/data")

클라이언트 메서드

Client 인터페이스는 패키지 레벨 함수와 동일한 HTTP 메서드와 컨텍스트가 포함된 Request 메서드를 제공합니다.

New

func New(config ...*Config) (Client, error)

새 HTTP 클라이언트를 생성합니다. 설정을 전달하지 않거나 nil을 전달하면 DefaultConfig()를 사용합니다.

client, err := httpc.New()
client, err := httpc.New(nil)
client, err := httpc.New(httpc.SecureConfig())

cfg := httpc.DefaultConfig()
cfg.Timeouts.Request = 60 * time.Second
client, err := httpc.New(cfg)

클라이언트 HTTP 메서드

result, err := client.Get(url, options...)
result, err := client.Post(url, options...)
result, err := client.Put(url, options...)
result, err := client.Patch(url, options...)
result, err := client.Delete(url, options...)
result, err := client.Head(url, options...)
result, err := client.Options(url, options...)
result, err := client.Request(ctx, "GET", url, options...)

Close

Client 인터페이스 메서드로, 클라이언트가 보유한 리소스 (연결 풀, Transport) 를 해제합니다. 호출 후에는 더 이상 사용할 수 없습니다.

// Client 인터페이스 메서드
Close() error

client, _ := httpc.New()
defer client.Close()

기본 클라이언트 관리

SetDefaultClient

func SetDefaultClient(client Client) error

커스텀 클라이언트를 기본 클라이언트로 설정하여 패키지 함수에서 사용합니다. 이전 기본 클라이언트는 자동으로 닫힙니다.

제한

httpc.New()로 생성된 클라이언트만 허용되며, 이미 닫힌 클라이언트는 설정할 수 없습니다.

client, _ := httpc.New(httpc.PerformanceConfig())
httpc.SetDefaultClient(client)

// 이후 패키지 함수는 PerformanceConfig 사용
result, _ := httpc.Get(url)

CloseDefaultClient

func CloseDefaultClient() error

기본 클라이언트를 닫고 초기화합니다. 다음 패키지 함수 호출 시 새 클라이언트가 생성됩니다.

다운로드 함수

패키지 다운로드 함수는 기본 클라이언트를 사용하며, Client 인터페이스와 DomainClient 도 동일한 이름의 메서드를 제공하고 세 곳 모두 시그니처가 동일합니다.

Download

func Download(ctx context.Context, url string, cfg *DownloadConfig, options ...RequestOption) (*DownloadResult, error)

Download는 패키지 수준 함수, Client 인터페이스, DomainClient에 걸친 유일한 정규 다운로드 진입점입니다 — 이전의 {config} × {context} 변형 매트릭스를 단일 시그니처로 대체합니다.

cfg는 nil 일 수 없으며, cfg.FilePath를 반드시 설정해야 합니다 (그렇지 않으면 ErrEmptyFilePath 반환). 취소나 타임아웃 제어가 필요 없을 때는 context.Background()를 전달하고, 요청 옵션은 요청 헤더, 인증, 쿼리 매개변수 등을 설정하는 데 사용합니다.

cfg := httpc.DefaultDownloadConfig()
cfg.FilePath = "/tmp/file.zip"
cfg.Overwrite = true
cfg.ResumeDownload = true
cfg.ProgressCallback = func(downloaded, total int64, speed float64) {
    fmt.Printf("\r%.1f%%", float64(downloaded)/float64(total)*100)
}

// 패키지 함수 (기본 클라이언트 사용)
result, err := httpc.Download(context.Background(), url, cfg)

// Client 인터페이스 메서드
result, err = client.Download(ctx, url, cfg)

// DomainClient 메서드 (path 는 baseURL 에 상대적, 응답 Cookie 자동 캡처)
result, err = dc.Download(ctx, "/files/report.pdf", cfg)

마이그레이션 안내

기존의 DownloadFile, DownloadWithOptions, DownloadFileWithContext, DownloadWithOptionsWithContext 는 v1.5.2 에서 제거되었습니다. Download(ctx, url, cfg, options...)로 통일하여 사용하고, 경로, 덮어쓰기, 이어받기, 검증은 DownloadConfig로 설정하세요.

보조 함수

SetSecurityWarnOutput

func SetSecurityWarnOutput(w io.Writer)

보안 경고 출력을 리다이렉트합니다 (TestingConfig, InsecureSkipVerify 경고 등). io.Discard를 전달하면 모든 경고를 음소거할 수 있습니다.

// 모든 보안 경고 음소거
httpc.SetSecurityWarnOutput(io.Discard)

// 커스텀 로그로 리다이렉트
httpc.SetSecurityWarnOutput(log.Writer())

WARNING

이 함수는 주로 테스트용입니다. 프로덕션 환경에서는 경고를 억제하기보다 SecureConfig() 또는 DefaultConfig()를 사용하세요.

포맷 도구

FormatBytes

func FormatBytes(bytes int64) string

바이트 수를 사람이 읽을 수 있는 문자열로 포맷합니다 (예: "1.50 KB", "500 B"). 다운로드 결과 표시와 로그 출력에 자주 사용됩니다.

result, _ := httpc.Download(context.Background(), url, cfg)
fmt.Printf("다운로드 완료 %s\n", httpc.FormatBytes(result.BytesWritten))
// 다운로드 완료 12.34 MB

입력	출력
`500`	`500 B`
`1536`	`1.50 KB`
`1048576`	`1.00 MB`
`1073741824`	`1.00 GB`

FormatSpeed

func FormatSpeed(bytesPerSecond float64) string

바이트/초 속도를 사람이 읽을 수 있는 문자열로 포맷합니다 (예: "1.50 MB/s"). DownloadResult.AverageSpeed나 DownloadProgressCallback의 speed 매개변수와 함께 자주 사용됩니다.

result, _ := httpc.Download(context.Background(), url, cfg)
fmt.Printf("평균 속도 %s\n", httpc.FormatSpeed(result.AverageSpeed))
// 평균 속도 5.67 MB/s

// 진행률 콜백에서 사용
cfg.ProgressCallback = func(downloaded, total int64, speed float64) {
    fmt.Printf("\r%s / %s (%s)",
        httpc.FormatBytes(downloaded),
        httpc.FormatBytes(total),
        httpc.FormatSpeed(speed),
    )
}

입력 (바이트/초)	출력
`500`	`500 B/s`
`1536`	`1.50 KB/s`
`1048576`	`1.00 MB/s`

TIP

두 함수 모두 이진 단위 (1024 진수) 를 사용하며, 단위 순서는 B → KB → MB → GB → TB → PB → EB입니다.

도메인 클라이언트

NewDomain

func NewDomain(baseURL string, config ...*Config) (DomainClienter, error)

도메인 범위 클라이언트를 생성하여 Cookie 와 요청 헤더를 자동으로 관리합니다.

dc, err := httpc.NewDomain("https://api.example.com")
defer dc.Close()

dc.SetHeader("Authorization", "Bearer "+token)
result, err := dc.Get("/users")

패키지 함수와 클라이언트 메서드 ​

패키지 레벨 HTTP 메서드 ​

Get ​

Post ​

Put / Patch / Delete / Head / Options ​

Request ​

클라이언트 메서드 ​

New ​

클라이언트 HTTP 메서드 ​

Close ​

기본 클라이언트 관리 ​

SetDefaultClient ​

CloseDefaultClient ​

다운로드 함수 ​

Download ​

보조 함수 ​

SetSecurityWarnOutput ​

포맷 도구 ​

FormatBytes ​

FormatSpeed ​

도메인 클라이언트 ​

NewDomain ​

관련 항목 ​