httpclient

Documentation

Overview

Package httpclient là factory tạo *http.Client production-ready: timeout, connection pool đã tinh chỉnh, retry (exponential backoff cho method idempotent) và sẵn sàng gắn instrumentation OTel (WithBaseTransport ở M3).

cli := httpclient.New(
    httpclient.WithTimeout(10*time.Second),
    httpclient.WithRetry(3, 100*time.Millisecond, 2*time.Second),
)
resp, err := cli.Get("https://api.example.com/health")

Index

• func DefaultRetryPolicy(req *http.Request, resp *http.Response, err error) bool
• func Module(opts ...Option) fx.Option
• func New(opts ...Option) *http.Client
• type CircuitBreakerConfig
  • func DefaultCircuitBreakerConfig() CircuitBreakerConfig
• type Option
  • func WithBaseTransport(rt http.RoundTripper) Option
  • func WithCircuitBreaker(cfg CircuitBreakerConfig) Option
  • func WithDialTimeout(d time.Duration) Option
  • func WithIdleConnTimeout(d time.Duration) Option
  • func WithMaxConnsPerHost(n int) Option
  • func WithMaxIdleConns(n int) Option
  • func WithMaxIdleConnsPerHost(n int) Option
  • func WithNoRetry() Option
  • func WithPerAttemptTimeout(d time.Duration) Option
  • func WithRetry(maxRetries int, baseBackoff, maxBackoff time.Duration) Option
  • func WithRetryPolicy(p RetryPolicy) Option
  • func WithTimeout(d time.Duration) Option
  • func WithoutOTel() Option
• type RetryPolicy

Functions

func DefaultRetryPolicy

func DefaultRetryPolicy(req *http.Request, resp *http.Response, err error) bool

DefaultRetryPolicy retry khi: lỗi transport (resp nil), hoặc status 429 / 502 / 503 / 504, VÀ method là idempotent. POST/PATCH không retry mặc định để tránh nhân đôi side effect (service tự dùng WithRetryPolicy nếu cần).

func Module

func Module(opts ...Option) fx.Option

Module cung cấp một *http.Client mặc định cho graph fx. Service cần nhiều client với cấu hình khác nhau nên tự fx.Provide (dùng New trực tiếp) hoặc dùng named provider thay vì dựa vào client chung này.

opts áp dụng lên client mặc định.

func New

func New(opts ...Option) *http.Client

New tạo *http.Client theo option. Pipeline transport: retryTransport bọc base transport (mặc định *http.Transport đã tune; hoặc transport do WithBaseTransport cấp).

Types

type CircuitBreakerConfig

type CircuitBreakerConfig struct {
	Name string
	// MaxRequests: số request cho qua khi ở trạng thái half-open.
	MaxRequests uint32
	// Interval: chu kỳ reset bộ đếm khi đang closed (0 = không reset định kỳ).
	Interval time.Duration
	// Timeout: thời gian ở open trước khi chuyển half-open.
	Timeout time.Duration
	// ConsecutiveFailures: số lỗi liên tiếp để trip (mở mạch).
	ConsecutiveFailures uint32
}

CircuitBreakerConfig cấu hình circuit breaker cho client.

func DefaultCircuitBreakerConfig

func DefaultCircuitBreakerConfig() CircuitBreakerConfig

DefaultCircuitBreakerConfig trả cấu hình mặc định hợp lý.

type Option

type Option func(*options)

Option tinh chỉnh client.

func WithBaseTransport

func WithBaseTransport(rt http.RoundTripper) Option

WithBaseTransport đặt transport gốc (mặc định tạo từ tuning ở trên). Khi set, tuning và otelhttp bị bỏ qua — caller tự chịu trách nhiệm instrument.

func WithCircuitBreaker

func WithCircuitBreaker(cfg CircuitBreakerConfig) Option

WithCircuitBreaker bật circuit breaker (mở mạch sau N lỗi transport liên tiếp).

func WithDialTimeout

func WithDialTimeout(d time.Duration) Option

WithDialTimeout đặt timeout cho việc mở kết nối TCP.

func WithIdleConnTimeout

func WithIdleConnTimeout(d time.Duration) Option

WithIdleConnTimeout đặt thời gian giữ idle connection.

func WithMaxConnsPerHost

func WithMaxConnsPerHost(n int) Option

WithMaxConnsPerHost giới hạn tổng connection mỗi host (0 = không giới hạn).

func WithMaxIdleConns

func WithMaxIdleConns(n int) Option

WithMaxIdleConns đặt tổng số idle connection của pool.

func WithMaxIdleConnsPerHost

func WithMaxIdleConnsPerHost(n int) Option

WithMaxIdleConnsPerHost đặt số idle connection mỗi host.

func WithNoRetry

func WithNoRetry() Option

WithNoRetry tắt retry hoàn toàn.

func WithPerAttemptTimeout

func WithPerAttemptTimeout(d time.Duration) Option

WithPerAttemptTimeout đặt timeout cho MỖI lần thử (gồm cả đọc body của lần trả về cuối). 0 = chỉ dùng timeout tổng của Client. Hữu ích để một attempt chậm không nuốt hết ngân sách thời gian của các retry.

func WithRetry

func WithRetry(maxRetries int, baseBackoff, maxBackoff time.Duration) Option

WithRetry cấu hình retry: số lần thử lại tối đa và khoảng backoff.

func WithRetryPolicy

func WithRetryPolicy(p RetryPolicy) Option

WithRetryPolicy thay policy quyết định retry (mặc định DefaultRetryPolicy).

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout đặt timeout tổng cho mỗi request (gồm cả retry). 0 = không timeout.

func WithoutOTel

func WithoutOTel() Option

WithoutOTel tắt bọc otelhttp (mặc định bật: tự inject trace context và tạo client span).

type RetryPolicy

type RetryPolicy func(req *http.Request, resp *http.Response, err error) bool

RetryPolicy quyết định có retry một request hay không, dựa trên request, response (có thể nil nếu lỗi transport) và lỗi. Trả true để retry.