CyberGocybergodev/httpc

简体中文

English

简体中文

English

主题

简体中文

English

API 参考 ​

HTTPC 提供 29 个请求选项函数、5 个配置预设、7 个内置中间件和完整的下载支持。

核心架构 ​

HTTPC 采用双层设计：Layer 1 的方法 API 是薄封装，真正处理请求的引擎是 Layer 2 的 Handler 管线。

text
HTTPC 双层架构
├── Layer 1  方法 API（薄封装）
│     包级函数 httpc.Get/Post/... + Client 方法 + 请求选项 → Result
│
└── Layer 2  Handler 管线（请求处理引擎）
      MiddlewareFunc(Handler) 洋葱链
      → 组装 clientImpl.middlewareChain
      → 执行（每个请求 = 组装并执行一条 Handler 链）

模块导航 ​

核心 ​

模块说明
包级函数与客户端方法Get/Post/Put/Patch/Delete 等包级函数、客户端方法和辅助函数
配置Config 结构体、5 种预设配置、验证函数和 Cookie 安全
接口Client、Doer、DomainClienter、RetryPolicy 等核心接口
ResultResult、RequestInfo、ResponseInfo、RequestMeta 类型和所有方法
处理器Handler 管线、MiddlewareFunc 洋葱链、Chain 组合器与 Mutator 契约
变更器RequestMutator/ResponseMutator 的读写方法与类型断言

请求与响应 ​

模块说明
请求选项29 个 WithXxx 请求选项函数（请求头、请求体、认证、Cookie、回调等）
内置中间件Chain 组合、7 个内置中间件工厂和审计事件类型
错误类型ClientError、12 种 ErrorType 枚举和 17 个错误变量

高级功能 ​

模块说明
域名客户端DomainClient 创建、HTTP 方法、下载方法和 URL 拼接规则
会话管理SessionManager 的 Cookie/请求头管理和安全验证
文件下载下载函数、DownloadConfig、断点续传和安全保护
常量与类型BodyKind 枚举、FormData/FileData 和审计上下文键

API 地图 ​

按符号类型分组的完整索引，与 github.com/cybergodev/httpc 包的导出面一一对应，点击跳转到对应详情页。

客户端与包级函数 ​

符号说明
New / NewDefault创建客户端（自定义 / 默认配置）
Get / Post / Put / Patch / Delete / Head / Options / Request包级 HTTP 方法（共享内部默认客户端）
Download统一文件下载入口（包级函数 / Client / DomainClient 三处同名同签名）
SetDefaultClient / CloseDefaultClient默认客户端替换与关闭
NewDomain / NewDomainDefault域名作用域客户端
SetSecurityWarnOutput安全警告输出重定向
FormatBytes / FormatSpeed字节数 / 速率格式化

请求选项（29 个） ​

分组选项
请求头（3）WithHeader、WithHeaderMap、WithUserAgent
认证（2）WithBasicAuth、WithBearerToken
请求体（7）WithJSON、WithXML、WithForm、WithFormData、WithFile、WithBinary、WithBody
查询参数（2）WithQuery、WithQueryMap
Cookie（4）WithCookies、WithCookieMap、WithCookieString、WithSecureCookie
请求控制（9）WithContext、WithTimeout、WithNoTimeout、WithMaxRetries、WithRetryNonIdempotent、WithFollowRedirects、WithMaxRedirects、WithAllowPrivateIPs、WithStreamBody
回调（2）WithOnRequest、WithOnResponse

全部选项的签名、校验规则与覆盖的 Config 默认值见请求选项。

Result 家族 ​

分类符号
类型Result（17 个 nil 安全方法）
状态与协议StatusCode、Proto、IsSuccess、IsRedirect、IsClientError、IsServerError
请求体访问Body、RawBody
解析与保存Unmarshal、SaveToFile、String
CookieResponseCookies、GetCookie、HasCookie、RequestCookies、GetRequestCookie、HasRequestCookie
子类型RequestInfo、ResponseInfo、RequestMeta（含 ProxyURL 代理字段）

详见 Result。

配置 ​

