httpclient

package
v1.0.0-rc.54 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package httpclient 提供基于 github.com/sunerpy/requests 的 HTTP 客户端连接池管理

Index

Constants

View Source
const (
	MethodGet     = requests.MethodGet
	MethodPost    = requests.MethodPost
	MethodPut     = requests.MethodPut
	MethodDelete  = requests.MethodDelete
	MethodPatch   = requests.MethodPatch
	MethodHead    = requests.MethodHead
	MethodOptions = requests.MethodOptions
)

HTTP 方法常量

View Source
const (
	SiteProxyAll     = "all"     // 全部站点
	SiteProxyInclude = "include" // 只有选中的站点
	SiteProxyExclude = "exclude" // 除了选中的站点
)

站点代理的模式。

Variables

View Source
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
)

导出常用请求选项

View Source
var (
	NewMiddlewareChain = requests.NewMiddlewareChain
	NewHooks           = requests.NewHooks
)

导出中间件和钩子构造函数

View Source
var (
	NoRetryPolicy          = requests.NoRetryPolicy
	LinearRetryPolicy      = requests.LinearRetryPolicy
	ExponentialRetryPolicy = requests.ExponentialRetryPolicy
	RetryOn5xx             = requests.RetryOn5xx
	RetryOnNetworkError    = requests.RetryOnNetworkError
	RetryOnStatusCodes     = requests.RetryOnStatusCodes
	CombineRetryConditions = requests.CombineRetryConditions
)

导出重试策略函数

View Source
var (
	IsTimeout         = requests.IsTimeout
	IsConnectionError = requests.IsConnectionError
	IsResponseError   = requests.IsResponseError
	IsTemporary       = requests.IsTemporary
)

导出错误检查函数

Functions

func AcquireSession

func AcquireSession() requests.Session

AcquireSession 从对象池获取 Session(高性能场景) 使用完毕后需调用 ReleaseSession

func Close

func Close() error

Close 关闭默认连接池

func IsHTTP2Enabled

func IsHTTP2Enabled() bool

IsHTTP2Enabled 检查全局是否启用 HTTP/2

func MaskProxyURL

func MaskProxyURL(raw string) string

MaskProxyURL 把代理地址里的密码换成 ***(给界面看);没有用户信息时原样返回。解析不了时整个换成 *** (存进去的都校验过,正常走不到;万一走到也不把原文交出去)。

func NewDelete

func NewDelete(url string) *requests.RequestBuilder

NewDelete 创建 DELETE 请求构建器

func NewGet

func NewGet(url string) *requests.RequestBuilder

NewGet 创建 GET 请求构建器

func NewPatch

func NewPatch(url string) *requests.RequestBuilder

NewPatch 创建 PATCH 请求构建器

func NewPost

func NewPost(url string) *requests.RequestBuilder

NewPost 创建 POST 请求构建器

func NewPut

func NewPut(url string) *requests.RequestBuilder

NewPut 创建 PUT 请求构建器

func NewRequestBuilder

func NewRequestBuilder(method requests.Method, url string) *requests.RequestBuilder

NewRequestBuilder 创建请求构建器

func NewSession

func NewSession() requests.Session

NewSession 是 requests.NewSession 的替身,新建时先把代理清掉。

requests 的 Session 共用一个 http.Transport 池:带代理的 Session 关掉后,它的 Transport 连同 Proxy 一起回到池里, 下一个 NewSession 可能拿到它,本该直连的请求(没配代理的站点、NO_PROXY 里的主机)就走了别人的代理。 需要代理的调用方在这之后照常 WithProxy。项目里不要直接用 requests.NewSession。

func NormalizeSiteID

func NormalizeSiteID(id string) string

NormalizeSiteID 是站点 ID 的规范写法:去掉首尾空白、转小写(站点设置里的名字就是注册表 ID 的小写)。

func ParseProxyURL

func ParseProxyURL(s string) (*url.URL, error)

ParseProxyURL 校验代理地址:http、https、socks5、socks5h,要有主机(和 TMDB、AI 助手的代理同样的规则)。

func ReleaseSession

func ReleaseSession(sess requests.Session)

ReleaseSession 释放 Session 回对象池

func ResolveProxyFromEnvironment added in v0.13.0

func ResolveProxyFromEnvironment(rawURL string) string

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

func ResolveSiteProxy(siteID string) (proxy string, decided bool)

ResolveSiteProxy 判断站点 siteID 的请求走不走代理。decided 为假表示这里不管(设置关闭,或者没有站点 ID), 调用方照旧按环境变量;decided 为真时 proxy 为空表示直连。

func ResolveSiteProxyOrEnv

func ResolveSiteProxyOrEnv(siteID, rawURL string) string

ResolveSiteProxyOrEnv 是 requests 发站点请求时用的代理地址:站点代理判定了就用它,否则按环境变量(认 ALL_PROXY)。 空串表示直连。调用方无论结果是不是空都要 WithProxy(清掉 Transport 池里残留的代理,见 NewSession)。

func SetEnvProxyForTest

func SetEnvProxyForTest(proxy string) (restore func())

SetEnvProxyForTest 让「按环境变量取代理」的两种回退都返回 proxy(空串表示直连),返回还原函数。只给测试用: Go 的 http.ProxyFromEnvironment 第一次调用以后就缓存环境变量,而且对回环地址一律直连,改环境变量证明不了回退。 替换期间所有走回退的请求都得到这个地址,用到它的测试不要并行。

func SetHTTP2Enabled

