http

package
v0.0.15 Latest Latest
Warning

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

 Go to latest Published: Nov 20, 2025 License: MIT Imports: 17 Imported by: 0

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Do 

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

Do 执行自定义的 HTTP 请求（全局默认客户端）。

参数：

  • ctx context.Context：请求上下文。
  • req *http.Request：HTTP 请求对象。

返回值：

  • *http.Response：HTTP 响应对象。
  • error：请求错误信息。

func Get 

func Get(ctx context.Context, url string) (*http.Response, error)

Get 发送 HTTP GET 请求（全局默认客户端）。

参数：

  • ctx context.Context：请求上下文。
  • url string：请求地址。

返回值：

  • *http.Response：HTTP 响应对象。
  • error：请求错误信息。

func GetCertificates 

func GetCertificates(ctx context.Context, requestURL, method, address string, timeout time.Duration) ([]*x509.Certificate, error)

GetCertificates 获取证书。

参数： - ctx context.Context 上下文对象，用于控制超时与取消。 - requestURL string 需要进行证书请求的 URL 地址。 - method string （可选）请求时使用的方式，如果为空值，则默认使用 HEAD。 - address string （可选）指定的服务器 Endpoint，包含 IP 和端口，例如：127.0.0.1:443。 - timeout time.Duration 超时时间。

返回值： - []*x509.Certificate 获取到的证书链。 - error 错误信息。

func GetCertificatesExpirestime 

func GetCertificatesExpirestime(ctx context.Context, requestURL, method, address string, timeout time.Duration) (int, error)

GetCertificatesExpirestime 获取证书剩余有效期。

参数： - ctx context.Context 上下文对象，用于控制超时与取消。 - requestURL string 需要进行证书请求的 URL 地址。 - method string （可选）请求时使用的方式，如果为空值，则默认使用 HEAD。 - address string （可选）指定的服务器 Endpoint，包含 IP 和端口，例如：127.0.0.1:443。 - timeout time.Duration 超时时间。

返回值： - int 证书剩余有效天数，-99 表示获取证书失败，-98 表示未获取到证书。 - error 错误信息。 

func Head(ctx context.Context, url string) (*http.Response, error)

Head 发送 HTTP HEAD 请求（全局默认客户端）。

参数：

  • ctx context.Context：请求上下文。
  • url string：请求地址。

返回值：

  • *http.Response：HTTP 响应对象。
  • error：请求错误信息。

func NewLogErrorHook 

func NewLogErrorHook(logger kitlog.Logger) *logErrorHook

func NewSlowHook 

func NewSlowHook(logger kitlog.Logger, threshold time.Duration) *slowHook

func NewTraceHook 

func NewTraceHook(logger kitlog.Logger) *traceHook

func Post 

func Post(ctx context.Context, url string, body io.Reader) (*http.Response, error)

Post 发送 HTTP POST 请求（全局默认客户端）。

参数：

  • ctx context.Context：请求上下文。
  • url string：请求地址。
  • body io.Reader：请求体。

返回值：

  • *http.Response：HTTP 响应对象。
  • error：请求错误信息。

func PostForm 

func PostForm(ctx context.Context, url string, data url.Values) (*http.Response, error)

PostForm 发送表单 POST 请求（全局默认客户端）。

参数：

  • ctx context.Context：请求上下文。
  • url string：请求地址。
  • data url.Values：表单数据。

返回值：

  • *http.Response：HTTP 响应对象。
  • error：请求错误信息。

func PostJSON 

func PostJSON(ctx context.Context, url string, data any) (*http.Response, error)

PostJSON 发送 JSON POST 请求（全局默认客户端）。

参数：

  • ctx context.Context：请求上下文。
  • url string：请求地址。
  • data any：JSON 数据。

返回值：

  • *http.Response：HTTP 响应对象。
  • error：请求错误信息。

Types

type Client 

