Documentation
¶
Overview ¶
Package httpclient 提供基于 github.com/sunerpy/requests 的 HTTP 客户端连接池管理
Index ¶
- Constants
- Variables
- func AcquireSession() requests.Session
- func Close() error
- func IsHTTP2Enabled() bool
- func MaskProxyURL(raw string) string
- func NewDelete(url string) *requests.RequestBuilder
- func NewGet(url string) *requests.RequestBuilder
- func NewPatch(url string) *requests.RequestBuilder
- func NewPost(url string) *requests.RequestBuilder
- func NewPut(url string) *requests.RequestBuilder
- func NewRequestBuilder(method requests.Method, url string) *requests.RequestBuilder
- func NewSession() requests.Session
- func NormalizeSiteID(id string) string
- func ParseProxyURL(s string) (*url.URL, error)
- func ReleaseSession(sess requests.Session)
- func ResolveProxyFromEnvironment(rawURL string) string
- func ResolveSiteProxy(siteID string) (proxy string, decided bool)
- func ResolveSiteProxyOrEnv(siteID, rawURL string) string
- func SetEnvProxyForTest(proxy string) (restore func())
- func SetHTTP2Enabled(enabled bool)
- func SetSiteProxyPolicy(p *SiteProxyPolicy)
- func SiteIDFrom(ctx context.Context) string
- func SiteTransport() *http.Transport
- func SiteTransportProxy(siteID string, req *http.Request) (*url.URL, error)
- func WithSiteID(ctx context.Context, siteID string) context.Context
- type Handler
- type Hooks
- type Method
- type Middleware
- type MiddlewareChain
- type Pool
- type PoolConfig
- type RequestBuilder
- type RequestOption
- type Response
- func Delete(url string, opts ...RequestOption) (Response, error)
- func DeleteWithContext(ctx context.Context, url string, opts ...RequestOption) (Response, error)
- func Get(url string, opts ...RequestOption) (Response, error)
- func GetWithContext(ctx context.Context, url string, opts ...RequestOption) (Response, error)
- func Patch(url string, body any, opts ...RequestOption) (Response, error)
- func PatchWithContext(ctx context.Context, url string, body any, opts ...RequestOption) (Response, error)
- func Post(url string, body any, opts ...RequestOption) (Response, error)
- func PostWithContext(ctx context.Context, url string, body any, opts ...RequestOption) (Response, error)
- func Put(url string, body any, opts ...RequestOption) (Response, error)
- func PutWithContext(ctx context.Context, url string, body any, opts ...RequestOption) (Response, error)
- type Result
- func DeleteJSON[T any](url string, opts ...RequestOption) (Result[T], error)
- func GetJSON[T any](url string, opts ...RequestOption) (Result[T], error)
- func PatchJSON[T any](url string, data any, opts ...RequestOption) (Result[T], error)
- func PostJSON[T any](url string, data any, opts ...RequestOption) (Result[T], error)
- func PutJSON[T any](url string, data any, opts ...RequestOption) (Result[T], error)
- type RetryExecutor
- type SiteProxyPolicy
Constants ¶
const ( MethodGet = requests.MethodGet MethodPost = requests.MethodPost MethodPut = requests.MethodPut MethodDelete = requests.MethodDelete MethodPatch = requests.MethodPatch MethodHead = requests.MethodHead MethodOptions = requests.MethodOptions )
HTTP 方法常量
const ( SiteProxyAll = "all" // 全部站点 SiteProxyInclude = "include" // 只有选中的站点 SiteProxyExclude = "exclude" // 除了选中的站点 )
站点代理的模式。
Variables ¶
var ( WithTimeout = requests.WithTimeout WithHeader = requests.WithHeader WithHeaders = requests.WithHeaders WithQuery = requests.WithQuery WithQueryParams = requests.WithQueryParams WithBasicAuth = requests.WithBasicAuth WithBearerToken = requests.WithBearerToken WithContext = requests.WithContext WithContentType = requests.WithContentType WithAccept = requests.WithAccept )
导出常用请求选项
var ( NewMiddlewareChain = requests.NewMiddlewareChain NewHooks = requests.NewHooks )
导出中间件和钩子构造函数
var ( NoRetryPolicy = requests.NoRetryPolicy LinearRetryPolicy = requests.LinearRetryPolicy ExponentialRetryPolicy = requests.ExponentialRetryPolicy RetryOn5xx = requests.RetryOn5xx RetryOnNetworkError = requests.RetryOnNetworkError RetryOnStatusCodes = requests.RetryOnStatusCodes CombineRetryConditions = requests.CombineRetryConditions )
导出重试策略函数
var ( IsTimeout = requests.IsTimeout IsConnectionError = requests.IsConnectionError IsResponseError = requests.IsResponseError IsTemporary = requests.IsTemporary )
导出错误检查函数
Functions ¶
func AcquireSession ¶
AcquireSession 从对象池获取 Session(高性能场景) 使用完毕后需调用 ReleaseSession
func MaskProxyURL ¶
MaskProxyURL 把代理地址里的密码换成 ***(给界面看);没有用户信息时原样返回。解析不了时整个换成 *** (存进去的都校验过,正常走不到;万一走到也不把原文交出去)。
func NewRequestBuilder ¶
func NewRequestBuilder(method requests.Method, url string) *requests.RequestBuilder
NewRequestBuilder 创建请求构建器
func NewSession ¶
NewSession 是 requests.NewSession 的替身,新建时先把代理清掉。
requests 的 Session 共用一个 http.Transport 池:带代理的 Session 关掉后,它的 Transport 连同 Proxy 一起回到池里, 下一个 NewSession 可能拿到它,本该直连的请求(没配代理的站点、NO_PROXY 里的主机)就走了别人的代理。 需要代理的调用方在这之后照常 WithProxy。项目里不要直接用 requests.NewSession。
func NormalizeSiteID ¶
NormalizeSiteID 是站点 ID 的规范写法:去掉首尾空白、转小写(站点设置里的名字就是注册表 ID 的小写)。
func ParseProxyURL ¶
ParseProxyURL 校验代理地址:http、https、socks5、socks5h,要有主机(和 TMDB、AI 助手的代理同样的规则)。
func ResolveProxyFromEnvironment ¶ added in v0.13.0
ResolveProxyFromEnvironment resolves proxy URL for target URL, honoring HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY and lowercase variants.
Go's http.ProxyFromEnvironment does NOT support ALL_PROXY/all_proxy, so we check it manually as a fallback when no protocol-specific proxy is found.
func ResolveSiteProxy ¶
ResolveSiteProxy 判断站点 siteID 的请求走不走代理。decided 为假表示这里不管(设置关闭,或者没有站点 ID), 调用方照旧按环境变量;decided 为真时 proxy 为空表示直连。
func ResolveSiteProxyOrEnv ¶
ResolveSiteProxyOrEnv 是 requests 发站点请求时用的代理地址:站点代理判定了就用它,否则按环境变量(认 ALL_PROXY)。 空串表示直连。调用方无论结果是不是空都要 WithProxy(清掉 Transport 池里残留的代理,见 NewSession)。
func SetEnvProxyForTest ¶
func SetEnvProxyForTest(proxy string) (restore func())
SetEnvProxyForTest 让「按环境变量取代理」的两种回退都返回 proxy(空串表示直连),返回还原函数。只给测试用: Go 的 http.ProxyFromEnvironment 第一次调用以后就缓存环境变量,而且对回环地址一律直连,改环境变量证明不了回退。 替换期间所有走回退的请求都得到这个地址,用到它的测试不要并行。
func SetSiteProxyPolicy ¶
func SetSiteProxyPolicy(p *SiteProxyPolicy)
SetSiteProxyPolicy 换上新的快照,之后发出的站点请求按它判定;nil 表示关闭。
func SiteIDFrom ¶
SiteIDFrom 取出 WithSiteID 放进去的站点 ID,没有时是空串。
func SiteTransport ¶
SiteTransport 是按站点代理判定的 http.Transport(默认 Transport 的副本,Proxy 换成 SiteTransportProxy): 请求的 context 里用 WithSiteID 放上站点 ID。所有调用方共用这一个,连接池也共用。
func SiteTransportProxy ¶
SiteTransportProxy 是 http.Transport 发站点请求时用的代理:站点代理判定了就用它(空串直连), 否则按 http.ProxyFromEnvironment(不认 ALL_PROXY)。
Types ¶
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool HTTP 客户端连接池,基于 requests 库
type PoolConfig ¶
type PoolConfig struct {
// MaxIdleConns 最大空闲连接数
MaxIdleConns int
// MaxIdleConnsPerHost 每个主机的最大空闲连接数
MaxIdleConnsPerHost int
// IdleTimeout 空闲连接超时时间
IdleTimeout time.Duration
// Timeout 请求超时时间
Timeout time.Duration
// ConnectTimeout 连接超时时间
ConnectTimeout time.Duration
// EnableKeepAlive 是否启用 Keep-Alive
EnableKeepAlive bool
// EnableHTTP2 是否启用 HTTP/2
EnableHTTP2 bool
// MaxRetries 最大重试次数
MaxRetries int
// RetryDelay 初始重试延迟
RetryDelay time.Duration
// MaxRetryDelay 最大重试延迟
MaxRetryDelay time.Duration
}
PoolConfig 连接池配置
type Response ¶
type Response interface {
StatusCode() int
Bytes() []byte
Text() string
IsSuccess() bool
IsError() bool
}
Response 响应接口 - 封装 requests 库的响应
func DeleteWithContext ¶
DeleteWithContext 发送带上下文的 DELETE 请求
func GetWithContext ¶
GetWithContext 发送带上下文的 GET 请求
func Patch ¶
func Patch(url string, body any, opts ...RequestOption) (Response, error)
Patch 发送 PATCH 请求
func PatchWithContext ¶
func PatchWithContext(ctx context.Context, url string, body any, opts ...RequestOption) (Response, error)
PatchWithContext 发送带上下文的 PATCH 请求
func Post ¶
func Post(url string, body any, opts ...RequestOption) (Response, error)
Post 发送 POST 请求
func PostWithContext ¶
func PostWithContext(ctx context.Context, url string, body any, opts ...RequestOption) (Response, error)
PostWithContext 发送带上下文的 POST 请求
func PutWithContext ¶
func PutWithContext(ctx context.Context, url string, body any, opts ...RequestOption) (Response, error)
PutWithContext 发送带上下文的 PUT 请求
type Result ¶
type Result[T any] struct { // contains filtered or unexported fields }
Result 泛型结果类型
func DeleteJSON ¶
func DeleteJSON[T any](url string, opts ...RequestOption) (Result[T], error)
DeleteJSON 发送 DELETE 请求并解析 JSON 响应
func GetJSON ¶
func GetJSON[T any](url string, opts ...RequestOption) (Result[T], error)
GetJSON 发送 GET 请求并解析 JSON 响应
type RetryExecutor ¶
type RetryExecutor struct {
// contains filtered or unexported fields
}
RetryExecutor 重试执行器
func NewRetryExecutor ¶
func NewRetryExecutor(maxRetries int, retryDelay, maxRetryDelay time.Duration) *RetryExecutor
NewRetryExecutor 创建重试执行器
func NewRetryExecutorFromConfig ¶
func NewRetryExecutorFromConfig(config PoolConfig) *RetryExecutor
NewRetryExecutorFromConfig 从配置创建重试执行器
func (*RetryExecutor) GetAttemptCount ¶
func (r *RetryExecutor) GetAttemptCount() int
GetAttemptCount 获取最大尝试次数(初始 + 重试)
func (*RetryExecutor) GetMaxRetries ¶
func (r *RetryExecutor) GetMaxRetries() int
GetMaxRetries 获取最大重试次数