func SetHTTP2Enabled(enabled bool)

SetHTTP2Enabled 全局设置是否启用 HTTP/2

func SetSiteProxyPolicy

func SetSiteProxyPolicy(p *SiteProxyPolicy)

SetSiteProxyPolicy 换上新的快照,之后发出的站点请求按它判定;nil 表示关闭。

func SiteIDFrom

func SiteIDFrom(ctx context.Context) string

SiteIDFrom 取出 WithSiteID 放进去的站点 ID,没有时是空串。

func SiteTransport

func SiteTransport() *http.Transport

SiteTransport 是按站点代理判定的 http.Transport(默认 Transport 的副本,Proxy 换成 SiteTransportProxy): 请求的 context 里用 WithSiteID 放上站点 ID。所有调用方共用这一个,连接池也共用。

func SiteTransportProxy

func SiteTransportProxy(siteID string, req *http.Request) (*url.URL, error)

SiteTransportProxy 是 http.Transport 发站点请求时用的代理:站点代理判定了就用它(空串直连), 否则按 http.ProxyFromEnvironment(不认 ALL_PROXY)。

func WithSiteID

func WithSiteID(ctx context.Context, siteID string) context.Context

WithSiteID 把站点 ID 放进请求的 context:SiteTransport 的 Proxy 按它判定。

Types

type Handler

type Handler = requests.Handler

Handler 请求处理器类型

type Hooks

type Hooks = requests.Hooks

Hooks 请求钩子类型

type Method

type Method = requests.Method

Method HTTP 方法类型

type Middleware

type Middleware = requests.Middleware

Middleware 中间件类型

type MiddlewareChain

type MiddlewareChain = requests.MiddlewareChain

MiddlewareChain 中间件链类型

type Pool

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

Pool HTTP 客户端连接池,基于 requests 库

func GetDefaultPool

func GetDefaultPool() *Pool

GetDefaultPool 获取默认连接池(单例)

func NewPool

func NewPool(config PoolConfig) *Pool

NewPool 创建新的连接池

func NewPoolWithDefaults

func NewPoolWithDefaults() *Pool

NewPoolWithDefaults 使用默认配置创建连接池

func (*Pool) Close

func (p *Pool) Close() error

Close 关闭连接池

func (*Pool) GetConfig

func (p *Pool) GetConfig() PoolConfig

GetConfig 获取连接池配置

func (*Pool) GetSession

func (p *Pool) GetSession() requests.Session

GetSession 获取底层 Session

func (*Pool) GetStats

func (p *Pool) GetStats() map[string]any

GetStats 获取连接池统计信息

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 连接池配置

func DefaultPoolConfig

func DefaultPoolConfig() PoolConfig

DefaultPoolConfig 返回默认配置

type RequestBuilder

type RequestBuilder = requests.RequestBuilder

RequestBuilder 请求构建器类型

type RequestOption

type RequestOption = requests.RequestOption

RequestOption 请求选项类型

type Response

type Response interface {
	StatusCode() int
	Bytes() []byte
	Text() string
	IsSuccess() bool
	IsError() bool
}

Response 响应接口 - 封装 requests 库的响应

func Delete

func Delete(url string, opts ...RequestOption) (Response, error)

Delete 发送 DELETE 请求

func DeleteWithContext

func DeleteWithContext(ctx context.Context, url string, opts ...RequestOption) (Response, error)

DeleteWithContext 发送带上下文的 DELETE 请求

func Get

func Get(url string, opts ...RequestOption) (Response, error)

Get 发送 GET 请求

func GetWithContext

func GetWithContext(ctx context.Context, url string, opts ...RequestOption) (Response, error)

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 Put

func Put(url string, body any, opts ...RequestOption) (Response, error)

Put 发送 PUT 请求

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 响应

func PatchJSON

func PatchJSON[T any](url string, data any, opts ...RequestOption) (Result[T], error)

PatchJSON 发送 PATCH 请求并解析 JSON 响应

func PostJSON

func PostJSON[T any](url string, data any, opts ...RequestOption) (Result[T], error)

PostJSON 发送 POST 请求并解析 JSON 响应

func PutJSON

func PutJSON[T any](url string, data any, opts ...RequestOption) (Result[T], error)

PutJSON 发送 PUT 请求并解析 JSON 响应

func (Result[T]) Data

func (r Result[T]) Data() T

Data 获取解析后的数据

func (Result[T]) IsSuccess

func (r Result[T]) IsSuccess() bool

IsSuccess 检查是否成功

func (Result[T]) StatusCode

func (r Result[T]) StatusCode() int

StatusCode 获取状态码

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) Execute

func (r *RetryExecutor) Execute(ctx context.Context, fn func() (Response, error)) (Response, error)

Execute 执行带重试的请求

func (*RetryExecutor) GetAttemptCount

func (r *RetryExecutor) GetAttemptCount() int

GetAttemptCount 获取最大尝试次数(初始 + 重试)

func (*RetryExecutor) GetMaxRetries

func (r *RetryExecutor) GetMaxRetries() int

GetMaxRetries 获取最大重试次数

type SiteProxyPolicy

type SiteProxyPolicy struct {
	Enabled bool
	// Proxy 是校验过的代理地址,可能带用户名密码:只在内存里,不要写进日志
	Proxy string
	Mode  string
	// Sites 是选中的站点 ID(NormalizeSiteID 以后的)
	Sites map[string]bool
}

SiteProxyPolicy 是站点代理设置的只读快照(换设置时整个换掉,不要改它的字段)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL