httpclient

HTTP Client

github.com/ClownSketch/httpclient 是一套基于 Go net/http 构建的出站 HTTP 客户端库，面向长期运行的服务、上游 Provider、内部 API 调用和公共 SDK。

它负责把连接池、请求构建、响应读取、重试、错误分类和可观测扩展组织成稳定的公共 API，不负责业务签名、服务发现、熔断、限流或日志存储。

主要能力

• 可长期复用、并发安全的 Client
• 链式 Request builder 和便捷请求方法
• JSON、XML、表单、文本、字节和 io.Reader 请求体
• JSON/XML 自动响应解码
• 固定请求数据重试、指数退避、抖动和 Retry-After
• 请求级 Before / After 生命周期回调
• 客户端级和请求级 Interceptor
• 与具体链路库解耦的 Trace 接口
• Cookie Jar、Basic Auth、Bearer Token、代理和 TLS
• 请求/响应体大小限制和统一错误分类
• 请求级 Mock
• 配置化 factory 子包

设计边界

这个库刻意不内置以下能力：

• 不生成或刷新签名、时间戳、Nonce
• 不判断请求是否具备业务幂等性
• 不提供服务发现、负载均衡、熔断和限流
• 不绑定任何日志或 Trace 实现
• 不提供 HTTP Server
• 不提供流式上传或流式响应；请求和响应体会进入内存

这些边界让核心客户端保持通用，也避免把宿主业务规则固化进基础库。

环境要求

• Go 1.23.8 或更高版本
• 核心库没有第三方运行时依赖

安装

go get github.com/ClownSketch/httpclient

快速开始

package main

import (
	"context"
	"log"
	"time"

	clienthttp "github.com/ClownSketch/httpclient"
)

func main() {
	client := clienthttp.New(
		clienthttp.WithDefaultTimeout(5*time.Second),
		clienthttp.WithDefaultHeader("X-Service", "resource-service"),
	)
	defer client.Close()

	resp, err := client.Get(context.Background(), "https://example.com/health")
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("status=%d body=%s", resp.StatusCode, resp.Text())
}

Client 应在应用启动时创建并长期复用，不应为每个请求重复创建。

JSON 请求与响应

type CreateResourceRequest struct {
	TenantID string `json:"tenant_id"`
	Name     string `json:"name"`
}

type CreateResourceResponse struct {
	ResourceID string `json:"resource_id"`
	Status     string `json:"status"`
}

resp, err := client.Post(
	ctx,
	"https://api.example.com/resources",
	clienthttp.Header("X-Request-ID", "request-10001"),
	clienthttp.JSONBody(CreateResourceRequest{
		TenantID: "TENANT001",
		Name:     "document",
	}),
)
if err != nil {
	return err
}

var result CreateResourceResponse
if err := resp.Decode(&result); err != nil {
	return err
}

Decode 根据响应 Content-Type 选择 JSON 或 XML；JSON 始终按 JSON 解码。

Builder

复杂请求可以使用链式 builder：

resp, err := client.R().
	Method(http.MethodPost).
	URL("https://api.example.com/resources").
	Header("X-Request-ID", "request-10001").
	Query("expand", "owner").
	Bearer(token).
	JSON(payload).
	Timeout(3 * time.Second).
	Do(ctx)

每次调用 Client.R() 都会创建独立的请求构建器。Request 不允许多个 goroutine 同时修改或执行。

重试语义

默认 MaxAttempts=1，所有 HTTP Method 都只执行一次。

client := clienthttp.New(
	clienthttp.WithRetryPolicy(clienthttp.RetryPolicy{
		MaxAttempts: 3,
		BaseDelay:   100 * time.Millisecond,
		MaxDelay:    2 * time.Second,
	}),
)

配置重试后，库会使用相同的 Method、URL、Header、Query 和 Body 重新构建网络请求。它不会更新业务签名、时间戳或 Nonce。

对具有副作用的写操作启用重试前，调用方必须确认上游接口支持幂等，并提供稳定的业务幂等键。

默认策略会考虑：

• 429 Too Many Requests
• 503 Service Unavailable 的 Retry-After
• 除 501 Not Implemented 外的 5xx
• 明确可识别的临时网络错误

上下文取消和超时不会继续重试。

请求生命周期

Before 在请求进入拦截器链前执行一次，After 在一次逻辑请求最终结束后执行一次：

resp, err := client.Post(
	ctx,
	url,
	clienthttp.JSONBody(payload),
	clienthttp.Before(func(ctx context.Context, event *clienthttp.BeforeEvent) error {
		return validateRequest(event.Request)
	}),
	clienthttp.After(func(ctx context.Context, event *clienthttp.AfterEvent) {
		if event.Failed() {
			notifyFailure(ctx, event)
		}
	}),
)

生命周期事件包含独立快照，回调修改快照不会改变真实请求或返回给调用方的响应。回调由当前 goroutine 同步执行；异步通知应由调用方自行投递。

Interceptor

func requestIDInterceptor(next clienthttp.Handler) clienthttp.Handler {
	return func(ctx context.Context, req *clienthttp.Request) (*clienthttp.Response, error) {
		req.Header("X-Request-ID", newRequestID())
		return next(ctx, req)
	}
}

client := clienthttp.New(
	clienthttp.WithInterceptor(requestIDInterceptor),
)

客户端级拦截器按注册顺序进入、按相反顺序退出。请求级拦截器通过 Request.Use 添加。

请求级拦截器包裹客户端级拦截器。使用 WithRoundTripper 后，自定义传输器完整接管 TLS、代理和连接池行为。

Trace 集成

核心包只定义 Tracer、Span 和 TracePropagator 接口，不直接依赖任何 Trace 库：

client := clienthttp.New(
	clienthttp.WithTrace(clienthttp.TraceConfig{
		Tracer:     tracerAdapter,
		Mode:       clienthttp.TraceModeAuto,
		Propagator: propagatorAdapter,
	}),
)

TraceModeAuto 会优先复用父 Span，没有父 Span 时创建 Client Span。库本身不执行脱敏；需要脱敏时由主项目提供 DataSanitizer。

Transport 配置

WithTransportConfig 是整体替换语义。只修改部分字段时，应从默认配置开始：

transport := clienthttp.DefaultTransportConfig()
transport.MaxIdleConns = 512
transport.MaxIdleConnsPerHost = 128
transport.MaxConnsPerHost = 128

client := clienthttp.New(
	clienthttp.WithTransportConfig(transport),
)

默认限制：

• 请求体最大 1 MiB
• 响应体最大 10 MiB
• HTTP 调用超时 30s
• 最大重定向次数 10

配置值 0 的具体含义以 TransportConfig 字段注释为准。

Factory

需要统一加载超时、重试、认证、TLS 和 Trace 时，可使用 factory：

client := factory.Must(factory.Config{
	Timeout: 5 * time.Second,
	DefaultHeaders: map[string]string{
		"X-Service": "resource-service",
	},
	RetryPolicy: clienthttp.RetryPolicy{
		MaxAttempts: 2,
		BaseDelay:   100 * time.Millisecond,
	},
})

文档

• 完整 API 使用手册
• 架构与文件职责
• 性能与并发安全
• 参与开发
• 版本记录
• MIT License
• 可运行完整示例

验证

go test ./...
go test -race ./...
go vet ./...
go test -run '^$' -bench . -benchmem

当前核心包测试覆盖率约为 78.7%，Factory 包约为 55.1%。