http_client

Documentation

Overview

Package http_client 提供高性能的 HTTP 客户端工具 支持连接池复用、链路追踪、请求重试、熔断保护等功能

Package http_client HTTP客户端工具包 提供常用的HTTP请求方法，支持GET、POST、PUT等请求类型 支持表单提交、文件上传、JSON请求等功能 已优化：连接池复用、链路追踪、请求重试

Index

• type Client
  • func GetDefaultClient() *Client
  • func NewClient(config *ClientConfig) *Client
  • func (c *Client) CloseIdleConnections()
  • func (c *Client) Do(ctx context.Context, req *http.Request) (*http.Response, error)
  • func (c *Client) GetBreakerStats() map[string]circuitbreaker.BreakerStats
  • func (c *Client) GetHTTPClient() *http.Client
  • func (c *Client) IsCircuitOpen(host string) bool
  • func (c *Client) ResetAllBreakers()
  • func (c *Client) ResetBreaker(host string)
• type ClientConfig
  • func DefaultClientConfig() *ClientConfig
• type ResponseWrapper
  • func DeleteWithContext(ctx context.Context, url string, timeout int, headers map[string]string) ResponseWrapper
  • func GetWithContext(ctx context.Context, url string, timeout int, headers map[string]string) ResponseWrapper
  • func PostFormWithContext(ctx context.Context, httpUrl string, dataMap map[string]string, ...) ResponseWrapper
  • func PostJSONWithContext(ctx context.Context, url string, body string, timeout int, ...) ResponseWrapper
  • func PostParamsWithContext(ctx context.Context, url string, params string, timeout int, ...) ResponseWrapper
  • func PutJSONWithContext(ctx context.Context, url string, body string, timeout int, ...) ResponseWrapper
  • func (r *ResponseWrapper) HasError() bool
  • func (r *ResponseWrapper) IsSuccess() bool
• type ServerError
  • func (e *ServerError) Error() string

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client 高性能 HTTP 客户端 支持连接池复用、链路追踪、请求重试、熔断保护

func GetDefaultClient

func GetDefaultClient() *Client

GetDefaultClient 获取默认的全局 HTTP 客户端 使用单例模式，线程安全

func NewClient

func NewClient(config *ClientConfig) *Client

NewClient 创建新的 HTTP 客户端 参数：

• config: 客户端配置，为 nil 时使用默认配置

返回：

• *Client: HTTP 客户端实例

func (*Client) CloseIdleConnections

func (c *Client) CloseIdleConnections()

CloseIdleConnections 关闭所有空闲连接 用于优雅关闭时释放资源

func (*Client) Do

func (c *Client) Do(ctx context.Context, req *http.Request) (*http.Response, error)

Do 执行 HTTP 请求（带重试和熔断保护） 参数：

• ctx: 上下文，用于超时控制和取消
• req: HTTP 请求对象

返回：

• *http.Response: HTTP 响应
• error: 错误信息（如果熔断器打开，返回 circuitbreaker.ErrCircuitOpen）

func (*Client) GetBreakerStats

func (c *Client) GetBreakerStats() map[string]circuitbreaker.BreakerStats

GetBreakerStats 获取所有熔断器的统计信息 返回：

• map[string]circuitbreaker.BreakerStats: 熔断器名称到状态的映射
• 如果未启用熔断器，返回 nil

func (*Client) GetHTTPClient

func (c *Client) GetHTTPClient() *http.Client

GetHTTPClient 获取底层的 http.Client 用于需要直接操作 http.Client 的场景

func (*Client) IsCircuitOpen

func (c *Client) IsCircuitOpen(host string) bool

IsCircuitOpen 检查指定主机的熔断器是否打开 参数：

• host: 主机名

返回：

• bool: 熔断器是否打开

func (*Client) ResetAllBreakers

func (c *Client) ResetAllBreakers()

ResetAllBreakers 重置所有熔断器

func (*Client) ResetBreaker

func (c *Client) ResetBreaker(host string)

ResetBreaker 重置指定主机的熔断器 参数：

• host: 主机名（如 api.example.com:8080）

type ClientConfig

