README
¶
http
简介
http 包提供了功能丰富的 Go HTTP 客户端，支持 GET/POST/HEAD/表单/JSON 请求、超时、代理、钩子、慢请求日志、trace、全局方法等，适合微服务、API 调用、健康检查等多种场景。
主要特性
- 统一 HTTP 客户端接口，支持 Do/Get/Post/Head/PostForm/PostJSON
- 支持 Option 配置（超时、代理、连接池、日志、trace、慢请求等）
- 支持自定义钩子（Hook）、慢请求日志、错误日志、trace
- 支持全局默认客户端与实例化客户端
- 支持 HTTPS 证书有效期检测
- 并发安全，适合高并发环境
- 完整单元测试覆盖
设计理念
http 包遵循"高效、灵活、可观测"的设计理念，接口与实现分离，Option 配置灵活，钩子机制可扩展，适合微服务和高并发场景。默认实现兼容标准库 http.Client，便于迁移和集成。
安装
前置条件
- Go 版本要求：Go 1.18+
- 依赖要求：
- github.com/stretchr/testify（仅测试）
安装命令
go get -u github.com/fsyyft-go/kit/net/http
快速开始
基础用法
package main
import (
"context"
"fmt"
kithttp "github.com/fsyyft-go/kit/net/http"
)
func main() {
client := kithttp.NewClient(
kithttp.WithTimeout(5 * time.Second),
)
resp, err := client.Get(context.Background(), "https://httpbin.org/get")
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("状态码:", resp.StatusCode)
}
全局方法
resp, err := kithttp.Get(context.Background(), "https://httpbin.org/get")
POST/表单/JSON
// POST 普通请求
client.Post(ctx, url, body)
// POST 表单
client.PostForm(ctx, url, url.Values{"a": {"1"}})
// POST JSON
client.PostJSON(ctx, url, map[string]any{"x": 1})
钩子与慢请求日志
client := kithttp.NewClient(
kithttp.WithLogSlow(100*time.Millisecond),
kithttp.WithTraceEnable(true),
)
证书有效期检测
days, err := kithttp.GetCertificatesExpirestime(ctx, "https://example.com", "", "", 3*time.Second)
fmt.Println("证书剩余天数:", days)
详细指南
核心概念
- Client 接口：统一封装 http.Client，支持常用请求方法
- Option 配置：灵活设置超时、代理、连接池、日志、trace 等
- 钩子机制：支持请求前后自定义扩展（如 trace、慢日志、错误日志）
- 全局方法：便捷调用全局默认客户端
- 证书检测：支持 HTTPS 证书剩余天数检测
常见用例
- 微服务间 HTTP 通信
- API 调用与数据采集
- 健康检查与监控
- 自动化测试
- 证书有效期监控
最佳实践
- 合理设置超时与连接池参数，避免资源泄漏
- 慢请求日志与 trace 有助于排查性能瓶颈
- 钩子机制可扩展自定义监控与埋点
- 始终检查 error 并关闭 resp.Body
API 文档
主要类型
// Client HTTP 客户端接口
type Client interface {
Do(ctx context.Context, req *http.Request) (*http.Response, error)
Head(ctx context.Context, url string) (*http.Response, error)
Get(ctx context.Context, url string) (*http.Response, error)
Post(ctx context.Context, url string, body io.Reader) (*http.Response, error)
PostForm(ctx context.Context, url string, data url.Values) (*http.Response, error)
PostJSON(ctx context.Context, url string, data any) (*http.Response, error)
}
// Option 配置项类型
type Option func(*client)
// NewClient 创建客户端
func NewClient(opts ...Option) Client
// 全局方法
func Get(ctx context.Context, url string) (*http.Response, error)
func Post(ctx context.Context, url string, body io.Reader) (*http.Response, error)
...
// 证书检测
func GetCertificatesExpirestime(ctx context.Context, requestURL, method, address string, timeout time.Duration) (int, error)
关键函数
NewClient：创建 HTTP 客户端，支持 Option 配置Do/Get/Post/Head/PostForm/PostJSON：常用请求方法WithTimeout/WithProxy/WithLogSlow/WithTraceEnable/WithLogger：常用配置项GetCertificatesExpirestime：证书剩余天数检测
错误处理
- 所有请求方法均返回 error，需检查
- 超时、网络、协议等错误均有详细信息
- Option 配置错误会 panic 或返回 error
性能指标
- 单连接 QPS 万级，连接池/并发可进一步提升
- 钩子/trace/日志功能对性能影响可控
测试覆盖率
- 单元测试覆盖所有接口、边界、异常场景
- 使用 testify，覆盖率 100%
调试指南
- 检查超时、代理、连接池等参数设置
- trace/慢日志有助于定位慢请求
- 证书检测适合自动化监控
相关文档
贡献指南
欢迎提交 Issue、PR 或建议，详见 贡献指南。
许可证
本项目采用 MIT License 许可证。详见 LICENSE。
Documentation
¶
Overview ¶
Package http 提供可配置的 HTTP client、请求 Hook，以及 HTTPS 证书辅助函数。
NewClient 基于标准库 http.Client 组装超时、连接池、代理和日志/trace Hook。 当未通过 WithTransport 显式提供自定义 Transport 时，默认 Transport 会将 TLSClientConfig.InsecureSkipVerify 设为 true，也就是默认跳过 TLS 证书校验； 如需启用证书校验，调用方需要通过 WithTransport 显式调整 TLS 配置。 GetCertificates 与 GetCertificatesExpirestime 用于发起 HTTPS 请求并提取对端证书链及剩余有效期。
Index ¶
- func Do(ctx context.Context, req *http.Request) (*http.Response, error)
- func Get(ctx context.Context, url string) (*http.Response, error)
- func GetCertificates(ctx context.Context, requestURL, method, address string, timeout time.Duration) ([]*x509.Certificate, error)
- func GetCertificatesExpirestime(ctx context.Context, requestURL, method, address string, timeout time.Duration) (int, error)
- func Head(ctx context.Context, url string) (*http.Response, error)
- func NewLogErrorHook(logger kitlog.Logger) *logErrorHook
- func NewSlowHook(logger kitlog.Logger, threshold time.Duration) *slowHook
- func NewTraceHook(logger kitlog.Logger) *traceHook
- func Post(ctx context.Context, url string, body io.Reader) (*http.Response, error)
- func PostForm(ctx context.Context, url string, data url.Values) (*http.Response, error)
- func PostJSON(ctx context.Context, url string, data any) (*http.Response, error)
- type Client
- type Hook
- type HookContext
- func (h *HookContext) Deadline() (deadline time.Time, ok bool)
- func (h *HookContext) Done() <-chan struct{}
- func (h *HookContext) Duration() time.Duration
- func (h *HookContext) EndTime() time.Time
- func (h *HookContext) Err() error
- func (h *HookContext) GetHookValue(key string) (interface{}, bool)
- func (h *HookContext) Method() string
- func (h *HookContext) OriginError() error
- func (h *HookContext) OriginResult() any
- func (h *HookContext) Request() *http.Request
- func (h *HookContext) SetHookValue(key string, value interface{})
- func (h *HookContext) SetResult(response *http.Response, err error)
- func (h *HookContext) StartTime() time.Time
- func (h *HookContext) Url() string
- func (h *HookContext) Value(key interface{}) interface{}
- type HookManager
- type Option
- func WithHook(hook Hook) Option
- func WithLogError(logError bool) Option
- func WithLogSlow(logSlow time.Duration) Option
- func WithLogger(logger kitlog.Logger) Option
- func WithMaxConnsPerHost(maxConnsPerHost int) Option
- func WithMaxIdleConns(maxIdleConns int) Option
- func WithMaxIdleConnsPerHost(maxIdleConnsPerHost int) Option
- func WithName(name string) Option
- func WithProxy(proxy func(*http.Request) (*url.URL, error)) Option
- func WithTimeout(timeout time.Duration) Option
- func WithTraceEnable(enable bool) Option
- func WithTransport(transport *http.Transport) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Do ¶
Do 使用全局默认客户端执行自定义的 HTTP 请求。
ctx 用于传递给 HookContext；请求本身使用 req 已携带的上下文，Do 不会用 ctx 重写 req.Context()。
参数：
- ctx: 传递给 HookContext 的上下文。
- req: 待发送的 HTTP 请求对象。
返回：
- *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
- error: Hook Before 失败或底层 HTTP 请求失败时返回错误；Hook After 的错误会被忽略。
func Get ¶
Get 使用全局默认客户端发送 HTTP GET 请求。
参数：
- ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
- url: 请求地址。
返回：
- *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
- error: 请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
func GetCertificates ¶
func GetCertificates(ctx context.Context, requestURL, method, address string, timeout time.Duration) ([]*x509.Certificate, error)
GetCertificates 请求目标地址并提取 TLS 对端证书。
本函数使用基于 requestURL 主机名的 TLS ServerName 发起请求；主机名提取沿用 generateTLSConfig 的规则，因此 IPv6 字面量主机存在按第一个冒号截断的既有限制。 本函数保留标准库默认的证书校验策略。成功收到响应时优先从响应的 TLS 状态读取 PeerCertificates。若 TLS 握手因未知 CA 失败，会尝试从错误链中的 x509.UnknownAuthorityError 提取其中携带的证书并将该错误视为已处理； 这只用于在证书不受本地信任时尽量取回证书，不表示证书链校验成功。
参数：
- ctx: 请求上下文，用于控制请求取消和超时。
- requestURL: 目标请求地址，用于创建请求并解析 TLS ServerName。
- method: 请求使用的 HTTP 方法；为空时使用 HEAD。
- address: 可选的实际拨号地址，格式通常为 host:port；非空时只覆盖底层 Dial 目标，不改变 requestURL，也不改变基于 requestURL 生成的 SNI。
- timeout: HTTP 客户端的整体超时时间；零值表示不设置 http.Client 超时。
返回：
- []*x509.Certificate: 提取到的对端证书切片；成功建立 TLS 连接时通常为 PeerCertificates，未知 CA 场景下可能只包含从错误中提取的一张证书；非 TLS 响应或未取到证书时返回空切片。
- error: URL 解析、请求创建、网络访问、上下文取消或 TLS 握手中的未处理错误；当仅因未知 CA 失败且已成功提取证书时返回 nil。
func GetCertificatesExpirestime ¶
func GetCertificatesExpirestime(ctx context.Context, requestURL, method, address string, timeout time.Duration) (int, error)
GetCertificatesExpirestime 返回请求目标提取到的首张证书剩余有效天数。
本函数仅基于 GetCertificates 返回切片中的首张证书计算有效期， 不校验证书链完整性，也不推断中间证书或根证书的剩余有效期。 剩余天数通过 time.Until(cert.NotAfter).Hours()/24 向零截断， 已过期证书可能返回负数。
参数：
- ctx: 请求上下文，用于控制证书请求的取消和超时。
- requestURL: 目标请求地址，用于生成请求并解析 TLS ServerName。
- method: 请求使用的 HTTP 方法；为空时使用 HEAD。
- address: 可选的实际拨号地址，格式通常为 host:port；非空时只覆盖底层 Dial 目标，不改变 requestURL，也不改变基于 requestURL 生成的 SNI。
- timeout: HTTP 客户端的整体超时时间；零值表示不设置 http.Client 超时。
返回：
- int: 首张证书剩余的整天数；返回 -99 表示 GetCertificates 返回错误，返回 -98 表示请求过程未提取到任何证书。
- error: GetCertificates 返回的错误；当返回值为 -98 时通常为 nil。
func Head ¶
Head 使用全局默认客户端发送 HTTP HEAD 请求。
参数：
- ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
- url: 请求地址。
返回：
- *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
- error: 请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
func NewLogErrorHook ¶
NewLogErrorHook 创建一个在请求返回原始错误时异步记录错误日志的 Hook。
日志任务通过 runtime/goroutine 包级默认协程池提交；若协程池提交失败，错误会被忽略。
参数：
- logger: 写入错误日志时使用的日志记录器。
返回：
- *logErrorHook: 可注册到 HookManager 的错误日志 Hook。
func NewSlowHook ¶
NewSlowHook 创建一个在请求耗时超过 threshold 时异步记录慢请求日志的 Hook。
threshold 不会在构造时校验；当 threshold 小于等于 0 时，绝大多数已完成请求都会满足记录条件。 日志任务通过 runtime/goroutine 包级默认协程池提交；若协程池提交失败，错误会被忽略。
参数：
- logger: 写入慢请求日志时使用的日志记录器。
- threshold: 触发慢请求日志的耗时阈值。
返回：
- *slowHook: 可注册到 HookManager 的慢请求日志 Hook。
func NewTraceHook ¶
NewTraceHook 创建一个通过 httptrace 采集 DNS、连接、TLS 等阶段耗时并异步输出调试日志的 Hook。
该 Hook 会在 Before 中把 ClientTrace 写入请求上下文，并在 After 中通过 runtime/goroutine 包级默认协程池输出日志；若协程池提交失败，错误会被忽略。
参数：
- logger: 输出 trace 调试日志时使用的日志记录器。
返回：
- *traceHook: 可注册到 HookManager 的 trace Hook。
func Post ¶
Post 使用全局默认客户端发送 HTTP POST 请求。
参数：
- ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
- url: 请求地址。
- body: 请求体；可为 nil。
返回：
- *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
- error: 请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
func PostForm ¶
PostForm 使用全局默认客户端发送 application/x-www-form-urlencoded 表单 POST 请求。
参数：
- ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
- url: 请求地址。
- data: 表单数据，会通过 url.Values.Encode 编码到请求体。
返回：
- *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
- error: 请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
Types ¶
type Client ¶
type Client interface {
// Do 执行自定义的 HTTP 请求。
//
// ctx 用于传递给 HookContext；请求本身使用 req 已携带的上下文，Do 不会用 ctx 重写 req.Context()。
//
// 参数：
// - ctx: 传递给 HookContext 的上下文。
// - req: 待发送的 HTTP 请求对象。
//
// 返回：
// - *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
// - error: Hook Before 失败或底层 HTTP 请求失败时返回错误；Hook After 的错误会被忽略。
Do(ctx context.Context, req *http.Request) (*http.Response, error)
// Head 发送 HTTP HEAD 请求。
//
// 参数：
// - ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
// - url: 请求地址。
//
// 返回：
// - *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
// - error: 请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
Head(ctx context.Context, url string) (*http.Response, error)
// Get 发送 HTTP GET 请求。
//
// 参数：
// - ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
// - url: 请求地址。
//
// 返回：
// - *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
// - error: 请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
Get(ctx context.Context, url string) (*http.Response, error)
// Post 发送 HTTP POST 请求。
//
// 参数：
// - ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
// - url: 请求地址。
// - body: 请求体；可为 nil。
//
// 返回：
// - *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
// - error: 请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
Post(ctx context.Context, url string, body io.Reader) (*http.Response, error)
// PostForm 发送 application/x-www-form-urlencoded 表单 POST 请求。
//
// 参数：
// - ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
// - url: 请求地址。
// - data: 表单数据，会通过 url.Values.Encode 编码到请求体。
//
// 返回：
// - *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
// - error: 请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
PostForm(ctx context.Context, url string, data url.Values) (*http.Response, error)
// PostJSON 发送 application/json POST 请求。
//
// 参数：
// - ctx: 请求上下文，用于创建 HTTP 请求并控制其生命周期。
// - url: 请求地址。
// - data: 待编码为 JSON 的请求体数据。
//
// 返回：
// - *http.Response: HTTP 响应对象；非 nil 时调用方负责关闭 Body。
// - error: JSON 编码失败、请求创建失败、Hook Before 失败或底层 HTTP 请求失败时返回错误。
PostJSON(ctx context.Context, url string, data any) (*http.Response, error)
}
Client 定义支持请求 Hook、默认配置和常用 HTTP 方法的客户端接口。
返回的 *http.Response 在非 nil 时由调用方负责关闭 Body；请求错误语义与标准库 http.Client 保持一致。
func NewClient ¶
NewClient 创建一个新的 HTTP 客户端实例。
当未显式提供 Transport 时，NewClient 会构造默认 http.Transport，并将 TLSClientConfig.InsecureSkipVerify 设为 true，也就是默认跳过 TLS 证书校验； 如需启用证书校验，调用方必须通过 WithTransport 显式提供自定义 Transport 并调整 TLS 配置。 当未显式提供 Hook 时，会按 logSlow、traceEnable 和 logError 选项自动组装默认 HookManager。
参数：
- opts: 用于覆盖默认超时、连接池、Transport、Hook 和日志配置的可选项，按传入顺序应用。
返回：
- Client: 按给定选项构造的 HTTP 客户端实例。
type Hook ¶
type Hook interface {
// Before 在操作执行前调用。
//
// 参数：
// - ctx: 钩子上下文，包含请求和共享 Hook 数据。
//
// 返回：
// - error: 返回非 nil 错误时请求会被中止并向调用方返回该错误。
Before(ctx *HookContext) error
// After 在操作执行后调用。
//
// 参数：
// - ctx: 钩子上下文，包含请求、原始响应、原始错误和共享 Hook 数据。
//
// 返回：
// - error: Hook 执行失败时返回错误；当前 client.Do 会忽略该错误。
After(ctx *HookContext) error
}
Hook 定义 HTTP 请求执行前后的扩展点。
Before 在请求发送前执行，可修改 HookContext 中的请求对象或返回错误中止请求； After 在请求完成后执行，适合记录日志、指标和 trace 等观察逻辑。
type HookContext ¶
type HookContext struct {
// contains filtered or unexported fields
}
HookContext 包含一次 HTTP 请求在 Hook 链中共享的上下文信息。
HookContext 同时实现 context.Context，并把 Deadline、Done、Err 和 Value 委托给原始上下文。 Hook 可以通过 SetHookValue 和 GetHookValue 共享附加数据；请求结果需在请求完成后由 SetResult 写入。
func NewHookContext ¶
NewHookContext 创建新的 HookContext。
startTime 会在创建时记录；endTime、originResult 和 originError 需要在请求完成后通过 SetResult 写入。
参数：
- ctx: 原始上下文对象，context.Context 接口方法会委托给它。
- method: HTTP 方法，如 GET、POST 等。
- url: 请求的 URL 地址。
- request: 当前要发送的 HTTP 请求对象。
返回：
- *HookContext: 初始化完成的 Hook 上下文。
func (*HookContext) Deadline ¶
func (h *HookContext) Deadline() (deadline time.Time, ok bool)
Deadline 实现 context.Context 接口并返回原始上下文的截止时间。
参数：无。
返回：
- deadline: 原始上下文的截止时间。
- ok: 原始上下文设置了截止时间时返回 true，否则返回 false。
func (*HookContext) Done ¶
func (h *HookContext) Done() <-chan struct{}
Done 实现 context.Context 接口并返回原始上下文的取消通知通道。
参数：无。
返回：
- <-chan struct{}: 原始上下文被取消或超时时关闭的通道。
func (*HookContext) Duration ¶
func (h *HookContext) Duration() time.Duration
Duration 返回操作持续时间。
请求未调用 SetResult 时，endTime 为零值，返回值会反映零值时间与 startTime 的差值。
参数：无。
返回：
- time.Duration: endTime 与 startTime 的时间差。
func (*HookContext) EndTime ¶
func (h *HookContext) EndTime() time.Time
EndTime 返回操作结束时间。
参数：无。
返回：
- time.Time: SetResult 记录的结束时间；请求未完成前为零值。
func (*HookContext) Err ¶
func (h *HookContext) Err() error
Err 实现 context.Context 接口并返回原始上下文的取消原因。
参数：无。
返回：
- error: 原始上下文被取消或超时时返回对应错误；未取消时返回 nil。
func (*HookContext) GetHookValue ¶
func (h *HookContext) GetHookValue(key string) (interface{}, bool)
GetHookValue 获取 Hook 链共享数据。
参数：
- key: 要获取的键名。
返回：
- interface{}: 与 key 关联的值。
- bool: key 存在时返回 true，否则返回 false。
func (*HookContext) Method ¶
func (h *HookContext) Method() string
Method 返回 HTTP 方法。
参数：无。
返回：
- string: 当前 HookContext 记录的 HTTP 方法。
func (*HookContext) OriginError ¶
func (h *HookContext) OriginError() error
OriginError 返回原始 HTTP 请求错误。
参数：无。
返回：
- error: SetResult 写入的原始错误；请求成功或尚未写入结果时为 nil。
func (*HookContext) OriginResult ¶
func (h *HookContext) OriginResult() any
OriginResult 返回原始 HTTP 响应。
参数：无。
返回：
- any: SetResult 写入的 *http.Response；尚未写入结果时为 nil。
func (*HookContext) Request ¶
func (h *HookContext) Request() *http.Request
Request 返回当前 HTTP 请求对象。
Hook 可在 Before 阶段替换请求上下文，后续 Do 会使用这里返回的请求对象发送。
参数：无。
返回：
- *http.Request: 当前要发送的 HTTP 请求对象。
func (*HookContext) SetHookValue ¶
func (h *HookContext) SetHookValue(key string, value interface{})
SetHookValue 写入 Hook 链共享数据。
参数：
- key: 要设置的键名。
- value: 要存储的值。
func (*HookContext) SetResult ¶
func (h *HookContext) SetResult(response *http.Response, err error)
SetResult 记录 HTTP 请求的原始响应、错误和结束时间。
参数：
- response: HTTP 返回对象，可为 nil。
- err: HTTP 请求返回的原始错误；没有错误时为 nil。
func (*HookContext) StartTime ¶
func (h *HookContext) StartTime() time.Time
StartTime 返回操作开始时间。
参数：无。
返回：
- time.Time: 创建 HookContext 时记录的开始时间。
func (*HookContext) Url ¶
func (h *HookContext) Url() string
Url 返回请求 URL 字符串。
参数：无。
返回：
- string: 当前 HookContext 记录的请求 URL。
func (*HookContext) Value ¶
func (h *HookContext) Value(key interface{}) interface{}
Value 实现 context.Context 接口并从原始上下文读取值。
HookContext 的共享 Hook 数据不通过 Value 暴露，调用方应使用 GetHookValue 读取。
参数：
- key: 要从原始上下文读取的键。
返回：
- interface{}: 原始上下文中与 key 关联的值；不存在时返回 nil。
type HookManager ¶
type HookManager struct {
// contains filtered or unexported fields
}
HookManager 管理多个 Hook 的执行顺序。
Before 按注册顺序执行，After 按逆序执行，便于为一次请求构建成对包裹的 Hook 链。
func NewHookManager ¶
func NewHookManager() *HookManager
NewHookManager 创建新的 HookManager。
参数：无。
返回：
- *HookManager: 未注册任何 Hook 的 HookManager。
func (*HookManager) AddHook ¶
func (m *HookManager) AddHook(hook Hook)
AddHook 添加一个 Hook 到执行链尾部。
参数：
- hook: 要添加的 Hook 实现；当前实现不会过滤 nil。
func (*HookManager) After ¶
func (m *HookManager) After(ctx *HookContext) error
After 实现 Hook 接口，按注册逆序执行所有 Hook 的 After 方法。
参数：
- ctx: 钩子上下文，包含请求、原始响应、原始错误和共享 Hook 数据。
返回：
- error: 任一 Hook 的 After 返回错误时立即停止并返回该错误。
func (*HookManager) Before ¶
func (m *HookManager) Before(ctx *HookContext) error
Before 实现 Hook 接口，按注册顺序执行所有 Hook 的 Before 方法。
参数：
- ctx: 钩子上下文，包含请求和共享 Hook 数据。
返回：
- error: 任一 Hook 的 Before 返回错误时立即停止并返回该错误。
type Option ¶
type Option func(c *client)
Option 定义修改 HTTP client 配置的函数。
Option 由 NewClient 按传入顺序执行，后传入的配置可覆盖先前写入的同一字段。
参数：
- c: 待修改的 client 配置实例，由 NewClient 创建并传入。
func WithHook ¶
WithHook 设置自定义 Hook。
当该选项最终写入非 nil hook 时，NewClient 不再自动组装 logSlow、traceEnable 和 logError 对应的默认 HookManager；传入 nil 时继续按这些选项组装默认 HookManager。
参数：
- hook: 自定义的 Hook 实现；为 nil 时 NewClient 会继续组装默认 HookManager。
返回：
- Option: 应用于 NewClient 的 Hook 配置项。
func WithLogError ¶
WithLogError 控制是否为默认 HookManager 自动注入错误日志 Hook。
仅在未通过 WithHook 提供自定义 Hook 时生效。
参数：
- logError: true 表示启用默认错误日志 Hook，false 表示不注入。
返回：
- Option: 应用于 NewClient 的错误日志 Hook 开关配置项。
func WithLogSlow ¶
WithLogSlow 设置默认慢请求日志 Hook 的阈值。
仅在未通过 WithHook 提供自定义 Hook 时生效；当阈值小于等于 0 时，不会自动安装慢请求 Hook。
参数：
- logSlow: 默认慢请求日志 Hook 的阈值。
返回：
- Option: 应用于 NewClient 的慢请求日志配置项。
func WithLogger ¶
WithLogger 设置 HTTP 客户端的日志记录器。
该日志记录器只会传递给自动组装的默认慢请求、trace 和错误日志 Hook；如果通过 WithHook 提供自定义 Hook，NewClient 不会把 logger 自动注入到自定义 Hook。调用方应提供可用的 Logger。
参数：
- logger: 自定义的日志记录器实现。
返回：
- Option: 应用于 NewClient 的日志配置项。
func WithMaxConnsPerHost ¶
WithMaxConnsPerHost 设置每个主机的最大连接数。
该选项只在使用 NewClient 内置 Transport 时生效，取值语义与 http.Transport.MaxConnsPerHost 保持一致。
参数：
- maxConnsPerHost: 自定义的每主机最大连接数。
返回：
- Option: 应用于 NewClient 的连接池配置项。
func WithMaxIdleConns ¶
WithMaxIdleConns 设置所有主机的最大空闲连接数。
该选项只在使用 NewClient 内置 Transport 时生效，取值语义与 http.Transport.MaxIdleConns 保持一致。
参数：
- maxIdleConns: 自定义的全局最大空闲连接数。
返回：
- Option: 应用于 NewClient 的连接池配置项。
func WithMaxIdleConnsPerHost ¶
WithMaxIdleConnsPerHost 设置每个主机的最大空闲连接数。
该选项只在使用 NewClient 内置 Transport 时生效，取值语义与 http.Transport.MaxIdleConnsPerHost 保持一致。
参数：
- maxIdleConnsPerHost: 自定义的每主机最大空闲连接数。
返回：
- Option: 应用于 NewClient 的连接池配置项。
func WithName ¶
WithName 设置 HTTP 客户端名称。
该名称当前用于配置保存，默认 Hook 日志不会自动输出该字段。
参数：
- name: 自定义客户端名称，空字符串会按原值写入。
返回：
- Option: 应用于 NewClient 的客户端名称配置项。
func WithProxy ¶
WithProxy 设置 HTTP 客户端代理函数。
该选项只在使用 NewClient 内置 Transport 时生效；通过 WithTransport 提供自定义 Transport 后，代理行为由自定义 Transport 决定。
参数：
- proxy: 自定义代理函数，用于根据请求返回代理 URL；可为 nil，含义与 http.Transport.Proxy 一致。
返回：
- Option: 应用于 NewClient 的代理配置项。
func WithTimeout ¶
WithTimeout 设置 HTTP 客户端总超时时间。
timeout 会写入底层 http.Client.Timeout；非正值表示不设置整体超时，正值会限制包含连接、重定向和读取响应体在内的完整请求周期。
参数：
- timeout: 自定义客户端总超时时间。
返回：
- Option: 应用于 NewClient 的超时时间配置项。
func WithTraceEnable ¶
WithTraceEnable 控制是否为默认 HookManager 自动注入 traceHook。
仅在未通过 WithHook 提供自定义 Hook 时生效。
参数：
- enable: true 表示启用默认 traceHook 注入，false 表示不注入。
返回：
- Option: 应用于 NewClient 的 traceHook 开关配置项。
func WithTransport ¶
WithTransport 设置自定义的 http.Transport。
当该选项最终写入非 nil transport 时，NewClient 不再根据 proxy、TLS 和连接池默认参数构造内置 Transport；传入 nil 时继续使用默认构造逻辑。Transport 的生命周期由调用方负责。
参数：
- transport: 自定义的 HTTP 传输层配置；为 nil 时 NewClient 会继续构造内置 Transport。
返回：
- Option: 应用于 NewClient 的 Transport 配置项。
Source Files