type Client interface {
	// Do 执行自定义的 HTTP 请求。
	//
	// 参数：
	//   - ctx context.Context：请求上下文。
	//   - req *http.Request：HTTP 请求对象。
	// 返回值：
	//   - *http.Response：HTTP 响应对象。
	//   - error：请求错误信息。
	Do(ctx context.Context, req *http.Request) (*http.Response, error)
	// Head 发送 HTTP HEAD 请求。
	//
	// 参数：
	//   - ctx context.Context：请求上下文。
	//   - url string：请求地址。
	// 返回值：
	//   - *http.Response：HTTP 响应对象。
	//   - error：请求错误信息。
	Head(ctx context.Context, url string) (*http.Response, error)
	// Get 发送 HTTP GET 请求。
	//
	// 参数：
	//   - ctx context.Context：请求上下文。
	//   - url string：请求地址。
	// 返回值：
	//   - *http.Response：HTTP 响应对象。
	//   - error：请求错误信息。
	Get(ctx context.Context, url string) (*http.Response, error)
	// Post 发送 HTTP POST 请求。
	//
	// 参数：
	//   - ctx context.Context：请求上下文。
	//   - url string：请求地址。
	//   - body io.Reader：请求体。
	// 返回值：
	//   - *http.Response：HTTP 响应对象。
	//   - error：请求错误信息。
	Post(ctx context.Context, url string, body io.Reader) (*http.Response, error)
	// PostForm 发送表单 POST 请求。
	//
	// 参数：
	//   - ctx context.Context：请求上下文。
	//   - url string：请求地址。
	//   - data url.Values：表单数据。
	// 返回值：
	//   - *http.Response：HTTP 响应对象。
	//   - error：请求错误信息。
	PostForm(ctx context.Context, url string, data url.Values) (*http.Response, error)
	// PostJSON 发送 JSON POST 请求。
	//
	// 参数：
	//   - ctx context.Context：请求上下文。
	//   - url string：请求地址。
	//   - data any：JSON 数据。
	// 返回值：
	//   - *http.Response：HTTP 响应对象。
	//   - error：请求错误信息。
	PostJSON(ctx context.Context, url string, data any) (*http.Response, error)
}

Client 定义了 HTTP 客户端的接口。

提供常用的 HTTP 请求方法。

func NewClient 

func NewClient(opts ...Option) Client

NewClient 创建一个新的 HTTP 客户端实例。

参数：

  • opts ...Option：可选配置项。

返回值：

  • Client：HTTP 客户端实例。

type Hook 

type Hook interface {
	// Before 在操作执行前调用。
	//
	// 参数：
	//   - ctx：钩子上下文，包含操作的相关信息。
	//
	// 返回值：
	//   - error：如果钩子执行出错，返回相应的错误信息。
	Before(ctx *HookContext) error

	// After 在操作执行后调用。
	//
	// 参数：
	//   - ctx：钩子上下文，包含操作的相关信息和结果。
	//
	// 返回值：
	//   - error：如果钩子执行出错，返回相应的错误信息。
	After(ctx *HookContext) error
}

Hook 定义 HTTP 操作的钩子接口。

该接口用于在 HTTP 操作执行前后插入自定义逻辑。

type HookContext 

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

HookContext 包含 HTTP 操作的上下文信息。

该结构体用于在 HTTP 请求生命周期中传递操作相关的上下文、请求信息、执行结果、错误信息及自定义钩子数据。

func NewHookContext 

func NewHookContext(ctx context.Context, method, url string, request *http.Request) *HookContext

NewHookContext 创建一个新的 HookContext 实例。

参数：

  • ctx：原始上下文对象，用于控制操作的生命周期。
  • method：HTTP 方法，如 GET、POST 等。
  • url：请求的 URL 地址。
  • request：原始 HTTP 请求对象。

返回值：

  • *HookContext：返回一个新创建的 HookContext 实例。

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{}：返回一个 channel，当上下文被取消时会被关闭。

func (*HookContext) Duration 

func (h *HookContext) Duration() time.Duration

Duration 返回操作持续时间。

返回值：

  • time.Duration：返回操作的持续时间。

func (*HookContext) EndTime 

func (h *HookContext) EndTime() time.Time

EndTime 返回操作结束时间。

返回值：

  • time.Time：返回操作的结束时间。

func (*HookContext) Err 

func (h *HookContext) Err() error

Err 实现 context.Context 接口。

返回值：

  • error：如果上下文被取消，返回取消的原因。

func (*HookContext) GetHookValue 

func (h *HookContext) GetHookValue(key string) (interface{}, bool)

GetHookValue 获取 hook 中的值。

参数：

  • key：要获取的键名。

返回值：

  • interface{}：返回与键关联的值。
  • bool：如果键存在返回 true，否则返回 false。

func (*HookContext) Method 

func (h *HookContext) Method() string

Method 返回 HTTP 方法。

返回值：

  • string：返回 HTTP 方法字符串。

func (*HookContext) OriginError 

func (h *HookContext) OriginError() error

OriginError 返回原始操作错误。

返回值：

  • error：返回操作过程中产生的原始错误。

func (*HookContext) OriginResult 

func (h *HookContext) OriginResult() any

OriginResult 返回原始操作结果。

返回值：

  • any：返回操作的原始结果。

func (*HookContext) Request 

func (h *HookContext) Request() *http.Request

Request 返回原始 HTTP 请求对象。

返回值：

  • *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 设置操作结果和结束时间。

参数：

  • response：HTTP 返回对象。
  • err：操作过程中产生的错误，如果没有错误则为 nil。

func (*HookContext) StartTime 

func (h *HookContext) StartTime() time.Time

StartTime 返回操作开始时间。