分类符号
主类型Config（Timeouts / Connection / Security / Retry / Middleware / Defaults 六组）
子配置类型TimeoutConfig、ConnectionConfig、SecurityConfig、RetryConfig、MiddlewareConfig、RequestDefaults
预设（5 个）DefaultConfig、SecureConfig、PerformanceConfig、TestingConfig、MinimalConfig
校验与输出ValidateConfig、Config.String
Cookie 安全CookieSecurityConfig、DefaultCookieSecurityConfig、StrictCookieSecurityConfig
下载配置DownloadConfig、DefaultDownloadConfig、DownloadResult、DownloadProgressCallback、ChecksumAlgorithm
会话配置SessionConfig、DefaultSessionConfig、NewSessionManager、NewSessionManagerDefault

详见 配置、文件下载、会话管理。

Handler、中间件与变更器 ​

分类符号
管线类型Handler、MiddlewareFunc、Chain
中间件工厂（7 个）LoggingMiddleware、RecoveryMiddleware、RequestIDMiddleware、TimeoutMiddleware、HeaderMiddleware、MetricsMiddleware、AuditMiddleware
中间件配置LoggingConfig、RequestIDConfig、TimeoutMiddlewareConfig、HeaderConfig、MetricsConfig、AuditConfig（各配 Default*Config() 构造函数）
变更器RequestMutator、ResponseMutator（中间件读写请求/响应的契约）

详见 处理器、内置中间件、变更器。

接口与类型 ​

分类符号
核心接口Client、Doer、DomainClienter、RetryPolicy
类型别名RequestOption、ClientError、ErrorType、CertificatePinner、ProxyStrategy
证书固定NewSPKIHashPinner、NewPublicKeyPinner、NewCertificatePinnerChain
会话与域名SessionManager、DomainClient（建议以 DomainClienter 接口使用）
数据类型FormData、FileData、AuditEvent

详见 接口、域名客户端、会话管理、常量与类型。

错误与常量 ​

分类符号
错误类型ClientError、ErrorType（12 种错误类别枚举）
哨兵错误（17 个）ErrClientClosed、ErrNilConfig、ErrInvalidHeader、ErrInvalidTimeout、ErrInvalidRetry、ErrInvalidMaxRedirects、ErrInvalidCredentials、ErrInvalidConnection、ErrInvalidSecurity、ErrInvalidMiddleware、ErrEmptyFilePath、ErrFileExists、ErrResponseBodyEmpty、ErrResponseBodyTooLarge、ErrStreamBodyRequiresDownload、ErrDownloadInProgress、ErrProxyConnectionFailed
BodyKind（6 常量）BodyAuto、BodyJSON、BodyXML、BodyForm、BodyBinary、BodyMultipart
其他常量ProxyStrategyRoundRobin / ProxyStrategyRandom、ChecksumSHA256、审计上下文键

详见 错误类型、常量与类型。

快速参考 ​

创建客户端 ​

go
client, err := httpc.NewDefault()             // 默认配置
client, err := httpc.New(httpc.SecureConfig()) // 安全预设
client, err := httpc.New(customConfig)         // 自定义配置

发送请求 ​

go
// 包级函数
result, err := httpc.Get(url, options...)

// 客户端方法
result, err := client.Get(url, options...)

// 带上下文
result, err := client.Request(ctx, "GET", url, options...)

处理响应 ​

go
result.StatusCode()           // 状态码
result.Body()                 // 响应体（字符串）
result.RawBody()              // 响应体（字节）
result.Unmarshal(&data)       // JSON 解析
result.IsSuccess()            // 是否 2xx
result.Meta.Duration          // 请求耗时
result.Meta.Attempts          // 重试次数

版本兼容性 ​

  • Go 版本：要求 Go 1.26 及以上（go.mod 声明 go 1.26.0）。
  • 导入路径：github.com/cybergodev/httpc（包名 httpc，无需别名）。
  • 直接依赖：仅 golang.org/x/sys（用于各平台系统代理检测，覆盖 Linux/macOS/Windows），无其他第三方依赖。
  • API 状态：当前全部导出符号均无 Deprecated 标记，处于活跃维护状态。