type ClientConfig struct {
	// 连接池配置
	MaxIdleConns        int           // 最大空闲连接数，默认 100
	MaxIdleConnsPerHost int           // 每个主机最大空闲连接数，默认 10
	MaxConnsPerHost     int           // 每个主机最大连接数，默认 100
	IdleConnTimeout     time.Duration // 空闲连接超时时间，默认 90s

	// 超时配置
	DialTimeout         time.Duration // 连接建立超时，默认 30s
	TLSHandshakeTimeout time.Duration // TLS 握手超时，默认 10s
	ResponseTimeout     time.Duration // 响应头超时，默认 30s

	// 重试配置
	MaxRetries    int           // 最大重试次数，默认 3
	RetryInterval time.Duration // 重试间隔，默认 100ms

	// 功能开关
	EnableTracing        bool // 是否启用链路追踪，默认 true
	EnableCircuitBreaker bool // 是否启用熔断器，默认 false

	// 熔断器配置（EnableCircuitBreaker=true 时生效）
	CircuitBreakerFailureThreshold uint32        // 连续失败阈值，默认 5
	CircuitBreakerTimeout          time.Duration // 熔断超时时间，默认 30s
	CircuitBreakerMaxRequests      uint32        // 半开状态最大请求数，默认 3
}

ClientConfig HTTP 客户端配置

func DefaultClientConfig

func DefaultClientConfig() *ClientConfig

DefaultClientConfig 返回默认的客户端配置

type ResponseWrapper

type ResponseWrapper struct {
	StatusCode int         // HTTP状态码
	Body       string      // 响应体内容
	Header     http.Header // 响应头信息
	Error      error       // 错误信息（新增）
}

ResponseWrapper HTTP响应包装器 用于统一封装HTTP请求的响应结果

func DeleteWithContext

func DeleteWithContext(ctx context.Context, url string, timeout int, headers map[string]string) ResponseWrapper

DeleteWithContext 发送DELETE请求（推荐使用） 参数:

• ctx: 上下文，用于超时控制和链路追踪
• url: 请求的URL地址
• timeout: 请求超时时间（秒）
• headers: 自定义请求头

返回值: ResponseWrapper 包含响应状态码、响应体和响应头

func GetWithContext

func GetWithContext(ctx context.Context, url string, timeout int, headers map[string]string) ResponseWrapper

GetWithContext 发送GET请求（推荐使用） 参数:

• ctx: 上下文，用于超时控制和链路追踪
• url: 请求的URL地址
• timeout: 请求超时时间（秒），0 表示使用默认超时
• headers: 自定义请求头

返回值: ResponseWrapper 包含响应状态码、响应体和响应头

func PostFormWithContext

func PostFormWithContext(ctx context.Context, httpUrl string, dataMap map[string]string,
	filePathMap map[string]string, fileMap map[string]io.Reader,
	headers map[string]string, timeout int) ResponseWrapper

PostFormWithContext 发送POST请求（表单形式，支持文件上传，推荐使用） 参数:

• ctx: 上下文，用于超时控制和链路追踪
• httpUrl: 请求的URL地址
• dataMap: 普通表单字段（键值对）
• filePathMap: 文件路径映射（字段名 -> 文件路径）
• fileMap: 文件读取器映射（字段名 -> io.Reader）
• headers: 自定义请求头
• timeout: 请求超时时间（秒）

返回值: ResponseWrapper 包含响应状态码、响应体和响应头

func PostJSONWithContext

func PostJSONWithContext(ctx context.Context, url string, body string, timeout int, headers map[string]string) ResponseWrapper

PostJSONWithContext 发送POST请求（JSON格式，推荐使用） 参数:

• ctx: 上下文，用于超时控制和链路追踪
• url: 请求的URL地址
• body: JSON格式的请求体
• timeout: 请求超时时间（秒）
• headers: 自定义请求头

返回值: ResponseWrapper 包含响应状态码、响应体和响应头

func PostParamsWithContext

func PostParamsWithContext(ctx context.Context, url string, params string, timeout int, headers map[string]string) ResponseWrapper

PostParamsWithContext 发送POST请求（参数形式，推荐使用） 参数:

• ctx: 上下文，用于超时控制和链路追踪
• url: 请求的URL地址
• params: POST参数（字符串形式）
• timeout: 请求超时时间（秒）
• headers: 自定义请求头

返回值: ResponseWrapper 包含响应状态码、响应体和响应头

func PutJSONWithContext

func PutJSONWithContext(ctx context.Context, url string, body string, timeout int, headers map[string]string) ResponseWrapper

PutJSONWithContext 发送PUT请求（JSON格式，推荐使用） 参数:

• ctx: 上下文，用于超时控制和链路追踪
• url: 请求的URL地址
• body: JSON格式的请求体
• timeout: 请求超时时间（秒）
• headers: 自定义请求头

返回值: ResponseWrapper 包含响应状态码、响应体和响应头

func (*ResponseWrapper) HasError

func (r *ResponseWrapper) HasError() bool

HasError 判断是否有错误

func (*ResponseWrapper) IsSuccess

func (r *ResponseWrapper) IsSuccess() bool

IsSuccess 判断请求是否成功

type ServerError

type ServerError struct {
	StatusCode int
}

ServerError 服务端错误（5xx）

func (*ServerError) Error

func (e *ServerError) Error() string