返回值：

  • time.Time：返回操作的开始时间。

func (*HookContext) Url 

func (h *HookContext) Url() string

Url 返回请求的 URL。

返回值：

  • string：返回请求的 URL 字符串。

func (*HookContext) Value 

func (h *HookContext) Value(key interface{}) interface{}

Value 实现 context.Context 接口。

参数：

  • key：要获取的值的键。

返回值：

  • interface{}：返回与键关联的值。

type HookManager 

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

HookManager 管理多个 Hook 的执行。

该结构体用于统一管理和调度多个钩子的执行顺序。

func NewHookManager 

func NewHookManager() *HookManager

NewHookManager 创建一个新的 HookManager 实例。

返回值：

  • *HookManager：返回一个新创建的 HookManager 实例。

func (*HookManager) AddHook 

func (m *HookManager) AddHook(hook Hook)

AddHook 添加一个 Hook。

参数：

  • hook：要添加的钩子实例。

func (*HookManager) After 

func (m *HookManager) After(ctx *HookContext) error

After 实现 Hook 接口，按逆序执行所有 Hook 的 After 方法。

参数：

  • ctx：钩子上下文，包含操作的相关信息和结果。

返回值：

  • error：如果任何钩子执行出错，返回第一个错误信息。

func (*HookManager) Before 

func (m *HookManager) Before(ctx *HookContext) error

Before 实现 Hook 接口，按顺序执行所有 Hook 的 Before 方法。

参数：

  • ctx：钩子上下文，包含操作的相关信息。

返回值：

  • error：如果任何钩子执行出错，返回第一个错误信息。

type Option 

type Option func(c *client)

Option 定义用于配置 client 的函数类型。

通过 Option，可以灵活地设置 client 的各项参数。

func WithHook 

func WithHook(hook Hook) Option

WithHook 设置 HTTP 客户端的钩子函数。

参数：

  • hook Hook：自定义的 Hook 实现。

返回值：

  • Option：用于设置钩子的配置项。

func WithLogError 

func WithLogError(logError bool) Option

WithLogError 设置 HTTP 客户端的错误记录功能开关。

参数：

  • logError bool：是否启用错误记录功能。

返回值：

  • Option：用于设置错误记录功能的配置项。

func WithLogSlow 

func WithLogSlow(logSlow time.Duration) Option

WithLogSlow 设置 HTTP 客户端的慢请求阈值。

参数：

  • logSlow time.Duration：自定义的慢请求阈值。

返回值：

  • Option：用于设置慢请求阈值的配置项。

func WithLogger 

func WithLogger(logger kitlog.Logger) Option

WithLogger 设置 HTTP 客户端的日志记录器。

参数：

  • logger kitlog.Logger：自定义的日志记录器实现。

返回值：

  • Option：用于设置日志记录器的配置项。

func WithMaxConnsPerHost 

func WithMaxConnsPerHost(maxConnsPerHost int) Option

WithMaxConnsPerHost 设置每个主机的最大连接数。

参数：

  • maxConnsPerHost int：自定义的最大连接数。

返回值：

  • Option：用于设置最大连接数的配置项。

func WithMaxIdleConns 

func WithMaxIdleConns(maxIdleConns int) Option

WithMaxIdleConns 设置所有主机的最大空闲连接数。

参数：

  • maxIdleConns int：自定义的最大空闲连接数。

返回值：

  • Option：用于设置最大空闲连接数的配置项。

func WithMaxIdleConnsPerHost 

func WithMaxIdleConnsPerHost(maxIdleConnsPerHost int) Option

WithMaxIdleConnsPerHost 设置每个主机的最大空闲连接数。

参数：

  • maxIdleConnsPerHost int：自定义的最大空闲连接数。

返回值：

  • Option：用于设置最大空闲连接数的配置项。

func WithName 

func WithName(name string) Option

WithName 设置 HTTP 客户端名称。

参数：

  • name string：自定义客户端名称。

返回值：

  • Option：用于设置客户端名称的配置项。

func WithProxy 

func WithProxy(proxy func(*http.Request) (*url.URL, error)) Option

WithProxy 设置 HTTP 客户端代理。

参数：

  • proxy func(*http.Request) (*url.URL, error)：自定义代理函数，用于根据请求返回代理 URL。

返回值：

  • Option：用于设置代理的配置项。

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout 设置 HTTP 客户端超时时间。

参数：

  • timeout time.Duration：自定义超时时间。

返回值：

  • Option：用于设置超时时间的配置项。

func WithTraceEnable 

func WithTraceEnable(enable bool) Option

func WithTransport 

func WithTransport(transport *http.Transport) Option

WithTransport 设置自定义的 http.Transport。

参数：

  • transport *http.Transport：自定义的传输层配置。

返回值：

  • Option：用于设置传输层的配置项。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.